[DOC] Add link targets (#6602)

Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>

doc/io_streams.rdoc

@@ -87,10 +87,11 @@ Many examples here use these variables:
 
 === Basic \IO
 
-You can perform basic stream \IO with these methods:
+==== Reading and Writing
 
-- IO#read: Returns all remaining or the next _n_ bytes read from the stream,
+===== \Method <tt>#read</tt>
-  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"
@@ -100,7 +101,9 @@ You can perform basic stream \IO with these methods:
   f.read(30) # => nil
   f.close
 
-- IO#write: Writes one or more given strings to the stream:
+===== \Method <tt>#write</tt>
+
+Writes one or more given strings to the stream:
 
   $stdout.write('Hello', ', ', 'World!', "\n") # => 14
   $stdout.write('foo', :bar, 2, "\n")
@@ -117,9 +120,8 @@ 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.
 
-The relevant methods:
+===== \Method <tt>#tell</tt>
 
-- IO#tell (aliased as +#pos+):
 Returns the current position (in bytes) in the stream:
 
   f = File.new('t.txt')
@@ -128,7 +130,11 @@ The relevant methods:
   f.tell # => 12
   f.close
 
-- IO#pos=: Sets the position of the stream (in bytes):
+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
@@ -136,7 +142,9 @@ The relevant methods:
   f.tell     # => 20
   f.close
 
-- IO#seek: Sets the position of the stream to a given integer +offset+
+===== \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:
 
 - +:CUR+ or <tt>IO::SEEK_CUR</tt>:
@@ -174,7 +182,9 @@ The relevant methods:
     f.tell           # => 40
     f.close
 
-- IO#rewind: Positions the stream to the beginning (also resetting the line number):
+===== \Method <tt>#rewind</tt>
+
+Positions the stream to the beginning (also resetting the line number):
 
   f = File.new('t.txt')
   f.tell     # => 0
@@ -189,20 +199,33 @@ The relevant methods:
 
 A new \IO stream may be open for reading, open for writing, or both.
 
-You can close a stream using these methods:
+===== \Method <tt>#close</tt>
 
-- IO#close: Closes the stream for both reading and writing.
+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.
 
-You can query whether a stream is closed using this method:
+===== \Method <tt>#close_read</tt>
 
-- IO#closed?: Returns whether the stream is closed.
+Closes the stream for reading,
+
+Not in ARGF.
+
+===== \Method <tt>#close_write</tt>
+
+Closes the stream for writing
+
+Not in ARGF.
+
+===== \Method <tt>#closed?</tt>
+
+Returns whether the stream is closed.
 
 ==== End-of-Stream
 
-You can query whether a stream is positioned at its end using
+===== \Method <tt>#eof?</tt>
-method IO#eof? (also aliased as +#eof+).
+
+Returns whether a stream is positioned at its end; aliased as +#eof+.
+
+===== Repositioning to End-of-Stream
 
 You can reposition to end-of-stream by reading all stream content:
 
@@ -220,9 +243,11 @@ Or by using method IO#seek:
 
 === Line \IO
 
-You can read an \IO stream line-by-line using these methods:
+You can process an \IO stream line-by-line.
 
-- IO#each_line: Passes each line to the block:
+===== \Method <tt>#each_line</tt>
+
+Passes each line to the block:
 
   f = File.new('t.txt')
   f.each_line {|line| p line }
@@ -246,7 +271,9 @@ You can read an \IO stream line-by-line using these methods:
   "rth line\n"
   "Fifth line\n"
 
-- IO#gets (also in Kernel): Returns the next line (which may begin mid-line):
+===== \Method <tt>#gets</tt>
+
+Returns the next line (which may begin mid-line); also in Kernel:
 
   f = File.new('t.txt')
   f.gets      # => "First line\n"
@@ -256,10 +283,15 @@ You can read an \IO stream line-by-line using these methods:
   f.readlines # => ["Fifth line\n"]
   f.gets      # => nil
 
-- IO#readline (also in Kernel; not in StringIO):
+===== \Method <tt>#readline</tt>
+
 Like #gets, but raises an exception at end-of-stream.
 
-- IO#readlines (also in Kernel): Returns all remaining lines in an array;
+Also in Kernel; not in StringIO.
+
+===== \Method <tt>#readlines</tt>
+
+Returns all remaining lines in an array;
 may begin mid-line:
 
   f = File.new('t.txt')
@@ -267,21 +299,27 @@ You can read an \IO stream line-by-line using these methods:
   f.readlines # => ["ine\n", "\n", "Fourth line\n", "Fifth line\n"]
   f.readlines # => []
 
+Also in Kernel.
+
+===== Optional Reader Arguments
+
 Each of these reader methods may be called with:
 
 - An optional line separator, +sep+.
 - An optional line-size limit, +limit+.
 - Both +sep+ and +limit+.
 
-You can write to an \IO stream line-by-line using this method:
+===== \Method <tt>#puts</tt>
 
-- IO#puts (also in Kernel; not in \StringIO): Writes objects to the stream:
+Writes objects to the stream:
 
   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"
 
+Also in Kernel; not in StringIO.
+
 ==== Line Separator
 
 The default line separator is the given by the global variable <tt>$/</tt>,
@@ -368,13 +406,21 @@ 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
-(IO.foreach, IO#each_line, IO#gets, IO#readline, and IO#readlines)
+({::foreach}[https://docs.ruby-lang.org/en/master/IO.html#method-c-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])
 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 IO#lineno returns the line number.
+===== \Method <tt>#lineno</tt>
+
+Returns the line number.
+
+===== Changes to the Line Number
 
 Reading lines from a stream usually changes its line number:
 
@@ -414,9 +460,11 @@ that determine how lines in a stream are to be treated:
 
 === Character \IO
 
-You can process an \IO stream character-by-character using these methods:
+You can process an \IO stream character-by-character.
 
-- IO#getc: Reads and returns the next character from the stream:
+===== \Method <tt>#getc</tt>
+
+Reads and returns the next character from the stream:
 
   f = File.new('t.rus')
   f.getc # => "т"
@@ -425,12 +473,14 @@ You can process an \IO stream character-by-character using these methods:
   f.getc # => "т"
   f.getc # => nil
 
-- IO#readchar (not in \StringIO):
+===== \Method <tt>#readchar</tt>
-  Like #getc, but raises an exception at end-of-stream:
 
-    f.readchar # Raises EOFError.
+Like #getc, but raises an exception at end-of-stream.
+
+Not in \StringIO.
+
+===== \Method <tt>#ungetc</tt>
 
-- IO#ungetc (not in \ARGF):
 Pushes back ("unshifts") a character or integer onto the stream:
 
   path = 't.tmp'
@@ -440,7 +490,11 @@ You can process an \IO stream character-by-character using these methods:
     f.read # => "тfoo"
   end
 
-- IO#putc (also in Kernel): Writes a character to the stream:
+Not in \ARGF.
+
+===== \Method <tt>#putc</tt>
+
+Writes a character to the stream:
 
   File.open('t.tmp', 'w') do |f|
     f.putc('т')
@@ -450,7 +504,11 @@ You can process an \IO stream character-by-character using these methods:
   end
   File.read('t.tmp') # => "тест"
 
-- IO#each_char: Reads each remaining character in the stream,
+Also in Kernel.
+
+===== \Method <tt>#each_char</tt>
+
+Reads each remaining character in the stream,
 passing the character to the given block:
 
   File.open('t.rus') do |f|
@@ -465,9 +523,11 @@ You can process an \IO stream character-by-character using these methods:
 
 === Byte \IO
 
-You can process an \IO stream byte-by-byte using these methods:
+You can process an \IO stream byte-by-byte.
 
-- IO#getbyte: Returns the next 8-bit byte as an integer in range 0..255:
+===== \Method <tt>#getbyte</tt>
+
+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"
@@ -481,19 +541,27 @@ You can process an \IO stream byte-by-byte using these methods:
   f.getbyte # => 148
   f.getbyte # => nil
 
-- IO#readbyte (not in \StringIO):
+===== \Method <tt>#readbyte</tt>
+
 Like #getbyte, but raises an exception if at end-of-stream:
 
   f.readbyte # Raises EOFError.
 
-- IO#ungetbyte (not in \ARGF):
+Not in \StringIO.
+
+===== \Method <tt>#ungetbyte</tt>
+
 Pushes back ("unshifts") a byte back onto the stream:
 
   f.ungetbyte(0)
   f.ungetbyte(01)
   f.read # => "\u0001\u0000"
 
-- IO#each_byte: Reads each remaining byte in the stream,
+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)
@@ -508,8 +576,12 @@ You can process an \IO stream byte-by-byte using these methods:
 
 === Codepoint \IO
 
-You can process an \IO stream codepoint-by-codepoint using method
+You can process an \IO stream codepoint-by-codepoint.
-+#each_codepoint+:
+
+===== \Method +each_codepoint+
+
+Reads each remaining codepoint in the stream,
+passing the codepoint to the given block:
 
   a = []
   File.open('t.rus') do |f|