Clarify MIME::Type stringification documentation

Fixes #80.

Worked out the wording with @kenips.

History.rdoc

@@ -1,7 +1,9 @@
 == NEXT / YYYY-MM-DD
 
 * Documentation:
-  * Tibor Szolár fixed a typo in the README.
+  * Tibor Szolár (@flexik) fixed a typo in the README.
+  * Fixed #80, clarifying the relationship of MIME::Type#content_type and
+    MIME::Type#simplified, with Ken Ip (@kenips).
 
 == 2.4.3 / 2014-10-21
 

README.rdoc

@@ -24,28 +24,7 @@ add additional type definitions (see Contributing.rdoc). The primary sources
 for MIME type definitions found in mime-types is the IANA collection of
 registrations (see below for the link), RFCs, and W3C recommendations.
 
-This is release 2.4.3, restoring full compatibility with Ruby 1.9.2 (which will
-be dropped in mime-types 3.0). It also includes the performance improvements
-from mime-types 2.4.2 (since yanked because of the broken Ruby 1.9.2 support)
-and the 2.4.1 fix of a bug in observed use of the mime-types library where
-extensions were not previously sorted, such that
-
-    MIME::Types.of('image.jpg').first.extensions.first
-
-returned a value of +jpeg+ in mime-types 1, but +jpe+ in mime-types 2. This was
-introduced because extensions were sorted during assignment
-(MIME::Type#extensions=). This behaviour has been reverted to protect clients
-that work as noted above. The preferred way to express this is the new method:
-
-    MIME::Types.of('image.jpg').first.preferred_extension
-
-Łukasz Śliwa created the
-{friendly_mime}[https://github.com/lukaszsliwa/friendly_mime] gem, which offers
-friendly descriptive names for MIME types. This functionality and
-English-language data has been added to mime-types as MIME::Type#friendly. To
-make it easy for internationalization, MIME::Type#i18n_key has been added,
-which will return a key suitable for use with the
-{I18n}[https://github.com/svenfuchs/i18n] library.
+This is release 2.5, …
 
 As a reminder, mime-types 2.x is no longer compatible with Ruby 1.8 and
 mime-types 1.x is only being maintained for security issues. No new MIME types
@@ -71,6 +50,7 @@ files). A MIME::Type stores the known information about one MIME type.
     puts text.sub_type              # => 'plain'
 
     puts text.extensions.join(" ")  # => 'txt asc c cc h hh cpp hpp dat hlp'
+    puts text.preferred_extension   # => 'txt'
     puts text.friendly              # => 'Text Document'
     puts text.i18n_key              # => 'text.plain'
 
@@ -90,6 +70,17 @@ files). A MIME::Type stores the known information about one MIME type.
     puts MIME::Types.all?(&:registered?)
                                     # => false
 
+    # Various string representations of MIME types
+
+    qcelp = MIME::Types['audio/QCELP'].first # => audio/QCELP
+    puts qcelp.content_type         # => 'audio/QCELP'
+    puts qcelp.simplified           # => 'audio/qcelp'
+
+    xwingz = MIME::Types['application/x-Wingz'].first # => application/x-Wingz
+    puts xwingz.content_type        # => 'application/x-Wingz'
+    puts xwingz.simplified          # => 'application/wingz'
+
+
 == mime-types Modified Semantic Versioning
 
 The mime-types library has one version number, but this single version number

lib/mime/type.rb

@@ -192,9 +192,22 @@ def eql?(other)
 
   # Returns the whole MIME content-type string.
   #
+  # The content type is a presentation value from the MIME type registry and
+  # should not be used for comparison. The case of the content type is
+  # preserved, and extension markers (<tt>x-</tt>) are kept.
+  #
   #   text/plain        => text/plain
   #   x-chemical/x-pdb  => x-chemical/x-pdb
+  #   audio/QCELP       => audio/QCELP
   attr_reader :content_type
+  # A simplified form of the MIME content-type string, suitable for
+  # case-insensitive comparison, with any extension markers (<tt>x-</tt)
+  # removed and converted to lowercase.
+  #
+  #   text/plain        => text/plain
+  #   x-chemical/x-pdb  => chemical/pdb
+  #   audio/QCELP       => audio/qcelp
+  attr_reader :simplified
   # Returns the media type of the simplified MIME::Type.
   #
   #   text/plain        => text
@@ -215,15 +228,6 @@ def eql?(other)
   #   text/plain        => plain
   #   x-chemical/x-pdb  => x-pdb
   attr_reader :raw_sub_type
-  # The MIME types main- and sub-label can both start with <tt>x-</tt>,
-  # which indicates that it is a non-registered name. Of course, after
-  # registration this flag can disappear, adds to the confusing
-  # proliferation of MIME types. The simplified string has the <tt>x-</tt>
-  # removed and are translated to lowercase.
-  #
-  #   text/plain        => text/plain
-  #   x-chemical/x-pdb  => chemical/pdb
-  attr_reader :simplified
 
   # The list of extensions which are known to be used for this MIME::Type.
   # Non-array values will be coerced into an array with #to_a. Array values
@@ -511,15 +515,15 @@ def complete?
 
   # Returns the MIME::Type as a string.
   def to_s
-    @content_type
+    content_type
   end
 
   # Returns the MIME::Type as a string for implicit conversions. This allows
   # MIME::Type objects to appear on either side of a comparison.
   #
   #   'text/plain' == MIME::Type.new('text/plain')
   def to_str
-    @content_type
+    content_type
   end
 
   # Returns the MIME::Type as an array suitable for use with

type-lists/application.yaml

@@ -17763,6 +17763,7 @@
   encoding: base64
   extensions:
   - wz
+  - wkz
   registered: false
 - !ruby/object:MIME::Type
   content-type: application/x-word