[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.)

1 files changed, 40 insertions, 36 deletions

diff --git a/doc/encoding.rdoc b/doc/encoding.rdoc
index e09cfee898..acb0e3aa47 100644
--- a/doc/encoding.rdoc
+++ b/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
-                 according to a given destination encoding,
-                 a given or default source encoding, and encoding options.
+- String#encode: Transcodes +self+ into a new string
+  according to given encodings and 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.
+
+=== Transcoding a Stream
+
+Each of these methods may transcode a stream;
+whether it does so depends on the external and internal encodings:
+
+- 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#encode! :: Like String#encode,
-                  but transcodes the string in place.
+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:
 
-String#scrub :: Transcodes a string into a new string
-                by replacing invalid byte sequences
-                with a given or default replacement string.
+  s = "R\u00E9sum\u00E9"
+  path = 't.tmp'
+  ext_enc = 'ISO-8859-1'
+  int_enc = 'UTF-8'
 
-String#scrub! :: Like String#scrub, but transcodes the string in place.
+  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)
 
-String#unicode_normalize :: Transcodes a string into a new string
-                            according to Unicode normalization:
+  p raw_text
+  p transcoded_text
 
-String#unicode_normalize! :: Like String#unicode_normalize,
-                             but transcodes the string in place.
+Output:
+
+  "R\xE9sum\xE9"
+  "Résumé"
 
 === \Encoding Options