Incorporate most new doc changes since branch

Adds most documentation changes since 72c0213d42

sphinx_doc_src/cmds/abbr.rst

@@ -9,6 +9,7 @@ abbr --erase word
 abbr --rename [SCOPE] OLD_WORD NEW_WORD
 abbr --show
 abbr --list
+abbr --query WORD...
 
 Description
 -----------
@@ -32,6 +33,8 @@ The following options are available:
 
 - ``-e WORD`` or ``--erase WORD`` Erase the abbreviation WORD.
 
+- ``-q`` or ``--query`` Return 0 (true) if one of the WORDs is an abbreviation.
+
 In addition, when adding abbreviations:
 
 - ``-g`` or ``--global`` to use a global variable.

sphinx_doc_src/cmds/builtin.rst

@@ -4,7 +4,8 @@ builtin - run a builtin command
 Synopsis
 --------
 
-builtin BUILTINNAME [OPTIONS...]
+builtin [OPTIONS...] BUILTINNAME
+builtin --query BUILTINNAMES...
 
 
 Description
@@ -15,6 +16,7 @@ Description
 The following parameters are available:
 
 - ``-n`` or ``--names`` List the names of all defined builtins
+- ``-q`` or ``--query`` tests if any of the specified builtins exists
 
 
 Example

sphinx_doc_src/cmds/command.rst

@@ -16,7 +16,7 @@ The following options are available:
 
 - ``-a`` or ``--all`` returns all the external commands that are found in ``$PATH`` in the order they are found.
 
-- ``-q`` or ``--quiet``, in conjunction with ``-s``, silences the output and prints nothing, setting only the exit code.
+- ``-q`` or ``--quiet``, silences the output and prints nothing, setting only the exit code. Implies ``--search``.
 
 - ``-s`` or ``--search`` returns the name of the external command that would be executed, or nothing if no file with the specified name could be found in the ``$PATH``.
 
@@ -31,4 +31,4 @@ Examples
 
 ``command -s ls`` returns the path to the ``ls`` program.
 
-``command -sq git; and command git log`` runs ``git log`` only if ``git`` exists.
+``command -q git; and command git log`` runs ``git log`` only if ``git`` exists.

sphinx_doc_src/cmds/math.rst

@@ -14,13 +14,13 @@ Description
 
 By default, the output is as a float with trailing zeroes trimmed. To get a fixed representation, the ``--scale`` option can be used, including ``--scale=0`` for integer output.
 
-Keep in mind that parameter expansion takes before expressions are evaluated. This can be very useful in order to perform calculations involving shell variables or the output of command substitutions, but it also means that parenthesis and the asterisk glob character have to be escaped or quoted.
+Keep in mind that parameter expansion takes before expressions are evaluated. This can be very useful in order to perform calculations involving shell variables or the output of command substitutions, but it also means that parenthesis (``()``) and the asterisk (``*``) glob character have to be escaped or quoted.
 
 ``math`` ignores whitespace between arguments and takes its input as multiple arguments (internally joined with a space), so ``math 2 +2`` and ``math "2 +    2"`` work the same. ``math 2 2`` is an error.
 
 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.
+- ``-sN`` or ``--scale=N`` sets the scale of the result. ``N`` must be an integer or the word "max" for the maximum scale. 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.
 
 Return Values
 -------------
@@ -41,13 +41,13 @@ Operators
 
 - ``+`` for addition and ``-`` for subtraction.
 
-- ``*`` for multiplication, ``/`` for division.
+- ``*`` for multiplication, ``/`` for division. (Note that ``*`` is the glob character and needs to be quoted or escaped.)
 
 - ``^`` for exponentiation.
 
 - ``%`` for modulo.
 
-- ``(`` and ``)`` for grouping.
+- ``(`` and ``)`` for grouping. (These need to be quoted or escaped because ``()`` denotes a command substitution.)
 
 They are all used in an infix manner - ``5 + 2``, not ``+ 5 2``.
 
@@ -106,6 +106,8 @@ Examples
 
 ``math "sin(pi)"`` outputs ``0``.
 
+``math 5 \* 2`` or ``math "5 * 2"`` or ``math 5 "*" 2`` all output ``10``.
+
 Compatibility notes
 -------------------
 

sphinx_doc_src/cmds/printf.rst

@@ -75,6 +75,6 @@ Will print "flounder	fish" (separated with a tab character), followed by a newli
 
 ::
 
-    printf '%s:%d' "Number of bananas in my pocket" 42
+    printf '%s: %d' "Number of bananas in my pocket" 42
 
 Will print "Number of bananas in my pocket: 42", _without_ a newline.

sphinx_doc_src/cmds/status.rst

@@ -13,6 +13,7 @@ status is-command-substitution
 status is-no-job-control
 status is-full-job-control
 status is-interactive-job-control
