docs: Use :doc: role when linking to commands

This makes it so we link to the very top of the document instead of a
special anchor we manually include.

So clicking e.g. :doc:`string <cmds/string>` will link you to
cmds/string.html instead of cmds/string.html#cmd-string.

I would love to have a way to say "this document from the root of the
document path", but that doesn't appear to work, I tried
`/cmds/string`.

So we'll just have to use cmds/string in normal documents and plain
`string` from other commands.

doc_src/cmds/alias.rst

@@ -16,7 +16,7 @@ Synopsis
 Description
 -----------
 
-``alias`` is a simple wrapper for the ``function`` builtin, which creates a function wrapping a command. It has similar syntax to POSIX shell ``alias``. For other uses, it is recommended to define a :ref:`function <cmd-function>`.
+``alias`` is a simple wrapper for the ``function`` builtin, which creates a function wrapping a command. It has similar syntax to POSIX shell ``alias``. For other uses, it is recommended to define a :doc:`function <function>`.
 
 ``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``.
 
@@ -31,7 +31,7 @@ The following options are available:
     Displays help about using this command.
 
 **-s** or **--save**
-    Saves the function created by the alias into your fish configuration directory using :ref:`funcsave <cmd-funcsave>`.
+    Saves the function created by the alias into your fish configuration directory using :doc:`funcsave <funcsave>`.
 
 Example
 -------
@@ -55,6 +55,6 @@ The following code will create ``rmi``, which runs ``rm`` with additional argume
 See more
 --------
 
-1. The :ref:`function <cmd-function>` command this builds on.
+1. The :doc:`function <function>` command this builds on.
 2. :ref:`Functions <syntax-function>`.
 3. :ref:`Function wrappers <syntax-function-wrappers>`.

doc_src/cmds/and.rst

@@ -15,7 +15,7 @@ Description
 
 ``and`` is used to execute a command if the previous command was successful (returned a status of 0).
 
-``and`` statements may be used as part of the condition in an :ref:`while <cmd-while>` or :ref:`if <cmd-if>` block.
+``and`` statements may be used as part of the condition in an :doc:`while <while>` or :doc:`if <if>` block.
 
 ``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.
 
@@ -33,5 +33,5 @@ The following code runs the ``make`` command to build a program. If the build su
 See Also
 --------
 
-- :ref:`or <cmd-or>` command
-- :ref:`not <cmd-not>` command
+- :doc:`or <or>` command
+- :doc:`not <not>` command

doc_src/cmds/argparse.rst

@@ -98,7 +98,7 @@ Each option specification consists of:
 
 - Optionally a ``!`` followed by fish script to validate the value. Typically this will be a function to run. If the exit status is zero the value for the flag is valid. If non-zero the value is invalid. Any error messages should be written to stdout (not stderr). See the section on :ref:`Flag Value Validation <flag-value-validation>` for more information.
 
-See the :ref:`fish_opt <cmd-fish_opt>` command for a friendlier but more verbose way to create option specifications.
+See the :doc:`fish_opt <fish_opt>` command for a friendlier but more verbose way to create option specifications.
 
 If a flag is not seen when parsing the arguments then the corresponding _flag_X var(s) will not be set.
 

doc_src/cmds/bg.rst

@@ -17,7 +17,7 @@ Description
 
 A background job is executed simultaneously with fish, and does not have access to the keyboard. If no job is specified, the last job to be used is put in the background. If ``PID`` is specified, the jobs containing the specified process IDs are put in the background.
 
-For compatibility with other shells, job expansion syntax is supported for ``bg``. A PID of the format ``%1`` will be interpreted as the PID of job 1. Job numbers can be seen in the output of :ref:`jobs <cmd-jobs>`.
+For compatibility with other shells, job expansion syntax is supported for ``bg``. A PID of the format ``%1`` will be interpreted as the PID of job 1. Job numbers can be seen in the output of :doc:`jobs <jobs>`.
 
 When at least one of the arguments isn't a valid job specifier,
 ``bg`` will print an error without backgrounding anything.

doc_src/cmds/bind.rst

@@ -27,7 +27,7 @@ The generic key binding that matches if no other binding does can be set by spec
 
 If the ``-k`` switch is used, the name of a key (such as 'down', 'up' or 'backspace') is used instead of a sequence. The names used are the same as the corresponding curses variables, but without the 'key\_' prefix. (See ``terminfo(5)`` for more information, or use ``bind --key-names`` for a list of all available named keys). Normally this will print an error if the current ``$TERM`` entry doesn't have a given key, unless the ``-s`` switch is given.
 
-To find out what sequence a key combination sends, you can use :ref:`fish_key_reader <cmd-fish_key_reader>`.
+To find out what sequence a key combination sends, you can use :doc:`fish_key_reader <fish_key_reader>`.
 
 ``COMMAND`` can be any fish command, but it can also be one of a set of special input functions. These include functions for moving the cursor, operating on the kill-ring, performing tab completion, etc. Use ``bind --function-names`` for a complete list of these input functions.
 
@@ -261,7 +261,7 @@ The following special input functions are available:
     reexecutes the prompt functions and redraws the prompt (also ``force-repaint`` for backwards-compatibility)
 
 ``repaint-mode``
