diff --git a/doc_src/cmds/argparse.rst b/doc_src/cmds/argparse.rst index 6d9314208..f7547bdcf 100644 --- a/doc_src/cmds/argparse.rst +++ b/doc_src/cmds/argparse.rst @@ -14,9 +14,9 @@ Synopsis Description ----------- -This command makes it easy for fish scripts and functions to handle arguments like how fish builtin commands handle their arguments. You pass arguments that define the known options, followed by a literal ``--``, then the arguments to be parsed (which might also include a literal ``--``). ``argparse`` then sets variables to indicate the passed options with their values, and sets $argv (and always $argv) to the remaining arguments. More on this in the `usage <#usage>`__ section below. +This command makes it easy for fish scripts and functions to handle arguments like how fish builtin commands handle their arguments. You pass arguments that define the known options, followed by a literal ``--``, then the arguments to be parsed (which might also include a literal ``--``). ``argparse`` then sets variables to indicate the passed options with their values, and sets $argv (and always $argv) to the remaining arguments. More on this in the :ref:`usage ` section below. -Each option specification (``OPTION_SPEC``) is written in the `domain specific language <#option-specifications>`__ described below. All OPTION_SPECs must appear after any argparse flags and before the ``--`` that separates them from the arguments to be parsed. +Each option specification (``OPTION_SPEC``) is written in the :ref:`domain specific language ` described below. All OPTION_SPECs must appear after any argparse flags and before the ``--`` that separates them from the arguments to be parsed. Each option that is seen in the ARG list will result in variables named ``_flag_X``, where ``X`` is the short flag letter and the long flag name (if they are defined). For example a ``--help`` option could cause argparse to define one variable called ``_flag_h`` and another called ``_flag_help``. @@ -41,6 +41,8 @@ The following ``argparse`` options are available. They must appear before all OP - ``-h`` or ``--help`` displays help about using this command. +.. _cmd-argparse-usage: + Usage ----- @@ -69,6 +71,8 @@ But this is not:: The first ``--`` seen is what allows the ``argparse`` command to reliably separate the option specifications and options to ``argparse`` itself (like ``--ignore-unknown``) from the command arguments, so it is required. +.. _cmd-argparse-option-specification: + Option Specifications --------------------- diff --git a/doc_src/completions.rst b/doc_src/completions.rst index eb39e99ae..9205f6150 100644 --- a/doc_src/completions.rst +++ b/doc_src/completions.rst @@ -119,7 +119,7 @@ These paths are controlled by parameters set at build, install, or run time, and This wide search may be confusing. If you are unsure, your completions probably belong in ``~/.config/fish/completions``. -If you have written new completions for a common Unix command, please consider sharing your work by submitting it via the instructions in `Further help and development <#more-help>`_. +If you have written new completions for a common Unix command, please consider sharing your work by submitting it via the instructions in :ref:`Further help and development ` If you are developing another program and would like to ship completions with your program, install them to the "vendor" completions directory. As this path may vary from system to system, the ``pkgconfig`` framework should be used to discover this path with the output of ``pkg-config --variable completionsdir fish``. diff --git a/doc_src/index.rst b/doc_src/index.rst index 47e0110d5..13bb1a865 100644 --- a/doc_src/index.rst +++ b/doc_src/index.rst @@ -152,7 +152,7 @@ Here we define some of the terms used on this page and throughout the rest of th Quotes ------ -Sometimes features like `parameter expansion <#expand>`_ and `character escapes <#escapes>`_ get in the way. When that happens, you can use quotes, either single (``'``) or double (``"``). Between single quotes, fish performs no expansions. Between double quotes, fish only performs :ref:`variable expansion `. No other kind of expansion (including :ref:`brace expansion ` or parameter expansion) is performed, and escape sequences (for example, ``\n``) are ignored. Within quotes, whitespace is not used to separate arguments, allowing quoted arguments to contain spaces. +Sometimes features like :ref:`parameter expansion ` and :ref:`character escapes ` get in the way. When that happens, you can use quotes, either single (``'``) or double (``"``). Between single quotes, fish performs no expansions. Between double quotes, fish only performs :ref:`variable expansion `. No other kind of expansion (including :ref:`brace expansion ` or parameter expansion) is performed, and escape sequences (for example, ``\n``) are ignored. Within quotes, whitespace is not used to separate arguments, allowing quoted arguments to contain spaces. The only meaningful escape sequences in single quotes are ``\'``, which escapes a single quote and ``\\``, which escapes the backslash symbol. The only meaningful escapes in double quotes are ``\"``, which escapes a double quote, ``\$``, which escapes a dollar character, ``\`` followed by a newline, which deletes the backslash and the newline, and ``\\``, which escapes the backslash symbol. @@ -399,7 +399,7 @@ By default ``$fish_function_path`` contains the following: If you are unsure, your functions probably belong in ``~/.config/fish/functions``. -Autoloading also won't work for `event handlers <#event>`_, since fish cannot know that a function is supposed to be executed when an event occurs when it hasn't yet loaded the function. See the `event handlers <#event>`_ section for more information. +Autoloading also won't work for :ref:`event handlers `, since fish cannot know that a function is supposed to be executed when an event occurs when it hasn't yet loaded the function. See the :ref:`event handlers ` section for more information. If you are developing another program and want to install fish functions for it, install them to the "vendor" functions directory. As this path varies from system to system, you can use ``pkgconfig`` to discover it with the output of ``pkg-config --variable functionsdir fish``. Your installation system should support a custom path to override the pkgconfig path, as other distributors may need to alter it easily. @@ -636,7 +636,7 @@ When you write a command in parenthesis like ``outercommand (innercommand)``, th If the output is piped to :ref:`string split or string split0 ` as the last step, those splits are used as they appear instead of splitting lines. -The exit status of the last run command substitution is available in the `status <#variables-status>`_ variable if the substitution happens in the context of a :ref:`set ` command (so ``if set -l (something)`` checks if ``something`` returned true). +The exit status of the last run command substitution is available in the :ref:`status ` variable if the substitution happens in the context of a :ref:`set ` command (so ``if set -l (something)`` checks if ``something`` returned true). Only part of the output can be used, see :ref:`index range expansion ` for details. @@ -1032,7 +1032,7 @@ Universal variables are variables that are shared between all the user's fish se To see universal variables in action, start two fish sessions side by side, and issue the following command in one of them ``set fish_color_cwd blue``. Since ``fish_color_cwd`` is a universal variable, the color of the current working directory listing in the prompt will instantly change to blue on both terminals. -`Universal variables <#variables-universal>`_ are stored in the file ``.config/fish/fish_variables``. Do not edit this file directly, as your edits may be overwritten. Edit the variables through fish scripts or by using fish interactively instead. +:ref:`Universal variables ` are stored in the file ``.config/fish/fish_variables``. Do not edit this file directly, as your edits may be overwritten. Edit the variables through fish scripts or by using fish interactively instead. Do not append to universal variables in :ref:`config.fish `, because these variables will then get longer with each new shell instance. Instead, simply set them once at the command line. @@ -1276,9 +1276,9 @@ You can change the settings of fish by changing the values of certain variables. - ``CDPATH``, a list of directories in which the :ref:`cd ` builtin looks for a new directory. -- The locale variables ``LANG``, ``LC_ALL``, ``LC_COLLATE``, ``LC_CTYPE``, ``LC_MESSAGES``, ``LC_MONETARY``, ``LC_NUMERIC`` and ``LC_TIME`` set the language option for the shell and subprograms. See the section `Locale variables <#variables-locale>`_ for more information. +- The locale variables ``LANG``, ``LC_ALL``, ``LC_COLLATE``, ``LC_CTYPE``, ``LC_MESSAGES``, ``LC_MONETARY``, ``LC_NUMERIC`` and ``LC_TIME`` set the language option for the shell and subprograms. See the section :ref:`Locale variables ` for more information. -- A number of variable starting with the prefixes ``fish_color`` and ``fish_pager_color``. See `Variables for changing highlighting colors <#variables-color>`__ for more information. +- A number of variable starting with the prefixes ``fish_color`` and ``fish_pager_color``. See :ref:`Variables for changing highlighting colors ` for more information. - ``fish_ambiguous_width`` controls the computed width of ambiguous-width characters. This should be set to 1 if your terminal renders these characters as single-width (typical), or 2 if double-width. @@ -1326,7 +1326,7 @@ Fish also provides additional information through the values of certain environm - ``hostname``, the machine's hostname. -- ``IFS``, the internal field separator that is used for word splitting with the :ref:`read ` builtin. Setting this to the empty string will also disable line splitting in `command substitution <#expand-command-substitution>`_. This variable can be changed. +- ``IFS``, the internal field separator that is used for word splitting with the :ref:`read ` builtin. Setting this to the empty string will also disable line splitting in :ref:`command substitution `. This variable can be changed. - ``last_pid``, the process ID (PID) of the last background process. @@ -1336,7 +1336,7 @@ Fish also provides additional information through the values of certain environm - ``SHLVL``, the level of nesting of shells. -- ``status``, the `exit status <#variables-status>`_ of the last foreground job to exit. If the job was terminated through a signal, the exit status will be 128 plus the signal number. +- ``status``, the :ref:`exit status ` of the last foreground job to exit. If the job was terminated through a signal, the exit status will be 128 plus the signal number. - ``status_generation``, the "generation" count of ``$status``. This will be incremented only when the previous command produced an explicit status. (For example, background jobs will not increment this). @@ -1512,7 +1512,7 @@ Fish prides itself on being really nice to use interactively. That's down to a f Help ---- -Fish has an extensive help system. Use the :ref:`help ` command to obtain help on a specific subject or command. For instance, writing ``help syntax`` displays the `syntax section <#syntax>`_ of this documentation. +Fish has an extensive help system. Use the :ref:`help ` command to obtain help on a specific subject or command. For instance, writing ``help syntax`` displays the :ref:`syntax section ` of this documentation. Fish also has man pages for its commands, and translates the help pages to man pages. For example, ``man set`` will show the documentation for ``set`` as a man page. @@ -1525,7 +1525,7 @@ This page can be viewed via ``help index`` (or just ``help``) or ``man fish-doc` Autosuggestions --------------- -fish suggests commands as you type, based on `command history <#history-search>`_, completions, and valid file paths. As you type commands, you will see a suggestion offered after the cursor, in a muted gray color (which can be changed with the ``fish_color_autosuggestion`` variable). +fish suggests commands as you type, based on :ref:`command history `, completions, and valid file paths. As you type commands, you will see a suggestion offered after the cursor, in a muted gray color (which can be changed with the ``fish_color_autosuggestion`` variable). To accept the autosuggestion (replacing the command line contents), press :kbd:`→` or :kbd:`Control`\ +\ :kbd:`F`. To accept the first suggested word, press :kbd:`Alt`\ +\ :kbd:`→` or :kbd:`Alt`\ +\ :kbd:`F`. If the autosuggestion is not what you want, just ignore it: it won't execute unless you accept it. @@ -1583,7 +1583,7 @@ Detected errors include: When the cursor is over a parenthesis or a quote, fish also highlights its matching quote or parenthesis. -To customize the syntax highlighting, you can set the environment variables listed in the `Variables for changing highlighting colors <#variables-color>`__ section. +To customize the syntax highlighting, you can set the environment variables listed in the :ref:`Variables for changing highlighting colors ` section. .. _abbreviations: @@ -1627,7 +1627,7 @@ To show the last command in the title:: Programmable prompt ------------------- -When fish waits for input, it will display a prompt by evaluating the :ref:`fish_prompt ` and :ref:`fish_right_prompt ` functions. The output of the former is displayed on the left and the latter's output on the right side of the terminal. The output of :ref:`fish_mode_prompt ` will be prepended on the left, though the default function only does this when in `vi-mode <#vi-mode>`__. +When fish waits for input, it will display a prompt by evaluating the :ref:`fish_prompt ` and :ref:`fish_right_prompt ` functions. The output of the former is displayed on the left and the latter's output on the right side of the terminal. The output of :ref:`fish_mode_prompt ` will be prepended on the left, though the default function only does this when in :ref:`vi-mode `. .. _greeting: @@ -1652,7 +1652,7 @@ You can query the variable ``fish_private_mode`` (``if set -q fish_private_mode Command line editor =================== -The fish editor features copy and paste, a `searchable history <#history-search>`_ and many editor functions that can be bound to special keyboard shortcuts. +The fish editor features copy and paste, a :ref:`searchable history ` and many editor functions that can be bound to special keyboard shortcuts. Similar to bash, fish has Emacs and Vi editing modes. The default editing mode is Emacs. You can switch to Vi mode with ``fish_vi_key_bindings`` and switch back with ``fish_default_key_bindings``. You can also make your own key bindings by creating a function and setting $fish_key_bindings to its name. For example:: @@ -1674,7 +1674,7 @@ Shared bindings Some bindings are shared between emacs- and vi-mode because they aren't text editing bindings or because what Vi/Vim does for a particular key doesn't make sense for a shell. -- :kbd:`Tab` `completes <#tab-completion>`_ the current token. :kbd:`Shift`\ +\ :kbd:`Tab` completes the current token and starts the pager's search mode. +- :kbd:`Tab` :ref:`completes ` the current token. :kbd:`Shift`\ +\ :kbd:`Tab` completes the current token and starts the pager's search mode. - :kbd:`←` (Left) and :kbd:`→` (Right) move the cursor left or right by one character. If the cursor is already at the end of the line, and an autosuggestion is available, :kbd:`→` accepts the autosuggestion. @@ -1684,25 +1684,25 @@ Some bindings are shared between emacs- and vi-mode because they aren't text edi - :kbd:`Shift`\ +\ :kbd:`←` and :kbd:`Shift`\ +\ :kbd:`→` move the cursor one word left or right, without stopping on punctuation. These accept one big word of the autosuggestion. -- :kbd:`↑` (Up) and :kbd:`↓` (Down) (or :kbd:`Control`\ +\ :kbd:`P` and :kbd:`Control`\ +\ :kbd:`N` for emacs aficionados) search the command history for the previous/next command containing the string that was specified on the commandline before the search was started. If the commandline was empty when the search started, all commands match. See the `history <#history-search>`_ section for more information on history searching. +- :kbd:`↑` (Up) and :kbd:`↓` (Down) (or :kbd:`Control`\ +\ :kbd:`P` and :kbd:`Control`\ +\ :kbd:`N` for emacs aficionados) search the command history for the previous/next command containing the string that was specified on the commandline before the search was started. If the commandline was empty when the search started, all commands match. See the :ref:`history ` section for more information on history searching. -- :kbd:`Alt`\ +\ :kbd:`↑` and :kbd:`Alt`\ +\ :kbd:`↓` search the command history for the previous/next token containing the token under the cursor before the search was started. If the commandline was not on a token when the search started, all tokens match. See the `history <#history-search>`_ section for more information on history searching. +- :kbd:`Alt`\ +\ :kbd:`↑` and :kbd:`Alt`\ +\ :kbd:`↓` search the command history for the previous/next token containing the token under the cursor before the search was started. If the commandline was not on a token when the search started, all tokens match. See the :ref:`history ` section for more information on history searching. - :kbd:`Control`\ +\ :kbd:`C` cancels the entire line. - :kbd:`Control`\ +\ :kbd:`D` delete one character to the right of the cursor. If the command line is empty, :kbd:`Control`\ +\ :kbd:`D` will exit fish. -- :kbd:`Control`\ +\ :kbd:`U` moves contents from the beginning of line to the cursor to the `killring <#killring>`__. +- :kbd:`Control`\ +\ :kbd:`U` moves contents from the beginning of line to the cursor to the :ref:`killring `. - :kbd:`Control`\ +\ :kbd:`L` clears and repaints the screen. - :kbd:`Control`\ +\ :kbd:`R` searches the history if there is something in the commandline. This is mainly to ease the transition from other shells, where ctrl+r initiates the history search. -- :kbd:`Control`\ +\ :kbd:`W` moves the previous path component (everything up to the previous "/", ":" or "@") to the `killring <#killring>`__. +- :kbd:`Control`\ +\ :kbd:`W` moves the previous path component (everything up to the previous "/", ":" or "@") to the :ref:`killring `. - :kbd:`Control`\ +\ :kbd:`X` copies the current buffer to the system's clipboard, :kbd:`Control`\ +\ :kbd:`V` inserts the clipboard contents. -- :kbd:`Alt`\ +\ :kbd:`D` moves the next word to the `killring <#killring>`__. +- :kbd:`Alt`\ +\ :kbd:`D` moves the next word to the :ref:`killring `. - :kbd:`Alt`\ +\ :kbd:`H` (or :kbd:`F1`) shows the manual page for the current command, if one exists. @@ -1737,7 +1737,7 @@ Emacs mode commands - :kbd:`Delete` or :kbd:`Backspace` removes one character forwards or backwards respectively. -- :kbd:`Control`\ +\ :kbd:`K` moves contents from the cursor to the end of line to the `killring <#killring>`__. +- :kbd:`Control`\ +\ :kbd:`K` moves contents from the cursor to the end of line to the :ref:`killring `. - :kbd:`Alt`\ +\ :kbd:`C` capitalizes the current word. @@ -1760,7 +1760,7 @@ You can change these key bindings using the :ref:`bind ` builtin. Vi mode commands ---------------- -Vi mode allows for the use of Vi-like commands at the prompt. Initially, `insert mode <#vi-mode-insert>`_ is active. :kbd:`Escape` enters `command mode <#vi-mode-command>`_. The commands available in command, insert and visual mode are described below. Vi mode shares `some bindings <#shared-binds>`_ with `Emacs mode <#emacs-mode>`_. +Vi mode allows for the use of Vi-like commands at the prompt. Initially, :ref:`insert mode ` is active. :kbd:`Escape` enters :ref:`command mode `. The commands available in command, insert and visual mode are described below. Vi mode shares :ref:`some bindings ` with :ref:`Emacs mode `. It is also possible to add all emacs-mode bindings to vi-mode by using something like:: @@ -1809,25 +1809,25 @@ Command mode is also known as normal mode. - :kbd:`L` moves the cursor right. -- :kbd:`I` enters `insert mode <#vi-mode-insert>`_ at the current cursor position. +- :kbd:`I` enters :ref:`insert mode ` at the current cursor position. -- :kbd:`V` enters `visual mode <#vi-mode-visual>`_ at the current cursor position. +- :kbd:`V` enters :ref:`visual mode ` at the current cursor position. -- :kbd:`A` enters `insert mode <#vi-mode-insert>`_ after the current cursor position. +- :kbd:`A` enters :ref:`insert mode ` after the current cursor position. -- :kbd:`Shift`\ +\ :kbd:`A` enters `insert mode <#vi-mode-insert>`_ at the end of the line. +- :kbd:`Shift`\ +\ :kbd:`A` enters :ref:`insert mode ` at the end of the line. - :kbd:`0` (zero) moves the cursor to beginning of line (remaining in command mode). -- :kbd:`D`\ +\ :kbd:`D` deletes the current line and moves it to the `killring <#killring>`__. +- :kbd:`D`\ +\ :kbd:`D` deletes the current line and moves it to the :ref:`killring `. -- :kbd:`Shift`\ +\ :kbd:`D` deletes text after the current cursor position and moves it to the `killring <#killring>`__. +- :kbd:`Shift`\ +\ :kbd:`D` deletes text after the current cursor position and moves it to the :ref:`killring `. -- :kbd:`P` pastes text from the `killring <#killring>`__. +- :kbd:`P` pastes text from the :ref:`killring `. - :kbd:`U` search history backwards. -- :kbd:`[` and :kbd:`]` search the command history for the previous/next token containing the token under the cursor before the search was started. See the `history <#history-search>`_ section for more information on history searching. +- :kbd:`[` and :kbd:`]` search the command history for the previous/next token containing the token under the cursor before the search was started. See the :ref:`history ` section for more information on history searching. - :kbd:`Backspace` moves the cursor left. @@ -1836,7 +1836,7 @@ Command mode is also known as normal mode. Insert mode ^^^^^^^^^^^ -- :kbd:`Escape` enters `command mode <#vi-mode-command>`_. +- :kbd:`Escape` enters :ref:`command mode `. - :kbd:`Backspace` removes one character to the left. @@ -1849,9 +1849,9 @@ Visual mode - :kbd:`B` and :kbd:`W` extend the selection backward/forward by one word. -- :kbd:`D` and :kbd:`X` move the selection to the `killring <#killring>`__ and enter `command mode <#vi-mode-command>`__. +- :kbd:`D` and :kbd:`X` move the selection to the :ref:`killring ` and enter :ref:`command mode `. -- :kbd:`Escape` and :kbd:`Control`\ +\ :kbd:`C` enter `command mode <#vi-mode-command>`_. +- :kbd:`Escape` and :kbd:`Control`\ +\ :kbd:`C` enter :ref:`command mode `. .. _custom-binds: @@ -2012,7 +2012,7 @@ If you want to add the directory ``~/linux/bin`` to your PATH variable when usin set -gx PATH $PATH ~/linux/bin end -If you want to run a set of commands when fish exits, use an `event handler <#event>`_ that is triggered by the exit of the shell:: +If you want to run a set of commands when fish exits, use an :ref:`event handler ` that is triggered by the exit of the shell:: function on_exit --on-event fish_exit diff --git a/doc_src/tutorial.rst b/doc_src/tutorial.rst index 0317a95bc..511a27f8f 100644 --- a/doc_src/tutorial.rst +++ b/doc_src/tutorial.rst @@ -28,8 +28,8 @@ which means you are all set up and can start using fish:: This prompt that you see above is the fish default prompt: it shows your username, hostname, and working directory. -- to change this prompt see `how to change your prompt <#prompt>`_ -- to switch to fish permanently see `switch your default shell to fish <#switching-to-fish>`_. +- to change this prompt see :ref:`how to change your prompt ` +- to switch to fish permanently see :ref:`switch your default shell to fish `. From now on, we'll pretend your prompt is just a ``>`` to save space. @@ -373,7 +373,7 @@ Lists adjacent to other lists or strings are expanded as :ref:`cartesian product 1 2 3 banana -This is similar to `Brace expansion `__. +This is similar to :ref:`Brace expansion `. Command Substitutions ---------------------