+status current-command
 status filename
 status fish-path
 status function
@@ -30,7 +31,7 @@ With no arguments, ``status`` displays a summary of the current login and job co
 
 The following operations (sub-commands) are available:
 
-- ``is-command-sub`` returns 0 if fish is currently executing a command substitution. Also ``-c`` or ``--is-command-substitution``.
+- ``is-command-substitution`` returns 0 if fish is currently executing a command substitution. Also ``-c`` or ``--is-command-substitution``.
 
 - ``is-block`` returns 0 if fish is currently executing a block of code. Also ``-b`` or ``--is-block``.
 
@@ -46,6 +47,8 @@ The following operations (sub-commands) are available:
 
 - ``is-no-job-control`` returns 0 if no job control is enabled. Also ``--is-no-job-control`` (no short flag).
 
+- ``current-command`` prints the name of the currently-running function or command, like the deprecated ``_`` variable.
+
 - ``filename`` prints the filename of the currently running script. Also ``current-filename``, ``-f`` or ``--current-filename``.
 
 - ``fish-path`` prints the absolute path to the currently executing instance of fish.

sphinx_doc_src/cmds/string.rst

@@ -52,7 +52,7 @@ The following subcommands are available.
 
 ``--style=regex`` escapes an input string for literal matching within a regex expression. The string is first converted to UTF-8 before being encoded.
 
-``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.
+``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 ``--style=regex``.
 
 "join" subcommand
 -----------------

sphinx_doc_src/cmds/type.rst

@@ -20,9 +20,9 @@ The following options are available:
 
 - ``-t`` or ``--type`` prints ``function``, ``builtin``, or ``file`` if ``NAME`` is a shell function, builtin, or disk file, respectively.
 
-- ``-p`` or ``--path`` returns the name of the disk file that would be executed, or nothing if ``type  -t  name`` would not return ``file``.
+- ``-p`` or ``--path`` prints the path to ``NAME`` if ``NAME`` resolves to an executable file in <tt>$PATH</tt>, the path to the script containing the definition of the function ``NAME`` if ``NAME`` resolves to a function loaded from a file on disk (i.e. not interactively defined at the prompt), or nothing otherwise.
 
-- ``-P`` or ``--force-path`` returns the name of the disk file that would be executed, or nothing if no file with the specified name could be found in the <tt>$PATH</tt>.
+- ``-P`` or ``--force-path`` returns the path to the executable file ``NAME``, presuming ``NAME`` is found in ``$PATH``, or nothing otherwise. ``--force-path`` explicitly resolves only the path to executable files in ``$PATH``, regardless of whether ``$NAME`` is shadowed by a function or builtin with the same name.
 
 - ``-q`` or ``--quiet`` suppresses all output; this is useful when testing the exit status.
 

sphinx_doc_src/cmds/while.rst

@@ -12,10 +12,7 @@ Description
 
 ``while`` repeatedly executes ``CONDITION``, and if the exit status is 0, then executes ``COMMANDS``.
 
-If the exit status of ``CONDITION`` is non-zero on the first iteration, ``COMMANDS`` will not be
-executed at all, and the exit status of the loop set to the exit status of ``CONDITION``.
-
-The exit status of the loop is 0 otherwise.
+The exit status of the while loop is the exit status of the last iteration of the ``COMMANDS`` executed, or 0 if none were executed. (This matches other shells and is POSIX-compatible.)
 
 You can use <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>.
 

sphinx_doc_src/index.rst

@@ -156,7 +156,7 @@ Any file descriptor can be redirected in an arbitrary way by prefixing the redir
 - To redirect output of FD N, write ``N>DESTINATION``
 - To append the output of FD N to a file, write ``N>>DESTINATION_FILE``
 
-Example: ``echo Hello 2>output.stderr`` and ``echo Hello 2>output.stderr`` are equivalent, and write the standard error (file descriptor 2) of the target program to ``output.stderr``.
+Example: ``echo Hello 2>output.stderr`` writes the standard error (file descriptor 2) of the target program to ``output.stderr``.
 
 Piping
 ------
@@ -335,8 +335,9 @@ Autosuggestions are a powerful way to quickly summon frequently entered commands
 Tab Completion
 ==============
 
