From 6ead168c82c2395ce13ee86b58ba1bca6faf21c1 Mon Sep 17 00:00:00 2001 From: Fabian Boehm Date: Fri, 28 Mar 2025 20:12:58 +0100 Subject: [PATCH] docs: Remove "just"/"simply" weasel words Text like "simply do" or "just press" is patronizing and unnecessary. The prose is nicer if it's removed, and in some cases other words are more specific. Something like "we'll pretend your prompt is just a ``>``" can stay. --- doc_src/cmds/_.rst | 2 +- doc_src/cmds/argparse.rst | 8 +++--- doc_src/cmds/history.rst | 4 +-- doc_src/cmds/path.rst | 2 +- doc_src/cmds/read.rst | 2 +- doc_src/cmds/string-match.rst | 4 +-- doc_src/cmds/test.rst | 2 +- doc_src/faq.rst | 14 +++++------ doc_src/fish_for_bash_users.rst | 12 ++++----- doc_src/interactive.rst | 12 ++++----- doc_src/language.rst | 44 ++++++++++++++++----------------- 11 files changed, 53 insertions(+), 53 deletions(-) diff --git a/doc_src/cmds/_.rst b/doc_src/cmds/_.rst index a8d11e8b8..b5b1519eb 100644 --- a/doc_src/cmds/_.rst +++ b/doc_src/cmds/_.rst @@ -17,7 +17,7 @@ Description It is equivalent to ``gettext fish STRING``, meaning it can only be used to look up fish's own translations. -It requires fish to be built with gettext support. If that support is disabled, or there is no translation it will simply echo the argument back. +It requires fish to be built with gettext support. If that support is disabled, or there is no translation it will echo the argument back. The language depends on the current locale, set with :envvar:`LANG` and :envvar:`LC_MESSAGES`. diff --git a/doc_src/cmds/argparse.rst b/doc_src/cmds/argparse.rst index 49febc7f0..0ce738a4b 100644 --- a/doc_src/cmds/argparse.rst +++ b/doc_src/cmds/argparse.rst @@ -20,7 +20,7 @@ Each option specification (``OPTION_SPEC``) is written in the :ref:`domain speci 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``. -The variables 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, it just is passed or not, it doesn't have a value) the values are the short and long flags seen. If the option is not a boolean 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 variable will not be set. +The variables 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, it is passed or not, it doesn't have a value) the values are the short and long flags seen. If the option is not a boolean 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 variable will not be set. Options ------- @@ -165,7 +165,7 @@ This isn't specific to argparse but common to all things using ``getopt(3)`` (if Flag Value Validation --------------------- -Sometimes you need to validate the option values. For example, that it is a valid integer within a specific range, or an ip address, or something entirely different. 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: +Sometimes you need to validate the option values. For example, that it is a valid integer within a specific range, or an ip address, or something entirely different. 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 append an ``!`` (exclamation-mark) then the fish script to be run. When that code is executed three vars will be defined: - ``_argparse_cmd`` will be set to the value of the value of the ``argparse --name`` value. @@ -177,7 +177,7 @@ These variables are passed to the function as local exported variables. The script should write any error messages to stdout, not stderr. It should return a status of zero if the flag value is valid otherwise a non-zero status to indicate it is invalid. -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. +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 call ``_validate_int`` without those flags is to check that the value is a valid integer with no limits on the min or max value allowed. Here are some examples of flag validations:: @@ -234,7 +234,7 @@ A simple use:: return 0 end -This just wants one option - ``-h`` / ``--help``. Any other option is an error. If it is given it prints help and exits. +This supports one option - ``-h`` / ``--help``. Any other option is an error. If it is given it prints help and exits. How :doc:`fish_add_path` parses its args:: diff --git a/doc_src/cmds/history.rst b/doc_src/cmds/history.rst index 254db771c..35cdf99e3 100644 --- a/doc_src/cmds/history.rst +++ b/doc_src/cmds/history.rst @@ -27,10 +27,10 @@ Description The following operations (sub-commands) are available: **search** - Returns history items matching the search string. If no search string is provided it returns all history items. This is the default operation if no other operation is specified. You only have to explicitly say ``history search`` if you wish to search for one of the subcommands. The ``--contains`` search option will be used if you don't specify a different search option. Entries are ordered newest to oldest unless you use the ``--reverse`` flag. If stdout is attached to a tty the output will be piped through your pager by the history function. The history builtin simply writes the results to stdout. + Returns history items matching the search string. If no search string is provided it returns all history items. This is the default operation if no other operation is specified. You only have to explicitly say ``history search`` if you wish to search for one of the subcommands. The ``--contains`` search option will be used if you don't specify a different search option. Entries are ordered newest to oldest unless you use the ``--reverse`` flag. If stdout is attached to a tty the output will be piped through your pager by the history function. The history builtin writes the results to stdout. **delete** - Deletes history items. The ``--contains`` search option will be used if you don't specify a different search option. If you don't specify ``--exact`` a prompt will be displayed before any items are deleted asking you which entries are to be deleted. You can enter the word "all" to delete all matching entries. You can enter a single ID (the number in square brackets) to delete just that single entry. You can enter more than one ID, or an ID range separated by a space to delete multiple entries. Just press [enter] to not delete anything. Note that the interactive delete behavior is a feature of the history function. The history builtin only supports ``--exact --case-sensitive`` deletion. + Deletes history items. The ``--contains`` search option will be used if you don't specify a different search option. If you don't specify ``--exact`` a prompt will be displayed before any items are deleted asking you which entries are to be deleted. You can enter the word "all" to delete all matching entries. You can enter a single ID (the number in square brackets) to delete just that single entry. You can enter more than one ID, or an ID range separated by a space to delete multiple entries. Press [enter] to not delete anything. Note that the interactive delete behavior is a feature of the history function. The history builtin only supports ``--exact --case-sensitive`` deletion. **merge** Immediately incorporates history changes from other sessions. Ordinarily ``fish`` ignores history changes from sessions started after the current one. This command applies those changes immediately. diff --git a/doc_src/cmds/path.rst b/doc_src/cmds/path.rst index 7182c2f5c..fb000194d 100644 --- a/doc_src/cmds/path.rst +++ b/doc_src/cmds/path.rst @@ -346,7 +346,7 @@ Examples path change-extension [-z | --null-in] [-Z | --null-out] \ [-q | --quiet] EXTENSION [PATH ...] -``path change-extension`` returns the given paths, with their extension changed to the given new extension. The extension is the part after (and including) the last ".", unless that "." followed a "/" or the basename is "." or "..", in which case there is no previous extension and the new one is simply added. +``path change-extension`` returns the given paths, with their extension changed to the given new extension. The extension is the part after (and including) the last ".", unless that "." followed a "/" or the basename is "." or "..", in which case there is no previous extension and the new one is added. If the extension is empty, any previous extension is stripped, along with the ".". This is, of course, the inverse of ``path extension``. diff --git a/doc_src/cmds/read.rst b/doc_src/cmds/read.rst index bc2e2ae11..66463a7d5 100644 --- a/doc_src/cmds/read.rst +++ b/doc_src/cmds/read.rst @@ -101,7 +101,7 @@ If no option to determine how to split like ``--delimiter``, ``--line`` or ``--t With the ``--line`` option, ``read`` reads a line of input from standard input into each provided variable, stopping when each variable has been filled. The line is not tokenized. -If no variable names are provided, ``read`` enters a special case that simply provides redirection from standard input to standard output, useful for command substitution. For instance, the fish shell command below can be used to read a password from the console instead of hardcoding it in the command itself, which prevents it from showing up in fish's history:: +If no variable names are provided, ``read`` enters a special case that provides redirection from standard input to standard output, useful for command substitution. For instance, the fish shell command below can be used to read a password from the console instead of hardcoding it in the command itself, which prevents it from showing up in fish's history:: mysql -uuser -p(read) diff --git a/doc_src/cmds/string-match.rst b/doc_src/cmds/string-match.rst index 4e5b18378..5121d2e04 100644 --- a/doc_src/cmds/string-match.rst +++ b/doc_src/cmds/string-match.rst @@ -22,11 +22,11 @@ Description ``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. -If you specify the **-e** or **--entire** then each matching string is printed including any prefix or suffix not matched by the pattern (equivalent to ``grep`` without the **-o** flag). You can, obviously, achieve the same result by prepending and appending **\*** or **.*** depending on whether or not you have specified the **--regex** flag. The **--entire** flag is simply a way to avoid having to complicate the pattern in that fashion and make the intent of the ``string match`` clearer. Without **--entire** and **--regex**, a *PATTERN* will need to match the entire *STRING* before it will be reported. +If you specify the **-e** or **--entire** then each matching string is printed including any prefix or suffix not matched by the pattern (equivalent to ``grep`` without the **-o** flag). You can, obviously, achieve the same result by prepending and appending **\*** or **.*** depending on whether or not you have specified the **--regex** flag. The **--entire** flag is a way to avoid having to complicate the pattern in that fashion and make the intent of the ``string match`` clearer. Without **--entire** and **--regex**, a *PATTERN* will need to match the entire *STRING* before it will be reported. Matching can be made case-insensitive with **--ignore-case** or **-i**. -If **--groups-only** or **-g** is given, only the capturing groups will be reported - meaning the full match will be skipped. This is incompatible with **--entire** and **--invert**, and requires **--regex**. It is useful as a simple cutting tool instead of ``string replace``, so you can simply choose "this part" of a string. +If **--groups-only** or **-g** is given, only the capturing groups will be reported - meaning the full match will be skipped. This is incompatible with **--entire** and **--invert**, and requires **--regex**. It is useful as a simple cutting tool instead of ``string replace``, so you can choose "this part" of a string. If **--index** or **-n** is given, each match is reported as a 1-based start position and a length. By default, PATTERN is interpreted as a glob pattern matched against each entire *STRING* argument. A glob pattern is only considered a valid match if it matches the entire *STRING*. diff --git a/doc_src/cmds/test.rst b/doc_src/cmds/test.rst index 84721375a..1e26d2c01 100644 --- a/doc_src/cmds/test.rst +++ b/doc_src/cmds/test.rst @@ -203,7 +203,7 @@ Parentheses and the ``-o`` and ``-a`` operators can be combined to produce more end -Numerical comparisons will simply fail if one of the operands is not a number: +Numerical comparisons will fail if one of the operands is not a number: :: diff --git a/doc_src/faq.rst b/doc_src/faq.rst index 21a341a62..74bf65bd5 100644 --- a/doc_src/faq.rst +++ b/doc_src/faq.rst @@ -13,7 +13,7 @@ Use the :doc:`set ` command:: set -x key value # typically set -gx key value set -e key -Since fish 3.1 you can set an environment variable for just one command using the ``key=value some command`` syntax, like in other shells. The two lines below behave identically - unlike other shells, fish will output ``value`` both times:: +Since fish 3.1 you can set an environment variable for one command using the ``key=value some command`` syntax, like in other shells. The two lines below behave identically - unlike other shells, fish will output ``value`` both times:: key=value echo $key begin; set -lx key value; echo $key; end @@ -162,11 +162,11 @@ Why doesn't history substitution ("!$" etc.) work? -------------------------------------------------- Because history substitution is an awkward interface that was invented before interactive line editing was even possible. Instead of adding this pseudo-syntax, fish opts for nice history searching and recall features. Switching requires a small change of habits: if you want to modify an old line/word, first recall it, then edit. -As a special case, most of the time history substitution is used as ``sudo !!``. In that case just press :kbd:`alt-s`, and it will recall your last commandline with ``sudo`` prefixed (or toggle a ``sudo`` prefix on the current commandline if there is anything). +As a special case, most of the time history substitution is used as ``sudo !!``. In that case press :kbd:`alt-s`, and it will recall your last commandline with ``sudo`` prefixed (or toggle a ``sudo`` prefix on the current commandline if there is anything). In general, fish's history recall works like this: -- Like other shells, the Up arrow, ``up`` recalls whole lines, starting from the last executed line. So instead of typing ``!!``, you would just hit the up-arrow. +- Like other shells, the Up arrow, ``up`` recalls whole lines, starting from the last executed line. So instead of typing ``!!``, you would hit the up-arrow. - If the line you want is far back in the history, type any part of the line and then press Up one or more times. This will filter the recalled lines to ones that include this text, and you will get to the line you want much faster. This replaces "!vi", "!?bar.c" and the like. If you want to see more context, you can press ``ctrl-r`` to open the history in the pager. @@ -174,7 +174,7 @@ In general, fish's history recall works like this: See :ref:`documentation ` for more details about line editing in fish. -That being said, you can use :ref:`abbreviations` to implement history substitution. Here's just ``!!``:: +That being said, you can use :ref:`abbreviations` to implement history substitution. Here's ``!!`` only:: function last_history_item; echo $history[1]; end abbr -a !! --position anywhere --function last_history_item @@ -232,7 +232,7 @@ Use the ``$status`` variable. This replaces the ``$?`` variable used in other sh end -If you are just interested in success or failure, you can run the command directly as the if-condition:: +If you are only interested in success or failure, you can run the command directly as the if-condition:: if somecommand echo "Command succeeded" @@ -330,7 +330,7 @@ This is more important to fish than other shells because features like syntax hi Sometimes, there is disagreement on the width. There are numerous causes and fixes for this: -- It is possible the character is simply too new for your system to know - in this case you need to refrain from using it. +- It is possible the character is too new for your system to know - in this case you need to refrain from using it. - Fish or your terminal might not know about the character or handle it wrong - in this case fish or your terminal needs to be fixed, or you need to update to a fixed version. - The character has an "ambiguous" width and fish thinks that means a width of X while your terminal thinks it's Y. In this case you either need to change your terminal's configuration or set $fish_ambiguous_width to the correct value. - The character is an emoji and the host system only supports Unicode 8, while you are running the terminal on a system that uses Unicode >= 9. In this case set $fish_emoji_width to 2. @@ -346,7 +346,7 @@ Uninstalling fish ----------------- If you want to uninstall fish, first make sure fish is not set as your shell. Run ``chsh -s /bin/bash`` if you are not sure. -If you installed it with a package manager, just use that package manager's uninstall function. If you built fish yourself, assuming you installed it to /usr/local, do this:: +If you installed it with a package manager, use that package manager's uninstall function. If you built fish yourself, assuming you installed it to /usr/local, do this:: rm -Rf /usr/local/etc/fish /usr/local/share/fish ~/.config/fish rm /usr/local/share/man/man1/fish*.1 diff --git a/doc_src/fish_for_bash_users.rst b/doc_src/fish_for_bash_users.rst index edb5c35a4..49b9cb14c 100644 --- a/doc_src/fish_for_bash_users.rst +++ b/doc_src/fish_for_bash_users.rst @@ -192,7 +192,7 @@ Note that both of these are bashisms, and most things can easily be expressed wi source (command | psub) -just use:: +Use:: command | source @@ -246,7 +246,7 @@ is mostly the same as foo EOF -Just like with heredocs, the command has to be prepared to read from stdin. Sometimes this requires special options to be used, often giving a filename of ``-`` turns it on. +Like with heredocs, the command has to be prepared to read from stdin. Sometimes this requires special options to be used, often giving a filename of ``-`` turns it on. For example:: @@ -266,7 +266,7 @@ and could be written in other shells as rxvt-unicode EOF -So heredocs really are just minor syntactical sugar that introduces a lot of special rules, which is why fish doesn't have them. Pipes are a core concept, and are simpler and compose nicer. +So heredocs really are minor syntactical sugar that introduces a lot of special rules, which is why fish doesn't have them. Pipes are a core concept, and are simpler and compose nicer. .. [#] For example, the "EOF" is just a convention, the terminator can be an arbitrary string, something like "THISISTHEEND" also works. And using ``<<-`` trims leading *tab* characters (but not other whitespace), so you can indent the lines, but only with tabs. Substitutions (variables, commands) are done on the heredoc by default, but not if the terminator is quoted: ``cat << "EOF"``. @@ -326,7 +326,7 @@ and a rough fish equivalent:: This shows a few differences: - Fish provides :doc:`set_color ` to color text. It can use the 16 named colors and also RGB sequences (so you could also use ``set_color 5555FF``) -- Instead of introducing specific escapes like ``\h`` for the hostname, the prompt is simply a function. To achieve the effect of ``\h``, fish provides helper functions like :doc:`prompt_hostname `, which prints a shortened version of the hostname. +- Instead of introducing specific escapes like ``\h`` for the hostname, the prompt is a function. To achieve the effect of ``\h``, fish provides helper functions like :doc:`prompt_hostname `, which prints a shortened version of the hostname. - Fish offers other helper functions for adding things to the prompt, like :doc:`fish_vcs_prompt ` for adding a display for common version control systems (git, mercurial, svn), and :doc:`prompt_pwd ` for showing a shortened ``$PWD`` (the user's home directory becomes ``~`` and any path component is shortened). The default prompt is reasonably full-featured and its code can be read via ``type fish_prompt``. @@ -417,7 +417,7 @@ This includes things like: baz & done -Fish does not currently have subshells. You will have to find a different solution. The isolation can usually be achieved by just scoping variables (with ``set -l``), but if you really do need to run your code in a new shell environment you can use ``fish -c 'your code here'`` to do so explicitly. +Fish does not currently have subshells. You will have to find a different solution. The isolation can usually be achieved by scoping variables (with ``set -l``), but if you really do need to run your code in a new shell environment you can use ``fish -c 'your code here'`` to do so explicitly. ``()`` subshells are often confused with ``{}`` grouping, which does *not* use a subshell. When you just need to group, you can use ``begin; end`` in fish:: @@ -427,7 +427,7 @@ Fish does not currently have subshells. You will have to find a different soluti # becomes begin; foo; bar; end | baz -The pipe will simply be run in the same process, so ``while read`` loops can set variables outside:: +The pipe will be run in the same process, so ``while read`` loops can set variables outside:: foo | while read bar set -g VAR VAL diff --git a/doc_src/interactive.rst b/doc_src/interactive.rst index b971c006f..23453d6fd 100644 --- a/doc_src/interactive.rst +++ b/doc_src/interactive.rst @@ -25,7 +25,7 @@ Autosuggestions 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:`right` (``→``) or :kbd:`ctrl-f`. To accept the first suggested word, press :kbd:`alt-right` (``→``) or :kbd:`alt-f`. If the autosuggestion is not what you want, just ignore it: it won't execute unless you accept it. +To accept the autosuggestion (replacing the command line contents), press :kbd:`right` (``→``) or :kbd:`ctrl-f`. To accept the first suggested word, press :kbd:`alt-right` (``→``) or :kbd:`alt-f`. If the autosuggestion is not what you want, ignore it: it won't execute unless you accept it. Autosuggestions are a powerful way to quickly summon frequently entered commands, by typing the first few characters. They are also an efficient technique for navigating through directory hierarchies. @@ -38,7 +38,7 @@ If you don't like autosuggestions, you can disable them by setting ``$fish_autos Tab Completion -------------- -Tab completion is a time saving feature of any modern shell. When you type :kbd:`tab`, fish tries to guess the rest of the word under the cursor. If it finds just one possibility, it inserts it. If it finds more, it inserts the longest unambiguous part and then opens a menu (the "pager") that you can navigate to find what you're looking for. +Tab completion is a time saving feature of any modern shell. When you type :kbd:`tab`, fish tries to guess the rest of the word under the cursor. If it finds exactly one possibility, it inserts it. If it finds more, it inserts the longest unambiguous part and then opens a menu (the "pager") that you can navigate to find what you're looking for. The pager can be navigated with the arrow keys, :kbd:`pageup` / :kbd:`pagedown`, :kbd:`tab` or :kbd:`shift-tab`. Pressing :kbd:`ctrl-s` (the ``pager-toggle-search`` binding - :kbd:`/` in vi mode) opens up a search menu that you can use to filter the list. @@ -56,7 +56,7 @@ It also provides a large number of program specific scripted completions. Most o You can also write your own completions or install some you got from someone else. For that, see :ref:`Writing your own completions `. -Completion scripts are loaded on demand, just like :ref:`functions are `. The difference is the ``$fish_complete_path`` :ref:`list ` is used instead of ``$fish_function_path``. Typically you can drop new completions in ~/.config/fish/completions/name-of-command.fish and fish will find them automatically. +Completion scripts are loaded on demand, like :ref:`functions are `. The difference is the ``$fish_complete_path`` :ref:`list ` is used instead of ``$fish_function_path``. Typically you can drop new completions in ~/.config/fish/completions/name-of-command.fish and fish will find them automatically. .. _color: @@ -554,7 +554,7 @@ In addition to the standard bindings listed here, you can also define your own w Put ``bind`` statements into :ref:`config.fish ` or a function called ``fish_user_key_bindings``. -If you change your mind on a binding and want to go back to fish's default, you can simply erase it again:: +If you change your mind on a binding and want to go back to fish's default, you can erase it again:: bind --erase ctrl-c @@ -606,7 +606,7 @@ Copy and paste (Kill Ring) Fish uses an Emacs-style kill ring for copy and paste functionality. For example, use :kbd:`ctrl-k` (`kill-line`) to cut from the current cursor position to the end of the line. The string that is cut (a.k.a. killed in emacs-ese) is inserted into a list of kills, called the kill ring. To paste the latest value from the kill ring (emacs calls this "yanking") use :kbd:`ctrl-y` (the ``yank`` input function). After pasting, use :kbd:`alt-y` (``yank-pop``) to rotate to the previous kill. Copy and paste from outside are also supported, both via the :kbd:`ctrl-x` / :kbd:`ctrl-v` bindings (the ``fish_clipboard_copy`` and ``fish_clipboard_paste`` functions [#]_) and via the terminal's paste function, for which fish enables "Bracketed Paste Mode", so it can tell a paste from manually entered text. -In addition, when pasting inside single quotes, pasted single quotes and backslashes are automatically escaped so that the result can be used as a single token simply by closing the quote after. +In addition, when pasting inside single quotes, pasted single quotes and backslashes are automatically escaped so that the result can be used as a single token by closing the quote after. Kill ring entries are stored in ``fish_killring`` variable. The commands ``begin-selection`` and ``end-selection`` (unbound by default; used for selection in vi visual mode) control text selection together with cursor movement commands that extend the current selection. @@ -636,7 +636,7 @@ Searchable command history After a command has been executed, it is remembered in the history list. Any duplicate history items are automatically removed. By pressing the up and down keys, you can search forwards and backwards in the history. If the current command line is not empty when starting a history search, only the commands containing the string entered into the command line are shown. -By pressing :kbd:`alt-up` (``↑``) and :kbd:`alt-down` (``↓``), a history search is also performed, but instead of searching for a complete commandline, each commandline is broken into separate elements just like it would be before execution, and the history is searched for an element matching that under the cursor. +By pressing :kbd:`alt-up` (``↑``) and :kbd:`alt-down` (``↓``), a history search is also performed, but instead of searching for a complete commandline, each commandline is broken into separate elements like it would be before execution, and the history is searched for an element matching that under the cursor. For more complicated searches, you can press :kbd:`ctrl-r` to open a pager that allows you to search the history. It shows a limited number of entries in one page, press :kbd:`ctrl-r` [#]_ again to move to the next page and :kbd:`ctrl-s` [#]_ to move to the previous page. You can change the text to refine your search. diff --git a/doc_src/language.rst b/doc_src/language.rst index a62406fac..13dc3a93e 100644 --- a/doc_src/language.rst +++ b/doc_src/language.rst @@ -257,7 +257,7 @@ This is important when any redirections reference other file descriptors with th Consider this helper function:: - # Just make a function that prints something to stdout and stderr + # Make a function that prints something to stdout and stderr function print echo out echo err >&2 @@ -281,7 +281,7 @@ Now let's see a few cases:: Job control ----------- -When you start a job in fish, fish itself will pause, and give control of the terminal to the program just started. Sometimes, you want to continue using the commandline, and have the job run in the background. To create a background job, append an ``&`` (ampersand) to your command. This will tell fish to run the job in the background. Background jobs are very useful when running programs that have a graphical user interface. +When you start a job in fish, fish itself will pause, and give control of the terminal to the program it just started. Sometimes, you want to continue using the commandline, and have the job run in the background. To create a background job, append an ``&`` (ampersand) to your command. This will tell fish to run the job in the background. Background jobs are very useful when running programs that have a graphical user interface. Example:: @@ -314,7 +314,7 @@ For example, here's a simple function to list directories:: ls -l $argv end -The first line tells fish to define a function by the name of ``ll``, so it can be used by simply writing ``ll`` on the commandline. The second line tells fish that the command ``ls -l $argv`` should be called when ``ll`` is invoked. :ref:`$argv ` is a :ref:`list variable `, which always contains all arguments sent to the function. In the example above, these are simply passed on to the ``ls`` command. The ``end`` on the third line ends the definition. +The first line tells fish to define a function by the name of ``ll``, so it can be used by writing ``ll`` on the commandline. The second line tells fish that the command ``ls -l $argv`` should be called when ``ll`` is invoked. :ref:`$argv ` is a :ref:`list variable `, which always contains all arguments sent to the function. In the example above, these are passed on to the ``ls`` command. The ``end`` on the third line ends the definition. Calling this as ``ll /tmp/`` will end up running ``ls -l /tmp/``, which will list the contents of /tmp. @@ -408,7 +408,7 @@ This is useful to explain what and why you are doing something:: command ls --color=auto $argv end -There are no multiline comments. If you want to make a comment span multiple lines, simply start each line with a ``#``. +There are no multiline comments. If you want to make a comment span multiple lines, start each line with a ``#``. Comments can also appear after a line like so:: @@ -436,7 +436,7 @@ Like other shells, but unlike typical programming languages you might know, the This uses the :doc:`test ` command to see if the file /etc/os-release exists. If it does, it runs ``cat``, which prints it on the screen. -Unlike other shells, the condition command just ends after the first job, there is no ``then`` here. Combiners like ``and`` and ``or`` extend the condition. +Unlike other shells, the condition command ends after the first job, there is no ``then`` here. Combiners like ``and`` and ``or`` extend the condition. A more complicated example with a :ref:`command substitution `:: @@ -460,7 +460,7 @@ Because ``test`` can be used for many different tests, it is important to quote The :doc:`not ` keyword can be used to invert the status:: - # Just see if the file contains the string "fish" anywhere. + # Check if the file contains the string "fish" anywhere. # This executes the `grep` command, which searches for a string, # and if it finds it returns a status of 0. # The `not` then turns 0 into 1 or anything else into 0. @@ -530,7 +530,7 @@ Or you can have a case where it is necessary to stop early:: If this went on after seeing that the command "foo" doesn't exist, it would try to run ``foo`` and error because it wasn't found! -Combiners really just execute step-by-step, so it isn't recommended to build longer chains of them because they might do something you don't want. Consider:: +Combiners execute step-by-step, so it isn't recommended to build longer chains of them because they might do something you don't want. Consider:: test -e /etc/my.config or echo "OH NO WE NEED A CONFIG FILE" @@ -567,7 +567,7 @@ will print "Still running" once a second. You can abort it with ctrl-c. echo file: $file end -will print each file in the current directory. The part after the ``in`` is just a list of arguments, so you can use any :ref:`expansions ` there:: +will print each file in the current directory. The part after the ``in`` is a list of arguments, so you can use any :ref:`expansions ` there:: set moreanimals bird fox for animal in {cat,}fish dog $moreanimals @@ -620,7 +620,7 @@ When a parameter includes an :ref:`unquoted ` ``*`` star (or "asterisk") - ``**`` matches any number of characters (including zero), and also descends into subdirectories. If ``**`` is a segment by itself, that segment may match zero times, for compatibility with other shells. -- ``?`` can match any single character except ``/``. This is deprecated and can be disabled via the ``qmark-noglob`` :ref:`feature flag`, so ``?`` will just be an ordinary character. +- ``?`` can match any single character except ``/``. This is deprecated and can be disabled via the ``qmark-noglob`` :ref:`feature flag`, so ``?`` will be an ordinary character. Wildcard matches are sorted case insensitively. When sorting matches containing numbers, they are naturally sorted, so that the strings '1' '5' and '12' would be sorted like 1, 5, 12. @@ -658,7 +658,7 @@ Variable expansion One of the most important expansions in fish is the "variable expansion". This is the replacing of a dollar sign (``$``) followed by a variable name with the _value_ of that variable. -In the simplest case, this is just something like:: +A simple example:: echo $HOME @@ -859,13 +859,13 @@ Examples:: # Set ``$data`` to the contents of data, splitting on NUL-bytes. set data (cat data | string split0) -Sometimes you want to pass the output of a command to another command that only accepts files. If it's just one file, you can usually just pass it via a pipe, like:: +Sometimes you want to pass the output of a command to another command that only accepts files. If it's just one file, you can usually pass it via a pipe, like:: grep fish myanimallist1 | wc -l but if you need multiple or the command doesn't read from standard input, "process substitution" is useful. Other shells allow this via ``foo <(bar) <(baz)``, and fish uses the :doc:`psub ` command:: - # Compare just the lines containing "fish" in two files: + # Compare only the lines containing "fish" in two files: diff -u (grep fish myanimallist1 | psub) (grep fish myanimallist2 | psub) This creates a temporary file, stores the output of the command in that file and prints the filename, so it is given to the outer command. @@ -909,7 +909,7 @@ If there is no "," or variable expansion between the curly braces, they will not If after expansion there is nothing between the braces, the argument will be removed (see :ref:`the Combining Lists ` section):: > echo foo-{$undefinedvar} - # Output is an empty line, just like a bare `echo`. + # Output is an empty line, like a bare `echo`. If there is nothing between a brace and a comma or two commas, it's interpreted as an empty element:: @@ -1326,7 +1326,7 @@ To see universal variables in action, start two fish sessions side by side, and :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. +Do not append to universal variables in :ref:`config.fish `, because these variables will then get longer with each new shell instance. Instead, set them once at the command line. .. _variables-export: @@ -1369,7 +1369,7 @@ To access one element of a list, use the index of the element inside of square b echo $PATH[3] -List indices start at 1 in fish, not 0 like in other languages. This is because it requires less subtracting of 1 and many common Unix tools like ``seq`` work better with it (``seq 5`` prints 1 to 5, not 0 to 5). An invalid index is silently ignored resulting in no value (not even an empty string, just no argument at all). +List indices start at 1 in fish, not 0 like in other languages. This is because it requires less subtracting of 1 and many common Unix tools like ``seq`` work better with it (``seq 5`` prints 1 to 5, not 0 to 5). An invalid index is silently ignored resulting in no value (not even an empty string, no argument at all). If you don't use any brackets, all the elements of the list will be passed to the command as separate items. This means you can iterate over a list with ``for``:: @@ -1379,7 +1379,7 @@ If you don't use any brackets, all the elements of the list will be passed to th This goes over every directory in :envvar:`PATH` separately and prints a line saying it is in the path. -To create a variable ``smurf``, containing the items ``blue`` and ``small``, simply write:: +To create a variable ``smurf``, containing the items ``blue`` and ``small``, write:: set smurf blue small @@ -1441,7 +1441,7 @@ Lists can be inspected with the :doc:`count ` or the :doc:`contains > contains -i blue $smurf 1 -A nice thing about lists is that they are passed to commands one element as one argument, so once you've set your list, you can just pass it:: +A nice thing about lists is that they are passed to commands one element as one argument, so once you've set your list, you can pass it:: set -l grep_args -r "my string" grep $grep_args . # will run the same as `grep -r "my string"` . @@ -1715,7 +1715,7 @@ Fish also provides additional information through the values of certain environm .. ENVVAR:: SHLVL - the level of nesting of shells. Fish increments this in interactive shells, otherwise it simply passes it along. + the level of nesting of shells. Fish increments this in interactive shells, otherwise it only passes it along. .. envvar:: status @@ -1954,7 +1954,7 @@ Let's make up an example. This function will :ref:`glob ` the f printf '%s\n' $files end -If you run this as ``show_files /``, it will most likely ask you until you press Y/y or N/n. If you run this as ``show_files / | cat``, it will print the files without asking. If you run this as ``show_files .``, it might just print something without asking because there are fewer than five files. +If you run this as ``show_files /``, it will most likely ask you until you press Y/y or N/n. If you run this as ``show_files / | cat``, it will print the files without asking. If you run this as ``show_files .``, it might print something without asking because there are fewer than five files. .. _identifiers: @@ -2027,7 +2027,7 @@ You can see the current list of features via ``status features``:: Here is what they mean: -- ``stderr-nocaret`` was introduced in fish 3.0 and cannot be turned off since fish 3.5. It can still be tested for compatibility, but a ``no-stderr-nocaret`` value will simply be ignored. The flag made ``^`` an ordinary character instead of denoting an stderr redirection. Use ``2>`` instead. +- ``stderr-nocaret`` was introduced in fish 3.0 and cannot be turned off since fish 3.5. It can still be tested for compatibility, but a ``no-stderr-nocaret`` value will be ignored. The flag made ``^`` an ordinary character instead of denoting an stderr redirection. Use ``2>`` instead. - ``qmark-noglob`` was also introduced in fish 3.0 (and made the default in 4.0). It makes ``?`` an ordinary character instead of a single-character glob. Use a ``*`` instead (which will match multiple characters) or find other ways to match files like ``find``. - ``regex-easyesc`` was introduced in 3.1 (and made the default in 3.5). It makes it so the replacement expression in ``string replace -r`` does one fewer round of escaping. Before, to escape a backslash you would have to use ``string replace -ra '([ab])' '\\\\\\\\$1'``. After, just ``'\\\\$1'`` is enough. Check your ``string replace`` calls if you use this anywhere. - ``ampersand-nobg-in-token`` was introduced in fish 3.4 (and made the default in 3.5). It makes it so a ``&`` i no longer interpreted as the backgrounding operator in the middle of a token, so dealing with URLs becomes easier. Either put spaces or a semicolon after the ``&``. This is recommended formatting anyway, and ``fish_indent`` will have done it for you already. @@ -2116,9 +2116,9 @@ For more information on how to define new event handlers, see the documentation Debugging fish scripts ---------------------- -Fish includes basic built-in debugging facilities that allow you to stop execution of a script at an arbitrary point. When this happens you are presented with an interactive prompt where you can execute any fish command to inspect or change state (there are no debug commands as such). For example, you can check or change the value of any variables using :doc:`printf ` and :doc:`set `. As another example, you can run :doc:`status print-stack-trace ` to see how the current breakpoint was reached. To resume normal execution of the script, simply type :doc:`exit ` or :kbd:`ctrl-d`. +Fish includes basic built-in debugging facilities that allow you to stop execution of a script at an arbitrary point. When this happens you are presented with an interactive prompt where you can execute any fish command to inspect or change state (there are no debug commands as such). For example, you can check or change the value of any variables using :doc:`printf ` and :doc:`set `. As another example, you can run :doc:`status print-stack-trace ` to see how the current breakpoint was reached. To resume normal execution of the script, type :doc:`exit ` or :kbd:`ctrl-d`. -To start a debug session simply insert the :doc:`builtin command ` ``breakpoint`` at the point in a function or script where you wish to gain control, then run the function or script. Also, the default action of the ``TRAP`` signal is to call this builtin, meaning a running script can be actively debugged by sending it the ``TRAP`` signal (``kill -s TRAP ``). There is limited support for interactively setting or modifying breakpoints from this debug prompt: it is possible to insert new breakpoints in (or remove old ones from) other functions by using the ``funced`` function to edit the definition of a function, but it is not possible to add or remove a breakpoint from the function/script currently loaded and being executed. +To start a debug session insert the :doc:`builtin command ` ``breakpoint`` at the point in a function or script where you wish to gain control, then run the function or script. Also, the default action of the ``TRAP`` signal is to call this builtin, meaning a running script can be actively debugged by sending it the ``TRAP`` signal (``kill -s TRAP ``). There is limited support for interactively setting or modifying breakpoints from this debug prompt: it is possible to insert new breakpoints in (or remove old ones from) other functions by using the ``funced`` function to edit the definition of a function, but it is not possible to add or remove a breakpoint from the function/script currently loaded and being executed. Another way to debug script issues is to set the :envvar:`fish_trace` variable, e.g. ``fish_trace=1 fish_prompt`` to see which commands fish executes when running the :doc:`fish_prompt ` function.