-    reexecutes the :ref:`fish_mode_prompt <cmd-fish_mode_prompt>` and redraws the prompt. This is useful for vi-mode. If no ``fish_mode_prompt`` exists or it prints nothing, it acts like a normal repaint.
+    reexecutes the :doc:`fish_mode_prompt <fish_mode_prompt>` and redraws the prompt. This is useful for vi-mode. If no ``fish_mode_prompt`` exists or it prints nothing, it acts like a normal repaint.
 
 ``self-insert``
     inserts the matching sequence into the command line

doc_src/cmds/block.rst

@@ -14,7 +14,7 @@ Synopsis
 Description
 -----------
 
-``block`` prevents events triggered by ``fish`` or the :ref:`emit <cmd-emit>` command from being delivered and acted upon while the block is in place.
+``block`` prevents events triggered by ``fish`` or the :doc:`emit <emit>` command from being delivered and acted upon while the block is in place.
 
 In functions, ``block`` can be useful while performing work that should not be interrupted by the shell.
 

doc_src/cmds/break.rst

@@ -17,7 +17,7 @@ Synopsis
 Description
 -----------
 
-``break`` halts a currently running loop (*LOOP_CONSTRUCT*), such as a :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 :doc:`for <for>` or :doc:`while <while>` loop. It is usually added inside of a conditional block such as an :doc:`if <if>` block.
 
 There are no parameters for ``break``.
 
@@ -37,4 +37,4 @@ The following code searches all .c files for "smurf", and halts at the first occ
 See Also
 --------
 
-- the :ref:`continue <cmd-continue>` command, to skip the remainder of the current iteration of the current inner loop
+- the :doc:`continue <continue>` command, to skip the remainder of the current iteration of the current inner loop

doc_src/cmds/cd.rst

@@ -22,7 +22,7 @@ It is recommended to keep **.** as the first element of :envvar:`CDPATH`, or :en
 Fish will also try to change directory if given a command that looks like a directory (starting with **.**, **/** or **~**, or ending with **/**), without explicitly requiring **cd**.
 
 Fish also ships a wrapper function around the builtin **cd** that understands ``cd -`` as changing to the previous directory.
-See also :ref:`prevd <cmd-prevd>`.
+See also :doc:`prevd <prevd>`.
 This wrapper function maintains a history of the 25 most recently visited directories in the ``$dirprev`` and ``$dirnext`` global variables.
 If you make those universal variables your **cd** history is shared among all fish instances.
 

doc_src/cmds/cdh.rst

@@ -25,6 +25,6 @@ If you make those universal variables, your ``cd`` history is shared among all f
 See Also
 --------
 
-- the :ref:`dirh <cmd-dirh>` command to print the directory history
-- the :ref:`prevd <cmd-prevd>` command to move backward
-- the :ref:`nextd <cmd-nextd>` command to move forward
+- the :doc:`dirh <dirh>` command to print the directory history
+- the :doc:`prevd <prevd>` command to move backward
+- the :doc:`nextd <nextd>` command to move forward

doc_src/cmds/commandline.rst

@@ -29,7 +29,7 @@ The following options are available:
 **-f** or **--function**
     Causes any additional arguments to be interpreted as input functions, and puts them into the queue, so that they will be read before any additional actual key presses are.
     This option cannot be combined with any other option.
-    See :ref:`bind <cmd-bind>` for a list of input functions.
+    See :doc:`bind <bind>` for a list of input functions.
 
 **-h** or **--help**
     Displays help about using this command.

doc_src/cmds/continue.rst

@@ -13,7 +13,7 @@ Synopsis
 Description
 -----------
 
-``continue`` skips the remainder of the current iteration of the current inner loop, such as a :ref:`for <cmd-for>` loop or a :ref:`while <cmd-while>` loop. It is usually added inside of a conditional block such as an :ref:`if <cmd-if>` statement or a :ref:`switch <cmd-switch>` statement.
+``continue`` skips the remainder of the current iteration of the current inner loop, such as a :doc:`for <for>` loop or a :doc:`while <while>` loop. It is usually added inside of a conditional block such as an :doc:`if <if>` statement or a :doc:`switch <switch>` statement.
 
 Example
 -------
@@ -35,4 +35,4 @@ The following code removes all tmp files that do not contain the word smurf.
 See Also
 --------
 
-- the :ref:`break <cmd-break>` command, to stop the current inner loop
+- the :doc:`break <break>` command, to stop the current inner loop

doc_src/cmds/dirh.rst

@@ -17,11 +17,11 @@ Description
 
 ``dirh`` does not accept any parameters.
 
-Note that the :ref:`cd <cmd-cd>` command limits directory history to the 25 most recently visited directories. The history is stored in the ``$dirprev`` and ``$dirnext`` variables.
+Note that the :doc:`cd <cd>` command limits directory history to the 25 most recently visited directories. The history is stored in the ``$dirprev`` and ``$dirnext`` variables.
 
 See Also
 --------
 
-- the :ref:`cdh <cmd-cdh>` command to display a prompt to quickly navigate the history
-- the :ref:`prevd <cmd-prevd>` command to move backward
-- the :ref:`nextd <cmd-nextd>` command to move forward
+- the :doc:`cdh <cdh>` command to display a prompt to quickly navigate the history
+- the :doc:`prevd <prevd>` command to move backward
+- the :doc:`nextd <nextd>` command to move forward

