1 files changed, 40 insertions, 20 deletions
diff --git a/doc_src/read.txt b/doc_src/read.txt
index 1e8aef37..33829070 100644
--- a/doc_src/read.txt
+++ b/doc_src/read.txt
@@ -1,33 +1,53 @@
 \section read read - read line of input into variables
 
 \subsection read-synopsis Synopsis
-<tt>read [OPTIONS] [VARIABLES...]</tt>
+\fish{synopsis}
+read [OPTIONS] [VARIABLES...]
+\endfish
 
 \subsection read-description Description
 
-<tt>read</tt> reads one line from standard
-input and stores the result in one or more environment variables.
+`read` reads one line from standard input and stores the result in one or more shell variables.
 
 The following options are available:
 
-- <tt>-c CMD</tt> or <tt>--command=CMD</tt> sets the initial string in the interactive mode command buffer to <tt>CMD</tt>.
-- <tt>-g</tt> or <tt>--global</tt> makes the variables global (default behaviour).
-- <tt>-l</tt> or <tt>--local</tt> makes the variables local.
-- <tt>-m NAME</tt> or <tt>--mode-name=NAME</tt> specifies that the name NAME should be used to save/load the history file. If NAME is fish, the regular fish history will be available.
-- <tt>-p PROMPT_CMD</tt> or <tt>--prompt=PROMPT_CMD</tt> uses the output of the shell command \c PROMPT_CMD as the prompt for the interactive mode. The default prompt command is <tt>set_color green; echo read; set_color normal; echo "> "</tt>.
-- <code>-s</code> or <code>--shell</code> enables syntax highlighting, tab completions and command termination suitable for entering shellscript code in the interactive mode.
-- <code>-u</code> or <code>--unexport</code> prevents the variables from being exported to child processes (default behaviour).
-- <code>-U</code> or <code>--universal</code> causes the specified environment variable to be made universal.
-- <code>-x</code> or <code>--export</code> exports the variables to child processes.
-
-\c read reads a single line of input from stdin, breaks it into tokens
-based on the <tt>IFS</tt> environment variable, and then assigns one
-token to each variable specified in <tt>VARIABLES</tt>. If there are more
-tokens than variables, the complete remainder is assigned to the last variable.
+- `-c CMD` or `--command=CMD` sets the initial string in the interactive mode command buffer to `CMD`.
+
+- `-g` or `--global` makes the variables global.
+
+- `-l` or `--local` makes the variables local.
+
+- `-m NAME` or `--mode-name=NAME` specifies that the name NAME should be used to save/load the history file. If NAME is fish, the regular fish history will be available.
+
+- `-n NCHARS` or `--nchars=NCHARS` causes `read` to return after reading NCHARS characters rather than waiting for a complete line of input.
+
+- `-p PROMPT_CMD` 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 <code>set_color green; echo read; set_color normal; echo "> "</code>.
+
+- `-R RIGHT_PROMPT_CMD` 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.
+
+- `-s` or `--shell` enables syntax highlighting, tab completions and command termination suitable for entering shellscript code in the interactive mode.
+
+- `-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 `--array` stores the result as an array.
+
+- `-z` or `--null` reads up to NUL instead of newline. Disables interactive mode.
+
+`read` reads a single line of input from stdin, breaks it into tokens based on the `IFS` shell variable, and then assigns one token to each variable specified in `VARIABLES`. If there are more tokens than variables, the complete remainder is assigned to the last variable. As a special case, if `IFS` is set to the empty string, each character of the input is considered a separate token.
+
+If `-a` or `--array` is provided, only one variable name is allowed and the tokens are stored as an array in this variable.
+
+See the documentation for `set` for more details on the scoping rules for variables.
+
 
 \subsection read-example Example
 
-The following code stores the value 'hello' in the environment variable
-<tt>$foo</tt>.
+The following code stores the value 'hello' in the shell variable `$foo`.
 
-<tt>echo hello|read foo</tt>
+\fish
+echo hello|read foo
+\endfish