docs: Fix moar reference syntax

sphinx_doc_src/cmds/alias.rst

@@ -12,7 +12,7 @@ alias [OPTIONS] NAME=DEFINITION
 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 <a href='#function'>function</a>.
+``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 `function <cmds/function.html>`__.
 
 ``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``.
 
@@ -25,7 +25,7 @@ The following options are available:
 
 - ``-h`` or ``--help`` displays help about using this command.
 
-- ``-s`` or ``--save`` Automatically save the function created by the alias into your fish configuration directory using <a href='#funcsave'>funcsave</a>.
+- ``-s`` or ``--save`` Automatically save the function created by the alias into your fish configuration directory using `funcsave <cmds/funcsave.html>`__.
 
 Example
 -------

sphinx_doc_src/cmds/and.rst

@@ -12,9 +12,9 @@ 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 <a href="#if">``if``</a> or <a href="#while">``while``</a> block. See the documentation for <a href="#if">``if``</a> and <a href="#while">``while``</a> for examples.
+``and`` statements may be used as part of the condition in an `while <cmds/while.html>`__ or `if <cmds/if.html>`__ 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 <a href="index.html#variables-status">$status</a> variable.
+``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 `$status <index.html#variables-status>`__ variable.
 
 Example
 -------

sphinx_doc_src/cmds/argparse.rst

@@ -10,9 +10,9 @@ argparse [OPTIONS] OPTION_SPEC... -- [ARG...]
 Description
 -----------
 
-This command makes it easy for fish scripts and functions to handle arguments in a manner 100% identical to how fish builtin commands handle their arguments. You pass a sequence of arguments that define the options recognized, followed by a literal ``--``, then the arguments to be parsed (which might also include a literal ``--``). More on this in the <a href="#argparse-usage">usage</a> section below.
+This command makes it easy for fish scripts and functions to handle arguments in a manner 100% identical to how fish builtin commands handle their arguments. You pass a sequence of arguments that define the options recognized, followed by a literal ``--``, then the arguments to be parsed (which might also include a literal ``--``). More on this in the `usage <#argparse-usage>`__ section below.
 
-Each OPTION_SPEC can be written in the domain specific language <a href="#argparse-option-specs">described below</a> or created using the companion <a href="#fish-opt">``fish_opt``</a> command. All OPTION_SPECs must appear after any argparse flags and before the ``--`` that separates them from the arguments to be parsed.
+Each OPTION_SPEC can be written in the `domain specific language <#argparse-option-specs>`__ described below or created using the companion `fish_opt <cmds/fish-opt.html>`__ command. All OPTION_SPECs must appear after any argparse flags and before the ``--`` that separates them from the arguments to be parsed.
 
 Each option that is seen in the ARG list will result in a var name of the form ``_flag_X``, where ``X`` is the short flag letter and the long flag name. The OPTION_SPEC always requires a short flag even if it can't be used. So there will always be ``_flag_X`` var set using the short flag letter if the corresponding short or long flag is seen. The long flag name var (e.g., ``_flag_help``) will only be defined, obviously, if the OPTION_SPEC includes a long flag name.
 
@@ -48,7 +48,7 @@ Using this command involves passing two sets of arguments separated by ``--``. T
     or return
 
 
-If ``$argv`` is empty then there is nothing to parse and ``argparse`` returns zero to indicate success. If ``$argv`` is not empty then it is checked for flags ``-h``, ``--help``, ``-n`` and ``--name``. If they are found they are removed from the arguments and local variables (more on this <a href="argparse-local-variables">below</a>) are set so the script can determine which options were seen. Assuming ``$argv`` doesn't have any errors, such as a missing mandatory value for an option, then ``argparse`` exits with status zero. Otherwise it writes appropriate error messages to stderr and exits with a status of one.
+If ``$argv`` is empty then there is nothing to parse and ``argparse`` returns zero to indicate success. If ``$argv`` is not empty then it is checked for flags ``-h``, ``--help``, ``-n`` and ``--name``. If they are found they are removed from the arguments and local variables (more on this `below <argparse-local-variables>`__) are set so the script can determine which options were seen. Assuming ``$argv`` doesn't have any errors, such as a missing mandatory value for an option, then ``argparse`` exits with status zero. Otherwise it writes appropriate error messages to stderr and exits with a status of one.
 
 The ``--`` argument is required. You do not have to include any arguments after the ``--`` but you must include the ``--``. For example, this is acceptable:
 
