docs: omnibus cleanup

Includes harmonizing the display of options and arguments, standardising
terminology, using the envvar directive more broadly, adding help options to all
commands that support them, simplifying some language, and tidying up multiple
formatting issues.

string documentation is not changed.

doc_src/cmds/abbr.rst

@@ -46,7 +46,10 @@ The following options are available:
 **-q** or **--query**
     Return 0 (true) if one of the *WORD* is an abbreviation.
 
-In addition, when adding or renaming abbreviations:
+**-h** or **--help**
+    Displays help about using this command.
+
+In addition, when adding or renaming abbreviations, one of the following **SCOPE** options can be used:
 
 **-g** or **--global**
     Use a global variable

doc_src/cmds/alias.rst

@@ -9,8 +9,8 @@ Synopsis
 .. synopsis::
 
     alias
-    alias [OPTIONS] NAME DEFINITION
-    alias [OPTIONS] NAME=DEFINITION
+    alias [--save] NAME DEFINITION
+    alias [--save] NAME=DEFINITION
 
 
 Description
@@ -21,7 +21,7 @@ Description
 ``fish`` marks functions that have been created by ``alias`` by including the command used to create them in the function description. You can list ``alias``-created functions by running ``alias`` without arguments. They must be erased using ``functions -e``.
 
 - ``NAME`` is the name of the alias
-- ``DEFINITION`` is the actual command to execute. The string ``$argv`` will be appended.
+- ``DEFINITION`` is the actual command to execute. ``alias`` automatically appends ``$argv``, so that all parameters used with the alias are passed to the actual command.
 
 You cannot create an alias to a function with the same name. Note that spaces need to be escaped in the call to ``alias`` just like at the command line, *even inside quoted parts*.
 
@@ -55,6 +55,6 @@ The following code will create ``rmi``, which runs ``rm`` with additional argume
 See more
 --------
 
-1. The :ref:`function <cmd-function>` builtin this builds on.
+1. The :ref:`function <cmd-function>` command this builds on.
 2. :ref:`Functions <syntax-function>`.
 3. :ref:`Function wrappers <syntax-function-wrappers>`.

doc_src/cmds/and.rst

@@ -1,7 +1,7 @@
 .. _cmd-and:
 
 and - conditionally execute a command
-=========================================
+=====================================
 
 Synopsis
 --------
@@ -19,6 +19,8 @@ Description
 
 ``and`` does not change the current exit status itself, but the command it runs most likely will. The exit status of the last foreground command to exit can always be accessed using the :ref:`$status <variables-status>` variable.
 
+The **-h** or **--help** option displays help about using this command.
+
 Example
 -------
 
@@ -32,3 +34,4 @@ See Also
 --------
 
 - :ref:`or <cmd-or>` command
+- :ref:`not <cmd-not>` command

doc_src/cmds/argparse.rst

@@ -14,7 +14,7 @@ Synopsis
 Description
 -----------
 
-This command makes it easy for fish scripts and functions to handle arguments like how fish builtin commands handle their arguments. You pass arguments that define the known options, followed by a literal **--**, then the arguments to be parsed (which might also include a literal **--**). ``argparse`` then sets variables to indicate the passed options with their values, and sets $argv (and always $argv) to the remaining arguments. More on this in the :ref:`usage <cmd-argparse-usage>` section below.
+This command makes it easy for fish scripts and functions to handle arguments. You pass arguments that define the known options, followed by a literal **--**, then the arguments to be parsed (which might also include a literal **--**). ``argparse`` then sets variables to indicate the passed options with their values, and sets ``$argv`` to the remaining arguments. See the :ref:`usage <cmd-argparse-usage>` section below.
 
 Each option specification (``OPTION_SPEC``) is written in the :ref:`domain specific language <cmd-argparse-option-specification>` described below. All OPTION_SPECs must appear after any argparse flags and before the ``--`` that separates them from the arguments to be parsed.
 

doc_src/cmds/begin.rst

@@ -15,12 +15,14 @@ Description
 
 ``begin`` is used to create a new block of code.
 
-A block allows the introduction of a new variable scope, redirection of the input or output of a set of commands as a group, or to specify precedence when using the conditional commands like ``and``.
+A block allows the introduction of a new :ref:`variable scope <variables-scope>`, redirection of the input or output of a set of commands as a group, or to specify precedence when using the conditional commands like ``and``.
 
 The block is unconditionally executed. ``begin; ...; end`` is equivalent to ``if true; ...; end``.
 
 ``begin`` does not change the current exit status itself. After the block has completed, ``$status`` will be set to the status returned by the most recent command.
 
+The **-h** or **--help** option displays help about using this command.
+
 Example
 -------
 

doc_src/cmds/bg.rst

@@ -24,6 +24,8 @@ When at least one of the arguments isn't a valid job specifier,
 
 When all arguments are valid job specifiers, ``bg`` will background all matching jobs that exist.
 
+The **-h** or **--help** option displays help about using this command.
+
 Example
 -------
 

doc_src/cmds/bind.rst

@@ -81,6 +81,9 @@ The following options are available:
     All invocations except for inserting new bindings can operate on both levels at the same time (if both **--preset** and **--user** are given).
     **--preset** should only be used in full binding sets (like when working on ``fish_vi_key_bindings``).
 
+**-h** or **--help**
+    Displays help about using this command.
+
 Special input functions
 -----------------------
 The following special input functions are available:

doc_src/cmds/block.rst

@@ -8,7 +8,8 @@ Synopsis
 
 .. synopsis::
 
-    block [OPTIONS]
+    block [(--local | --global)]
+    block --erase
 
 Description
 -----------
@@ -21,6 +22,8 @@ The block can be removed. Any events which triggered while the block was in plac
 
 Event blocks should not be confused with code blocks, which are created with ``begin``, ``if``, ``while`` or ``for``
 
+Without options, the ``block`` command acts with function scope.
+
 The following options are available:
 
 **-l** or **--local**
@@ -32,6 +35,9 @@ The following options are available:
 **-e** or **--erase**
     Release global block.
 
+**-h** or **--help**
+    Displays help about using this command.
+
 Example
 -------
 ::

doc_src/cmds/break.rst

@@ -17,11 +17,10 @@ Synopsis
 Description
 -----------
 
-``break`` halts a currently running loop, such as a :ref:`switch <cmd-switch>`, :ref:`for <cmd-for>` or :ref:`while <cmd-while>` loop. It is usually added inside of a conditional block such as an :ref:`if <cmd-if>` block.
+``break`` halts a currently running loop (*LOOP_CONSTRUCT*), such as a :ref:`switch <cmd-switch>`, :ref:`for <cmd-for>` or :ref:`while <cmd-while>` loop. It is usually added inside of a conditional block such as an :ref:`if <cmd-if>` block.
 
 There are no parameters for ``break``.
 
-
 Example
 -------
 The following code searches all .c files for "smurf", and halts at the first occurrence.

doc_src/cmds/builtin.rst

@@ -10,11 +10,12 @@ Synopsis
 
     builtin [OPTIONS] BUILTINNAME
     builtin --query BUILTINNAME ...
+    builtin --names
 
 Description
 -----------
 
-``builtin`` forces the shell to use a builtin command, rather than a function or program.
+``builtin`` forces the shell to use a builtin command named *BUILTIN*, rather than a function or external program.
 
 The following options are available:
 
