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.
 

doc_src/commands.rst

@@ -12,77 +12,77 @@ Keywords
 
 Core language keywords that make up the syntax, like
 
-- :ref:`if <cmd-if>` for conditions.
-- :ref:`for <cmd-for>` and :ref:`while <cmd-while>` for loops.
-- :ref:`break <cmd-break>` and :ref:`continue <cmd-continue>` to control loops.
-- :ref:`function <cmd-function>` to define functions.
-- :ref:`return <cmd-return>` to return a status from a function.
-- :ref:`begin <cmd-begin>` to begin a block and :ref:`end <cmd-end>` to end any block (including ifs and loops).
-- :ref:`and <cmd-and>`, :ref:`or <cmd-or>` and :ref:`not <cmd-not>` to combine commands logically.
-- :ref:`switch <cmd-switch>` and :ref:`case <cmd-case>` to make multiple blocks depending on the value of a variable.
+- :doc:`if <cmds/if>` for conditions.
+- :doc:`for <cmds/for>` and :doc:`while <cmds/while>` for loops.
+- :doc:`break <cmds/break>` and :doc:`continue <cmds/continue>` to control loops.
+- :doc:`function <cmds/function>` to define functions.
+- :doc:`return <cmds/return>` to return a status from a function.
+- :doc:`begin <cmds/begin>` to begin a block and :doc:`end <cmds/end>` to end any block (including ifs and loops).
+- :doc:`and <cmds/and>`, :doc:`or <cmds/or>` and :doc:`not <cmds/not>` to combine commands logically.
+- :doc:`switch <cmds/switch>` and :doc:`case <cmds/case>` to make multiple blocks depending on the value of a variable.
 
 Decorations
 ^^^^^^^^^^^
 
-Command decorations are keywords like :ref:`command <cmd-command>` or :ref:`builtin <cmd-builtin>` to tell fish what sort of thing to execute, and :ref:`time <cmd-time>` to time its execution. :ref:`exec <cmd-exec>` tells fish to replace itself with the command.
+Command decorations are keywords like :doc:`command <cmds/command>` or :doc:`builtin <cmds/builtin>` to tell fish what sort of thing to execute, and :doc:`time <cmds/time>` to time its execution. :doc:`exec <cmds/exec>` tells fish to replace itself with the command.
 
 Tools to do a task
 ^^^^^^^^^^^^^^^^^^
 
 Builtins to do a task, like
 
-- :ref:`cd <cmd-cd>` to change the current directory.
-- :ref:`echo <cmd-echo>` or :ref:`printf <cmd-printf>` to produce output.
-- :ref:`set <cmd-set>` to set, query or erase variables.
-- :ref:`read <cmd-read>` to read input.
-- :ref:`string <cmd-string>` for string manipulation.
-- :ref:`math <cmd-math>` does arithmetic.
-- :ref:`argparse <cmd-argparse>` to make arguments easier to handle.
-- :ref:`count <cmd-count>` to count arguments.
-- :ref:`type <cmd-type>` to find out what sort of thing (command, builtin or function) fish would call, or if it exists at all.
-- :ref:`test <cmd-test>` checks conditions like if a file exists or a string is empty.
-- :ref:`contains <cmd-contains>` to see if a list contains an entry.
-- :ref:`abbr <cmd-abbr>` manages :ref:`abbreviations`.
-- :ref:`eval <cmd-eval>` and :ref:`source <cmd-source>` to run fish code from a string or file.
-- :ref:`set_color <cmd-set_color>` to colorize your output.
-- :ref:`status <cmd-status>` to get shell information, like whether it's interactive or a login shell, or which file it is currently running.
-- :ref:`bind <cmd-bind>` to change bindings.
-- :ref:`commandline <cmd-commandline>` to get or change the commandline contents.
-- :ref:`fish_config <cmd-fish_config>` to easily change fish's configuration, like the prompt or colorscheme.
-- :ref:`random <cmd-random>` to generate random numbers or pick from a list.
+- :doc:`cd <cmds/cd>` to change the current directory.
+- :doc:`echo <cmds/echo>` or :doc:`printf <cmds/printf>` to produce output.
+- :doc:`set <cmds/set>` to set, query or erase variables.
+- :doc:`read <cmds/read>` to read input.
+- :doc:`string <cmds/string>` for string manipulation.
+- :doc:`math <cmds/math>` does arithmetic.
+- :doc:`argparse <cmds/argparse>` to make arguments easier to handle.
+- :doc:`count <cmds/count>` to count arguments.
+- :doc:`type <cmds/type>` to find out what sort of thing (command, builtin or function) fish would call, or if it exists at all.
+- :doc:`test <cmds/test>` checks conditions like if a file exists or a string is empty.
+- :doc:`contains <cmds/contains>` to see if a list contains an entry.
+- :doc:`abbr <cmds/abbr>` manages :ref:`abbreviations`.
+- :doc:`eval <cmds/eval>` and :doc:`source <cmds/source>` to run fish code from a string or file.
+- :doc:`set_color <cmds/set_color>` to colorize your output.
+- :doc:`status <cmds/status>` to get shell information, like whether it's interactive or a login shell, or which file it is currently running.
+- :doc:`bind <cmds/bind>` to change bindings.
+- :doc:`commandline <cmds/commandline>` to get or change the commandline contents.
+- :doc:`fish_config <cmds/fish_config>` to easily change fish's configuration, like the prompt or colorscheme.
+- :doc:`random <cmds/random>` to generate random numbers or pick from a list.
 
 Known functions
 ^^^^^^^^^^^^^^^^
 
 Known functions are a customization point. You can change them to change how your fish behaves. This includes:
 
-- :ref:`fish_prompt <cmd-fish_prompt>` and :ref:`fish_right_prompt <cmd-fish_right_prompt>` and :ref:`fish_mode_prompt <cmd-fish_mode_prompt>` to print your prompt.
-- :ref:`fish_command_not_found <cmd-fish_command_not_found>` to tell fish what to do when a command is not found.
-- :ref:`fish_title <cmd-fish_title>` to change the terminal's title.
-- :ref:`fish_greeting <cmd-fish_greeting>` to show a greeting when fish starts.
+- :doc:`fish_prompt <cmds/fish_prompt>` and :doc:`fish_right_prompt <cmds/fish_right_prompt>` and :doc:`fish_mode_prompt <cmds/fish_mode_prompt>` to print your prompt.
+- :doc:`fish_command_not_found <cmds/fish_command_not_found>` to tell fish what to do when a command is not found.
+- :doc:`fish_title <cmds/fish_title>` to change the terminal's title.
+- :doc:`fish_greeting <cmds/fish_greeting>` to show a greeting when fish starts.
 
 Helper functions
 ^^^^^^^^^^^^^^^^
 
 Some helper functions, often to give you information for use in your prompt:
 
-- :ref:`fish_git_prompt <cmd-fish_git_prompt>` and :ref:`fish_hg_prompt <cmd-fish_hg_prompt>` to print information about the current git or mercurial repository.
-- :ref:`fish_vcs_prompt <cmd-fish_vcs_prompt>` to print information for either.
-- :ref:`fish_svn_prompt <cmd-fish_svn_prompt>` to print information about the current svn repository.
-- :ref:`fish_status_to_signal <cmd-fish_status_to_signal>` to give a signal name from a return status.
-- :ref:`prompt_pwd <cmd-prompt_pwd>` to give the current directory in a nicely formatted and shortened way.
-- :ref:`prompt_login <cmd-prompt_login>` to describe the current login, with user and hostname, and to explain if you are in a chroot or connected via ssh.
-- :ref:`prompt_hostname <cmd-prompt_hostname>` to give the hostname, shortened for use in the prompt.
-- :ref:`fish_is_root_user <cmd-fish_is_root_user>` to check if the current user is an administrator user like root.
-- :ref:`fish_add_path <cmd-fish_add_path>` to easily add a path to $PATH.
-- :ref:`alias <cmd-alias>` to quickly define wrapper functions ("aliases").
+- :doc:`fish_git_prompt <cmds/fish_git_prompt>` and :doc:`fish_hg_prompt <cmds/fish_hg_prompt>` to print information about the current git or mercurial repository.
+- :doc:`fish_vcs_prompt <cmds/fish_vcs_prompt>` to print information for either.
+- :doc:`fish_svn_prompt <cmds/fish_svn_prompt>` to print information about the current svn repository.
+- :doc:`fish_status_to_signal <cmds/fish_status_to_signal>` to give a signal name from a return status.
+- :doc:`prompt_pwd <cmds/prompt_pwd>` to give the current directory in a nicely formatted and shortened way.
+- :doc:`prompt_login <cmds/prompt_login>` to describe the current login, with user and hostname, and to explain if you are in a chroot or connected via ssh.
+- :doc:`prompt_hostname <cmds/prompt_hostname>` to give the hostname, shortened for use in the prompt.
+- :doc:`fish_is_root_user <cmds/fish_is_root_user>` to check if the current user is an administrator user like root.
+- :doc:`fish_add_path <cmds/fish_add_path>` to easily add a path to $PATH.
+- :doc:`alias <cmds/alias>` to quickly define wrapper functions ("aliases").
 
 Helper commands
 ^^^^^^^^^^^^^^^
 
 fish also ships some things as external commands so they can be easily called from elsewhere.
 
