docs: Add labels to all commands

This allows us to use :ref: references, which don't require hardcoding
it as html

[ci skip]

sphinx_doc_src/cmds/abbr.rst

@@ -1,3 +1,5 @@
+.. _cmd-abbr:
+
 abbr - manage fish abbreviations
 ================================
 

sphinx_doc_src/cmds/alias.rst

@@ -1,3 +1,5 @@
+.. _cmd-alias:
+
 alias - create a function
 =========================
 

sphinx_doc_src/cmds/and.rst

@@ -1,3 +1,5 @@
+.. _cmd-and:
+
 and - conditionally execute a command
 =====================================
 

sphinx_doc_src/cmds/argparse.rst

@@ -1,3 +1,5 @@
+.. _cmd-argparse:
+
 argparse - parse options passed to a fish script or function
 ============================================================
 

sphinx_doc_src/cmds/begin.rst

@@ -1,3 +1,5 @@
+.. _cmd-begin:
+
 begin - start a new block of code
 =================================
 

sphinx_doc_src/cmds/bg.rst

@@ -1,3 +1,5 @@
+.. _cmd-bg:
+
 bg - send jobs to background
 ============================
 

sphinx_doc_src/cmds/bind.rst

@@ -1,3 +1,5 @@
+.. _cmd-bind:
+
 bind - handle fish key bindings
 ===============================
 

sphinx_doc_src/cmds/block.rst

@@ -1,3 +1,5 @@
+.. _cmd-block:
+
 block - temporarily block delivery of events
 ============================================
 

sphinx_doc_src/cmds/break.rst

@@ -1,3 +1,5 @@
+.. _cmd-break:
+
 break - stop the current inner loop
 ===================================
 

sphinx_doc_src/cmds/breakpoint.rst

@@ -1,3 +1,5 @@
+.. _cmd-breakpoint:
+
 breakpoint - Launch debug mode
 ==============================
 

sphinx_doc_src/cmds/builtin.rst

@@ -1,3 +1,5 @@
+.. _cmd-builtin:
+
 builtin - run a builtin command
 ===============================
 

sphinx_doc_src/cmds/case.rst

@@ -1,3 +1,5 @@
+.. _cmd-case:
+
 case - conditionally execute a block of commands
 ================================================
 

sphinx_doc_src/cmds/cd.rst

@@ -1,3 +1,5 @@
+.. _cmd-cd:
+
 cd - change directory
 =====================
 

sphinx_doc_src/cmds/cdh.rst

@@ -1,3 +1,5 @@
+.. _cmd-cdh:
+
 cdh - change to a recently visited directory
 ============================================
 

sphinx_doc_src/cmds/command.rst

@@ -1,3 +1,5 @@
+.. _cmd-command:
+
 command - run a program
 =======================
 

sphinx_doc_src/cmds/commandline.rst

@@ -1,3 +1,5 @@
+.. _cmd-commandline:
+
 commandline - set or get the current command line buffer
 ========================================================
 

sphinx_doc_src/cmds/complete.rst

@@ -1,3 +1,5 @@
+.. _cmd-complete:
+
 complete - edit command specific tab-completions
 ================================================
 

sphinx_doc_src/cmds/contains.rst

@@ -1,3 +1,5 @@
+.. _cmd-contains:
+
 contains - test if a word is present in a list
 ==============================================
 

sphinx_doc_src/cmds/continue.rst

@@ -1,3 +1,5 @@
+.. _cmd-continue:
+
 continue - skip the remainder of the current iteration of the current inner loop
 ================================================================================
 

sphinx_doc_src/cmds/count.rst

@@ -1,3 +1,5 @@
+.. _cmd-count:
+
 count - count the number of elements of an array
 ================================================
 

sphinx_doc_src/cmds/dirh.rst

@@ -1,3 +1,5 @@
+.. _cmd-dirh:
+
 dirh - print directory history
 ==============================
 

sphinx_doc_src/cmds/dirs.rst

@@ -1,3 +1,5 @@
+.. _cmd-dirs:
+
 dirs - print directory stack
 ============================
 

sphinx_doc_src/cmds/disown.rst

@@ -1,3 +1,5 @@
+.. _cmd-disown:
+
 disown - remove a process from the list of jobs
 ===============================================
 

sphinx_doc_src/cmds/echo.rst

@@ -1,3 +1,5 @@
+.. _cmd-echo:
+
 echo - display a line of text
 =============================
 

sphinx_doc_src/cmds/else.rst