@@ -24,6 +25,9 @@ The following options are available:
 **-q** or **--query** *BUILTIN*
     Tests if any of the specified builtins exist.
 
+**-h** or **--help**
+    Displays help about using this command.
+
 Example
 -------
 

doc_src/cmds/cd.rst

@@ -12,7 +12,7 @@ Synopsis
 
 Description
 -----------
-**cd** changes the current working directory.
+``cd`` changes the current working directory.
 
 If *DIRECTORY* is given, it will become the new directory. If no parameter is given, the :envvar:`HOME` environment variable will be used.
 
@@ -28,6 +28,8 @@ If you make those universal variables your **cd** history is shared among all fi
 
 As a special case, ``cd .`` is equivalent to ``cd $PWD``, which is useful in cases where a mountpoint has been recycled or a directory has been removed and recreated.
 
+The **--help** or **-h** option displays help about using this command, and does not change the directory.
+
 Examples
 --------
 

doc_src/cmds/cdh.rst

@@ -8,7 +8,7 @@ Synopsis
 
 .. synopsis::
 
-    cdh [DIR]
+    cdh [DIRECTORY]
 
 Description
 -----------
@@ -16,11 +16,11 @@ Description
 ``cdh`` with no arguments presents a list of :ref:`recently visited directories <directory-history>`.
 You can then select one of the entries by letter or number.
 You can also press :kbd:`Tab` to use the completion pager to select an item from the list.
-If you give it a single argument it is equivalent to ``cd DIR``.
+If you give it a single argument it is equivalent to ``cd DIRECTORY``.
 
 Note that the ``cd`` command limits directory history to the 25 most recently visited directories.
-The history is stored in the ``$dirprev`` and ``$dirnext`` variables which this command manipulates.
-If you make those universal variables your ``cd`` history is shared among all fish instances.
+The history is stored in the :envvar:`dirprev` and :envvar:`$dirnext` variables, which this command manipulates.
+If you make those universal variables, your ``cd`` history is shared among all fish instances.
 
 See Also
 --------

doc_src/cmds/command.rst

@@ -28,6 +28,9 @@ The following options are available:
 **-v** (or **-s** or **--search**)
     Prints the external command that would be executed, or prints nothing if no file with the specified name could be found in :envvar:`PATH`.
 
+**-h** or **--help**
+    Displays help about using this command.
+
 With the **-v** option, ``command`` treats every argument as a separate command to look up and sets the exit status to 0 if any of the specified commands were found, or 127 if no commands could be found. **--quiet** used with **-v** prevents commands being printed, like ``type -q``.
 
 Examples

doc_src/cmds/commandline.rst

@@ -31,6 +31,9 @@ The following options are available:
     This option cannot be combined with any other option.
     See :ref:`bind <cmd-bind>` for a list of input functions.
 
+**-h** or **--help**
+    Displays help about using this command.
+
 The following options change the way ``commandline`` updates the command line buffer:
 
 **-a** or **--append**

doc_src/cmds/complete.rst

@@ -9,7 +9,7 @@ Synopsis
 .. synopsis::
 
     complete ((-c | --command) | (-p | --path)) COMMAND [OPTIONS] 
-    complete ((-C | --do-complete)) [STRING] [--escape] 
+    complete (-C | --do-complete) [--escape] STRING
 
 Description
 -----------
@@ -69,6 +69,9 @@ The following options are available:
 **--escape**
     When used with ``-C``, escape special characters in completions.
 
+**-h** or **--help**
+    Displays help about using this command.
+
 Command specific tab-completions in ``fish`` are based on the notion of options and arguments. An option is a parameter which begins with a hyphen, such as ``-h``, ``-help`` or ``--help``. Arguments are parameters that do not begin with a hyphen. Fish recognizes three styles of options, the same styles as the GNU getopt library. These styles are:
 
 - Short options, like ``-a``. Short options are a single character long, are preceded by a single hyphen and can be grouped together (like ``-la``, which is equivalent to ``-l -a``). Option arguments may be specified by appending the option with the value (``-w32``), or, if ``--require-parameter`` is given, in the following parameter (``-w 32``).

doc_src/cmds/contains.rst

@@ -21,6 +21,9 @@ The following options are available:
 **-i** or **--index**
     Print the index (number of the element in the set) of the first matching element.
 
+**-h** or **--help**
+    Displays help about using this command.
+
 Note that ``contains`` interprets all arguments starting with a **-** as an option to ``contains``, until an **--** argument is reached.
 
 See the examples below.

doc_src/cmds/dirs.rst

@@ -20,9 +20,12 @@ The following options are available:
 **-c**:
     Clear the directory stack instead of printing it.
 
-``dirs`` does not accept any parameters.
+**-h** or **--help**
+    Displays help about using this command.
+
+``dirs`` does not accept any arguments.
 
 See Also
 --------
 
-- the :ref:`cdh <cmd-cdh>` command which provides a more intuitive way to navigate to recently visited directories.
+- the :ref:`cdh <cmd-cdh>` command, which provides a more intuitive way to navigate to recently visited directories.

doc_src/cmds/disown.rst

@@ -23,6 +23,8 @@ If a job is stopped, it is sent a signal to continue running, and a warning is p
 
 ``disown`` returns 0 if all specified jobs were disowned successfully, and 1 if any problems were encountered.
 
+The **--help** or **-h** option displays help about using this command.
+
 Example
 -------
 

doc_src/cmds/emit.rst

@@ -15,6 +15,7 @@ Description
 
 ``emit`` emits, or fires, an event. Events are delivered to, or caught by, special functions called :ref:`event handlers <event>`. The arguments are passed to the event handlers as function arguments.
 
+The **--help** or **-h** option displays help about using this command.
 
 Example
 -------

doc_src/cmds/exec.rst

@@ -15,6 +15,7 @@ Description
 
 ``exec`` replaces the currently running shell with a new command. On successful completion, ``exec`` never returns. ``exec`` cannot be used inside a pipeline.
 
+The **--help** or **-h** option displays help about using this command.
 
 Example
 -------

doc_src/cmds/exit.rst

@@ -18,3 +18,5 @@ Description
 Otherwise, the exit status will be that of the last command executed.
 
 If exit is called while sourcing a file (using the :ref:`source <cmd-source>` builtin) the rest of the file will be skipped, but the shell itself will not exit.
+
+The **--help** or **-h** option displays help about using this command.

doc_src/cmds/fg.rst

@@ -21,6 +21,8 @@ If ``PID`` is specified, the job containing a process with the specified process
 For compatibility with other shells, job expansion syntax is supported for ``fg``. A *PID* of the format **%1** will foreground job 1.
 Job numbers can be seen in the output of :ref:`jobs <cmd-jobs>`.
 
+The **--help** or **-h** option displays help about using this command.
+
 Example
 -------
 

doc_src/cmds/fish_add_path.rst

@@ -24,7 +24,7 @@ Components are normalized by :ref:`realpath <cmd-realpath>`. Trailing slashes ar
 
 Components are added in the order they are given, and they are prepended to the path unless ``--append`` is given (if $fish_user_paths is used, that means they are last in $fish_user_paths, which is itself prepended to $PATH, so they still stay ahead of the system paths).
 