-This includes :ref:`fish_indent <cmd-fish_indent>` to format fish code and :ref:`fish_key_reader <cmd-fish_key_reader>` to show you what escape sequence a keypress produces.
+This includes :doc:`fish_indent <cmds/fish_indent>` to format fish code and :doc:`fish_key_reader <cmds/fish_key_reader>` to show you what escape sequence a keypress produces.
 
 The full list
 ^^^^^^^^^^^^^

doc_src/completions.rst

@@ -12,7 +12,7 @@ To provide a list of possible completions for myprog, use the ``-a`` switch. If
   complete -c myprog -s o -l output -a "yes no"
 
 
-There are also special switches for specifying that a switch requires an argument, to disable filename completion, to create completions that are only available in some combinations, etc..  For a complete description of the various switches accepted by the ``complete`` command, see the documentation for the :ref:`complete <cmd-complete>` builtin, or write ``complete --help`` inside the ``fish`` shell.
+There are also special switches for specifying that a switch requires an argument, to disable filename completion, to create completions that are only available in some combinations, etc..  For a complete description of the various switches accepted by the ``complete`` command, see the documentation for the :doc:`complete <cmds/complete>` builtin, or write ``complete --help`` inside the ``fish`` shell.
 
 As a more comprehensive example, here's a commented excerpt of the completions for systemd's ``timedatectl``::
 

doc_src/faq.rst

@@ -8,7 +8,7 @@ See :ref:`Fish for bash users <fish_for_bash_users>`
 
 How do I set or clear an environment variable?
 ----------------------------------------------
-Use the :ref:`set <cmd-set>` command::
+Use the :doc:`set <cmds/set>` command::
 
     set -x key value # typically set -gx key value
     set -e key
@@ -96,7 +96,7 @@ The prompt is the output of the ``fish_prompt`` function. Put it in ``~/.config/
     end
 
 
-You can also use the Web configuration tool, :ref:`fish_config <cmd-fish_config>`, to preview and choose from a gallery of sample prompts.
+You can also use the Web configuration tool, :doc:`fish_config <cmds/fish_config>`, to preview and choose from a gallery of sample prompts.
 
 Or you can use fish_config from the commandline::
 
@@ -107,7 +107,7 @@ Or you can use fish_config from the commandline::
   > fish_config prompt save
   # makes the change permanent
 
-If you want to modify your existing prompt, you can use :ref:`funced <cmd-funced>` and :ref:`funcsave <cmd-funcsave>` like::
+If you want to modify your existing prompt, you can use :doc:`funced <cmds/funced>` and :doc:`funcsave <cmds/funcsave>` like::
 
   >_ funced fish_prompt
   # This opens up your editor (set in $EDITOR).
@@ -116,20 +116,20 @@ If you want to modify your existing prompt, you can use :ref:`funced <cmd-funced
   # Once you are happy with it:
   >_ funcsave fish_prompt
 
-This also applies to :ref:`fish_right_prompt <cmd-fish_right_prompt>` and :ref:`fish_mode_prompt <cmd-fish_mode_prompt>`.
+This also applies to :doc:`fish_right_prompt <cmds/fish_right_prompt>` and :doc:`fish_mode_prompt <cmds/fish_mode_prompt>`.
 
 Why does my prompt show a ``[I]``?
 ----------------------------------
 
-That's the :ref:`fish_mode_prompt <cmd-fish_mode_prompt>`. It is displayed by default when you've activated vi mode using ``fish_vi_key_bindings``.
+That's the :doc:`fish_mode_prompt <cmds/fish_mode_prompt>`. It is displayed by default when you've activated vi mode using ``fish_vi_key_bindings``.
 
 If you haven't activated vi mode on purpose, you might have installed a third-party theme or plugin that does it.
 
-If you want to change or disable this display, modify the ``fish_mode_prompt`` function, for instance via :ref:`funced <cmd-funced>`.
+If you want to change or disable this display, modify the ``fish_mode_prompt`` function, for instance via :doc:`funced <cmds/funced>`.
 
 How do I customize my syntax highlighting colors?
 -------------------------------------------------
-Use the web configuration tool, :ref:`fish_config <cmd-fish_config>`, or alter the :ref:`fish_color family of environment variables <variables-color>`.
+Use the web configuration tool, :doc:`fish_config <cmds/fish_config>`, or alter the :ref:`fish_color family of environment variables <variables-color>`.
 
 You can also use ``fish_config`` on the commandline, like::
 
@@ -142,7 +142,7 @@ You can also use ``fish_config`` on the commandline, like::
 
 How do I change the greeting message?
 -------------------------------------
-Change the value of the variable ``fish_greeting`` or create a :ref:`fish_greeting <cmd-fish_greeting>` function. For example, to remove the greeting use::
+Change the value of the variable ``fish_greeting`` or create a :doc:`fish_greeting <cmds/fish_greeting>` function. For example, to remove the greeting use::
 
     set -U fish_greeting
 
@@ -243,7 +243,7 @@ Or if you just want to do one command in case the first succeeded or failed, use
     somecommand
     or someothercommand
 
-See the :ref:`Conditions <syntax-conditional>` and the documentation for :ref:`test <cmd-test>` and :ref:`if <cmd-if>` for more information.
+See the :ref:`Conditions <syntax-conditional>` and the documentation for :doc:`test <cmds/test>` and :doc:`if <cmds/if>` for more information.
 
 My command prints "No matches for wildcard" but works in bash
 -------------------------------------------------------------

doc_src/fish_for_bash_users.rst

@@ -14,7 +14,7 @@ Command substitutions
 
 Fish spells command substitutions as ``$(command)`` or ``(command)``, but not ```command```.
 
-In addition, it only splits them on newlines instead of $IFS. If you want to split on something else, use :ref:`string split <cmd-string-split>`, :ref:`string split0 <cmd-string-split>` or :ref:`string collect <cmd-string-collect>`. If those are used as the last command in a command substitution the splits they create are carried over. So::
+In addition, it only splits them on newlines instead of $IFS. If you want to split on something else, use :doc:`string split <cmds/string-split>`, :doc:`string split0 <cmds/string-split>` or :doc:`string collect <cmds/string-collect>`. If those are used as the last command in a command substitution the splits they create are carried over. So::
 
   for i in (find . -print0 | string split0)
 
@@ -23,7 +23,7 @@ will correctly handle all possible filenames.
 Variables
 ---------
 
-Fish sets and erases variables with :ref:`set <cmd-set>` instead of ``VAR=VAL`` and a variety of separate builtins like ``declare`` and ``unset`` and ``export``. ``set`` takes options to determine the scope and exportedness of a variable::
+Fish sets and erases variables with :doc:`set <cmds/set>` instead of ``VAR=VAL`` and a variety of separate builtins like ``declare`` and ``unset`` and ``export``. ``set`` takes options to determine the scope and exportedness of a variable::
 
   # Define $PAGER global and exported,
   # so this is like ``export PAGER=less``
@@ -132,7 +132,7 @@ See :ref:`Quotes <quotes>` for more.
 String manipulation
 -------------------
 
-Fish does not have ``${foo%bar}``, ``${foo#bar}`` and ``${foo/bar/baz}``. Instead string manipulation is done by the :ref:`string <cmd-string>` builtin.
+Fish does not have ``${foo%bar}``, ``${foo#bar}`` and ``${foo/bar/baz}``. Instead string manipulation is done by the :doc:`string <cmds/string>` builtin.
 
 For example, to replace "bar" with "baz"::
 
@@ -191,7 +191,7 @@ just use::
 
   command | source
 
-as fish's :ref:`source <cmd-source>` can read from stdin.
+as fish's :doc:`source <cmds/source>` can read from stdin.
 
 Heredocs
 --------
@@ -275,7 +275,7 @@ Fish has a POSIX-compatible ``test`` or ``[`` builtin. There is no ``[[`` and ``
 Arithmetic Expansion
 --------------------
 
-Fish does not have ``$((i+1))`` arithmetic expansion, computation is handled by :ref:`math <cmd-math>`::
+Fish does not have ``$((i+1))`` arithmetic expansion, computation is handled by :doc:`math <cmds/math>`::
 
   math $i + 1
 
@@ -298,7 +298,7 @@ Both ``*`` and ``x`` are valid ways to spell multiplication, but ``*`` needs to
 Prompts
 -------
 
-Fish does not use the ``$PS1``, ``$PS2`` and so on variables. Instead the prompt is the output of the :ref:`fish_prompt <cmd-fish_prompt>` function, plus the :ref:`fish_mode_prompt <cmd-fish_mode_prompt>` function if vi-mode is enabled and the :ref:`fish_right_prompt <cmd-fish_right_prompt>` function for the right prompt.
+Fish does not use the ``$PS1``, ``$PS2`` and so on variables. Instead the prompt is the output of the :doc:`fish_prompt <cmds/fish_prompt>` function, plus the :doc:`fish_mode_prompt <cmds/fish_mode_prompt>` function if vi-mode is enabled and the :doc:`fish_right_prompt <cmds/fish_right_prompt>` function for the right prompt.
 
 As an example, here's a relatively simple bash prompt:
 
@@ -320,9 +320,9 @@ and a rough fish equivalent::
 
 This shows a few differences:
 
-- Fish provides :ref:`set_color <cmd-set_color>` to color text. It can use the 16 named colors and also RGB sequences (so you could also use ``set_color 5555FF``)
-- Instead of introducing specific escapes like ``\h`` for the hostname, the prompt is simply a function. To achieve the effect of ``\h``, fish provides helper functions like :ref:`prompt_hostname <cmd-prompt_hostname>`, which prints a shortened version of the hostname.
-- Fish offers other helper functions for adding things to the prompt, like :ref:`fish_vcs_prompt <cmd-fish_vcs_prompt>` for adding a display for common version control systems (git, mercurial, svn), and :ref:`prompt_pwd <cmd-prompt_pwd>` for showing a shortened ``$PWD`` (the user's home directory becomes ``~`` and any path component is shortened).
+- Fish provides :doc:`set_color <cmds/set_color>` to color text. It can use the 16 named colors and also RGB sequences (so you could also use ``set_color 5555FF``)
+- Instead of introducing specific escapes like ``\h`` for the hostname, the prompt is simply a function. To achieve the effect of ``\h``, fish provides helper functions like :doc:`prompt_hostname <cmds/prompt_hostname>`, which prints a shortened version of the hostname.
+- Fish offers other helper functions for adding things to the prompt, like :doc:`fish_vcs_prompt <cmds/fish_vcs_prompt>` for adding a display for common version control systems (git, mercurial, svn), and :doc:`prompt_pwd <cmds/prompt_pwd>` for showing a shortened ``$PWD`` (the user's home directory becomes ``~`` and any path component is shortened).
 
 The default prompt is reasonably full-featured and its code can be read via ``type fish_prompt``.
 
@@ -439,11 +439,11 @@ Builtins and other commands
 
 By now it has become apparent that fish puts much more of a focus on its builtins and external commands rather than its syntax. So here are some helpful builtins and their rough equivalent in bash:
 
-- :ref:`string <cmd-string>` - this replaces most of the string transformation (``${i%foo}`` et al) and can also be used instead of ``grep`` and ``sed`` and such.
-- :ref:`math <cmd-math>` - this replaces ``$((i + 1))`` arithmetic and can also do floats and some simple functions (sine and friends).
-- :ref:`argparse <cmd-argparse>` - this can handle a script's option parsing, for which bash would probably use ``getopt`` (zsh provides ``zparseopts``).
-- :ref:`count <cmd-count>` can be used to count things and therefore replaces ``$#`` and can be used instead of ``wc``.
-- :ref:`status <cmd-status>` provides information about the shell status, e.g. if it's interactive or what the current linenumber is. This replaces ``$-`` and ``$BASH_LINENO`` and other variables.
+- :doc:`string <cmds/string>` - this replaces most of the string transformation (``${i%foo}`` et al) and can also be used instead of ``grep`` and ``sed`` and such.
+- :doc:`math <cmds/math>` - this replaces ``$((i + 1))`` arithmetic and can also do floats and some simple functions (sine and friends).
+- :doc:`argparse <cmds/argparse>` - this can handle a script's option parsing, for which bash would probably use ``getopt`` (zsh provides ``zparseopts``).
+- :doc:`count <cmds/count>` can be used to count things and therefore replaces ``$#`` and can be used instead of ``wc``.
+- :doc:`status <cmds/status>` provides information about the shell status, e.g. if it's interactive or what the current linenumber is. This replaces ``$-`` and ``$BASH_LINENO`` and other variables.
 
 - ``seq(1)`` can be used as a replacement for ``{1..10}`` range expansion. If your OS doesn't ship a ``seq`` fish includes a replacement function.
 
@@ -452,5 +452,5 @@ Other facilities
 
 Bash has ``set -x`` or ``set -o xtrace`` to print all commands that are being executed. In fish, this would be enabled by setting :envvar:`fish_trace`.
 
-Or, if your intention is to *profile* how long each line of a script takes, you can use ``fish --profile`` - see the :ref:`page for the fish command <cmd-fish>`.
+Or, if your intention is to *profile* how long each line of a script takes, you can use ``fish --profile`` - see the :doc:`page for the fish command <cmds/fish>`.
 

doc_src/index.rst

@@ -124,7 +124,7 @@ To add ``~/linux/bin`` to PATH variable when using a login shell, add this to ``
         set -gx PATH $PATH ~/linux/bin
     end
 
-This is just an example; using :ref:`fish_add_path <cmd-fish_add_path>` e.g. ``fish_add_path ~/linux/bin`` which only adds the path if it isn't included yet is easier.
+This is just an example; using :doc:`fish_add_path <cmds/fish_add_path>` e.g. ``fish_add_path ~/linux/bin`` which only adds the path if it isn't included yet is easier.
 
 To run commands on exit, use an :ref:`event handler <event>` that is triggered by the exit of the shell::
 

doc_src/interactive.rst

@@ -10,11 +10,11 @@ Fish is used by giving commands in the fish language, see :ref:`The Fish Languag
 Help
 ----
 