doc_src/cmds/dirs.rst

@@ -13,7 +13,7 @@ Synopsis
 Description
 -----------
 
-``dirs`` prints the current :ref:`directory stack <directory-stack>`, as created by :ref:`pushd <cmd-pushd>` and modified by :ref:`popd <cmd-popd>`.
+``dirs`` prints the current :ref:`directory stack <directory-stack>`, as created by :doc:`pushd <pushd>` and modified by :doc:`popd <popd>`.
 
 The following options are available:
 
@@ -28,4 +28,4 @@ The following options are available:
 See Also
 --------
 
-- the :ref:`cdh <cmd-cdh>` command, which provides a more intuitive way to navigate to recently visited directories.
+- the :doc:`cdh <cdh>` command, which provides a more intuitive way to navigate to recently visited directories.

doc_src/cmds/disown.rst

@@ -17,9 +17,9 @@ Description
 
 Jobs in the list of jobs are sent a hang-up signal when fish terminates, which usually causes the job to terminate; ``disown`` allows these processes to continue regardless.
 
-If no process is specified, the most recently-used job is removed (like :ref:`bg <cmd-bg>` and :ref:`fg <cmd-fg>`).  If one or more PIDs are specified, jobs with the specified process IDs are removed from the job list. Invalid jobs are ignored and a warning is printed.
+If no process is specified, the most recently-used job is removed (like :doc:`bg <bg>` and :doc:`fg <fg>`).  If one or more PIDs are specified, jobs with the specified process IDs are removed from the job list. Invalid jobs are ignored and a warning is printed.
 
-If a job is stopped, it is sent a signal to continue running, and a warning is printed. It is not possible to use the :ref:`bg <cmd-bg>` builtin to continue a job once it has been disowned.
+If a job is stopped, it is sent a signal to continue running, and a warning is printed. It is not possible to use the :doc:`bg <bg>` builtin to continue a job once it has been disowned.
 
 ``disown`` returns 0 if all specified jobs were disowned successfully, and 1 if any problems were encountered.
 
@@ -30,4 +30,4 @@ Example
 
 ``firefox &; disown`` will start the Firefox web browser in the background and remove it from the job list, meaning it will not be closed when the fish process is closed.
 
-``disown (jobs -p)`` removes all :ref:`jobs <cmd-jobs>` from the job list without terminating them.
+``disown (jobs -p)`` removes all :doc:`jobs <jobs>` from the job list without terminating them.

doc_src/cmds/echo.rst

@@ -78,4 +78,4 @@ Example
 See Also
 --------
 
-- the :ref:`printf <cmd-printf>` command, for more control over output formatting
+- the :doc:`printf <printf>` command, for more control over output formatting

doc_src/cmds/else.rst

@@ -13,7 +13,7 @@ Synopsis
 Description
 -----------
 
-:ref:`if <cmd-if>` will execute the command *CONDITION**.
+:doc:`if <if>` will execute the command *CONDITION**.
 If the condition's exit status is 0, the commands *COMMANDS_TRUE* will execute.
 If it is not 0 and **else** is given, *COMMANDS_FALSE* will be executed.
 

doc_src/cmds/end.rst

@@ -25,10 +25,10 @@ Description
 
 The **end** keyword ends a block of commands started by one of the following commands:
 
-- :ref:`begin <cmd-begin>` to start a block of commands
-- :ref:`function <cmd-function>` to define a function
-- :ref:`if <cmd-if>`, :ref:`switch <cmd-switch>` to conditionally execute commands
-- :ref:`while <cmd-while>`, :ref:`for <cmd-for>` to perform commands multiple times
+- :doc:`begin <begin>` to start a block of commands
+- :doc:`function <function>` to define a function
+- :doc:`if <if>`, :doc:`switch <switch>` to conditionally execute commands
+- :doc:`while <while>`, :doc:`for <for>` to perform commands multiple times
 
 The **end** keyword does not change the current exit status.
 Instead, the status after it will be the status returned by the most recent command.

doc_src/cmds/eval.rst

@@ -15,7 +15,7 @@ Description
 **eval** evaluates the specified parameters as a command.
 If more than one parameter is specified, all parameters will be joined using a space character as a separator.
 
-If the command does not need access to stdin, consider using :ref:`source <cmd-source>` instead.
+If the command does not need access to stdin, consider using :doc:`source <source>` instead.
 
 If no piping or other compound shell constructs are required, variable-expansion-as-command, as in  ``set cmd ls -la; $cmd``, is also an option.
 

doc_src/cmds/exit.rst

@@ -17,6 +17,6 @@ Description
 **exit** is a special builtin that causes the shell to exit. Either 255 or the *CODE* supplied is used, whichever is lesser.
 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.