-If no component is new, the variable ($fish_user_paths or $PATH) is not set again or otherwise modified, so variable handlers are not triggered.
+If no component is new, the variable (:envvar:`fish_user_paths` or :envvar:`$PATH`) is not set again or otherwise modified, so variable handlers are not triggered.
 
 If a component is not an existing directory, ``fish_add_path`` ignores it.
 
@@ -55,6 +55,9 @@ Options
 **-n** or **--dry-run**
     Print the ``set`` command that would be used without executing it.
 
+**-h** or **--help**
+    Displays help about using this command.
+
 If ``--move`` is used, it may of course lead to the path swapping order, so you should be careful doing that in config.fish.
 
 

doc_src/cmds/fish_config.rst

@@ -43,6 +43,8 @@ Available subcommands for the ``theme`` command:
 
 The themes are loaded from the theme directory shipped with fish or a ``themes`` directory in the fish configuration directory (typically ``~/.config/fish/themes``).
 
+The **-h** or **--help** option displays help about using this command.
+
 Example
 -------
 

doc_src/cmds/fish_indent.rst

@@ -45,3 +45,6 @@ The following options are available:
 
 **--dump-parse-tree**
     Dumps information about the parsed statements to standard error. This is likely to be of interest only to people working on the fish source code.
+
+**-h** or **--help**
+    Displays help about using this command.

doc_src/cmds/fish_key_reader.rst

@@ -13,9 +13,9 @@ Synopsis
 Description
 -----------
 
-``fish_key_reader`` is used to explain how you would bind a certain key sequence. By default, it prints the :ref:`bind <cmd-bind>` command for one key sequence read interactively over standard input.
+:program:`fish_key_reader` is used to explain how you would bind a certain key sequence. By default, it prints the :ref:`bind <cmd-bind>` command for one key sequence read interactively over standard input.
 
-If the character sequence matches a special key name (see ``bind --key-names``),  both ``bind CHARS ...`` and ``bind -k KEYNAME ...`` usage will be shown. In verbose mode (enabled by passing ``--verbose``), additional details about the characters received, such as the delay between chars, are written to stderr.
+If the character sequence matches a special key name (see ``bind --key-names``),  both ``bind CHARS ...`` and ``bind -k KEYNAME ...`` usage will be shown. In verbose mode (enabled by passing ``--verbose``), additional details about the characters received, such as the delay between chars, are written to standard error.
 
 The following options are available:
 
@@ -34,7 +34,7 @@ The following options are available:
 Usage Notes
 -----------
 
-In verbose mode, the delay in milliseconds since the previous character was received is included in the diagnostic information written to stderr. This information may be useful to determine the optimal ``fish_escape_delay_ms`` setting or learn the amount of lag introduced by tools like ``ssh``, ``mosh`` or ``tmux``.
+In verbose mode, the delay in milliseconds since the previous character was received is included in the diagnostic information written to standard error. This information may be useful to determine the optimal ``fish_escape_delay_ms`` setting or learn the amount of lag introduced by tools like ``ssh``, ``mosh`` or ``tmux``.
 
 ``fish_key_reader`` intentionally disables handling of many signals. To terminate ``fish_key_reader`` in ``--continuous`` mode do:
 

doc_src/cmds/fish_opt.rst

@@ -1,20 +1,20 @@
 .. _cmd-fish_opt:
 
-fish_opt - create an option spec for the argparse command
-=========================================================
+fish_opt - create an option specification for the argparse command
+==================================================================
 
 Synopsis
 --------
 
 .. synopsis::
 
-    fish_opt [--help]
     fish_opt [(-slor | --multiple-vals=) OPTNAME]
+    fish_opt --help
 
 Description
 -----------
 
-This command provides a way to produce option specifications suitable for use with the :ref:`argparse <cmd-argparse>` command. You can, of course, write the option specs by hand without using this command. But you might prefer to use this for the clarity it provides.
+This command provides a way to produce option specifications suitable for use with the :ref:`argparse <cmd-argparse>` command. You can, of course, write the option specifications by hand without using this command. But you might prefer to use this for the clarity it provides.
 
 The following ``argparse`` options are available:
 
@@ -42,7 +42,7 @@ The following ``argparse`` options are available:
 Examples
 --------
 
-Define a single option spec for the boolean help flag:
+Define a single option specification for the boolean help flag:
 
 
 

doc_src/cmds/fish_svn_prompt.rst

@@ -25,47 +25,47 @@ The fish_svn_prompt function displays information about the current Subversion r
 
 There are numerous customization options, which can be controlled with fish variables.
 
-- ``$__fish_svn_prompt_color_revision``
+- :envvar:`__fish_svn_prompt_color_revision`
     the colour of the revision number to display in the prompt
-- ``$__fish_svn_prompt_char_separator``
+- :envvar:`__fish_svn_prompt_char_separator`
     the separator between status characters
 
 A number of variables control the symbol ("display") and color ("color") for the different status indicators:
 
-- ``$__fish_svn_prompt_char_added_display``
-- ``$__fish_svn_prompt_char_added_color``
-- ``$__fish_svn_prompt_char_conflicted_display``
-- ``$__fish_svn_prompt_char_conflicted_color``
-- ``$__fish_svn_prompt_char_deleted_display``
-- ``$__fish_svn_prompt_char_deleted_color``
-- ``$__fish_svn_prompt_char_ignored_display``
-- ``$__fish_svn_prompt_char_ignored_color``
-- ``$__fish_svn_prompt_char_modified_display``
-- ``$__fish_svn_prompt_char_modified_color``
-- ``$__fish_svn_prompt_char_replaced_display``
-- ``$__fish_svn_prompt_char_replaced_color``
-- ``$__fish_svn_prompt_char_unversioned_external_display``
-- ``$__fish_svn_prompt_char_unversioned_external_color``
-- ``$__fish_svn_prompt_char_unversioned_display``
-- ``$__fish_svn_prompt_char_unversioned_color``
-- ``$__fish_svn_prompt_char_missing_display``
-- ``$__fish_svn_prompt_char_missing_color``
-- ``$__fish_svn_prompt_char_versioned_obstructed_display``
-- ``$__fish_svn_prompt_char_versioned_obstructed_color``
-- ``$__fish_svn_prompt_char_locked_display``
-- ``$__fish_svn_prompt_char_locked_color``
-- ``$__fish_svn_prompt_char_scheduled_display``
-- ``$__fish_svn_prompt_char_scheduled_color``
-- ``$__fish_svn_prompt_char_switched_display``
-- ``$__fish_svn_prompt_char_switched_color``
-- ``$__fish_svn_prompt_char_token_present_display``
-- ``$__fish_svn_prompt_char_token_present_color``
-- ``$__fish_svn_prompt_char_token_other_display``
-- ``$__fish_svn_prompt_char_token_other_color``
-- ``$__fish_svn_prompt_char_token_stolen_display``
-- ``$__fish_svn_prompt_char_token_stolen_color``
-- ``$__fish_svn_prompt_char_token_broken_display``
-- ``$__fish_svn_prompt_char_token_broken_color``
+- :envvar:`__fish_svn_prompt_char_added_display`
+- :envvar:`__fish_svn_prompt_char_added_color`
+- :envvar:`__fish_svn_prompt_char_conflicted_display`
+- :envvar:`__fish_svn_prompt_char_conflicted_color`
+- :envvar:`__fish_svn_prompt_char_deleted_display`
+- :envvar:`__fish_svn_prompt_char_deleted_color`
+- :envvar:`__fish_svn_prompt_char_ignored_display`
+- :envvar:`__fish_svn_prompt_char_ignored_color`
+- :envvar:`__fish_svn_prompt_char_modified_display`
+- :envvar:`__fish_svn_prompt_char_modified_color`
+- :envvar:`__fish_svn_prompt_char_replaced_display`
+- :envvar:`__fish_svn_prompt_char_replaced_color`
+- :envvar:`__fish_svn_prompt_char_unversioned_external_display`
+- :envvar:`__fish_svn_prompt_char_unversioned_external_color`
+- :envvar:`__fish_svn_prompt_char_unversioned_display`
+- :envvar:`__fish_svn_prompt_char_unversioned_color`
+- :envvar:`__fish_svn_prompt_char_missing_display`
+- :envvar:`__fish_svn_prompt_char_missing_color`
+- :envvar:`__fish_svn_prompt_char_versioned_obstructed_display`
+- :envvar:`__fish_svn_prompt_char_versioned_obstructed_color`
+- :envvar:`__fish_svn_prompt_char_locked_display`
+- :envvar:`__fish_svn_prompt_char_locked_color`
+- :envvar:`__fish_svn_prompt_char_scheduled_display`
+- :envvar:`__fish_svn_prompt_char_scheduled_color`
+- :envvar:`__fish_svn_prompt_char_switched_display`
+- :envvar:`__fish_svn_prompt_char_switched_color`
+- :envvar:`__fish_svn_prompt_char_token_present_display`
+- :envvar:`__fish_svn_prompt_char_token_present_color`
+- :envvar:`__fish_svn_prompt_char_token_other_display`
+- :envvar:`__fish_svn_prompt_char_token_other_color`
+- :envvar:`__fish_svn_prompt_char_token_stolen_display`
+- :envvar:`__fish_svn_prompt_char_token_stolen_color`
+- :envvar:`__fish_svn_prompt_char_token_broken_display`
+- :envvar:`__fish_svn_prompt_char_token_broken_color`
 
 See also :ref:`fish_vcs_prompt <cmd-fish_vcs_prompt>`, which will call all supported version control prompt functions, including git, Mercurial and Subversion.
 