-Fish has an extensive help system. Use the :ref:`help <cmd-help>` command to obtain help on a specific subject or command. For instance, writing ``help syntax`` displays the :ref:`syntax section <syntax>` of this documentation.
+Fish has an extensive help system. Use the :doc:`help <cmds/help>` command to obtain help on a specific subject or command. For instance, writing ``help syntax`` displays the :ref:`syntax section <syntax>` of this documentation.
 
 Fish also has man pages for its commands, and translates the help pages to man pages. For example, ``man set`` will show the documentation for ``set`` as a man page.
 
-Help on a specific builtin can also be obtained with the ``-h`` parameter. For instance, to obtain help on the :ref:`fg <cmd-fg>` builtin, either type ``fg -h`` or ``help fg``.
+Help on a specific builtin can also be obtained with the ``-h`` parameter. For instance, to obtain help on the :doc:`fg <cmds/fg>` builtin, either type ``fg -h`` or ``help fg``.
 
 The main page can be viewed via ``help index`` (or just ``help``) or ``man fish-doc``. The tutorial can be viewed with ``help tutorial`` or ``man fish-tutorial``.
 
@@ -84,7 +84,7 @@ Detected errors include:
 
 To customize the syntax highlighting, you can set the environment variables listed in the :ref:`Variables for changing highlighting colors <variables-color>` section.
 
-Fish also provides pre-made color themes you can pick with :ref:`fish_config <cmd-fish_config>`. Running just ``fish_config`` opens a browser interface, or you can use ``fish_config theme`` in the terminal.
+Fish also provides pre-made color themes you can pick with :doc:`fish_config <cmds/fish_config>`. Running just ``fish_config`` opens a browser interface, or you can use ``fish_config theme`` in the terminal.
 
 For example, to disable nearly all coloring::
 
@@ -99,7 +99,7 @@ Or, to see all themes, right in your terminal::
 Syntax highlighting variables
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The colors used by fish for syntax highlighting can be configured by changing the values of various variables. The value of these variables can be one of the colors accepted by the :ref:`set_color <cmd-set_color>` command. The modifier switches accepted by ``set_color`` like ``--bold``, ``--dim``, ``--italics``, ``--reverse`` and ``--underline`` are also accepted.
+The colors used by fish for syntax highlighting can be configured by changing the values of various variables. The value of these variables can be one of the colors accepted by the :doc:`set_color <cmds/set_color>` command. The modifier switches accepted by ``set_color`` like ``--bold``, ``--dim``, ``--italics``, ``--reverse`` and ``--underline`` are also accepted.
 
 
 Example: to make errors highlighted and red, use::
@@ -191,7 +191,7 @@ When the secondary or selected variables aren't set or are empty, the normal var
 Abbreviations
 -------------
 
-To avoid needless typing, a frequently-run command like ``git checkout`` can be abbreviated to ``gco`` using the :ref:`abbr <cmd-abbr>` command.
+To avoid needless typing, a frequently-run command like ``git checkout`` can be abbreviated to ``gco`` using the :doc:`abbr <cmds/abbr>` command.
 
 ::
 
@@ -206,7 +206,7 @@ This is an alternative to aliases, and has the advantage that you see the actual
 Programmable title
 ------------------
 
