Convert \\subsection sections into rst format

sphinx_doc_src/cmds/abbr.rst

@@ -10,13 +10,15 @@ abbr --rename [SCOPE] OLD_WORD NEW_WORD
 abbr --show
 abbr --list
 
-\subsection abbr-description Description
+Description
+------------
 
 `abbr` manages abbreviations - user-defined words that are replaced with longer phrases after they are entered.
 
 For example, a frequently-run command like `git checkout` can be abbreviated to `gco`. After entering `gco` and pressing @key{Space} or @key{Enter}, the full text `git checkout` will appear in the command line.
 
-\subsection abbr-options Options
+Options
+------------
 
 The following options are available:
 
@@ -37,7 +39,8 @@ In addition, when adding abbreviations:
 
 See the "Internals" section for more on them.
 
-\subsection abbr-example Examples
+Examples
+------------
 
 \fish
 abbr -a -g gco git checkout
@@ -64,7 +67,8 @@ ssh another_host abbr -s | source
 \endfish
 Import the abbreviations defined on another_host over SSH.
 
-\subsection abbr-internals Internals
+Internals
+------------
 Each abbreviation is stored in its own global or universal variable. The name consists of the prefix `_fish_abbr_` followed by the WORD after being transformed by `string escape style=var`. The WORD cannot contain a space but all other characters are legal.
 
 Defining an abbreviation with global scope is slightly faster than universal scope (which is the default). But in general you'll only want to use the global scope when defining abbreviations in a startup script like `~/.config/fish/config.fish` like this:

sphinx_doc_src/cmds/alias.rst

@@ -9,7 +9,8 @@ alias [OPTIONS] NAME DEFINITION
 alias [OPTIONS] NAME=DEFINITION
 
 
-\subsection alias-description Description
+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>.
 
@@ -26,7 +27,8 @@ The following options are available:
 
 - `-s` or `--save` Automatically save the function created by the alias into your fish configuration directory using <a href='#funcsave'>funcsave</a>.
 
-\subsection alias-example Example
+Example
+------------
 
 The following code will create `rmi`, which runs `rm` with additional arguments on every invocation.
 

sphinx_doc_src/cmds/and.rst

@@ -7,7 +7,8 @@ Synopsis
 COMMAND1; and COMMAND2
 
 
-\subsection and-description Description
+Description
+------------
 
 `and` is used to execute a command if the previous command was successful (returned a status of 0).
 
@@ -15,7 +16,8 @@ COMMAND1; and COMMAND2
 
 `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.
 
-\subsection and-example Example
+Example
+------------
 
 The following code runs the `make` command to build a program. If the build succeeds, `make`'s exit status is 0, and the program is installed. If either step fails, the exit status is 1, and `make clean` is run, which removes the files created by the build process.
 

sphinx_doc_src/cmds/argparse.rst

@@ -7,7 +7,8 @@ Synopsis
 argparse [OPTIONS] OPTION_SPEC... -- [ARG...]
 
 
-\subsection argparse-description Description
+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.
 
@@ -17,7 +18,8 @@ Each option that is seen in the ARG list will result in a var name of the form `
 
 For example `_flag_h` and `_flag_help` if `-h` or `--help` is seen. The var will be set with local scope (i.e., as if the script had done `set -l _flag_X`). If the flag is a boolean (that is, does not have an associated value) the values are the short and long flags seen. If the option is not a boolean flag the values will be zero or more values corresponding to the values collected when the ARG list is processed. If the flag was not seen the flag var will not be set.
 
-\subsection argparse-options Options
+Options
+------------
 
 The following `argparse` options are available. They must appear before all OPTION_SPECs:
 
@@ -33,7 +35,8 @@ The following `argparse` options are available. They must appear before all OPTI
 
 - `-h` or `--help` displays help about using this command.
 
-\subsection argparse-usage Usage
+Usage
+------------
 
 Using this command involves passing two sets of arguments separated by `--`. The first set consists of one or more option specifications (`OPTION_SPEC` above) and options that modify the behavior of `argparse`. These must be listed before the `--` argument. The second set are the arguments to be parsed in accordance with the option specifications. They occur after the `--` argument and can be empty. More about this below but here is a simple example that might be used in a function named `my_function`:
 
@@ -60,7 +63,8 @@ argparse 'h/help' 'n/name' $argv
 
 The first `--` seen is what allows the `argparse` command to reliably separate the option specifications from the command arguments.
 
-\subsection argparse-option-specs Option Specifications
+Option Specifications
+------------
 
 Each option specification is a string composed of
 
@@ -84,7 +88,8 @@ See the <a href="#fish-opt">`fish_opt`</a> command for a friendlier but more ver
 
 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.
 
-\subsection argparse-validation Flag Value Validation
+Flag Value Validation
+------------
 
 It is common to want to validate the the value provided for an option satisfies some criteria. For example, that it is a valid integer within a specific range. You can always do this after `argparse` returns but you can also request that `argparse` perform the validation by executing arbitrary fish script. To do so simply append an `!` (exclamation-mark) then the fish script to be run. When that code is executed three vars will be defined:
 
@@ -100,7 +105,8 @@ The script should write any error messages to stdout, not stderr. It should retu
 
 Fish ships with a `_validate_int` function that accepts a `--min` and `--max` flag. Let's say your command accepts a `-m` or `--max` flag and the minimum allowable value is zero and the maximum is 5. You would define the option like this: `m/max=!_validate_int --min 0 --max 5`. The default if you just call `_validate_int` without those flags is to simply check that the value is a valid integer with no limits on the min or max value allowed.
 
-\subsection argparse-optspec-examples Example OPTION_SPECs
+Example OPTION_SPECs
+------------
 
 Some OPTION_SPEC examples:
 
@@ -128,6 +134,7 @@ After parsing the arguments the `argv` var is set with local scope to any values
 
 If an error occurs during argparse processing it will exit with a non-zero status and print error messages to stderr.
 
-\subsection argparse-notes Notes
+Notes
+------------
 
 Prior to the addition of this builtin command in the 2.7.0 release there were two main ways to parse the arguments passed to a fish script or function. One way was to use the OS provided `getopt` command. The problem with that is that the GNU and BSD implementations are not compatible. Which makes using that external command difficult other than in trivial situations. The other way is to iterate over `$argv` and use the fish `switch` statement to decide how to handle the argument. That, however, involves a huge amount of boilerplate code. It is also borderline impossible to implement the same behavior as builtin commands.

sphinx_doc_src/cmds/begin.rst

@@ -7,7 +7,8 @@ Synopsis
 begin; [COMMANDS...;] end
 
 
-\subsection begin-description Description
+Description
+------------
 
 `begin` is used to create a new block of code.
 
