diff options
Diffstat (limited to 'doc_src')
| -rw-r--r-- | doc_src/abbr.txt | 10 | ||||
| -rw-r--r-- | doc_src/bind.txt | 2 | ||||
| -rw-r--r-- | doc_src/complete.txt | 57 | ||||
| -rw-r--r-- | doc_src/fish_vi_mode.txt | 2 | ||||
| -rw-r--r-- | doc_src/index.hdr.in | 6 | ||||
| -rw-r--r-- | doc_src/printf.txt | 2 | ||||
| -rw-r--r-- | doc_src/random.txt | 14 | ||||
| -rw-r--r-- | doc_src/set_color.txt | 17 | ||||
| -rw-r--r-- | doc_src/string.txt | 4 | ||||
| -rw-r--r-- | doc_src/tutorial.hdr | 4 |
10 files changed, 78 insertions, 40 deletions
diff --git a/doc_src/abbr.txt b/doc_src/abbr.txt index a32592d8..799e5003 100644 --- a/doc_src/abbr.txt +++ b/doc_src/abbr.txt @@ -14,7 +14,15 @@ abbr -e word Abbreviations are user-defined character sequences or words that are replaced with longer phrases after they are entered. For example, a frequently-run command such as `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. -Abbreviations are stored, by default, in a universal variable. +Abbreviations are stored using universal variables. You can create abbreviations directly on the command line, and they will be saved automatically. Do not place them in config.fish, because this will lead to worse startup performance. Alternatively, guard the assignment with another universal variable, like: + +\fish +if not set -q my_fish_abbreviations + abbr gco='git checkout' + abbr abr='another abbreviation expansion' + set -U my_fish_abbreviations 1 +end +\endfish The following parameters are available: diff --git a/doc_src/bind.txt b/doc_src/bind.txt index 3485f49b..f72e0cde 100644 --- a/doc_src/bind.txt +++ b/doc_src/bind.txt @@ -31,7 +31,7 @@ When multiple `COMMAND`s are provided, they are all run in the specified order w If no `SEQUENCE` is provided, all bindings (or just the bindings in the specified `MODE`) are printed. If `SEQUENCE` is provided without `COMMAND`, just the binding matching that sequence is printed. -Key bindings are not saved between sessions by default. To save custom keybindings, edit the `fish_user_key_bindings` function and insert the appropriate `bind` statements. +Key bindings are not saved between sessions by default. **Bare `bind` statements in <a href="index.html#initialization">config.fish</a> won't have any effect because it is sourced before the default keybindings are setup.** To save custom keybindings, put the `bind` statements into a function called `fish_user_key_bindings`, which will be <a href="tutorial.html#tut_autoload">autoloaded</a>. Key bindings may use "modes", which mimics Vi's modal input behavior. The default mode is "default", and every bind applies to a single mode. The mode can be viewed/changed with the `$fish_bind_mode` variable. diff --git a/doc_src/complete.txt b/doc_src/complete.txt index f7826e5b..5c1a1877 100644 --- a/doc_src/complete.txt +++ b/doc_src/complete.txt @@ -3,19 +3,18 @@ \subsection complete-synopsis Synopsis \fish{synopsis} complete ( -c | --command | -p | --path ) COMMAND + [( -c | --command | -p | --path ) COMMAND]... [( -e | --erase )] - [( -s | --short-option ) SHORT_OPTION] - [( -l | --long-option | -o | --old-option ) LONG_OPTION] + [( -s | --short-option ) SHORT_OPTION]... + [( -l | --long-option | -o | --old-option ) LONG_OPTION]... + [( -a | --arguments ) OPTION_ARGUMENTS] [( -f | --no-files )] [( -r | --require-parameter )] [( -x | --exclusive )] - [( -u | --unauthoritative )] - [( -A | --authoritative )] - [( -a | --arguments ) OPTION_ARGUMENTS] - [( -w | --wraps ) WRAPPED_COMMAND] + [( -w | --wraps ) WRAPPED_COMMAND]... [( -n | --condition ) CONDITION] [( -d | --description ) DESCRIPTION] -complete ( -C STRING | --do-complete=STRING ) +complete ( -C[STRING] | --do-complete[=STRING] ) \endfish \subsection complete-description Description @@ -34,41 +33,55 @@ the fish manual. - `DESCRIPTION` is a description of what the option and/or option arguments do. -- `-C STRING` or `--do-complete=STRING` makes complete try to find all possible completions for the specified string. +- `-c COMMAND` or `--command COMMAND` specifies that `COMMAND` is the name of the command. -- `-w WRAPPED_COMMAND` or `--wraps=WRAPPED_COMMAND` causes the specified command to inherit completions from the wrapped command. +- `-p COMMAND` or `--path COMMAND` specifies that `COMMAND` is the absolute path of the program (optionally containing wildcards). - `-e` or `--erase` deletes the specified completion. -- `-f` or `--no-files` specifies that the option specified by this completion may not be followed by a filename. - -- `-n` or `--condition` specifies a shell command that must return 0 if the completion is to be used. This makes it possible to specify completions that should only be used in some cases. +- `-s SHORT_OPTION` or `--short-option=SHORT_OPTION` adds a short option to the completions list. -- `-o` or `--old-option` implies that the command uses old long style options with only one dash. +- `-l LONG_OPTION` or `--long-option=LONG_OPTION` adds a GNU style long option to the completions list. -- `-p` or `--path` implies that the string `COMMAND` is the full path of the command. +- `-o LONG_OPTION` or `--old-option=LONG_OPTION` adds an old style long option to the completions list (See below for details). -- `-r` or `--require-parameter` specifies that the option specified by this completion always must have an option argument, i.e. may not be followed by another option. +- `-a OPTION_ARGUMENTS` or `--arguments=OPTION_ARGUMENTS` adds the specified option arguments to the completions list. -- `-u` or `--unauthoritative` implies that there may be more options than the ones specified, and that fish should not assume that options not listed are spelling errors. +- `-f` or `--no-files` specifies that the options specified by this completion may not be followed by a filename. -- `-A` or `--authoritative` implies that there may be no more options than the ones specified, and that fish should assume that options not listed are spelling errors. +- `-r` or `--require-parameter` specifies that the options specified by this completion always must have an option argument, i.e. may not be followed by another option. - `-x` or `--exclusive` implies both `-r` and `-f`. +- `-w WRAPPED_COMMAND` or `--wraps=WRAPPED_COMMAND` causes the specified command to inherit completions from the wrapped command (See blow for details). + +- `-n` or `--condition` specifies a shell command that must return 0 if the completion is to be used. This makes it possible to specify completions that should only be used in some cases. + +- `-CSTRING` or `--do-complete=STRING` makes complete try to find all possible completions for the specified string. + +- `-C` or `--do-complete` with no argument makes complete try to find all possible completions for the current command line buffer. If the shell is not in interactive mode, an error is returned. + Command specific tab-completions in `fish` are based on the notion of options and arguments. An option is a parameter which begins with a hyphen, such as '`-h`', '`-help`' or '`--help`'. Arguments are parameters that do not begin with a hyphen. Fish recognizes three styles of options, the same styles as the GNU version of the getopt library. These styles are: - Short options, like '`-a`'. Short options are a single character long, are preceded by a single hyphen and may be grouped together (like '`-la`', which is equivalent to '`-l -a`'). Option arguments may be specified in the following parameter ('`-w 32`') or by appending the option with the value ('`-w32`'). - Old style long options, like '`-Wall`'. Old style long options can be more than one character long, are preceded by a single hyphen and may not be grouped together. Option arguments are specified in the following parameter ('`-ao null`'). -- GNU style long options, like '`--colors`'. GNU style long options can be more than one character long, are preceded by two hyphens, and may not be grouped together. Option arguments may be specified in the following parameter ('`--quoting-style`') or by appending the option with a '`=`' and the value ('`--quoting-style=shell`'). GNU style long options may be abbreviated so long as the abbreviation is unique ('`--h`') is equivalent to '`--help`' if help is the only long option beginning with an 'h'). +- GNU style long options, like '`--colors`'. GNU style long options can be more than one character long, are preceded by two hyphens, and may not be grouped together. Option arguments may be specified in the following parameter ('`--quoting-style shell`') or by appending the option with a '`=`' and the value ('`--quoting-style=shell`'). GNU style long options may be abbreviated so long as the abbreviation is unique ('`--h`') is equivalent to '`--help`' if help is the only long option beginning with an 'h'). + +The options for specifying command name and command path may be used multiple times to define the same completions for multiple commands. + +The options for specifying command switches and wrapped commands may be used multiple times to define multiple completions for the command(s) in a single call. + +Invoking `complete` multiple times for the same command adds the new definitions on top of any existing completions defined for the command. + +When `-a` or `--arguments` is specified in conjunction with long, short, or old style options, the specified arguments are only used as completions when attempting to complete an argument for any of the specified options. If `-a` or `--arguments` is specified without any long, short, or old style options, the specified arguments are used when completing any argument to the command (except when completing an option argument that was specified with `-r` or `--require-parameter`). -The options for specifying command name, command path, or command switches may all be used multiple times to specify multiple commands which have the same completion or multiple switches accepted by a command. +Command substitutions found in `OPTION_ARGUMENTS` are not expected to return a space-separated list of arguments. Instead they must return a newline-separated list of arguments, and each argument may optionally have a tab character followed by the argument description. Any description provided in this way overrides a description given with `-d` or `--description`. -The `-w` or `--wraps` options causes the specified command to inherit completions from another command. The inheriting command is said to "wrap" the inherited command. The wrapping command may have its own completions in addition to inherited ones. A command may wrap multiple commands, and wrapping is transitive: if A wraps B, and B wraps C, then A automatically inherits all of C's completions. Wrapping can be removed using the `-e` or `--erase` options. +The `-w` or `--wraps` options causes the specified command to inherit completions from another command. The inheriting command is said to "wrap" the inherited command. The wrapping command may have its own completions in addition to inherited ones. A command may wrap multiple commands, and wrapping is transitive: if A wraps B, and B wraps C, then A automatically inherits all of C's completions. Wrapping can be removed using the `-e` or `--erase` options. Note that wrapping only works for completions specified with `-c` or `--command` and are ignored when specifying completions with `-p` or `--path`. -When erasing completions, it is possible to either erase all completions for a specific command by specifying `complete -e -c COMMAND`, or by specifying a specific completion option to delete by specifying either a long, short or old style option. +When erasing completions, it is possible to either erase all completions for a specific command by specifying `complete -c COMMAND -e`, or by specifying a specific completion option to delete by specifying either a long, short or old style option. \subsection complete-example Example @@ -99,7 +112,7 @@ This can be written as: complete -c rpm -n "__fish_contains_opt -s e erase" -l nodeps -d "Don't check dependencies" \endfish -where `__fish_contains_opt` is a function that checks the commandline buffer for the presence of a specified set of options. +where `__fish_contains_opt` is a function that checks the command line buffer for the presence of a specified set of options. To implement an alias, use the `-w` or `--wraps` option: diff --git a/doc_src/fish_vi_mode.txt b/doc_src/fish_vi_mode.txt index b2ea4583..3676dedd 100644 --- a/doc_src/fish_vi_mode.txt +++ b/doc_src/fish_vi_mode.txt @@ -1,4 +1,4 @@ -408-600-6421\section fish_vi_mode fish_vi_mode - Enable vi mode +\section fish_vi_mode fish_vi_mode - Enable vi mode \subsection fish_vi_mode-synopsis Synopsis \fish{synopsis} diff --git a/doc_src/index.hdr.in b/doc_src/index.hdr.in index 5eb92423..dd6355db 100644 --- a/doc_src/index.hdr.in +++ b/doc_src/index.hdr.in @@ -273,13 +273,13 @@ This is a short explanation of some of the commonly used words in fish. - <b>command</b> a program that the shell can run. -- <b>function</b> a block of commands that can be called as if they where a single command. By using functions, it is possible to string together multiple smaller commands into one more advanced command. +- <b>function</b> a block of commands that can be called as if they were a single command. By using functions, it is possible to string together multiple smaller commands into one more advanced command. - <b>job</b> a running pipeline or command - <b>pipeline</b> a set of commands stringed together so that the output of one command is the input of the next command -- <b>redirection</b> a operation that changes one of the input/output streams associated with a job +- <b>redirection</b> an operation that changes one of the input/output streams associated with a job - <b>switch</b> a special flag sent as an argument to a command that will alter the behavior of the command. A switch almost always begins with one or two hyphens. @@ -669,6 +669,8 @@ To see universal variables in action, start two fish sessions side by side, and <a href="#variables-universal">Universal variables</a> are stored in the file `.config/fish/fishd.MACHINE_ID`, where MACHINE_ID is typically your MAC address. Do not edit this file directly, as your edits may be overwritten. Edit them through fish scripts or by using fish interactively instead. +Do not append to universal variables in <a href="index.html#initialization">config.fish</a>, because these variables will then get longer with each new shell instance. Instead, simply set them once at the command line. + \subsection variables-functions Variable scope for functions diff --git a/doc_src/printf.txt b/doc_src/printf.txt index 81082a26..ce7796c8 100644 --- a/doc_src/printf.txt +++ b/doc_src/printf.txt @@ -60,7 +60,7 @@ This file has been imported from the printf in GNU Coreutils version 6.9. If you \subsection printf-example Example \fish -printf '%s\t%s\n' flounder fish +printf '\%s\\t\%s\n' flounder fish \endfish Will print "flounder fish" (separated with a tab character), followed by a newline character. This is useful for writing completions, as fish expects completion scripts to output the option followed by the description, separated with a tab character. diff --git a/doc_src/random.txt b/doc_src/random.txt index 5e50232a..5d8a8bab 100644 --- a/doc_src/random.txt +++ b/doc_src/random.txt @@ -7,9 +7,17 @@ random [SEED] \subsection random-description Description -`random` outputs a random number from 0 to 32766, inclusive. - -If a `SEED` value is provided, it is used to seed the random number generator, and no output will be produced. This can be useful for debugging purposes, where it can be desirable to get the same random number sequence multiple times. If the random number generator is called without first seeding it, the current time will be used as the seed. +`random` outputs a psuedo-random number from 0 to 32767, inclusive. +Even ignoring the very narrow range of values you should not assume +this produces truly random values within that range. Do not use the +value for any cryptographic purposes, and take care to handle collisions: +the same random number appearing more than once in a given fish instance. + +If a `SEED` value is provided, it is used to seed the random number +generator, and no output will be produced. This can be useful for debugging +purposes, where it can be desirable to get the same random number sequence +multiple times. If the random number generator is called without first +seeding it, the current time will be used as the seed. \subsection random-example Example diff --git a/doc_src/set_color.txt b/doc_src/set_color.txt index 98f4f8ed..087c9ac9 100644 --- a/doc_src/set_color.txt +++ b/doc_src/set_color.txt @@ -9,7 +9,7 @@ set_color [OPTIONS] [COLOR] `set_color` changes the foreground and/or background color of the terminal. `COLOR` is one of `black`, `red`, `green`, `brown`, `yellow`, `blue`, `magenta`, `purple`, `cyan`, `brred`, `brgreen`, `brbrown`, `bryellow`, `brblue`, `brmagenta`, `brpurple`, `brcyan`, `white`. The `br`, bright, forms are most useful as background colors. The special color `normal` resets the background and foreground to whatever is normal for your terminal. -If your terminal supports term256 (modern xterms and OS X Terminal and iTerm2), you can specify an RGB value with three or six hex digits, such as A0FF33 or f2f. `fish` will choose the closest supported color. A three digit value is equivalent to specifying each digit twice; e.g., `#2BC` is the same as `#22BBCC`. Hex RGB values can be in lower or uppercase, optionally prefixed with the pound-sign character. +You can also specify an RGB value with three or six hex digits, such as A0FF33 or f2f. `fish` will choose the closest supported color. A three digit value is equivalent to specifying each digit twice; e.g., `#2BC` is the same as `#22BBCC`. Hex RGB values can be in lower or uppercase, optionally prefixed with the pound-sign character. Depending on the capabilities of your terminal the actual color may be approximated by the closest known matching color in the [ANSI X3.64](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors) color palette. The following options are available: @@ -21,16 +21,15 @@ The following options are available: - `-u`, `--underline` sets underlined mode. - Calling `set_color normal` will set the terminal background and foreground colors to the defaults for the terminal. -Some terminals use the `--bold` escape sequence to switch to a brighter color set rather than bolding the characters. +Some terminals use the `--bold` escape sequence to switch to a brighter color set rather than bolding the characters. This only applies to the foreground color. You should probably use the `br` color name variants listed above for both the foreground and background "bright" colors rather than use this option. The only use for this option is on a black&white terminal (e.g., a DEC VT220) to select foreground black text that is bolder than the normal text. Not all terminal emulators support all these features. -`set_color` uses the terminfo database to look up how to change terminal colors on whatever terminal is in use. Some systems have old and incomplete terminfo databases, and may lack color information for terminals that support it. +Note 1: Setting either color to "normal" will reset both background and foreground colors to whatever is the default for the terminal. -Note that setting either color to "normal" will reset both background and foreground colors. +Note 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. \subsection set_color-example Examples @@ -40,3 +39,11 @@ set_color blue; echo "Violets are blue" set_color 62A; echo "Eggplants are dark purple" set_color normal; echo "Normal is nice" # This will reset background, too \endfish + +\subsection set_color-detection Terminal Capability Detection + +Fish uses a heuristic to decide if your terminal supports the 256 color palette (as opposed to the more limited 16 color palette of older terminals). If you've done the equivalent of `set fish_term256 1` that will be true. If the $TERM value contains "256color" (e.g., "xterm-256color") that will be true. If your $TERM value is "xterm" and $TERM_PROGRAM is not set to "Apple_Terminal" that will be true. If your terminal supports the full 256 color palette (which is pretty much every color terminal emulator written in the past decade) you should ensure one of the aforementioned conditions is true. + +Many terminals support 24-bit (i.e., true-color) color escape sequences. This includes modern xterms, Gnome Terminal, KDE Konsole, and OS X Terminal and iTerm2. Fish does not currently auto-detect whether a given `$TERM` supports 24-bit colors. You can explicitly enable that support via `set fish_term24bit 1`. If you do so fish will not map your RGB color values to the closest known matching color in the ANSI X3.64 color palette. + +The `set_color` command uses the terminfo database to look up how to change terminal colors on whatever terminal is in use. Some systems have old and incomplete terminfo databases, and may lack color information for terminals that support it. Fish will use the [ANSI X3.64](https://en.wikipedia.org/wiki/ANSI_escape_code) escape sequences if the terminfo definition says less than 256 colors are supported; otherwise it will use the terminfo definition. diff --git a/doc_src/string.txt b/doc_src/string.txt index c7781473..37d24435 100644 --- a/doc_src/string.txt +++ b/doc_src/string.txt @@ -110,7 +110,7 @@ string trim --right --chars=yz xyzzy zany \endfish \fish -echo \\x07 | string escape +echo \x07 | string escape # Output: # \\cg \endfish @@ -193,7 +193,7 @@ string replace -r '(\\w+)\\s+(\\w+)' '$2 $1 $$' 'left right' # Output: # right left $ -string replace -r '\s*newline\s*' '\n' 'put a newline here' +string replace -r '\\s*newline\\s*' '\n' 'put a newline here' # Output: # put a # here diff --git a/doc_src/tutorial.hdr b/doc_src/tutorial.hdr index 1b0e121a..f31ad5b8 100644 --- a/doc_src/tutorial.hdr +++ b/doc_src/tutorial.hdr @@ -534,7 +534,7 @@ To prepend to `$PATH`, you can write: >_ set PATH /new/path $PATH \endfish -You can do so directly in `fish.config`, like you might do in other shells with `.profile`. See [this example](#path_example). +You can do so directly in `config.fish`, like you might do in other shells with `.profile`. See [this example](#path_example). A faster way is to modify the `$fish_user_paths` [universal variable](#tut_universal), which is automatically prepended to `$PATH`. For example, to permanently add `/usr/local/bin` to your `$PATH`, you could write: @@ -542,7 +542,7 @@ A faster way is to modify the `$fish_user_paths` [universal variable](#tut_unive >_ set -U fish_user_paths /usr/local/bin $fish_user_paths \endfish -The advantage is that you don't have to go mucking around in files: just run this once at the command line, and it will affect the current session and all future instances too. (Note: you should NOT add this line to `fish.config`. If you do, the variable will get longer each time you run fish!) +The advantage is that you don't have to go mucking around in files: just run this once at the command line, and it will affect the current session and all future instances too. (Note: you should NOT add this line to `config.fish`. If you do, the variable will get longer each time you run fish!) \section tut_startup Startup (Where's .bashrc?) |