-Tab completion is one of the most time saving features of any modern shell. By tapping the tab key, the user asks ``fish`` to guess the rest of the command or parameter that the user is currently typing. If  ``fish`` can only find one possible completion, ``fish`` will write it out. If there is more than one completion, ``fish`` will write out the longest prefix that all completions have in common. If the completions differ on the first character, a list of all possible completions is printed. The list features descriptions of the completions and if the list doesn't fit the screen, it is scrollable by using the arrow keys, the page up/page down keys, the tab key or the space bar. Once the list has been entered, pressing any other key will start a search. If the list has not been entered, pressing any other key will exit the list and insert the pressed key into the command line.
+Tab completion is one of the most time saving features of any modern shell. By tapping the tab key, the user asks ``fish`` to guess the rest of the command or parameter that the user is currently typing. If  ``fish`` can only find one possible completion, ``fish`` will write it out. If there is more than one completion, ``fish`` will write out the longest prefix that all completions have in common. If the completions differ on the first character, a list of all possible completions is printed. The list features descriptions of the completions and if the list doesn't fit the screen, it is scrollable by using the arrow keys, the page up/page down keys, the tab key or the space bar.
 
+If the list is visible, pressing control-S (or the ``pager-toggle-search`` binding) will allow filtering the list. Shift-tab (or the ``complete-and-search`` binding) will trigger completion with the search field immediately visible.
 These are the general purpose tab completions that ``fish`` provides:
 
 - Completion of commands (builtins, functions and regular programs).
@@ -450,7 +451,7 @@ If a star (``*``) or a question mark (``?``) is present in the parameter, ``fish
 
 - ``*`` can match any string of characters not containing '/'. This includes matching an empty string.
 