@@ -18,7 +19,8 @@ The block is unconditionally executed. `begin; ...; end` is equivalent to `if tr
 `begin` does not change the current exit status itself. After the block has completed, `$status` will be set to the status returned by the most recent command.
 
 
-\subsection begin-example Example
+Example
+------------
 
 The following code sets a number of variables inside of a block scope. Since the variables are set inside the block and have local scope, they will be automatically deleted when the block ends.
 

sphinx_doc_src/cmds/bg.rst

@@ -7,7 +7,8 @@ Synopsis
 bg [PID...]
 
 
-\subsection bg-description Description
+Description
+------------
 
 `bg` sends <a href="index.html#syntax-job-control">jobs</a> to the background, resuming them if they are stopped.
 
@@ -18,7 +19,8 @@ When at least one of the arguments isn't a valid job specifier (i.e. PID),
 
 When all arguments are valid job specifiers, bg will background all matching jobs that exist.
 
-\subsection bg-example Example
+Example
+------------
 
 `bg 123 456 789` will background 123, 456 and 789.
 

sphinx_doc_src/cmds/bind.rst

@@ -16,7 +16,8 @@ bind (-e | --erase) [(-M | --mode) MODE]
      (-a | --all | [(-k | --key)] SEQUENCE [SEQUENCE...])
 
 
-\subsection bind-description Description
+Description
+------------
 
 `bind` adds a binding for the specified key sequence to the specified command.
 
@@ -60,7 +61,8 @@ The following parameters are available:
 
 - `--preset` and `--user` specify if bind should operate on user or preset bindings. User bindings take precedence over preset bindings when fish looks up mappings. By default, all `bind` invocations work on the "user" level except for listing, which will show both levels. All invocations except for inserting new bindings can operate on both levels at the same time. `--preset` should only be used in full binding sets (like when working on `fish_vi_key_bindings`).
 
-\subsection bind-functions Special input functions
+Special input functions
+------------
 The following special input functions are available:
 
 - `accept-autosuggestion`, accept the current autosuggestion completely
@@ -144,7 +146,8 @@ The following special input functions are available:
 - `yank-pop`, rotate to the previous entry of the killring
 
 
-\subsection bind-example Examples
+Examples
+------------
 
 \fish
 bind <asis>\\cd</asis> 'exit'
@@ -163,7 +166,8 @@ bind -M insert \\cc kill-whole-line force-repaint
 Turns on Vi key bindings and rebinds @key{Control,C} to clear the input line.
 
 
-\subsection special-case-escape Special Case: The escape Character
+Special Case: The escape Character
+------------
 
 The escape key can be used standalone, for example, to switch from insertion mode to normal mode when using Vi keybindings. Escape may also be used as a "meta" key, to indicate the start of an escape sequence, such as function or arrow keys. Custom bindings can also be defined that begin with an escape character.
 

sphinx_doc_src/cmds/block.rst

@@ -7,7 +7,8 @@ Synopsis
 block [OPTIONS...]
 
 
-\subsection block-description Description
+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.
 
@@ -26,7 +27,8 @@ The following parameters are available:
 - `-e` or `--erase` Release global block
 
 
-\subsection block-example Example
+Example
+------------
 
 \fish
 # Create a function that listens for events
@@ -43,6 +45,7 @@ block -e
 \endfish
 
 
-\subsection block-notes Notes
+Notes
+------------
 
 Note that events are only received from the current fish process as there is no way to send events from one fish process to another.

sphinx_doc_src/cmds/break.rst

@@ -7,14 +7,16 @@ Synopsis
 LOOP_CONSTRUCT; [COMMANDS...] break; [COMMANDS...] end
 
 
-\subsection break-description Description
+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.
 
 There are no parameters for `break`.
 
 
-\subsection break-example Example
+Example
+------------
 The following code searches all .c files for "smurf", and halts at the first occurrence.
 
 \fish

sphinx_doc_src/cmds/breakpoint.rst

@@ -7,7 +7,8 @@ Synopsis
 breakpoint
 
 
-\subsection breakpoint-description Description
+Description
+------------
 
 `breakpoint` is used to halt a running script and launch an interactive debugging prompt.
 

sphinx_doc_src/cmds/builtin.rst

@@ -7,7 +7,8 @@ Synopsis
 builtin BUILTINNAME [OPTIONS...]
 
 
-\subsection builtin-description Description
+Description
+------------
 
 `builtin` forces the shell to use a builtin command, rather than a function or program.
 
@@ -16,7 +17,8 @@ The following parameters are available:
 - `-n` or `--names` List the names of all defined builtins
 
 
-\subsection builtin-example Example
+Example
+------------
 
 \fish
 builtin jobs

sphinx_doc_src/cmds/case.rst

@@ -7,7 +7,8 @@ Synopsis
 switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
 
 
-\subsection case-description Description
+Description
+------------
 
 `switch` executes one of several blocks of commands, depending on whether a specified value matches one of several values. `case` is used together with the `switch` statement in order to determine which block should be executed.
 
@@ -18,7 +19,8 @@ Note that fish does not fall through on case statements. Only the first matching
 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.
 
 
-\subsection case-example Example
+Example
+------------
 
 Say \$animal contains the name of an animal. Then this code would classify it:
 

sphinx_doc_src/cmds/cd.rst

@@ -7,7 +7,8 @@ Synopsis
 cd [DIRECTORY]
 
 
-\subsection cd-description Description
+Description
+------------
 `cd` changes the current working directory.
 
 If `DIRECTORY` is supplied, it will become the new directory. If no parameter is given, the contents of the `HOME` environment variable will be used.
@@ -20,7 +21,8 @@ Fish also ships a wrapper function around the builtin `cd` that understands `cd
 
 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.
 
-\subsection cd-example Examples
+Examples
+------------
 
 \fish
 cd
@@ -30,6 +32,7 @@ cd /usr/src/fish-shell
 # changes the working directory to /usr/src/fish-shell
 \endfish
 
-\subsection cd-see-also See Also
+See Also
+------------
 
 See also the <a href="commands.html#cdh">`cdh`</a> command for changing to a recently visited directory.

sphinx_doc_src/cmds/cdh.rst

@@ -8,12 +8,14 @@ Synopsis
 cdh [ directory ]
 
 
-\subsection cdh-description Description
+Description
+------------
 
 `cdh` with no arguments presents a list of recently visited directories. You can then select one of the entries by letter or number. You can also press @key{tab} to use the completion pager to select an item from the list. If you give it a single argument it is equivalent to `cd directory`.
 
 Note that the `cd` command limits directory history to the 25 most recently visited directories. The history is stored in the `$dirprev` and `$dirnext` variables which this command manipulates. If you make those universal variables your `cd` history is shared among all fish instances.
 
-\subsection cdh-see-also See Also
+See Also
+------------
 
 See also the <a href="commands.html#prevd">`prevd`</a> and <a href="commands.html#pushd">`pushd`</a> commands which also work with the recent `cd` history and are provided for compatibility with other shells.

sphinx_doc_src/cmds/command.rst

@@ -7,7 +7,8 @@ Synopsis
 command [OPTIONS] COMMANDNAME [ARGS...]
 
 
-\subsection command-description Description
+Description
+------------
 
 `command` forces the shell to execute the program `COMMANDNAME` and ignore any functions or builtins with the same name.
 
@@ -23,7 +24,8 @@ With the `-s` option, `command` treats every argument as a separate command to l
 
 For basic compatibility with POSIX `command`, the `-v` flag is recognized as an alias for `-s`.
 
-\subsection command-example Examples
+Examples
+------------
 
 `command ls` causes fish to execute the `ls` program, even if an `ls` function exists.
 

sphinx_doc_src/cmds/commandline.rst

@@ -7,7 +7,8 @@ Synopsis
 commandline [OPTIONS] [CMD]
 
 
-\subsection commandline-description Description
+Description
+------------
 
 `commandline` can be used to set or get the current contents of the command line buffer.
 
@@ -58,7 +59,8 @@ The following options output metadata about the commandline state:
 - `-P` or `--paging-mode` evaluates to true if the commandline is showing pager contents, such as tab completions
 
 
-\subsection commandline-example Example
+Example
+------------
 
 `commandline -j $history[3]` replaces the job under the cursor with the third item from the command line history.
 

sphinx_doc_src/cmds/complete.rst

@@ -20,7 +20,8 @@ complete ( -c | --command | -p | --path ) COMMAND
 complete ( -C[STRING] | --do-complete[=STRING] )
 
 
-\subsection complete-description Description
+Description
+------------
 
 For an introduction to specifying completions, see <a
 href='index.html#completion-own'>Writing your own completions</a> in
@@ -93,7 +94,8 @@ The `-w` or `--wraps` options causes the specified command to inherit completion
 When erasing completions, it is possible to either erase all completions for a specific command by specifying `complete -c COMMAND -e`, or by specifying a specific completion option to delete by specifying either a long, short or old style option.
 
 
-\subsection complete-example Example
+Example
+------------
 
 The short style option `-o` for the `gcc` command requires that a file follows it.  This can be done using writing:
 

sphinx_doc_src/cmds/contains.rst

@@ -7,7 +7,8 @@ Synopsis
 contains [OPTIONS] KEY [VALUES...]
 
 
-\subsection contains-description Description
+Description
+------------
 
 `contains` tests whether the set `VALUES` contains the string `KEY`. If so, `contains` exits with status 0; if not, it exits with status 1.
 
@@ -17,7 +18,8 @@ The following options are available:
 
 Note that, like GNU tools and most of fish's builtins, `contains` interprets all arguments starting with a `-` as options to contains, until it reaches an argument that is `--` (two dashes). See the examples below.
 
-\subsection contains-example Example
+Example
+------------
 
 If $animals is a list of animals, the following will test if it contains a cat:
 

sphinx_doc_src/cmds/continue.rst

@@ -7,11 +7,13 @@ Synopsis
 LOOP_CONSTRUCT; [COMMANDS...;] continue; [COMMANDS...;] end
 
 
-\subsection continue-description Description
+Description
+------------
 
 `continue` skips the remainder of the current iteration of the current inner 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.
 
-\subsection continue-example Example
+Example
+------------
 
 The following code removes all tmp files that do not contain the word smurf.
 

sphinx_doc_src/cmds/count.rst

@@ -7,7 +7,8 @@ Synopsis
 count $VARIABLE
 
 
-\subsection count-description Description
+Description
+------------
 
 `count` prints the number of arguments that were passed to it. This is usually used to find out how many elements an environment variable array contains.
 
