docs/read: Some reorganization

This just had *all the options* in one gigantic list, and some very
stuffy wording - "prompt-str" sounded like it was discouraged for some reason?

doc_src/cmds/read.rst

@@ -13,36 +13,54 @@ Synopsis
 Description
 -----------
 
-``read`` reads from standard input and either writes the result back to standard output (for use in command substitution), or stores the result in one or more shell variables. By default, ``read`` reads a single line and splits it into variables on spaces or tabs. Alternatively, a null character or a maximum number of characters can be used to terminate the input, and other delimiters can be given. Unlike other shells, there is no default variable (such as :envvar:`REPLY`) for storing the result - instead, it is printed on standard output.
+``read`` reads from standard input and either writes the result back to standard output (for use in command substitution), or stores the result in one or more shell variables.
 
-The following options are available:
+By default, ``read`` reads a single line and splits it into variables on spaces or tabs. Alternatively, a null character or a maximum number of characters can be used to terminate the input, and other delimiters can be given.
+
+Unlike other shells, there is no default variable (such as :envvar:`REPLY`) for storing the result - instead, it is printed on standard output.
+
+When ``read`` reaches the end-of-file (EOF) instead of the terminator, the exit status is set to 1.
+Otherwise, it is set to 0.
+
+The following options, like the corresponding ones in :doc:`set`, control variable scope or attributes:
+
+**-U** or **--universal**
+    Sets a universal variable.
+    The variable will be immediately available to all the user's ``fish`` instances on the machine, and will be persist across restarts of the shell.
+
+**-f** or **--function**
+    Sets a variable scoped to the executing function.
+    It is erased when the function ends.
+
+**-l** or **--local**
+    Sets a locally-scoped variable in this block.
+    It is erased when the block ends.
+    Outside of a block, this is the same as **--function**.
+
+**-g** or **--global**
+    Sets a globally-scoped variable.
+    Global variables are available to all functions running in the same shell.
+    They can be modified or erased.
+
+**-u** or **--unexport**
+    Prevents the variables from being exported to child processes (default behaviour).
+
+**-x** or **--export**
+    Exports the variables to child processes.
+
+The following options control the interactive mode:
 
 **-c** *CMD* or **--command** *CMD*
     Sets the initial string in the interactive mode command buffer to *CMD*.
 
-**-d** or **--delimiter** *DELIMITER*
-    Splits on *DELIMITER*. *DELIMITER* will be used as an entire string to split on, not a set of characters.
-
-**-g** or **--global**
-    Makes the variables global.
-
 **-s** or **--silent**
     Masks characters written to the terminal, replacing them with asterisks. This is useful for reading things like passwords or other sensitive information.
 
-**-f** or **--function**
-    Scopes the variable to the currently executing function. It is erased when the function ends.
-
-**-l** or **--local**
-    Scopes the variable to the currently executing block. It is erased when the block ends. Outside of a block, this is the same as **--function**.
-
-**-n** or **--nchars** *NCHARS*
-    Makes ``read`` return after reading *NCHARS* characters or the end of the line, whichever comes first.
-
 **-p** or **--prompt** *PROMPT_CMD*
     Uses the output of the shell command *PROMPT_CMD* as the prompt for the interactive mode. The default prompt command is ``set_color green; echo read; set_color normal; echo "> "``
 
 **-P** or **--prompt-str** *PROMPT_STR*
-    Uses the *PROMPT_STR* as the prompt for the interactive mode. It is equivalent to ``echo $PROMPT_STR`` and is provided solely to avoid the need to frame the prompt as a command. All special characters in the string are automatically escaped before being passed to the :doc:`echo <echo>` command.
+    Uses the literal *PROMPT_STR* as the prompt for the interactive mode.
 
 **-R** or **--right-prompt** *RIGHT_PROMPT_CMD*
     Uses the output of the shell command *RIGHT_PROMPT_CMD* as the right prompt for the interactive mode. There is no default right prompt command.
@@ -50,18 +68,17 @@ The following options are available:
 **-S** or **--shell**
     Enables syntax highlighting, tab completions and command termination suitable for entering shellscript code in the interactive mode. NOTE: Prior to fish 3.0, the short opt for **--shell** was **-s**, but it has been changed for compatibility with bash's **-s** short opt for **--silent**.
 
+The following options control how much is read and how it is stored:
+
+**-d** or **--delimiter** *DELIMITER*
+    Splits on *DELIMITER*. *DELIMITER* will be used as an entire string to split on, not a set of characters.
+
+**-n** or **--nchars** *NCHARS*
+    Makes ``read`` return after reading *NCHARS* characters or the end of the line, whichever comes first.
+
 **-t** -or **--tokenize**
     Causes read to split the input into variables by the shell's tokenization rules. This means it will honor quotes and escaping. This option is of course incompatible with other options to control splitting like **--delimiter** and does not honor :envvar:`IFS` (like fish's tokenizer). It saves the tokens in the manner they'd be passed to commands on the commandline, so e.g. ``a\ b`` is stored as ``a b``. Note that currently it leaves command substitutions intact along with the parentheses.
 
-**-u** or **--unexport**
-    Prevents the variables from being exported to child processes (default behaviour).
-
-**-U** or **--universal**
-    Causes the specified shell variable to be made universal.
-
-**-x** or **--export**
-    Exports the variables to child processes.
-
 **-a** or **--list**
     Stores the result as a list in a single variable. This option is also available as **--array** for backwards compatibility.
 
@@ -77,18 +94,13 @@ If no option to determine how to split like ``--delimiter``, ``--line`` or ``--t
 
 With the ``--line`` option, ``read`` reads a line of input from standard input into each provided variable, stopping when each variable has been filled. The line is not tokenized.
 
-If no variable names are provided, ``read`` enters a special case that simply provides redirection from standard input to standard output, useful for command substitution. For instance, the fish shell command below can be used to read data that should be provided via a command line argument from the console instead of hardcoding it in the command itself, allowing the command to both be reused as-is in various contexts with different input values and preventing possibly sensitive text from being included in the shell history::
+If no variable names are provided, ``read`` enters a special case that simply provides redirection from standard input to standard output, useful for command substitution. For instance, the fish shell command below can be used to read a password from the console instead of hardcoding it in the command itself, which prevents it from showing up in fish's history::
 
     mysql -uuser -p(read)
 
 When running in this mode, ``read`` does not split the input in any way and text is redirected to standard output without any further processing or manipulation.
 
-If ``-a`` or ``--array`` is provided, only one variable name is allowed and the tokens are stored as a list in this variable.
-
-See the documentation for ``set`` for more details on the scoping rules for variables.
-
-When ``read`` reaches the end-of-file (EOF) instead of the terminator, the exit status is set to 1.
-Otherwise, it is set to 0.
+If ``-l`` or ``--list`` is provided, only one variable name is allowed and the tokens are stored as a list in this variable.
 
 In order to protect the shell from consuming too many system resources, ``read`` will only consume a
 maximum of 100 MiB (104857600 bytes); if the terminator is not reached before this limit then *VARIABLE*