doc_src/cmds/fish_vcs_prompt.rst

@@ -29,7 +29,7 @@ It calls out to VCS-specific functions. The currently supported systems are:
 
 If a VCS isn't installed, the respective function does nothing.
 
-The svn prompt is disabled by default because it's slow on large svn repositories. To enable it, modify fish_vcs_prompt to uncomment it. See :ref:`funced <cmd-funced>`.
+The Subversion prompt is disabled by default, because it's slow on large repositories. To enable it, modify ``fish_vcs_prompt`` to uncomment it. See :ref:`funced <cmd-funced>`.
 
 For more information, see the documentation for each of the functions above.
 

doc_src/cmds/for.rst

@@ -17,6 +17,8 @@ Description
 
 Much like :ref:`set <cmd-set>`, **for** does not modify $status, but the evaluation of its subordinate commands can.
 
+The **-h** or **--help** option displays help about using this command.
+
 Example
 -------
 

doc_src/cmds/funced.rst

@@ -30,6 +30,9 @@ If there is no function called *NAME*, a new function will be created with the s
 **-s** or **--save**
     Automatically save the function after successfully editing it.
 
+**-h** or **--help**
+    Displays help about using this command.
+
 Example
 -------
 

doc_src/cmds/function.rst

@@ -14,7 +14,7 @@ Synopsis
 Description
 -----------
 
-``function`` creates a new function ``NAME`` with the body ``BODY``.
+``function`` creates a new function *NAME* with the body *BODY*.
 
 A function is a list of commands that will be executed when the name of the function is given as a command.
 

doc_src/cmds/functions.rst

@@ -62,6 +62,9 @@ The following options are available:
 **-t** or **--handlers-type** *TYPE*
     Show all event handlers matching the given *TYPE*.
 
+**-h** or **--help**
+    Displays help about using this command.
+
 The default behavior of ``functions``, when called with no arguments, is to print the names of all defined functions. Unless the ``-a`` option is given, no functions starting with underscores are included in the output.
 
 If any non-option parameters are given, the definition of the specified functions are printed.

doc_src/cmds/help.rst

@@ -17,9 +17,10 @@ Description
 
 If a *SECTION* is specified, the help for that command is shown.
 
-If the BROWSER environment variable is set, it will be used to display the documentation.
-Otherwise, fish will search for a suitable browser.
+The **-h** or **--help** option displays help about using this command.
 