@@ -16,7 +17,8 @@ count $VARIABLE
 `count` exits with a non-zero exit status if no arguments were passed to it, and with zero if at least one argument was passed.
 
 
-\subsection count-example Example
+Example
+------------
 
 \fish
 count $PATH

sphinx_doc_src/cmds/dirh.rst

@@ -7,7 +7,8 @@ Synopsis
 dirh
 
 
-\subsection dirh-description Description
+Description
+------------
 
 `dirh` prints the current directory history. The current position in the history is highlighted using the color defined in the `fish_color_history_current` environment variable.
 

sphinx_doc_src/cmds/dirs.rst

@@ -8,7 +8,8 @@ dirs
 dirs -c
 
 
-\subsection dirs-description Description
+Description
+------------
 
 `dirs` prints the current directory stack, as created by the <a href="#pushd">`pushd`</a> command.
 

sphinx_doc_src/cmds/disown.rst

@@ -7,7 +7,8 @@ Synopsis
 disown [ PID ... ]
 
 
-\subsection disown-description Description
+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.
 
@@ -19,7 +20,8 @@ If a job is stopped, it is sent a signal to continue running, and a warning is p
 
 `disown` returns 0 if all specified jobs were disowned successfully, and 1 if any problems were encountered.
 
-\subsection disown-example Example
+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.
 

sphinx_doc_src/cmds/echo.rst

@@ -7,7 +7,8 @@ Synopsis
 echo [OPTIONS] [STRING]
 
 
-\subsection echo-description Description
+Description
+------------
 
 `echo` displays a string of text.
 
@@ -21,7 +22,8 @@ The following options are available:
 
 - `-e`, Enable interpretation of backslash escapes
 
-\subsection echo-escapes Escape Sequences
+Escape Sequences
+------------
 
 If `-e` is used, the following sequences are recognized:
 
@@ -49,7 +51,8 @@ If `-e` is used, the following sequences are recognized:
 
 - `\xHH` byte with hexadecimal value HH (1 to 2 digits)
 
-\subsection echo-example Example
+Example
+------------
 
 \fish
 echo 'Hello World'

sphinx_doc_src/cmds/else.rst

@@ -7,12 +7,14 @@ Synopsis
 if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end
 
 
-\subsection else-description Description
+Description
+------------
 
 `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.
 
 
-\subsection else-example Example
+Example
+------------
 
 The following code tests whether a file `foo.txt` exists as a regular file.
 

sphinx_doc_src/cmds/emit.rst

@@ -7,12 +7,14 @@ Synopsis
 emit EVENT_NAME [ARGUMENTS...]
 
 
-\subsection emit-description Description
+Description
+------------
 
 `emit` emits, or fires, an event. Events are delivered to, or caught by, special functions called event handlers. The arguments are passed to the event handlers as function arguments.
 
 
-\subsection emit-example Example
+Example
+------------
 
 The following code first defines an event handler for the generic event named 'test_event', and then emits an event of that type.
 
@@ -25,6 +27,7 @@ emit test_event something
 \endfish
 
 
-\subsection emit-notes Notes
+Notes
+------------
 
 Note that events are only sent to the current fish process as there is no way to send events from one fish process to another.

sphinx_doc_src/cmds/end.rst

@@ -11,7 +11,8 @@ for VARNAME in [VALUES...]; COMMANDS...; end
 switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
 
 
-\subsection end-description Description
+Description
+------------
 
 `end` ends a block of commands.
 

sphinx_doc_src/cmds/eval.rst

@@ -7,12 +7,14 @@ Synopsis
 eval [COMMANDS...]
 
 
-\subsection eval-description Description
+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 your command does not need access to stdin, consider using `source` instead.
 
-\subsection eval-example Example
+Example
+------------
 
 The following code will call the ls command. Note that `fish` does not support the use of shell variables as direct commands; `eval` can be used to work around this.
 

sphinx_doc_src/cmds/exec.rst

@@ -7,11 +7,13 @@ Synopsis
 exec COMMAND [OPTIONS...]
 
 
-\subsection exec-description Description
+Description
+------------
 
 `exec` replaces the currently running shell with a new command. On successful completion, `exec` never returns. `exec` cannot be used inside a pipeline.
 
 
-\subsection exec-example Example
+Example
+------------
 
 `exec emacs` starts up the emacs text editor, and exits `fish`. When emacs exits, the session will terminate.

sphinx_doc_src/cmds/exit.rst

@@ -7,7 +7,8 @@ Synopsis
 exit [STATUS]
 
 
-\subsection exit-description Description
+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.
 

sphinx_doc_src/cmds/false.rst

@@ -7,6 +7,7 @@ Synopsis
 false
 
 
-\subsection false-description Description
+Description
+------------
 
 `false` sets the exit status to 1.

sphinx_doc_src/cmds/fg.rst

@@ -7,11 +7,13 @@ Synopsis
 fg [PID]
 
 
-\subsection fg-description Description
+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.
 
 
-\subsection fg-example Example
+Example
+------------
 
 `fg` will put the last job in the foreground.

sphinx_doc_src/cmds/fish.rst

@@ -7,7 +7,8 @@ Synopsis
 fish [OPTIONS] [-c command] [FILE [ARGUMENTS...]]
 
 
-\subsection fish-description Description
+Description
+------------
 
 `fish` is a command-line shell written mainly with interactive use in mind. The full manual is available <a href='index.html'>in HTML</a> by using the <a href='#help'>help</a> command from inside fish.
 

sphinx_doc_src/cmds/fish_breakpoint_prompt.rst

@@ -9,7 +9,8 @@ function fish_breakpoint_prompt
 end
 
 
-\subsection fish_breakpoint_prompt-description Description
+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.
 
@@ -18,7 +19,8 @@ The exit status of commands within `fish_breakpoint_prompt` will not modify the
 `fish` ships with a default version of this function that displays the function name and line number of the current execution context.
 
 
-\subsection fish_breakpoint_prompt-example Example
+Example
+------------
 
 A simple prompt that is a simplified version of the default debugging prompt:
 

sphinx_doc_src/cmds/fish_config.rst

@@ -2,7 +2,8 @@ fish_config - start the web-based configuration interface
 ==========================================
 
 
-\subsection fish_config-description Description
+Description
+------------
 
 `fish_config` starts the web-based configuration interface.
 
@@ -15,6 +16,7 @@ The web interface allows you to view your functions, variables and history, and
 If the `BROWSER` environment variable is set, it will be used as the name of the web browser to open instead of the system default.
 
 
-\subsection fish_config-example Example
+Example
+------------
 
 `fish_config` opens a new web browser window and allows you to configure certain fish settings.

sphinx_doc_src/cmds/fish_indent.rst

@@ -7,7 +7,8 @@ Synopsis
 fish_indent [OPTIONS]
 
 
-\subsection fish_indent-description Description
+Description
+------------
 
 `fish_indent` is used to indent a piece of fish code. `fish_indent` reads commands from standard input and outputs them to standard output or a specified file.
 

sphinx_doc_src/cmds/fish_key_reader.rst

@@ -7,7 +7,8 @@ Synopsis
 fish_key_reader [OPTIONS]
 
 
-\subsection fish_key_reader-description Description
+Description
+------------
 
 `fish_key_reader` is used to study input received from the terminal and can help with key binds. The program is interactive and works on standard input. Individual characters themselves and their hexadecimal values are displayed.
 
@@ -25,7 +26,8 @@ The following options are available:
 
 - `-v` or `--version` prints fish_key_reader's version and exits.
 
-\subsection fish_key_reader-usage-notes Usage Notes
+Usage Notes
+------------
 
 The delay in milliseconds since the previous character was received is included in the diagnostic information written to stderr. This information may be useful to determine the optimal `fish_escape_delay_ms` setting or learn the amount of lag introduced by tools like `ssh`, `mosh` or `tmux`.
 

sphinx_doc_src/cmds/fish_mode_prompt.rst

@@ -5,12 +5,14 @@ fish_mode_prompt - define the appearance of the mode indicator
 
 The fish_mode_prompt function will output the mode indicator for use in vi-mode.
 
-\subsection fish_mode_prompt-description Description
+Description
+------------
 
 The default `fish_mode_prompt` function will output indicators about the current Vi editor mode displayed to the left of the regular prompt. Define your own function to customize the appearance of the mode indicator. You can also define an empty `fish_mode_prompt` function to remove the Vi mode indicators. The `$fish_bind_mode variable` can be used to determine the current mode. It
 will be one of `default`, `insert`, `replace_one`, or `visual`.
 
-\subsection fish_mode_prompt-example Example
+Example
+------------
 
 \fish
 function fish_mode_prompt

sphinx_doc_src/cmds/fish_opt.rst

@@ -9,7 +9,8 @@ fish_opt ( -s X | --short=X ) [ -l LONG | --long=LONG ] [ --long-only ] \
     [ -o | --optional-val ] [ -r | --required-val ] [ --multiple-vals ]
 
 
-\subsection fish_opt-description Description
+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.
 
@@ -29,7 +30,8 @@ The following `argparse` options are available:
 
 - `-h` or `--help` displays help about using this command.
 
-\subsection fish_opt-examples Examples
+Examples
+------------
 
 Define a single option spec for the boolean help flag:
 

sphinx_doc_src/cmds/fish_prompt.rst

@@ -9,7 +9,8 @@ function fish_prompt
 end
 
 
-\subsection fish_prompt-description Description
+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.
 
@@ -18,7 +19,8 @@ The exit status of commands within `fish_prompt` will not modify the value of <a
 `fish` ships with a number of example prompts that can be chosen with the `fish_config` command.
 
 
-\subsection fish_prompt-example Example
+Example
+------------
 
 A simple prompt:
 

sphinx_doc_src/cmds/fish_right_prompt.rst

@@ -9,14 +9,16 @@ function fish_right_prompt
 end
 
 
-\subsection fish_right_prompt-description Description
+Description
+------------
 
 `fish_right_prompt` is similar to `fish_prompt`, except that it appears on the right side of the terminal window.
 
 Multiple lines are not supported in `fish_right_prompt`.
 
 
-\subsection fish_right_prompt-example Example
+Example
+------------
 
 A simple right prompt:
 

sphinx_doc_src/cmds/fish_update_completions.rst

@@ -2,7 +2,8 @@ fish_update_completions - Update completions using manual pages
 ==========================================
 
 
-\subsection fish_update_completions-description Description
+Description
+------------
 
 `fish_update_completions` parses manual pages installed on the system, and attempts to create completion files in the `fish` configuration directory.
 

sphinx_doc_src/cmds/fish_vi_mode.rst

@@ -7,7 +7,8 @@ Synopsis
 fish_vi_mode
 
 
-\subsection fish_vi_mode-description Description
+Description
+------------
 
 This function is deprecated. Please call `fish_vi_key_bindings directly`
 

sphinx_doc_src/cmds/for.rst

@@ -7,11 +7,13 @@ Synopsis
 for VARNAME in [VALUES...]; COMMANDS...; end
 
 
-\subsection for-description Description
+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.
 
-\subsection for-example Example
+Example
+------------
 
 \fish
 for i in foo bar baz; echo $i; end
@@ -22,7 +24,8 @@ bar
 baz
 \endfish
 
-\subsection for-notes Notes
+Notes
+------------
 
 The `VARNAME` was local to the for block in releases prior to 3.0.0. This means that if you did something like this:
 

sphinx_doc_src/cmds/funced.rst

@@ -7,7 +7,8 @@ Synopsis
 funced [OPTIONS] NAME
 
 
-\subsection funced-description Description
+Description
+------------
 
 `funced` provides an interface to edit the definition of the function `NAME`.
 

sphinx_doc_src/cmds/funcsave.rst

@@ -7,7 +7,8 @@ Synopsis
 funcsave FUNCTION_NAME
 
 
-\subsection funcsave-description Description
+Description
+------------
 
 `funcsave` saves the current definition of a function to a file in the fish configuration directory. This function will be automatically loaded by current and future fish sessions. This can be useful if you have interactively created a new function and wish to save it for later use.
 

sphinx_doc_src/cmds/function.rst

@@ -7,7 +7,8 @@ Synopsis
 function NAME [OPTIONS]; BODY; end
 
 
-\subsection function-description Description
+Description
+------------
 
 `function` creates a new function `NAME` with the body `BODY`.
 
@@ -56,7 +57,8 @@ By using one of the event handler switches, a function can be made to run automa
 
 - `fish_exit` is emitted right before fish exits.
 
-\subsection function-example Example
+Example
+------------
 
 \fish
 function ll
@@ -98,6 +100,7 @@ end
 This will beep when the most recent job completes.
 
 
-\subsection function-notes Notes
+Notes
+------------
 
 Note that events are only received from the current fish process as there is no way to send events from one fish process to another.

sphinx_doc_src/cmds/functions.rst

@@ -11,7 +11,8 @@ functions -d DESCRIPTION FUNCTION
 functions [ -e | -q ] FUNCTIONS...
 
 
-\subsection functions-description Description
+Description
+------------
 
 `functions` prints or erases functions.
 
@@ -58,7 +59,8 @@ Only one function's description can be changed in a single invocation of `functi
 The exit status of `functions` is the number of functions specified in the argument list that do not exist, which can be used in concert with the `-q` option.
 
 