@@ -1,3 +1,5 @@
+.. _cmd-else:
+
 else - execute command if a condition is not met
 ================================================
 

sphinx_doc_src/cmds/emit.rst

@@ -1,3 +1,5 @@
+.. _cmd-emit:
+
 emit - Emit a generic event
 ===========================
 

sphinx_doc_src/cmds/end.rst

@@ -1,3 +1,5 @@
+.. _cmd-end:
+
 end - end a block of commands.
 ==============================
 

sphinx_doc_src/cmds/eval.rst

@@ -1,3 +1,5 @@
+.. _cmd-eval:
+
 eval - evaluate the specified commands
 ======================================
 

sphinx_doc_src/cmds/exec.rst

@@ -1,3 +1,5 @@
+.. _cmd-exec:
+
 exec - execute command in current process
 =========================================
 

sphinx_doc_src/cmds/exit.rst

@@ -1,3 +1,5 @@
+.. _cmd-exit:
+
 exit - exit the shell
 =====================
 

sphinx_doc_src/cmds/false.rst

@@ -1,3 +1,5 @@
+.. _cmd-false:
+
 false - return an unsuccessful result
 =====================================
 

sphinx_doc_src/cmds/fg.rst

@@ -1,3 +1,5 @@
+.. _cmd-fg:
+
 fg - bring job to foreground
 ============================
 

sphinx_doc_src/cmds/fish.rst

@@ -1,3 +1,5 @@
+.. _cmd-fish:
+
 fish - the friendly interactive shell
 =====================================
 

sphinx_doc_src/cmds/fish_breakpoint_prompt.rst

@@ -1,3 +1,5 @@
+.. _cmd-fish_breakpoint_prompt:
+
 fish_breakpoint_prompt - define the prompt when stopped at a breakpoint
 =======================================================================
 

sphinx_doc_src/cmds/fish_config.rst

@@ -1,3 +1,5 @@
+.. _cmd-fish_config:
+
 fish_config - start the web-based configuration interface
 =========================================================
 

sphinx_doc_src/cmds/fish_git_prompt.rst

@@ -1,3 +1,5 @@
+.. _cmd-fish_git_prompt:
+
 fish_git_prompt - output git information for use in a prompt
 ============================================================
 

sphinx_doc_src/cmds/fish_hg_prompt.rst

@@ -1,3 +1,5 @@
+.. _cmd-fish_hg_prompt:
+
 fish_hg_prompt - output mercurial information for use in a prompt
 =================================================================
 

sphinx_doc_src/cmds/fish_indent.rst

@@ -1,3 +1,5 @@
+.. _cmd-fish_indent:
+
 fish_indent - indenter and prettifier
 =====================================
 

sphinx_doc_src/cmds/fish_key_reader.rst

@@ -1,3 +1,5 @@
+.. _cmd-fish_key_reader:
+
 fish_key_reader - explore what characters keyboard keys send
 ============================================================
 

sphinx_doc_src/cmds/fish_mode_prompt.rst

@@ -1,3 +1,5 @@
+.. _cmd-fish_mode_prompt:
+
 fish_mode_prompt - define the appearance of the mode indicator
 ==============================================================
 

sphinx_doc_src/cmds/fish_opt.rst

@@ -1,3 +1,5 @@
+.. _cmd-fish_opt:
+
 fish_opt - create an option spec for the argparse command
 =========================================================
 

sphinx_doc_src/cmds/fish_prompt.rst

@@ -1,3 +1,5 @@
+.. _cmd-fish_prompt:
+
 fish_prompt - define the appearance of the command line prompt
 ==============================================================
 

sphinx_doc_src/cmds/fish_right_prompt.rst

@@ -1,3 +1,5 @@
+.. _cmd-fish_right_prompt:
+
 fish_right_prompt - define the appearance of the right-side command line prompt
 ===============================================================================
 

sphinx_doc_src/cmds/fish_svn_prompt.rst

@@ -1,3 +1,5 @@
+.. _cmd-fish_svn_prompt:
+
 fish_svn_prompt - output svn information for use in a prompt
 ============================================================
 

sphinx_doc_src/cmds/fish_update_completions.rst

@@ -1,3 +1,5 @@
+.. _cmd-fish_update_completions:
+
 fish_update_completions - Update completions using manual pages
 ===============================================================
 

sphinx_doc_src/cmds/fish_vcs_prompt.rst

@@ -1,3 +1,5 @@
+.. _cmd-fish_vcs_prompt:
+
 fish_vcs_prompt - output vcs information for use in a prompt
 ============================================================
 