+If the :envvar:`BROWSER`` environment variable is set, it will be used to display the documentation.
+Otherwise, fish will search for a suitable browser.
 To use a different browser than as described above, one can set the :envvar:`fish_help_browser` variable.
 This variable may be set as a list, where the first element is the browser command and the rest are browser options.
 
@@ -31,4 +32,4 @@ Example
 Notes
 -----
 
-Most builtin commands display their help in the terminal when given the **--help** option.
+Most builtin commands, including this one, display their help in the terminal when given the **--help** option.

doc_src/cmds/if.rst

@@ -22,6 +22,8 @@ You can use :ref:`and <cmd-and>` or :ref:`or <cmd-or>` in the condition. See the
 
 The exit status of the last foreground command to exit can always be accessed using the :ref:`$status <variables-status>` variable.
 
+The **-h** or **--help** option displays help about using this command.
+
 Example
 -------
 

doc_src/cmds/isatty.rst

@@ -19,6 +19,7 @@ Description
 
 If the specified file descriptor is a terminal device, the exit status of the command is zero. Otherwise, the exit status is non-zero. No messages are printed to standard error.
 
+The **-h** or **--help** option displays help about using this command.
 
 Examples
 --------

doc_src/cmds/jobs.rst

@@ -33,9 +33,12 @@ Description
 **-q** or **--query**
     Prints no output for evaluation of jobs by exit status only. For compatibility with old fish versions this is also **--quiet** (but this is deprecated).
 
+**-h** or **--help**
+    Displays help about using this command.
+
 On systems that supports this feature, jobs will print the CPU usage of each job since the last command was executed. The CPU usage is expressed as a percentage of full CPU activity. Note that on multiprocessor systems, the total activity may be more than 100\%.
 
-Arguments of the form ``PID`` or ``%JOBID`` restrict the output to jobs with the selected process identifiers or job numbers respectively.
+Arguments of the form *PID* or *%JOBID* restrict the output to jobs with the selected process identifiers or job numbers respectively.
 
 If the output of ``jobs`` is redirected or if it is part of a command substitution, the column header that is usually printed is omitted, making it easier to parse.
 

doc_src/cmds/math.rst

@@ -48,6 +48,9 @@ The following options are available:
     Hex numbers will be printed with a ``0x`` prefix.
     Octal numbers will have a prefix of ``0`` but aren't understood by ``math`` as input.
 
+**-h** or **--help**
+    Displays help about using this command.
+
 Return Values
 -------------
 

doc_src/cmds/nextd.rst

@@ -13,11 +13,13 @@ Synopsis
 Description
 -----------
 
-``nextd`` moves forwards ``POS`` positions in the :ref:`history of visited directories <directory-history>`; if the end of the history has been hit, a warning is printed.
+``nextd`` moves forwards *POS* positions in the :ref:`history of visited directories <directory-history>`; if the end of the history has been hit, a warning is printed.
 
-If the ``-l`` or ``--list`` flag is specified, the current directory history is also displayed.
+If the **-l** or **--list** option is specified, the current directory history is also displayed.
 
-Note that the ``cd`` command limits directory history to the 25 most recently visited directories. The history is stored in the ``$dirprev`` and ``$dirnext`` variables which this command manipulates.
+The **-h** or **--help** option displays help about using this command.
+
+Note that the ``cd`` command limits directory history to the 25 most recently visited directories. The history is stored in the :envvar:`dirprev` and :envvar:`dirnext` variables which this command manipulates.
 
 Example
 -------

doc_src/cmds/not.rst

@@ -16,6 +16,7 @@ Description
 
 ``not`` negates the exit status of another command. If the exit status is zero, ``not`` returns 1. Otherwise, ``not`` returns 0.
 
+The **-h** or **--help** option displays help about using this command.
 
 Example
 -------

doc_src/cmds/or.rst

@@ -19,6 +19,8 @@ Description
 
 ``or`` does not change the current exit status itself, but the command it runs most likely will. The exit status of the last foreground command to exit can always be accessed using the :ref:`$status <variables-status>` variable.
 
+The **-h** or **--help** option displays help about using this command.
+
 Example
 -------
 

doc_src/cmds/popd.rst

@@ -15,6 +15,8 @@ Description
 
 ``popd`` removes the top directory from the :ref:`directory stack <directory-stack>` and changes the working directory to the new top directory. Use :ref:`pushd <cmd-pushd>` to add directories to the stack.
 
+The **-h** or **--help** option displays help about using this command.
+
 Example
 -------
 

doc_src/cmds/prevd.rst

@@ -13,11 +13,13 @@ Synopsis
 Description
 -----------
 
-``prevd`` moves backwards ``POS`` positions in the :ref:`history of visited directories <directory-history>`; if the beginning of the history has been hit, a warning is printed.
+``prevd`` moves backwards *POS* positions in the :ref:`history of visited directories <directory-history>`; if the beginning of the history has been hit, a warning is printed.
 
-If the ``-l`` or ``--list`` flag is specified, the current history is also displayed.
+If the **-l** or **--list** flag is specified, the current history is also displayed.
 
-Note that the ``cd`` command limits directory history to the 25 most recently visited directories. The history is stored in the ``$dirprev`` and ``$dirnext`` variables which this command manipulates.
+Note that the ``cd`` command limits directory history to the 25 most recently visited directories. The history is stored in the :envvar:`dirprev` and :envvar:`dirnext` variables which this command manipulates.
+
+The **-h** or **--help** option displays help about using this command.
 
 Example
 -------

doc_src/cmds/printf.rst

@@ -19,9 +19,9 @@ Description
           To see the documentation on the ``printf`` command you might have,
           use ``command man printf``.
 
-printf uses the format string FORMAT to print the ARGUMENT arguments. This means that it takes format specifiers in the format string and replaces each with an argument.
+``printf`` uses the format string *FORMAT* to print the *ARGUMENT* arguments. This means that it takes format specifiers in the format string and replaces each with an argument.
 
-The ``format`` argument is re-used as many times as necessary to convert all of the given arguments. So ``printf %s\n flounder catfish clownfish shark`` will print four lines.
+The *FORMAT* argument is re-used as many times as necessary to convert all of the given arguments. So ``printf %s\n flounder catfish clownfish shark`` will print four lines.
 
 Unlike :ref:`echo <cmd-echo>`, ``printf`` does not append a new line unless it is specified as part of the string.
 

doc_src/cmds/prompt_login.rst

@@ -13,7 +13,7 @@ Synopsis
 Description
 -----------
 
-``prompt_login`` is a function to describe the current login. It will show the user, the host and also whether the shell is running in a chroot (currently debian's debian_chroot is supported).
+``prompt_login`` is a function to describe the current login. It will show the user, the host and also whether the shell is running in a chroot (currently Debian's ``debian_chroot`` file is supported).
 
 Examples
 --------

doc_src/cmds/prompt_pwd.rst

@@ -15,11 +15,11 @@ Description
 
 ``prompt_pwd`` is a function to print the current working directory in a way suitable for prompts. It will replace the home directory with "~" and shorten every path component but the last to a default of one character.
 
-To change the number of characters per path component, pass ``--dir-length=`` or set ``$fish_prompt_pwd_dir_length`` to the number of characters. Setting it to 0 or an invalid value will disable shortening entirely. This defaults to 1.
+To change the number of characters per path component, pass ``--dir-length=`` or set :envvar:`fish_prompt_pwd_dir_length` to the number of characters. Setting it to 0 or an invalid value will disable shortening entirely. This defaults to 1.
 
-To keep some components unshortened, pass ``--full-length-dirs=`` or set ``$fish_prompt_pwd_full_dirs`` to the number of components. This defaults to 1, keeping the last component.
+To keep some components unshortened, pass ``--full-length-dirs=`` or set :envvar:`$fish_prompt_pwd_full_dirs` to the number of components. This defaults to 1, keeping the last component.
 
-If any positional arguments are given, prompt_pwd shortens them instead of $PWD.
+If any positional arguments are given, ``prompt_pwd`` shortens them instead of $PWD.
 
 Options
 -------

doc_src/cmds/psub.rst

@@ -26,6 +26,9 @@ The following options are available:
 **-s** or **--suffix** *SUFFIX*
     Append SUFFIX to the filename.
 
+**-h** or **--help**
+    Displays help about using this command.
+
 Example
 -------
 

doc_src/cmds/pushd.rst

@@ -13,7 +13,7 @@ Synopsis
 Description
 -----------
 
-The ``pushd`` function adds ``DIRECTORY`` to the top of the :ref:`directory stack <directory-stack>` and makes it the current working directory. :ref:`popd <cmd-popd>` will pop it off and return to the original directory.
+The ``pushd`` function adds *DIRECTORY* to the top of the :ref:`directory stack <directory-stack>` and makes it the current working directory. :ref:`popd <cmd-popd>` will pop it off and return to the original directory.
 
 Without arguments, it exchanges the top two directories in the stack.
 
@@ -21,6 +21,8 @@ Without arguments, it exchanges the top two directories in the stack.
 
 ``pushd -NUMBER`` rotates clockwise i.e. top to bottom.
 
+The **-h** or **--help** option displays help about using this command.
+
 Example
 -------
 

doc_src/cmds/pwd.rst

@@ -31,6 +31,9 @@ The following options are available:
 **-P** or **--physical**
     Output the physical working directory, with symlinks resolved.
 
+**-h** or **--help**
+    Displays help about using this command.
+
 See Also
 --------
 

doc_src/cmds/random.rst

@@ -19,17 +19,21 @@ Description
 
 ``random`` generates a pseudo-random integer from a uniform distribution. The
 range (inclusive) depends on the arguments.
+
 No arguments indicate a range of 0 to 32767 (inclusive).
 
 If one argument is specified, the internal engine will be seeded with the
 argument for future invocations of ``random`` and no output will be produced.
 
-Two arguments indicate a range from START to END (both START and END included).
+Two arguments indicate a range from *START* to *END* (both *START* and *END* included).
 
-Three arguments indicate a range from START to END with a spacing of STEP
+Three arguments indicate a range from *START* to *END* with a spacing of *STEP*
 between possible outputs.
+
 ``random choice`` will select one random item from the succeeding arguments.
 
+The **-h** or **--help** option displays help about using this command.
+
 Note that seeding the engine will NOT give the same result across different
 systems.
 

doc_src/cmds/read.rst

@@ -13,48 +13,65 @@ 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 ``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. 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.
 
 The following options are available:
 
-- ``-c CMD`` or ``--command=CMD`` sets the initial string in the interactive mode command buffer to ``CMD``.
+**-c** *CMD* or **--command** *CMD*
+    Sets the initial string in the interactive mode command buffer to *CMD*.
 
-- ``-d DELIMITER`` or ``--delimiter=DELIMITER`` splits on DELIMITER. DELIMITER will be used as an entire string to split on, not a set of characters.
+**-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.
+**-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.
+**-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.
+**-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``.
+**-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 NCHARS`` or ``--nchars=NCHARS`` makes ``read`` return after reading NCHARS characters or the end of
-  the line, whichever comes first.
+**-n** or **--nchars** *NCHARS*
+    Makes ``read`` return after reading *NCHARS* characters or the end of the line, whichever comes first.
 
-- ``-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 ``set_color green; echo read; set_color normal; echo "> "``
+**-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 PROMPT_STR`` or ``--prompt-str=PROMPT_STR`` uses the string 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 :ref:`echo <cmd-echo>` command.
+**-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 :ref:`echo <cmd-echo>` command.
 
-- ``-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.
+**-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.
 
-- ``-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``.
+**-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**.
 
-- ``-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 $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.
+**-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 **--unexport**
+    Prevents the variables from being exported to child processes (default behaviour).
 
-- ``-U`` or ``--universal`` causes the specified shell variable to be made universal.
+**-U** or **--universal**
+    Causes the specified shell variable to be made universal.
 
-- ``-x`` or ``--export`` exports the variables to child processes.
+**-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.
+**-a** or **--list**
+    Stores the result as a list in a single variable. This option is also available as **--array** for backwards compatibility.
 
-- ``-z`` or ``--null`` marks the end of the line with the NUL character, instead of newline. This also disables interactive mode.
+**-z** or **--null**
+    Marks the end of the line with the NUL character, instead of newline. This also disables interactive mode.
 
-- ``-L`` or ``--line`` reads each line into successive variables, and stops after each variable has been filled. This cannot be combined with the ``--delimiter`` option.
+**-L** or **--line**
+    Reads each line into successive variables, and stops after each variable has been filled. This cannot be combined with the ``--delimiter`` option.
 
-Without the ``--line`` option, ``read`` reads a single line of input from standard input, breaks it into tokens, 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.
+Without the ``--line`` option, ``read`` reads a single line of input from standard input, breaks it into tokens, 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.
 
 If no option to determine how to split like ``--delimiter``, ``--line`` or ``--tokenize`` is given, the variable ``IFS`` is used as a list of characters to split on. Relying on the use of ``IFS`` is deprecated and this behaviour will be removed in future versions. The default value of ``IFS`` contains space, tab and newline characters. As a special case, if ``IFS`` is set to the empty string, each character of the input is considered a separate token.
 
@@ -74,14 +91,14 @@ When ``read`` reaches the end-of-file (EOF) instead of the terminator, the exit
 Otherwise, it is set to 0.
 
 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
+maximum of 100 MiB (104857600 bytes); if the terminator is not reached before this limit then *VARIABLE*
 is set to empty and the exit status is set to 122. This limit can be altered with the
-``fish_read_limit`` variable. If set to 0 (zero), the limit is removed.
+:envvar:`fish_read_limit` variable. If set to 0 (zero), the limit is removed.
 
 Example
 -------
 
-The following code stores the value 'hello' in the shell variable ``$foo``.
+The following code stores the value 'hello' in the shell variable :envvar:`$foo`.
 
 
 

doc_src/cmds/realpath.rst

@@ -29,3 +29,6 @@ The following options are available:
 
 **-s** or **--no-symlinks**
     Don't resolve symlinks, only make paths absolute, squash multiple slashes and remove trailing slashes.
+
+**-h** or **--help**
+    Displays help about using this command.

doc_src/cmds/return.rst

@@ -15,7 +15,7 @@ Description
 -----------
 
 :program:`return` halts a currently running function.
-The exit status is set to ``N`` if it is given.
+The exit status is set to *N* if it is given.
 If :program:`return` is invoked outside of a function or dot script it is equivalent to exit.
 
 It is often added inside of a conditional block such as an :ref:`if <cmd-if>` statement or a :ref:`switch <cmd-switch>` statement to conditionally stop the executing function and return to the caller; it can also be used to specify the exit status of a function.
@@ -23,6 +23,8 @@ It is often added inside of a conditional block such as an :ref:`if <cmd-if>` st
 If at the top level of a script, it exits with the given status, like :ref:`exit <cmd-exit>`.
 If at the top level in an interactive session, it will set :envvar:`status`, but not exit the shell.
 
+The **-h** or **--help** option displays help about using this command.
+
 Example
 -------
 

doc_src/cmds/set.rst

@@ -82,6 +82,9 @@ The following other options are available:
 **-L** or **--long**
     Do not abbreviate long values when printing set variables.
 
+**-h** or **--help**
+    Displays help about using this command.
+
 If a variable is set to more than one value, the variable will be a list with the specified elements. If a variable is set to zero elements, it will become a list with zero elements.
 
 If the variable name is one or more list elements, such as ``PATH[1 3 7]``, only those list elements specified will be changed. If you specify a negative index when expanding or assigning to a list variable, the index will be calculated from the end of the list. For example, the index -1 means the last index of a list.
@@ -108,12 +111,12 @@ In query mode, the scope to be examined can be specified. Whether the variable h
 
 In erase mode, if variable indices are specified, only the specified slices of the list variable will be erased.
 
-``set`` requires all options to come before any other arguments. For example, ``set flags -l`` will have the effect of setting the value of the variable ``flags`` to '-l', not making the variable local.
+``set`` requires all options to come before any other arguments. For example, ``set flags -l`` will have the effect of setting the value of the variable :envvar:`flags` to '-l', not making the variable local.
 
 Exit status
 -----------
 
-In assignment mode, ``set`` does not modify the exit status, but passes along whatever $status was set, including by command substitutions. This allows capturing the output and exit status of a subcommand, like in ``if set output (command)``.
+In assignment mode, ``set`` does not modify the exit status, but passes along whatever :envvar:`status` was set, including by command substitutions. This allows capturing the output and exit status of a subcommand, like in ``if set output (command)``.
 
 In query mode, the exit status is the number of variables that were not found.
 

doc_src/cmds/set_color.rst

@@ -13,16 +13,16 @@ Synopsis
 Description
 -----------
 
-``set_color`` is used to control the color and styling of text in the terminal. ``VALUE`` describes that styling. ``VALUE`` can be a reserved color name like *red* or a RGB color value given as 3 or 6 hexadecimal digits ("F27" or "FF2277"). A special keyword *normal* resets text formatting to terminal defaults.
+``set_color`` is used to control the color and styling of text in the terminal. *VALUE* describes that styling. *VALUE* can be a reserved color name like **red** or a RGB color value given as 3 or 6 hexadecimal digits ("F27" or "FF2277"). A special keyword **normal** resets text formatting to terminal defaults.
 
 Valid colors include:
 
-  - *black*, *red*, *green*, *yellow*, *blue*, *magenta*, *cyan*, *white*
-  - *brblack*, *brred*, *brgreen*, *bryellow*, *brblue*, *brmagenta*, *brcyan*, *brwhite*
+  - **black**, **red**, **green**, **yellow**, **blue**, **magenta**, **cyan**, **white**
+  - **brblack**, **brred**, **brgreen**, **bryellow**, **brblue**, **brmagenta**, **brcyan**, **brwhite**
 
-The *br*- (as in 'bright') forms are full-brightness variants of the 8 standard-brightness colors on many terminals. *brblack* has higher brightness than *black* - towards gray.
+The *br*- (as in 'bright') forms are full-brightness variants of the 8 standard-brightness colors on many terminals. **brblack** has higher brightness than **black** - towards gray.
 
-An RGB value with three or six hex digits, such as A0FF33 or f2f can be used. ``fish`` will choose the closest supported color. A three digit value is equivalent to specifying each digit twice; e.g., ``set_color 2BC`` is the same as ``set_color 22BBCC``. Hexadecimal RGB values can be in lower or uppercase. Depending on the capabilities of your terminal (and the level of support ``set_color`` has for it) the actual color may be approximated by a nearby matching reserved color name or ``set_color`` may not have an effect on color.
+An RGB value with three or six hex digits, such as A0FF33 or f2f can be used. Fish will choose the closest supported color. A three digit value is equivalent to specifying each digit twice; e.g., ``set_color 2BC`` is the same as ``set_color 22BBCC``. Hexadecimal RGB values can be in lower or uppercase. Depending on the capabilities of your terminal (and the level of support ``set_color`` has for it) the actual color may be approximated by a nearby matching reserved color name or ``set_color`` may not have an effect on color.
 
 A second color may be given as a desired fallback color. e.g. ``set_color 124212 brblue`` will instruct set_color to use *brblue* if a terminal is not capable of the exact shade of grey desired. This is very useful when an 8 or 16 color terminal might otherwise not use a color.
 
@@ -49,15 +49,18 @@ The following options are available:
 **-u** or **--underline**
     Sets underlined mode.
 
+**-h** or **--help**
+    Displays help about using this command.
+
 Using the **normal** keyword will reset foreground, background, and all formatting back to default.
 
 Notes
 -----
 
-1. Using the *normal* keyword will reset both background and foreground colors to whatever is the default for the terminal.
+1. Using the **normal** keyword will reset both background and foreground colors to whatever is the default for the terminal.
 2. Setting the background color only affects subsequently written characters. Fish provides no way to set the background color for the entire terminal window. Configuring the window background color (and other attributes such as its opacity) has to be done using whatever mechanisms the terminal provides. Look for a config option.
 3. Some terminals use the ``--bold`` escape sequence to switch to a brighter color set rather than increasing the weight of text.
-4. ``set_color`` works by printing sequences of characters to *stdout*. If used in command substitution or a pipe, these characters will also be captured. This may or may not be desirable. Checking the exit status of ``isatty stdout`` before using ``set_color`` can be useful to decide not to colorize output in a script.
+4. ``set_color`` works by printing sequences of characters to standard output. If used in command substitution or a pipe, these characters will also be captured. This may or may not be desirable. Checking the exit status of ``isatty stdout`` before using ``set_color`` can be useful to decide not to colorize output in a script.
 
 Examples
 --------
@@ -78,13 +81,13 @@ Fish uses some heuristics to determine what colors a terminal supports to avoid
 
 In particular it will:
 
-- Enable 256 colors if $TERM contains "xterm", except for known exceptions (like MacOS 10.6 Terminal.app)
+- Enable 256 colors if :envvar:`TERM` contains "xterm", except for known exceptions (like MacOS 10.6 Terminal.app)
 - Enable 24-bit ("true-color") even if the $TERM entry only reports 256 colors. This includes modern xterm, VTE-based terminals like Gnome Terminal, Konsole and iTerm2.
 - Detect support for italics, dim, reverse and other modes.
 
 If terminfo reports 256 color support for a terminal, 256 color support will always be enabled.
 
-To force true-color support on or off, set $fish_term24bit to "1" for on and 0 for off - ``set -g fish_term24bit 1``.
+To force true-color support on or off, set :envvar:`fish_term24bit`` to "1" for on and 0 for off - ``set -g fish_term24bit 1``.
 
 To debug color palette problems, ``tput colors`` may be useful to see the number of colors in terminfo for a terminal. Fish launched as ``fish -d2`` will include diagnostic messages that indicate the color support mode in use.
 