+If exit is called while sourcing a file (using the :doc:`source <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/false.rst

@@ -18,5 +18,5 @@ Description
 See Also
 --------
 
-- :ref:`true <cmd-true>` command
+- :doc:`true <true>` command
 - :ref:`$status <variables-status>` variable

doc_src/cmds/fg.rst

@@ -19,7 +19,7 @@ If no job is specified, the last job to be used is put in the foreground.
 If ``PID`` is specified, the job containing a process with the specified process ID is put in the foreground.
 
 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>`.
+Job numbers can be seen in the output of :doc:`jobs <jobs>`.
 
 The **--help** or **-h** option displays help about using this command.
 

doc_src/cmds/fish_add_path.rst

@@ -20,7 +20,7 @@ Description
 
 It is (by default) safe to use :program:`fish_add_path` in config.fish, or it can be used once, interactively, and the paths will stay in future because of :ref:`universal variables <variables-universal>`. This is a "do what I mean" style command, if you need more control, consider modifying the variable yourself.
 
-Components are normalized by :ref:`realpath <cmd-realpath>`. Trailing slashes are ignored and relative paths are made absolute (but symlinks are not resolved). If a component already exists, it is not added again and stays in the same place unless the ``--move`` switch is given.
+Components are normalized by :doc:`realpath <realpath>`. Trailing slashes are ignored and relative paths are made absolute (but symlinks are not resolved). If a component already exists, it is not added again and stays in the same place unless the ``--move`` switch is given.
 
 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 :envvar:`PATH`, so they still stay ahead of the system paths).
 
@@ -50,7 +50,7 @@ Options
     Move already-existing components to the place they would be added - by default they would be left in place and not added again.
 
 **-v** or **--verbose**
-    Print the :ref:`set <cmd-set>` command used.
+    Print the :doc:`set <set>` command used.
 
 **-n** or **--dry-run**
     Print the ``set`` command that would be used without executing it.

doc_src/cmds/fish_breakpoint_prompt.rst

@@ -20,7 +20,7 @@ Synopsis
 Description
 -----------
 
-``fish_breakpoint_prompt`` is the prompt function when asking for input in response to a :ref:`breakpoint <cmd-breakpoint>` command.
+``fish_breakpoint_prompt`` is the prompt function when asking for input in response to a :doc:`breakpoint <breakpoint>` command.
 
 The exit status of commands within ``fish_breakpoint_prompt`` will not modify the value of :ref:`$status <variables-status>` outside of the ``fish_breakpoint_prompt`` function.
 

doc_src/cmds/fish_config.rst

@@ -27,7 +27,7 @@ Available subcommands for the ``prompt`` command:
 
 - ``choose`` loads a sample prompt in the current session.
 - ``list`` lists the names of the available sample prompts.
-- ``save`` saves the current prompt to a file (via :ref:`funcsave <cmd-funcsave>`).
+- ``save`` saves the current prompt to a file (via :doc:`funcsave <funcsave>`).
 - ``show`` shows what the given sample prompts (or all) would look like.
 
 With the ``theme`` command ``fish_config`` can be used to view and choose a theme (meaning a color scheme) inside the terminal.

doc_src/cmds/fish_git_prompt.rst

@@ -24,7 +24,7 @@ The ``fish_git_prompt`` function displays information about the current git repo
 
 `Git <https://git-scm.com>`_ must be installed.
 
-There are numerous customization options, which can be controlled with git options or fish variables. git options, where available, take precedence over the fish variable with the same function. git options can be set on a per-repository or global basis. git options can be set with the ``git config`` command, while fish variables can be set as usual with the :ref:`set <cmd-set>` command.
+There are numerous customization options, which can be controlled with git options or fish variables. git options, where available, take precedence over the fish variable with the same function. git options can be set on a per-repository or global basis. git options can be set with the ``git config`` command, while fish variables can be set as usual with the :doc:`set <set>` command.
 
 - ``$__fish_git_prompt_show_informative_status`` or the git option ``bash.showInformativeStatus`` can be set to enable the "informative" display, which will show a large amount of information - the number of dirty files, unpushed/unpulled commits, and more.
   In large repositories, this can take a lot of time, so you may wish to disable it in these repositories with  ``git config --local bash.showInformativeStatus false``. It also changes the characters the prompt uses to less plain ones (``✚`` instead of ``*`` for the dirty state for example) , and if you are only interested in that, set ``$__fish_git_prompt_use_informative_chars`` instead.
@@ -121,7 +121,7 @@ Colors used with ``showcolorhints``:
 
 Note that all colors can also have a corresponding ``_done`` color. For example, the contents of ``$__fish_git_prompt_color_upstream_done`` is printed right _after_ the upstream.
 
-See also :ref:`fish_vcs_prompt <cmd-fish_vcs_prompt>`, which will call all supported version control prompt functions, including git, Mercurial and Subversion.
+See also :doc:`fish_vcs_prompt <fish_vcs_prompt>`, which will call all supported version control prompt functions, including git, Mercurial and Subversion.
 
 Example
 --------

doc_src/cmds/fish_hg_prompt.rst

@@ -51,7 +51,7 @@ The status symbols themselves:
 
 Finally, ``$fish_prompt_hg_status_order``, which can be used to change the order the status symbols appear in. It defaults to ``added modified copied deleted untracked unmerged``.
 
-See also :ref:`fish_vcs_prompt <cmd-fish_vcs_prompt>`, which will call all supported version control prompt functions, including git, Mercurial and Subversion.
+See also :doc:`fish_vcs_prompt <fish_vcs_prompt>`, which will call all supported version control prompt functions, including git, Mercurial and Subversion.
 
 Example
 -------

