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>.