doc_src/cmds/source.rst

@@ -15,18 +15,19 @@ Synopsis
 Description
 -----------
 
-``source`` evaluates the commands of the specified file in the current shell as a new block of code. This is different from starting a new process to perform the commands (i.e. ``fish < FILE``) since the commands will be evaluated by the current shell, which means that changes in shell variables will affect the current shell. If additional arguments are specified after the file name, they will be inserted into the ``$argv`` variable. The ``$argv`` variable will not include the name of the sourced file.
+``source`` evaluates the commands of the specified *FILE* in the current shell as a new block of code. This is different from starting a new process to perform the commands (i.e. ``fish < FILE``) since the commands will be evaluated by the current shell, which means that changes in shell variables will affect the current shell. If additional arguments are specified after the file name, they will be inserted into the :envvar:`argv` variable. The :envvar:`argv` variable will not include the name of the sourced file.
 
-fish will search the working directory to resolve relative paths but will not search ``$PATH``.
+fish will search the working directory to resolve relative paths but will not search :envvar:`PATH` .
 
 If no file is specified and stdin is not the terminal, or if the file name ``-`` is used, stdin will be read.
 
 The exit status of ``source`` is the exit status of the last job to execute. If something goes wrong while opening or reading the file, ``source`` exits with a non-zero status.
 