doc_src/cmds/fish_indent.rst

@@ -38,7 +38,7 @@ The following options are available:
     Outputs HTML, which supports syntax highlighting if the appropriate CSS is defined. The CSS class names are the same as the variable names, such as ``fish_color_command``.
 
 **-d** or **--debug=DEBUG_CATEGORIES**
-    Enable debug output and specify a pattern for matching debug categories. See :ref:`Debugging <debugging-fish>` in :ref:`fish <cmd-fish>` (1) for details.
+    Enable debug output and specify a pattern for matching debug categories. See :ref:`Debugging <debugging-fish>` in :doc:`fish <fish>` (1) for details.
 
 **-o** or **--debug-output=DEBUG_FILE**
     Specify a file path to receive the debug output, including categories and ``fish_trace``. The default is standard error.

doc_src/cmds/fish_key_reader.rst

@@ -13,7 +13,7 @@ Synopsis
 Description
 -----------
 
-: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.
+:program:`fish_key_reader` is used to explain how you would bind a certain key sequence. By default, it prints the :doc:`bind <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 standard error.
 

doc_src/cmds/fish_mode_prompt.rst

@@ -29,7 +29,7 @@ You can also define an empty ``fish_mode_prompt`` function to remove the Vi mode
     function fish_mode_prompt; end
     funcsave fish_mode_prompt
 
-``fish_mode_prompt`` will be executed when the vi mode changes. If it produces any output, it is displayed and used. If it does not, the other prompt functions (:ref:`fish_prompt <cmd-fish_prompt>` and :ref:`fish_right_prompt <cmd-fish_right_prompt>`) will be executed as well in case they contain a mode display.
+``fish_mode_prompt`` will be executed when the vi mode changes. If it produces any output, it is displayed and used. If it does not, the other prompt functions (:doc:`fish_prompt <fish_prompt>` and :doc:`fish_right_prompt <fish_right_prompt>`) will be executed as well in case they contain a mode display.
 
 Example
 -------

doc_src/cmds/fish_opt.rst

@@ -14,7 +14,7 @@ Synopsis
 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 specifications 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 :doc:`argparse <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:
 

doc_src/cmds/fish_svn_prompt.rst

@@ -67,7 +67,7 @@ A number of variables control the symbol ("display") and color ("color") for the
 - :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.
+See also :doc:`fish_vcs_prompt <fish_vcs_prompt>`, which will call all supported version control prompt functions, including git, Mercurial and Subversion.
 
 Example
 -------

doc_src/cmds/fish_vcs_prompt.rst

@@ -23,13 +23,13 @@ The ``fish_vcs_prompt`` function displays information about the current version
 
 It calls out to VCS-specific functions. The currently supported systems are:
 
-- :ref:`fish_git_prompt <cmd-fish_git_prompt>`
-- :ref:`fish_hg_prompt <cmd-fish_hg_prompt>`
-- :ref:`fish_svn_prompt <cmd-fish_svn_prompt>`
+- :doc:`fish_git_prompt <fish_git_prompt>`
+- :doc:`fish_hg_prompt <fish_hg_prompt>`
+- :doc:`fish_svn_prompt <fish_svn_prompt>`
 
 If a VCS isn't installed, the respective function does nothing.
 
-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>`.
+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 :doc:`funced <funced>`.
 
 For more information, see the documentation for each of the functions above.
 

doc_src/cmds/for.rst

@@ -15,7 +15,7 @@ Description
 
 **for** is a loop construct. It will perform the commands specified by *COMMANDS* multiple times. On each iteration, the local variable specified by *VARNAME* is assigned a new value from *VALUES*. If *VALUES* is empty, *COMMANDS* will not be executed at all. The *VARNAME* is visible when the loop terminates and will contain the last value assigned to it. If *VARNAME* does not already exist it will be set in the local scope. For our purposes if the **for** block is inside a function there must be a local variable with the same name. If the **for** block is not nested inside a function then global and universal variables of the same name will be used if they exist.
 
-Much like :ref:`set <cmd-set>`, **for** does not modify $status, but the evaluation of its subordinate commands can.
+Much like :doc:`set <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.
 

doc_src/cmds/funced.rst

@@ -48,4 +48,4 @@ When you're done, use::
 
   >_ funcsave fish_prompt
 
-For more, see :ref:`funcsave <cmd-funcsave>`.
+For more, see :doc:`funcsave <funcsave>`.

doc_src/cmds/funcsave.rst

@@ -17,8 +17,8 @@ Description
 
 ``funcsave`` saves a function to a file in the fish configuration directory. This function will be :ref:`automatically loaded <syntax-function-autoloading>` by current and future fish sessions. This can be useful to commit functions created interactively for permanent use.
 
-If you have erased a function using :ref:`functions <cmd-functions>`'s ``--erase`` option, ``funcsave`` will remove the saved function definition.
+If you have erased a function using :doc:`functions <functions>`'s ``--erase`` option, ``funcsave`` will remove the saved function definition.
 
 Because fish loads functions on-demand, saved functions cannot serve as :ref:`event handlers <event>` until they are run or otherwise sourced. To activate an event handler for every new shell, add the function to the :ref:`configuration file <configuration>` instead of using ``funcsave``.
 
