Docs: Switch back to vanilla :ref: for commands that should be linked

Unfortunately, currently :program: doesn't link to the program's page.

So we use the old-school :ref: again where we should link, i.e. for
everything that's not the program the current page is about.

Fixes #8438

doc_src/cmds/exit.rst

@@ -1,3 +1,4 @@
+.. _cmd-exit:
 .. program::exit
 
 exit - exit the shell
@@ -14,4 +15,4 @@ 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 :program:`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 :ref:`source <cmd-source>` builtin) the rest of the file will be skipped, but the shell itself will not exit.

doc_src/cmds/fish.rst

@@ -1,3 +1,4 @@
+.. _cmd-fish:
 .. program::fish
 
 fish - the friendly interactive shell

doc_src/cmds/fish_add_path.rst

@@ -1,3 +1,4 @@
+.. _cmd-fish_add_path:
 .. program::fish_add_path
 
 fish_add_path - add to the path
@@ -18,7 +19,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 :program:`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 :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 added in the order they are given, and they are prepended to the path unless ``--append`` is given (if $fish_user_paths is used, that means they are last in $fish_user_paths, which is itself prepended to $PATH, so they still stay ahead of the system paths).
 

doc_src/cmds/fish_indent.rst

@@ -1,3 +1,4 @@
+.. _cmd-fish_indent:
 .. program::fish_indent
 
 fish_indent - indenter and prettifier
@@ -28,7 +29,7 @@ The following options are available:
 
 - ``--html`` 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 :program:`fish` (1) for details.
+- ``-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.
 
 - ``-o`` or ``--debug-output=DEBUG_FILE`` specify a file path to receive the debug output, including categories and ``fish_trace``. The default is stderr.
 

doc_src/cmds/realpath.rst

@@ -1,3 +1,4 @@
+.. _cmd-realpath:
 .. program::realpath
 
 realpath - convert a path to an absolute path without symlinks
@@ -11,7 +12,7 @@ Synopsis
 Description
 -----------
 
-:program:`realpath` follows all symbolic links encountered for the provided :envvar:`PATH`, printing the absolute path resolved. :program:`fish` provides a :command:`realpath`-alike builtin intended to be 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. :ref:`fish <cmd-fish>` provides a :command:`realpath`-alike builtin intended to be 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

@@ -1,3 +1,4 @@
+.. _cmd-return:
 .. program::return:
 
 return - stop the current inner function
@@ -15,9 +16,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 :program:`if` statement or a :program:`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 :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.
 
-If at the top level of a script, it exits with the given status, like :program:`exit`.
+If at the top level of a script, it exits with the given status, like :ref:`exit <cmd-exit>`.
 If at the top level in an interactive session, it will set :envvar:`status`, but not exit the shell.
 
 Example

doc_src/commands.rst

@@ -16,7 +16,7 @@ Core language keywords that make up the syntax, like
 - :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.
-- :program:`return` to return a status from a function.
+- :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.
@@ -81,7 +81,7 @@ Helper commands
 
 fish also ships some things as external commands so they can be easily called from elsewhere.
 
-This includes :program:`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 :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.
 
 The full list
 ^^^^^^^^^^^^^

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
 
-:program:`echo` command writes its arguments to the screen. In this example the output is ``hello world``.
+:ref:`echo <cmd-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.
 
@@ -1571,6 +1571,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 :program:`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 :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`.
 
 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.