docs/read: Improve examples a bit

doc_src/cmds/read.rst

@@ -98,26 +98,29 @@ is set to empty and the exit status is set to 122. This limit can be altered wit
 Example
 -------
 
+``read`` has a few separate uses.
+
 The following code stores the value 'hello' in the shell variable :envvar:`$foo`.
 
-
-
 ::
 
     echo hello|read foo
 
-    # This is a neat way to handle command output by-line:
+While this is a neat way to handle command output line-by-line::
+
     printf '%s\n' line1 line2 line3 line4 | while read -l foo
                       echo "This is another line: $foo"
                   end
 
-    # Delimiters given via "-d" are taken as one string
+Delimiters given via "-d" are taken as one string::
+
     echo a==b==c | read -d == -l a b c
     echo $a # a
     echo $b # b
     echo $c # c
 
-    # --tokenize honors quotes and escaping like the shell's argument passing:
+``--tokenize`` honors quotes and escaping like the shell's argument passing::
+
     echo 'a\ b' | read -t first second
     echo $first # outputs "a b", $second is empty
 
@@ -125,3 +128,5 @@ The following code stores the value 'hello' in the shell variable :envvar:`$foo`
     echo $a # outputs 'afoo bar' (without the quotes)
     echo $b # outputs '(command echo wurst)* {a,b}' (without the quotes)
     echo $c # nothing
+
+For an example on interactive use, see :ref:`Querying for user input <user-input>`.

doc_src/language.rst

@@ -1540,6 +1540,8 @@ For a list of all builtins, use ``builtin -n``.
 
 For a list of all builtins, functions and commands shipped with fish, see the :ref:`list of commands <Commands>`. The documentation is also available by using the ``--help`` switch.
 
+.. _user-input:
+
 Querying for user input
 -----------------------