@@ -91,9 +91,9 @@ Each option specification is a string composed of
 
 - ``=+`` if it requires a value and each instance of the flag is saved.
 
-- Optionally a ``!`` followed by fish script to validate the value. Typically this will be a function to run. If the return 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 <a href="#arparse-validation">Flag Value Validation</a> for more information.
+- Optionally a ``!`` followed by fish script to validate the value. Typically this will be a function to run. If the return 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 `Flag Value Validation <#arparse-validation>`__ for more information.
 
-See the <a href="#fish-opt">``fish_opt``</a> command for a friendlier but more verbose way to create option specifications.
+See the `fish_opt <cmds/fish-opt.html>`__ command for a friendlier but more verbose way to create option specifications.
 
 In the following examples if a flag is not seen when parsing the arguments then the corresponding _flag_X var(s) will not be set.
 

sphinx_doc_src/cmds/bg.rst

@@ -10,7 +10,7 @@ bg [PID...]
 Description
 -----------
 
-``bg`` sends <a href="index.html#syntax-job-control">jobs</a> to the background, resuming them if they are stopped.
+``bg`` sends `jobs <index.html#syntax-job-control>`__ to the background, resuming them if they are stopped.
 
 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 with the specified process group IDs are put in the background.
 

sphinx_doc_src/cmds/bind.rst

@@ -22,7 +22,7 @@ Description
 
 ``bind`` adds a binding for the specified key sequence to the specified command.
 
-SEQUENCE is the character sequence to bind to. These should be written as <a href="index.html#escapes">fish escape sequences</a>. For example, because pressing the Alt key and another character sends that character prefixed with an escape character, Alt-based key bindings can be written using the ``\e`` escape. For example, :kbd:`Alt+w` can be written as ``\ew``. The control character can be written in much the same way using the ``\c`` escape, for example :kbd:`Control+X` (^X) can be written as ``\cx``. Note that Alt-based key bindings are case sensitive and Control-based key bindings are not. This is a constraint of text-based terminals, not ``fish``.
+SEQUENCE is the character sequence to bind to. These should be written as `fish escape sequences <index.html#escapes>`__. For example, because pressing the Alt key and another character sends that character prefixed with an escape character, Alt-based key bindings can be written using the ``\e`` escape. For example, :kbd:`Alt+w` can be written as ``\ew``. The control character can be written in much the same way using the ``\c`` escape, for example :kbd:`Control+X` (^X) can be written as ``\cx``. Note that Alt-based key bindings are case sensitive and Control-based key bindings are not. This is a constraint of text-based terminals, not ``fish``.
 
 The default key binding can be set by specifying a ``SEQUENCE`` of the empty string (that is, ``''`` ). It will be used whenever no other binding matches. For most key bindings, it makes sense to use the ``self-insert`` function (i.e. ``````bind '' self-insert``````) as the default keybinding. This will insert any keystrokes not specifically bound to into the editor. Non- printable characters are ignored by the editor, so this will not result in control sequences being printable.
 