sphinx_doc_src/cmds/fish_vi_mode.rst

@@ -1,3 +1,5 @@
+.. _cmd-fish_vi_mode:
+
 fish_vi_mode - Enable vi mode
 =============================
 

sphinx_doc_src/cmds/for.rst

@@ -1,3 +1,5 @@
+.. _cmd-for:
+
 for - perform a set of commands multiple times.
 ===============================================
 

sphinx_doc_src/cmds/funced.rst

@@ -1,3 +1,5 @@
+.. _cmd-funced:
+
 funced - edit a function interactively
 ======================================
 

sphinx_doc_src/cmds/funcsave.rst

@@ -1,3 +1,5 @@
+.. _cmd-funcsave:
+
 funcsave - save the definition of a function to the user's autoload directory
 =============================================================================
 

sphinx_doc_src/cmds/function.rst

@@ -1,3 +1,5 @@
+.. _cmd-function:
+
 function - create a function
 ============================
 

sphinx_doc_src/cmds/functions.rst

@@ -1,3 +1,5 @@
+.. _cmd-functions:
+
 functions - print or erase functions
 ====================================
 

sphinx_doc_src/cmds/help.rst

@@ -1,3 +1,5 @@
+.. _cmd-help:
+
 help - display fish documentation
 =================================
 

sphinx_doc_src/cmds/history.rst

@@ -1,3 +1,5 @@
+.. _cmd-history:
+
 history - Show and manipulate command history
 =============================================
 

sphinx_doc_src/cmds/if.rst

@@ -1,3 +1,5 @@
+.. _cmd-if:
+
 if - conditionally execute a command
 ====================================
 

sphinx_doc_src/cmds/isatty.rst

@@ -1,3 +1,5 @@
+.. _cmd-isatty:
+
 isatty - test if a file descriptor is a tty.
 ============================================
 

sphinx_doc_src/cmds/jobs.rst

@@ -1,3 +1,5 @@
+.. _cmd-jobs:
+
 jobs - print currently running jobs
 ===================================
 

sphinx_doc_src/cmds/math.rst

@@ -1,3 +1,5 @@
+.. _cmd-math:
+
 math - Perform mathematics calculations
 =======================================
 

sphinx_doc_src/cmds/nextd.rst

@@ -1,3 +1,5 @@
+.. _cmd-nextd:
+
 nextd - move forward through directory history
 ==============================================
 

sphinx_doc_src/cmds/not.rst

@@ -1,3 +1,5 @@
+.. _cmd-not:
+
 not - negate the exit status of a job
 =====================================
 

sphinx_doc_src/cmds/open.rst

@@ -1,3 +1,5 @@
+.. _cmd-open:
+
 open - open file in its default application
 ===========================================
 

sphinx_doc_src/cmds/or.rst

@@ -1,3 +1,5 @@
+.. _cmd-or:
+
 or - conditionally execute a command
 ====================================
 

sphinx_doc_src/cmds/popd.rst

@@ -1,3 +1,5 @@
+.. _cmd-popd:
+
 popd - move through directory stack
 ===================================
 

sphinx_doc_src/cmds/prevd.rst

@@ -1,3 +1,5 @@
+.. _cmd-prevd:
+
 prevd - move backward through directory history
 ===============================================
 

sphinx_doc_src/cmds/printf.rst

@@ -1,3 +1,5 @@
+.. _cmd-printf:
+
 printf - display text according to a format string
 ==================================================
 

sphinx_doc_src/cmds/prompt_pwd.rst

@@ -1,3 +1,5 @@
+.. _cmd-prompt_pwd:
+
 prompt_pwd - Print pwd suitable for prompt
 ==========================================
 

sphinx_doc_src/cmds/psub.rst

@@ -1,3 +1,5 @@
+.. _cmd-psub:
+
 psub - perform process substitution
 ===================================
 

sphinx_doc_src/cmds/pushd.rst

@@ -1,3 +1,5 @@
+.. _cmd-pushd:
+
 pushd - push directory to directory stack
 =========================================
 

sphinx_doc_src/cmds/pwd.rst

@@ -1,3 +1,5 @@
+.. _cmd-pwd:
+
 pwd - output the current working directory
 ==========================================
 

sphinx_doc_src/cmds/random.rst

@@ -1,3 +1,5 @@
+.. _cmd-random:
+
 random - generate random number
 ===============================
 

sphinx_doc_src/cmds/read.rst

@@ -1,3 +1,5 @@
+.. _cmd-read:
+
 read - read line of input into variables
 ========================================
 

