[DOC] Revert previous merge (#6624)

Revert previous merge

1 files changed, 188 insertions, 260 deletions

diff --git a/doc/io_streams.rdoc b/doc/io_streams.rdoc
index 680d5e99c4..3ee8592687 100644
--- a/doc/io_streams.rdoc
+++ b/doc/io_streams.rdoc
@@ -87,31 +87,28 @@ Many examples here use these variables:
 
 === Basic \IO
 
-==== Reading and Writing
+You can perform basic stream \IO with these methods:
 
-===== \Method <tt>#read</tt>
+- IO#read: Returns all remaining or the next _n_ bytes read from the stream,
+  for a given _n_:
 
-Returns all remaining or the next +n+ bytes read from the stream, for a given +n+:
-
-  f = File.new('t.txt')
-  f.read     # => "First line\nSecond line\n\nFourth line\nFifth line\n"
-  f.rewind
-  f.read(30) # => "First line\r\nSecond line\r\n\r\nFou"
-  f.read(30) # => "rth line\r\nFifth line\r\n"
-  f.read(30) # => nil
-  f.close
-
-===== \Method <tt>#write</tt>
+    f = File.new('t.txt')
+    f.read     # => "First line\nSecond line\n\nFourth line\nFifth line\n"
+    f.rewind
+    f.read(30) # => "First line\r\nSecond line\r\n\r\nFou"
+    f.read(30) # => "rth line\r\nFifth line\r\n"
+    f.read(30) # => nil
+    f.close
 
-Writes one or more given strings to the stream:
+- IO#write: Writes one or more given strings to the stream:
 
-  $stdout.write('Hello', ', ', 'World!', "\n") # => 14
-  $stdout.write('foo', :bar, 2, "\n")
+    $stdout.write('Hello', ', ', 'World!', "\n") # => 14
+    $stdout.write('foo', :bar, 2, "\n")
 
-Output:
+  Output:
 
-  Hello, World!
-  foobar2
+    Hello, World!
+    foobar2
 
 ==== Position
 
@@ -120,112 +117,92 @@ which is the byte offset at which the next read or write is to occur.
 A new stream has position zero (and line number zero);
 method +rewind+ resets the position (and line number) to zero.
 
-===== \Method <tt>#tell</tt>
-
-Returns the current position (in bytes) in the stream:
-
-  f = File.new('t.txt')
-  f.tell # => 0
-  f.gets # => "First line\n"
-  f.tell # => 12
-  f.close
-
-Aliased as <tt>pos</tt>.
-
-===== \Method <tt>#pos=</tt>
-
-Sets the position of the stream (in bytes):
-
-  f = File.new('t.txt')
-  f.tell     # => 0
-  f.pos = 20 # => 20
-  f.tell     # => 20
-  f.close
-
-===== \Method <tt>#seek</tt>
-
-Sets the position of the stream to a given integer +offset+
-(in bytes), with respect to a given constant +whence+, which is one of:
+The relevant methods:
 
-- +:CUR+ or <tt>IO::SEEK_CUR</tt>:
-  Repositions the stream to its current position plus the given +offset+:
+- IO#tell (aliased as +#pos+):
+  Returns the current position (in bytes) in the stream:
 
     f = File.new('t.txt')
-    f.tell            # => 0
-    f.seek(20, :CUR)  # => 0
-    f.tell            # => 20
-    f.seek(-10, :CUR) # => 0
-    f.tell            # => 10
+    f.tell # => 0
+    f.gets # => "First line\n"
+    f.tell # => 12
     f.close
 
-- +:END+ or <tt>IO::SEEK_END</tt>:
-  Repositions the stream to its end plus the given +offset+:
+- IO#pos=: Sets the position of the stream (in bytes):
 
     f = File.new('t.txt')
-    f.tell            # => 0
-    f.seek(0, :END)   # => 0  # Repositions to stream end.
-    f.tell            # => 52
-    f.seek(-20, :END) # => 0
-    f.tell            # => 32
-    f.seek(-40, :END) # => 0
-    f.tell            # => 12
+    f.tell     # => 0
+    f.pos = 20 # => 20
+    f.tell     # => 20
     f.close
 
-- +:SET+ or <tt>IO:SEEK_SET</tt>:
-  Repositions the stream to the given +offset+:
+- IO#seek: Sets the position of the stream to a given integer +offset+
+  (in bytes), with respect to a given constant +whence+, which is one of:
+
+  - +:CUR+ or <tt>IO::SEEK_CUR</tt>:
+    Repositions the stream to its current position plus the given +offset+:
+
+      f = File.new('t.txt')
+      f.tell            # => 0
+      f.seek(20, :CUR)  # => 0
+      f.tell            # => 20
+      f.seek(-10, :CUR) # => 0
+      f.tell            # => 10
+      f.close
+
+  - +:END+ or <tt>IO::SEEK_END</tt>:
+    Repositions the stream to its end plus the given +offset+:
+
+      f = File.new('t.txt')
+      f.tell            # => 0
+      f.seek(0, :END)   # => 0  # Repositions to stream end.
+      f.tell            # => 52
+      f.seek(-20, :END) # => 0
+      f.tell            # => 32
+      f.seek(-40, :END) # => 0
+      f.tell            # => 12
+      f.close
+
+  - +:SET+ or <tt>IO:SEEK_SET</tt>:
+    Repositions the stream to the given +offset+:
+
+      f = File.new('t.txt')
+      f.tell            # => 0
+      f.seek(20, :SET) # => 0
+      f.tell           # => 20
+      f.seek(40, :SET) # => 0
+      f.tell           # => 40
+      f.close
+
+- IO#rewind: Positions the stream to the beginning (also resetting the line number):
 
     f = File.new('t.txt')
-    f.tell            # => 0
-    f.seek(20, :SET) # => 0
-    f.tell           # => 20
-    f.seek(40, :SET) # => 0
-    f.tell           # => 40
+    f.tell     # => 0
+    f.gets     # => "First line\n"
+    f.tell     # => 12
+    f.rewind   # => 0
+    f.tell     # => 0
+    f.lineno   # => 0
     f.close
 
-===== \Method <tt>#rewind</tt>
-
-Positions the stream to the beginning (also resetting the line number):
-
-  f = File.new('t.txt')
-  f.tell     # => 0
-  f.gets     # => "First line\n"
-  f.tell     # => 12
-  f.rewind   # => 0
-  f.tell     # => 0
-  f.lineno   # => 0
-  f.close
-
 ==== Open and Closed Streams
 
 A new \IO stream may be open for reading, open for writing, or both.
 
-===== \Method <tt>#close</tt>
-
-Closes the stream for both reading and writing.
-
-===== \Method <tt>#close_read</tt>
-
-Closes the stream for reading,
-
-Not in ARGF.
+You can close a stream using these methods:
 
-===== \Method <tt>#close_write</tt>
+- IO#close: Closes the stream for both reading and writing.
+- IO#close_read (not in \ARGF): Closes the stream for reading.
+- IO#close_write (not in \ARGF): Closes the stream for writing.
 
-Closes the stream for writing
+You can query whether a stream is closed using this method:
 
-Not in ARGF.
-
-===== \Method <tt>#closed?</tt>
-
-Returns whether the stream is closed.
+- IO#closed?: Returns whether the stream is closed.
 
 ==== End-of-Stream
 
-===== \Method <tt>#eof?</tt>
-
-Returns whether a stream is positioned at its end; aliased as +#eof+.
-
-===== Repositioning to End-of-Stream
+You can query whether a stream is positioned at its end using
+method IO#eof? (also aliased as +#eof+).
 
 You can reposition to end-of-stream by reading all stream content:
 
@@ -243,65 +220,52 @@ Or by using method IO#seek:
 
 === Line \IO
 
-You can process an \IO stream line-by-line.
-
-===== \Method <tt>#each_line</tt>
-
-Passes each line to the block:
-
-  f = File.new('t.txt')
-  f.each_line {|line| p line }
-
-Output:
-
-  "First line\n"
-  "Second line\n"
-  "\n"
-  "Fourth line\n"
-  "Fifth line\n"
-
-The reading may begin mid-line:
-
-  f = File.new('t.txt')
-  f.pos = 27
-  f.each_line {|line| p line }
+You can read an \IO stream line-by-line using these methods:
 
-Output:
+- IO#each_line: Passes each line to the block:
 
-  "rth line\n"
-  "Fifth line\n"
+    f = File.new('t.txt')
+    f.each_line {|line| p line }
 
-===== \Method <tt>#gets</tt>
+  Output:
 
-Returns the next line (which may begin mid-line); also in Kernel:
+    "First line\n"
+    "Second line\n"
+    "\n"
+    "Fourth line\n"
+    "Fifth line\n"
 
-  f = File.new('t.txt')
-  f.gets      # => "First line\n"
-  f.gets      # => "Second line\n"
-  f.pos = 27
-  f.gets      # => "rth line\n"
-  f.readlines # => ["Fifth line\n"]
-  f.gets      # => nil
+  The reading may begin mid-line:
 
-===== \Method <tt>#readline</tt>
+    f = File.new('t.txt')
+    f.pos = 27
+    f.each_line {|line| p line }
 
-Like #gets, but raises an exception at end-of-stream.
+  Output:
 
-Also in Kernel; not in StringIO.
+    "rth line\n"
+    "Fifth line\n"
 
-===== \Method <tt>#readlines</tt>
+- IO#gets (also in Kernel): Returns the next line (which may begin mid-line):
 
-Returns all remaining lines in an array;
-may begin mid-line:
+    f = File.new('t.txt')
+    f.gets      # => "First line\n"
+    f.gets      # => "Second line\n"
+    f.pos = 27
+    f.gets      # => "rth line\n"
+    f.readlines # => ["Fifth line\n"]
+    f.gets      # => nil
 
-  f = File.new('t.txt')
-  f.pos = 19
-  f.readlines # => ["ine\n", "\n", "Fourth line\n", "Fifth line\n"]
-  f.readlines # => []
+- IO#readline (also in Kernel; not in StringIO):
+  Like #gets, but raises an exception at end-of-stream.
 
-Also in Kernel.
+- IO#readlines (also in Kernel): Returns all remaining lines in an array;
+  may begin mid-line:
 
-===== Optional Reader Arguments
+    f = File.new('t.txt')
+    f.pos = 19
+    f.readlines # => ["ine\n", "\n", "Fourth line\n", "Fifth line\n"]
+    f.readlines # => []
 
 Each of these reader methods may be called with:
 
@@ -309,16 +273,14 @@ Each of these reader methods may be called with:
 - An optional line-size limit, +limit+.
 - Both +sep+ and +limit+.
 
-===== \Method <tt>#puts</tt>
-
-Writes objects to the stream:
+You can write to an \IO stream line-by-line using this method:
 
-  f = File.new('t.tmp', 'w')
-  f.puts('foo', :bar, 1, 2.0, Complex(3, 0))
-  f.flush
-  File.read('t.tmp') # => "foo\nbar\n1\n2.0\n3+0i\n"
+- IO#puts (also in Kernel; not in \StringIO): Writes objects to the stream:
 
-Also in Kernel; not in StringIO.
+    f = File.new('t.tmp', 'w')
+    f.puts('foo', :bar, 1, 2.0, Complex(3, 0))
+    f.flush
+    File.read('t.tmp') # => "foo\nbar\n1\n2.0\n3+0i\n"
 
 ==== Line Separator
 
@@ -406,21 +368,13 @@ which is the non-negative integer line number
 in the stream where the next read will occur.
 
 The line number is the number of lines read by certain line-oriented methods
-({::foreach}[rdoc-ref:IO.foreach],
-{#each_line}[rdoc-ref:io_streams.rdoc@Method+-23each_line],
-{#gets}[rdoc-ref:io_streams.rdoc@Method+-23gets],
-{#readline}[rdoc-ref:io_streams.rdoc@Method+-23readline],
-{#readlines}[rdoc-ref:io_streams.rdoc@Method+-23readlines])
+(IO.foreach, IO#each_line, IO#gets, IO#readline, and IO#readlines)
 according to the given (or default) line separator +sep+.
 
 A new stream is initially has line number zero (and position zero);
 method +rewind+ resets the line number (and position) to zero.
 
-===== \Method <tt>#lineno</tt>
-
-Returns the line number.
-
-===== Changes to the Line Number
+\Method IO#lineno returns the line number.
 
 Reading lines from a stream usually changes its line number:
 
@@ -460,128 +414,102 @@ that determine how lines in a stream are to be treated:
 
 === Character \IO
 
-You can process an \IO stream character-by-character.
+You can process an \IO stream character-by-character using these methods:
 
-===== \Method <tt>#getc</tt>
+- IO#getc: Reads and returns the next character from the stream:
 
-Reads and returns the next character from the stream:
+    f = File.new('t.rus')
+    f.getc # => "т"
+    f.getc # => "е"
+    f.getc # => "с"
+    f.getc # => "т"
+    f.getc # => nil
 
-  f = File.new('t.rus')
-  f.getc # => "т"
-  f.getc # => "е"
-  f.getc # => "с"
-  f.getc # => "т"
-  f.getc # => nil
+- IO#readchar (not in \StringIO):
+  Like #getc, but raises an exception at end-of-stream:
 
-===== \Method <tt>#readchar</tt>
+    f.readchar # Raises EOFError.
 
-Like #getc, but raises an exception at end-of-stream.
-
-Not in \StringIO.
-
-===== \Method <tt>#ungetc</tt>
-
-Pushes back ("unshifts") a character or integer onto the stream:
-
-  path = 't.tmp'
-  File.write(path, 'foo')
-  File.open(path) do |f|
-    f.ungetc('т')
-    f.read # => "тfoo"
-  end
+- IO#ungetc (not in \ARGF):
+  Pushes back ("unshifts") a character or integer onto the stream:
 
-Not in \ARGF.
-
-===== \Method <tt>#putc</tt>
-
-Writes a character to the stream:
-
-  File.open('t.tmp', 'w') do |f|
-    f.putc('т')
-    f.putc('е')
-    f.putc('с')
-    f.putc('т')
-  end
-  File.read('t.tmp') # => "тест"
+    path = 't.tmp'
+    File.write(path, 'foo')
+    File.open(path) do |f|
+      f.ungetc('т')
+      f.read # => "тfoo"
+    end
 
-Also in Kernel.
+- IO#putc (also in Kernel): Writes a character to the stream:
 
-===== \Method <tt>#each_char</tt>
+    File.open('t.tmp', 'w') do |f|
+      f.putc('т')
+      f.putc('е')
+      f.putc('с')
+      f.putc('т')
+    end
+    File.read('t.tmp') # => "тест"
 
-Reads each remaining character in the stream,
-passing the character to the given block:
+- IO#each_char: Reads each remaining character in the stream,
+  passing the character to the given block:
 
-  File.open('t.rus') do |f|
-    f.pos = 4
-    f.each_char {|c| p c }
-  end
+    File.open('t.rus') do |f|
+      f.pos = 4
+      f.each_char {|c| p c }
+    end
 
-Output:
+  Output:
 
-  "с"
-  "т"
+    "с"
+    "т"
 
 === Byte \IO
 
-You can process an \IO stream byte-by-byte.
+You can process an \IO stream byte-by-byte using these methods:
 
-===== \Method <tt>#getbyte</tt>
+- IO#getbyte: Returns the next 8-bit byte as an integer in range 0..255:
 
-Returns the next 8-bit byte as an integer in range 0..255:
+    File.read('t.dat')
+    # => "\xFE\xFF\x99\x90\x99\x91\x99\x92\x99\x93\x99\x94"
+    File.read('t.dat')
+    # => "\xFE\xFF\x99\x90\x99\x91\x99\x92\x99\x93\x99\x94"
+    f = File.new('t.dat')
+    f.getbyte # => 254
+    f.getbyte # => 255
+    f.seek(-2, :END)
+    f.getbyte # => 153
+    f.getbyte # => 148
+    f.getbyte # => nil
 
-  File.read('t.dat')
-  # => "\xFE\xFF\x99\x90\x99\x91\x99\x92\x99\x93\x99\x94"
-  File.read('t.dat')
-  # => "\xFE\xFF\x99\x90\x99\x91\x99\x92\x99\x93\x99\x94"
-  f = File.new('t.dat')
-  f.getbyte # => 254
-  f.getbyte # => 255
-  f.seek(-2, :END)
-  f.getbyte # => 153
-  f.getbyte # => 148
-  f.getbyte # => nil
+- IO#readbyte (not in \StringIO):
+  Like #getbyte, but raises an exception if at end-of-stream:
 
-===== \Method <tt>#readbyte</tt>
+    f.readbyte # Raises EOFError.
 
-Like #getbyte, but raises an exception if at end-of-stream:
+- IO#ungetbyte (not in \ARGF):
+  Pushes back ("unshifts") a byte back onto the stream:
 
-  f.readbyte # Raises EOFError.
+    f.ungetbyte(0)
+    f.ungetbyte(01)
+    f.read # => "\u0001\u0000"
 
-Not in \StringIO.
+- IO#each_byte: Reads each remaining byte in the stream,
+  passing the byte to the given block:
 
-===== \Method <tt>#ungetbyte</tt>
+    f.seek(-4, :END)
+    f.each_byte {|b| p b }
 
-Pushes back ("unshifts") a byte back onto the stream:
+  Output:
 
-  f.ungetbyte(0)
-  f.ungetbyte(01)
-  f.read # => "\u0001\u0000"
-
-Not in \ARGF.
-
-===== \Method <tt>#each_byte</tt>
-
-Reads each remaining byte in the stream,
-passing the byte to the given block:
-
-  f.seek(-4, :END)
-  f.each_byte {|b| p b }
-
-Output:
-
-  153
-  147
-  153
-  148
+    153
+    147
+    153
+    148
 
 === Codepoint \IO
 
-You can process an \IO stream codepoint-by-codepoint.
-
-===== \Method +each_codepoint+
-
-Reads each remaining codepoint in the stream,
-passing the codepoint to the given block:
+You can process an \IO stream codepoint-by-codepoint using method
++#each_codepoint+:
 
   a = []
   File.open('t.rus') do |f|