-This is often used after :ref:`funced <cmd-funced>`, which opens the function in ``$EDITOR`` or ``$VISUAL`` and loads it into the current session afterwards.
+This is often used after :doc:`funced <funced>`, which opens the function in ``$EDITOR`` or ``$VISUAL`` and loads it into the current session afterwards.

doc_src/cmds/function.rst

@@ -27,10 +27,10 @@ The following options are available:
     A description of what the function does, suitable as a completion description.
 
 **-w** *WRAPPED_COMMAND* or **--wraps** *WRAPPED_COMMAND*
-    Inherit completions from the given *WRAPPED_COMMAND*. See the documentation for :ref:`complete <cmd-complete>` for more information.
+    Inherit completions from the given *WRAPPED_COMMAND*. See the documentation for :doc:`complete <complete>` for more information.
 
 **-e** *EVENT_NAME* or **--on-event** *EVENT_NAME*
-    Run this function when the specified named event is emitted. Fish internally generates named events, for example,when showing the prompt. Custom events can be emitted using the :ref:`emit <cmd-emit>` command.
+    Run this function when the specified named event is emitted. Fish internally generates named events, for example,when showing the prompt. Custom events can be emitted using the :doc:`emit <emit>` command.
 
 **-v** *VARIABLE_NAME* or **--on-variable** *VARIABLE_NAME*
     Run this function when the variable *VARIABLE_NAME* changes value. Note that :program:`fish` makes no guarantees on any particular timing or even that the function will be run for every single ``set``. Rather it will be run when the variable has been set at least once, possibly skipping some values or being run when the variable has been set to the same value (except for universal variables set in other shells - only changes in the value will be picked up for those).
@@ -54,7 +54,7 @@ The following options are available:
 
 If the user enters any additional arguments after the function, they are inserted into the environment :ref:`variable list <variables-lists>` ``$argv``. If the ``--argument-names`` option is provided, the arguments are also assigned to names specified in that option.
 
-By using one of the event handler switches, a function can be made to run automatically at specific events. The user may generate new events using the :ref:`emit <cmd-emit>` builtin. Fish generates the following named events:
+By using one of the event handler switches, a function can be made to run automatically at specific events. The user may generate new events using the :doc:`emit <emit>` builtin. Fish generates the following named events:
 
 - ``fish_prompt``, which is emitted whenever a new fish prompt is about to be displayed.
 

doc_src/cmds/functions.rst

@@ -31,10 +31,10 @@ The following options are available:
     Changes the description of this function.
 
 **-e** or **--erase**
-    Causes the specified functions to be erased. This also means that it is prevented from autoloading in the current session. Use :ref:`funcsave <cmd-funcsave>` to remove the saved copy.
+    Causes the specified functions to be erased. This also means that it is prevented from autoloading in the current session. Use :doc:`funcsave <funcsave>` to remove the saved copy.
 
 **-D** or **--details**
-    Reports the path name where the specified function is defined or could be autoloaded, ``stdin`` if the function was defined interactively or on the command line or by reading standard input, **-** if the function was created via :ref:`source <cmd-source>`, and ``n/a`` if the function isn't available. (Functions created via :ref:`alias <cmd-alias>` will return **-**, because ``alias`` uses ``source`` internally.) If the **--verbose** option is also specified then five lines are written:
+    Reports the path name where the specified function is defined or could be autoloaded, ``stdin`` if the function was defined interactively or on the command line or by reading standard input, **-** if the function was created via :doc:`source <source>`, and ``n/a`` if the function isn't available. (Functions created via :doc:`alias <alias>` will return **-**, because ``alias`` uses ``source`` internally.) If the **--verbose** option is also specified then five lines are written:
 
     - the pathname as already described,
     - ``autoloaded``, ``not-autoloaded`` or ``n/a``,

doc_src/cmds/help.rst

@@ -27,7 +27,7 @@ This variable may be set as a list, where the first element is the browser comma
 Example
 -------
 
-``help fg`` shows the documentation for the :ref:`fg <cmd-fg>` builtin.
+``help fg`` shows the documentation for the :doc:`fg <fg>` builtin.
 
 Notes
 -----

doc_src/cmds/if.rst

@@ -16,9 +16,9 @@ Synopsis
 Description
 -----------
 
-``if`` will execute the command ``CONDITION``. If the condition's exit status is 0, the commands ``COMMANDS_TRUE`` will execute.  If the exit status is not 0 and :ref:`else <cmd-else>` is given, ``COMMANDS_FALSE`` will be executed.
+``if`` will execute the command ``CONDITION``. If the condition's exit status is 0, the commands ``COMMANDS_TRUE`` will execute.  If the exit status is not 0 and :doc:`else <else>` is given, ``COMMANDS_FALSE`` will be executed.
 
-You can use :ref:`and <cmd-and>` or :ref:`or <cmd-or>` in the condition. See the second example below.
+You can use :doc:`and <and>` or :doc:`or <or>` in the condition. See the second example below.
 
 The exit status of the last foreground command to exit can always be accessed using the :ref:`$status <variables-status>` variable.
 

doc_src/cmds/nextd.rst