-- ``**`` matches any string of characters. This includes matching an empty string. The matched string may include the ``/`` character; that is, it recurses into subdirectories. Note that augmenting this wildcard with other strings will not match files in the current working directory (``$PWD``) if you separate the strings with a slash ("/"). This is unlike other shells such as zsh. For example, ``**\/*.fish`` in zsh will match ``.fish`` files in the PWD but in fish will only match such files in a subdirectory. In fish you should type ``***.fish`` to match files in the PWD as well as subdirectories.
+- ``**`` matches any string of characters. This includes matching an empty string. The matched string may include the ``/`` character; that is, it recurses into subdirectories. Note that augmenting this wildcard with other strings will not match files in the current working directory (``$PWD``) if you separate the strings with a slash ("/"). This is unlike other shells such as zsh. For example, ``**\/*.fish`` in zsh will match ``.fish`` files in the PWD but in fish will only match such files in a subdirectory. In fish you should type ``**.fish`` to match files in the PWD as well as subdirectories.
 
 Other shells, such as zsh, provide a rich glob syntax for restricting the files matched by globs. For example, ``**(.)``, to only match regular files. Fish prefers to defer such features to programs, such as ``find``, rather than reinventing the wheel. Thus, if you want to limit the wildcard expansion to just regular files the fish approach is to define and use a function. For example,
 
@@ -949,7 +950,7 @@ The user can change the settings of ``fish`` by changing the values of certain v
 
 - ``fish_ambiguous_width`` controls the computed width of ambiguous East Asian characters. This should be set to 1 if your terminal emulator renders these characters as single-width (typical), or 2 if double-width.
 
-- ``fish_escape_delay_ms`` overrides the default timeout of 300ms (default key bindings) or 10ms (vi key bindings) after seeing an escape character before giving up on matching a key binding. See the documentation for the <a href='bind.html#special-case-escape'>bind</a> builtin command. This delay facilitates using escape as a meta key.
+- ``fish_escape_delay_ms`` overrides the default timeout of 30ms after seeing an escape character before giving up on matching a key binding. See the documentation for the <a href='bind.html#special-case-escape'>bind</a> builtin command. This delay facilitates using escape as a meta key.
 
 - ``fish_greeting``, the greeting message printed on startup.
 
@@ -973,7 +974,7 @@ The user can change the settings of ``fish`` by changing the values of certain v
 
 ``fish`` also sends additional information to the user through the values of certain environment variables. The user cannot change the values of most of these variables.
 
-- ``_``, the name of the currently running command.
+- ``_``, the name of the currently running command (though this is deprecated, and the use of ``status current-command`` is preferred).
 
 - ``argv``, an array of arguments to the shell or function. ``argv`` is only defined when inside a function call, or if fish was invoked with a list of arguments, like ``fish myscript.fish foo bar``. This variable can be changed by the user.
 
@@ -981,6 +982,8 @@ The user can change the settings of ``fish`` by changing the values of certain v
 
 - ``HOME``, the user's home directory. This variable can be changed by the user.
 
+- ``hostname``, the machine's hostname.
+
 - ``IFS``, the internal field separator that is used for word splitting with the <a href="commands.html#read">read builtin</a>. Setting this to the empty string will also disable line splitting in `command substitution <#expand-command-substitution>`_. This variable can be changed by the user.
 
 - ``PWD``, the current working directory.
@@ -1078,15 +1081,31 @@ The following variables are available to change the highlighting colors in fish:
 
 Additionally, the following variables are available to change the highlighting in the completion pager:
 
+- ``fish_pager_color_progress``, the color of the progress bar at the bottom left corner
+
+- ``fish_pager_color_background``, the background color of a line
+
 - ``fish_pager_color_prefix``, the color of the prefix string, i.e. the string that is to be completed
 
 - ``fish_pager_color_completion``, the color of the completion itself
 
 - ``fish_pager_color_description``, the color of the completion description
 
-- ``fish_pager_color_progress``, the color of the progress bar at the bottom left corner
+- ``fish_pager_color_secondary_background``, ``fish_pager_color_background`` of every second unselected completion. Defaults to ``fish_pager_color_background``
 
-- ``fish_pager_color_secondary``, the background color of the every second completion
+- ``fish_pager_color_secondary_ prefix``, ``fish_pager_color_prefix`` of every second unselected completion. Defaults to ``fish_pager_color_prefix``
+
+- ``fish_pager_color_secondary_completion``, ``fish_pager_color_completion`` of every second unselected completion. Defaults to ``fish_pager_color_completion``
+
+- ``fish_pager_color_secondary_description``, ``fish_pager_color_description`` of every second unselected completion. Defaults to ``fish_pager_color_description``
+
+- ``fish_pager_color_selected_background``, ``fish_pager_color_background`` of the selected completion. Defaults to ``fish_color_search_match``
+
+- ``fish_pager_color_selected_prefix``, ``fish_pager_color_prefix`` of the selected completion. Defaults to ``fish_pager_color_prefix``
+
+- ``fish_pager_color_selected_completion``, ``fish_pager_color_completion`` of the selected completion. Defaults to ``fish_pager_color_completion``
+
+- ``fish_pager_color_selected_description``, ``fish_pager_color_description`` of the selected completion. Defaults to ``fish_pager_color_description``
 
 Example:
 
@@ -1142,7 +1161,9 @@ Some bindings are shared between emacs- and vi-mode because they aren't text edi
 
 - @key{Tab} `completes <#completion>`_ the current token. @key{Shift, Tab} completes the current token and starts the pager's search mode.
 
-- @key{Alt,&larr;,Left} and @key{Alt,&rarr;,Right} move the cursor one word left or right, or moves forward/backward in the directory history if the command line is empty. If the cursor is already at the end of the line, and an autosuggestion is available, @key{Alt,&rarr;,Right} (or @key{Alt,F}) accepts the first word in the suggestion.
+- @key{Alt,&larr;,Left} and @key{Alt,&rarr;,Right} move the cursor one word left or right (to the next space or punctuation mark), or moves forward/backward in the directory history if the command line is empty. If the cursor is already at the end of the line, and an autosuggestion is available, @key{Alt,&rarr;,Right} (or @key{Alt,F}) accepts the first word in the suggestion.
+
+- @key{Shift,&larr;,Left} and @key{Shift,&rarr;,Right} move the cursor one word left or right, without stopping on punctuation.
 
 - @cursor_key{&uarr;,Up} and @cursor_key{&darr;,Down} (or @key{Control,P} and @key{Control,N} for emacs aficionados) search the command history for the previous/next command containing the string that was specified on the commandline before the search was started. If the commandline was empty when the search started, all commands match. See the `history <#history>`_ section for more information on history searching.
 
@@ -1352,7 +1373,6 @@ On startup, Fish evaluates a number of configuration files, which can be used to
 
 Configuration files are evaluated in the following order:
 - Configuration shipped with fish, which should not be edited, in ``$__fish_data_dir/config.fish`` (usually ``/usr/share/fish/config.fish`).
-- System-wide configuration files, where administrators can include initialization that should be run for all users on the system - similar to ``/etc/profile`` for POSIX-style shells - in ``$__fish_sysconf_dir``` (usually ``/etc/fish/config.fish``);
 - Configuration snippets in files ending in ``.fish``, in the directories:
   - ``$__fish_config_dir/conf.d`` (by default, ``~/.config/fish/conf.d/``)
   - ``$__fish_sysconf_dir/conf.d`` (by default, ``/etc/fish/conf.d``)
@@ -1361,6 +1381,7 @@ Configuration files are evaluated in the following order:
   If there are multiple files with the same name in these directories, only the first will be executed.
   They are executed in order of their filename, sorted (like globs) in a natural order (i.e. "01" sorts before "2").
 
+- System-wide configuration files, where administrators can include initialization that should be run for all users on the system - similar to ``/etc/profile`` for POSIX-style shells - in ``$__fish_sysconf_dir``` (usually ``/etc/fish/config.fish``);
 - User initialization, usually in `~/.config/fish/config.fish` (controlled by the ``XDG_CONFIG_HOME`` environment variable, and accessible as ``$__fish_config_dir``).
 
 These paths are controlled by parameters set at build, install, or run time, and may vary from the defaults listed above.