From c8dc306b189fb4d7699298f77e6f7781319b8411 Mon Sep 17 00:00:00 2001 From: ridiculousfish Date: Wed, 2 Jan 2019 20:10:47 -0800 Subject: [PATCH] Fix command section separator line lengths --- sphinx_doc_src/cmds/abbr.rst | 10 ++--- sphinx_doc_src/cmds/alias.rst | 6 +-- sphinx_doc_src/cmds/and.rst | 6 +-- sphinx_doc_src/cmds/argparse.rst | 16 ++++---- sphinx_doc_src/cmds/begin.rst | 6 +-- sphinx_doc_src/cmds/bg.rst | 6 +-- sphinx_doc_src/cmds/bind.rst | 10 ++--- sphinx_doc_src/cmds/block.rst | 8 ++-- sphinx_doc_src/cmds/break.rst | 6 +-- sphinx_doc_src/cmds/breakpoint.rst | 4 +- sphinx_doc_src/cmds/builtin.rst | 6 +-- sphinx_doc_src/cmds/case.rst | 6 +-- sphinx_doc_src/cmds/cd.rst | 8 ++-- sphinx_doc_src/cmds/cdh.rst | 6 +-- sphinx_doc_src/cmds/command.rst | 6 +-- sphinx_doc_src/cmds/commandline.rst | 6 +-- sphinx_doc_src/cmds/complete.rst | 6 +-- sphinx_doc_src/cmds/contains.rst | 6 +-- sphinx_doc_src/cmds/continue.rst | 6 +-- sphinx_doc_src/cmds/count.rst | 6 +-- sphinx_doc_src/cmds/dirh.rst | 4 +- sphinx_doc_src/cmds/dirs.rst | 4 +- sphinx_doc_src/cmds/disown.rst | 6 +-- sphinx_doc_src/cmds/echo.rst | 8 ++-- sphinx_doc_src/cmds/else.rst | 6 +-- sphinx_doc_src/cmds/emit.rst | 8 ++-- sphinx_doc_src/cmds/end.rst | 4 +- sphinx_doc_src/cmds/eval.rst | 6 +-- sphinx_doc_src/cmds/exec.rst | 6 +-- sphinx_doc_src/cmds/exit.rst | 4 +- sphinx_doc_src/cmds/false.rst | 4 +- sphinx_doc_src/cmds/fg.rst | 6 +-- sphinx_doc_src/cmds/fish.rst | 4 +- .../cmds/fish_breakpoint_prompt.rst | 6 +-- sphinx_doc_src/cmds/fish_config.rst | 6 +-- sphinx_doc_src/cmds/fish_indent.rst | 4 +- sphinx_doc_src/cmds/fish_key_reader.rst | 6 +-- sphinx_doc_src/cmds/fish_mode_prompt.rst | 6 +-- sphinx_doc_src/cmds/fish_opt.rst | 6 +-- sphinx_doc_src/cmds/fish_prompt.rst | 6 +-- sphinx_doc_src/cmds/fish_right_prompt.rst | 6 +-- .../cmds/fish_update_completions.rst | 4 +- sphinx_doc_src/cmds/fish_vi_mode.rst | 4 +- sphinx_doc_src/cmds/for.rst | 8 ++-- sphinx_doc_src/cmds/funced.rst | 4 +- sphinx_doc_src/cmds/funcsave.rst | 4 +- sphinx_doc_src/cmds/function.rst | 8 ++-- sphinx_doc_src/cmds/functions.rst | 6 +-- sphinx_doc_src/cmds/help.rst | 6 +-- sphinx_doc_src/cmds/history.rst | 10 ++--- sphinx_doc_src/cmds/if.rst | 6 +-- sphinx_doc_src/cmds/isatty.rst | 6 +-- sphinx_doc_src/cmds/jobs.rst | 8 ++-- sphinx_doc_src/cmds/math.rst | 18 ++++----- sphinx_doc_src/cmds/nextd.rst | 6 +-- sphinx_doc_src/cmds/not.rst | 6 +-- sphinx_doc_src/cmds/open.rst | 6 +-- sphinx_doc_src/cmds/or.rst | 6 +-- sphinx_doc_src/cmds/popd.rst | 6 +-- sphinx_doc_src/cmds/prevd.rst | 6 +-- sphinx_doc_src/cmds/printf.rst | 6 +-- sphinx_doc_src/cmds/prompt_pwd.rst | 4 +- sphinx_doc_src/cmds/psub.rst | 6 +-- sphinx_doc_src/cmds/pushd.rst | 6 +-- sphinx_doc_src/cmds/pwd.rst | 2 +- sphinx_doc_src/cmds/random.rst | 6 +-- sphinx_doc_src/cmds/read.rst | 8 ++-- sphinx_doc_src/cmds/realpath.rst | 4 +- sphinx_doc_src/cmds/return.rst | 6 +-- sphinx_doc_src/cmds/set.rst | 8 ++-- sphinx_doc_src/cmds/set_color.rst | 10 ++--- sphinx_doc_src/cmds/source.rst | 6 +-- sphinx_doc_src/cmds/status.rst | 6 +-- sphinx_doc_src/cmds/string.rst | 40 +++++++++---------- sphinx_doc_src/cmds/suspend.rst | 4 +- sphinx_doc_src/cmds/switch.rst | 6 +-- sphinx_doc_src/cmds/test.rst | 16 ++++---- sphinx_doc_src/cmds/trap.rst | 6 +-- sphinx_doc_src/cmds/true.rst | 4 +- sphinx_doc_src/cmds/type.rst | 6 +-- sphinx_doc_src/cmds/ulimit.rst | 6 +-- sphinx_doc_src/cmds/umask.rst | 6 +-- sphinx_doc_src/cmds/vared.rst | 6 +-- sphinx_doc_src/cmds/wait.rst | 6 +-- sphinx_doc_src/cmds/while.rst | 6 +-- 85 files changed, 287 insertions(+), 287 deletions(-) diff --git a/sphinx_doc_src/cmds/abbr.rst b/sphinx_doc_src/cmds/abbr.rst index 7aff46d13..1346c8adb 100644 --- a/sphinx_doc_src/cmds/abbr.rst +++ b/sphinx_doc_src/cmds/abbr.rst @@ -1,5 +1,5 @@ abbr - manage fish abbreviations -========================================== +================================ Synopsis -------- @@ -11,14 +11,14 @@ abbr --show abbr --list 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. Options ------------- +------- The following options are available: @@ -40,7 +40,7 @@ In addition, when adding abbreviations: See the "Internals" section for more on them. Examples ------------- +-------- @@ -83,7 +83,7 @@ Erase the ``gco`` abbreviation. Import the abbreviations defined on another_host over SSH. 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: diff --git a/sphinx_doc_src/cmds/alias.rst b/sphinx_doc_src/cmds/alias.rst index 39cad912f..487b35c5c 100644 --- a/sphinx_doc_src/cmds/alias.rst +++ b/sphinx_doc_src/cmds/alias.rst @@ -1,5 +1,5 @@ alias - create a function -========================================== +========================= Synopsis -------- @@ -10,7 +10,7 @@ alias [OPTIONS] NAME=DEFINITION 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 function. @@ -28,7 +28,7 @@ The following options are available: - ``-s`` or ``--save`` Automatically save the function created by the alias into your fish configuration directory using funcsave. Example ------------- +------- The following code will create ``rmi``, which runs ``rm`` with additional arguments on every invocation. diff --git a/sphinx_doc_src/cmds/and.rst b/sphinx_doc_src/cmds/and.rst index 79ae303e1..a5614c4ad 100644 --- a/sphinx_doc_src/cmds/and.rst +++ b/sphinx_doc_src/cmds/and.rst @@ -1,5 +1,5 @@ and - conditionally execute a command -========================================== +===================================== Synopsis -------- @@ -8,7 +8,7 @@ COMMAND1; and COMMAND2 Description ------------- +----------- ``and`` is used to execute a command if the previous command was successful (returned a status of 0). @@ -17,7 +17,7 @@ Description ``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 $status variable. 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. diff --git a/sphinx_doc_src/cmds/argparse.rst b/sphinx_doc_src/cmds/argparse.rst index 3628a0a0e..c328e205b 100644 --- a/sphinx_doc_src/cmds/argparse.rst +++ b/sphinx_doc_src/cmds/argparse.rst @@ -1,5 +1,5 @@ argparse - parse options passed to a fish script or function -========================================== +============================================================ Synopsis -------- @@ -8,7 +8,7 @@ argparse [OPTIONS] OPTION_SPEC... -- [ARG...] 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 usage section below. @@ -19,7 +19,7 @@ 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. Options ------------- +------- The following ``argparse`` options are available. They must appear before all OPTION_SPECs: @@ -36,7 +36,7 @@ The following ``argparse`` options are available. They must appear before all OP - ``-h`` or ``--help`` displays help about using this command. 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``: @@ -73,7 +73,7 @@ But this is not: The first ``--`` seen is what allows the ``argparse`` command to reliably separate the option specifications from the command arguments. Option Specifications ------------- +--------------------- Each option specification is a string composed of @@ -98,7 +98,7 @@ See the ``fish_opt`` command for a friendlier but more v 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. 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: @@ -115,7 +115,7 @@ 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. Example OPTION_SPECs ------------- +-------------------- Some OPTION_SPEC examples: @@ -144,6 +144,6 @@ After parsing the arguments the ``argv`` var is set with local scope to any valu If an error occurs during argparse processing it will exit with a non-zero status and print error messages to stderr. 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. diff --git a/sphinx_doc_src/cmds/begin.rst b/sphinx_doc_src/cmds/begin.rst index a9b626f98..101d7e89b 100644 --- a/sphinx_doc_src/cmds/begin.rst +++ b/sphinx_doc_src/cmds/begin.rst @@ -1,5 +1,5 @@ begin - start a new block of code -========================================== +================================= Synopsis -------- @@ -8,7 +8,7 @@ begin; [COMMANDS...;] end Description ------------- +----------- ``begin`` is used to create a new block of code. @@ -20,7 +20,7 @@ The block is unconditionally executed. ``begin; ...; end`` is equivalent to ``if 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. diff --git a/sphinx_doc_src/cmds/bg.rst b/sphinx_doc_src/cmds/bg.rst index 7db38aa7f..a90e8cfb9 100644 --- a/sphinx_doc_src/cmds/bg.rst +++ b/sphinx_doc_src/cmds/bg.rst @@ -1,5 +1,5 @@ bg - send jobs to background -========================================== +============================ Synopsis -------- @@ -8,7 +8,7 @@ bg [PID...] Description ------------- +----------- ``bg`` sends jobs to the background, resuming them if they are stopped. @@ -20,7 +20,7 @@ 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. Example ------------- +------- ``bg 123 456 789`` will background 123, 456 and 789. diff --git a/sphinx_doc_src/cmds/bind.rst b/sphinx_doc_src/cmds/bind.rst index dacf10cfd..76c182793 100644 --- a/sphinx_doc_src/cmds/bind.rst +++ b/sphinx_doc_src/cmds/bind.rst @@ -1,5 +1,5 @@ bind - handle fish key bindings -========================================== +=============================== Synopsis -------- @@ -17,7 +17,7 @@ bind (-e | --erase) [(-M | --mode) MODE] Description ------------- +----------- ``bind`` adds a binding for the specified key sequence to the specified command. @@ -62,7 +62,7 @@ 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``). Special input functions ------------- +----------------------- The following special input functions are available: - ``accept-autosuggestion``, accept the current autosuggestion completely @@ -147,7 +147,7 @@ The following special input functions are available: Examples ------------- +-------- @@ -176,7 +176,7 @@ Turns on Vi key bindings and rebinds @key{Control,C} to clear the input line. 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. diff --git a/sphinx_doc_src/cmds/block.rst b/sphinx_doc_src/cmds/block.rst index acd7e7c37..db9914d0b 100644 --- a/sphinx_doc_src/cmds/block.rst +++ b/sphinx_doc_src/cmds/block.rst @@ -1,5 +1,5 @@ block - temporarily block delivery of events -========================================== +============================================ Synopsis -------- @@ -8,7 +8,7 @@ block [OPTIONS...] Description ------------- +----------- ``block`` prevents events triggered by ``fish`` or the ``emit`` command from being delivered and acted upon while the block is in place. @@ -28,7 +28,7 @@ The following parameters are available: Example ------------- +------- @@ -49,6 +49,6 @@ Example 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. diff --git a/sphinx_doc_src/cmds/break.rst b/sphinx_doc_src/cmds/break.rst index 9251df0b6..b4b55870e 100644 --- a/sphinx_doc_src/cmds/break.rst +++ b/sphinx_doc_src/cmds/break.rst @@ -1,5 +1,5 @@ break - stop the current inner loop -========================================== +=================================== Synopsis -------- @@ -8,7 +8,7 @@ LOOP_CONSTRUCT; [COMMANDS...] break; [COMMANDS...] end Description ------------- +----------- ``break`` halts a currently running loop, such as a for loop or a while loop. It is usually added inside of a conditional block such as an if statement or a switch statement. @@ -16,7 +16,7 @@ There are no parameters for ``break``. Example ------------- +------- The following code searches all .c files for "smurf", and halts at the first occurrence. diff --git a/sphinx_doc_src/cmds/breakpoint.rst b/sphinx_doc_src/cmds/breakpoint.rst index 4db33f5ee..6486fbf5a 100644 --- a/sphinx_doc_src/cmds/breakpoint.rst +++ b/sphinx_doc_src/cmds/breakpoint.rst @@ -1,5 +1,5 @@ breakpoint - Launch debug mode -========================================== +============================== Synopsis -------- @@ -8,7 +8,7 @@ breakpoint Description ------------- +----------- ``breakpoint`` is used to halt a running script and launch an interactive debugging prompt. diff --git a/sphinx_doc_src/cmds/builtin.rst b/sphinx_doc_src/cmds/builtin.rst index 48d413a59..651064e1a 100644 --- a/sphinx_doc_src/cmds/builtin.rst +++ b/sphinx_doc_src/cmds/builtin.rst @@ -1,5 +1,5 @@ builtin - run a builtin command -========================================== +=============================== Synopsis -------- @@ -8,7 +8,7 @@ builtin BUILTINNAME [OPTIONS...] Description ------------- +----------- ``builtin`` forces the shell to use a builtin command, rather than a function or program. @@ -18,7 +18,7 @@ The following parameters are available: Example ------------- +------- diff --git a/sphinx_doc_src/cmds/case.rst b/sphinx_doc_src/cmds/case.rst index 2ed89819e..2568f4fd0 100644 --- a/sphinx_doc_src/cmds/case.rst +++ b/sphinx_doc_src/cmds/case.rst @@ -1,5 +1,5 @@ case - conditionally execute a block of commands -========================================== +================================================ Synopsis -------- @@ -8,7 +8,7 @@ switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end 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. @@ -20,7 +20,7 @@ Note that command substitutions in a case statement will be evaluated even if it Example ------------- +------- Say \$animal contains the name of an animal. Then this code would classify it: diff --git a/sphinx_doc_src/cmds/cd.rst b/sphinx_doc_src/cmds/cd.rst index 0707d40a3..2a6fcc748 100644 --- a/sphinx_doc_src/cmds/cd.rst +++ b/sphinx_doc_src/cmds/cd.rst @@ -1,5 +1,5 @@ cd - change directory -========================================== +===================== Synopsis -------- @@ -8,7 +8,7 @@ cd [DIRECTORY] 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. @@ -22,7 +22,7 @@ Fish also ships a wrapper function around the builtin ``cd`` that understands `` 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. Examples ------------- +-------- @@ -36,6 +36,6 @@ Examples See Also ------------- +-------- See also the ``cdh`` command for changing to a recently visited directory. diff --git a/sphinx_doc_src/cmds/cdh.rst b/sphinx_doc_src/cmds/cdh.rst index 60b58fe46..a29a53a9d 100644 --- a/sphinx_doc_src/cmds/cdh.rst +++ b/sphinx_doc_src/cmds/cdh.rst @@ -1,5 +1,5 @@ cdh - change to a recently visited directory -========================================== +============================================ Synopsis @@ -9,13 +9,13 @@ cdh [ directory ] 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. See Also ------------- +-------- See also the ``prevd`` and ``pushd`` commands which also work with the recent ``cd`` history and are provided for compatibility with other shells. diff --git a/sphinx_doc_src/cmds/command.rst b/sphinx_doc_src/cmds/command.rst index b72f79b34..82114a468 100644 --- a/sphinx_doc_src/cmds/command.rst +++ b/sphinx_doc_src/cmds/command.rst @@ -1,5 +1,5 @@ command - run a program -========================================== +======================= Synopsis -------- @@ -8,7 +8,7 @@ command [OPTIONS] COMMANDNAME [ARGS...] Description ------------- +----------- ``command`` forces the shell to execute the program ``COMMANDNAME`` and ignore any functions or builtins with the same name. @@ -25,7 +25,7 @@ With the ``-s`` option, ``command`` treats every argument as a separate command For basic compatibility with POSIX ``command``, the ``-v`` flag is recognized as an alias for ``-s``. Examples ------------- +-------- ``command ls`` causes fish to execute the ``ls`` program, even if an ``ls`` function exists. diff --git a/sphinx_doc_src/cmds/commandline.rst b/sphinx_doc_src/cmds/commandline.rst index d13dcac84..7782c02d2 100644 --- a/sphinx_doc_src/cmds/commandline.rst +++ b/sphinx_doc_src/cmds/commandline.rst @@ -1,5 +1,5 @@ commandline - set or get the current command line buffer -========================================== +======================================================== Synopsis -------- @@ -8,7 +8,7 @@ commandline [OPTIONS] [CMD] Description ------------- +----------- ``commandline`` can be used to set or get the current contents of the command line buffer. @@ -60,7 +60,7 @@ The following options output metadata about the commandline state: Example ------------- +------- ``commandline -j $history[3]`` replaces the job under the cursor with the third item from the command line history. diff --git a/sphinx_doc_src/cmds/complete.rst b/sphinx_doc_src/cmds/complete.rst index 6e4cf79e6..ab3ba1007 100644 --- a/sphinx_doc_src/cmds/complete.rst +++ b/sphinx_doc_src/cmds/complete.rst @@ -1,5 +1,5 @@ complete - edit command specific tab-completions -========================================== +================================================ Synopsis -------- @@ -21,7 +21,7 @@ complete ( -C[STRING] | --do-complete[=STRING] ) Description ------------- +----------- For an introduction to specifying completions, see Writing your own completions in @@ -95,7 +95,7 @@ When erasing completions, it is possible to either erase all completions for a s Example ------------- +------- The short style option ``-o`` for the ``gcc`` command requires that a file follows it. This can be done using writing: diff --git a/sphinx_doc_src/cmds/contains.rst b/sphinx_doc_src/cmds/contains.rst index e5338c80c..081e15fd3 100644 --- a/sphinx_doc_src/cmds/contains.rst +++ b/sphinx_doc_src/cmds/contains.rst @@ -1,5 +1,5 @@ contains - test if a word is present in a list -========================================== +============================================== Synopsis -------- @@ -8,7 +8,7 @@ contains [OPTIONS] KEY [VALUES...] 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. @@ -19,7 +19,7 @@ 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. Example ------------- +------- If $animals is a list of animals, the following will test if it contains a cat: diff --git a/sphinx_doc_src/cmds/continue.rst b/sphinx_doc_src/cmds/continue.rst index 39cddf805..b5cac1b57 100644 --- a/sphinx_doc_src/cmds/continue.rst +++ b/sphinx_doc_src/cmds/continue.rst @@ -1,5 +1,5 @@ continue - skip the remainder of the current iteration of the current inner loop -========================================== +================================================================================ Synopsis -------- @@ -8,12 +8,12 @@ LOOP_CONSTRUCT; [COMMANDS...;] continue; [COMMANDS...;] end Description ------------- +----------- ``continue`` skips the remainder of the current iteration of the current inner loop, such as a for loop or a while loop. It is usually added inside of a conditional block such as an if statement or a switch statement. Example ------------- +------- The following code removes all tmp files that do not contain the word smurf. diff --git a/sphinx_doc_src/cmds/count.rst b/sphinx_doc_src/cmds/count.rst index fe89b2261..058ea1102 100644 --- a/sphinx_doc_src/cmds/count.rst +++ b/sphinx_doc_src/cmds/count.rst @@ -1,5 +1,5 @@ count - count the number of elements of an array -========================================== +================================================ Synopsis -------- @@ -8,7 +8,7 @@ count $VARIABLE 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. @@ -18,7 +18,7 @@ Description Example ------------- +------- diff --git a/sphinx_doc_src/cmds/dirh.rst b/sphinx_doc_src/cmds/dirh.rst index 847c64df7..2b9749521 100644 --- a/sphinx_doc_src/cmds/dirh.rst +++ b/sphinx_doc_src/cmds/dirh.rst @@ -1,5 +1,5 @@ dirh - print directory history -========================================== +============================== Synopsis -------- @@ -8,7 +8,7 @@ dirh 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. diff --git a/sphinx_doc_src/cmds/dirs.rst b/sphinx_doc_src/cmds/dirs.rst index 6dff26d1a..d888489e4 100644 --- a/sphinx_doc_src/cmds/dirs.rst +++ b/sphinx_doc_src/cmds/dirs.rst @@ -1,5 +1,5 @@ dirs - print directory stack -========================================== +============================ Synopsis -------- @@ -9,7 +9,7 @@ dirs -c Description ------------- +----------- ``dirs`` prints the current directory stack, as created by the ``pushd`` command. diff --git a/sphinx_doc_src/cmds/disown.rst b/sphinx_doc_src/cmds/disown.rst index 701c62b3a..65732b389 100644 --- a/sphinx_doc_src/cmds/disown.rst +++ b/sphinx_doc_src/cmds/disown.rst @@ -1,5 +1,5 @@ disown - remove a process from the list of jobs -========================================== +=============================================== Synopsis -------- @@ -8,7 +8,7 @@ disown [ PID ... ] Description ------------- +----------- ``disown`` removes the specified job from the list of jobs. The job itself continues to exist, but fish does not keep track of it any longer. @@ -21,7 +21,7 @@ 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. 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. diff --git a/sphinx_doc_src/cmds/echo.rst b/sphinx_doc_src/cmds/echo.rst index 0d366296f..065023e3c 100644 --- a/sphinx_doc_src/cmds/echo.rst +++ b/sphinx_doc_src/cmds/echo.rst @@ -1,5 +1,5 @@ echo - display a line of text -========================================== +============================= Synopsis -------- @@ -8,7 +8,7 @@ echo [OPTIONS] [STRING] Description ------------- +----------- ``echo`` displays a string of text. @@ -23,7 +23,7 @@ The following options are available: - ``-e``, Enable interpretation of backslash escapes Escape Sequences ------------- +---------------- If ``-e`` is used, the following sequences are recognized: @@ -52,7 +52,7 @@ If ``-e`` is used, the following sequences are recognized: - ``\xHH`` byte with hexadecimal value HH (1 to 2 digits) Example ------------- +------- diff --git a/sphinx_doc_src/cmds/else.rst b/sphinx_doc_src/cmds/else.rst index 8c8f0e1d6..71523a694 100644 --- a/sphinx_doc_src/cmds/else.rst +++ b/sphinx_doc_src/cmds/else.rst @@ -1,5 +1,5 @@ else - execute command if a condition is not met -========================================== +================================================ Synopsis -------- @@ -8,13 +8,13 @@ if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end 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. Example ------------- +------- The following code tests whether a file ``foo.txt`` exists as a regular file. diff --git a/sphinx_doc_src/cmds/emit.rst b/sphinx_doc_src/cmds/emit.rst index a4326eb51..1a5cbc386 100644 --- a/sphinx_doc_src/cmds/emit.rst +++ b/sphinx_doc_src/cmds/emit.rst @@ -1,5 +1,5 @@ emit - Emit a generic event -========================================== +=========================== Synopsis -------- @@ -8,13 +8,13 @@ emit EVENT_NAME [ARGUMENTS...] 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. Example ------------- +------- The following code first defines an event handler for the generic event named 'test_event', and then emits an event of that type. @@ -31,6 +31,6 @@ The following code first defines an event handler for the generic event named 't 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. diff --git a/sphinx_doc_src/cmds/end.rst b/sphinx_doc_src/cmds/end.rst index 3ed4d66b6..e1e7b2182 100644 --- a/sphinx_doc_src/cmds/end.rst +++ b/sphinx_doc_src/cmds/end.rst @@ -1,5 +1,5 @@ end - end a block of commands. -========================================== +============================== Synopsis -------- @@ -12,7 +12,7 @@ switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end Description ------------- +----------- ``end`` ends a block of commands. diff --git a/sphinx_doc_src/cmds/eval.rst b/sphinx_doc_src/cmds/eval.rst index bd76f9743..f34dbd767 100644 --- a/sphinx_doc_src/cmds/eval.rst +++ b/sphinx_doc_src/cmds/eval.rst @@ -1,5 +1,5 @@ eval - evaluate the specified commands -========================================== +====================================== Synopsis -------- @@ -8,13 +8,13 @@ eval [COMMANDS...] 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. 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. diff --git a/sphinx_doc_src/cmds/exec.rst b/sphinx_doc_src/cmds/exec.rst index e9b77c6e6..8acc7d6be 100644 --- a/sphinx_doc_src/cmds/exec.rst +++ b/sphinx_doc_src/cmds/exec.rst @@ -1,5 +1,5 @@ exec - execute command in current process -========================================== +========================================= Synopsis -------- @@ -8,12 +8,12 @@ exec COMMAND [OPTIONS...] Description ------------- +----------- ``exec`` replaces the currently running shell with a new command. On successful completion, ``exec`` never returns. ``exec`` cannot be used inside a pipeline. Example ------------- +------- ``exec emacs`` starts up the emacs text editor, and exits ``fish``. When emacs exits, the session will terminate. diff --git a/sphinx_doc_src/cmds/exit.rst b/sphinx_doc_src/cmds/exit.rst index cd793b884..bc9fe2de1 100644 --- a/sphinx_doc_src/cmds/exit.rst +++ b/sphinx_doc_src/cmds/exit.rst @@ -1,5 +1,5 @@ exit - exit the shell -========================================== +===================== Synopsis -------- @@ -8,7 +8,7 @@ exit [STATUS] 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. diff --git a/sphinx_doc_src/cmds/false.rst b/sphinx_doc_src/cmds/false.rst index 47f526508..d972f5864 100644 --- a/sphinx_doc_src/cmds/false.rst +++ b/sphinx_doc_src/cmds/false.rst @@ -1,5 +1,5 @@ false - return an unsuccessful result -========================================== +===================================== Synopsis -------- @@ -8,6 +8,6 @@ false Description ------------- +----------- ``false`` sets the exit status to 1. diff --git a/sphinx_doc_src/cmds/fg.rst b/sphinx_doc_src/cmds/fg.rst index a1bb08b9f..33831232b 100644 --- a/sphinx_doc_src/cmds/fg.rst +++ b/sphinx_doc_src/cmds/fg.rst @@ -1,5 +1,5 @@ fg - bring job to foreground -========================================== +============================ Synopsis -------- @@ -8,12 +8,12 @@ fg [PID] Description ------------- +----------- ``fg`` brings the specified job 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. Example ------------- +------- ``fg`` will put the last job in the foreground. diff --git a/sphinx_doc_src/cmds/fish.rst b/sphinx_doc_src/cmds/fish.rst index 1325818ef..b3b8a090b 100644 --- a/sphinx_doc_src/cmds/fish.rst +++ b/sphinx_doc_src/cmds/fish.rst @@ -1,5 +1,5 @@ fish - the friendly interactive shell -========================================== +===================================== Synopsis -------- @@ -8,7 +8,7 @@ fish [OPTIONS] [-c command] [FILE [ARGUMENTS...]] Description ------------- +----------- ``fish`` is a command-line shell written mainly with interactive use in mind. The full manual is available in HTML by using the help command from inside fish. diff --git a/sphinx_doc_src/cmds/fish_breakpoint_prompt.rst b/sphinx_doc_src/cmds/fish_breakpoint_prompt.rst index e8519b279..4d4bd2ac6 100644 --- a/sphinx_doc_src/cmds/fish_breakpoint_prompt.rst +++ b/sphinx_doc_src/cmds/fish_breakpoint_prompt.rst @@ -1,5 +1,5 @@ fish_breakpoint_prompt - define the appearance of the command line prompt when in the context of a ``breakpoint`` command -========================================== +========================================================================================================================= Synopsis -------- @@ -10,7 +10,7 @@ end 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. @@ -20,7 +20,7 @@ The exit status of commands within ``fish_breakpoint_prompt`` will not modify th Example ------------- +------- A simple prompt that is a simplified version of the default debugging prompt: diff --git a/sphinx_doc_src/cmds/fish_config.rst b/sphinx_doc_src/cmds/fish_config.rst index c761479bb..386797299 100644 --- a/sphinx_doc_src/cmds/fish_config.rst +++ b/sphinx_doc_src/cmds/fish_config.rst @@ -1,9 +1,9 @@ fish_config - start the web-based configuration interface -========================================== +========================================================= Description ------------- +----------- ``fish_config`` starts the web-based configuration interface. @@ -17,6 +17,6 @@ If the ``BROWSER`` environment variable is set, it will be used as the name of t Example ------------- +------- ``fish_config`` opens a new web browser window and allows you to configure certain fish settings. diff --git a/sphinx_doc_src/cmds/fish_indent.rst b/sphinx_doc_src/cmds/fish_indent.rst index 10da3ee1d..56dd7e798 100644 --- a/sphinx_doc_src/cmds/fish_indent.rst +++ b/sphinx_doc_src/cmds/fish_indent.rst @@ -1,5 +1,5 @@ fish_indent - indenter and prettifier -========================================== +===================================== Synopsis -------- @@ -8,7 +8,7 @@ fish_indent [OPTIONS] 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. diff --git a/sphinx_doc_src/cmds/fish_key_reader.rst b/sphinx_doc_src/cmds/fish_key_reader.rst index 4290ec7b6..ea8f4d4c3 100644 --- a/sphinx_doc_src/cmds/fish_key_reader.rst +++ b/sphinx_doc_src/cmds/fish_key_reader.rst @@ -1,5 +1,5 @@ fish_key_reader - explore what characters keyboard keys send -========================================== +============================================================ Synopsis -------- @@ -8,7 +8,7 @@ fish_key_reader [OPTIONS] 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. @@ -27,7 +27,7 @@ The following options are available: - ``-v`` or ``--version`` prints fish_key_reader's version and exits. 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``. diff --git a/sphinx_doc_src/cmds/fish_mode_prompt.rst b/sphinx_doc_src/cmds/fish_mode_prompt.rst index 97d84da8f..88e1cb2e7 100644 --- a/sphinx_doc_src/cmds/fish_mode_prompt.rst +++ b/sphinx_doc_src/cmds/fish_mode_prompt.rst @@ -1,18 +1,18 @@ 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. 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``. Example ------------- +------- diff --git a/sphinx_doc_src/cmds/fish_opt.rst b/sphinx_doc_src/cmds/fish_opt.rst index a844fe330..0d3516500 100644 --- a/sphinx_doc_src/cmds/fish_opt.rst +++ b/sphinx_doc_src/cmds/fish_opt.rst @@ -1,5 +1,5 @@ fish_opt - create an option spec for the argparse command -========================================== +========================================================= Synopsis -------- @@ -10,7 +10,7 @@ fish_opt ( -s X | --short=X ) [ -l LONG | --long=LONG ] [ --long-only ] \ Description ------------- +----------- This command provides a way to produce option specifications suitable for use with the ``argparse`` 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. @@ -31,7 +31,7 @@ The following ``argparse`` options are available: - ``-h`` or ``--help`` displays help about using this command. Examples ------------- +-------- Define a single option spec for the boolean help flag: diff --git a/sphinx_doc_src/cmds/fish_prompt.rst b/sphinx_doc_src/cmds/fish_prompt.rst index 4e03fa28c..99a047a1c 100644 --- a/sphinx_doc_src/cmds/fish_prompt.rst +++ b/sphinx_doc_src/cmds/fish_prompt.rst @@ -1,5 +1,5 @@ fish_prompt - define the appearance of the command line prompt -========================================== +============================================================== Synopsis -------- @@ -10,7 +10,7 @@ end 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. @@ -20,7 +20,7 @@ The exit status of commands within ``fish_prompt`` will not modify the value of Example ------------- +------- A simple prompt: diff --git a/sphinx_doc_src/cmds/fish_right_prompt.rst b/sphinx_doc_src/cmds/fish_right_prompt.rst index 701cb65ad..01e8cc263 100644 --- a/sphinx_doc_src/cmds/fish_right_prompt.rst +++ b/sphinx_doc_src/cmds/fish_right_prompt.rst @@ -1,5 +1,5 @@ fish_right_prompt - define the appearance of the right-side command line prompt -========================================== +=============================================================================== Synopsis -------- @@ -10,7 +10,7 @@ end Description ------------- +----------- ``fish_right_prompt`` is similar to ``fish_prompt``, except that it appears on the right side of the terminal window. @@ -18,7 +18,7 @@ Multiple lines are not supported in ``fish_right_prompt``. Example ------------- +------- A simple right prompt: diff --git a/sphinx_doc_src/cmds/fish_update_completions.rst b/sphinx_doc_src/cmds/fish_update_completions.rst index a1f5de530..b269d56bf 100644 --- a/sphinx_doc_src/cmds/fish_update_completions.rst +++ b/sphinx_doc_src/cmds/fish_update_completions.rst @@ -1,9 +1,9 @@ fish_update_completions - Update completions using manual pages -========================================== +=============================================================== Description ------------- +----------- ``fish_update_completions`` parses manual pages installed on the system, and attempts to create completion files in the ``fish`` configuration directory. diff --git a/sphinx_doc_src/cmds/fish_vi_mode.rst b/sphinx_doc_src/cmds/fish_vi_mode.rst index 9a8e7ff73..590538b3b 100644 --- a/sphinx_doc_src/cmds/fish_vi_mode.rst +++ b/sphinx_doc_src/cmds/fish_vi_mode.rst @@ -1,5 +1,5 @@ fish_vi_mode - Enable vi mode -========================================== +============================= Synopsis -------- @@ -8,7 +8,7 @@ fish_vi_mode Description ------------- +----------- This function is deprecated. Please call ``fish_vi_key_bindings directly`` diff --git a/sphinx_doc_src/cmds/for.rst b/sphinx_doc_src/cmds/for.rst index e7881b114..cfb02bf01 100644 --- a/sphinx_doc_src/cmds/for.rst +++ b/sphinx_doc_src/cmds/for.rst @@ -1,5 +1,5 @@ for - perform a set of commands multiple times. -========================================== +=============================================== Synopsis -------- @@ -8,12 +8,12 @@ for VARNAME in [VALUES...]; COMMANDS...; end 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. Example ------------- +------- @@ -28,7 +28,7 @@ Example 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: diff --git a/sphinx_doc_src/cmds/funced.rst b/sphinx_doc_src/cmds/funced.rst index b554dcaad..5c9bfe5ad 100644 --- a/sphinx_doc_src/cmds/funced.rst +++ b/sphinx_doc_src/cmds/funced.rst @@ -1,5 +1,5 @@ funced - edit a function interactively -========================================== +====================================== Synopsis -------- @@ -8,7 +8,7 @@ funced [OPTIONS] NAME Description ------------- +----------- ``funced`` provides an interface to edit the definition of the function ``NAME``. diff --git a/sphinx_doc_src/cmds/funcsave.rst b/sphinx_doc_src/cmds/funcsave.rst index 53e46d31b..fad1550b6 100644 --- a/sphinx_doc_src/cmds/funcsave.rst +++ b/sphinx_doc_src/cmds/funcsave.rst @@ -1,5 +1,5 @@ funcsave - save the definition of a function to the user's autoload directory -========================================== +============================================================================= Synopsis -------- @@ -8,7 +8,7 @@ funcsave FUNCTION_NAME 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. diff --git a/sphinx_doc_src/cmds/function.rst b/sphinx_doc_src/cmds/function.rst index 40e158941..bf6623d93 100644 --- a/sphinx_doc_src/cmds/function.rst +++ b/sphinx_doc_src/cmds/function.rst @@ -1,5 +1,5 @@ function - create a function -========================================== +============================ Synopsis -------- @@ -8,7 +8,7 @@ function NAME [OPTIONS]; BODY; end Description ------------- +----------- ``function`` creates a new function ``NAME`` with the body ``BODY``. @@ -58,7 +58,7 @@ By using one of the event handler switches, a function can be made to run automa - ``fish_exit`` is emitted right before fish exits. Example ------------- +------- @@ -110,6 +110,6 @@ This will beep when the most recent job completes. 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. diff --git a/sphinx_doc_src/cmds/functions.rst b/sphinx_doc_src/cmds/functions.rst index e4675fece..abb1d4398 100644 --- a/sphinx_doc_src/cmds/functions.rst +++ b/sphinx_doc_src/cmds/functions.rst @@ -1,5 +1,5 @@ functions - print or erase functions -========================================== +==================================== Synopsis -------- @@ -12,7 +12,7 @@ functions [ -e | -q ] FUNCTIONS... Description ------------- +----------- ``functions`` prints or erases functions. @@ -60,7 +60,7 @@ The exit status of ``functions`` is the number of functions specified in the arg Examples ------------- +-------- :: diff --git a/sphinx_doc_src/cmds/help.rst b/sphinx_doc_src/cmds/help.rst index 4ec33f9fd..314f3c0fc 100644 --- a/sphinx_doc_src/cmds/help.rst +++ b/sphinx_doc_src/cmds/help.rst @@ -1,5 +1,5 @@ help - display fish documentation -========================================== +================================= Synopsis -------- @@ -8,7 +8,7 @@ help [SECTION] Description ------------- +----------- ``help`` displays the fish help documentation. @@ -22,6 +22,6 @@ Note that most builtin commands display their help in the terminal when given th Example ------------- +------- ``help fg`` shows the documentation for the ``fg`` builtin. diff --git a/sphinx_doc_src/cmds/history.rst b/sphinx_doc_src/cmds/history.rst index 9b36e6f19..3056f262e 100644 --- a/sphinx_doc_src/cmds/history.rst +++ b/sphinx_doc_src/cmds/history.rst @@ -1,5 +1,5 @@ history - Show and manipulate command history -========================================== +============================================= Synopsis -------- @@ -13,7 +13,7 @@ history ( -h | --help ) Description ------------- +----------- ``history`` is used to search, delete, and otherwise manipulate the history of interactive commands. @@ -52,7 +52,7 @@ These flags can appear before or immediately after one of the sub-commands liste - ``-h`` or ``--help`` display help for this command. Example ------------- +------- @@ -70,7 +70,7 @@ Example 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``). @@ -81,7 +81,7 @@ You can change ``fish_history`` at any time (by using ``set -x fish_history "ses 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. Notes ------------- +----- If you specify both ``--prefix`` and ``--contains`` the last flag seen is used. diff --git a/sphinx_doc_src/cmds/if.rst b/sphinx_doc_src/cmds/if.rst index 3ba43ae9d..ba90693ba 100644 --- a/sphinx_doc_src/cmds/if.rst +++ b/sphinx_doc_src/cmds/if.rst @@ -1,5 +1,5 @@ if - conditionally execute a command -========================================== +==================================== Synopsis -------- @@ -11,7 +11,7 @@ end 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. @@ -20,7 +20,7 @@ You can use ``and`` or ``or`` in the condit The exit status of the last foreground command to exit can always be accessed using the $status variable. 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``. diff --git a/sphinx_doc_src/cmds/isatty.rst b/sphinx_doc_src/cmds/isatty.rst index fc231e314..744003049 100644 --- a/sphinx_doc_src/cmds/isatty.rst +++ b/sphinx_doc_src/cmds/isatty.rst @@ -1,5 +1,5 @@ isatty - test if a file descriptor is a tty. -========================================== +============================================ Synopsis -------- @@ -8,7 +8,7 @@ isatty [FILE DESCRIPTOR] Description ------------- +----------- ``isatty`` tests if a file descriptor is a tty. @@ -18,7 +18,7 @@ If the specified file descriptor is a tty, the exit status of the command is zer Examples ------------- +-------- From an interactive shell, the commands below exit with a return value of zero: diff --git a/sphinx_doc_src/cmds/jobs.rst b/sphinx_doc_src/cmds/jobs.rst index 3ba255e8c..3874f2f8d 100644 --- a/sphinx_doc_src/cmds/jobs.rst +++ b/sphinx_doc_src/cmds/jobs.rst @@ -1,5 +1,5 @@ jobs - print currently running jobs -========================================== +=================================== Synopsis -------- @@ -8,7 +8,7 @@ jobs [OPTIONS] [PID] Description ------------- +----------- ``jobs`` prints a list of the currently running jobs and their status. @@ -29,10 +29,10 @@ 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. no output. ------------- +---------- Example ------------- +------- ``jobs`` outputs a summary of the current jobs. diff --git a/sphinx_doc_src/cmds/math.rst b/sphinx_doc_src/cmds/math.rst index 170d86357..cb75f327b 100644 --- a/sphinx_doc_src/cmds/math.rst +++ b/sphinx_doc_src/cmds/math.rst @@ -1,5 +1,5 @@ math - Perform mathematics calculations -========================================== +======================================= Synopsis -------- @@ -8,7 +8,7 @@ math [-sN | --scale=N] [--] EXPRESSION 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()``. @@ -23,19 +23,19 @@ 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. Return Values ------------- +------------- If the expression is successfully evaluated and doesn't over/underflow or return NaN the return ``status`` is zero (success) else one. 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. Operators ------------- +--------- ``math`` knows the following operators: @@ -52,7 +52,7 @@ Operators They are all used in an infix manner - ``5 + 2``, not ``+ 5 2``. Constants ------------- +--------- ``math`` knows the following constants: @@ -62,7 +62,7 @@ Constants Use them without a leading ``$`` - ``pi - 3`` should be about 0. Functions ------------- +--------- ``math`` supports the following functions: @@ -92,7 +92,7 @@ Functions All of the trigonometric functions use radians. Examples ------------- +-------- ``math 1+1`` outputs 2. @@ -107,7 +107,7 @@ Examples ``math "sin(pi)"`` outputs ``0``. 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. diff --git a/sphinx_doc_src/cmds/nextd.rst b/sphinx_doc_src/cmds/nextd.rst index d954b7142..df8e10a05 100644 --- a/sphinx_doc_src/cmds/nextd.rst +++ b/sphinx_doc_src/cmds/nextd.rst @@ -1,5 +1,5 @@ nextd - move forward through directory history -========================================== +============================================== Synopsis -------- @@ -8,7 +8,7 @@ nextd [ -l | --list ] [POS] 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. @@ -19,7 +19,7 @@ Note that the ``cd`` command limits directory history to the 25 most recently vi You may be interested in the ``cdh`` command which provides a more intuitive way to navigate to recently visited directories. Example ------------- +------- diff --git a/sphinx_doc_src/cmds/not.rst b/sphinx_doc_src/cmds/not.rst index 50438fc39..524f69605 100644 --- a/sphinx_doc_src/cmds/not.rst +++ b/sphinx_doc_src/cmds/not.rst @@ -1,5 +1,5 @@ not - negate the exit status of a job -========================================== +===================================== Synopsis -------- @@ -8,13 +8,13 @@ not COMMAND [OPTIONS...] Description ------------- +----------- ``not`` negates the exit status of another command. If the exit status is zero, ``not`` returns 1. Otherwise, ``not`` returns 0. Example ------------- +------- The following code reports an error and exits if no file named spoon can be found. diff --git a/sphinx_doc_src/cmds/open.rst b/sphinx_doc_src/cmds/open.rst index 4b86a0641..b4e5ac63d 100644 --- a/sphinx_doc_src/cmds/open.rst +++ b/sphinx_doc_src/cmds/open.rst @@ -1,5 +1,5 @@ open - open file in its default application -========================================== +=========================================== Synopsis -------- @@ -8,7 +8,7 @@ open FILES... 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. @@ -16,6 +16,6 @@ Note that this function will not be used if a command by this name exists (which Example ------------- +------- ``open *.txt`` opens all the text files in the current directory using your system's default text editor. diff --git a/sphinx_doc_src/cmds/or.rst b/sphinx_doc_src/cmds/or.rst index 7f04d8af0..258d22158 100644 --- a/sphinx_doc_src/cmds/or.rst +++ b/sphinx_doc_src/cmds/or.rst @@ -1,5 +1,5 @@ or - conditionally execute a command -========================================== +==================================== Synopsis -------- @@ -8,7 +8,7 @@ COMMAND1; or COMMAND2 Description ------------- +----------- ``or`` is used to execute a command if the previous command was not successful (returned a status of something other than 0). @@ -18,7 +18,7 @@ for ``if`` and ``while`` 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 $status variable. 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. diff --git a/sphinx_doc_src/cmds/popd.rst b/sphinx_doc_src/cmds/popd.rst index 126d331d2..945912777 100644 --- a/sphinx_doc_src/cmds/popd.rst +++ b/sphinx_doc_src/cmds/popd.rst @@ -1,5 +1,5 @@ popd - move through directory stack -========================================== +=================================== Synopsis -------- @@ -8,14 +8,14 @@ popd Description ------------- +----------- ``popd`` removes the top directory from the directory stack and changes the working directory to the new top directory. Use ``pushd`` to add directories to the stack. You may be interested in the ``cdh`` command which provides a more intuitive way to navigate to recently visited directories. Example ------------- +------- diff --git a/sphinx_doc_src/cmds/prevd.rst b/sphinx_doc_src/cmds/prevd.rst index 9087249f7..10a749803 100644 --- a/sphinx_doc_src/cmds/prevd.rst +++ b/sphinx_doc_src/cmds/prevd.rst @@ -1,5 +1,5 @@ prevd - move backward through directory history -========================================== +=============================================== Synopsis -------- @@ -8,7 +8,7 @@ prevd [ -l | --list ] [POS] 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. @@ -19,7 +19,7 @@ Note that the ``cd`` command limits directory history to the 25 most recently vi You may be interested in the ``cdh`` command which provides a more intuitive way to navigate to recently visited directories. Example ------------- +------- diff --git a/sphinx_doc_src/cmds/printf.rst b/sphinx_doc_src/cmds/printf.rst index d951e16ab..e883bdd72 100644 --- a/sphinx_doc_src/cmds/printf.rst +++ b/sphinx_doc_src/cmds/printf.rst @@ -1,5 +1,5 @@ printf - display text according to a format string -========================================== +================================================== Synopsis -------- @@ -8,7 +8,7 @@ printf format [argument...] 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)``. @@ -61,7 +61,7 @@ The ``format`` argument is re-used as many times as necessary to convert all of 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``. Example ------------- +------- diff --git a/sphinx_doc_src/cmds/prompt_pwd.rst b/sphinx_doc_src/cmds/prompt_pwd.rst index 3d914d0cc..3d9ac5b37 100644 --- a/sphinx_doc_src/cmds/prompt_pwd.rst +++ b/sphinx_doc_src/cmds/prompt_pwd.rst @@ -8,14 +8,14 @@ prompt_pwd 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. Examples ------------- +-------- diff --git a/sphinx_doc_src/cmds/psub.rst b/sphinx_doc_src/cmds/psub.rst index 6229ea2f9..f61a183f2 100644 --- a/sphinx_doc_src/cmds/psub.rst +++ b/sphinx_doc_src/cmds/psub.rst @@ -1,5 +1,5 @@ psub - perform process substitution -========================================== +=================================== Synopsis -------- @@ -8,7 +8,7 @@ COMMAND1 ( COMMAND2 | psub [-F | --fifo] [-f | --file] [-s SUFFIX]) 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. @@ -21,7 +21,7 @@ The following options are available: - ``-s`` or ``--suffix`` will append SUFFIX to the filename. Example ------------- +------- diff --git a/sphinx_doc_src/cmds/pushd.rst b/sphinx_doc_src/cmds/pushd.rst index 68cd3b5ae..a524ac93f 100644 --- a/sphinx_doc_src/cmds/pushd.rst +++ b/sphinx_doc_src/cmds/pushd.rst @@ -1,5 +1,5 @@ pushd - push directory to directory stack -========================================== +========================================= Synopsis -------- @@ -8,7 +8,7 @@ pushd [DIRECTORY] Description ------------- +----------- The ``pushd`` function adds ``DIRECTORY`` to the top of the directory stack and makes it the current working directory. ``popd`` will pop it off and return to the original directory. @@ -23,7 +23,7 @@ See also ``dirs`` and ``dirs -c``. You may be interested in the ``cdh`` command which provides a more intuitive way to navigate to recently visited directories. Example ------------- +------- diff --git a/sphinx_doc_src/cmds/pwd.rst b/sphinx_doc_src/cmds/pwd.rst index 9845e1533..0521514a5 100644 --- a/sphinx_doc_src/cmds/pwd.rst +++ b/sphinx_doc_src/cmds/pwd.rst @@ -8,7 +8,7 @@ pwd Description ------------- +----------- ``pwd`` outputs (prints) the current working directory. diff --git a/sphinx_doc_src/cmds/random.rst b/sphinx_doc_src/cmds/random.rst index 43bbc1809..9b5a19ab2 100644 --- a/sphinx_doc_src/cmds/random.rst +++ b/sphinx_doc_src/cmds/random.rst @@ -1,5 +1,5 @@ random - generate random number -========================================== +=============================== Synopsis -------- @@ -12,7 +12,7 @@ random choice [ITEMS...] Description ------------- +----------- ``RANDOM`` generates a pseudo-random integer from a uniform distribution. The range (inclusive) is dependent on the arguments passed. @@ -31,7 +31,7 @@ You should not consider ``RANDOM`` cryptographically secure, or even statistically accurate. Example ------------- +------- The following code will count down from a random even number between 10 and 20 to 1: diff --git a/sphinx_doc_src/cmds/read.rst b/sphinx_doc_src/cmds/read.rst index 974ad6ab8..a420b5382 100644 --- a/sphinx_doc_src/cmds/read.rst +++ b/sphinx_doc_src/cmds/read.rst @@ -1,5 +1,5 @@ read - read line of input into variables -========================================== +======================================== Synopsis -------- @@ -8,7 +8,7 @@ read [OPTIONS] [VARIABLE ...] 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. @@ -73,12 +73,12 @@ is set to empty and the exit status is set to 122. This limit can be altered wit ``fish_read_limit`` variable. If set to 0 (zero), the limit is removed. 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. Example ------------- +------- The following code stores the value 'hello' in the shell variable ``$foo``. diff --git a/sphinx_doc_src/cmds/realpath.rst b/sphinx_doc_src/cmds/realpath.rst index 4b6700c66..859c6458b 100644 --- a/sphinx_doc_src/cmds/realpath.rst +++ b/sphinx_doc_src/cmds/realpath.rst @@ -1,5 +1,5 @@ realpath - Convert a path to an absolute path without symlinks -========================================== +============================================================== Synopsis -------- @@ -8,7 +8,7 @@ realpath path 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``. diff --git a/sphinx_doc_src/cmds/return.rst b/sphinx_doc_src/cmds/return.rst index edf51aa9a..6de7c1dd7 100644 --- a/sphinx_doc_src/cmds/return.rst +++ b/sphinx_doc_src/cmds/return.rst @@ -1,5 +1,5 @@ return - stop the current inner function -========================================== +======================================== Synopsis -------- @@ -8,7 +8,7 @@ function NAME; [COMMANDS...;] return [STATUS]; [COMMANDS...;] end Description ------------- +----------- ``return`` halts a currently running function. The exit status is set to ``STATUS`` if it is given. @@ -16,7 +16,7 @@ It is usually added inside of a conditional block such as an ifshell variables. @@ -84,7 +84,7 @@ In assignment mode, ``set`` does not modify the exit status. This allows simulta Examples ------------- +-------- :: @@ -115,7 +115,7 @@ Examples 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. diff --git a/sphinx_doc_src/cmds/set_color.rst b/sphinx_doc_src/cmds/set_color.rst index 77aa432a0..e616fb58e 100644 --- a/sphinx_doc_src/cmds/set_color.rst +++ b/sphinx_doc_src/cmds/set_color.rst @@ -1,5 +1,5 @@ set_color - set the terminal color -========================================== +================================== Synopsis -------- @@ -8,7 +8,7 @@ set_color [OPTIONS] VALUE 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. @@ -32,7 +32,7 @@ The following options are available: Using the *normal* keyword will reset foreground, background, and all formatting back to default. 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. @@ -40,7 +40,7 @@ Notes 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. Examples ------------- +-------- @@ -53,7 +53,7 @@ Examples 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. diff --git a/sphinx_doc_src/cmds/source.rst b/sphinx_doc_src/cmds/source.rst index 8c1d2f710..33b5dc0c3 100644 --- a/sphinx_doc_src/cmds/source.rst +++ b/sphinx_doc_src/cmds/source.rst @@ -1,5 +1,5 @@ source - evaluate contents of file. -========================================== +=================================== Synopsis -------- @@ -9,7 +9,7 @@ somecommand | source 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. @@ -21,7 +21,7 @@ The return status of ``source`` is the return status of the last job to execute. Example ------------- +------- diff --git a/sphinx_doc_src/cmds/status.rst b/sphinx_doc_src/cmds/status.rst index 40503f60b..8dda9dde6 100644 --- a/sphinx_doc_src/cmds/status.rst +++ b/sphinx_doc_src/cmds/status.rst @@ -1,5 +1,5 @@ status - query fish runtime information -========================================== +======================================= Synopsis -------- @@ -24,7 +24,7 @@ status test-feature FEATURE Description ------------- +----------- With no arguments, ``status`` displays a summary of the current login and job control status of the shell. @@ -64,7 +64,7 @@ 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. 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). diff --git a/sphinx_doc_src/cmds/string.rst b/sphinx_doc_src/cmds/string.rst index bbfca183e..8b97ec3c0 100644 --- a/sphinx_doc_src/cmds/string.rst +++ b/sphinx_doc_src/cmds/string.rst @@ -1,5 +1,5 @@ string - manipulate strings -========================================== +=========================== Synopsis -------- @@ -29,7 +29,7 @@ string upper [(-q | --quiet)] [STRING...] Description ------------- +----------- ``string`` performs operations on strings. @@ -42,7 +42,7 @@ Most subcommands accept a ``-q`` or ``--quiet`` switch, which suppresses the usu The following subcommands are available. "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. @@ -55,7 +55,7 @@ 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. "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. @@ -64,17 +64,17 @@ 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. "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. "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. "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. @@ -91,12 +91,12 @@ If ``--invert`` or ``-v`` is used the selected lines will be only those which do Exit status: 0 if at least one match was found, or 1 otherwise. "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. "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. @@ -107,7 +107,7 @@ If you specify the ``-f`` or ``--filter`` flag then each input string is printed Exit status: 0 if at least one replacement was performed, or 1 otherwise. "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. @@ -120,22 +120,22 @@ 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. "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. "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. "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. 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. @@ -186,7 +186,7 @@ And some other things: - ``|`` is "alternation", i.e. the "or". Examples ------------- +-------- @@ -270,7 +270,7 @@ Examples Match Glob Examples ------------- +------------------- @@ -306,7 +306,7 @@ Match Glob Examples Match Regex Examples ------------- +-------------------- @@ -362,7 +362,7 @@ Match Regex Examples Replace Literal Examples ------------- +------------------------ @@ -381,7 +381,7 @@ Replace Literal Examples Replace Regex Examples ------------- +---------------------- @@ -399,7 +399,7 @@ Replace Regex Examples Repeat Examples ------------- +--------------- diff --git a/sphinx_doc_src/cmds/suspend.rst b/sphinx_doc_src/cmds/suspend.rst index 21559783a..7e1b92129 100644 --- a/sphinx_doc_src/cmds/suspend.rst +++ b/sphinx_doc_src/cmds/suspend.rst @@ -1,5 +1,5 @@ suspend - suspend the current shell -========================================== +=================================== Synopsis -------- @@ -8,7 +8,7 @@ suspend [--force] Description ------------- +----------- ``suspend`` suspends execution of the current shell by sending it a SIGTSTP signal, returning to the controlling process. It can be diff --git a/sphinx_doc_src/cmds/switch.rst b/sphinx_doc_src/cmds/switch.rst index 92779c03c..d0a106b2f 100644 --- a/sphinx_doc_src/cmds/switch.rst +++ b/sphinx_doc_src/cmds/switch.rst @@ -1,5 +1,5 @@ switch - conditionally execute a block of commands -========================================== +================================================== Synopsis -------- @@ -8,7 +8,7 @@ switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end 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. @@ -20,7 +20,7 @@ Note that command substitutions in a case statement will be evaluated even if it Example ------------- +------- If the variable \$animal contains the name of an animal, the following code would attempt to classify it: diff --git a/sphinx_doc_src/cmds/test.rst b/sphinx_doc_src/cmds/test.rst index b807fb8c5..834415e32 100644 --- a/sphinx_doc_src/cmds/test.rst +++ b/sphinx_doc_src/cmds/test.rst @@ -1,5 +1,5 @@ test - perform tests on files and text -========================================== +====================================== Synopsis -------- @@ -9,7 +9,7 @@ test [EXPRESSION] 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. @@ -20,7 +20,7 @@ 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. Operators for files and directories ------------- +----------------------------------- - ``-b FILE`` returns true if ``FILE`` is a block device. @@ -59,7 +59,7 @@ Operators for files and directories - ``-x FILE`` returns true if ``FILE`` is marked as executable. Operators for text strings ------------- +-------------------------- - ``STRING1 = STRING2`` returns true if the strings ``STRING1`` and ``STRING2`` are identical. @@ -70,7 +70,7 @@ Operators for text strings - ``-z STRING`` returns true if the length of ``STRING`` is zero. Operators to compare and examine numbers ------------- +---------------------------------------- - ``NUM1 -eq NUM2`` returns true if ``NUM1`` and ``NUM2`` are numerically equal. @@ -87,7 +87,7 @@ Operators to compare and examine numbers Both integers and floating point numbers are supported. Operators to combine expressions ------------- +-------------------------------- - ``COND1 -a COND2`` returns true if both ``COND1`` and ``COND2`` are true. @@ -105,7 +105,7 @@ Expressions can be grouped using parentheses. Examples ------------- +-------- If the ``/tmp`` directory exists, copy the ``/etc/motd`` file to it: @@ -185,7 +185,7 @@ which is logically equivalent to the following: Standards ------------- +--------- ``test`` implements a subset of the IEEE Std 1003.1-2008 (POSIX.1) standard. The following exceptions apply: diff --git a/sphinx_doc_src/cmds/trap.rst b/sphinx_doc_src/cmds/trap.rst index 76279ba8f..318fbd1b4 100644 --- a/sphinx_doc_src/cmds/trap.rst +++ b/sphinx_doc_src/cmds/trap.rst @@ -1,5 +1,5 @@ trap - perform an action when the shell receives a signal -========================================== +========================================================= Synopsis -------- @@ -8,7 +8,7 @@ trap [OPTIONS] [[ARG] REASON ... ] 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 event handler. @@ -33,7 +33,7 @@ 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. Example ------------- +------- diff --git a/sphinx_doc_src/cmds/true.rst b/sphinx_doc_src/cmds/true.rst index 98ce568a4..c8607d6ff 100644 --- a/sphinx_doc_src/cmds/true.rst +++ b/sphinx_doc_src/cmds/true.rst @@ -1,5 +1,5 @@ true - return a successful result -========================================== +================================= Synopsis -------- @@ -8,6 +8,6 @@ true Description ------------- +----------- ``true`` sets the exit status to 0. diff --git a/sphinx_doc_src/cmds/type.rst b/sphinx_doc_src/cmds/type.rst index c1fdfeb07..a793ee3a9 100644 --- a/sphinx_doc_src/cmds/type.rst +++ b/sphinx_doc_src/cmds/type.rst @@ -1,5 +1,5 @@ type - indicate how a command would be interpreted -========================================== +================================================== Synopsis -------- @@ -8,7 +8,7 @@ type [OPTIONS] NAME [NAME ...] Description ------------- +----------- With no options, ``type`` indicates how each ``NAME`` would be interpreted if used as a command name. @@ -30,7 +30,7 @@ The ``-q``, ``-p``, ``-t`` and ``-P`` flags (and their long flag aliases) are mu Example ------------- +------- diff --git a/sphinx_doc_src/cmds/ulimit.rst b/sphinx_doc_src/cmds/ulimit.rst index 032333aa0..846e06993 100644 --- a/sphinx_doc_src/cmds/ulimit.rst +++ b/sphinx_doc_src/cmds/ulimit.rst @@ -1,5 +1,5 @@ ulimit - set or get resource usage limits -========================================== +========================================= Synopsis -------- @@ -8,7 +8,7 @@ ulimit [OPTIONS] [LIMIT] 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. @@ -62,7 +62,7 @@ The ``fish`` implementation of ``ulimit`` should behave identically to the imple Example ------------- +------- ``ulimit -Hs 64`` sets the hard stack size limit to 64 kB. diff --git a/sphinx_doc_src/cmds/umask.rst b/sphinx_doc_src/cmds/umask.rst index f67e710dc..8775c8a5c 100644 --- a/sphinx_doc_src/cmds/umask.rst +++ b/sphinx_doc_src/cmds/umask.rst @@ -1,5 +1,5 @@ umask - set or get the file creation mode mask -========================================== +============================================== Synopsis -------- @@ -8,7 +8,7 @@ umask [OPTIONS] [MASK] Description ------------- +----------- ``umask`` displays and manipulates the "umask", or file creation mode mask, which is used to restrict the default access to files. @@ -40,6 +40,6 @@ Note that symbolic masks currently do not work as intended. 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. diff --git a/sphinx_doc_src/cmds/vared.rst b/sphinx_doc_src/cmds/vared.rst index 91ab9028b..2fb29bf98 100644 --- a/sphinx_doc_src/cmds/vared.rst +++ b/sphinx_doc_src/cmds/vared.rst @@ -1,5 +1,5 @@ vared - interactively edit the value of an environment variable -========================================== +=============================================================== Synopsis -------- @@ -8,12 +8,12 @@ vared VARIABLE_NAME 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. Example ------------- +------- ``vared PATH[3]`` edits the third element of the PATH array diff --git a/sphinx_doc_src/cmds/wait.rst b/sphinx_doc_src/cmds/wait.rst index 7afa01edf..763d42191 100644 --- a/sphinx_doc_src/cmds/wait.rst +++ b/sphinx_doc_src/cmds/wait.rst @@ -1,5 +1,5 @@ wait - wait for jobs to complete -========================================== +================================ Synopsis -------- @@ -8,7 +8,7 @@ wait [-n | --any] [PID | PROCESS_NAME] ... Description ------------- +----------- ``wait`` waits for child jobs to complete. @@ -18,7 +18,7 @@ Description - 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. Example ------------- +------- diff --git a/sphinx_doc_src/cmds/while.rst b/sphinx_doc_src/cmds/while.rst index 6bc372767..8827dd75f 100644 --- a/sphinx_doc_src/cmds/while.rst +++ b/sphinx_doc_src/cmds/while.rst @@ -1,5 +1,5 @@ while - perform a command multiple times -========================================== +======================================== Synopsis -------- @@ -8,7 +8,7 @@ while CONDITION; COMMANDS...; end Description ------------- +----------- ``while`` repeatedly executes ``CONDITION``, and if the exit status is 0, then executes ``COMMANDS``. @@ -20,7 +20,7 @@ The exit status of the loop is 0 otherwise. You can use ``and`` or ``or`` for complex conditions. Even more complex control can be achieved with ``while true`` containing a break. Example ------------- +-------