@@ -30,7 +30,7 @@ If the ``-k`` switch is used, the name of the key (such as 'down', 'up' or 'back
 
 ``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.
 
-When ``COMMAND`` is a shellscript command, it is a good practice to put the actual code into a <a href="#function">function</a> and simply bind to the function name. This way it becomes significantly easier to test the function while editing, and the result is usually more readable as well.
+When ``COMMAND`` is a shellscript command, it is a good practice to put the actual code into a `function <#function>`__ and simply bind to the function name. This way it becomes significantly easier to test the function while editing, and the result is usually more readable as well.
 
 If a script produces output, it should finish by calling ``commandline -f repaint`` to tell fish that a repaint is in order.
 
@@ -38,7 +38,7 @@ When multiple ``COMMAND``s are provided, they are all run in the specified order
 
 If no ``SEQUENCE`` is provided, all bindings (or just the bindings in the specified ``MODE``) are printed. If ``SEQUENCE`` is provided without ``COMMAND``, just the binding matching that sequence is printed.
 
-To save custom keybindings, put the ``bind`` statements into <a href="index.html#initialization">config.fish</a>. Alternatively, fish also automatically executes a function called ``fish_user_key_bindings`` if it exists.
+To save custom keybindings, put the ``bind`` statements into `config.fish <index.html#initialization>`__. Alternatively, fish also automatically executes a function called ``fish_user_key_bindings`` if it exists.
 
 Key bindings may use "modes", which mimics Vi's modal input behavior. The default mode is "default", and every bind applies to a single mode. The mode can be viewed/changed with the ``$fish_bind_mode`` variable.
 

sphinx_doc_src/cmds/block.rst

@@ -10,7 +10,7 @@ block [OPTIONS...]
 Description
 -----------
 
-``block`` prevents events triggered by ``fish`` or the <a href="commands.html#emit">``emit``</a> command from being delivered and acted upon while the block is in place.
+``block`` prevents events triggered by ``fish`` or the `emit <cmds/emit.html>`__ 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.
 

sphinx_doc_src/cmds/break.rst

@@ -10,7 +10,7 @@ LOOP_CONSTRUCT; [COMMANDS...] break; [COMMANDS...] end
 Description
 -----------
 
-``break`` halts a currently running loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement.
+``break`` halts a currently running loop, such as a `switch <cmds/switch.html>`__, `for <cmds/for.html>`__ or `while <cmds/while.html>`__ loop. It is usually added inside of a conditional block such as an `if <cmds/if.html`__ block.
 
 There are no parameters for ``break``.
 

sphinx_doc_src/cmds/breakpoint.rst

@@ -12,6 +12,6 @@ Description
 
 ``breakpoint`` is used to halt a running script and launch an interactive debugging prompt.
 
-For more details, see <a href="index.html#debugging">Debugging fish scripts</a> in the ``fish`` manual.
+For more details, see `Debugging fish scripts <index.html#debugging>`__ in the ``fish`` manual.
 
 There are no parameters for ``breakpoint``.

sphinx_doc_src/cmds/cd.rst

@@ -17,7 +17,7 @@ If ``DIRECTORY`` is a relative path, the paths found in the ``CDPATH`` list will
 
 Note that the shell will attempt to change directory without requiring ``cd`` if the name of a directory is provided (starting with ``.``, ``/`` or ``~``, or ending with ``/``).
 
-Fish also ships a wrapper function around the builtin ``cd`` that understands ``cd -`` as changing to the previous directory. See also <a href="commands.html#prevd">``prevd``</a>. 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.
+Fish also ships a wrapper function around the builtin ``cd`` that understands ``cd -`` as changing to the previous directory. See also `prevd <cmds/prevd.html>`__. 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.
 
 As a special case, ``cd .`` is equivalent to ``cd $PWD``, which is useful in cases where a mountpoint has been recycled or a directory has been removed and recreated.
 
@@ -38,4 +38,4 @@ Examples
 See Also
 --------
 
-See also the <a href="commands.html#cdh">``cdh``</a> command for changing to a recently visited directory.
+See also the `cdh <cmds/cdh.html>`__ command for changing to a recently visited directory.

sphinx_doc_src/cmds/disown.rst

@@ -10,7 +10,7 @@ Synopsis
 Description
 -----------
 
-``disown`` removes the specified <a href="index.html#syntax-job-control">job</a> from the list of jobs. The job itself continues to exist, but fish does not keep track of it any longer.
+``disown`` removes the specified `job <index.html#syntax-job-control>`__ from the list of jobs. The job itself continues to exist, but fish does not keep track of it any longer.
 
 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.
 

sphinx_doc_src/cmds/exit.rst

@@ -12,4 +12,4 @@ Description
 
 ``exit`` causes fish to exit. If ``STATUS`` is supplied, it will be converted to an integer and used as the exit code. Otherwise, the exit code will be that of the last command executed.
 
-If exit is called while sourcing a file (using the <a href="#source">source</a> 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 `source <cmds/source.html>`__ builtin) the rest of the file will be skipped, but the shell itself will not exit.

sphinx_doc_src/cmds/fg.rst

@@ -10,7 +10,7 @@ fg [PID]
 Description
 -----------
 
-``fg`` brings the specified <a href="index.html#syntax-job-control">job</a> to the foreground, resuming it if it is stopped. While a foreground job is executed, fish is suspended. If no job is specified, the last job to be used is put in the foreground. If PID is specified, the job with the specified group ID is put in the foreground.
+``fg`` brings the specified `job <index.html#syntax-job-control>`__ to the foreground, resuming it if it is stopped. While a foreground job is executed, fish is suspended. If no job is specified, the last job to be used is put in the foreground. If PID is specified, the job with the specified group ID is put in the foreground.
 
 
 Example

sphinx_doc_src/cmds/fish_breakpoint_prompt.rst

@@ -16,7 +16,7 @@ Description
 
 By defining the ``fish_breakpoint_prompt`` function, the user can choose a custom prompt when asking for input in response to a ``breakpoint`` command. The ``fish_breakpoint_prompt`` function is executed when the prompt is to be shown, and the output is used as a prompt.
 
-The exit status of commands within ``fish_breakpoint_prompt`` will not modify the value of <a href="index.html#variables-status">$status</a> outside of the ``fish_breakpoint_prompt`` function.
+The exit status of commands within ``fish_breakpoint_prompt`` will not modify the value of `$status <index.html#variables-status>`__ outside of the ``fish_breakpoint_prompt`` function.
 
 ``fish`` ships with a default version of this function that displays the function name and line number of the current execution context.
 

sphinx_doc_src/cmds/fish_opt.rst

@@ -13,7 +13,7 @@ Synopsis
 Description
 -----------
 
-This command provides a way to produce option specifications suitable for use with the <a href="#argparse">``argparse``</a> command. You can, of course, write the option specs by hand without using this command. But you might prefer to use this for the clarity it provides.
+This command provides a way to produce option specifications suitable for use with the `argparse <cmds/argparse.html>`__ command. You can, of course, write the option specs by hand without using this command. But you might prefer to use this for the clarity it provides.
 
 The following ``argparse`` options are available:
 

sphinx_doc_src/cmds/fish_prompt.rst

@@ -16,7 +16,7 @@ Description
 
 By defining the ``fish_prompt`` function, the user can choose a custom prompt. The ``fish_prompt`` function is executed when the prompt is to be shown, and the output is used as a prompt.
 
-The exit status of commands within ``fish_prompt`` will not modify the value of <a href="index.html#variables-status">$status</a> outside of the ``fish_prompt`` function.
+The exit status of commands within ``fish_prompt`` will not modify the value of `$status <index.html#variables-status>`__ outside of the ``fish_prompt`` function.
 
 ``fish`` ships with a number of example prompts that can be chosen with the ``fish_config`` command.
 

sphinx_doc_src/cmds/function.rst

@@ -20,7 +20,7 @@ The following options are available:
 
 - ``-d DESCRIPTION`` or ``--description=DESCRIPTION`` is a description of what the function does, suitable as a completion description.
 
-- ``-w WRAPPED_COMMAND`` or ``--wraps=WRAPPED_COMMAND`` causes the function to inherit completions from the given wrapped command. See the documentation for <a href="#complete">``complete``</a> for more information.
+- ``-w WRAPPED_COMMAND`` or ``--wraps=WRAPPED_COMMAND`` causes the function to inherit completions from the given wrapped command. See the documentation for `complete <cmds/complete.html>`__ for more information.
 
 - ``-e`` or ``--on-event EVENT_NAME`` tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt.
 
@@ -39,9 +39,9 @@ The following options are available:
 
 - ``-V`` or ``--inherit-variable NAME`` snapshots the value of the variable ``NAME`` and defines a local variable with that same name and value when the function is defined. This is similar to a closure in other languages like Python but a bit different. Note the word "snapshot" in the first sentence. If you change the value of the variable after defining the function, even if you do so in the same scope (typically another function) the new value will not be used by the function you just created using this option. See the ``function notify`` example below for how this might be used.
 
-If the user enters any additional arguments after the function, they are inserted into the environment <a href="index.html#variables-arrays">variable array</a> ``$argv``. If the ``--argument-names`` option is provided, the arguments are also assigned to names specified in that option.
+If the user enters any additional arguments after the function, they are inserted into the environment `variable array <index.html#variables-arrays>`__ ``$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 <a href="#emit">emit</a> 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 `emit <cmds/emit.html>`__ builtin. Fish generates the following named events:
 
 - ``fish_prompt``, which is emitted whenever a new fish prompt is about to be displayed.
 

sphinx_doc_src/cmds/jobs.rst

@@ -10,7 +10,7 @@ jobs [OPTIONS] [PID]
 Description
 -----------
 
-``jobs`` prints a list of the currently running <a href="index.html#syntax-job-control">jobs</a> and their status.
+``jobs`` prints a list of the currently running `jobs <index.html#syntax-job-control>`__ and their status.
 
 jobs accepts the following switches:
 

sphinx_doc_src/faq.rst

@@ -241,7 +241,7 @@ Fish history recall is very simple yet effective:
 
   - If you want to reuse several arguments from the same line ("!!:3*" and the like), consider recalling the whole line and removing what you don't need (:kbd:`Alt+D` and :kbd:`Alt+Backspace` are your friends).
 
-See <a href='index.html#editor'>documentation</a> for more details about line editing in fish.
+See `documentation <index.html#editor>`__ for more details about line editing in fish.
 
 
 How can I use ``-`` as a shortcut for ``cd -``?
@@ -266,7 +266,7 @@ Next, do the following (assuming fish was installed to /usr/local)::
 
 Unicode private-use characters reserved by fish
 -----------------------------------------------
-Fish reserves the <a href="http://www.unicode.org/faq/private_use.html">Unicode private-use character range</a> from U+F600 thru U+F73F for internal use. Any attempt to feed characters in that range to fish will result in them being replaced by the Unicode "replacement character" U+FFFD. This includes both interactive input as well as any file read by fish (but not programs run by fish).
+Fish reserves the `Unicode private-use character range <http://www.unicode.org/faq/private_use.html>`__ from U+F600 thru U+F73F for internal use. Any attempt to feed characters in that range to fish will result in them being replaced by the Unicode "replacement character" U+FFFD. This includes both interactive input as well as any file read by fish (but not programs run by fish).
 
 
 Where can I find extra tools for fish?

sphinx_doc_src/tutorial.rst

@@ -419,7 +419,7 @@ fish also supports ``and``, ``or``, and ``not``. The first two are job modifiers
     <outp>Backup failed</outp>
 
 
-As mentioned in <a href="#tut_semicolon">the section on the semicolon</a>, this can also be written in multiple lines, like so::
+As mentioned in `the section on the semicolon <#tut_semicolon>`__, this can also be written in multiple lines, like so::
 
     cp file1.txt file1_bak.txt && cp file2.txt file2_bak.txt
     and echo "Backup successful"
@@ -464,7 +464,7 @@ To compare strings or numbers or check file properties (whether a file exists or
     end
 
 
-<a href="#tut_combiners">Combiners</a> can also be used to make more complex conditions, like
+`Combiners <#tut_combiners>`__ can also be used to make more complex conditions, like