sphinx_doc_src/cmds/realpath.rst

@@ -1,3 +1,5 @@
+.. _cmd-realpath:
+
 realpath - Convert a path to an absolute path without symlinks
 ==============================================================
 

sphinx_doc_src/cmds/return.rst

@@ -1,3 +1,5 @@
+.. _cmd-return:
+
 return - stop the current inner function
 ========================================
 

sphinx_doc_src/cmds/set.rst

@@ -1,3 +1,5 @@
+.. _cmd-set:
+
 set - display and change shell variables.
 =========================================
 

sphinx_doc_src/cmds/set_color.rst

@@ -1,3 +1,5 @@
+.. _cmd-set_color:
+
 set_color - set the terminal color
 ==================================
 

sphinx_doc_src/cmds/source.rst

@@ -1,3 +1,5 @@
+.. _cmd-source:
+
 source - evaluate contents of file.
 ===================================
 

sphinx_doc_src/cmds/status.rst

@@ -1,3 +1,5 @@
+.. _cmd-status:
+
 status - query fish runtime information
 =======================================
 

sphinx_doc_src/cmds/string.rst

@@ -1,3 +1,5 @@
+.. _cmd-string:
+
 string - manipulate strings
 ===========================
 

sphinx_doc_src/cmds/suspend.rst

@@ -1,3 +1,5 @@
+.. _cmd-suspend:
+
 suspend - suspend the current shell
 ===================================
 

sphinx_doc_src/cmds/switch.rst

@@ -1,3 +1,5 @@
+.. _cmd-switch:
+
 switch - conditionally execute a block of commands
 ==================================================
 

sphinx_doc_src/cmds/test.rst

@@ -1,3 +1,5 @@
+.. _cmd-test:
+
 test - perform tests on files and text
 ======================================
 

sphinx_doc_src/cmds/trap.rst

@@ -1,3 +1,5 @@
+.. _cmd-trap:
+
 trap - perform an action when the shell receives a signal
 =========================================================
 

sphinx_doc_src/cmds/true.rst

@@ -1,3 +1,5 @@
+.. _cmd-true:
+
 true - return a successful result
 =================================
 

sphinx_doc_src/cmds/type.rst

@@ -1,3 +1,5 @@
+.. _cmd-type:
+
 type - indicate how a command would be interpreted
 ==================================================
 

sphinx_doc_src/cmds/ulimit.rst

@@ -1,3 +1,5 @@
+.. _cmd-ulimit:
+
 ulimit - set or get resource usage limits
 =========================================
 

sphinx_doc_src/cmds/umask.rst

@@ -1,3 +1,5 @@
+.. _cmd-umask:
+
 umask - set or get the file creation mode mask
 ==============================================
 

sphinx_doc_src/cmds/vared.rst

@@ -1,3 +1,5 @@
+.. _cmd-vared:
+
 vared - interactively edit the value of an environment variable
 ===============================================================
 

sphinx_doc_src/cmds/wait.rst

@@ -1,3 +1,5 @@
+.. _cmd-wait:
+
 wait - wait for jobs to complete
 ================================
 

sphinx_doc_src/cmds/while.rst

@@ -1,3 +1,5 @@
+.. _cmd-while:
+
 while - perform a command multiple times
 ========================================
 

sphinx_doc_src/conf.py

@@ -144,14 +144,15 @@ latex_documents = [
 
 # -- Options for manual page output ------------------------------------------
 
-def get_command_description(path):
+def get_command_description(path, name):
-    """ Return the description for a command, by parsing its first line """
+    """ Return the description for a command, by parsing its synopsis line """
     with open(path) as fd:
-        title = fd.readline()
+        for line in fd:
-    if ' - ' not in title:
+            if line.startswith(name + " - "):
-        raise SphinxWarning('No description in file %s' % os.path.basename(path))
+                _, desc = line.split(' - ', 1)
-    _, desc = title.split(' - ', 1)
+                return desc.strip()
-    return desc.strip()
+    raise SphinxWarning('No description in file %s' % os.path.basename(path))
+
 
 
 # One entry per manual page. List of tuples
@@ -163,7 +164,7 @@ man_pages = [
 for path in sorted(glob.glob('cmds/*')):
     docname = strip_ext(path)
     cmd = os.path.basename(docname)
-    man_pages.append((docname, cmd, get_command_description(path), '', 1))
+    man_pages.append((docname, cmd, get_command_description(path, cmd), '', 1))
 
 
 # -- Options for Texinfo output ----------------------------------------------