-``.`` (a single period) is an alias for the ``source`` command. The use of ``.`` is deprecated in favour of ``source``, and ``.`` will be removed in a future version of fish.
+**.** (a single period) is an alias for the ``source`` command. The use of **.** is deprecated in favour of ``source``, and **.** will be removed in a future version of fish.
 
 ``source`` creates a new :ref:`local scope<variables-scope>`; ``set --local`` within a sourced block will not affect variables in the enclosing scope.
 
+The **-h** or **--help** option displays help about using this command.
 
 Example
 -------
@@ -42,4 +43,4 @@ Example
 Caveats
 -------
 
-In fish versions prior to 2.3.0, the ``$argv`` variable would have a single element (the name of the sourced file) if no arguments are present. Otherwise, it would contain arguments without the name of the sourced file. That behavior was very confusing and unlike other shells such as bash and zsh.
+In fish versions prior to 2.3.0, the :envvar:`argv` variable would have a single element (the name of the sourced file) if no arguments are present. Otherwise, it would contain arguments without the name of the sourced file. That behavior was very confusing and unlike other shells such as bash and zsh.

doc_src/cmds/status.rst

@@ -34,7 +34,7 @@ Description
 
 With no arguments, ``status`` displays a summary of the current login and job control status of the shell.
 
-The following operations (sub-commands) are available:
+The following operations (subcommands) are available:
 
 **is-command-substitution**, **-c** or **--is-command-substitution**
     Returns 0 if fish is currently executing a command substitution.

