[DOC] Addition to encoding.rdoc (#5617)

Adds section "Transcoding a Stream," listing relevant methods in IO.
    Moves an example from section "String Encoding Example" to the new section.
    Removes header "String Encoding Example" for now-empty section.
    Changes items in section "Transcoding a String" from labeled list items to bullet list items. (Labeled list items are sometimes rendered with strange indentations for continued lines, and are always rendered with different indentations for the items.)

doc/encoding.rdoc

@@ -274,29 +274,6 @@ For an \IO, \File, \ARGF, or \StringIO object, the internal encoding may be set
 
 - \Method +set_encoding+.
 
-==== Stream \Encoding Example
-
-This example writes a string to a file, encoding it as ISO-8859-1,
-then reads the file into a new string, encoding it as UTF-8:
-
-  s = "R\u00E9sum\u00E9"
-  path = 't.tmp'
-  ext_enc = 'ISO-8859-1'
-  int_enc = 'UTF-8'
-
-  File.write(path, s, external_encoding: ext_enc)
-  raw_text = File.binread(path)
-
-  transcoded_text = File.read(path, external_encoding: ext_enc, internal_encoding: int_enc)
-
-  p raw_text
-  p transcoded_text
-
-Output:
-
-  "R\xE9sum\xE9"
-  "Résumé"
-
 === Script \Encoding
 
 A Ruby script has a script encoding, which may be retrieved by:
@@ -327,24 +304,51 @@ may be specified by @Encoding+Options.
 
 Each of these methods transcodes a string:
 
-String#encode :: Transcodes a string into a new string
+- String#encode: Transcodes +self+ into a new string
-                 according to a given destination encoding,
+  according to given encodings and options.
-                 a given or default source encoding, and encoding options.
+- String#encode!: Like String#encode, but transcodes +self+ in place.
+- String#scrub: Transcodes +self+ into a new string
+  by replacing invalid byte sequences with a given or default replacement string.
+- String#scrub!: Like String#scrub, but transcodes +self+ in place.
+- String#unicode_normalize: Transcodes +self+ into a new string
+  according to Unicode normalization.
+- String#unicode_normalize!: Like String#unicode_normalize,
+  but transcodes +self+ in place.
 
-String#encode! :: Like String#encode,
+=== Transcoding a Stream
-                  but transcodes the string in place.
 
-String#scrub :: Transcodes a string into a new string
+Each of these methods may transcode a stream;
-                by replacing invalid byte sequences
+whether it does so depends on the external and internal encodings:
-                with a given or default replacement string.
 
-String#scrub! :: Like String#scrub, but transcodes the string in place.
+- IO.foreach: Yields each line of given stream to the block.
+- IO.new: Creates and returns a new \IO object for the given integer file descriptor.
+- IO.open: Creates a new \IO object.
+- IO.pipe: Creates a connected pair of reader and writer \IO objects.
+- IO.popen: Creates an \IO object to interact with a subprocess.
+- IO.read: Returns a string with all or a subset of bytes from the given stream.
+- IO.readlines: Returns an array of strings, which are the lines from the given stream.
+- IO.write: Writes a given string to the given stream.
 
-String#unicode_normalize :: Transcodes a string into a new string
+This example writes a string to a file, encoding it as ISO-8859-1,
-                            according to Unicode normalization:
+then reads the file into a new string, encoding it as UTF-8:
 
-String#unicode_normalize! :: Like String#unicode_normalize,
+  s = "R\u00E9sum\u00E9"
-                             but transcodes the string in place.
+  path = 't.tmp'
+  ext_enc = 'ISO-8859-1'
+  int_enc = 'UTF-8'
+
+  File.write(path, s, external_encoding: ext_enc)
+  raw_text = File.binread(path)
+
+  transcoded_text = File.read(path, external_encoding: ext_enc, internal_encoding: int_enc)
+
+  p raw_text
+  p transcoded_text
+
+Output:
+
+  "R\xE9sum\xE9"
+  "Résumé"
 
 === \Encoding Options