-\subsection functions-example Examples
+Examples
+------------
 \fish
 functions -n
 # Displays a list of currently-defined functions

sphinx_doc_src/cmds/help.rst

@@ -7,7 +7,8 @@ Synopsis
 help [SECTION]
 
 
-\subsection help-description Description
+Description
+------------
 
 `help` displays the fish help documentation.
 
@@ -20,6 +21,7 @@ If you prefer to use a different browser (other than as described above) for fis
 Note that most builtin commands display their help in the terminal when given the `--help` option.
 
 
-\subsection help-example Example
+Example
+------------
 
 `help fg` shows the documentation for the `fg` builtin.

sphinx_doc_src/cmds/history.rst

@@ -12,7 +12,8 @@ history clear
 history ( -h | --help )
 
 
-\subsection history-description Description
+Description
+------------
 
 `history` is used to search, delete, and otherwise manipulate the history of interactive commands.
 
@@ -50,7 +51,8 @@ These flags can appear before or immediately after one of the sub-commands liste
 
 - `-h` or `--help` display help for this command.
 
-\subsection history-examples Example
+Example
+------------
 
 \fish
 history clear
@@ -64,7 +66,8 @@ history delete --prefix "foo"
 # You can select more than one entry by entering their IDs separated by a space.
 \endfish
 
-\subsection customizing-the-histfile Customizing the name of the history file
+Customizing the name of the history file
+------------
 
 By default interactive commands are logged to `$XDG_DATA_HOME/fish/fish_history` (typically `~/.local/share/fish/fish_history`).
 