@@ -41,6 +41,6 @@ Example
 See Also
 --------
 
-- the :ref:`cdh <cmd-cdh>` command to display a prompt to quickly navigate the history
-- the :ref:`dirh <cmd-dirh>` command to print the directory history
-- the :ref:`prevd <cmd-prevd>` command to move backward
+- the :doc:`cdh <cdh>` command to display a prompt to quickly navigate the history
+- the :doc:`dirh <dirh>` command to print the directory history
+- the :doc:`prevd <prevd>` command to move backward

doc_src/cmds/or.rst

@@ -15,7 +15,7 @@ Description
 
 ``or`` is used to execute a command if the previous command was not successful (returned a status of something other than 0).
 
-``or`` statements may be used as part of the condition in an :ref:`and <cmd-if>` or :ref:`while <cmd-while>` block.
+``or`` statements may be used as part of the condition in an :doc:`if <if>` or :doc:`while <while>` block.
 
 ``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.
 
@@ -33,4 +33,4 @@ The following code runs the ``make`` command to build a program. If the build su
 See Also
 --------
 
-- :ref:`and <cmd-and>` command
+- :doc:`and <and>` command

doc_src/cmds/path.rst

@@ -247,7 +247,7 @@ Examples
 
 With ``--relative`` (or ``-R``), it prints the number of seconds since the modification time. It only reads the current time once at start, so in case multiple paths are given the times are all relative to the *start* of ``path mtime -R`` running.
 
-If you want to know if a file is newer or older than another file, consider using ``test -nt`` instead. See :ref:`the test documentation <cmd-test>`.
+If you want to know if a file is newer or older than another file, consider using ``test -nt`` instead. See :doc:`the test documentation <test>`.
 
 It returns 0 if reading mtime for any path succeeded.
 

doc_src/cmds/popd.rst

@@ -13,7 +13,7 @@ Synopsis
 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.
+``popd`` removes the top directory from the :ref:`directory stack <directory-stack>` and changes the working directory to the new top directory. Use :doc:`pushd <pushd>` to add directories to the stack.
 
 The **-h** or **--help** option displays help about using this command.
 
@@ -37,5 +37,5 @@ Example
 See Also
 --------
 
-- the :ref:`dirs <cmd-dirs>` command to print the directory stack
-- the :ref:`cdh <cmd-cdh>` command which provides a more intuitive way to navigate to recently visited directories.
+- the :doc:`dirs <dirs>` command to print the directory stack
+- the :doc:`cdh <cdh>` command which provides a more intuitive way to navigate to recently visited directories.

doc_src/cmds/prevd.rst

@@ -41,6 +41,6 @@ Example
 See Also
 --------
 
-- the :ref:`cdh <cmd-cdh>` command to display a prompt to quickly navigate the history
-- the :ref:`dirh <cmd-dirh>` command to print the directory history
-- the :ref:`nextd <cmd-nextd>` command to move forward
+- the :doc:`cdh <cdh>` command to display a prompt to quickly navigate the history
+- the :doc:`dirh <dirh>` command to print the directory history
+- the :doc:`nextd <nextd>` command to move forward

doc_src/cmds/printf.rst

@@ -23,7 +23,7 @@ Description
 
 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.
+Unlike :doc:`echo <echo>`, ``printf`` does not append a new line unless it is specified as part of the string.
 
 It doesn't support any options, so there is no need for a ``--`` separator, which makes it easier to use for arbitrary input than ``echo``. [#]_ 
 
@@ -99,7 +99,7 @@ Will print "Number of bananas in my pocket: 42", `without` a newline.
 See Also
 --------
 
-- the :ref:`echo <cmd-echo>` command, for simpler output
+- the :doc:`echo <echo>` command, for simpler output
 
 Footnotes
 ---------

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. :doc:`popd <popd>` will pop it off and return to the original directory.
 
 Without arguments, it exchanges the top two directories in the stack.
 
@@ -49,5 +49,5 @@ Example
 See Also
 --------
 
-- the :ref:`dirs <cmd-dirs>` command to print the directory stack
-- the :ref:`cdh <cmd-cdh>` command which provides a more intuitive way to navigate to recently visited directories.
+- the :doc:`dirs <dirs>` command to print the directory stack
+- the :doc:`cdh <cdh>` command which provides a more intuitive way to navigate to recently visited directories.

doc_src/cmds/read.rst

@@ -42,7 +42,7 @@ The following options are available:
     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 :ref:`echo <cmd-echo>` command.
+    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.
 
 **-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.

doc_src/cmds/realpath.rst

@@ -20,7 +20,7 @@ Description
           To see the documentation on the ``realpath`` command you might have,
           use ``command man realpath``.
 
-:program:`realpath` follows all symbolic links encountered for the provided :envvar:`PATH`, printing the absolute path resolved. :ref:`fish <cmd-fish>` provides a :command:`realpath`-alike builtin intended to enrich systems where no such command is installed by default.
+:program:`realpath` follows all symbolic links encountered for the provided :envvar:`PATH`, printing the absolute path resolved. :doc:`fish <fish>` provides a :command:`realpath`-alike builtin intended to enrich systems where no such command is installed by default.
 
 If a :command:`realpath` command exists, that will be preferred.
 ``builtin realpath`` will explicitly use the fish implementation of :command:`realpath`.