doc_src/cmds/suspend.rst

@@ -13,4 +13,4 @@ Synopsis
 Description
 -----------
 
-``suspend`` suspends execution of the current shell by sending it a SIGTSTP signal, returning to the controlling process. It can be resumed later by sending it a SIGCONT.  In order to prevent suspending a shell that doesn't have a controlling process, it will not suspend the shell if it is a login shell. This requirement is bypassed if the ``--force`` option is given or the shell is not interactive.
+``suspend`` suspends execution of the current shell by sending it a SIGTSTP signal, returning to the controlling process. It can be resumed later by sending it a SIGCONT.  In order to prevent suspending a shell that doesn't have a controlling process, it will not suspend the shell if it is a login shell. This requirement is bypassed if the **--force** option is given or the shell is not interactive.

doc_src/cmds/switch.rst

@@ -25,9 +25,7 @@ Note that command substitutions in a case statement will be evaluated even if it
 Example
 -------
 
-If the variable \$animal contains the name of an animal, the following code would attempt to classify it:
-
-
+If the variable :envvar:`animal` contains the name of an animal, the following code would attempt to classify it:
 
 ::
 

doc_src/cmds/test.rst

@@ -143,7 +143,7 @@ Expressions can be grouped using parentheses.
 **(** *EXPRESSION* **)**
      Returns the value of *EXPRESSION*.
 
- Note that parentheses will usually require escaping with ``\(`` to avoid being interpreted as a command substitution.
+Note that parentheses will usually require escaping with ``\(`` to avoid being interpreted as a command substitution.
 
 
 Examples
@@ -160,7 +160,7 @@ If the ``/tmp`` directory exists, copy the ``/etc/motd`` file to it:
     end
 
 
-If the variable ``MANPATH`` is defined and not empty, print the contents. (If ``MANPATH`` is not defined, then it will expand to zero arguments, unless quoted.)
+If the variable :envvar:`MANPATH` is defined and not empty, print the contents. (If :envvar:`MANPATH` is not defined, then it will expand to zero arguments, unless quoted.)
 
 
 
@@ -193,7 +193,7 @@ Numerical comparisons will simply fail if one of the operands is not a number:
     end
 
 
-A common comparison is with $status:
+A common comparison is with :envvar:`status`:
 
 
 

doc_src/cmds/trap.rst

@@ -29,15 +29,18 @@ The following parameters are available:
 **-p** or **--print**
     Prints all defined signal handlers.
 
-If ``ARG`` and ``REASON`` are both specified, ``ARG`` is the command to be executed when the event specified by ``REASON`` occurs (e.g., the signal is delivered).
+**-h** or **--help**
+    Displays help about using this command.
 
-If ``ARG`` is absent (and there is a single REASON) or -, each specified signal is reset to its original disposition (the value it had upon entrance to the shell).  If ``ARG`` is the null string the signal specified by each ``REASON`` is ignored by the shell and by the commands it invokes.
+If *ARG* and *REASON* are both specified, *ARG* is the command to be executed when the event specified by *REASON* occurs (e.g., the signal is delivered).
 
-If ``ARG`` is not present and ``-p`` has been supplied, then the trap commands associated with each ``REASON`` are displayed. If no arguments are supplied or if only ``-p`` is given, ``trap`` prints the list of commands associated with each signal.
+If *ARG* is absent (and there is a single *REASON*) or ``-``, each specified signal is reset to its original disposition (the value it had upon entrance to the shell).  If *ARG* is the null string the signal specified by each *REASON* is ignored by the shell and by the commands it invokes.
+
+If *ARG* is not present and **-p** has been supplied, then the trap commands associated with each *REASON* are displayed. If no arguments are supplied or if only **-p** is given, ``trap`` prints the list of commands associated with each signal.
 
 Signal names are case insensitive and the ``SIG`` prefix is optional.
 
-The exit status is 1 if any ``REASON`` is invalid; otherwise trap returns 0.
+The exit status is 1 if any *REASON* is invalid; otherwise trap returns 0.
 
 Example
 -------

doc_src/cmds/type.rst

@@ -13,7 +13,7 @@ Synopsis
 Description
 -----------
 
-With no options, :command:`type` indicates how each ``NAME`` would be interpreted if used as a command name.
+With no options, :command:`type` indicates how each *NAME* would be interpreted if used as a command name.
 
 The following options are available:
 
@@ -38,7 +38,10 @@ The following options are available:
 **-q** or **--query**
     Suppresses all output; this is useful when testing the exit status. For compatibility with old fish versions this is also **--quiet**.
 
-The ``-q``, ``-p``, ``-t`` and ``-P`` flags (and their long flag aliases) are mutually exclusive. Only one can be specified at a time.
+**-h** or **--help**
+    Displays help about using this command.
+
+The **-q**, **-p**, **-t** and **-P** flags (and their long flag aliases) are mutually exclusive. Only one can be specified at a time.
 
 
 Example

doc_src/cmds/ulimit.rst

@@ -69,13 +69,16 @@ The following additional options are also understood by ``ulimit``:
 **-a** or **--all**
     Prints all current limits.
 
+**-h** or **--help**
+    Displays help about using this command.
+
 The ``fish`` implementation of ``ulimit`` should behave identically to the implementation in bash, except for these differences:
 
-- Fish ``ulimit`` supports GNU-style long options for all switches
+- Fish ``ulimit`` supports GNU-style long options for all switches.
 
-- Fish ``ulimit`` does not support the ``-p`` option for getting the pipe size. The bash implementation consists of a compile-time check that empirically guesses this number by writing to a pipe and waiting for SIGPIPE. Fish does not do this because it this method of determining pipe size is unreliable. Depending on bash version, there may also be further additional limits to set in bash that do not exist in fish.
+- Fish ``ulimit`` does not support the **-p** option for getting the pipe size. The bash implementation consists of a compile-time check that empirically guesses this number by writing to a pipe and waiting for SIGPIPE. Fish does not do this because it this method of determining pipe size is unreliable. Depending on bash version, there may also be further additional limits to set in bash that do not exist in fish.
 
-- Fish ``ulimit`` does not support getting or setting multiple limits in one command, except reporting all values using the ``-a`` switch
+- Fish ``ulimit`` does not support getting or setting multiple limits in one command, except reporting all values using the **-a** switch.
 
 
 Example

doc_src/cmds/vared.rst

@@ -15,6 +15,7 @@ Description
 
 ``vared`` is used to interactively edit the value of an environment variable. Array variables as a whole can not be edited using ``vared``, but individual list elements can.
 
+The **-h** or **--help** option displays help about using this command.
 
 Example
 -------

doc_src/cmds/wait.rst

@@ -23,6 +23,8 @@ If neither a pid nor a process name is specified, the command waits for all back
 
 If the **-n** or **--any** flag is provided, the command returns as soon as the first job completes. If it is not provided, it returns after all jobs complete.
 
+The **-h** or **--help** option displays help about using this command.
+
 Example
 -------
 

doc_src/cmds/while.rst

@@ -19,6 +19,8 @@ The exit status of the **while** loop is the exit status of the last iteration o
 
 You can use :ref:`and <cmd-and>` or :ref:`or <cmd-or>` for complex conditions. Even more complex control can be achieved with ``while true`` containing a :ref:`break <cmd-break>`.
 
+The **-h** or **--help** option displays help about using this command.
+
 Example
 -------