-When using most virtual terminals, it is possible to set the message displayed in the titlebar of the terminal window. This can be done automatically in fish by defining the :ref:`fish_title <cmd-fish_title>` function. The :ref:`fish_title <cmd-fish_title>` function is executed before and after a new command is executed or put into the foreground and the output is used as a titlebar message. The :ref:`status current-command <cmd-status>` builtin will always return the name of the job to be put into the foreground (or ``fish`` if control is returning to the shell) when the :ref:`fish_prompt <cmd-fish_prompt>` function is called. The first argument to fish_title will contain the most recently executed foreground command as a string.
+When using most virtual terminals, it is possible to set the message displayed in the titlebar of the terminal window. This can be done automatically in fish by defining the :doc:`fish_title <cmds/fish_title>` function. The :doc:`fish_title <cmds/fish_title>` function is executed before and after a new command is executed or put into the foreground and the output is used as a titlebar message. The :doc:`status current-command <cmds/status>` builtin will always return the name of the job to be put into the foreground (or ``fish`` if control is returning to the shell) when the :doc:`fish_prompt <cmds/fish_prompt>` function is called. The first argument to fish_title will contain the most recently executed foreground command as a string.
 
 The default fish title shows the hostname if connected via ssh, the currently running command (unless it is fish) and the current working directory. All of this is shortened to not make the tab too wide.
 
@@ -225,16 +225,16 @@ To show the last command and working directory in the title::
 Programmable prompt
 -------------------
 
-When it is fish's turn to ask for input (like after it started or the command ended), it will show a prompt. It does this by running the :ref:`fish_prompt <cmd-fish_prompt>` and :ref:`fish_right_prompt <cmd-fish_right_prompt>` functions.
+When it is fish's turn to ask for input (like after it started or the command ended), it will show a prompt. It does this by running the :doc:`fish_prompt <cmds/fish_prompt>` and :doc:`fish_right_prompt <cmds/fish_right_prompt>` functions.
 
-The output of the former is displayed on the left and the latter's output on the right side of the terminal. The output of :ref:`fish_mode_prompt <cmd-fish_mode_prompt>` will be prepended on the left, though the default function only does this when in :ref:`vi-mode <vi-mode>`.
+The output of the former is displayed on the left and the latter's output on the right side of the terminal. The output of :doc:`fish_mode_prompt <cmds/fish_mode_prompt>` will be prepended on the left, though the default function only does this when in :ref:`vi-mode <vi-mode>`.
 
 .. _greeting:
 
 Configurable greeting
 ---------------------
 
-When it is started interactively, fish tries to run the :ref:`fish_greeting <cmd-fish_greeting>` function. The default fish_greeting prints a simple greeting. You can change its text by changing the ``$fish_greeting`` variable.
+When it is started interactively, fish tries to run the :doc:`fish_greeting <cmds/fish_greeting>` function. The default fish_greeting prints a simple greeting. You can change its text by changing the ``$fish_greeting`` variable.
 
 .. _private-mode:
 
@@ -359,7 +359,7 @@ To enable emacs mode, use ``fish_default_key_bindings``. This is also the defaul
 - :kbd:`Control`\ +\ :kbd:`R` opens the history in a pager. This will show history entries matching the search, a few at a time. Pressing :kbd:`Control`\ +\ :kbd:`R` again will search older entries, pressing :kbd:`Control`\ +\ :kbd:`S` (that otherwise toggles pager search) will go to newer entries. The search bar will always be selected.
 
 
-You can change these key bindings using the :ref:`bind <cmd-bind>` builtin.
+You can change these key bindings using the :doc:`bind <cmds/bind>` builtin.
 
 
 .. _vi-mode:
@@ -386,9 +386,9 @@ It is also possible to add all emacs-mode bindings to vi-mode by using something
     end
 
 
-When in vi-mode, the :ref:`fish_mode_prompt <cmd-fish_mode_prompt>` function will display a mode indicator to the left of the prompt. To disable this feature, override it with an empty function. To display the mode elsewhere (like in your right prompt), use the output of the ``fish_default_mode_prompt`` function.
+When in vi-mode, the :doc:`fish_mode_prompt <cmds/fish_mode_prompt>` function will display a mode indicator to the left of the prompt. To disable this feature, override it with an empty function. To display the mode elsewhere (like in your right prompt), use the output of the ``fish_default_mode_prompt`` function.
 
-When a binding switches the mode, it will repaint the mode-prompt if it exists, and the rest of the prompt only if it doesn't. So if you want a mode-indicator in your ``fish_prompt``, you need to erase ``fish_mode_prompt`` e.g. by adding an empty file at ``~/.config/fish/functions/fish_mode_prompt.fish``. (Bindings that change the mode are supposed to call the `repaint-mode` bind function, see :ref:`bind <cmd-bind>`)
+When a binding switches the mode, it will repaint the mode-prompt if it exists, and the rest of the prompt only if it doesn't. So if you want a mode-indicator in your ``fish_prompt``, you need to erase ``fish_mode_prompt`` e.g. by adding an empty file at ``~/.config/fish/functions/fish_mode_prompt.fish``. (Bindings that change the mode are supposed to call the `repaint-mode` bind function, see :doc:`bind <cmds/bind>`)
 
 The ``fish_vi_cursor`` function will be used to change the cursor's shape depending on the mode in supported terminals. The following snippet can be used to manually configure cursors after enabling vi-mode::
 
@@ -489,14 +489,14 @@ Visual mode
 Custom bindings
 ---------------
 
-In addition to the standard bindings listed here, you can also define your own with :ref:`bind <cmd-bind>`::
+In addition to the standard bindings listed here, you can also define your own with :doc:`bind <cmds/bind>`::
 
   # Just clear the commandline on control-c
   bind \cc 'commandline -r ""'
 
 Put ``bind`` statements into :ref:`config.fish <configuration>` or a function called ``fish_user_key_bindings``.
 
-The key sequence (the ``\cc``) here depends on your setup, in particular the terminal. To find out what the terminal sends use :ref:`fish_key_reader <cmd-fish_key_reader>`::
+The key sequence (the ``\cc``) here depends on your setup, in particular the terminal. To find out what the terminal sends use :doc:`fish_key_reader <cmds/fish_key_reader>`::
 
   > fish_key_reader # pressing control-c
   Press a key:
@@ -538,7 +538,7 @@ Multiline editing
 
 The fish commandline editor can be used to work on commands that are several lines long. There are three ways to make a command span more than a single line:
 
-- Pressing the :kbd:`Enter` key while a block of commands is unclosed, such as when one or more block commands such as ``for``, ``begin`` or ``if`` do not have a corresponding :ref:`end <cmd-end>` command.
+- Pressing the :kbd:`Enter` key while a block of commands is unclosed, such as when one or more block commands such as ``for``, ``begin`` or ``if`` do not have a corresponding :doc:`end <cmds/end>` command.
 
 - Pressing :kbd:`Alt`\ +\ :kbd:`Enter` instead of pressing the :kbd:`Enter` key.
 