doc_src/cmds/return.rst

@@ -18,9 +18,9 @@ Description
 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.
+It is often added inside of a conditional block such as an :doc:`if <if>` statement or a :doc:`switch <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.
 
-If at the top level of a script, it exits with the given status, like :ref:`exit <cmd-exit>`.
+If at the top level of a script, it exits with the given status, like :doc:`exit <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.

doc_src/cmds/status.rst

@@ -43,7 +43,7 @@ The following operations (subcommands) are available:
     Returns 0 if fish is currently executing a block of code.
 
 **is-breakpoint**
-    Returns 0 if fish is currently showing a prompt in the context of a :ref:`breakpoint <cmd-breakpoint>` command. See also the :ref:`fish_breakpoint_prompt <cmd-fish_breakpoint_prompt>` function.
+    Returns 0 if fish is currently showing a prompt in the context of a :doc:`breakpoint <breakpoint>` command. See also the :doc:`fish_breakpoint_prompt <fish_breakpoint_prompt>` function.
 
 **is-interactive**, **-i** or **--is-interactive**
     Returns 0 if fish is interactive - that is, connected to a keyboard.
@@ -64,7 +64,7 @@ The following operations (subcommands) are available:
     Prints the name of the currently-running function or command, like the deprecated :envvar:`_` variable.
 
 **filename**, **current-filename**, **-f** or **--current-filename**
-    Prints the filename of the currently-running script. If the current script was called via a symlink, this will return the symlink. If the current script was received by piping into :ref:`source <cmd-source>`, then this will return ``-``.
+    Prints the filename of the currently-running script. If the current script was called via a symlink, this will return the symlink. If the current script was received by piping into :doc:`source <source>`, then this will return ``-``.
 
 **basename**
     Prints just the filename of the running script, without any path components before.

doc_src/cmds/string-pad.rst

@@ -53,8 +53,8 @@ Examples
 See Also
 --------
 
-- The :ref:`printf <cmd-printf>` command can do simple padding, for example ``printf %10s\n`` works like ``string pad -w10``.
+- The :doc:`printf <printf>` command can do simple padding, for example ``printf %10s\n`` works like ``string pad -w10``.
 
-- :ref:`string length <cmd-string-length>` with the ``--visible`` option can be used to show what fish thinks the width is.
+- :doc:`string length <string-length>` with the ``--visible`` option can be used to show what fish thinks the width is.
 
 .. END EXAMPLES

doc_src/cmds/string-shorten.rst

@@ -82,8 +82,8 @@ See Also
 
 - :ref:`string<cmd-string>`'s ``pad`` subcommand does the inverse of this command, adding padding to a specific width instead.
   
-- The :ref:`printf <cmd-printf>` command can do simple padding, for example ``printf %10s\n`` works like ``string pad -w10``.
+- The :doc:`printf <printf>` command can do simple padding, for example ``printf %10s\n`` works like ``string pad -w10``.
 
-- :ref:`string length <cmd-string-length>` with the ``--visible`` option can be used to show what fish thinks the width is.
+- :doc:`string length <string-length>` with the ``--visible`` option can be used to show what fish thinks the width is.
 
 .. END EXAMPLES

doc_src/cmds/string-split.rst

@@ -24,7 +24,7 @@ Description
 
 Use **-f** or **--fields** to print out specific fields. FIELDS is a comma-separated string of field numbers and/or spans. Each field is one-indexed, and will be printed on separate lines. If a given field does not exist, then the command exits with status 1 and does not print anything, unless **--allow-empty** is used.
 
-See also the **--delimiter** option of the :ref:`read <cmd-read>` command.
+See also the **--delimiter** option of the :doc:`read <read>` command.
 
 ``string split0`` splits each *STRING* on the zero byte (NUL). Options are the same as ``string split`` except that no separator is given.
 

doc_src/cmds/switch.rst

@@ -19,7 +19,7 @@ Each ``case`` command is given one or more parameters. The first ``case`` comman
 
 Note that fish does not fall through on case statements. Only the first matching case is executed.
 
-Note that :ref:`break <cmd-break>` cannot be used to exit a case/switch block early like in other languages. It can only be used in loops.
+Note that :doc:`break <break>` cannot be used to exit a case/switch block early like in other languages. It can only be used in loops.
 
 Note that command substitutions in a case statement will be evaluated even if its body is not taken. All substitutions, including command substitutions, must be performed before the value can be compared against the parameter.
 

doc_src/cmds/true.rst

@@ -20,5 +20,5 @@ Description
 See Also
 --------
 
-- :ref:`false <cmd-false>` command
+- :doc:`false <false>` command
 - :ref:`$status <variables-status>` variable

doc_src/cmds/while.rst

@@ -17,7 +17,7 @@ Description
 
 The exit status of the **while** loop is the exit status of the last iteration of the ``COMMANDS`` executed, or 0 if none were executed. (This matches other shells and is POSIX-compatible.)
 
-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>`.
+You can use :doc:`and <and>` or :doc:`or <or>` for complex conditions. Even more complex control can be achieved with ``while true`` containing a :doc:`break <break>`.
 
 The **-h** or **--help** option displays help about using this command.