@@ -74,7 +77,8 @@ You can change `fish_history` at any time (by using `set -x fish_history "sessio
 
 Other shells such as bash and zsh use a variable named `HISTFILE` for a similar purpose. Fish uses a different name to avoid conflicts and signal that the behavior is different (session name instead of a file path). Also, if you set the var to anything other than `fish` or `default` it will inhibit importing the bash history. That's because the most common use case for this feature is to avoid leaking private or sensitive history when giving a presentation.
 
-\subsection history-notes Notes
+Notes
+------------
 
 If you specify both `--prefix` and `--contains` the last flag seen is used.
 

sphinx_doc_src/cmds/if.rst

@@ -10,7 +10,8 @@ if CONDITION; COMMANDS_TRUE...;
 end
 
 
-\subsection if-description Description
+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 `else` is given, `COMMANDS_FALSE` will be executed.
 
@@ -18,7 +19,8 @@ You can use <a href="#and">`and`</a> or <a href="#or">`or`</a> in the condition.
 
 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.
 
-\subsection if-example Example
+Example
+------------
 
 The following code will print `foo.txt exists` if the file foo.txt exists and is a regular file, otherwise it will print `bar.txt exists` if the file bar.txt exists and is a regular file, otherwise it will print `foo.txt and bar.txt do not exist`.
 

sphinx_doc_src/cmds/isatty.rst

@@ -7,7 +7,8 @@ Synopsis
 isatty [FILE DESCRIPTOR]
 
 
-\subsection isatty-description Description
+Description
+------------
 
 `isatty` tests if a file descriptor is a tty.
 
@@ -16,7 +17,8 @@ isatty [FILE DESCRIPTOR]
 If the specified file descriptor is a tty, the exit status of the command is zero. Otherwise, the exit status is non-zero. No messages are printed to standard error.
 
 
-\subsection isatty-examples Examples
+Examples
+------------
 
 From an interactive shell, the commands below exit with a return value of zero:
 

sphinx_doc_src/cmds/jobs.rst

@@ -7,7 +7,8 @@ Synopsis
 jobs [OPTIONS] [PID]
 
 
-\subsection jobs-description Description
+Description
+------------
 
 `jobs` prints a list of the currently running <a href="index.html#syntax-job-control">jobs</a> and their status.
 
@@ -27,9 +28,11 @@ On systems that supports this feature, jobs will print the CPU usage of each job
 
 The exit code of the `jobs` builtin is `0` if there are running background jobs and `1` otherwise.
 
-\subsection prints no output.
+no output.
+------------
 
 
-\subsection jobs-example Example
+Example
+------------
 
 `jobs` outputs a summary of the current jobs.

sphinx_doc_src/cmds/math.rst

@@ -7,7 +7,8 @@ Synopsis
 math [-sN | --scale=N] [--] EXPRESSION
 
 
-\subsection math-description Description
+Description
+------------
 
 `math` is used to perform mathematical calculations. It supports all the usual operations such as addition, subtraction, etc. As well as functions like `abs()`, `sqrt()` and `log2()`.
 
@@ -21,17 +22,20 @@ The following options are available:
 
 - `-sN` or `--scale=N` sets the scale of the result. `N` must be an integer. A scale of zero causes results to be rounded down to the nearest integer. So `3/2` returns `1` rather than `2` which `1.5` would normally round to. This is for compatibility with `bc` which was the basis for this command prior to fish 3.0.0. Scale values greater than zero causes the result to be rounded using the usual rules to the specified number of decimal places.
 
-\subsection return-values Return Values
+Return Values
+------------
 
 If the expression is successfully evaluated and doesn't over/underflow or return NaN the return `status` is zero (success) else one.
 
-\subsection math-syntax Syntax
+Syntax
+------------
 
 `math` knows some operators, constants, functions and can (obviously) read numbers.
 
 For numbers, `.` is always the radix character regardless of locale - `2.5`, not `2,5`. Scientific notation (`10e5`) is also available.
 
-\subsection math-operators Operators
+Operators
+------------
 
 `math` knows the following operators:
 
@@ -47,7 +51,8 @@ For numbers, `.` is always the radix character regardless of locale - `2.5`, not
 
 They are all used in an infix manner - `5 + 2`, not `+ 5 2`.
 
-\subsection math-constants Constants
+Constants
+------------
 
 `math` knows the following constants:
 
@@ -56,7 +61,8 @@ They are all used in an infix manner - `5 + 2`, not `+ 5 2`.
 
 Use them without a leading `$` - `pi - 3` should be about 0.
 
-\subsection math-functions Functions
+Functions
+------------
 
 `math` supports the following functions:
 
@@ -85,7 +91,8 @@ Use them without a leading `$` - `pi - 3` should be about 0.
 
 All of the trigonometric functions use radians.
 
-\subsection math-example Examples
+Examples
+------------
 
 `math 1+1` outputs 2.
 
@@ -99,7 +106,8 @@ All of the trigonometric functions use radians.
 
 `math "sin(pi)"` outputs `0`.
 
-\subsection math-notes Compatibility notes
+Compatibility notes
+------------
 
 Fish 1.x and 2.x releases relied on the `bc` command for handling `math` expressions. Starting with fish 3.0.0 fish uses the tinyexpr library and evaluates the expression without the involvement of any external commands.
 

sphinx_doc_src/cmds/nextd.rst

@@ -7,7 +7,8 @@ Synopsis
 nextd [ -l | --list ] [POS]
 
 
-\subsection nextd-description Description
+Description
+------------
 
 `nextd` moves forwards `POS` positions in the history of visited directories; if the end of the history has been hit, a warning is printed.
 
@@ -17,7 +18,8 @@ Note that the `cd` command limits directory history to the 25 most recently visi
 
 You may be interested in the <a href="commands.html#cdh">`cdh`</a> command which provides a more intuitive way to navigate to recently visited directories.
 
-\subsection nextd-example Example
+Example
+------------
 
 \fish
 cd /usr/src

sphinx_doc_src/cmds/not.rst

@@ -7,12 +7,14 @@ Synopsis
 not COMMAND [OPTIONS...]
 
 
-\subsection not-description Description
+Description
+------------
 
 `not` negates the exit status of another command. If the exit status is zero, `not` returns 1. Otherwise, `not` returns 0.
 
 
-\subsection not-example Example
+Example
+------------
 
 The following code reports an error and exits if no file named spoon can be found.
 

sphinx_doc_src/cmds/open.rst

@@ -7,13 +7,15 @@ Synopsis
 open FILES...
 
 
-\subsection open-description Description
+Description
+------------
 
 `open` opens a file in its default application, using the appropriate tool for the operating system. On GNU/Linux, this requires the common but optional `xdg-open` utility, from the `xdg-utils` package.
 
 Note that this function will not be used if a command by this name exists (which is the case on macOS or Haiku).
 
 
-\subsection open-example Example
+Example
+------------
 
 `open *.txt` opens all the text files in the current directory using your system's default text editor.

sphinx_doc_src/cmds/or.rst

@@ -7,7 +7,8 @@ Synopsis
 COMMAND1; or COMMAND2
 
 
-\subsection or-description Description
+Description
+------------
 
 `or` is used to execute a command if the previous command was not successful (returned a status of something other than 0).
 
@@ -16,7 +17,8 @@ for <a href="#if">`if`</a> and <a href="#while">`while`</a> for examples.
 
 `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 <a href="index.html#variables-status">$status</a> variable.
 
-\subsection or-example Example
+Example
+------------
 
 The following code runs the `make` command to build a program. If the build succeeds, the program is installed. If either step fails, `make clean` is run, which removes the files created by the build process.
 

sphinx_doc_src/cmds/popd.rst

@@ -7,13 +7,15 @@ Synopsis
 popd
 
 
-\subsection popd-description Description
+Description
+------------
 
 `popd` removes the top directory from the directory stack and changes the working directory to the new top directory. Use <a href="#pushd">`pushd`</a> to add directories to the stack.
 
 You may be interested in the <a href="commands.html#cdh">`cdh`</a> command which provides a more intuitive way to navigate to recently visited directories.
 
-\subsection popd-example Example
+Example
+------------
 
 \fish
 pushd /usr/src

sphinx_doc_src/cmds/prevd.rst

@@ -7,7 +7,8 @@ Synopsis
 prevd [ -l | --list ] [POS]
 
 
-\subsection prevd-description Description
+Description
+------------
 
 `prevd` moves backwards `POS` positions in the history of visited directories; if the beginning of the history has been hit, a warning is printed.
 
@@ -17,7 +18,8 @@ Note that the `cd` command limits directory history to the 25 most recently visi
 
 You may be interested in the <a href="commands.html#cdh">`cdh`</a> command which provides a more intuitive way to navigate to recently visited directories.
 
-\subsection prevd-example Example
+Example
+------------
 
 \fish
 cd /usr/src

sphinx_doc_src/cmds/printf.rst

@@ -7,7 +7,8 @@ Synopsis
 printf format [argument...]
 
 
-\subsection printf-description Description
+Description
+------------
 printf formats the string FORMAT with ARGUMENT, and displays the result.
 
 The string FORMAT should contain format specifiers, each of which are replaced with successive arguments according to the specifier. Specifiers are detailed below, and are taken from the C library function `printf(3)`.
@@ -59,7 +60,8 @@ The `format` argument is re-used as many times as necessary to convert all of th
 
 This file has been imported from the printf in GNU Coreutils version 6.9. If you would like to use a newer version of printf, for example the one shipped with your OS, try `command printf`.
 
-\subsection printf-example Example
+Example
+------------
 
 \fish
 printf '%s\\t%s\\n' flounder fish

sphinx_doc_src/cmds/prompt_pwd.rst

@@ -7,13 +7,15 @@ Synopsis
 prompt_pwd
 
 
-\subsection prompt_pwd-description Description
+Description
+------------
 
 prompt_pwd is a function to print the current working directory in a way suitable for prompts. It will replace the home directory with "~" and shorten every path component but the last to a default of one character.
 
 To change the number of characters per path component, set $fish_prompt_pwd_dir_length to the number of characters. Setting it to 0 or an invalid value will disable shortening entirely.
 
-\subsection prompt_pwd-example Examples
+Examples
+------------
 
 \fish{cli-dark}
 >_ cd ~/

sphinx_doc_src/cmds/psub.rst

@@ -7,7 +7,8 @@ Synopsis
 COMMAND1 ( COMMAND2 | psub [-F | --fifo] [-f | --file] [-s SUFFIX])
 
 
-\subsection psub-description Description
+Description
+------------
 
 Some shells (e.g., ksh, bash) feature a syntax that is a mix between command substitution and piping, called process substitution. It is used to send the output of a command into the calling command, much like command substitution, but with the difference that the output is not sent through commandline arguments but through a named pipe, with the filename of the named pipe sent as an argument to the calling program. `psub` combined with a regular command substitution provides the same functionality.
 
@@ -19,7 +20,8 @@ The following options are available:
 
 - `-s` or `--suffix` will append SUFFIX to the filename.
 
-\subsection psub-example Example
+Example
+------------
 
 \fish
 diff (sort a.txt | psub) (sort b.txt | psub)

sphinx_doc_src/cmds/pushd.rst

@@ -7,7 +7,8 @@ Synopsis
 pushd [DIRECTORY]
 
 
-\subsection pushd-description Description
+Description
+------------
 
 The `pushd` function adds `DIRECTORY` to the top of the directory stack and makes it the current working directory. <a href="#popd">`popd`</a> will pop it off and return to the original directory.
 
@@ -21,7 +22,8 @@ See also `dirs` and `dirs -c`.
 
 You may be interested in the <a href="commands.html#cdh">`cdh`</a> command which provides a more intuitive way to navigate to recently visited directories.
 
-\subsection pushd-example Example
+Example
+------------
 
 \fish
 pushd /usr/src

sphinx_doc_src/cmds/pwd.rst

@@ -7,7 +7,8 @@ Synopsis
 pwd
 
 
-\subsection pwd-description Description
+Description
+------------
 
 `pwd` outputs (prints) the current working directory.
 

sphinx_doc_src/cmds/random.rst

@@ -11,7 +11,8 @@ random START STEP END
 random choice [ITEMS...]
 
 
-\subsection random-description Description
+Description
+------------
 
 `RANDOM` generates a pseudo-random integer from a uniform distribution. The
 range (inclusive) is dependent on the arguments passed.
@@ -29,7 +30,8 @@ systems.
 You should not consider `RANDOM` cryptographically secure, or even
 statistically accurate.
 
-\subsection random-example Example
+Example
+------------
 
 The following code will count down from a random even number between 10 and 20 to 1:
 

sphinx_doc_src/cmds/read.rst

@@ -7,7 +7,8 @@ Synopsis
 read [OPTIONS] [VARIABLE ...]
 
 
-\subsection read-description Description
+Description
+------------
 
 `read` reads from standard input and either writes the result back to standard output (for use in command substitution), or stores the result in one or more shell variables. By default, `read` reads a single line and splits it into variables on spaces or tabs. Alternatively, a null character or a maximum number of characters can be used to terminate the input, and other delimiters can be given. Unlike other shells, there is no default variable (such as `REPLY`) for storing the result - instead, it is printed on standard output.
 
@@ -71,11 +72,13 @@ maximum of 10 MiB (1048576 bytes); if the terminator is not reached before this
 is set to empty and the exit status is set to 122. This limit can be altered with the
 `fish_read_limit` variable. If set to 0 (zero), the limit is removed.
 
-\subsection read-history Using another read history file
+Using another read history file
+------------
 
 The `read` command supported the `-m` and `--mode-name` flags in fish versions prior to 2.7.0 to specify an alternative read history file. Those flags are now deprecated and ignored. Instead, set the `fish_history` variable to specify a history session ID. That will affect both the `read` history file and the fish command history file. You can set it to an empty string to specify that no history should be read or written. This is useful for presentations where you do not want possibly private or sensitive history to be exposed to the audience but do want history relevant to the presentation to be available.
 
-\subsection read-example Example
+Example
+------------
 
 The following code stores the value 'hello' in the shell variable `$foo`.
 

sphinx_doc_src/cmds/realpath.rst

@@ -7,7 +7,8 @@ Synopsis
 realpath path
 
 
-\subsection realpath-description Description
+Description
+------------
 
 This is implemented as a function and a builtin. The function will attempt to use an external realpath command if one can be found. Otherwise it falls back to the builtin.  The builtin does not support any options. It's meant to be used only by scripts which need to be portable. The builtin implementation behaves like GNU realpath when invoked without any options (which is the most common use case). In general scripts should not invoke the builtin directly. They should just use `realpath`.
 

sphinx_doc_src/cmds/return.rst

@@ -7,14 +7,16 @@ Synopsis
 function NAME; [COMMANDS...;] return [STATUS]; [COMMANDS...;] end
 
 
-\subsection return-description Description
+Description
+------------
 
 `return` halts a currently running function. The exit status is set to `STATUS` if it is given.
 
 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 to conditionally stop the executing function and return to the caller, but it can also be used to specify the exit status of a function.
 
 
-\subsection return-example Example
+Example
+------------
 
 The following code is an implementation of the false command as a fish function
 

sphinx_doc_src/cmds/set.rst

@@ -13,7 +13,8 @@ set ( -e | --erase ) [SCOPE_OPTIONS] VARIABLE_NAME[INDICES]...
 set ( -S | --show ) [SCOPE_OPTIONS] [VARIABLE_NAME]...
 
 
-\subsection set-description Description
+Description
+------------
 
 `set` manipulates <a href="index.html#variables">shell variables</a>.
 
@@ -82,7 +83,8 @@ In erase mode, if variable indices are specified, only the specified slices of t
 In assignment mode, `set` does not modify the exit status. This allows simultaneous capture of the output and exit status of a subcommand, e.g. `if set output (command)`. In query mode, the exit status is the number of variables that were not found. In erase mode, `set` exits with a zero exit status in case of success, with a non-zero exit status if the commandline was invalid, if the variable was write-protected or if the variable did not exist.
 
 
-\subsection set-examples Examples
+Examples
+------------
 \fish
 # Prints all global, exported variables.
 set -xg
@@ -109,7 +111,8 @@ if set python_path (type -p python)
 end
 \endfish
 
-\subsection set-notes Notes
+Notes
+------------
 
 Fish versions prior to 3.0 supported the syntax `set PATH[1] PATH[4] /bin /sbin`, which worked like
 `set PATH[1 4] /bin /sbin`. This syntax was not widely used, and was ambiguous and inconsistent.

sphinx_doc_src/cmds/set_color.rst

@@ -7,7 +7,8 @@ Synopsis
 set_color [OPTIONS] VALUE
 
 
-\subsection set_color-description Description
+Description
+------------
 
 `set_color` is used to control the color and styling of text in the terminal. `VALUE` corresponds to a reserved color name such as *red* or a RGB color value given as 3 or 6 hexadecimal digits. The *br*-, as in 'bright', forms are full-brightness variants of the 8 standard-brightness colors on many terminals. *brblack* has higher brightness than *black* - towards gray. A special keyword *normal* resets text formatting to terminal defaults.
 
@@ -30,14 +31,16 @@ The following options are available:
 
 Using the *normal* keyword will reset foreground, background, and all formatting back to default.
 
-\subsection set_color-notes Notes
+Notes
+------------
 
 1. Using the *normal* keyword will reset both background and foreground colors to whatever is the default for the terminal.
 2. Setting the background color only affects subsequently written characters. Fish provides no way to set the background color for the entire terminal window. Configuring the window background color (and other attributes such as its opacity) has to be done using whatever mechanisms the terminal provides.
 3. Some terminals use the `--bold` escape sequence to switch to a brighter color set rather than increasing the weight of text.
 4. `set_color` works by printing sequences of characters to *stdout*. If used in command substitution or a pipe, these characters will also be captured. This may or may not be desirable. Checking the exit code of `isatty stdout` before using `set_color` can be useful to decide not to colorize output in a script.
 
-\subsection set_color-example Examples
+Examples
+------------
 
 \fish
 set_color red; echo "Roses are red"
@@ -46,7 +49,8 @@ set_color 62A; echo "Eggplants are dark purple"
 set_color normal; echo "Normal is nice" # Resets the background too
 \endfish
 
-\subsection set_color-detection Terminal Capability Detection
+Terminal Capability Detection
+------------
 
 Fish uses a heuristic to decide if a terminal supports the 256-color palette as opposed to the more limited 16 color palette of older terminals. Support can be forced on by setting `fish_term256` to *1*. If `$TERM` contains "256color" (e.g., *xterm-256color*), 256-color support is enabled. If `$TERM` contains *xterm*, 256 color support is enabled (except for MacOS: `$TERM_PROGRAM` and `$TERM_PROGRAM_VERSION` are used to detect Terminal.app from MacOS 10.6; support is disabled here it because it is known that it reports `xterm` and only supports 16 colors.
 

sphinx_doc_src/cmds/source.rst

@@ -8,7 +8,8 @@ source FILENAME [ARGUMENTS...]
 somecommand | source
 
 
-\subsection source-description Description
+Description
+------------
 
 `source` evaluates the commands of the specified file in the current shell. This is different from starting a new process to perform the commands (i.e. `fish < FILENAME`) since the commands will be evaluated by the current shell, which means that changes in shell variables will affect the current shell. If additional arguments are specified after the file name, they will be inserted into the `$argv` variable. The `$argv` variable will not include the name of the sourced file.
 
@@ -19,7 +20,8 @@ The return status of `source` is the return status of the last job to execute. I
 `.` (a single period) is an alias for the `source` command. The use of `.` is deprecated in favour of `source`, and `.` will be removed in a future version of fish.
 
 
-\subsection source-example Example
+Example
+------------
 
 \fish
 source ~/.config/fish/config.fish

sphinx_doc_src/cmds/status.rst

@@ -23,7 +23,8 @@ status features
 status test-feature FEATURE
 
 
-\subsection status-description Description
+Description
+------------
 
 With no arguments, `status` displays a summary of the current login and job control status of the shell.
 
@@ -62,7 +63,8 @@ The following operations (sub-commands) are available:
 
 - `test-feature FEATURE` returns 0 when FEATURE is enabled, 1 if it is disabled, and 2 if it is not recognized.
 
-\subsection status-notes Notes
+Notes
+------------
 
 For backwards compatibility each subcommand can also be specified as a long or short option. For example, rather than `status is-login` you can type `status --is-login`. The flag forms are deprecated and may be removed in a future release (but not before fish 3.0).
 

sphinx_doc_src/cmds/string.rst

@@ -28,7 +28,8 @@ string upper [(-q | --quiet)] [STRING...]
 
 
 
-\subsection string-description Description
+Description
+------------
 
 `string` performs operations on strings.
 
@@ -40,7 +41,8 @@ Most subcommands accept a `-q` or `--quiet` switch, which suppresses the usual o
 
 The following subcommands are available.
 
-\subsection string-escape "escape" subcommand
+"escape" subcommand
+------------
 
 `string escape` escapes each STRING in one of three ways. The first is `--style=script`. This is the default. It alters the string such that it can be passed back to `eval` to produce the original argument again. By default, all special characters are escaped, and quotes are used to simplify the output when possible. If `-n` or `--no-quoted` is given, the simplifying quoted format is not used. Exit status: 0 if at least one string was escaped, or 1 otherwise.
 
@@ -52,7 +54,8 @@ The following subcommands are available.
 
 `string unescape` performs the inverse of the `string escape` command. If the string to be unescaped is not properly formatted it is ignored. For example, doing `string unescape --style=var (string escape --style=var $str)` will return the original string. There is no support for unescaping pcre2.
 
-\subsection string-join "join" subcommand
+"join" subcommand
+------------
 
 `string join` joins its STRING arguments into a single string separated by SEP, which can be an empty string. Exit status: 0 if at least one join was performed, or 1 otherwise.
 
@@ -60,15 +63,18 @@ The following subcommands are available.
 
 `string join` joins its STRING arguments into a single string separated by the zero byte (NUL), and adds a trailing NUL. This is most useful in conjunction with tools that accept NUL-delimited input, such as `sort -z`. Exit status: 0 if at least one join was performed, or 1 otherwise.
 
-\subsection string-length "length" subcommand
+"length" subcommand
+------------
 
 `string length` reports the length of each string argument in characters. Exit status: 0 if at least one non-empty STRING was given, or 1 otherwise.
 
-\subsection string-lower "lower" subcommand
+"lower" subcommand
+------------
 
 `string lower` converts each string argument to lowercase. Exit status: 0 if at least one string was converted to lowercase, else 1. This means that in conjunction with the `-q` flag you can readily test whether a string is already lowercase.
 
-\subsection string-match "match" subcommand
+"match" subcommand
+------------
 
 `string match` tests each STRING against PATTERN and prints matching substrings. Only the first match for each STRING is reported unless `-a` or `--all` is given, in which case all matches are reported.
 
@@ -84,11 +90,13 @@ If `--invert` or `-v` is used the selected lines will be only those which do not
 
 Exit status: 0 if at least one match was found, or 1 otherwise.
 
-\subsection string-repeat "repeat" subcommand
+"repeat" subcommand
+------------
 
 `string repeat` repeats the STRING `-n` or `--count` times. The `-m` or `--max` option will limit the number of outputted char (excluding the newline). This option can be used by itself or in conjunction with `--count`. If both `--count` and `--max` are present, max char will be outputed unless the final repeated string size is less than max, in that case, the string will repeat until count has been reached. Both `--count` and `--max` will accept a number greater than or equal to zero, in the case of zero, nothing will be outputed. If `-N` or `--no-newline` is given, the output won't contain a newline character at the end. Exit status: 0 if yielded string is not empty, 1 otherwise.
 
-\subsection string-replace "replace" subcommand
+"replace" subcommand
+------------
 
 `string replace` is similar to `string match` but replaces non-overlapping matching substrings with a replacement string and prints the result. By default, PATTERN is treated as a literal substring to be matched.
 
@@ -98,7 +106,8 @@ If you specify the `-f` or `--filter` flag then each input string is printed onl
 
 Exit status: 0 if at least one replacement was performed, or 1 otherwise.
 
-\subsection string-split "split" subcommand
+"split" subcommand
+------------
 
 `string split` splits each STRING on the separator SEP, which can be an empty string. If `-m` or `--max` is specified, at most MAX splits are done on each STRING. If `-r` or `--right` is given, splitting is performed right-to-left. This is useful in combination with `-m` or `--max`. With `-n` or `--no-empty`, empty results are excluded from consideration (e.g. `hello\n\nworld` would expand to two strings and not three). Exit status: 0 if at least one split was performed, or 1 otherwise.
 
@@ -110,19 +119,23 @@ See also `read --delimiter`.
 
 `split0` has the important property that its output is not further split when used in a command substitution, allowing for the command substitution to produce elements containing newlines. This is most useful when used with Unix tools that produce zero bytes, such as `find -print0` or `sort -z`. See split0 examples below.
 
-\subsection string-sub "sub" subcommand
+"sub" subcommand
+------------
 
 `string sub` prints a substring of each string argument. The start of the substring can be specified with `-s` or `--start` followed by a 1-based index value. Positive index values are relative to the start of the string and negative index values are relative to the end of the string. The default start value is 1. The length of the substring can be specified with `-l` or `--length`. If the length is not specified, the substring continues to the end of each STRING. Exit status: 0 if at least one substring operation was performed, 1 otherwise.
 
-\subsection string-trim "trim" subcommand
+"trim" subcommand
+------------
 
 `string trim` removes leading and trailing whitespace from each STRING. If `-l` or `--left` is given, only leading whitespace is removed. If `-r` or `--right` is given, only trailing whitespace is trimmed. The `-c` or `--chars` switch causes the characters in CHARS to be removed instead of whitespace. Exit status: 0 if at least one character was trimmed, or 1 otherwise.
 
-\subsection string-upper "upper" subcommand
+"upper" subcommand
+------------
 
 `string upper` converts each string argument to uppercase. Exit status: 0 if at least one string was converted to uppercase, else 1. This means that in conjunction with the `-q` flag you can readily test whether a string is already uppercase.
 
-\subsection regular-expressions Regular Expressions
+Regular Expressions
+------------
 
 Both the `match` and `replace` subcommand support regular expressions when used with the `-r` or `--regex` option. The dialect is that of PCRE2.
 
@@ -172,7 +185,8 @@ And some other things:
 - `^` is the start of the string or line, `$` the end.
 - `|` is "alternation", i.e. the "or".
 
-\subsection string-example Examples
+Examples
+------------
 
 \fish{cli-dark}
 >_ string length 'hello, world'
@@ -234,7 +248,8 @@ And some other things:
 <bs>a1_20b2__c_E6_85_A1</bs>
 \endfish
 
-\subsection string-example-match-glob Match Glob Examples
+Match Glob Examples
+------------
 
 \fish{cli-dark}
 >_ string match '?' a
@@ -266,7 +281,8 @@ foo2
 </outp>
 \endfish
 
-\subsection string-example-match-regex Match Regex Examples
+Match Regex Examples
+------------
 
 \fish{cli-dark}
 >_ string match -r 'cat|dog|fish' 'nice dog'
@@ -315,7 +331,8 @@ foo2
 <outp>alpha\\ngamma</outp>
 \endfish
 
-\subsection string-example-replace-literal Replace Literal Examples
+Replace Literal Examples
+------------
 
 \fish{cli-dark}
 >_ string replace is was 'blue is my favorite'
@@ -330,7 +347,8 @@ foo2
 <outp>spaces_to_underscores</outp>
 \endfish
 
-\subsection string-example-replace-Regex Replace Regex Examples
+Replace Regex Examples
+------------
 
 \fish{cli-dark}
 >_ string replace -r -a '[^\\d.]+' ' ' '0 one two 3.14 four 5x'
@@ -344,7 +362,8 @@ foo2
 <outp>here</outp>
 \endfish
 
-\subsection string-example-repeat Repeat Examples
+Repeat Examples
+------------
 
 \fish{cli-dark}
 >_ string repeat -n 2 'foo '

sphinx_doc_src/cmds/suspend.rst

@@ -7,7 +7,8 @@ Synopsis
 suspend [--force]
 
 
-\subsection suspend-description Description
+Description
+------------
 
 `suspend` suspends execution of the current shell by sending it a
 SIGTSTP signal, returning to the controlling process. It can be

sphinx_doc_src/cmds/switch.rst

@@ -7,7 +7,8 @@ Synopsis
 switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
 
 
-\subsection switch-description Description
+Description
+------------
 
 `switch` performs one of several blocks of commands, depending on whether a specified value equals one of several wildcarded values. `case` is used together with the `switch` statement in order to determine which block should be executed.
 
@@ -18,7 +19,8 @@ Note that fish does not fall through on case statements. Only the first matching
 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.
 
 
-\subsection switch-example Example
+Example
+------------
 
 If the variable \$animal contains the name of an animal, the following code would attempt to classify it:
 

sphinx_doc_src/cmds/test.rst

@@ -8,7 +8,8 @@ test [EXPRESSION]
 [ [EXPRESSION] ]
 
 
-\subsection test-description Description
+Description
+------------
 
 Tests the expression given and sets the exit status to 0 if true, and 1 if false. An expression is made up of one or more operators and their arguments.
 
@@ -18,7 +19,8 @@ This test is mostly POSIX-compatible.
 
 When using a variable as an argument for a test operator you should almost always enclose it in double-quotes. There are only two situations it is safe to omit the quote marks. The first is when the argument is a literal string with no whitespace or other characters special to the shell (e.g., semicolon). For example, `test -b /my/file`. The second is using a variable that expands to exactly one element including if that element is the empty string (e.g., `set x ''`). If the variable is not set, set but with no value, or set to more than one value you must enclose it in double-quotes. For example, `test "$x" = "$y"`. Since it is always safe to enclose variables in double-quotes when used as `test` arguments that is the recommended practice.
 
-\subsection test-files Operators for files and directories
+Operators for files and directories
+------------
 
 - `-b FILE` returns true if `FILE` is a block device.
 
@@ -56,7 +58,8 @@ When using a variable as an argument for a test operator you should almost alway
 
 - `-x FILE` returns true if `FILE` is marked as executable.
 
-\subsection test-strings Operators for text strings
+Operators for text strings
+------------
 
 - `STRING1 = STRING2` returns true if the strings `STRING1` and `STRING2` are identical.
 
@@ -66,7 +69,8 @@ When using a variable as an argument for a test operator you should almost alway
 
 - `-z STRING` returns true if the length of `STRING` is zero.
 
-\subsection test-numbers Operators to compare and examine numbers
+Operators to compare and examine numbers
+------------
 
 - `NUM1 -eq NUM2` returns true if `NUM1` and `NUM2` are numerically equal.
 
@@ -82,7 +86,8 @@ When using a variable as an argument for a test operator you should almost alway
 
 Both integers and floating point numbers are supported.
 
-\subsection test-combinators Operators to combine expressions
+Operators to combine expressions
+------------
 
 - `COND1 -a COND2` returns true if both `COND1` and `COND2` are true.
 
@@ -99,7 +104,8 @@ Expressions can be grouped using parentheses.
  Note that parentheses will usually require escaping with `\(` to avoid being interpreted as a command substitution.
 
 
-\subsection test-example Examples
+Examples
+------------
 
 If the `/tmp` directory exists, copy the `/etc/motd` file to it:
 
@@ -157,7 +163,8 @@ if test $status -ne 0
 end
 \endfish
 
-\subsection test-standards Standards
+Standards
+------------
 
 `test` implements a subset of the <a href="http://www.unix.com/man-page/POSIX/1/test/">IEEE Std 1003.1-2008 (POSIX.1) standard</a>. The following exceptions apply:
 

sphinx_doc_src/cmds/trap.rst

@@ -7,7 +7,8 @@ Synopsis
 trap [OPTIONS] [[ARG] REASON ... ]
 
 
-\subsection trap-description Description
+Description
+------------
 
 `trap` is a wrapper around the fish event delivery framework. It exists for backwards compatibility with POSIX shells. For other uses, it is recommended to define an <a href='index.html#event'>event handler</a>.
 
@@ -31,7 +32,8 @@ Signal names are case insensitive and the `SIG` prefix is optional.
 
 The return status is 1 if any `REASON` is invalid; otherwise trap returns 0.
 
-\subsection trap-example Example
+Example
+------------
 
 \fish
 trap "status --print-stack-trace" SIGUSR1

sphinx_doc_src/cmds/true.rst

@@ -7,6 +7,7 @@ Synopsis
 true
 
 
-\subsection true-description Description
+Description
+------------
 
 `true` sets the exit status to 0.

sphinx_doc_src/cmds/type.rst

@@ -7,7 +7,8 @@ Synopsis
 type [OPTIONS] NAME [NAME ...]
 
 
-\subsection type-description Description
+Description
+------------
 
 With no options, `type` indicates how each `NAME` would be interpreted if used as a command name.
 
@@ -28,7 +29,8 @@ The following options are available:
 The `-q`, `-p`, `-t` and `-P` flags (and their long flag aliases) are mutually exclusive. Only one can be specified at a time.
 
 
-\subsection type-example Example
+Example
+------------
 
 \fish{cli-dark}
 >_ type fg

sphinx_doc_src/cmds/ulimit.rst

@@ -7,7 +7,8 @@ Synopsis
 ulimit [OPTIONS] [LIMIT]
 
 
-\subsection ulimit-description Description
+Description
+------------
 
 `ulimit` builtin sets or outputs the resource usage limits of the shell and any processes spawned by it. If a new limit value is omitted, the current value of the limit of the resource is printed; otherwise, the specified limit is set to the new value.
 
@@ -60,7 +61,8 @@ The `fish` implementation of `ulimit` should behave identically to the implement
 - Fish `ulimit` does not support getting or setting multiple limits in one command, except reporting all values using the -a switch
 
 
-\subsection ulimit-example Example
+Example
+------------
 
 `ulimit -Hs 64` sets the hard stack size limit to 64 kB.
 

sphinx_doc_src/cmds/umask.rst

@@ -7,7 +7,8 @@ Synopsis
 umask [OPTIONS] [MASK]
 
 
-\subsection umask-description Description
+Description
+------------
 
 `umask` displays and manipulates the "umask", or file creation mode mask, which is used to restrict the default access to files.
 
@@ -38,6 +39,7 @@ If the first and second parts are skipped, they are assumed to be `a` and `=`, r
 Note that symbolic masks currently do not work as intended.
 
 
-\subsection umask-example Example
+Example
+------------
 
 `umask 177` or `umask u=rw` sets the file creation mask to read and write for the owner and no permissions at all for any other users.

sphinx_doc_src/cmds/vared.rst

@@ -7,11 +7,13 @@ Synopsis
 vared VARIABLE_NAME
 
 
-\subsection vared-description Description
+Description
+------------
 
 `vared` is used to interactively edit the value of an environment variable. Array variables as a whole can not be edited using `vared`, but individual array elements can.
 
 
-\subsection vared-example Example
+Example
+------------
 
 `vared PATH[3]` edits the third element of the PATH array

sphinx_doc_src/cmds/wait.rst

@@ -7,7 +7,8 @@ Synopsis
 wait [-n | --any] [PID | PROCESS_NAME] ...
 
 
-\subsection wait-description Description
+Description
+------------
 
 `wait` waits for child jobs to complete.
 
@@ -16,7 +17,8 @@ wait [-n | --any] [PID | PROCESS_NAME] ...
 - If neither a pid nor a process name is specified, the command waits for all background jobs.
 - If the `-n` / `--any` flag is provided, the command returns as soon as the first job completes. If it is not provided, it returns after all jobs complete.
 
-\subsection wait-example Example
+Example
+------------
 
 \fish
 sleep 10 &

sphinx_doc_src/cmds/while.rst

@@ -7,7 +7,8 @@ Synopsis
 while CONDITION; COMMANDS...; end
 
 
-\subsection while-description Description
+Description
+------------
 
 `while` repeatedly executes `CONDITION`, and if the exit status is 0, then executes `COMMANDS`.
 
@@ -18,7 +19,8 @@ The exit status of the loop is 0 otherwise.
 
 You can use <a href="#and">`and`</a> or <a href="#or">`or`</a> for complex conditions. Even more complex control can be achieved with `while true` containing a <a href="#break">break</a>.
 
-\subsection while-example Example
+Example
+------------
 
 \fish
 while test -f foo.txt; or test -f bar.txt ; echo file exists; sleep 10; end