@@ -566,7 +566,7 @@ The command history is stored in the file ``~/.local/share/fish/fish_history`` (
 ``fish_history`` environment variable to change the name of the history session (resulting in a
 ``<session>_history`` file); both before starting the shell and while the shell is running.
 
-See the :ref:`history <cmd-history>` command for other manipulations.
+See the :doc:`history <cmds/history>` command for other manipulations.
 
 Examples:
 
@@ -574,7 +574,7 @@ To search for previous entries containing the word 'make', type ``make`` in the
 
 If the commandline reads ``cd m``, place the cursor over the ``m`` character and press :kbd:`Alt`\ +\ :kbd:`↑` to search for previously typed words containing 'm'.
 
-.. [#] Or another binding that triggers the ``history-pager`` input function. See :ref:`bind <cmd-bind>` for a list.
+.. [#] Or another binding that triggers the ``history-pager`` input function. See :doc:`bind <cmds/bind>` for a list.
 .. [#] Or another binding that triggers the ``pager-toggle-search`` input function.
 
 Navigating directories
@@ -582,21 +582,21 @@ Navigating directories
 
 .. _directory-history:
 
-Navigating directories is usually done with the :ref:`cd <cmd-cd>` command, but fish offers some advanced features as well.
+Navigating directories is usually done with the :doc:`cd <cmds/cd>` command, but fish offers some advanced features as well.
 
-The current working directory can be displayed with the :ref:`pwd <cmd-pwd>` command, or the ``$PWD`` :ref:`special variable <variables-special>`. Usually your prompt already does this.
+The current working directory can be displayed with the :doc:`pwd <cmds/pwd>` command, or the ``$PWD`` :ref:`special variable <variables-special>`. Usually your prompt already does this.
 
 Directory history
 ^^^^^^^^^^^^^^^^^
 
-Fish automatically keeps a trail of the recent visited directories with :ref:`cd <cmd-cd>` by storing this history in the ``dirprev`` and ``dirnext`` variables.
+Fish automatically keeps a trail of the recent visited directories with :doc:`cd <cmds/cd>` by storing this history in the ``dirprev`` and ``dirnext`` variables.
 
 Several commands are provided to interact with this directory history:
 
-- :ref:`dirh <cmd-dirh>` prints the history
-- :ref:`cdh <cmd-cdh>` displays a prompt to quickly navigate the history
-- :ref:`prevd <cmd-prevd>` moves backward through the history. It is bound to :kbd:`Alt`\ +\ :kbd:`←`
-- :ref:`nextd <cmd-nextd>` moves forward through the history. It is bound to :kbd:`Alt`\ +\ :kbd:`→`
+- :doc:`dirh <cmds/dirh>` prints the history
+- :doc:`cdh <cmds/cdh>` displays a prompt to quickly navigate the history
+- :doc:`prevd <cmds/prevd>` moves backward through the history. It is bound to :kbd:`Alt`\ +\ :kbd:`←`
+- :doc:`nextd <cmds/nextd>` moves forward through the history. It is bound to :kbd:`Alt`\ +\ :kbd:`→`
 
 .. _directory-stack:
 
@@ -605,6 +605,6 @@ Directory stack
 
 Another set of commands, usually also available in other shells like bash, deal with the directory stack. Stack handling is not automatic and needs explicit calls of the following commands:
 
-- :ref:`dirs <cmd-dirs>` prints the stack
-- :ref:`pushd <cmd-pushd>` adds a directory on top of the stack and makes it the current working directory
-- :ref:`popd <cmd-popd>` removes the directory on top of the stack and changes the current working directory
+- :doc:`dirs <cmds/dirs>` prints the stack
+- :doc:`pushd <cmds/pushd>` adds a directory on top of the stack and makes it the current working directory
+- :doc:`popd <cmds/popd>` removes the directory on top of the stack and changes the current working directory

doc_src/language.rst

@@ -17,7 +17,7 @@ Shells like fish are used by giving them commands. A command is executed by writ
 
     echo hello world
 
-:ref:`echo <cmd-echo>` command writes its arguments to the screen. In this example the output is ``hello world``.
+:doc:`echo <cmds/echo>` command writes its arguments to the screen. In this example the output is ``hello world``.
 
 Everything in fish is done with commands. There are commands for repeating other commands, commands for assigning variables, commands for treating a group of commands as a single command, etc. All of these commands follow the same basic syntax.
 
@@ -27,12 +27,12 @@ Every program on your computer can be used as a command in fish. If the program
 
 Here is a list of some useful commands:
 
-- :ref:`cd <cmd-cd>`: Change the current directory
+- :doc:`cd <cmds/cd>`: Change the current directory
 - ``ls``: List files and directories
 - ``man``: Display a manual page
 - ``mv``: Move (rename) files
 - ``cp``: Copy files
-- :ref:`open <cmd-open>`: Open files with the default application associated with each filetype
+- :doc:`open <cmds/open>`: Open files with the default application associated with each filetype
 - ``less``: Display the contents of files
 
 Commands and arguments are separated by the space character ``' '``. Every command ends with either a newline (by pressing the return key) or a semicolon ``;``. Multiple commands can be written on the same line by separating them with semicolons.
@@ -223,16 +223,16 @@ Example::
   emacs &
 
 
-will start the emacs text editor in the background. :ref:`fg <cmd-fg>` can be used to bring it into the foreground again when needed.
+will start the emacs text editor in the background. :doc:`fg <cmds/fg>` can be used to bring it into the foreground again when needed.
 
-Most programs allow you to suspend the program's execution and return control to fish by pressing :kbd:`Control`\ +\ :kbd:`Z` (also referred to as ``^Z``). Once back at the fish commandline, you can start other programs and do anything you want. If you then want you can go back to the suspended command by using the :ref:`fg <cmd-fg>` (foreground) command.
+Most programs allow you to suspend the program's execution and return control to fish by pressing :kbd:`Control`\ +\ :kbd:`Z` (also referred to as ``^Z``). Once back at the fish commandline, you can start other programs and do anything you want. If you then want you can go back to the suspended command by using the :doc:`fg <cmds/fg>` (foreground) command.
 
-If you instead want to put a suspended job into the background, use the :ref:`bg <cmd-bg>` command.
+If you instead want to put a suspended job into the background, use the :doc:`bg <cmds/bg>` command.
 
-To get a listing of all currently started jobs, use the :ref:`jobs <cmd-jobs>` command.
-These listed jobs can be removed with the :ref:`disown <cmd-disown>` command.
+To get a listing of all currently started jobs, use the :doc:`jobs <cmds/jobs>` command.
+These listed jobs can be removed with the :doc:`disown <cmds/disown>` command.
 
-At the moment, functions cannot be started in the background. Functions that are stopped and then restarted in the background using the :ref:`bg <cmd-bg>` command will not execute correctly.
+At the moment, functions cannot be started in the background. Functions that are stopped and then restarted in the background using the :doc:`bg <cmds/bg>` command will not execute correctly.
 
 If the ``&`` character is followed by a non-separating character, it is not interpreted as background operator. Separating characters are whitespace and the characters ``;<>&|``.
 
@@ -255,7 +255,7 @@ Calling this as ``ll /tmp/`` will end up running ``ls -l /tmp/``, which will lis
 
 This is a kind of function known as a :ref:`wrapper <syntax-function-wrappers>` or "alias".
 
-Fish's prompt is also defined in a function, called :ref:`fish_prompt <cmd-fish_prompt>`. It is run when the prompt is about to be displayed and its output forms the prompt::
+Fish's prompt is also defined in a function, called :doc:`fish_prompt <cmds/fish_prompt>`. It is run when the prompt is about to be displayed and its output forms the prompt::
 
   function fish_prompt
       # A simple prompt. Displays the current directory
@@ -269,11 +269,11 @@ Fish's prompt is also defined in a function, called :ref:`fish_prompt <cmd-fish_
       echo (set_color yellow)$PWD (set_color purple)$user_char
   end
 
-To edit a function, you can use :ref:`funced <cmd-funced>`, and to save a function :ref:`funcsave <cmd-funcsave>`. This will store it in a function file that fish will :ref:`autoload <syntax-function-autoloading>` when needed.
+To edit a function, you can use :doc:`funced <cmds/funced>`, and to save a function :doc:`funcsave <cmds/funcsave>`. This will store it in a function file that fish will :ref:`autoload <syntax-function-autoloading>` when needed.
 
-The :ref:`functions <cmd-functions>` builtin can show a function's current definition (and :ref:`type <cmd-type>` will also do if given a function).
+The :doc:`functions <cmds/functions>` builtin can show a function's current definition (and :doc:`type <cmds/type>` will also do if given a function).
 
-For more information on functions, see the documentation for the :ref:`function <cmd-function>` builtin.
+For more information on functions, see the documentation for the :doc:`function <cmds/function>` builtin.
 
 .. _syntax-function-wrappers:
 
@@ -293,7 +293,7 @@ There are a few important things that need to be noted about aliases:
 - If the alias has the same name as the aliased command, you need to prefix the call to the program with ``command`` to tell fish that the function should not call itself, but rather a command with the same name. If you forget to do so, the function would call itself until the end of time. Usually fish is smart enough to figure this out and will refrain from doing so (which is hopefully in your interest).
 
 
-To easily create a function of this form, you can use the :ref:`alias <cmd-alias>` command. Unlike other shells, this just makes functions - fish has no separate concept of an "alias", we just use the word for a function wrapper like this. :ref:`alias <cmd-alias>` immediately creates a function. Consider using ``alias --save`` or :ref:`funcsave <cmd-funcsave>` to save the created function into an autoload file instead of recreating the alias each time.
+To easily create a function of this form, you can use the :doc:`alias <cmds/alias>` command. Unlike other shells, this just makes functions - fish has no separate concept of an "alias", we just use the word for a function wrapper like this. :doc:`alias <cmds/alias>` immediately creates a function. Consider using ``alias --save`` or :doc:`funcsave <cmds/funcsave>` to save the created function into an autoload file instead of recreating the alias each time.
 
 For an alternative, try :ref:`abbreviations <abbreviations>`. These are words that are expanded while you type, instead of being actual functions inside the shell.
 
@@ -353,15 +353,15 @@ Comments can also appear after a line like so::
 Conditions
 ----------
 
-Fish has some builtins that let you execute commands only if a specific criterion is met: :ref:`if <cmd-if>`, :ref:`switch <cmd-switch>`, :ref:`and <cmd-and>` and :ref:`or <cmd-or>`, and also the familiar :ref:`&&/|| <tut-combiners>` syntax.
+Fish has some builtins that let you execute commands only if a specific criterion is met: :doc:`if <cmds/if>`, :doc:`switch <cmds/switch>`, :doc:`and <cmds/and>` and :doc:`or <cmds/or>`, and also the familiar :ref:`&&/|| <tut-combiners>` syntax.
 
-The :ref:`switch <cmd-switch>` command is used to execute one of possibly many blocks of commands depending on the value of a string. See the documentation for :ref:`switch <cmd-switch>` for more information.
+The :doc:`switch <cmds/switch>` command is used to execute one of possibly many blocks of commands depending on the value of a string. See the documentation for :doc:`switch <cmds/switch>` for more information.
 
 The other conditionals use the :ref:`exit status <variables-status>` of a command to decide if a command or a block of commands should be executed.
 
-Unlike programming languages you might know, :ref:`if <cmd-if>` doesn't take a *condition*, it takes a *command*. If that command returned a successful :ref:`exit status <variables-status>` (that's 0), the ``if`` branch is taken, otherwise the :ref:`else <cmd-else>` branch.
+Unlike programming languages you might know, :doc:`if <cmds/if>` doesn't take a *condition*, it takes a *command*. If that command returned a successful :ref:`exit status <variables-status>` (that's 0), the ``if`` branch is taken, otherwise the :doc:`else <cmds/else>` branch.
 
-To check a condition, there is the :ref:`test <cmd-test>` command::
+To check a condition, there is the :doc:`test <cmds/test>` command::
 
   if test 5 -gt 2
       echo Yes, five is greater than two
@@ -391,9 +391,9 @@ For more, see the documentation for the builtins or the :ref:`Conditionals <tut-
 Loops and blocks
 ----------------
 
-Like most programming language, fish also has the familiar :ref:`while <cmd-while>` and :ref:`for <cmd-for>` loops.
+Like most programming language, fish also has the familiar :doc:`while <cmds/while>` and :doc:`for <cmds/for>` loops.
 
-``while`` works like a repeated :ref:`if <cmd-if>`::
+``while`` works like a repeated :doc:`if <cmds/if>`::
 
   while true
       echo Still running
@@ -421,7 +421,7 @@ If you need a list of numbers, you can use the ``seq`` command to create one::
       echo $i
   end
 
-:ref:`break <cmd-break>` is available to break out of a loop, and :ref:`continue <cmd-continue>` to jump to the next iteration.
+:doc:`break <cmds/break>` is available to break out of a loop, and :doc:`continue <cmds/continue>` to jump to the next iteration.
 
 :ref:`Input and output redirections <redirects>` (including :ref:`pipes <pipes>`) can also be applied to loops::
 
@@ -429,7 +429,7 @@ If you need a list of numbers, you can use the ``seq`` command to create one::
       echo line: $line
   end < file
 
-In addition there's a :ref:`begin <cmd-begin>` block that just groups commands together so you can redirect to a block or use a new :ref:`variable scope <variables-scope>` without any repetition::
+In addition there's a :doc:`begin <cmds/begin>` block that just groups commands together so you can redirect to a block or use a new :ref:`variable scope <variables-scope>` without any repetition::
 
   begin
      set -l foo bar # this variable will only be available in this block!
@@ -475,7 +475,7 @@ Examples:
 
 - ``~/.*`` matches all hidden files (also known as "dotfiles") and directories in your home directory.
 
-For most commands, if any wildcard fails to expand, the command is not executed, :ref:`$status <variables-status>` is set to nonzero, and a warning is printed. This behavior is like what bash does with ``shopt -s failglob``. There are exceptions, namely :ref:`set <cmd-set>` and :ref:`path <cmd-path>`, overriding variables in :ref:`overrides <variables-override>`, :ref:`count <cmd-count>` and :ref:`for <cmd-for>`. Their globs will instead expand to zero arguments (so the command won't see them at all), like with ``shopt -s nullglob`` in bash.
+For most commands, if any wildcard fails to expand, the command is not executed, :ref:`$status <variables-status>` is set to nonzero, and a warning is printed. This behavior is like what bash does with ``shopt -s failglob``. There are exceptions, namely :doc:`set <cmds/set>` and :doc:`path <cmds/path>`, overriding variables in :ref:`overrides <variables-override>`, :doc:`count <cmds/count>` and :doc:`for <cmds/for>`. Their globs will instead expand to zero arguments (so the command won't see them at all), like with ``shopt -s nullglob`` in bash.
 
 Examples::
 
@@ -503,9 +503,9 @@ In the simplest case, this is just something like::
 
     echo $HOME
 
-which will replace ``$HOME`` with the home directory of the current user, and pass it to :ref:`echo <cmd-echo>`, which will then print it.
+which will replace ``$HOME`` with the home directory of the current user, and pass it to :doc:`echo <cmds/echo>`, which will then print it.
 
-Some variables like ``$HOME`` are already set because fish sets them by default or because fish's parent process passed them to fish when it started it. You can define your own variables by setting them with :ref:`set <cmd-set>`::
+Some variables like ``$HOME`` are already set because fish sets them by default or because fish's parent process passed them to fish when it started it. You can define your own variables by setting them with :doc:`set <cmds/set>`::
 
     set my_directory /home/cooluser/mystuff
     ls $my_directory
@@ -552,7 +552,7 @@ Unlike other shells, fish doesn't do what is known as "Word Splitting". Once a v
   |one
   thing|
 
-That means quoting isn't the absolute necessity it is in other shells. Most of the time, not quoting a variable is correct. The exception is when you need to ensure that the variable is passed as one element, even if it might be unset or have multiple elements. This happens often with :ref:`test <cmd-test>`::
+That means quoting isn't the absolute necessity it is in other shells. Most of the time, not quoting a variable is correct. The exception is when you need to ensure that the variable is passed as one element, even if it might be unset or have multiple elements. This happens often with :doc:`test <cmds/test>`::
 
   set -l foo one two three
   test -n $foo
@@ -596,13 +596,13 @@ When you write a command in parentheses like ``outercommand (innercommand)``, th
 
 A command substitution can have a dollar sign before the opening parenthesis like ``outercommand $(innercommand)``. This variant is also allowed inside double quotes. When using double quotes, the command output is not split up by lines.
 
-If the output is piped to :ref:`string split or string split0 <cmd-string-split>` as the last step, those splits are used as they appear instead of splitting lines.
+If the output is piped to :doc:`string split or string split0 <cmds/string-split>` as the last step, those splits are used as they appear instead of splitting lines.
 
-The exit status of the last run command substitution is available in the :ref:`status <variables-status>` variable if the substitution happens in the context of a :ref:`set <cmd-set>` command (so ``if set -l (something)`` checks if ``something`` returned true).
+The exit status of the last run command substitution is available in the :ref:`status <variables-status>` variable if the substitution happens in the context of a :doc:`set <cmds/set>` command (so ``if set -l (something)`` checks if ``something`` returned true).
 
 To use only part of the output, refer to :ref:`index range expansion <expand-index-range>`.
 
-Fish has a default limit of 100 MiB on the data it will read in a command sustitution. If that limit is reached the command (all of it, not just the command substitution - the outer command won't be executed at all) fails and ``$status`` is set to 122. This is so command substitutions can't cause the system to go out of memory, because typically your operating system has a much lower limit, so reading more than that would be useless and harmful. This limit can be adjusted with the ``fish_read_limit`` variable (`0` meaning no limit). This limit also affects the :ref:`read <cmd-read>` command.
+Fish has a default limit of 100 MiB on the data it will read in a command sustitution. If that limit is reached the command (all of it, not just the command substitution - the outer command won't be executed at all) fails and ``$status`` is set to 122. This is so command substitutions can't cause the system to go out of memory, because typically your operating system has a much lower limit, so reading more than that would be useless and harmful. This limit can be adjusted with the ``fish_read_limit`` variable (`0` meaning no limit). This limit also affects the :doc:`read <cmds/read>` command.
 
 Examples::
 
@@ -625,14 +625,14 @@ Sometimes you want to pass the output of a command to another command that only
 
     grep fish myanimallist1 | wc -l
 
-but if you need multiple or the command doesn't read from standard input, "process substitution" is useful. Other shells allow this via ``foo <(bar) <(baz)``, and fish uses the :ref:`psub <cmd-psub>` command::
+but if you need multiple or the command doesn't read from standard input, "process substitution" is useful. Other shells allow this via ``foo <(bar) <(baz)``, and fish uses the :doc:`psub <cmds/psub>` command::
 
     # Compare just the lines containing "fish" in two files:
     diff -u (grep fish myanimallist1 | psub) (grep fish myanimallist2 | psub)
 
 This creates a temporary file, stores the output of the command in that file and prints the filename, so it is given to the outer command.
 
-.. [#] Setting ``$IFS`` to empty will disable line splitting. This is deprecated, use :ref:`string split <cmd-string-split>` instead.
+.. [#] Setting ``$IFS`` to empty will disable line splitting. This is deprecated, use :doc:`string split <cmds/string-split>` instead.
 
 .. _expand-brace:
 
@@ -873,7 +873,7 @@ Shell variables
 
 Variables are a way to save data and pass it around. They can be used just by the shell, or they can be ":ref:`exported <variables-export>`", so that a copy of the variable is available to any external command the shell starts. An exported variable is referred to as an "environment variable".
 
-To set a variable value, use the :ref:`set <cmd-set>` command. A variable name can not be empty and can contain only letters, digits, and underscores. It may begin and end with any of those characters.
+To set a variable value, use the :doc:`set <cmds/set>` command. A variable name can not be empty and can contain only letters, digits, and underscores. It may begin and end with any of those characters.
 
 Example:
 
@@ -1157,7 +1157,7 @@ When a list is exported as an environment variable, it is either space or colon
 
 Fish automatically creates lists from all environment variables whose name ends in ``PATH`` (like :envvar:`PATH`, :envvar:`CDPATH` or :envvar:`MANPATH`), by splitting them on colons. Other variables are not automatically split.
 
-Lists can be inspected with the :ref:`count <cmd-count>` or the :ref:`contains <cmd-contains>` commands::
+Lists can be inspected with the :doc:`count <cmds/count>` or the :doc:`contains <cmds/contains>` commands::
 
     count $smurf
     # 2
@@ -1199,7 +1199,7 @@ This function takes whatever arguments it gets and prints the first and third::
 
 Commandline tools often get various options and flags and positional arguments, and $argv would contain all of these.
 
-A more robust approach to argument handling is :ref:`argparse <cmd-argparse>`, which checks the defined options and puts them into various variables, leaving only the positional arguments in $argv. Here's a simple example::
+A more robust approach to argument handling is :doc:`argparse <cmds/argparse>`, which checks the defined options and puts them into various variables, leaving only the positional arguments in $argv. Here's a simple example::
 
   function mybetterfunction
       argparse h/help s/second -- $argv
@@ -1271,7 +1271,7 @@ You can change the settings of fish by changing the values of certain variables.
 
 .. envvar:: CDPATH
    
-   A list of directories in which the :ref:`cd <cmd-cd>` builtin looks for a new directory.
+   A list of directories in which the :doc:`cd <cmds/cd>` builtin looks for a new directory.
 
 .. envvar:: FISH_DEBUG
 
@@ -1315,7 +1315,7 @@ You can change the settings of fish by changing the values of certain variables.
 
 .. envvar:: fish_greeting
 
-   the greeting message printed on startup. This is printed by a function of the same name that can be overridden for more complicated changes (see :ref:`funced <cmd-funced>`)
+   the greeting message printed on startup. This is printed by a function of the same name that can be overridden for more complicated changes (see :doc:`funced <cmds/funced>`)
 
 .. envvar:: fish_history
 
@@ -1336,7 +1336,7 @@ You can change the settings of fish by changing the values of certain variables.
 
 .. envvar:: umask
 
-   the current file creation mask. The preferred way to change the umask variable is through the :ref:`umask <cmd-umask>` function. An attempt to set umask to an invalid value will always fail.
+   the current file creation mask. The preferred way to change the umask variable is through the :doc:`umask <cmds/umask>` function. An attempt to set umask to an invalid value will always fail.
 
 .. envvar:: BROWSER
 
@@ -1386,7 +1386,7 @@ Fish also provides additional information through the values of certain environm
 
 .. ENVVAR:: IFS
 
-   the internal field separator that is used for word splitting with the :ref:`read <cmd-read>` builtin. Setting this to the empty string will also disable line splitting in :ref:`command substitution <expand-command-substitution>`. This variable can be changed.
+   the internal field separator that is used for word splitting with the :doc:`read <cmds/read>` builtin. Setting this to the empty string will also disable line splitting in :ref:`command substitution <expand-command-substitution>`. This variable can be changed.
 
 .. envvar:: last_pid
 
@@ -1457,9 +1457,9 @@ If fish encounters a problem while executing a command, the status variable may
 
 If a process exits through a signal, the exit status will be 128 plus the number of the signal.
 
-The status can be negated with :ref:`not <cmd-not>` (or ``!``), which is useful in a :ref:`condition <syntax-conditional>`. This turns a status of 0 into 1 and any non-zero status into 0.
+The status can be negated with :doc:`not <cmds/not>` (or ``!``), which is useful in a :ref:`condition <syntax-conditional>`. This turns a status of 0 into 1 and any non-zero status into 0.
 
-There is also ``$pipestatus``, which is a list of all ``status`` values of processes in a pipe. One difference is that :ref:`not <cmd-not>` applies to ``$status``, but not ``$pipestatus``, because it loses information.
+There is also ``$pipestatus``, which is a list of all ``status`` values of processes in a pipe. One difference is that :doc:`not <cmds/not>` applies to ``$status``, but not ``$pipestatus``, because it loses information.
 
 For example::
 
@@ -1526,15 +1526,15 @@ Builtin commands
 
 Fish includes a number of commands in the shell directly. We call these "builtins". These include:
 
-- Builtins that manipulate the shell state - :ref:`cd <cmd-cd>` changes directory, :ref:`set <cmd-set>` sets variables
-- Builtins for dealing with data, like :ref:`string <cmd-string>` for strings and :ref:`math <cmd-math>` for numbers, :ref:`count <cmd-count>` for counting lines or arguments
-- :ref:`status <cmd-status>` for asking about the shell's status
-- :ref:`printf <cmd-printf>` and :ref:`echo <cmd-echo>` for creating output
-- :ref:`test <cmd-test>` for checking conditions
-- :ref:`argparse <cmd-argparse>` for parsing function arguments
-- :ref:`source <cmd-source>` to read a script in the current shell (so changes to variables stay) and :ref:`eval <cmd-eval>` to execute a string as script
-- :ref:`random <cmd-random>` to get random numbers or pick a random element from a list
-- :ref:`read <cmd-read>` for reading from a pipe or the terminal
+- Builtins that manipulate the shell state - :doc:`cd <cmds/cd>` changes directory, :doc:`set <cmds/set>` sets variables
+- Builtins for dealing with data, like :doc:`string <cmds/string>` for strings and :doc:`math <cmds/math>` for numbers, :doc:`count <cmds/count>` for counting lines or arguments
+- :doc:`status <cmds/status>` for asking about the shell's status
+- :doc:`printf <cmds/printf>` and :doc:`echo <cmds/echo>` for creating output
+- :doc:`test <cmds/test>` for checking conditions
+- :doc:`argparse <cmds/argparse>` for parsing function arguments
+- :doc:`source <cmds/source>` to read a script in the current shell (so changes to variables stay) and :doc:`eval <cmds/eval>` to execute a string as script
+- :doc:`random <cmds/random>` to get random numbers or pick a random element from a list
+- :doc:`read <cmds/read>` for reading from a pipe or the terminal
 
 For a list of all builtins, use ``builtin -n``.
 
@@ -1543,9 +1543,9 @@ For a list of all builtins, functions and commands shipped with fish, see the :r
 Querying for user input
 -----------------------
 
-Sometimes, you want to ask the user for input, for instance to confirm something. This can be done with the :ref:`read <cmd-read>` builtin.
+Sometimes, you want to ask the user for input, for instance to confirm something. This can be done with the :doc:`read <cmds/read>` builtin.
 
-Let's make up an example. This function will :ref:`glob <expand-wildcard>` the files in all the directories it gets as :ref:`arguments <variables-argv>`, and :ref:`if <syntax-conditional>` there are :ref:`more than five <cmd-test>` it will ask the user if it is supposed to show them, but only if it is connected to a terminal::
+Let's make up an example. This function will :ref:`glob <expand-wildcard>` the files in all the directories it gets as :ref:`arguments <variables-argv>`, and :ref:`if <syntax-conditional>` there are :doc:`more than five <cmds/test>` it will ask the user if it is supposed to show them, but only if it is connected to a terminal::
 
     function show_files
         # This will glob on all arguments. Any non-directories will be ignored.
@@ -1694,9 +1694,9 @@ To specify a signal handler for the WINCH signal, write::
         echo Got WINCH signal!
     end
 
-Please note that event handlers only become active when a function is loaded, which means you need to otherwise :ref:`source <cmd-source>` or execute a function instead of relying on :ref:`autoloading <syntax-function-autoloading>`. One approach is to put it into your :ref:`configuration file <configuration>`.
+Please note that event handlers only become active when a function is loaded, which means you need to otherwise :doc:`source <cmds/source>` or execute a function instead of relying on :ref:`autoloading <syntax-function-autoloading>`. One approach is to put it into your :ref:`configuration file <configuration>`.
 
-For more information on how to define new event handlers, see the documentation for the :ref:`function <cmd-function>` command.
+For more information on how to define new event handlers, see the documentation for the :doc:`function <cmds/function>` command.
 
 
 .. _debugging:
@@ -1704,6 +1704,6 @@ For more information on how to define new event handlers, see the documentation
 Debugging fish scripts
 ----------------------
 
-Fish includes a built-in debugging facility. The debugger allows you to stop execution of a script at an arbitrary point. When this happens you are presented with an interactive prompt. At this prompt you can execute any fish command (there are no debug commands as such). For example, you can check or change the value of any variables using :ref:`printf <cmd-printf>` and :ref:`set <cmd-set>`. As another example, you can run :ref:`status print-stack-trace <cmd-status>` to see how this breakpoint was reached. To resume normal execution of the script, simply type :ref:`exit <cmd-exit>` or :kbd:`Control`\ +\ :kbd:`D`.
+Fish includes a built-in debugging facility. The debugger allows you to stop execution of a script at an arbitrary point. When this happens you are presented with an interactive prompt. At this prompt you can execute any fish command (there are no debug commands as such). For example, you can check or change the value of any variables using :doc:`printf <cmds/printf>` and :doc:`set <cmds/set>`. As another example, you can run :doc:`status print-stack-trace <cmds/status>` to see how this breakpoint was reached. To resume normal execution of the script, simply type :doc:`exit <cmds/exit>` or :kbd:`Control`\ +\ :kbd:`D`.
 
-To start a debug session simply run the builtin command :ref:`breakpoint <cmd-breakpoint>` at the point in a function or script where you wish to gain control. Also, the default action of the TRAP signal is to call this builtin. So a running script can be debugged by sending it the TRAP signal with the ``kill`` command. Once in the debugger, it is easy to insert new breakpoints by using the funced function to edit the definition of a function.
+To start a debug session simply run the builtin command :doc:`breakpoint <cmds/breakpoint>` at the point in a function or script where you wish to gain control. Also, the default action of the TRAP signal is to call this builtin. So a running script can be debugged by sending it the TRAP signal with the ``kill`` command. Once in the debugger, it is easy to insert new breakpoints by using the funced function to edit the definition of a function.

doc_src/tutorial.rst

@@ -478,7 +478,7 @@ fish supports the familiar ``&&`` and ``||`` to combine commands, and ``!`` to n
 
 Here, ``make`` is only executed if ``./configure`` succeeds (returns 0), and ``sudo make install`` is only executed if both ``./configure`` and ``make`` succeed.
 
-fish also supports :ref:`and <cmd-and>`, :ref:`or <cmd-or>`, and :ref:`not <cmd-not>`. The first two are job modifiers and have lower precedence. Example usage::
+fish also supports :doc:`and <cmds/and>`, :doc:`or <cmds/or>`, and :doc:`not <cmds/not>`. The first two are job modifiers and have lower precedence. Example usage::
 
     > cp file1 file1_bak && cp file2 file2_bak; and echo "Backup successful"; or echo "Backup failed"
     Backup failed
@@ -495,7 +495,7 @@ As mentioned in :ref:`the section on the semicolon <tut-semicolon>`, this can al
 Conditionals (If, Else, Switch)
 -------------------------------
 
-Use :ref:`if <cmd-if>` and :ref:`else <cmd-else>` to conditionally execute code, based on the exit status of a command.
+Use :doc:`if <cmds/if>` and :doc:`else <cmds/else>` to conditionally execute code, based on the exit status of a command.
 
 
 ::
@@ -509,7 +509,7 @@ Use :ref:`if <cmd-if>` and :ref:`else <cmd-else>` to conditionally execute code,
     end
 
 
-To compare strings or numbers or check file properties (whether a file exists or is writeable and such), use :ref:`test <cmd-test>`, like
+To compare strings or numbers or check file properties (whether a file exists or is writeable and such), use :doc:`test <cmds/test>`, like
 
 
 ::
@@ -546,9 +546,9 @@ To compare strings or numbers or check file properties (whether a file exists or
     end
 
 
-For even more complex conditions, use :ref:`begin <cmd-begin>` and :ref:`end <cmd-end>` to group parts of them.
+For even more complex conditions, use :doc:`begin <cmds/begin>` and :doc:`end <cmds/end>` to group parts of them.
 
-There is also a :ref:`switch <cmd-switch>` command::
+There is also a :doc:`switch <cmds/switch>` command::
 
     switch (uname)
     case Linux
@@ -561,14 +561,14 @@ There is also a :ref:`switch <cmd-switch>` command::
         echo Hi, stranger!
     end
 
-As you see, :ref:`case <cmd-case>` does not fall through, and can accept multiple arguments or (quoted) wildcards.
+As you see, :doc:`case <cmds/case>` does not fall through, and can accept multiple arguments or (quoted) wildcards.
 
 For more, see :ref:`Conditions <syntax-conditional>`.
 
 Functions
 ---------
 
-A fish function is a list of commands, which may optionally take arguments. Unlike other shells, arguments are not passed in "numbered variables" like ``$1``, but instead in a single list ``$argv``. To create a function, use the :ref:`function <cmd-function>` builtin::
+A fish function is a list of commands, which may optionally take arguments. Unlike other shells, arguments are not passed in "numbered variables" like ``$1``, but instead in a single list ``$argv``. To create a function, use the :doc:`function <cmds/function>` builtin::
 
     function say_hello
         echo Hello $argv
@@ -581,7 +581,7 @@ A fish function is a list of commands, which may optionally take arguments. Unli
 
 Unlike other shells, fish does not have aliases or special prompt syntax. Functions take their place. [#]_
 
-You can list the names of all functions with the :ref:`functions <cmd-functions>` builtin (note the plural!). fish starts out with a number of functions::
+You can list the names of all functions with the :doc:`functions <cmds/functions>` builtin (note the plural!). fish starts out with a number of functions::
 
     > functions
     N_, abbr, alias, bg, cd, cdh, contains_seq, dirh, dirs, disown, down-or-search, edit_command_buffer, export, fg, fish_add_path, fish_breakpoint_prompt, fish_clipboard_copy, fish_clipboard_paste, fish_config, fish_default_key_bindings, fish_default_mode_prompt, fish_git_prompt, fish_hg_prompt, fish_hybrid_key_bindings, fish_indent, fish_is_root_user, fish_job_summary, fish_key_reader, fish_md5, fish_mode_prompt, fish_npm_helper, fish_opt, fish_print_git_action, fish_print_hg_root, fish_prompt, fish_sigtrap_handler, fish_svn_prompt, fish_title, fish_update_completions, fish_vcs_prompt, fish_vi_cursor, fish_vi_key_bindings, funced, funcsave, grep, help, history, hostname, isatty, kill, la, ll, ls, man, nextd, open, popd, prevd, prompt_hostname, prompt_pwd, psub, pushd, realpath, seq, setenv, suspend, trap, type, umask, up-or-search, vared, wait
@@ -597,7 +597,7 @@ You can see the source for any function by passing its name to ``functions``::
 
 For more, see :ref:`Functions <syntax-function>`.
 
-.. [#] There is a function called :ref:`alias <cmd-alias>`, but it's just a shortcut to make functions.
+.. [#] There is a function called :doc:`alias <cmds/alias>`, but it's just a shortcut to make functions.
 
 Loops
 -----
@@ -634,7 +634,7 @@ Prompt
 
 .. role:: purple
 
-Unlike other shells, there is no prompt variable like ``PS1``. To display your prompt, fish executes the :ref:`fish_prompt <cmd-fish_prompt>` function and uses its output as the prompt. And if it exists, fish also executes the :ref:`fish_right_prompt <cmd-fish_right_prompt>` function and uses its output as the right prompt.
+Unlike other shells, there is no prompt variable like ``PS1``. To display your prompt, fish executes the :doc:`fish_prompt <cmds/fish_prompt>` function and uses its output as the prompt. And if it exists, fish also executes the :doc:`fish_right_prompt <cmds/fish_right_prompt>` function and uses its output as the right prompt.
 
 You can define your own prompt from the command line:
 
@@ -647,7 +647,7 @@ You can define your own prompt from the command line:
 
 Then, if you are happy with it, you can save it to disk by typing ``funcsave fish_prompt``. This saves the prompt in ``~/.config/fish/functions/fish_prompt.fish``. (Or, if you want, you can create that file manually from the start.)
 
-Multiple lines are OK. Colors can be set via :ref:`set_color <cmd-set_color>`, passing it named ANSI colors, or hex RGB values::
+Multiple lines are OK. Colors can be set via :doc:`set_color <cmds/set_color>`, passing it named ANSI colors, or hex RGB values::
 
     function fish_prompt
         set_color purple
@@ -693,7 +693,7 @@ and it will be exported like that, and when fish starts it splits the $PATH it r
 
 You can do so directly in ``config.fish``, like you might do in other shells with ``.profile``. See :ref:`this example <path_example>`.
 
-A faster way is to use the :ref:`fish_add_path <cmd-fish_add_path>` function, which adds given directories to the path if they aren't already included. It does this by modifying the ``$fish_user_paths`` :ref:`universal variable <tut-universal>`, which is automatically prepended to ``$PATH``. For example, to permanently add ``/usr/local/bin`` to your ``$PATH``, you could write::
+A faster way is to use the :doc:`fish_add_path <cmds/fish_add_path>` function, which adds given directories to the path if they aren't already included. It does this by modifying the ``$fish_user_paths`` :ref:`universal variable <tut-universal>`, which is automatically prepended to ``$PATH``. For example, to permanently add ``/usr/local/bin`` to your ``$PATH``, you could write::
 
     > fish_add_path /usr/local/bin
 
@@ -749,7 +749,7 @@ This is the preferred way to define your prompt as well::
     end
 
 
-See the documentation for :ref:`funced <cmd-funced>` and :ref:`funcsave <cmd-funcsave>` for ways to create these files automatically, and :ref:`$fish_function_path <syntax-function-autoloading>` to control their location.
+See the documentation for :doc:`funced <cmds/funced>` and :doc:`funcsave <cmds/funcsave>` for ways to create these files automatically, and :ref:`$fish_function_path <syntax-function-autoloading>` to control their location.
 
 .. _tut-universal: