diff --git a/doc_src/alias.txt b/doc_src/alias.txt
index 079cabff2..028277a35 100644
--- a/doc_src/alias.txt
+++ b/doc_src/alias.txt
@@ -13,10 +13,12 @@ alias NAME=DEFINITION
`fish` does not keep track of which functions have been defined using `alias`. They must be erased using `functions -e`.
- `NAME` is the name of the alias
+
- `DEFINITION` is the actual command to execute. The string `$argv` will be appended.
You cannot create an alias to a function with the same name.
+
\subsection alias-example Example
The following code will create `rmi`, which runs `rm` with additional arguments on every invocation.
diff --git a/doc_src/and.txt b/doc_src/and.txt
index 9d71d67ce..0b4f681d1 100644
--- a/doc_src/and.txt
+++ b/doc_src/and.txt
@@ -7,21 +7,16 @@ COMMAND1; and COMMAND2
\subsection and-description Description
-`and` is used to execute a command if the current exit
-status (as set by the last previous command) is 0.
+`and` is used to execute a command if the current exit status (as set by the last previous command) is 0.
`and` does not change the current exit status.
-The exit status of the last foreground command to exit can always be
-accessed using the $status
-variable.
+The exit status of the last foreground command to exit can always be accessed using the $status variable.
+
\subsection and-example Example
-The following code runs the `make` command to build a program. If the
-build succeeds, `make`'s exit status is 0, and the program is installed. If either step fails,
-the exit status is 1, and `make clean` is run, which removes the files created by the.
-build process.
+The following code runs the `make` command to build a program. If the build succeeds, `make`'s exit status is 0, and the program is installed. If either step fails, the exit status is 1, and `make clean` is run, which removes the files created by the build process.
\fish
make; and make install; or make clean
diff --git a/doc_src/begin.txt b/doc_src/begin.txt
index 6807fac4e..6d18a6061 100644
--- a/doc_src/begin.txt
+++ b/doc_src/begin.txt
@@ -9,21 +9,16 @@ begin; [COMMANDS...;] end
`begin` is used to create a new block of code.
-The block is unconditionally executed. `begin; ...; end` is equivalent
-to `if true; ...; end`.
+The block is unconditionally executed. `begin; ...; end` is equivalent to `if true; ...; end`.
-`begin` is used to group a number of commands into a block.
-This allows the introduction of a new variable scope, redirection of the input or
-output of a set of commands as a group, or to specify precedence when
-using the conditional commands like `and`.
+`begin` is used to group a number of commands into a block. This allows the introduction of a new variable scope, redirection of the input or output of a set of commands as a group, or to specify precedence when using the conditional commands like `and`.
`begin` does not change the current exit status.
+
\subsection begin-example Example
-The following code sets a number of variables inside of a block
-scope. Since the variables are set inside the block and have local
-scope, they will be automatically deleted when the block ends.
+The following code sets a number of variables inside of a block scope. Since the variables are set inside the block and have local scope, they will be automatically deleted when the block ends.
\fish
begin
@@ -32,8 +27,8 @@ begin
end
echo $PIRATE
-# This will not output anything, since the PIRATE variable went out
-# of scope at the end of the block
+# This will not output anything, since the PIRATE variable
+# went out of scope at the end of the block
\endfish
In the following code, all output is redirected to the file out.html.
diff --git a/doc_src/bg.txt b/doc_src/bg.txt
index d05bf54d1..8e9ec2444 100644
--- a/doc_src/bg.txt
+++ b/doc_src/bg.txt
@@ -7,13 +7,11 @@ bg [PID...]
\subsection bg-description Description
-`bg` sends jobs to the background, resuming them if they are stopped. A background job is
-executed simultaneously with fish, and does not have access to the
-keyboard. If no job is specified, the last job to be used is put in the background. If PID is specified, the jobs with the specified process group IDs are put in the background.
+`bg` sends jobs to the background, resuming them if they are stopped. A background job is executed simultaneously with fish, and does not have access to the keyboard. If no job is specified, the last job to be used is put in the background. If PID is specified, the jobs with the specified process group IDs are put in the background.
The PID of the desired process is usually found by using process expansion.
+
\subsection bg-example Example
`bg %1` will put the job with job ID 1 in the background.
-
diff --git a/doc_src/bind.txt b/doc_src/bind.txt
index 9607c8b0c..59a8dec5d 100644
--- a/doc_src/bind.txt
+++ b/doc_src/bind.txt
@@ -10,82 +10,83 @@ bind [OPTIONS] SEQUENCE COMMAND
`bind` adds a binding for the specified key sequence to the
specified command.
-SEQUENCE is the character sequence to bind to. These should be written as fish escape sequences. For example, because
-pressing the Alt key and another character sends that character prefixed with
-an escape character, Alt-based key bindings can be written using the `\e`
-escape. For example, @key{Alt,w} can be written as `\ew`. The control
-character can be written in much the same way using the `\c` escape, for
-example @key{Control,X} (^X) can be written as `\cx`. Note
-that Alt-based key bindings are case sensitive and Control-based key bindings
-are not. This is a constraint of text-based terminals, not `fish`.
+SEQUENCE is the character sequence to bind to. These should be written as fish escape sequences. For example, because pressing the Alt key and another character sends that character prefixed with an escape character, Alt-based key bindings can be written using the `\e` escape. For example, @key{Alt,w} can be written as `\ew`. The control character can be written in much the same way using the `\c` escape, for example @key{Control,X} (^X) can be written as `\cx`. Note that Alt-based key bindings are case sensitive and Control-based key bindings are not. This is a constraint of text-based terminals, not `fish`.
-The default key binding can be set by specifying a `SEQUENCE` of the empty
-string (that is, ```''``` ). It will be used whenever no other binding
-matches. For most key bindings, it makes sense to use the `self-insert`
-function (i.e. ```bind '' self-insert```) as the default keybinding. This
-will insert any keystrokes not specifically bound to into the editor. Non-
-printable characters are ignored by the editor, so this will not result in
-control sequences being printable.
+The default key binding can be set by specifying a `SEQUENCE` of the empty string (that is, ```''``` ). It will be used whenever no other binding matches. For most key bindings, it makes sense to use the `self-insert` function (i.e. ```bind '' self-insert```) as the default keybinding. This will insert any keystrokes not specifically bound to into the editor. Non- printable characters are ignored by the editor, so this will not result in control sequences being printable.
-If the `-k` switch is used, the name of the key (such as 'down', 'up' or 'backspace')
-is used instead of a sequence. The names used are the same as the
-corresponding curses variables, but without the 'key_' prefix. (See
-`terminfo(5)` for more information, or use `bind --key-names` for a list of all
-available named keys.)
+If the `-k` switch is used, the name of the key (such as 'down', 'up' or 'backspace') is used instead of a sequence. The names used are the same as the corresponding curses variables, but without the 'key_' prefix. (See `terminfo(5)` for more information, or use `bind --key-names` for a list of all available named keys.)
-`COMMAND` can be any fish command, but it can also be one of a set of special
-input functions. These include functions for moving the cursor, operating on
-the kill-ring, performing tab completion, etc. Use `bind --function-names` for
-a complete list of these input functions.
+`COMMAND` can be any fish command, but it can also be one of a set of special input functions. These include functions for moving the cursor, operating on the kill-ring, performing tab completion, etc. Use `bind --function-names` for a complete list of these input functions.
-When `COMMAND` is a shellscript command, it is a good practice to put the actual
-code into a function and simply bind to the function
-name. This way it becomes significantly easier to test the function while
-editing, and the result is usually more readable as well.
+When `COMMAND` is a shellscript command, it is a good practice to put the actual code into a function and simply bind to the function name. This way it becomes significantly easier to test the function while editing, and the result is usually more readable as well.
-If such a script produces output, the script needs to finish by calling
-`commandline -f repaint` in order to tell fish that a repaint is in order.
+If such a script produces output, the script needs to finish by calling `commandline -f repaint` in order to tell fish that a repaint is in order.
-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. To save custom keybindings, edit the `fish_user_key_bindings` function and insert the appropriate `bind` statements.
The following parameters are available:
- `-k` or `--key` Specify a key name, such as 'left' or 'backspace' instead of a character sequence
+
- `-K` or `--key-names` Display a list of available key names
+
- `-f` or `--function-names` Display a list of available input functions
The following special input functions are available:
- `backward-char`, moves one character to the left
+
- `backward-delete-char`, deletes one character of input to the left of the cursor
+
- `backward-kill-line`, move everything from the beginning of the line to the cursor to the killring
+
- `backward-kill-word`, move the word to the left of the cursor to the killring
+
- `backward-word`, move one word to the left
+
- `beginning-of-history`, move to the beginning of the history
+
- `beginning-of-line`, move to the beginning of the line
+
- `capitalize-word`, make the current word begin with a capital letter
+
- `complete`, guess the remainder of the current token
+
- `delete-char`, delete one character to the right of the cursor
+
- `delete-line`, delete the entire line
+
- `downcase-word`, make the current word lowercase
+
- `dump-functions`, print a list of all key-bindings
+
- `end-of-history`, move to the end of the history
+
- `end-of-line`, move to the end of the line
+
- `explain`, print a description of possible problems with the current command
+
- `forward-char`, move one character to the right
+
- `forward-word`, move one word to the right
+
- `history-search-backward`, search the history for the previous match
+
- `history-search-forward`, search the history for the next match
+
- `kill-line`, move everything from the cursor to the end of the line to the killring
+
- `kill-whole-line`, move the line to the killring
+
- `kill-word`, move the next word to the killring
+
- `upcase-word`, make the current word uppercase
+
- `yank`, insert the latest entry of the killring into the buffer
+
- `yank-pop`, rotate to the previous entry of the killring
+
\subsection bind-example Examples
`bind \cd 'exit'` causes `fish` to exit when @key{Control,D} is pressed.
diff --git a/doc_src/block.txt b/doc_src/block.txt
index f3f741f12..37b2de0c6 100644
--- a/doc_src/block.txt
+++ b/doc_src/block.txt
@@ -7,26 +7,23 @@ block [OPTIONS...]
\subsection block-description Description
-`block` prevents events triggered by `fish` or the
-`emit` command from
-being delivered and acted upon while the block is in place.
+`block` prevents events triggered by `fish` or the `emit` command from being delivered and acted upon while the block is in place.
-In functions, `block` can be useful while performing work that
-should not be interrupted by the shell.
+In functions, `block` can be useful while performing work that should not be interrupted by the shell.
-The block can be removed. Any events which triggered while the
-block was in place will then be delivered.
+The block can be removed. Any events which triggered while the block was in place will then be delivered.
-Event blocks should not be confused with code blocks, which are created
-with `begin`, `if`, `while` or
-`for`
+Event blocks should not be confused with code blocks, which are created with `begin`, `if`, `while` or `for`
The following parameters are available:
- `-l` or `--local` Release the block automatically at the end of the current innermost code block scope
+
- `-g` or `--global` Never automatically release the lock
+
- `-e` or `--erase` Release global block
+
\subsection block-example Example
\fish
diff --git a/doc_src/break.txt b/doc_src/break.txt
index 2056b054a..32672c09f 100644
--- a/doc_src/break.txt
+++ b/doc_src/break.txt
@@ -5,13 +5,13 @@
LOOP_CONSTRUCT; [COMMANDS...] break; [COMMANDS...] end
\endfish
-
\subsection break-description Description
`break` halts a currently running loop, such as a for loop or a while loop. It is usually added inside of a conditional block such as an if statement or a switch statement.
There are no parameters for `break`.
+
\subsection break-example Example
The following code searches all .c files for "smurf", and halts at the first occurrence.
diff --git a/doc_src/breakpoint.txt b/doc_src/breakpoint.txt
index 348c779d9..8645c18dd 100644
--- a/doc_src/breakpoint.txt
+++ b/doc_src/breakpoint.txt
@@ -7,10 +7,8 @@ breakpoint
\subsection breakpoint-description Description
-`breakpoint` is used to halt a running script and launch
-an interactive debugging prompt.
+`breakpoint` is used to halt a running script and launch an interactive debugging prompt.
-For more details, see Debugging fish
-scripts in the `fish` manual.
+For more details, see Debugging fish scripts in the `fish` manual.
There are no parameters for `breakpoint`.
diff --git a/doc_src/builtin.txt b/doc_src/builtin.txt
index 2d915fc34..4c465ef18 100644
--- a/doc_src/builtin.txt
+++ b/doc_src/builtin.txt
@@ -13,6 +13,10 @@ The following parameters are available:
- `-n` or `--names` List the names of all defined builtins
+
\subsection builtin-example Example
-`builtin jobs` executes the jobs builtin, even if a function named jobs exists.
+\fish
+builtin jobs
+# executes the jobs builtin, even if a function named jobs exists
+\endfish
diff --git a/doc_src/case.txt b/doc_src/case.txt
index b05006502..24fde2803 100644
--- a/doc_src/case.txt
+++ b/doc_src/case.txt
@@ -7,24 +7,14 @@ switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
\subsection case-description Description
-`switch` performs one of several blocks of commands, depending on whether
-a specified value equals one of several wildcarded values. `case` is used
-together with the `switch` statement in order to determine which block should
-be executed.
+`switch` performs one of several blocks of commands, depending on whether a specified value equals one of several wildcarded values. `case` is used together with the `switch` statement in order to determine which block should be executed.
-Each `case` command is given one or more parameters. The first `case`
-command with a parameter that matches the string specified in the
-switch command will be evaluated. `case` parameters may contain
-wildcards. These need to be escaped or quoted in order to avoid
-regular wildcard expansion using filenames.
+Each `case` command is given one or more parameters. The first `case` command with a parameter that matches the string specified in the switch command will be evaluated. `case` parameters may contain wildcards. These need to be escaped or quoted in order to avoid regular wildcard expansion using filenames.
-Note that fish does not fall through on case statements. Only the
-first matching case is executed.
+Note that fish does not fall through on case statements. Only the first matching case is executed.
+
+Note that command substitutions in a case statement will be evaluated even if its body is not taken. All substitutions, including command substitutions, must be performed before the value can be compared against the parameter.
-Note that command substitutions in a case statement will be
-evaluated even if its body is not taken. All substitutions, including
-command substitutions, must be performed before the value can be compared
-against the parameter.
\subsection case-example Example
diff --git a/doc_src/cd.txt b/doc_src/cd.txt
index 200d97675..bb4dc488c 100644
--- a/doc_src/cd.txt
+++ b/doc_src/cd.txt
@@ -8,20 +8,19 @@ cd [DIRECTORY]
\subsection cd-description Description
`cd` changes the current working directory.
-If `DIRECTORY` is supplied, it will become the new directory. If no parameter
-is given, the contents of the `HOME` environment variable will be used.
+If `DIRECTORY` is supplied, it will become the new directory. If no parameter is given, the contents of the `HOME` environment variable will be used.
-If `DIRECTORY` is a relative path, the paths found in the
-`CDPATH` environment variable array will be tried as prefixes for the specified
-path.
+If `DIRECTORY` is a relative path, the paths found in the `CDPATH` environment variable array will be tried as prefixes for the specified path.
+
+Note that the shell will attempt to change directory without requiring `cd` if the name of a directory is provided (starting with `.`, `/` or `~`, or ending with `/`).
-Note that the shell will attempt to change directory without requiring `cd`
-if the name of a directory is provided (starting with '`.`', '`/`' or `~`', or ending
-with '`/`').
\subsection cd-example Examples
-`cd` changes the working directory to your home directory.
+\fish
+cd
+# changes the working directory to your home directory.
-`cd /usr/src/fish-shell` changes the working directory to
-`/usr/src/fish-shell`.
+cd /usr/src/fish-shell
+# changes the working directory to /usr/src/fish-shell
+\endfish
diff --git a/doc_src/command.txt b/doc_src/command.txt
index fd2cd98d2..7d286974f 100644
--- a/doc_src/command.txt
+++ b/doc_src/command.txt
@@ -9,6 +9,7 @@ command COMMANDNAME [OPTIONS...]
`command` forces the shell to execute the program `COMMANDNAME` and ignore any functions or builtins with the same name.
+
\subsection command-example Example
`command ls` causes fish to execute the `ls` program, even if an 'ls' function exists.
diff --git a/doc_src/commandline.txt b/doc_src/commandline.txt
index b3eaba5ad..347f48700 100644
--- a/doc_src/commandline.txt
+++ b/doc_src/commandline.txt
@@ -7,69 +7,53 @@ commandline [OPTIONS] [CMD]
\subsection commandline-description Description
-`commandline` can be used to set or get the current contents of the command
-line buffer.
+`commandline` can be used to set or get the current contents of the command line buffer.
-With no parameters, `commandline` returns the current value of the command
-line.
+With no parameters, `commandline` returns the current value of the command line.
-With `CMD` specified, the command line buffer is erased and replaced with
-the contents of `CMD`.
+With `CMD` specified, the command line buffer is erased and replaced with the contents of `CMD`.
The following options are available:
-- `-C` or `--cursor` set or get the current cursor position, not
- the contents of the buffer. If no argument is given, the current
- cursor position is printed, otherwise the argument is interpreted
- as the new cursor position.
-- `-f` or `--function` inject readline functions into the
- reader. This option cannot be combined with any other option. It
- will cause any additional arguments to be interpreted as readline
- functions, and these functions will be injected into the reader, so
- that they will be returned to the reader before any additional
- actual key presses are read.
+- `-C` or `--cursor` set or get the current cursor position, not the contents of the buffer. If no argument is given, the current cursor position is printed, otherwise the argument is interpreted as the new cursor position.
-The following options change the way `commandline` updates the
-command line buffer:
+- `-f` or `--function` inject readline functions into the reader. This option cannot be combined with any other option. It will cause any additional arguments to be interpreted as readline functions, and these functions will be injected into the reader, so that they will be returned to the reader before any additional actual key presses are read.
-- `-a` or `--append` do not remove the current commandline, append
- the specified string at the end of it
-- `-i` or `--insert` do not remove the current commandline, insert
- the specified string at the current cursor position
-- `-r` or `--replace` remove the current commandline and replace it
- with the specified string (default)
+The following options change the way `commandline` updates the command line buffer:
-The following options change what part of the commandline is printed
-or updated:
+- `-a` or `--append` do not remove the current commandline, append the specified string at the end of it
+
+- `-i` or `--insert` do not remove the current commandline, insert the specified string at the current cursor position
+
+- `-r` or `--replace` remove the current commandline and replace it with the specified string (default)
+
+The following options change what part of the commandline is printed or updated:
- `-b` or `--current-buffer` select the entire buffer (default)
+
- `-j` or `--current-job` select the current job
+
- `-p` or `--current-process` select the current process
+
- `-t` or `--current-token` select the current token.
-The following options change the way `commandline` prints the current
-commandline buffer:
+The following options change the way `commandline` prints the current commandline buffer:
+
+- `-c` or `--cut-at-cursor` only print selection up until the current cursor position
-- `-c` or `--cut-at-cursor` only print selection up until the
- current cursor position
- `-o` or `--tokenize` tokenize the selection and print one string-type token per line
-
-If `commandline` is called during a call to complete a given string
-using `complete -C STRING`, `commandline` will consider the
-specified string to be the current contents of the command line.
+If `commandline` is called during a call to complete a given string using `complete -C STRING`, `commandline` will consider the specified string to be the current contents of the command line.
The following options output metadata about the commandline state:
-- `-L` or `--line` print the line that the cursor is on, with the topmost
-line starting at 1
-- `-S` or `--search-mode` evaluates to true if the commandline is performing
-a history search
-- `-P` or `--paging-mode` evaluates to true if the commandline is showing
-pager contents, such as tab completions
+- `-L` or `--line` print the line that the cursor is on, with the topmost line starting at 1
+
+- `-S` or `--search-mode` evaluates to true if the commandline is performing a history search
+
+- `-P` or `--paging-mode` evaluates to true if the commandline is showing pager contents, such as tab completions
\subsection commandline-example Example
-`commandline -j $history[3]` replaces the job under the cursor with the
-third item from the command line history.
+`commandline -j $history[3]` replaces the job under the cursor with the third item from the command line history.
diff --git a/doc_src/complete.txt b/doc_src/complete.txt
index 501eac86d..4f17e216a 100644
--- a/doc_src/complete.txt
+++ b/doc_src/complete.txt
@@ -6,99 +6,88 @@ complete (-c | --command | -p | --path) COMMAND
[(-s | --short-option) SHORT_OPTION]
[(-l | --long-option | -o | --old-option) LONG_OPTION]
[(-a | --arguments) OPTION_ARGUMENTS]
- [(-w | --wraps) WRAPPED_COMMAND]
+ [(-w | --wraps) WRAPPED_COMMAND]
[(-d | --description) DESCRIPTION]
\endfish
-
\subsection complete-description Description
For an introduction to specifying completions, see Writing your own completions in
the fish manual.
-<<<<<<< HEAD
- `COMMAND` is the name of the command for which to add a completion.
+
- `SHORT_OPTION` is a one character option for the command.
+
- `LONG_OPTION` is a multi character option for the command.
+
- `OPTION_ARGUMENTS` is parameter containing a space-separated list of possible option-arguments, which may contain subshells.
+
- `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.
+
- `-w WRAPPED_COMMAND` or `--wraps=WRAPPED_COMMAND` causes the specified command to inherit completions from the wrapped command.
+
- `-e` or `--erase` implies that the specified completion should be deleted.
+
- `-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.
+
- `-o` or `--old-option` implies that the command uses old long style options with only one dash.
+
- `-p` or `--path` implies that the string `COMMAND` is the full path of the command.
+
- `-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.
+
- `-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.
+
- `-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.
+
- `-x` or `--exclusive` implies both `-r` and `-f`.
-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:
+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').
-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.
+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.
-The \c -w or \c --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 \c -e or \c --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.
+
+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 -e -c
-COMMAND`, or by specifying a specific completion option to delete
-by specifying either a long, short or old style option.
\subsection complete-example Example
-The short style option `-o` for the `gcc` command requires
-that a file follows it. This can be done using writing:
+The short style option `-o` for the `gcc` command requires that a file follows it. This can be done using writing:
`complete -c gcc -s o -r`
-The short style option `-d` for the `grep` command requires
-that one of the strings '`read`', '`skip`' or '`recurse`' is used. This can
-be specified writing:
+The short style option `-d` for the `grep` command requires that one of the strings '`read`', '`skip`' or '`recurse`' is used. This can be specified writing:
`complete -c grep -s d -x -a "read skip recurse"`
-The `su` command takes any username as an argument. Usernames are
-given as the first colon-separated field in the file /etc/passwd. This
-can be specified as:
+The `su` command takes any username as an argument. Usernames are given as the first colon-separated field in the file /etc/passwd. This can be specified as:
-`complete -x -c su -d "Username" `
-`-a "(cat /etc/passwd | cut -d : -f 1)"`
+`complete -x -c su -d "Username" -a "(cat /etc/passwd | cut -d : -f 1)"`
-The `rpm` command has several different modes. If the `-e` or `--erase` flag has been specified, `rpm` should delete one or more
-packages, in which case several switches related to deleting packages are valid, like the `nodeps` switch.
+The `rpm` command has several different modes. If the `-e` or `--erase` flag has been specified, `rpm` should delete one or more packages, in which case several switches related to deleting packages are valid, like the `nodeps` switch.
This can be written as:
-`complete -c rpm -n "__fish_contains_opt -s e erase"`
-`-l nodeps -d "Don't check dependencies"`
+`complete -c rpm -n "__fish_contains_opt -s e erase" -l nodeps -d "Don't check dependencies"`
-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 commandline buffer for the presence of a specified set of options.
To implement an alias, use the `-w` or `--wraps` option:
`complete -c hub -w git`
-Now hub inherits all of the completions from git. Note this can
-also be specified in a function declaration.
+Now hub inherits all of the completions from git. Note this can also be specified in a function declaration.
diff --git a/doc_src/contains.txt b/doc_src/contains.txt
index 2ec6e0920..4c947c9df 100644
--- a/doc_src/contains.txt
+++ b/doc_src/contains.txt
@@ -7,15 +7,14 @@ contains [OPTIONS] KEY [VALUES...]
\subsection contains-description Description
-`contains` tests whether the set `VALUES` contains the string
-`KEY`. If so, `contains` exits with status 0; if not, it exits
-with status 1.
+`contains` tests whether the set `VALUES` contains the string `KEY`. If so, `contains` exits with status 0; if not, it exits with status 1.
The following options are available:
- `-i` or `--index` print the word index
- `-h` or `--help` display this message
+
\subsection contains-example Example
\fish
diff --git a/doc_src/continue.txt b/doc_src/continue.txt
index cb92c9cf3..1585b04a8 100644
--- a/doc_src/continue.txt
+++ b/doc_src/continue.txt
@@ -6,9 +6,11 @@ LOOP_CONSTRUCT; [COMMANDS...;] continue; [COMMANDS...;] end
\endfish
\subsection continue-description Description
+
`continue` skips the remainder of the current iteration of the current inner loop, such as a for loop or a while loop. It is usually added inside of a conditional block such as an if statement or a switch statement.
\subsection continue-example Example
+
The following code removes all tmp files that do not contain the word smurf.
\fish
diff --git a/doc_src/count.txt b/doc_src/count.txt
index bf66d2071..4587209fd 100644
--- a/doc_src/count.txt
+++ b/doc_src/count.txt
@@ -7,25 +7,21 @@ count $VARIABLE
\subsection count-description Description
-`count` prints the number of arguments that were
-passed to it. This is usually used to find out how many elements an
-environment variable array contains.
+`count` prints the number of arguments that were passed to it. This is usually used to find out how many elements an environment variable array contains.
`count` does not accept any options, including '`-h`'.
-`count` exits with a non-zero exit status if no arguments were passed
-to it, and with zero if at least one argument was passed.
+`count` exits with a non-zero exit status if no arguments were passed to it, and with zero if at least one argument was passed.
+
\subsection count-example Example
-
+\fish
count $PATH
-
-returns the number of directories in the users PATH variable.
+# Returns the number of directories in the users PATH variable.
-
count *.txt
-
-returns the number of files in the current working directory ending with the suffix '.txt'.
+# Returns the number of files in the current working directory ending with the suffix '.txt'.
+\endfish
\ No newline at end of file
diff --git a/doc_src/design.hdr b/doc_src/design.hdr
index e7d09d4c2..c8f880652 100644
--- a/doc_src/design.hdr
+++ b/doc_src/design.hdr
@@ -8,135 +8,101 @@
\section design-overview Overview
-This is a description of the design principles that have been used to
-design fish. The fish design has three high level goals. These are:
+This is a description of the design principles that have been used to design fish. The fish design has three high level goals. These are:
--# Everything that can be done in other shell languages should be
-possible to do in fish, though fish may rely on external commands in
-doing so.
--# Fish should be user friendly, but not at the expense of expressiveness.
-Most tradeoffs between power and ease of use can be avoided with careful design.
--# Whenever possible without breaking the above goals, fish should
-follow the Posix syntax.
+-# Everything that can be done in other shell languages should be possible to do in fish, though fish may rely on external commands in doing so.
+
+-# Fish should be user friendly, but not at the expense of expressiveness. Most tradeoffs between power and ease of use can be avoided with careful design.
+
+-# Whenever possible without breaking the above goals, fish should follow the Posix syntax.
+
+To achieve these high-level goals, the fish design relies on a number of more specific design principles. These are presented below, together with a rationale and a few examples for each.
-To achieve these high-level goals, the fish design relies on a number
-of more specific design principles. These are presented below,
-together with a rationale and a few examples for each.
\section ortho The law of orthogonality
-The shell language should have a small set of orthogonal features. Any
-situation where two features are related but not identical, one of them
-should be removed, and the other should be made powerful and general
-enough to handle all common use cases of either feature.
+The shell language should have a small set of orthogonal features. Any situation where two features are related but not identical, one of them should be removed, and the other should be made powerful and general enough to handle all common use cases of either feature.
Rationale:
-
-Related features make the language larger, which makes it harder to
-learn. It also increases the size of the sourcecode, making the
-program harder to maintain and update.
+Related features make the language larger, which makes it harder to learn. It also increases the size of the sourcecode, making the program harder to maintain and update.
Examples:
- Here documents are too similar to using echo inside of a pipeline.
+
- Subshells, command substitution and process substitution are strongly related. `fish` only supports command substitution, the others can be achieved either using a block or the psub shellscript function.
+
- Having both aliases and functions is confusing, especially since both of them have limitations and problems. `fish` functions have none of the drawbacks of either syntax.
+
- The many Posix quoting styles are silly, especially $''.
-\section sep The law of responsiveness
+
+\section design-response The law of responsiveness
The shell should attempt to remain responsive to the user at all times, even in the face of contended or unresponsive filesystems. It is only acceptable to block in response to a user initiated action, such as running a command.
Rationale:
-
Bad performance increases user-facing complexity, because it trains users to recognize and route around slow use cases. It is also incredibly frustrating.
Examples:
- Features like syntax highlighting and autosuggestions must perform all of their disk I/O asynchronously.
+
- Startup should minimize forks and disk I/O, so that fish can be started even if the system is under load.
-\section conf Configurability is the root of all evil
+\section design-configurability Configurability is the root of all evil
-Every configuration option in a program is a place where the program
-is too stupid to figure out for itself what the user really wants, and
-should be considered a failiure of both the program and the programmer
-who implemented it.
+Every configuration option in a program is a place where the program is too stupid to figure out for itself what the user really wants, and should be considered a failiure of both the program and the programmer who implemented it.
Rationale:
-
-Different configuration options are a nightmare to maintain, since the
-number of potential bugs caused by specific configuration combinations
-quickly becomes an issue. Configuration options often imply
-assumptions about the code which change when reimplementing the code,
-causing issues with backwards compatibility. But mostly, configuration
-options should be avoided since they simply should not exist, as the
-program should be smart enough to do what is best, or at least a good
-enough approximation of it.
+Different configuration options are a nightmare to maintain, since the number of potential bugs caused by specific configuration combinations quickly becomes an issue. Configuration options often imply assumptions about the code which change when reimplementing the code, causing issues with backwards compatibility. But mostly, configuration options should be avoided since they simply should not exist, as the program should be smart enough to do what is best, or at least a good enough approximation of it.
Examples:
- Fish allows the user to set various syntax highlighting colors. This is needed because fish does not know what colors the terminal uses by default, which might make some things unreadable. The proper solution would be for text color preferences to be defined centrally by the user for all programs, and for the terminal emulator to send these color properties to fish.
+
- Fish does not allow you to set the history filename, the number of history entries, different language substyles or any number of other common shell configuration options.
-A special note on the evils of configurability is the long list of
-very useful features found in some shells, that are not turned on by
-default. Both zsh and bash support command specific completions, but
-no such completions are shipped with bash by default, and they are
-turned off by default in zsh. Other features that zsh support that are
-disabled by default include tab-completion of strings containing
-wildcards, a sane completion pager and a history file.
+A special note on the evils of configurability is the long list of very useful features found in some shells, that are not turned on by default. Both zsh and bash support command specific completions, but no such completions are shipped with bash by default, and they are turned off by default in zsh. Other features that zsh support that are disabled by default include tab-completion of strings containing wildcards, a sane completion pager and a history file.
+
\section user The law of user focus
-When designing a program, one should first think about how to make a
-intuitive and powerful program. Implementation issues should only be
-considered once a user interface has been designed.
+When designing a program, one should first think about how to make a intuitive and powerful program. Implementation issues should only be considered once a user interface has been designed.
Rationale:
-
-This design rule is different than the others, since it describes how
-one should go about designing new features, not what the features
-should be. The problem with focusing on what can be done, and what is
-easy to do, is that to much of the implementation is exposed. This
-means that the user must know a great deal about the underlying system
-to be able to guess how the shell works, it also means that the
-language will often be rather low-level.
+This design rule is different than the others, since it describes how one should go about designing new features, not what the features should be. The problem with focusing on what can be done, and what is easy to do, is that to much of the implementation is exposed. This means that the user must know a great deal about the underlying system to be able to guess how the shell works, it also means that the language will often be rather low-level.
Examples:
-
- There should only be one type of input to the shell, lists of commands. Loops, conditionals and variable assignments are all performed through regular commands.
+
- The differences between builtin commands and shellscript functions should be made as small as possible. Builtins and shellscript functions should have exactly the same types of argument expansion as other commands, should be possible to use in any position in a pipeline, and should support any io redirection.
+
- Instead of forking when performing command substitution to provide a fake variable scope, all fish commands are performed from the same process, and fish instead supports true scoping.
+
- All blocks end with the `end` builtin.
+
\section disc The law of discoverability
-A program should be designed to make its features as
-easy as possible to discover for the user.
+A program should be designed to make its features as easy as possible to discover for the user.
Rationale:
+A program whose features are discoverable turns a new user into an expert in a shorter span of time, since the user will become an expert on the program simply by using it.
-A program whose features are discoverable turns a new user into an
-expert in a shorter span of time, since the user will become an expert
-on the program simply by using it.
-
-The main benefit of a graphical program over a command line-based
-program is discoverability. In a graphical program, one can discover
-all the common features by simply looking at the user interface and
-guessing what the different buttons, menus and other widgets do. The
-traditional way to discover features in commandline programs is
-through manual pages. This requires both that the user starts to use a
-different program, and the she/he then remembers the new information
-until the next time she/he uses the same program.
+The main benefit of a graphical program over a command line-based program is discoverability. In a graphical program, one can discover all the common features by simply looking at the user interface and guessing what the different buttons, menus and other widgets do. The traditional way to discover features in commandline programs is through manual pages. This requires both that the user starts to use a different program, and the she/he then remembers the new information until the next time she/he uses the same program.
Examples:
-
- Everything should be tab-completable, and every tab completion should have a description.
+
- Every syntax error and error in a builtin command should contain an error message describing what went wrong and a relevant help page. Whenever possible, errors should be flagged red by the syntax highlighter.
+
- The help manual should be easy to read, easily available from the shell, complete and contain many examples
+
- The language should be uniform, so that once the user understands the command/argument syntax, he will know the whole language, and be able to use tab-completion to discover new featues.
+
+
\htmlonly[block]
diff --git a/doc_src/dirh.txt b/doc_src/dirh.txt
index 00bd581fc..d25b9c2ad 100644
--- a/doc_src/dirh.txt
+++ b/doc_src/dirh.txt
@@ -7,8 +7,6 @@ dirh
\subsection dirh-description Description
-`dirh` prints the current directory history. The current position in the
-history is highlighted using the color defined in the
-`fish_color_history_current` environment variable.
+`dirh` prints the current directory history. The current position in the history is highlighted using the color defined in the `fish_color_history_current` environment variable.
`dirh` does not accept any parameters.
diff --git a/doc_src/dirs.txt b/doc_src/dirs.txt
index c15834c57..231b678b9 100644
--- a/doc_src/dirs.txt
+++ b/doc_src/dirs.txt
@@ -6,7 +6,7 @@ dirs
\endfish
\subsection dirs-description Description
-`dirs` prints the current directory stack, as created by the
-`pushd` command.
+
+`dirs` prints the current directory stack, as created by the `pushd` command.
`dirs` does not accept any parameters.
diff --git a/doc_src/echo.txt b/doc_src/echo.txt
index 7b9b03182..d70627161 100644
--- a/doc_src/echo.txt
+++ b/doc_src/echo.txt
@@ -12,9 +12,13 @@ echo [OPTIONS] [STRING]
The following options are available:
- `-n`, Do not output a newline
+
- `-s`, Do not separate arguments with spaces
+
- `-E`, Disable interpretation of backslash escapes (default)
+
- `-e`, Enable interpretation of backslash escapes
+
- `-h`, `--help` Display this help
\subsection echo-escapes Escape Sequences
@@ -22,20 +26,35 @@ The following options are available:
If `-e` is used, the following sequences are recognized:
- `\` backslash
+
- `\a` alert (BEL)
+
- `\b` backspace
+
- `\c` produce no further output
+
- `\e` escape
+
- `\f` form feed
+
- `\n` new line
+
- `\r` carriage return
+
- `\t` horizontal tab
+
- `\v` vertical tab
+
- `\0NNN` byte with octal value NNN (1 to 3 digits)
+
- `\xHH` byte with hexadecimal value HH (1 to 2 digits)
\subsection echo-example Example
-`echo 'Hello World'` Print hello world to stdout
+\fish
+echo 'Hello World'
+# Print hello world to stdout
-`echo -e 'Top\nBottom'` Print Top and Bottom on separate lines, using an escape sequence
+echo -e 'Top\nBottom'
+# Print Top and Bottom on separate lines, using an escape sequence
+\endfish
diff --git a/doc_src/else.txt b/doc_src/else.txt
index a22cfcdb9..76e0c61f3 100644
--- a/doc_src/else.txt
+++ b/doc_src/else.txt
@@ -6,13 +6,13 @@ if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end
\endfish
\subsection else-description Description
-`if` will execute the command `CONDITION`. If the condition's exit
-status is 0, the commands `COMMANDS_TRUE` will execute. If it is not 0 and
-`else` is given, `COMMANDS_FALSE` will be executed.
+
+`if` will execute the command `CONDITION`. If the condition's exit status is 0, the commands `COMMANDS_TRUE` will execute. If it is not 0 and `else` is given, `COMMANDS_FALSE` will be executed.
+
\subsection else-example Example
-The following code tests whether a file `foo`.txt exists as a regular file.
+The following code tests whether a file `foo.txt` exists as a regular file.
\fish
if test -f foo.txt
diff --git a/doc_src/emit.txt b/doc_src/emit.txt
index d8f17b45e..df154c5df 100644
--- a/doc_src/emit.txt
+++ b/doc_src/emit.txt
@@ -9,10 +9,10 @@ emit EVENT_NAME [ARGUMENTS...]
`emit` emits, or fires, an event. Events are delivered to, or caught by, special functions called event handlers. The arguments are passed to the event handlers as function arguments.
+
\subsection emit-example Example
-The following code first defines an event handler for the generic
-event named 'test_event', and then emits an event of that type.
+The following code first defines an event handler for the generic event named 'test_event', and then emits an event of that type.
\fish
function event_test --on-event test_event
diff --git a/doc_src/end.txt b/doc_src/end.txt
index aca294955..76cbe3603 100644
--- a/doc_src/end.txt
+++ b/doc_src/end.txt
@@ -10,10 +10,10 @@ switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
\endfish
\subsection end-description Description
+
`end` ends a block of commands.
For more information, read the
-documentation for the block constructs, such as \c if, \c for and \c
-while.
+documentation for the block constructs, such as `if`, `for` and `while`.
-The \c end command does not change the current exit status.
+The `end` command does not change the current exit status.
diff --git a/doc_src/eval.txt b/doc_src/eval.txt
index c966b5761..1ba8f97ee 100644
--- a/doc_src/eval.txt
+++ b/doc_src/eval.txt
@@ -8,11 +8,10 @@ eval [COMMANDS...]
\subsection eval-description Description
`eval` evaluates the specified parameters as a command. If more than one parameter is specified, all parameters will be joined using a space character as a separator.
+
\subsection eval-example Example
-The following code will call the ls command. Note that \c fish does not
-support the use of shell variables as direct commands; \c eval can
-be used to work around this.
+The following code will call the ls command. Note that `fish` does not support the use of shell variables as direct commands; `eval` can be used to work around this.
\fish
set cmd ls
diff --git a/doc_src/exec.txt b/doc_src/exec.txt
index 4bcd39996..f8936101a 100644
--- a/doc_src/exec.txt
+++ b/doc_src/exec.txt
@@ -7,11 +7,9 @@ exec COMMAND [OPTIONS...]
\subsection exec-description Description
-`exec` replaces the currently running shell with a new command.
-On successful completion, `exec` never returns. `exec` cannot be used
-inside a pipeline.
+`exec` replaces the currently running shell with a new command. On successful completion, `exec` never returns. `exec` cannot be used inside a pipeline.
+
\subsection exec-example Example
-`exec emacs` starts up the emacs text editor, and exits `fish`.
-When emacs exits, the session will terminate.
+`exec emacs` starts up the emacs text editor, and exits `fish`. When emacs exits, the session will terminate.
diff --git a/doc_src/exit.txt b/doc_src/exit.txt
index fcec4b923..5b43b612a 100644
--- a/doc_src/exit.txt
+++ b/doc_src/exit.txt
@@ -7,10 +7,6 @@ exit [STATUS]
\subsection exit-description Description
-`exit` causes fish to exit. If `STATUS` is
-supplied, it will be converted to an integer and used as the exit
-code. Otherwise, the exit code will be that of the last command executed.
+`exit` causes fish to exit. If `STATUS` is supplied, it will be converted to an integer and used as the exit code. Otherwise, the exit code will be that of the last command executed.
-If exit is called while sourcing a file (using the . builtin) the rest of the file will be skipped,
-but the shell itself will not exit.
+If exit is called while sourcing a file (using the . builtin) the rest of the file will be skipped, but the shell itself will not exit.
diff --git a/doc_src/faq.hdr b/doc_src/faq.hdr
index 6d3ead30a..99c2ada49 100644
--- a/doc_src/faq.hdr
+++ b/doc_src/faq.hdr
@@ -7,21 +7,37 @@
\endhtmlonly
- How do I set or clear an environment variable?
+
- How do I run a command every login? What's fish's equivalent to `.bashrc`?
+
- How do I set my prompt?
+
- How do I run a command from history?
+
- How do I run a subcommand? The backtick doesn't work!
+
- How do I get the exit status of a command?
+
- How do I set an environment variable for just one command?
+
- How do I customize my syntax highlighting colors?
+
- How do I update man page completions?
+
- Why does cd, pwd and other fish commands always resolve symlinked directories to their canonical path?
+
- I accidentally entered a directory path and fish changed directory. What happened?
+
- The open command doesn't work.
+
- How do I make fish my default shell?
+
- I'm seeing weird output before each prompt when using screen. What's wrong?
+
- How do I change the greeting message?
+
- Why doesn't history substitution ("!$" etc.) work?
+
- How do I uninstall fish?
\htmlonly[block]
@@ -31,6 +47,7 @@
Frequently Asked Questions
\endhtmlonly
+
\section faq-envvar How do I set or clear an environment variable?
Use the `set` command:
@@ -40,12 +57,11 @@ set -x key value
set -e key
\endfish
-
\section faq-login-cmd How do I run a command every login? What's fish's equivalent to .bashrc?
-Edit the file `~/.config/fish/config.fish`, creating it if it does not exist. (Note the leading period.)
-
+Edit the file `~/.config/fish/config.fish`, creating it if it does not exist (Note the leading period).
+
\section faq-prompt How do I set my prompt?
@@ -62,13 +78,11 @@ end
You can also use the Web configuration tool, `fish_config`, to preview and choose from a gallery of sample prompts.
-
\section faq-cmd-history How do I run a command from history?
Type some part of the command, and then hit the up or down arrow keys to navigate through history matches.
-
\section faq-subcommand How do I run a subcommand? The backtick doesn't work!
@@ -80,13 +94,11 @@ for i in (ls)
end
\endfish
-
\section faq-exit-status How do I get the exit status of a command?
Use the `$status` variable. This replaces the `$?` variable used in some other shells.
-
\section faq-single-env How do I set an environment variable for just one command?
@@ -105,18 +117,16 @@ begin
end
\endfish
-
\section faq-customize-colors How do I customize my syntax highlighting colors?
Use the web configuration tool, `fish_config`, or alter the `fish_color` family of environment variables.
-
+
\section faq-update-manpage-completions How do I update man page completions?
Use the `fish_update_completions` command.
-
\section faq-cwd-symlink Why does cd, $PWD and and various fish commands always resolve symlinked directories to their canonical path?
@@ -128,18 +138,16 @@ Writing `cd images; ls ..` given the above directory structure would list the co
Another related issue is that many programs that operate on recursive directory trees, like the find command, silently ignore symlinked directories. For example, ```find $PWD -name '*.txt'``` silently fails in shells that don't resolve symlinked paths.
-
\section faq-cd-implicit I accidentally entered a directory path and fish changed directory. What happened?
If fish is unable to locate a command with a given name, and it starts with '`.`', '`/`' or '`~`', fish will test if a directory of that name exists. If it does, it is implicitly assumed that you want to change working directory. For example, the fastest way to switch to your home directory is to simply press `~` and enter.
-
+
\section faq-open The open command doesn't work.
The `open` command uses the MIME type database and the `.desktop` files used by Gnome and KDE to identify filetypes and default actions. If at least one of these environments is installed, but the open command is not working, this probably means that the relevant files are installed in a non-standard location. Consider asking for more help.
-
\section faq-default How do I make fish my default shell?
@@ -161,7 +169,6 @@ You may need to adjust the above path to e.g. `/usr/bin/fish`. Use the command `
Unfortunately, there is no way to make the changes take effect at once. You will need to log out and back in again.
-
\section faq-titlebar I'm seeing weird output before each prompt when using screen. What's wrong?
@@ -181,7 +188,6 @@ Fish is trying to set the titlebar message of your terminal. While screen itself
Note that fish has a default titlebar message, which will be used if the fish_title function is undefined. So simply unsetting the fish_title function will not work.
-
\section faq-greeting How do I change the greeting message?
@@ -191,7 +197,6 @@ Change the value of the variable `fish_greeting` or create a `fish_greeting` fun
set fish_greeting
\endfish
-
\section faq-history Why doesn't history substitution ("!$" etc.) work?
@@ -200,14 +205,17 @@ Because history substitution is an awkward interface that was invented before in
Fish history recall is very simple yet effective:
- As in any modern shell, the Up arrow, @cursor_key{↑,Up} recalls whole lines, starting from the last line executed. A single press replaces "!!", later presses replace "!-3" and the like.
+
- 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 constrain the recall to lines that include this text, and you will get to the line you want much faster. This replaces "!vi", "!?bar.c" and the like.
+
- @key{Alt,↑,Up} recalls individual arguments, starting from the last argument in the last line executed. A single press replaces "!$", later presses replace "!!:4" and the like.
+
- If the argument you want is far back in history (e.g. 2 lines back - that's a lot of words!), type any part of it and then press @key{Alt,↑,Up}. This will show only arguments containing that part and you will get what you want much faster. Try it out, this is very convenient!
+
- If you want to reuse several arguments from the same line ("!!:3*" and the like), consider recalling the whole line and removing what you don't need (@key{Alt,D} and @key{Alt,Backspace} are your friends).
See documentation for more details about line editing in fish.
-
\section faq-uninstalling Uninstalling fish
diff --git a/doc_src/fg.txt b/doc_src/fg.txt
index e9f23bc53..0c09d50f6 100644
--- a/doc_src/fg.txt
+++ b/doc_src/fg.txt
@@ -6,11 +6,12 @@ fg [PID]
\endfish
\subsection fg-description Description
-`fg` brings the specified job to the foreground, resuming it if it is stopped. While a foreground job is
-executed, fish is suspended. If no job is specified, the last job to be used is put in the foreground. If PID is specified, the job with the specified group ID is put in the foreground.
+
+`fg` brings the specified job to the foreground, resuming it if it is stopped. While a foreground job is executed, fish is suspended. If no job is specified, the last job to be used is put in the foreground. If PID is specified, the job with the specified group ID is put in the foreground.
The PID of the desired process is usually found by using process expansion.
+
\subsection fg-example Example
`fg %1` will put the job with job ID 1 in the foreground.
diff --git a/doc_src/fish.txt b/doc_src/fish.txt
index ac100821f..05f48d66d 100644
--- a/doc_src/fish.txt
+++ b/doc_src/fish.txt
@@ -7,21 +7,24 @@ fish [OPTIONS] [-c command] [FILE [ARGUMENTS...]]
\subsection fish-description Description
-`fish` is a command-line shell written mainly with interactive use in mind. The
-full manual is available in HTML by using the
-help command from inside fish.
+`fish` is a command-line shell written mainly with interactive use in mind. The full manual is available in HTML by using the help command from inside fish.
The following options are available:
- `-c` or `--command=COMMANDS` evaluate the specified commands instead of reading from the commandline
+
- `-d` or `--debug-level=DEBUG_LEVEL` specify the verbosity level of fish. A higher number means higher verbosity. The default level is 1.
+
- `-h` or `--help` display help and exit
+
- `-i` or `--interactive` specify that fish is to run in interactive mode
+
- `-l` or `--login` specify that fish is to run as a login shell
+
- `-n` or `--no-execute` do not execute any commands, only perform syntax checking
+
- `-p` or `--profile=PROFILE_FILE` when fish exits, output timing information on all executed commands to the specified file
+
- `-v` or `--version` display version and exit
-The fish exit status is generally the exit status of the last
-foreground command. If fish is exiting because of a parse error, the
-exit status is 127.
+The fish exit status is generally the exit status of the last foreground command. If fish is exiting because of a parse error, the exit status is 127.
diff --git a/doc_src/fish_config.txt b/doc_src/fish_config.txt
index b09789426..4fa242651 100644
--- a/doc_src/fish_config.txt
+++ b/doc_src/fish_config.txt
@@ -4,19 +4,15 @@
`fish_config` starts the web-based configuration interface.
-The web interface allows you to view your functions, variables and history, and
-to make changes to your prompt and color configuration.
+The web interface allows you to view your functions, variables and history, and to make changes to your prompt and color configuration.
-`fish_config` starts a local web server and then opens a web browser window; when
-you have finished, close the browser window and then press the Enter key to
-terminate the configuration session.
+`fish_config` starts a local web server and then opens a web browser window; when you have finished, close the browser window and then press the Enter key to terminate the configuration session.
`fish_config` optionally accepts name of the initial configuration tab. For e.g. `fish_config history` will start configuration interface with history tab.
-If the `BROWSER` environment variable is set, it will be used as the name
-of the web browser to open instead of the system default.
+If the `BROWSER` environment variable is set, it will be used as the name of the web browser to open instead of the system default.
+
\subsection fish_config-example Example
-`fish_config` opens a new web browser window and allows you to configure certain
-fish settings.
+`fish_config` opens a new web browser window and allows you to configure certain fish settings.
diff --git a/doc_src/fish_indent.txt b/doc_src/fish_indent.txt
index 3a96b5343..386835dc9 100644
--- a/doc_src/fish_indent.txt
+++ b/doc_src/fish_indent.txt
@@ -7,13 +7,13 @@ fish_indent [OPTIONS]
\subsection fish_indent-description Description
-`fish_indent` is used to indent a piece of fish
-code. `fish_indent` reads commands from standard input and outputs
-them to standard output.
+`fish_indent` is used to indent a piece of fish code. `fish_indent` reads commands from standard input and outputs them to standard output.
The following options are available:
- `-h` or `--help` displays this help message and then exits
+
- `-i` or `--no-indent` do not indent commands
+
- `-v` or `--version` displays the current fish version and then exits
diff --git a/doc_src/fish_prompt.txt b/doc_src/fish_prompt.txt
index 57cc5c24e..1beb5304e 100644
--- a/doc_src/fish_prompt.txt
+++ b/doc_src/fish_prompt.txt
@@ -7,17 +7,14 @@ function fish_prompt
end
\endfish
-
\subsection fish_prompt-description Description
-By defining the `fish_prompt` function, the user can choose a custom
-prompt. The `fish_prompt` function is executed when the prompt is to
-be shown, and the output is used as a prompt.
+By defining the `fish_prompt` function, the user can choose a custom prompt. The `fish_prompt` function is executed when the prompt is to be shown, and the output is used as a prompt.
The exit status of commands within `fish_prompt` will not modify the value of $status outside of the `fish_prompt` function.
-`fish` ships with a number of example prompts that can be chosen with the
-`fish_config` command.
+`fish` ships with a number of example prompts that can be chosen with the `fish_config` command.
+
\subsection fish_prompt-example Example
diff --git a/doc_src/fish_right_prompt.txt b/doc_src/fish_right_prompt.txt
index 19d1efec8..21b4a1954 100644
--- a/doc_src/fish_right_prompt.txt
+++ b/doc_src/fish_right_prompt.txt
@@ -13,9 +13,11 @@ end
Multiple lines are not supported in `fish_right_prompt`.
+
\subsection fish_right_prompt-example Example
A simple right prompt:
+
\fish
function fish_right_prompt -d "Write out the right prompt"
date "+%m/%d/%y"
diff --git a/doc_src/for.txt b/doc_src/for.txt
index c75f953c0..15b28a25f 100644
--- a/doc_src/for.txt
+++ b/doc_src/for.txt
@@ -6,12 +6,11 @@ for VARNAME in [VALUES...]; COMMANDS...; end
\endfish
\subsection for-description Description
-`for` is a loop construct. It will perform the commands specified by
-`COMMANDS` multiple times. On each iteration, the environment variable specified by
-`VARNAME` is assigned a new value from `VALUES`. If `VALUES` is empty, `COMMANDS` will
-not be executed at all.
+
+`for` is a loop construct. It will perform the commands specified by `COMMANDS` multiple times. On each iteration, the environment variable specified by `VARNAME` is assigned a new value from `VALUES`. If `VALUES` is empty, `COMMANDS` will not be executed at all.
\subsection for-example Example
+
\fish
for i in foo bar baz; echo $i; end
@@ -20,4 +19,3 @@ foo
bar
baz
\endfish
-
diff --git a/doc_src/funced.txt b/doc_src/funced.txt
index 51d1b8651..143efba43 100644
--- a/doc_src/funced.txt
+++ b/doc_src/funced.txt
@@ -7,17 +7,12 @@ funced [OPTIONS] NAME
\subsection funced-description Description
-`funced` provides an interface to edit the definition of the function
-`NAME`.
+`funced` provides an interface to edit the definition of the function `NAME`.
-If the `$EDITOR` environment variable is set, it will be used as the program
-to edit the function. Otherwise, a built-in editor will be used.
+If the `$EDITOR` environment variable is set, it will be used as the program to edit the function. Otherwise, a built-in editor will be used.
-If there is no function called `NAME` a new function will be created with
-the specified name
+If there is no function called `NAME` a new function will be created with the specified name
-- `-e command` or `--editor command` Open the function
- body inside the text editor given by the command (for example, "vi"). The
- command 'fish' will use the built-in editor.
-- `-i` or `--interactive` Open function body in the
- built-in editor.
+- `-e command` or `--editor command` Open the function body inside the text editor given by the command (for example, "vi"). The command 'fish' will use the built-in editor.
+
+- `-i` or `--interactive` Open function body in the built-in editor.
diff --git a/doc_src/funcsave.txt b/doc_src/funcsave.txt
index c3f2fe320..a4c9e9d8f 100644
--- a/doc_src/funcsave.txt
+++ b/doc_src/funcsave.txt
@@ -7,8 +7,4 @@ funcsave FUNCTION_NAME
\subsection funcsave-description Description
-`funcsave` saves the current definition of a function to
-a file in the fish configuration directory. This function will be automatically
-loaded by current and future fish sessions. This can be useful if you have interactively
-created a new function and wish to save it for later use.
-
+`funcsave` saves the current definition of a function to a file in the fish configuration directory. This function will be automatically loaded by current and future fish sessions. This can be useful if you have interactively created a new function and wish to save it for later use.
diff --git a/doc_src/function.txt b/doc_src/function.txt
index f2f6ecd4e..8c4ba89b2 100644
--- a/doc_src/function.txt
+++ b/doc_src/function.txt
@@ -9,31 +9,37 @@ function [OPTIONS] NAME; BODY; end
`function` creates a new function `NAME` with the body `BODY`.
-A function is a list of commands that will be executed when the name of the
-function is given as a command.
+A function is a list of commands that will be executed when the name of the function is given as a command.
The following options are available:
- `-a NAMES` or `--argument-names NAMES` assigns the value of successive command-line arguments to the names given in NAMES.
+
- `-d DESCRIPTION` or `--description=DESCRIPTION` is a description of what the function does, suitable as a completion description.
+
- `-w WRAPPED_COMMAND` or `--wraps=WRAPPED_COMMAND` causes the function to inherit completions from the given wrapped command. See the documentation for `complete` for more information.
+
- `-e` or `--on-event EVENT_NAME` tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt.
+
- `-j PID` or `--on-job-exit PID` tells fish to run this function when the job with group ID PID exits. Instead of PID, the string 'caller' can be specified. This is only legal when in a command substitution, and will result in the handler being triggered by the exit of the job which created this command substitution.
+
- `-p PID` or `--on-process-exit PID` tells fish to run this function when the fish child process with process ID PID exits.
+
- `-s` or `--on-signal SIGSPEC` tells fish to run this function when the signal SIGSPEC is delivered. SIGSPEC can be a signal number, or the signal name, such as SIGHUP (or just HUP).
+
- `-S` or `--no-scope-shadowing` allows the function to access the variables of calling functions. Normally, any variables inside the function that have the same name as variables from the calling function are "shadowed", and their contents is independent of the calling function.
+
- `-v` or `--on-variable VARIABLE_NAME` tells fish to run this function when the variable VARIABLE_NAME changes value.
-If the user enters any additional arguments after the function, they
-are inserted into the environment variable array
-`$argv`. If the `--argument-names` option is provided, the arguments are
-also assigned to names specified in that option.
+If the user enters any additional arguments after the function, they are inserted into the environment variable array `$argv`. If the `--argument-names` option is provided, the arguments are also assigned to names specified in that option.
By using one of the event handler switches, a function can be made to run automatically at specific events. The user may generate new events using the emit builtin. Fish generates the following named events:
- `fish_prompt`, which is emitted whenever a new fish prompt is about to be displayed.
+
- `fish_command_not_found`, which is emitted whenever a command lookup failed.
+
\subsection function-example Example
\fish
diff --git a/doc_src/functions.txt b/doc_src/functions.txt
index 24e375c45..6e7f92d59 100644
--- a/doc_src/functions.txt
+++ b/doc_src/functions.txt
@@ -15,39 +15,36 @@ functions [-eq] FUNCTIONS...
The following options are available:
- `-a` or `--all` lists all functions, even those whose name start with an underscore.
+
- `-c OLDNAME NEWNAME` or `--copy OLDNAME NEWNAME` creates a new function named NEWNAME, using the definition of the OLDNAME function.
+
- `-d DESCRIPTION` or `--description=DESCRIPTION` changes the description of this function.
+
- `-e` or `--erase` causes the specified functions to be erased.
+
- `-h` or `--help` displays a help message and exits.
+
- `-n` or `--names` lists the names of all defined functions.
+
- `-q` or `--query` tests if the specified functions exist.
-The default behavior of `functions`, when called with no arguments,
-is to print the names of all defined functions. Unless the `-a` option is
-given, no functions starting with underscores are not included in the output.
+The default behavior of `functions`, when called with no arguments, is to print the names of all defined functions. Unless the `-a` option is given, no functions starting with underscores are not included in the output.
-If any non-option parameters are given, the definition of the specified
-functions are printed.
+If any non-option parameters are given, the definition of the specified functions are printed.
-Automatically loaded functions cannot be removed using `functions
--e`. Either remove the definition file or change the
-$fish_function_path variable to remove autoloaded functions.
+Automatically loaded functions cannot be removed using `functions -e`. Either remove the definition file or change the $fish_function_path variable to remove autoloaded functions.
-Copying a function using `-c` copies only the body of the function, and
-does not attach any event notifications from the original function.
+Copying a function using `-c` copies only the body of the function, and does not attach any event notifications from the original function.
-Only one function's description can be changed in a single invocation
-of `functions -d`.
+Only one function's description can be changed in a single invocation of `functions -d`.
+
+The exit status of `functions` is the number of functions specified in the argument list that do not exist, which can be used in concert with the `-q` option.
-The exit status of `functions` is the number of functions
-specified in the argument list that do not exist, which can be used in
-concert with the `-q` option.
\subsection functions-example Examples
`functions -n` displays a list of currently-defined functions.
-`functions -c foo bar` copies the `foo` function to a new function called
-`bar`.
+`functions -c foo bar` copies the `foo` function to a new function called `bar`.
`functions -e bar` erases the function `bar`.
diff --git a/doc_src/help.txt b/doc_src/help.txt
index d862da8cc..e279e62b0 100644
--- a/doc_src/help.txt
+++ b/doc_src/help.txt
@@ -11,11 +11,10 @@ help [SECTION]
If a `SECTION` is specified, the help for that command is shown.
-If the BROWSER environment variable is set, it will be used to display the
-documentation. Otherwise, fish will search for a suitable browser.
+If the BROWSER environment variable is set, it will be used to display the documentation. Otherwise, fish will search for a suitable browser.
+
+Note that most builtin commands display their help in the terminal when given the `--help` option.
-Note that most builtin commands display their help in the terminal when
-given the `--help` option.
\subsection help-example Example
diff --git a/doc_src/history.txt b/doc_src/history.txt
index 396e4d2e2..dbcd258ab 100644
--- a/doc_src/history.txt
+++ b/doc_src/history.txt
@@ -12,23 +12,33 @@ history (--search | --delete) [--prefix "prefix string" | --contains "search str
The following options are available:
- `--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.
+
- `--save` saves all changes in the history file. The shell automatically saves the history file; this option is provided for internal use.
+
- `--clear` clears the history file. A prompt is displayed before the history is erased.
+
- `--search` returns history items in keeping with the `--prefix` or `--contains` options.
+
- `--delete` deletes history items.
+
- `--prefix` searches or deletes items in the history that begin with the specified text string.
+
- `--contains` searches or deletes items in the history that contain the specified text string.
If `--search` is specified without `--contains` or `--prefix`, `--contains` will be assumed.
If `--delete` is specified without `--contains` or `--prefix`, only a history item which exactly matches the parameter will be erased. No prompt will be given. If `--delete` is specified with either of these parameters, an interactive prompt will be displayed before any items are deleted.
+
\subsection history-examples Example
-`history --clear` deletes all history items
+\fish
+history --clear
+# Deletes all history items
-`history --search --contains "foo"` outputs a list of all previous
-commands containing the string "foo".
+history --search --contains "foo"
+# Outputs a list of all previous commands containing the string "foo".
-`history --delete --prefix "foo"` interactively deletes the record
-of previous commands which start with "foo".
+history --delete --prefix "foo"
+# Interactively deletes the record of previous commands which start with "foo".
+\endfish
diff --git a/doc_src/if.txt b/doc_src/if.txt
index c53738010..0e9a7cb14 100644
--- a/doc_src/if.txt
+++ b/doc_src/if.txt
@@ -10,22 +10,17 @@ end
\subsection if-description Description
-`if` will execute the command `CONDITION`. If the condition's
-exit status is 0, the commands `COMMANDS_TRUE` will execute. If the
-exit status is not 0 and `else` is given, `COMMANDS_FALSE` will
-be executed.
+`if` will execute the command `CONDITION`. If the condition's exit status is 0, the commands `COMMANDS_TRUE` will execute. If the exit status is not 0 and `else` is given, `COMMANDS_FALSE` will be executed.
-In order to use the exit status of multiple commands as the condition
-of an if block, use `begin; ...; end` and
-the short circuit commands `and`
-and `or`.
+In order to use the exit status of multiple commands as the condition of an if block, use `begin; ...; end` and the short circuit commands `and` and `or`.
+
+The exit status of the last foreground command to exit can always be accessed using the $status variable.
-The exit status of the last foreground command to exit can always be
-accessed using the $status
-variable.
\subsection if-example Example
+The following code will print `foo.txt exists` if the file foo.txt exists and is a regular file, otherwise it will print `bar.txt exists` if the file bar.txt exists and is a regular file, otherwise it will print `foo.txt and bar.txt do not exist`.
+
\fish
if test -f foo.txt
echo foo.txt exists
@@ -35,9 +30,3 @@ else
echo foo.txt and bar.txt do not exist
end
\endfish
-
-will print `foo.txt exists` if the file foo.txt
-exists and is a regular file, otherwise it will print
-`bar.txt exists` if the file bar.txt exists
-and is a regular file, otherwise it will print
-`foo.txt and bar.txt do not exist`.
diff --git a/doc_src/index.hdr.in b/doc_src/index.hdr.in
index ae86b6c6a..5fa682208 100644
--- a/doc_src/index.hdr.in
+++ b/doc_src/index.hdr.in
@@ -42,11 +42,17 @@ Every program on your computer can be used as a command in `fish`. If the progra
Here is a list of some useful commands:
- `cd`, change the current directory
+
- `ls`, list files and directories
+
- `man`, display a manual page on the screen
+
- `mv`, move (rename) files
+
- `cp`, copy files
+
- `open`, open files with the default application associated with each filetype
+
- `less`, list the contents of files
Commands and parameters are separated by the space character ' '. Every command ends with either a newline (i.e. by pressing the return key) or a semicolon '`;`'. More than one command can be written on the same line by separating them with semicolons.
@@ -80,40 +86,76 @@ would remove the two files 'cumbersome' and 'filename.txt'.
Some characters can not be written directly on the command line. For these characters, so called escape sequences are provided. These are:
- '\\a' escapes the alert character
+
- '\\b' escapes the backspace character
+
- '\\e' escapes the escape character
+
- '\\f' escapes the form feed character
+
- '\\n' escapes a newline character
+
- '\\r' escapes the carriage return character
+
- '\\t' escapes the tab character
+
- '\\v' escapes the vertical tab character
+
- '\\ ' escapes the space character
+
- '\\$' escapes the dollar character
+
- '\\\\' escapes the backslash character
+
- '\\*' escapes the star character
+
- '\\?' escapes the question mark character
+
- '\\~' escapes the tilde character
+
- '\\%' escapes the percent character
+
- '\\#' escapes the hash character
+
- '\\(' escapes the left parenthesis character
+
- '\\)' escapes the right parenthesis character
+
- '\\{' escapes the left curly bracket character
+
- '\\}' escapes the right curly bracket character
+
- '\\[' escapes the left bracket character
+
- '\\]' escapes the right bracket character
+
- '\\' escapes the less than character
+
- '\\\>' escapes the more than character
+
- '\\^' escapes the circumflex character
+
- '\\&' escapes the ampersand character
+
- '\\;' escapes the semicolon character
+
- '\\"' escapes the quote character
+
- '\\'' escapes the apostrophe character
+
- '\\xxx', where xx is a hexadecimal number, escapes the ascii character with the specified value. For example, `\x9` is the tab character.
-- '\\Xxx', where xx is a hexadecimal number, escapes a byte of data with the specified value. If you are using a mutibyte encoding, this can be used to enter invalid strings. Only use this if you know what you are doing.
+
+- '\\Xxx', where xx is a hexadecimal number, escapes a byte of data with the specified value. If you are using a mutibyte encoding, this can be used to enter
+invalid strings. Only use this if you know what you are doing.
+
- '\\ooo', where ooo is an octal number, escapes the ascii character with the specified value. For example, `\011` is the tab character.
+
- '\\uxxxx', where xxxx is a hexadecimal number, escapes the 16-bit Unicode character with the specified value. For example, `\u9` is the tab character.
+
- '\\Uxxxxxxxx', where xxxxxxxx is a hexadecimal number, escapes the 32-bit Unicode character with the specified value. For example, `\U9` is the tab character.
-- '\\cx', where x is a letter of the alphabet, escapes the control sequence generated by pressing the control key and the specified letter. For example, `\ci` is the tab character
+
+- '\\cx', where x is a letter of the alphabet, escapes the control sequence generated by pressing the control key and the specified letter. For example, `\ci` is
+the tab character
\subsection redirects Input/Output (IO) redirection
@@ -121,7 +163,9 @@ Some characters can not be written directly on the command line. For these chara
Most programs use three input/output (IO) streams, each represented by a number called a file descriptor (FD). These are:
- Standard input, FD 0, for reading, defaults to reading from the keyboard.
+
- Standard output, FD 1, for writing, defaults to writing to the screen.
+
- Standard error, FD 2, for writing errors and warnings, defaults to writing to the screen.
The reason for providing for two output file descriptors is to allow
@@ -132,15 +176,21 @@ Any file descriptor can be directed to a different output than its default throu
An example of a file redirection is `echo hello > output.txt`, which directs the output of the echo command to the file output.txt.
- To read standard input from a file, write `>DESTINATION_FILE`
+
- To append standard error to a file, write `^^DESTINATION_FILE`
`DESTINATION` can be one of the following:
- A filename. The output will be written to the specified file.
+
- An ampersand (`&`) followed by the number of another file descriptor. The output will be written to that file descriptor instead.
+
- An ampersand followed by a minus sign (`&-`). The file descriptor will be closed.
Example:
@@ -151,7 +201,9 @@ Any file descriptor can be redirected in an arbitrary way by prefixing the
redirection with the file descriptor.
- To redirect input of FD N, write `NDESTINATION`
+
- To append the output of FD N to a file, write `N>>DESTINATION_FILE`
Example: `echo Hello 2>output.stderr` and `echo Hello
@@ -227,6 +279,7 @@ end
There are a few important things that need to be noted about aliases:
- Always take care to add the `$argv` variable to the list of parameters to the wrapped command. This makes sure that if the user specifies any additional parameters to the function, they are passed on to the underlying command.
+
- If the alias has the same name as the aliased command, it is necessary to refix the call to the program with `command` in order to tell fish that the unction should not call itself, but rather a command with the same name. ailing to do so will cause infinite recursion bugs.
To easily create a function of this form, you can use the alias command.
@@ -257,12 +310,19 @@ The other conditionals use the exit status of a
This is a short explanation of some of the commonly used words in fish.
- argument a parameter given to a command
+
- builtin a command that is implemented in the shell. Builtins are commands that are so closely tied to the shell that it is impossible to implement them as external commands.
+
- command a program that the shell can run.
+
- function 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.
+
- job a running pipeline or command
+
- pipeline a set of commands stringed together so that the output of one command is the input of the next command
+
- redirection a operation that changes one of the input/output streams associated with a job
+
- switch 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.
@@ -291,18 +351,27 @@ Tab completion is one of the most time saving features of any modern shell. By t
These are the general purpose tab completions that `fish` provides:
- Completion of commands (builtins, functions and regular programs).
+
- Completion of shell variable names.
+
- Completion of usernames for tilde expansion.
+
- Completion of filenames, even on strings with wildcards such as '`*`', '`**`' and '`?`'.
+
- Completion of job ID, job name and process names for process expansion.
`fish` provides a large number of program specific completions. Most of these completions are simple options like the `-l` option for `ls`, but some are more advanced. The latter include:
- The programs `man` and `whatis` show all installed manual pages as completions.
+
- The `make` program uses all targets in the Makefile in the current directory as completions.
+
- The `mount` command uses all mount points specified in fstab as completions.
+
- The `ssh` command uses all hosts that are stored in the known_hosts file as completions. (See the ssh documentation for more information)
+
- The `su` command uses all users on the system as completions.
+
- The `apt-get`, `rpm` and `yum` commands use all installed packages as completions.
@@ -327,16 +396,24 @@ For examples of how to write your own complex completions, study the completions
`fish` ships with several functions that are very useful when writing command specific completions. Most of these functions name begins with the string '`__fish_`'. Such functions are internal to `fish` and their name and interface may change in future fish versions. Still, some of them may be very useful when writing completions. A few of these functions are described here. Be aware that they may be removed or changed in future versions of fish.
-Functions beginning with the string `__fish_print_` print a newline- separated list of strings. For example, `__fish_print_filesystems` prints a list of all known file systems. Functions beginning with `__fish_complete_` print out a newline separated list of completions with descriptions. The description is separated from the completion by a tab character.
+Functions beginning with the string `__fish_print_` print a newline separated list of strings. For example, `__fish_print_filesystems` prints a list of all known file systems. Functions beginning with `__fish_complete_` print out a newline separated list of completions with descriptions. The description is separated from the completion by a tab character.
- `__fish_complete_directories STRING DESCRIPTION` performs path completion on STRING, allowing only directories, and giving them the description DESCRIPTION.
+
- `__fish_complete_groups` prints a list of all user groups with the groups members as description.
+
- `__fish_complete_pids` prints a list of all processes IDs with the command name as description.
+
- `__fish_complete_suffix SUFFIX` performs file completion allowing only files ending in SUFFIX. The mimetype database is used to find a suitable description.
+
- `__fish_complete_users` prints a list of all users with their full name as description.
+
- `__fish_print_filesystems` prints a list of all known file systems. Currently, this is a static list, and not dependent on what file systems the host operating system actually understands.
+
- `__fish_print_hostnames` prints a list of all known hostnames. This functions searches the fstab for nfs servers, ssh for known hosts and checks the `/etc/hosts` file.
+
- `__fish_print_interfaces` prints a list of all known network interfaces.
+
- `__fish_print_packages` prints a list of all installed packages. This function currently handles Debian, rpm and Gentoo packages.
@@ -359,7 +436,9 @@ When an argument for a program is given on the commandline, it undergoes the pro
If a star (`*`) or a question mark (`?`) is present in the parameter, `fish` attempts to match the given parameter to any files in such a way that:
- '`?`' can match any single character except '/'.
+
- '`*`' can match any string of characters not containing '/'. This includes matching an empty string.
+
- '`**`' matches any string of characters. This includes matching an empty string. The string may include the '/' character but does not need to.
Wildcard matches are sorted case insensitively. When sorting matches containing numbers, consecutive digits are considered to be one element, so that the strings '1' '5' and '12' would be sorted in the order given.
@@ -369,7 +448,9 @@ File names beginning with a dot are not considered when wildcarding unless a dot
Examples:
- `a*` matches any files beginning with an 'a' in the current directory.
+
- `???` matches any file in the current directory whose name is exactly three characters long.
+
- `**` matches any files and directories in the current directory and all of its subdirectories.
Note that if no matches are found for a specific wildcard, it will expand into zero arguments, i.e. to nothing. If none of the wildcarded arguments sent to a command result in any matches, the command will not be executed. If this happens when using the shell interactively, a warning will also be printed.
@@ -393,6 +474,7 @@ for i in *.jpg; convert $i (basename $i .jpg).png; end
# PNG format using the 'convert' program.
\endfish
+
\subsection expand-brace Brace expansion
A comma separated list of characters enclosed in curly braces will be expanded so each element of the list becomes a new parameter.
@@ -406,6 +488,7 @@ mv *.{c,h} src/
# Moves all files with the suffix '.c' or '.h' to the subdirectory src.
\endfish
+
\subsection expand-variable Variable expansion
A dollar sign followed by a string of characters is expanded into the value of the shell variable with the same name. For an introduction to the concept of shell variables, read the Shell variables section.
@@ -489,6 +572,7 @@ echo $PATH[$n..-1]
Note that variables can be used as indices for expansion of variables, but not command substitution.
+
\subsection expand-home Home directory expansion
The `~` (tilde) character at the beginning of a parameter, followed by a username, is expanded into the home directory of the specified user. A lone `~`, or a `~` followed by a slash, is expanded into the home directory of the process owner.
@@ -499,9 +583,13 @@ The `~` (tilde) character at the beginning of a parameter, followed by a usernam
The `%` (percent) character at the beginning of a parameter followed by a string is expanded into a process ID (PID). The following expansions are performed:
- If the string is the entire word `self`, the shell's PID is the result.
+
- Otherwise, if the string is the ID of a job, the result is the process group ID of the job.
+
- Otherwise, if any child processes match the specified string, their PIDs are the result of the expansion.
+
- Otherwise, if any processes owned by the user match the specified string, their PIDs are the result of the expansion.
+
- If none of these matches apply, an error is produced.
This form of expansion is useful for commands like kill and fg, which take process IDs as arguments.
@@ -520,9 +608,13 @@ All of the above expansions can be combined. If several expansions result in mor
When combining multiple parameter expansions, expansions are performed in the following order:
- Command substitutions
+
- Variable expansions
+
- Bracket expansion
+
- Pid expansion
+
- Wildcard expansion
Expansions are performed from right to left, nested bracket expansions are performed from the inside and out.
@@ -583,8 +675,8 @@ Universal variables are variables that are shared between all the users fish ses
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.
-\subsection variables-functions Variable scope for functions
+\subsection variables-functions Variable scope for functions
When calling a function, all current local variables temporarily disappear. This shadowing of the local scope is needed since the variable namespace would become cluttered, making it very easy to accidentally overwrite variables from another function.
@@ -666,38 +758,43 @@ The user can change the settings of `fish` by changing the values of
certain environment variables.
- `BROWSER`, the user's preferred web browser. If this variable is set, fish will use the specified browser instead of the system default browser to display the fish documentation.
+
- `CDPATH`, an array of directories in which to search for the new directory for the `cd` builtin. By default, the fish configuration defines `CDPATH` to be a universal variable with the values `.` and `~`.
+
- A large number of variable starting with the prefixes `fish_color` and `fish_pager_color`. See Variables for changing highlighting colors for more information.
+
- `fish_greeting`, the greeting message printed on startup.
+
- `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 for more information.
+
- `fish_user_paths`, an array of directories that are prepended to PATH. This can be a universal variable.
+
- `PATH`, an array of directories in which to search for commands
+
- `umask`, the current file creation mask. The preferred way to change the umask variable is through the umask function. An attempt to set umask to an invalid value will always fail.
-`fish` also sends additional information to the user through the
-values of certain environment variables. The user cannot change the
-values of most of these variables.
+`fish` also sends additional information to the user through the values of certain environment variables. The user cannot change the values of most of these variables.
- `_`, the name of the currently running command.
+
- `argv`, an array of arguments to the shell or function. `argv` is only defined when inside a function call, or if fish was invoked with a list of arguments, like 'fish myscript.fish foo bar'. This variable can be changed by the user.
+
- `history`, an array containing the last commands that were entered.
+
- `HOME`, the user's home directory. This variable can only be changed by the root user.
+
- `PWD`, the current working directory.
+
- `status`, the 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.
+
- `USER`, the current username. This variable can only be changed by the root user.
+
- `CMD_DURATION`, the runtime of the last command in milliseconds.
-The names of these variables are mostly derived from the csh family of
-shells and differ from the ones used by Bourne style shells such as
-bash.
+The names of these variables are mostly derived from the csh family of shells and differ from the ones used by Bourne style shells such as bash.
+
+Variables whose name are in uppercase are exported to the commands started by fish, while those in lowercase are not exported. This rule is not enforced by fish, but it is good coding practice to use casing to distinguish between exported and unexported variables. `fish` also uses several variables internally. Such variables are prefixed with the string `__FISH` or `__fish`. These should never be used by the user. Changing their value may break fish.
-Variables whose name are in uppercase are exported to the commands
-started by fish, while those in lowercase are not exported. This rule is not
-enforced by fish, but it is good coding practice to use casing to
-distinguish between exported and unexported variables. `fish` also
-uses several variables internally. Such variables are prefixed with
-the string `__FISH` or `__fish`. These should never be used by the
-user. Changing their value may break fish.
\subsection variables-status The status variable
@@ -708,9 +805,13 @@ Fish stores the exit status of the last process in the last job to exit in the `
If `fish` encounters a problem while executing a command, the status variable may also be set to a specific value:
- 1 is the generally the exit status from fish builtin commands if they were supplied with invalid arguments
+
- 124 means that the command was not executed because none of the wildcards in the command produced any matches
+
- 125 means that while an executable with the specified name was located, the operating system could not actually execute the command
+
- 126 means that while a file with the specified name was located, it was not executable
+
- 127 means that no function, builtin or command with the given name could be located
If a process exits through a signal, the exit status will be 128 plus the number of the signal.
@@ -723,26 +824,42 @@ The colors used by fish for syntax highlighting can be configured by changing th
The following variables are available to change the highlighting colors in fish:
- `fish_color_normal`, the default color
+
- `fish_color_command`, the color for commands
+
- `fish_color_quote`, the color for quoted blocks of text
+
- `fish_color_redirection`, the color for IO redirections
+
- `fish_color_end`, the color for process separators like ';' and '&'
+
- `fish_color_error`, the color used to highlight potential errors
+
- `fish_color_param`, the color for regular command parameters
+
- `fish_color_comment`, the color used for code comments
+
- `fish_color_match`, the color used to highlight matching parenthesis
+
- `fish_color_search_match`, the color used to highlight history search matches
+
- `fish_color_operator`, the color for parameter expansion operators like '*' and '~'
+
- `fish_color_escape`, the color used to highlight character escapes like '\\n' and '\\x70'
+
- `fish_color_cwd`, the color used for the current working directory in the default prompt
Additionally, the following variables are available to change the
highlighting in the completion pager:
- `fish_pager_color_prefix`, the color of the prefix string, i.e. the string that is to be completed
+
- `fish_pager_color_completion`, the color of the completion itself
+
- `fish_pager_color_description`, the color of the completion description
+
- `fish_pager_color_progress`, the color of the progress bar at the bottom left corner
+
- `fish_pager_color_secondary`, the background color of the every second completion
Example:
@@ -778,25 +895,45 @@ Similar to bash, fish has Emacs and Vi editing modes. The default editing mode i
\subsection emacs-mode Emacs mode commands
- @key{Tab} completes the current token.
+
- @key{Home} or @key{Control,A} moves the cursor to the beginning of the line.
+
- @key{End} or @key{Control,E} moves to the end of line. If the cursor is already at the end of the line, and an autosuggestion is available, @key{End} or @key{Control,E} accepts the autosuggestion.
+
- @cursor_key{←,Left} (or @key{Control,B}) and @cursor_key{→,Right} (or @key{Control,F}) 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, the @cursor_key{→,Right} key and the @key{Control,F} combination accept the suggestion.
+
- @key{Alt,←,Left} and @key{Alt,→,Right} move the cursor one word left or right, or moves forward/backward in the directory history if the command line is empty. If the cursor is already at the end of the line, and an autosuggestion is available, @key{Alt,→,Right} (or @key{Alt,F}) accepts the first word in the suggestion.
+
- @cursor_key{↑,Up} and @cursor_key{↓,Down} 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 section for more information on history searching.
+
- @key{Alt,↑,Up} and @key{Alt,↓,Down} 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 section for more information on history searching.
+
- @key{Delete} and @key{Backspace} removes one character forwards or backwards respectively.
+
- @key{Control,C} deletes the entire line.
+
- @key{Control,D} delete one character to the right of the cursor. If the command line is empty, @key{Control,D} will exit fish.
+
- @key{Control,K} moves contents from the cursor to the end of line to the killring.
+
- @key{Control,U} moves contents from the beginning of line to the cursor to the killring.
+
- @key{Control,L} clears and repaints the screen.
+
- @key{Control,W} moves the previous word to the killring.
+
- @key{Alt,D} moves the next word to the killring.
+
- @key{Alt,W} prints a short description of the command under the cursor.
+
- @key{Alt,L} lists the contents of the current directory, unless the cursor is over a directory argument, in which case the contents of that directory will be listed.
+
- @key{Alt,P} adds the string '`| less;`' to the end of the job under the cursor. The result is that the output of the command will be paged.
+
- @key{Alt,C} capitalizes the current word.
+
- @key{Alt,U} makes the current word uppercase.
+
- @key{F1} shows the manual page for the current command, if one exists.
You can change these key bindings using the bind builtin command.
@@ -807,15 +944,25 @@ You can change these key bindings using the bindjobs and their status.
+
+`jobs` prints a list of the currently running jobs and their status.
jobs accepts the following switches:
- `-c` or `--command` prints the command name for each process in jobs.
+
- `-g` or `--group` only prints the group ID of each job.
+
- `-h` or `--help` displays a help message and exits.
+
- `-l` or `--last` prints only the last job to be started.
+
- `-p` or `--pid` prints the process ID for each process in all jobs.
-On systems that supports this feature, jobs will print the CPU usage
-of each job since the last command was executed. The CPU usage is
-expressed as a percentage of full CPU activity. Note that on
-multiprocessor systems, the total activity may be more than 100\%.
+On systems that supports this feature, jobs will print the CPU usage of each job since the last command was executed. The CPU usage is expressed as a percentage of full CPU activity. Note that on multiprocessor systems, the total activity may be more than 100\%.
+
\subsection jobs-example Example
diff --git a/doc_src/license.hdr b/doc_src/license.hdr
index f9528b4bd..eac13766b 100644
--- a/doc_src/license.hdr
+++ b/doc_src/license.hdr
@@ -7,8 +7,7 @@
\endhtmlonly
-`fish` Copyright © 2005-2009 Axel Liljencrantz. `fish` is released under the GNU
-General Public License, version 2. The license agreement is included below.
+`fish` Copyright © 2005-2009 Axel Liljencrantz. `fish` is released under the GNU General Public License, version 2. The license agreement is included below.
## GNU GENERAL PUBLIC LICENSE
@@ -25,318 +24,126 @@ Version 2, June 1991
## Preamble
-The licenses for most software are designed to take away your freedom to share
-and change it. By contrast, the GNU General Public License is intended to
-guarantee your freedom to share and change free software - to make sure the
-software is free for all its users. This General Public License applies to
-most of the Free Software Foundation's software and to any other program whose
-authors commit to using it. (Some other Free Software Foundation software is
-covered by the GNU Library General Public License instead.) You can apply it
-to your programs, too.
+The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software - to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.
-When we speak of free software, we are referring to freedom, not price. Our
-General Public Licenses are designed to make sure that you have the freedom to
-distribute copies of free software (and charge for this service if you wish),
-that you receive source code or can get it if you want it, that you can change
-the software or use pieces of it in new free programs; and that you know you
-can do these things.
+When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.
-To protect your rights, we need to make restrictions that forbid anyone to
-deny you these rights or to ask you to surrender the rights. These
-restrictions translate to certain responsibilities for you if you distribute
-copies of the software, or if you modify it.
+To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.
-For example, if you distribute copies of such a program, whether gratis or for
-a fee, you must give the recipients all the rights that you have. You must
-make sure that they, too, receive or can get the source code. And you must
-show them these terms so they know their rights.
+For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
-We protect your rights with two steps: (1) copyright the software, and (2)
-offer you this license which gives you legal permission to copy, distribute
-and/or modify the software.
+We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.
-Also, for each author's protection and ours, we want to make certain that
-everyone understands that there is no warranty for this free software. If the
-software is modified by someone else and passed on, we want its recipients to
-know that what they have is not the original, so that any problems introduced
-by others will not reflect on the original authors' reputations.
+Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.
-Finally, any free program is threatened constantly by software patents. We
-wish to avoid the danger that redistributors of a free program will
-individually obtain patent licenses, in effect making the program proprietary.
-To prevent this, we have made it clear that any patent must be licensed for
-everyone's free use or not licensed at all.
+Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.
-The precise terms and conditions for copying, distribution and modification
-follow.
+The precise terms and conditions for copying, distribution and modification follow.
## TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-- This License applies to any program or other work which contains a notice
-placed by the copyright holder saying it may be distributed under the terms of
-this General Public License. The "Program", below, refers to any such program
-or work, and a "work based on the Program" means either the Program or any
-derivative work under copyright law: that is to say, a work containing the
-Program or a portion of it, either verbatim or with modifications and/or
-translated into another language. (Hereinafter, translation is included
-without limitation in the term "modification".) Each licensee is addressed as
-"you".
+- This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".
- Activities other than copying, distribution and modification are not covered
-by this License; they are outside its scope. The act of running the Program
-is not restricted, and the output from the Program is covered only if its
-contents constitute a work based on the Program (independent of having been
-made by running the Program). Whether that is true depends on what the Program
-does.
+ Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.
-1. You may copy and distribute verbatim copies of the Program's source code as
-you receive it, in any medium, provided that you conspicuously and
-appropriately publish on each copy an appropriate copyright notice and
-disclaimer of warranty; keep intact all the notices that refer to this License
-and to the absence of any warranty; and give any other recipients of the
-Program a copy of this License along with the Program.
+1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.
- You may charge a fee for the physical act of transferring a copy, and you may
-at your option offer warranty protection in exchange for a fee.
+ You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
-2. You may modify your copy or copies of the Program or any portion of it,
-thus forming a work based on the Program, and copy and distribute such
-modifications or work under the terms of Section 1 above, provided that you
-also meet all of these conditions:
+2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
- -# You must cause the modified files to carry prominent notices stating
-that you changed the files and the date of any change.
+ -# You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
- -# You must cause any work that you distribute or publish, that in whole or
-in part contains or is derived from the Program or any part thereof, to be
-licensed as a whole at no charge to all third parties under the terms of this
-License.
+ -# You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
- -# If the modified program normally reads commands interactively when run,
-you must cause it, when started running for such interactive use in the most
-ordinary way, to print or display an announcement including an appropriate
-copyright notice and a notice that there is no warranty (or else, saying that
-you provide a warranty) and that users may redistribute the program under
-these conditions, and telling the user how to view a copy of this License.
-(Exception: if the Program itself is interactive but does not normally print
-such an announcement, your work based on the Program is not required to print
-an announcement.)
+ -# If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)
- These requirements apply to the modified work as a whole. If identifiable
-sections of that work are not derived from the Program, and can be reasonably
-considered independent and separate works in themselves, then this License,
-and its terms, do not apply to those sections when you distribute them as
-separate works. But when you distribute the same sections as part of a whole
-which is a work based on the Program, the distribution of the whole must be on
-the terms of this License, whose permissions for other licensees extend to the
-entire whole, and thus to each and every part regardless of who wrote it.
+ These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.
- Thus, it is not the intent of this section to claim rights or contest your
-rights to work written entirely by you; rather, the intent is to exercise the
-right to control the distribution of derivative or collective works based on
-the Program.
+ Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.
- In addition, mere aggregation of another work not based on the Program with
-the Program (or with a work based on the Program) on a volume of a storage or
-distribution medium does not bring the other work under the scope of this
-License.
+ In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
-3. You may copy and distribute the Program (or a work based on it, under
-Section 2) in object code or executable form under the terms of Sections 1 and
-2 above provided that you also do one of the following:
+3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
- -# Accompany it with the complete corresponding machine-readable source code,
-which must be distributed under the terms of Sections 1 and 2 above on a
-medium customarily used for software interchange; or,
+ -# Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
- -# Accompany it with a written offer, valid for at least three years, to give
-any third party, for a charge no more than your cost of physically
-performing source distribution, a complete machine-readable copy of the
-corresponding source code, to be distributed under the terms of Sections 1
-and 2 above on a medium customarily used for software interchange; or,
+ -# Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
- -# Accompany it with the information you received as to the offer to
-distribute corresponding source code. (This alternative is allowed only
-for noncommercial distribution and only if you received the program in
-object code or executable form with such an offer, in accord with
-Subsection b above.)
+ -# Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)
- The source code for a work means the preferred form of the work for making
-modifications to it. For an executable work, complete source code means all
-the source code for all modules it contains, plus any associated interface
-definition files, plus the scripts used to control compilation and
-installation of the executable. However, as a special exception, the source
-code distributed need not include anything that is normally distributed (in
-either source or binary form) with the major components (compiler, kernel, and
-so on) of the operating system on which the executable runs, unless that
-component itself accompanies the executable.
+ The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.
- If distribution of executable or object code is made by offering access to
-copy from a designated place, then offering equivalent access to copy the
-source code from the same place counts as distribution of the source code,
-even though third parties are not compelled to copy the source along with the
-object code.
+ If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.
-4. You may not copy, modify, sublicense, or distribute the Program except as
-expressly provided under this License. Any attempt otherwise to copy, modify,
-sublicense or distribute the Program is void, and will automatically terminate
-your rights under this License. However, parties who have received copies, or
-rights, from you under this License will not have their licenses terminated so
-long as such parties remain in full compliance.
+4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
-5. You are not required to accept this License, since you have not signed it.
-However, nothing else grants you permission to modify or distribute the
-Program or its derivative works. These actions are prohibited by law if you
-do not accept this License. Therefore, by modifying or distributing the
-Program (or any work based on the Program), you indicate your acceptance of
-this License to do so, and all its terms and conditions for copying,
-distributing or modifying the Program or works based on it.
+5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
-6. Each time you redistribute the Program (or any work based on the Program),
-the recipient automatically receives a license from the original licensor to
-copy, distribute or modify the Program subject to these terms and conditions.
-You may not impose any further restrictions on the recipients' exercise of the
-rights granted herein. You are not responsible for enforcing compliance by
-third parties to this License.
+6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
-7. If, as a consequence of a court judgment or allegation of patent
-infringement or for any other reason (not limited to patent issues),
-conditions are imposed on you (whether by court order, agreement or otherwise)
-that contradict the conditions of this License, they do not excuse you from
-the conditions of this License. If you cannot distribute so as to satisfy
-simultaneously your obligations under this License and any other pertinent
-obligations, then as a consequence you may not distribute the Program at all.
-For example, if a patent license would not permit royalty-free redistribution
-of the Program by all those who receive copies directly or indirectly through
-you, then the only way you could satisfy both it and this License would be to
-refrain entirely from distribution of the Program.
+7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.
- If any portion of this section is held invalid or unenforceable under any
-particular circumstance, the balance of the section is intended to apply and
-the section as a whole is intended to apply in other circumstances.
+ If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.
- It is not the purpose of this section to induce you to infringe any patents or
-other property right claims or to contest validity of any such claims; this
-section has the sole purpose of protecting the integrity of the free software
-distribution system, which is implemented by public license practices. Many
-people have made generous contributions to the wide range of software
-distributed through that system in reliance on consistent application of that
-system; it is up to the author/donor to decide if he or she is willing to
-distribute software through any other system and a licensee cannot impose that
-choice.
+ It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.
- This section is intended to make thoroughly clear what is believed to be a
-consequence of the rest of this License.
+ This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
-8. If the distribution and/or use of the Program is restricted in certain
-countries either by patents or by copyrighted interfaces, the original
-copyright holder who places the Program under this License may add an explicit
-geographical distribution limitation excluding those countries, so that
-distribution is permitted only in or among countries not thus excluded. In
-such case, this License incorporates the limitation as if written in the body
-of this License.
+8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
-9. The Free Software Foundation may publish revised and/or new versions of the
-General Public License from time to time. Such new versions will be similar
-in spirit to the present version, but may differ in detail to address new
-problems or concerns.
+9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
- Each version is given a distinguishing version number. If the Program
-specifies a version number of this License which applies to it and "any later
-version", you have the option of following the terms and conditions either of
-that version or of any later version published by the Free Software
-Foundation. If the Program does not specify a version number of this License,
-you may choose any version ever published by the Free Software Foundation.
+ Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.
-10. If you wish to incorporate parts of the Program into other free programs
-whose distribution conditions are different, write to the author to ask for
-permission. For software which is copyrighted by the Free Software
-Foundation, write to the Free Software Foundation; we sometimes make
-exceptions for this. Our decision will be guided by the two goals of
-preserving the free status of all derivatives of our free software and of
-promoting the sharing and reuse of software generally.
+10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
__NO WARRANTY__
-11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
-THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE
-STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE
-PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
-INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
-FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
-PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE,
-YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
-12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
-ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE
-THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
-GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE
-OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR
-DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR
-A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH
-HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
----
+
## License for wcslcat and wcslcpy
+`fish` also contains small amounts of code under the BSD license, namely versions of the two functions strlcat and strlcpy, modified for use with wide character strings. This code is copyrighted by Todd C. Miller.
-`fish` also contains small amounts of code under the BSD license, namely
-versions of the two functions strlcat and strlcpy, modified for use with wide
-character strings. This code is copyrighted by Todd C. Miller.
+Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
-Permission to use, copy, modify, and distribute this software for any purpose
-with or without fee is hereby granted, provided that the above copyright
-notice and this permission notice appear in all copies.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
-REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
-AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
-INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
-LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
-OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-PERFORMANCE OF THIS SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
----
+
## License for XSel
-
-The XSel command, written and copyrighted by Conrad Parker, is distributed
-together with `fish`.
+The XSel command, written and copyrighted by Conrad Parker, is distributed together with `fish`.
It is Copyright © 2001 Conrad Parker \
-Permission to use, copy, modify, distribute, and sell this software and its
-documentation for any purpose is hereby granted without fee, provided that the
-above copyright notice appear in all copies and that both that copyright
-notice and this permission notice appear in supporting documentation. No
-representations are made about the suitability of this software for any
-purpose. It is provided "as is"without express or implied warranty.
+Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. No representations are made about the suitability of this software for any purpose. It is provided "as is"without express or implied warranty.
----
+
## License for xdgmime and glibc
-The xdgmime library, written and copyrighted by Red Hat, Inc, is used by the
-mimedb command, which is a part of fish. It is released under the LGPL,
-version 2 or later, or under the Academic Free License, version 2. Version 2
-of the LGPL license agreement is included below.
+The xdgmime library, written and copyrighted by Red Hat, Inc, is used by the mimedb command, which is a part of fish. It is released under the LGPL, version 2 or later, or under the Academic Free License, version 2. Version 2 of the LGPL license agreement is included below.
-Fish contains code from the glibc library, namely the wcstok function. This
-code is licensed under the LGPL, version 2 or later. Version 2 of the LPGL
-license agreement is included below.
+Fish contains code from the glibc library, namely the wcstok function. This code is licensed under the LGPL, version 2 or later. Version 2 of the LPGL license agreement is included below.
## GNU LESSER GENERAL PUBLIC LICENSE
Version 2.1, February 1999
-
Copyright (C) 1991, 1999 Free Software Foundation, Inc.
51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
@@ -344,420 +151,146 @@ Version 2.1, February 1999
of this license document, but changing it is not allowed.
-[This is the first released version of the Lesser GPL. It also counts as the
-[successor of the GNU Library Public License, version 2, hence the version
-[number 2.1.]
+[This is the first released version of the Lesser GPL. It also counts as the successor of the GNU Library Public License, version 2, hence the version number 2.1.]
## Preamble
-The licenses for most software are designed to take away your freedom to share
-and change it. By contrast, the GNU General Public Licenses are intended to
-guarantee your freedom to share and change free software - to make sure the
-software is free for all its users.
+The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software - to make sure the software is free for all its users.
-This license, the Lesser General Public License, applies to some specially
-designated software packages - typically libraries - of the Free Software
-Foundation and other authors who decide to use it. You can use it too, but we
-suggest you first think carefully about whether this license or the ordinary
-General Public License is the better strategy to use in any particular case,
-based on the explanations below.
+This license, the Lesser General Public License, applies to some specially designated software packages - typically libraries - of the Free Software Foundation and other authors who decide to use it. You can use it too, but we suggest you first think carefully about whether this license or the ordinary General Public License is the better strategy to use in any particular case, based on the explanations below.
-When we speak of free software, we are referring to freedom of use, not price.
-Our General Public Licenses are designed to make sure that you have the
-freedom to distribute copies of free software (and charge for this service if
-you wish); that you receive source code or can get it if you want it; that you
-can change the software and use pieces of it in new free programs; and that
-you are informed that you can do these things.
+When we speak of free software, we are referring to freedom of use, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish); that you receive source code or can get it if you want it; that you can change the software and use pieces of it in new free programs; and that you are informed that you can do these things.
-To protect your rights, we need to make restrictions that forbid distributors
-to deny you these rights or to ask you to surrender these rights. These
-restrictions translate to certain responsibilities for you if you distribute
-copies of the library or if you modify it.
+To protect your rights, we need to make restrictions that forbid distributors to deny you these rights or to ask you to surrender these rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library or if you modify it.
-For example, if you distribute copies of the library, whether gratis or for a
-fee, you must give the recipients all the rights that we gave you. You must
-make sure that they, too, receive or can get the source code. If you link
-other code with the library, you must provide complete object files to the
-recipients, so that they can relink them with the library after making changes
-to the library and recompiling it. And you must show them these terms so they
-know their rights.
+For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link other code with the library, you must provide complete object files to the recipients, so that they can relink them with the library after making changes to the library and recompiling it. And you must show them these terms so they know their rights.
-We protect your rights with a two-step method: (1) we copyright the library,
-and (2) we offer you this license, which gives you legal permission to copy,
-distribute and/or modify the library.
+We protect your rights with a two-step method: (1) we copyright the library, and (2) we offer you this license, which gives you legal permission to copy, distribute and/or modify the library.
-To protect each distributor, we want to make it very clear that there is no
-warranty for the free library. Also, if the library is modified by someone
-else and passed on, the recipients should know that what they have is not the
-original version, so that the original author's reputation will not be
-affected by problems that might be introduced by others.
+To protect each distributor, we want to make it very clear that there is no warranty for the free library. Also, if the library is modified by someone else and passed on, the recipients should know that what they have is not the original version, so that the original author's reputation will not be affected by problems that might be introduced by others.
-Finally, software patents pose a constant threat to the existence of any free
-program. We wish to make sure that a company cannot effectively restrict the
-users of a free program by obtaining a restrictive license from a patent
-holder. Therefore, we insist that any patent license obtained for a version
-of the library must be consistent with the full freedom of use specified in
-this license.
+Finally, software patents pose a constant threat to the existence of any free program. We wish to make sure that a company cannot effectively restrict the users of a free program by obtaining a restrictive license from a patent holder. Therefore, we insist that any patent license obtained for a version of the library must be consistent with the full freedom of use specified in this license.
-Most GNU software, including some libraries, is covered by the ordinary GNU
-General Public License. This license, the GNU Lesser General Public License,
-applies to certain designated libraries, and is quite different from the
-ordinary General Public License. We use this license for certain libraries in
-order to permit linking those libraries into non-free programs.
+Most GNU software, including some libraries, is covered by the ordinary GNU General Public License. This license, the GNU Lesser General Public License, applies to certain designated libraries, and is quite different from the ordinary General Public License. We use this license for certain libraries in order to permit linking those libraries into non-free programs.
-When a program is linked with a library, whether statically or using a shared
-library, the combination of the two is legally speaking a combined work, a
-derivative of the original library. The ordinary General Public License
-therefore permits such linking only if the entire combination fits its
-criteria of freedom. The Lesser General Public License permits more lax
-criteria for linking other code with the library.
+When a program is linked with a library, whether statically or using a shared library, the combination of the two is legally speaking a combined work, a derivative of the original library. The ordinary General Public License therefore permits such linking only if the entire combination fits its criteria of freedom. The Lesser General Public License permits more lax criteria for linking other code with the library.
-We call this license the "Lesser" General Public License because it does Less
-to protect the user's freedom than the ordinary General Public License. It
-also provides other free software developers Less of an advantage over
-competing non-free programs. These disadvantages are the reason we use the
-ordinary General Public License for many libraries. However, the Lesser
-license provides advantages in certain special circumstances.
+We call this license the "Lesser" General Public License because it does Less to protect the user's freedom than the ordinary General Public License. It also provides other free software developers Less of an advantage over competing non-free programs. These disadvantages are the reason we use the ordinary General Public License for many libraries. However, the Lesser license provides advantages in certain special circumstances.
-For example, on rare occasions, there may be a special need to encourage the
-widest possible use of a certain library, so that it becomes a de-facto
-standard. To achieve this, non-free programs must be allowed to use the
-library. A more frequent case is that a free library does the same job as
-widely used non-free libraries. In this case, there is little to gain by
-limiting the free library to free software only, so we use the Lesser General
-Public License.
+For example, on rare occasions, there may be a special need to encourage the widest possible use of a certain library, so that it becomes a de-facto standard. To achieve this, non-free programs must be allowed to use the library. A more frequent case is that a free library does the same job as widely used non-free libraries. In this case, there is little to gain by limiting the free library to free software only, so we use the Lesser General Public License.
-In other cases, permission to use a particular library in non-free programs
-enables a greater number of people to use a large body of free software. For
-example, permission to use the GNU C Library in non-free programs enables many
-more people to use the whole GNU operating system, as well as its variant, the
-GNU/Linux operating system.
+In other cases, permission to use a particular library in non-free programs enables a greater number of people to use a large body of free software. For example, permission to use the GNU C Library in non-free programs enables many more people to use the whole GNU operating system, as well as its variant, the GNU/Linux operating system.
-Although the Lesser General Public License is Less protective of the users'
-freedom, it does ensure that the user of a program that is linked with the
-Library has the freedom and the wherewithal to run that program using a
-modified version of the Library.
+Although the Lesser General Public License is Less protective of the users'freedom, it does ensure that the user of a program that is linked with the Library has the freedom and the wherewithal to run that program using a modified version of the Library.
+
+The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a "work based on the library" and a "work that uses the library". The former contains code derived from the library, whereas the latter must be combined with the library in order to run.
-The precise terms and conditions for copying, distribution and modification
-follow. Pay close attention to the difference between a "work based on the
-library" and a "work that uses the library". The former contains code derived
-from the library, whereas the latter must be combined with the library in
-order to run.
## TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-- This License Agreement applies to any software library or other program which
-contains a notice placed by the copyright holder or other authorized party
-saying it may be distributed under the terms of this Lesser General Public
-License (also called "this License"). Each licensee is addressed as "you".
+- This License Agreement applies to any software library or other program which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Lesser General Public License (also called "this License"). Each licensee is addressed as "you".
- A "library" means a collection of software functions and/or data prepared so
-as to be conveniently linked with application programs (which use some of
-those functions and data) to form executables.
+ A "library" means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables.
- The "Library", below, refers to any such software library or work which has
-been distributed under these terms. A "work based on the Library" means
-either the Library or any derivative work under copyright law: that is to say,
-a work containing the Library or a portion of it, either verbatim or with
-modifications and/or translated straightforwardly into another language.
-(Hereinafter, translation is included without limitation in the term
-"modification".)
+ The "Library", below, refers to any such software library or work which has been distributed under these terms. A "work based on the Library" means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term "modification".)
- "Source code for a work means the preferred form of the work for making
-"modifications to it. For a library, complete source code means all the
-"source code for all modules it contains, plus any associated interface
-"definition files, plus the scripts used to control compilation and
-"installation of the library.
+ "Source code for a work" means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library.
- Activities other than copying, distribution and modification are not covered
-by this License; they are outside its scope. The act of running a program
-using the Library is not restricted, and output from such a program is covered
-only if its contents constitute a work based on the Library (independent of
-the use of the Library in a tool for writing it). Whether that is true
-depends on what the Library does and what the program that uses the Library
-does.
+ Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does.
-1. You may copy and distribute verbatim copies of the Library's complete
-source code as you receive it, in any medium, provided that you conspicuously
-and appropriately publish on each copy an appropriate copyright notice and
-disclaimer of warranty; keep intact all the notices that refer to this License
-and to the absence of any warranty; and distribute a copy of this License
-along with the Library.
+1. You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library.
- You may charge a fee for the physical act of transferring a copy, and you may
-at your option offer warranty protection in exchange for a fee.
+ You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
-2. You may modify your copy or copies of the Library or any portion of it,
-thus forming a work based on the Library, and copy and distribute such
-modifications or work under the terms of Section 1 above, provided that you
-also meet all of these conditions:
+2. You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
-# The modified work must itself be a software library.
- -# You must cause the files modified to carry prominent notices stating that
-you changed the files and the date of any change.
+ -# You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change.
- -# You must cause the whole of the work to be licensed at no charge to all
-third parties under the terms of this License.
+ -# You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License.
- -# If a facility in the modified Library refers to a function or a table of
-data to be supplied by an application program that uses the facility, other
-than as an argument passed when the facility is invoked, then you must make
-a good faith effort to ensure that, in the event an application does not
-supply such function or table, the facility still operates, and performs
-whatever part of its purpose remains meaningful.
+ -# If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful.
- (For example, a function in a library to compute square roots has a purpose
-that is entirely well-defined independent of the application. Therefore,
-Subsection 2d requires that any application-supplied function or table used
-by this function must be optional: if the application does not supply it, the
-square root function must still compute square roots.)
+ (For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.)
- These requirements apply to the modified work as a whole. If identifiable
-sections of that work are not derived from the Library, and can be reasonably
-considered independent and separate works in themselves, then this License,
-and its terms, do not apply to those sections when you distribute them as
-separate works. But when you distribute the same sections as part of a whole
-which is a work based on the Library, the distribution of the whole must be on
-the terms of this License, whose permissions for other licensees extend to the
-entire whole, and thus to each and every part regardless of who wrote it.
+ These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.
- Thus, it is not the intent of this section to claim rights or contest your
-rights to work written entirely by you; rather, the intent is to exercise the
-right to control the distribution of derivative or collective works based on
-the Library.
+ Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library.
- In addition, mere aggregation of another work not based on the Library with
-the Library (or with a work based on the Library) on a volume of a storage or
-distribution medium does not bring the other work under the scope of this
-License.
+ In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
-3. You may opt to apply the terms of the ordinary GNU General Public License
-instead of this License to a given copy of the Library. To do this, you must
-alter all the notices that refer to this License, so that they refer to the
-ordinary GNU General Public License, version 2, instead of to this License.
-(If a newer version than version 2 of the ordinary GNU General Public License
-has appeared, then you can specify that version instead if you wish.) Do not
-make any other change in these notices.
+3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices.
- Once this change is made in a given copy, it is irreversible for that copy, so
-the ordinary GNU General Public License applies to all subsequent copies and
-derivative works made from that copy.
+ Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy.
- This option is useful when you wish to copy part of the code of the Library
-into a program that is not a library.
+ This option is useful when you wish to copy part of the code of the Library into a program that is not a library.
-4. You may copy and distribute the Library (or a portion or derivative of it,
-under Section 2) in object code or executable form under the terms of Sections
-1 and 2 above provided that you accompany it with the complete corresponding
-machine-readable source code, which must be distributed under the terms of
-Sections 1 and 2 above on a medium customarily used for software interchange.
+4. You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange.
- If distribution of object code is made by offering access to copy from a
-designated place, then offering equivalent access to copy the source code from
-the same place satisfies the requirement to distribute the source code, even
-though third parties are not compelled to copy the source along with the
-object code.
+ If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code.
-5. A program that contains no derivative of any portion of the Library, but is
-designed to work with the Library by being compiled or linked with it, is
-called a "work that uses the Library". Such a work, in isolation, is not a
-derivative work of the Library, and therefore falls outside the scope of this
-License.
+5. A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a "work that uses the Library". Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License.
- However, linking a "work that uses the Library" with the Library creates an
-executable that is a derivative of the Library (because it contains portions
-of the Library), rather than a "work that uses the library". The executable
-is therefore covered by this License. Section 6 states terms for distribution
-of such executables.
+ However, linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a "work that uses the library". The executable is therefore covered by this License. Section 6 states terms for distribution of such executables.
- When a "work that uses the Library" uses material from a header file that is
-part of the Library, the object code for the work may be a derivative work of
-the Library even though the source code is not. Whether this is true is
-especially significant if the work can be linked without the Library, or if
-the work is itself a library. The threshold for this to be true is not
-precisely defined by law.
+ When a "work that uses the Library" uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law.
- If such an object file uses only numerical parameters, data structure layouts
-and accessors, and small macros and small inline functions (ten lines or less
-in length), then the use of the object file is unrestricted, regardless of
-whether it is legally a derivative work. (Executables containing this object
-code plus portions of the Library will still fall under Section 6.)
+ If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.)
- Otherwise, if the work is a derivative of the Library, you may distribute the
-object code for the work under the terms of Section 6. Any executables
-containing that work also fall under Section 6, whether or not they are linked
-directly with the Library itself.
+ Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself.
-6. As an exception to the Sections above, you may also combine or link a "work
-that uses the Library" with the Library to produce a work containing portions
-of the Library, and distribute that work under terms of your choice, provided
-that the terms permit modification of the work for the customer's own use and
-reverse engineering for debugging such modifications.
+6. As an exception to the Sections above, you may also combine or link a "work that uses the Library" with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the customer's own use and reverse engineering for debugging such modifications.
- You must give prominent notice with each copy of the work that the Library is
-used in it and that the Library and its use are covered by this License. You
-must supply a copy of this License. If the work during execution displays
-copyright notices, you must include the copyright notice for the Library among
-them, as well as a reference directing the user to the copy of this License.
-Also, you must do one of these things:
+ You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things:
- -# Accompany the work with the complete corresponding machine-readable source
-code for the Library including whatever changes were used in the work
-(which must be distributed under Sections 1 and 2 above); and, if the work
-is an executable linked with the Library, with the complete machine-
-readable "work that uses the Library", as object code and/or source code,
-so that the user can modify the Library and then relink to produce a
-modified executable containing the modified Library. (It is understood
-that the user who changes the contents of definitions files in the Library
-will not necessarily be able to recompile the application to use the
-modified definitions.)
+ -# Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine- readable "work that uses the Library", as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.)
- -# Use a suitable shared library mechanism for linking with the Library. A
-suitable mechanism is one that (1) uses at run time a copy of the library
-already present on the user's computer system, rather than copying library
-functions into the executable, and (2) will operate properly with a
-modified version of the library, if the user installs one, as long as the
-modified version is interface-compatible with the version that the work was
-made with.
+ -# Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (1) uses at run time a copy of the library already present on the user's computer system, rather than copying library functions into the executable, and (2) will operate properly with a modified version of the library, if the user installs one, as long as the modified version is interface-compatible with the version that the work was made with.
- -# Accompany the work with a written offer, valid for at least three years, to
-give the same user the materials specified in Subsection 6a, above, for a
-charge no more than the cost of performing this distribution.
+ -# Accompany the work with a written offer, valid for at least three years, to give the same user the materials specified in Subsection 6a, above, for a charge no more than the cost of performing this distribution.
- -# If distribution of the work is made by offering access to copy from a
-designated place, offer equivalent access to copy the above specified
-materials from the same place.
+ -# If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place.
- -# Verify that the user has already received a copy of these materials or that
-you have already sent this user a copy.
+ -# Verify that the user has already received a copy of these materials or that you have already sent this user a copy.
- For an executable, the required form of the "work that uses the Library" must
-include any data and utility programs needed for reproducing the executable
-from it. However, as a special exception, the materials to be distributed
-need not include anything that is normally distributed (in either source or
-binary form) with the major components (compiler, kernel, and so on) of the
-operating system on which the executable runs, unless that component itself
-accompanies the executable.
+ For an executable, the required form of the "work that uses the Library" must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the materials to be distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.
- It may happen that this requirement contradicts the license restrictions of
-other proprietary libraries that do not normally accompany the operating
-system. Such a contradiction means you cannot use both them and the Library
-together in an executable that you distribute.
+ It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute.
-7. You may place library facilities that are a work based on the Library side-
-by-side in a single library together with other library facilities not covered
-by this License, and distribute such a combined library, provided that the
-separate distribution of the work based on the Library and of the other
-library facilities is otherwise permitted, and provided that you do these two
-things:
+7. You may place library facilities that are a work based on the Library side- by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things:
- -# Accompany the combined library with a copy of the same work based on the
-Library, uncombined with any other library facilities. This must be
-distributed under the terms of the Sections above.
+ -# Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities. This must be distributed under the terms of the Sections above.
- -# Give prominent notice with the combined library of the fact that part of it
-is a work based on the Library, and explaining where to find the
-accompanying uncombined form of the same work.
+ -# Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work.
-8. You may not copy, modify, sublicense, link with, or distribute the Library
-except as expressly provided under this License. Any attempt otherwise to
-copy, modify, sublicense, link with, or distribute the Library is void, and
-will automatically terminate your rights under this License. However, parties
-who have received copies, or rights, from you under this License will not have
-their licenses terminated so long as such parties remain in full compliance.
+8. You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
-9. You are not required to accept this License, since you have not signed it.
-However, nothing else grants you permission to modify or distribute the
-Library or its derivative works. These actions are prohibited by law if you
-do not accept this License. Therefore, by modifying or distributing the
-Library (or any work based on the Library), you indicate your acceptance of
-this License to do so, and all its terms and conditions for copying,
-distributing or modifying the Library or works based on it.
+9. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Library (or any work based on the Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it.
-10. Each time you redistribute the Library (or any work based on the Library),
-the recipient automatically receives a license from the original licensor to
-copy, distribute, link with or modify the Library subject to these terms and
-conditions. You may not impose any further restrictions on the recipients'
-exercise of the rights granted herein. You are not responsible for enforcing
-compliance by third parties with this License.
+10. Each time you redistribute the Library (or any work based on the Library), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients'exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties with this License.
-11. If, as a consequence of a court judgment or allegation of patent
-infringement or for any other reason (not limited to patent issues),
-conditions are imposed on you (whether by court order, agreement or otherwise)
-that contradict the conditions of this License, they do not excuse you from
-the conditions of this License. If you cannot distribute so as to satisfy
-simultaneously your obligations under this License and any other pertinent
-obligations, then as a consequence you may not distribute the Library at all.
-For example, if a patent license would not permit royalty-free redistribution
-of the Library by all those who receive copies directly or indirectly through
-you, then the only way you could satisfy both it and this License would be to
-refrain entirely from distribution of the Library.
+11. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library.
- If any portion of this section is held invalid or unenforceable under any
-particular circumstance, the balance of the section is intended to apply, and
-the section as a whole is intended to apply in other circumstances.
+ If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances.
- It is not the purpose of this section to induce you to infringe any patents or
-other property right claims or to contest validity of any such claims; this
-section has the sole purpose of protecting the integrity of the free software
-distribution system which is implemented by public license practices. Many
-people have made generous contributions to the wide range of software
-distributed through that system in reliance on consistent application of that
-system; it is up to the author/donor to decide if he or she is willing to
-distribute software through any other system and a licensee cannot impose that
-choice.
+ It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.
- This section is intended to make thoroughly clear what is believed to be a
-consequence of the rest of this License.
+ This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
-12. If the distribution and/or use of the Library is restricted in certain
-countries either by patents or by copyrighted interfaces, the original
-copyright holder who places the Library under this License may add an explicit
-geographical distribution limitation excluding those countries, so that
-distribution is permitted only in or among countries not thus excluded. In
-such case, this License incorporates the limitation as if written in the body
-of this License.
+12. If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
-13. The Free Software Foundation may publish revised and/or new versions of
-the Lesser General Public License from time to time. Such new versions will be
-similar in spirit to the present version, but may differ in detail to address
-new problems or concerns.
+13. The Free Software Foundation may publish revised and/or new versions of the Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
- Each version is given a distinguishing version number. If the Library
-specifies a version number of this License which applies to it and "any later
-version", you have the option of following the terms and conditions either of
-that version or of any later version published by the Free Software
-Foundation. If the Library does not specify a license version number, you may
-choose any version ever published by the Free Software Foundation.
+ Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation.
-14. If you wish to incorporate parts of the Library into other free programs
-whose distribution conditions are incompatible with these, write to the author
-to ask for permission. For software which is copyrighted by the Free Software
-Foundation, write to the Free Software Foundation; we sometimes make
-exceptions for this. Our decision will be guided by the two goals of
-preserving the free status of all derivatives of our free software and of
-promoting the sharing and reuse of software generally.
+14. If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
__NO WARRANTY__
-15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
-THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE
-STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE
-LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
-INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
-FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
-PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE,
-YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
-16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
-ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE
-THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
-GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE
-OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR
-DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR
-A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH
-HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
----
@@ -765,9 +298,7 @@ HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
## License for printf
-Copyright © 1990-2007 Free Software Foundation, Inc. Printf (from GNU
-Coreutils 6.9) is released under the GNU General Public License, version 2.
-The license agreement is included below.
+Copyright © 1990-2007 Free Software Foundation, Inc. Printf (from GNU Coreutils 6.9) is released under the GNU General Public License, version 2. The license agreement is included below.
# GNU GENERAL PUBLIC LICENSE
@@ -785,257 +316,86 @@ Version 2, June 1991
## Preamble
-The licenses for most software are designed to take away your freedom to share
-and change it. By contrast, the GNU General Public License is intended to
-guarantee your freedom to share and change free software - to make sure the
-software is free for all its users. This General Public License applies to
-most of the Free Software Foundation's software and to any other program whose
-authors commit to using it. (Some other Free Software Foundation software is
-covered by the GNU Library General Public License instead.) You can apply it
-to your programs, too.
+The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software - to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.
-When we speak of free software, we are referring to freedom, not price. Our
-General Public Licenses are designed to make sure that you have the freedom to
-distribute copies of free software (and charge for this service if you wish),
-that you receive source code or can get it if you want it, that you can change
-the software or use pieces of it in new free programs; and that you know you
-can do these things.
+When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.
-To protect your rights, we need to make restrictions that forbid anyone to
-deny you these rights or to ask you to surrender the rights. These
-restrictions translate to certain responsibilities for you if you distribute
-copies of the software, or if you modify it.
+To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.
-For example, if you distribute copies of such a program, whether gratis or for
-a fee, you must give the recipients all the rights that you have. You must
-make sure that they, too, receive or can get the source code. And you must
-show them these terms so they know their rights.
+For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
-We protect your rights with two steps: (1) copyright the software, and (2)
-offer you this license which gives you legal permission to copy, distribute
-and/or modify the software.
+We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.
-Also, for each author's protection and ours, we want to make certain that
-everyone understands that there is no warranty for this free software. If the
-software is modified by someone else and passed on, we want its recipients to
-know that what they have is not the original, so that any problems introduced
-by others will not reflect on the original authors' reputations.
+Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.
-Finally, any free program is threatened constantly by software patents. We
-wish to avoid the danger that redistributors of a free program will
-individually obtain patent licenses, in effect making the program proprietary.
-To prevent this, we have made it clear that any patent must be licensed for
-everyone's free use or not licensed at all.
+Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.
-The precise terms and conditions for copying, distribution and modification
-follow.
+The precise terms and conditions for copying, distribution and modification follow.
## TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-- This License applies to any program or other work which contains a notice
-placed by the copyright holder saying it may be distributed under the terms of
-this General Public License. The "Program", below, refers to any such program
-or work, and a "work based on the Program" means either the Program or any
-derivative work under copyright law: that is to say, a work containing the
-Program or a portion of it, either verbatim or with modifications and/or
-translated into another language. (Hereinafter, translation is included
-without limitation in the term "modification".) Each licensee is addressed as
-"you".
+- This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".
- Activities other than copying, distribution and modification are not covered
-by this License; they are outside its scope. The act of running the Program
-is not restricted, and the output from the Program is covered only if its
-contents constitute a work based on the Program (independent of having been
-made by running the Program). Whether that is true depends on what the Program
-does.
+ Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.
-1. You may copy and distribute verbatim copies of the Program's source code as
-you receive it, in any medium, provided that you conspicuously and
-appropriately publish on each copy an appropriate copyright notice and
-disclaimer of warranty; keep intact all the notices that refer to this License
-and to the absence of any warranty; and give any other recipients of the
-Program a copy of this License along with the Program.
+1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.
- You may charge a fee for the physical act of transferring a copy, and you may
-at your option offer warranty protection in exchange for a fee.
+ You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
-2. You may modify your copy or copies of the Program or any portion of it,
-thus forming a work based on the Program, and copy and distribute such
-modifications or work under the terms of Section 1 above, provided that you
-also meet all of these conditions:
+2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
- -# You must cause the modified files to carry prominent notices stating
-that you changed the files and the date of any change.
+ -# You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
- -# You must cause any work that you distribute or publish, that in whole or
-in part contains or is derived from the Program or any part thereof, to be
-licensed as a whole at no charge to all third parties under the terms of this
-License.
+ -# You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
- -# If the modified program normally reads commands interactively when run,
-you must cause it, when started running for such interactive use in the most
-ordinary way, to print or display an announcement including an appropriate
-copyright notice and a notice that there is no warranty (or else, saying that
-you provide a warranty) and that users may redistribute the program under
-these conditions, and telling the user how to view a copy of this License.
-(Exception: if the Program itself is interactive but does not normally print
-such an announcement, your work based on the Program is not required to print
-an announcement.)
+ -# If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)
- These requirements apply to the modified work as a whole. If identifiable
-sections of that work are not derived from the Program, and can be reasonably
-considered independent and separate works in themselves, then this License,
-and its terms, do not apply to those sections when you distribute them as
-separate works. But when you distribute the same sections as part of a whole
-which is a work based on the Program, the distribution of the whole must be on
-the terms of this License, whose permissions for other licensees extend to the
-entire whole, and thus to each and every part regardless of who wrote it.
+ These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.
- Thus, it is not the intent of this section to claim rights or contest your
-rights to work written entirely by you; rather, the intent is to exercise the
-right to control the distribution of derivative or collective works based on
-the Program.
+ Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.
- In addition, mere aggregation of another work not based on the Program with
-the Program (or with a work based on the Program) on a volume of a storage or
-distribution medium does not bring the other work under the scope of this
-License.
+ In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
-3. You may copy and distribute the Program (or a work based on it, under
-Section 2) in object code or executable form under the terms of Sections 1 and
-2 above provided that you also do one of the following:
+3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
- -# Accompany it with the complete corresponding machine-readable source code,
-which must be distributed under the terms of Sections 1 and 2 above on a
-medium customarily used for software interchange; or,
+ -# Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
- -# Accompany it with a written offer, valid for at least three years, to give
-any third party, for a charge no more than your cost of physically
-performing source distribution, a complete machine-readable copy of the
-corresponding source code, to be distributed under the terms of Sections 1
-and 2 above on a medium customarily used for software interchange; or,
+ -# Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
- -# Accompany it with the information you received as to the offer to
-distribute corresponding source code. (This alternative is allowed only
-for noncommercial distribution and only if you received the program in
-object code or executable form with such an offer, in accord with
-Subsection b above.)
+ -# Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)
- The source code for a work means the preferred form of the work for making
-modifications to it. For an executable work, complete source code means all
-the source code for all modules it contains, plus any associated interface
-definition files, plus the scripts used to control compilation and
-installation of the executable. However, as a special exception, the source
-code distributed need not include anything that is normally distributed (in
-either source or binary form) with the major components (compiler, kernel, and
-so on) of the operating system on which the executable runs, unless that
-component itself accompanies the executable.
+ The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.
- If distribution of executable or object code is made by offering access to
-copy from a designated place, then offering equivalent access to copy the
-source code from the same place counts as distribution of the source code,
-even though third parties are not compelled to copy the source along with the
-object code.
+ If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.
-4. You may not copy, modify, sublicense, or distribute the Program except as
-expressly provided under this License. Any attempt otherwise to copy, modify,
-sublicense or distribute the Program is void, and will automatically terminate
-your rights under this License. However, parties who have received copies, or
-rights, from you under this License will not have their licenses terminated so
-long as such parties remain in full compliance.
+4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
-5. You are not required to accept this License, since you have not signed it.
-However, nothing else grants you permission to modify or distribute the
-Program or its derivative works. These actions are prohibited by law if you
-do not accept this License. Therefore, by modifying or distributing the
-Program (or any work based on the Program), you indicate your acceptance of
-this License to do so, and all its terms and conditions for copying,
-distributing or modifying the Program or works based on it.
+5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
-6. Each time you redistribute the Program (or any work based on the Program),
-the recipient automatically receives a license from the original licensor to
-copy, distribute or modify the Program subject to these terms and conditions.
-You may not impose any further restrictions on the recipients' exercise of the
-rights granted herein. You are not responsible for enforcing compliance by
-third parties to this License.
+6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
-7. If, as a consequence of a court judgment or allegation of patent
-infringement or for any other reason (not limited to patent issues),
-conditions are imposed on you (whether by court order, agreement or otherwise)
-that contradict the conditions of this License, they do not excuse you from
-the conditions of this License. If you cannot distribute so as to satisfy
-simultaneously your obligations under this License and any other pertinent
-obligations, then as a consequence you may not distribute the Program at all.
-For example, if a patent license would not permit royalty-free redistribution
-of the Program by all those who receive copies directly or indirectly through
-you, then the only way you could satisfy both it and this License would be to
-refrain entirely from distribution of the Program.
+7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.
- If any portion of this section is held invalid or unenforceable under any
-particular circumstance, the balance of the section is intended to apply and
-the section as a whole is intended to apply in other circumstances.
+ If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.
- It is not the purpose of this section to induce you to infringe any patents or
-other property right claims or to contest validity of any such claims; this
-section has the sole purpose of protecting the integrity of the free software
-distribution system, which is implemented by public license practices. Many
-people have made generous contributions to the wide range of software
-distributed through that system in reliance on consistent application of that
-system; it is up to the author/donor to decide if he or she is willing to
-distribute software through any other system and a licensee cannot impose that
-choice.
+ It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.
- This section is intended to make thoroughly clear what is believed to be a
-consequence of the rest of this License.
+ This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
-8. If the distribution and/or use of the Program is restricted in certain
-countries either by patents or by copyrighted interfaces, the original
-copyright holder who places the Program under this License may add an explicit
-geographical distribution limitation excluding those countries, so that
-distribution is permitted only in or among countries not thus excluded. In
-such case, this License incorporates the limitation as if written in the body
-of this License.
+8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
-9. The Free Software Foundation may publish revised and/or new versions of the
-General Public License from time to time. Such new versions will be similar
-in spirit to the present version, but may differ in detail to address new
-problems or concerns.
+9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
- Each version is given a distinguishing version number. If the Program
-specifies a version number of this License which applies to it and "any later
-version", you have the option of following the terms and conditions either of
-that version or of any later version published by the Free Software
-Foundation. If the Program does not specify a version number of this License,
-you may choose any version ever published by the Free Software Foundation.
+ Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.
-10. If you wish to incorporate parts of the Program into other free programs
-whose distribution conditions are different, write to the author to ask for
-permission. For software which is copyrighted by the Free Software
-Foundation, write to the Free Software Foundation; we sometimes make
-exceptions for this. Our decision will be guided by the two goals of
-preserving the free status of all derivatives of our free software and of
-promoting the sharing and reuse of software generally.
+10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
__NO WARRANTY__
-11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
-THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE
-STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE
-PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
-INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
-FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
-PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE,
-YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
-12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
-ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE
-THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
-GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE
-OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR
-DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR
-A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH
-HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
----
@@ -1045,17 +405,9 @@ HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Copyright © 2007 Alexey Vatchenko \
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
-REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
-AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
-INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
-LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
-OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-PERFORMANCE OF THIS SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
\htmlonly[block]
diff --git a/doc_src/math.txt b/doc_src/math.txt
index 3b984fc08..994f15152 100644
--- a/doc_src/math.txt
+++ b/doc_src/math.txt
@@ -8,21 +8,13 @@ math EXPRESSION
\subsection math-description Description
-`math` is used to perform mathematical calculations. It is a very
-thin wrapper for the bc program, which makes it possible to specify an
-expression from the command line without using non-standard extensions
-or a pipeline.
+`math` is used to perform mathematical calculations. It is a very thin wrapper for the bc program, which makes it possible to specify an expression from the command line without using non-standard extensions or a pipeline.
+
+For a description of the syntax supported by math, see the manual for the bc program. Keep in mind that parameter expansion takes place on any expressions before they are evaluated. This can be very useful in order to perform calculations involving shell variables or the output of command substitutions, but it also means that parenthesis have to be escaped.
-For a description of the syntax supported by math, see the manual for
-the bc program. Keep in mind that parameter expansion takes place on
-any expressions before they are evaluated. This can be very useful in
-order to perform calculations involving shell variables or the
-output of command substitutions, but it also means that parenthesis
-have to be escaped.
\subsection math-example Examples
`math 1+1` outputs 2.
-`math $status-128` outputs the numerical exit status of the
-last command minus 128.
+`math $status-128` outputs the numerical exit status of the last command minus 128.
diff --git a/doc_src/mimedb.txt b/doc_src/mimedb.txt
index d65fd6ba6..b7ec29cee 100644
--- a/doc_src/mimedb.txt
+++ b/doc_src/mimedb.txt
@@ -7,22 +7,24 @@ mimedb [OPTIONS] FILES...
\subsection mimedb-description Description
-\c mimedb queries the MIME type database and the `.desktop` files
-installed on the system in order to find information on
-the files listed in `FILES`. The information that `mimedb`
-can retrieve includes the MIME type for a file, a description of the type,
-and the default action that can be performed on the file. `mimedb` can also
-be used to launch the default action for this file.
+`mimedb` queries the MIME type database and the `.desktop` files installed on the system in order to find information on the files listed in `FILES`. The information that `mimedb` can retrieve includes the MIME type for a file, a description of the type, and the default action that can be performed on the file. `mimedb` can also be used to launch the default action for this file.
The following options are available:
- `-t`, `--input-file-data` determines the files' type both by their filename and by their contents (default behaviour).
-- `-f`, `--input-filename` determines the files' type by their filename.
-- `-i`, `--input-mime` specifies that the arguments are not files, but MIME types.
-- `-m`, `--output-mime` outputs the MIME type of each file (default behaviour).
-- `-f`, `--output-description` outputs the description of each MIME type.
-- `-a`, `--output-action` outputs the default action of each MIME type.
-- `-l`, `--launch` launches the default action for the specified files.
-- `-h`, `--help` displays a help message and exit.
-- `-v`, `--version` displays the version number and exits.
+- `-f`, `--input-filename` determines the files' type by their filename.
+
+- `-i`, `--input-mime` specifies that the arguments are not files, but MIME types.
+
+- `-m`, `--output-mime` outputs the MIME type of each file (default behaviour).
+
+- `-f`, `--output-description` outputs the description of each MIME type.
+
+- `-a`, `--output-action` outputs the default action of each MIME type.
+
+- `-l`, `--launch` launches the default action for the specified files.
+
+- `-h`, `--help` displays a help message and exit.
+
+- `-v`, `--version` displays the version number and exits.
diff --git a/doc_src/nextd.txt b/doc_src/nextd.txt
index 217042b15..96daf18ce 100644
--- a/doc_src/nextd.txt
+++ b/doc_src/nextd.txt
@@ -6,11 +6,11 @@ nextd [-l | --list] [POS]
\endfish
\subsection nextd-description Description
-`nextd` moves forwards `POS` positions in the history of visited
-directories; if the end of the history has been hit, a warning is printed.
-If the `-l` or `--list` flag is specified, the current
-directory history is also displayed.
+`nextd` moves forwards `POS` positions in the history of visited directories; if the end of the history has been hit, a warning is printed.
+
+If the `-l` or `--list` flag is specified, the current directory history is also displayed.
+
\subsection nextd-example Example
diff --git a/doc_src/not.txt b/doc_src/not.txt
index b0d893f74..7848d2dc9 100644
--- a/doc_src/not.txt
+++ b/doc_src/not.txt
@@ -7,8 +7,8 @@ not COMMAND [OPTIONS...]
\subsection not-description Description
-`not` negates the exit status of another command. If the exit status
-is zero, `not` returns 1. Otherwise, `not` returns 0.
+`not` negates the exit status of another command. If the exit status is zero, `not` returns 1. Otherwise, `not` returns 0.
+
\subsection not-example Example
diff --git a/doc_src/open.txt b/doc_src/open.txt
index 48c71cac7..85e91e729 100644
--- a/doc_src/open.txt
+++ b/doc_src/open.txt
@@ -9,6 +9,7 @@ open FILES...
`open` opens a file in its default application, using the `xdg-open` command if it exists, or else the mimedb command.
+
\subsection open-example Example
`open *.txt` opens all the text files in the current directory using your system's default text editor.
diff --git a/doc_src/or.txt b/doc_src/or.txt
index 0d11129b4..1cd1d768e 100644
--- a/doc_src/or.txt
+++ b/doc_src/or.txt
@@ -7,23 +7,17 @@ COMMAND1; or COMMAND2
\subsection or-description Description
-`or` is used to execute a command if the current exit
-status (as set by the last previous command) is not 0.
+`or` is used to execute a command if the current exit status (as set by the last previous command) is not 0.
`or` does not change the current exit status.
-The exit status of the last foreground command to exit can always be
-accessed using the $status
-variable.
+The exit status of the last foreground command to exit can always be accessed using the $status variable.
+
\subsection or-example Example
-The following code runs the `make` command to build a program. If the
-build succeeds, the program is installed. If either step fails,
-`make clean` is run, which removes the files created by the
-build process.
+The following code runs the `make` command to build a program. If the build succeeds, the program is installed. If either step fails, `make clean` is run, which removes the files created by the build process.
\fish
make; and make install; or make clean
\endfish
-
diff --git a/doc_src/popd.txt b/doc_src/popd.txt
index f160f43d4..928168352 100644
--- a/doc_src/popd.txt
+++ b/doc_src/popd.txt
@@ -7,9 +7,8 @@ popd
\subsection popd-description Description
-`popd` removes the top directory from the directory stack and
-changes the working directory to the new top directory. Use `pushd` to add directories to the stack.
+`popd` removes the top directory from the directory stack and changes the working directory to the new top directory. Use `pushd` to add directories to the stack.
+
\subsection popd-example Example
diff --git a/doc_src/prevd.txt b/doc_src/prevd.txt
index 557f6c98a..cd0c99ac4 100644
--- a/doc_src/prevd.txt
+++ b/doc_src/prevd.txt
@@ -7,12 +7,10 @@ prevd [ -l | --list ] [POS]
\subsection prevd-description Description
-`prevd` moves backwards `POS` positions in the history
-of visited directories; if the beginning of the history has been hit,
-a warning is printed.
+`prevd` moves backwards `POS` positions in the history of visited directories; if the beginning of the history has been hit, a warning is printed.
+
+If the `-l` or `--list` flag is specified, the current history is also displayed.
-If the `-l` or `--list` flag is specified, the current
-history is also displayed.
\subsection prevd-example Example
diff --git a/doc_src/psub.txt b/doc_src/psub.txt
index be812f4ad..12f1b620a 100644
--- a/doc_src/psub.txt
+++ b/doc_src/psub.txt
@@ -7,20 +7,10 @@ COMMAND1 (COMMAND2 | psub [-f])
\subsection psub-description Description
-Posix shells feature a syntax that is a mix between command
-substitution and piping, called process substitution. It is used to
-send the output of a command into the calling command, much like
-command substitution, but with the difference that the output is not
-sent through commandline arguments but through a named pipe, with the
-filename of the named pipe sent as an argument to the calling
-program. `psub` combined with a
-regular command substitution provides the same functionality.
+Posix shells feature a syntax that is a mix between command substitution and piping, called process substitution. It is used to send the output of a command into the calling command, much like command substitution, but with the difference that the output is not sent through commandline arguments but through a named pipe, with the filename of the named pipe sent as an argument to the calling program. `psub` combined with a regular command substitution provides the same functionality.
+
+If the `-f` or `--file` switch is given to `psub`, `psub` will use a regular file instead of a named pipe to communicate with the calling process. This will cause `psub` to be significantly slower when large amounts of data are involved, but has the advantage that the reading process can seek in the stream.
-If the `-f` or `--file` switch is given to `psub`, `psub` will use a
-regular file instead of a named pipe to communicate with the calling
-process. This will cause `psub` to be significantly slower when large
-amounts of data are involved, but has the advantage that the reading
-process can seek in the stream.
\subsection psub-example Example
diff --git a/doc_src/pushd.txt b/doc_src/pushd.txt
index 3161fd098..25d939367 100644
--- a/doc_src/pushd.txt
+++ b/doc_src/pushd.txt
@@ -6,9 +6,9 @@ pushd [DIRECTORY]
\endfish
\subsection pushd-description Description
-The `pushd` function adds `DIRECTORY` to the top of the directory stack
-and makes it the current working directory. `popd` will pop it off and
-return to the original directory.
+
+The `pushd` function adds `DIRECTORY` to the top of the directory stack and makes it the current working directory. `popd` will pop it off and return to the original directory.
+
\subsection pushd-example Example
diff --git a/doc_src/random.txt b/doc_src/random.txt
index 3415daa6b..5e50232ae 100644
--- a/doc_src/random.txt
+++ b/doc_src/random.txt
@@ -9,11 +9,8 @@ random [SEED]
`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.
+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/read.txt b/doc_src/read.txt
index 3e171769f..7c4b07ee5 100644
--- a/doc_src/read.txt
+++ b/doc_src/read.txt
@@ -7,32 +7,38 @@ read [OPTIONS] [VARIABLES...]
\subsection read-description Description
-`read` reads one line from standard
-input and stores the result in one or more shell variables.
+`read` reads one line from standard input and stores the result in one or more shell variables.
The following options are available:
- `-c CMD` or `--command=CMD` sets the initial string in the interactive mode command buffer to `CMD`.
+
- `-g` or `--global` makes the variables global.
+
- `-l` or `--local` makes the variables local.
+
- `-m NAME` or `--mode-name=NAME` specifies that the name NAME should be used to save/load the history file. If NAME is fish, the regular fish history will be available.
+
- `-p PROMPT_CMD` or `--prompt=PROMPT_CMD` uses the output of the shell command `PROMPT_CMD` as the prompt for the interactive mode. The default prompt command is `set_color green; echo read; set_color normal; echo "> "`.
+
- `-s` or `--shell` enables syntax highlighting, tab completions and command termination suitable for entering shellscript code in the interactive mode.
+
- `-u` or `--unexport` prevents the variables from being exported to child processes (default behaviour).
+
- `-U` or `--universal` causes the specified shell variable to be made universal.
+
- `-x` or `--export` exports the variables to child processes.
-`read` reads a single line of input from stdin, breaks it into tokens
-based on the `IFS` shell variable, and then assigns one
-token to each variable specified in `VARIABLES`. If there are more
-tokens than variables, the complete remainder is assigned to the last variable.
+`read` reads a single line of input from stdin, breaks it into tokens based on the `IFS` shell variable, and then assigns one token to each variable specified in `VARIABLES`. If there are more tokens than variables, the complete remainder is assigned to the last variable.
+
+See the documentation for `set` for more details on the scoping rules for variables.
-See the documentation for `set` for more details on the scoping rules for
-variables.
\subsection read-example Example
The following code stores the value 'hello' in the shell variable
`$foo`.
-`echo hello|read foo`
+\fish
+echo hello|read foo
+\endfish
diff --git a/doc_src/return.txt b/doc_src/return.txt
index 5f033349f..af4ca9aeb 100644
--- a/doc_src/return.txt
+++ b/doc_src/return.txt
@@ -7,16 +7,13 @@ function NAME; [COMMANDS...;] return [STATUS]; [COMMANDS...;] end
\subsection return-description Description
-`return` halts a currently running function. The exit status is set
-to `STATUS` if it is given.
+`return` halts a currently running function. The exit status is set to `STATUS` if it is given.
+
+It is usually added inside of a conditional block such as an if statement or a switch statement to conditionally stop the executing function and return to the caller, but it can also be used to specify the exit status of a function.
-It is usually added inside of a conditional block such as an if statement or a switch
-statement to conditionally stop the executing function and return to
-the caller, but it can also be used to specify the exit status of a
-function.
\subsection return-example Example
+
The following code is an implementation of the false command as a fish function
\fish
diff --git a/doc_src/set.txt b/doc_src/set.txt
index cbdd0f154..0dae90103 100644
--- a/doc_src/set.txt
+++ b/doc_src/set.txt
@@ -12,74 +12,66 @@ set (-e | --erase) [SCOPE_OPTIONS] VARIABLE_NAME[INDICES]...
\subsection set-description Description
-`set` manipulates shell
-variables.
+`set` manipulates shell variables.
-If set is called with no arguments, the names and values of all
-shell variables are printed. If some of the scope or export
-flags have been given, only the variables matching the specified scope
-are printed.
+If set is called with no arguments, the names and values of all shell variables are printed. If some of the scope or export flags have been given, only the variables matching the specified scope are printed.
-With both variable names and values provided, `set` assigns the variable
-`VARIABLE_NAME` the values `VALUES...`.
+With both variable names and values provided, `set` assigns the variable `VARIABLE_NAME` the values `VALUES...`.
The following options control variable scope:
+
- `-l` or `--local` forces the specified shell variable to be given a scope that is local to the current block, even if a variable with the given name exists and is non-local
+
- `-g` or `--global` causes the specified shell variable to be given a global scope. Non-global variables disappear when the block they belong to ends
+
- `-U` or `--universal` causes the specified shell variable to be given a universal scope. If this option is supplied, the variable will be shared between all the current users fish instances on the current computer, and will be preserved across restarts of the shell.
+
- `-x` or `--export` causes the specified shell variable to be exported to child processes (making it an "environment variable")
+
- `-u` or `--unexport` causes the specified shell variable to NOT be exported to child processes
+
The following options are available:
+
- `-e` or `--erase` causes the specified shell variable to be erased
+
- `-q` or `--query` test if the specified variable names are defined. Does not output anything, but the builtins exit status is the number of variables specified that were not defined.
+
- `-n` or `--names` List only the names of all defined variables, not their value
+
- `-L` or `--long` do not abbreviate long values when printing set variables
-If a variable is set to more than one value, the variable will be an
-array with the specified elements. If a variable is set to zero
-elements, it will become an array with zero elements.
-If the variable name is one or more array elements, such as
-`PATH[1 3 7]`, only those array elements specified will be
-changed. When array indices are specified to `set`, multiple arguments
-may be used to specify additional indexes, e.g. `set PATH[1]
-PATH[4] /bin /sbin`. If you specify a negative index when
-expanding or assigning to an array variable, the index will be
-calculated from the end of the array. For example, the index -1 means
-the last index of an array.
+If a variable is set to more than one value, the variable will be an array with the specified elements. If a variable is set to zero elements, it will become an array with zero elements.
+
+If the variable name is one or more array elements, such as `PATH[1 3 7]`, only those array elements specified will be changed. When array indices are specified to `set`, multiple arguments may be used to specify additional indexes, e.g. `set PATH[1] PATH[4] /bin /sbin`. If you specify a negative index when expanding or assigning to an array variable, the index will be calculated from the end of the array. For example, the index -1 means the last index of an array.
The scoping rules when creating or updating a variable are:
-# If a variable is explicitly set to either universal, global or local, that setting will be honored. If a variable of the same name exists in a different scope, that variable will not be changed.
+
-# If a variable is not explicitly set to be either universal, global or local, but has been previously defined, the previous variable scope is used.
+
-# If a variable is not explicitly set to be either universal, global or local and has never before been defined, the variable will be local to the currently executing function. Note that this is different from using the `-l` or `--local` flag. If one of those flags is used, the variable will be local to the most inner currently executing block, while without these the variable will be local to the function. If no function is executing, the variable will be global.
-The exporting rules when creating or updating a variable are identical
-to the scoping rules for variables:
+
+The exporting rules when creating or updating a variable are identical to the scoping rules for variables:
-# If a variable is explicitly set to either be exported or not exported, that setting will be honored.
+
-# If a variable is not explicitly set to be exported or not exported, but has been previously defined, the previous exporting rule for the variable is kept.
+
-# If a variable is not explicitly set to be either exported or unexported and has never before been defined, the variable will not be exported.
+
In query mode, the scope to be examined can be specified.
-In erase mode, if variable indices are specified, only the specified
-slices of the array variable will be erased.
+In erase mode, if variable indices are specified, only the specified slices of the array variable will be erased.
-`set` requires all options to come before any
-other arguments. For example, `set flags -l` will have
-the effect of setting the value of the variable `flags` to
-'-l', not making the variable local.
+`set` requires all options to come before any other arguments. For example, `set flags -l` will have the effect of setting the value of the variable `flags` to '-l', not making the variable local.
+
+In assignment mode, `set` exits with a non-zero exit status if variable assignments could not be successfully performed. If the variable assignments were performed, the exit status is unchanged. This allows simultaneous capture of the output and exit status of a subcommand, e.g. `if set output (command)`. In query mode, the exit status is the number of variables that were not found. In erase mode, `set` exits with a zero exit status in case of success, with a non-zero exit status if the commandline was invalid, if the variable was write-protected or if the variable did not exist.
-In assignment mode, `set` exits with a non-zero exit status if variable
-assignments could not be successfully performed. If the variable assignments
-were performed, the exit status is unchanged. This allows simultaneous capture
-of the output and exit status of a subcommand, e.g. `if set output
-(command)`. In query mode, the exit status is the number of variables that
-were not found. In erase mode, `set` exits with a zero exit status in case of
-success, with a non-zero exit status if the commandline was invalid, if the
-variable was write-protected or if the variable did not exist.
\subsection set-example Example
\fish
diff --git a/doc_src/set_color.txt b/doc_src/set_color.txt
index 41c58d9e7..ab4916dfd 100644
--- a/doc_src/set_color.txt
+++ b/doc_src/set_color.txt
@@ -7,36 +7,31 @@ set_color [OPTIONS] [COLOR]
\subsection set_color-description Description
-`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, white and normal.
+`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, white and normal.
-If your terminal supports term256 (modern xterms and OS X Lion),
-you can specify an RGB value with three or six hex digits, such
-as A0FF33 or f2f. `fish` will choose the closest supported color.
+If your terminal supports term256 (modern xterms and OS X Lion), you can specify an RGB value with three or six hex digits, such as A0FF33 or f2f. `fish` will choose the closest supported color.
The following options are available:
- `-b`, `--background` `COLOR` sets the background color.
+
- `-c`, `--print-colors` prints a list of all valid color names.
+
- `-h`, `--help` displays a help message and exit.
+
- `-o`, `--bold` sets bold or extra bright mode.
+
- `-u`, `--underline` sets underlined mode.
-Calling `set_color normal` will set the terminal color to
-the default color of the terminal.
-Some terminals use the `--bold` escape sequence to switch to a brighter
-color set. On such terminals, `set_color white` will result
-in a grey font color, while `set_color --bold white` will
-result in a white font color.
+Calling `set_color normal` will set the terminal color to the default color of the terminal.
+
+Some terminals use the `--bold` escape sequence to switch to a brighter color set. On such terminals, `set_color white` will result in a grey font color, while `set_color --bold white` will result in a white font color.
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.
+`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.
+
\subsection set_color-example Examples
diff --git a/doc_src/source.txt b/doc_src/source.txt
index 8e051a8a5..dba14045c 100644
--- a/doc_src/source.txt
+++ b/doc_src/source.txt
@@ -7,26 +7,17 @@ source FILENAME [ARGUMENTS...]
\subsection source-description Description
-`source` evaluates the commands of the specified file in the current
-shell. This is different from starting a new process to perform the
-commands (i.e. `fish < FILENAME`) since the commands will be
-evaluated by the current shell, which means that changes in
-shell variables will affect the current shell. If additional arguments are
-specified after the file name, they will be inserted into the $argv
-variable.
+`source` evaluates the commands of the specified file in the current shell. This is different from starting a new process to perform the commands (i.e. `fish < FILENAME`) since the commands will be evaluated by the current shell, which means that changes in shell variables will affect the current shell. If additional arguments are specified after the file name, they will be inserted into the $argv variable.
-If no file is specified, or if the file name '`-`' is used, stdin will
-be read.
+If no file is specified, or if the file name '`-`' is used, stdin will be read.
-The return status of `source` is the return status of the last job to
-execute. If something goes wrong while opening or reading the file,
-`source` exits with a non-zero status.
+The return status of `source` is the return status of the last job to execute. If something goes wrong while opening or reading the file, `source` exits with a non-zero status.
+
+`.` (a single period) is an alias for the `source` command. The use of `.` is deprecated in favour of `source`, and `.` will be removed in a future version of fish.
-`.` (a single period) is an alias for the `source` command. The use of `.`
-is deprecated in favour of `source`, and `.` will be removed in a future
-version of fish.
\subsection source-example Example
+
\fish
source ~/.config/fish/config.fish
# Causes fish to re-read its initialization file.
diff --git a/doc_src/status.txt b/doc_src/status.txt
index 60e2342a6..c6b463945 100644
--- a/doc_src/status.txt
+++ b/doc_src/status.txt
@@ -6,18 +6,31 @@ status [OPTION]
\endfish
\subsection status-description Description
+
With no arguments, `status` displays a summary of the current login and job control status of the shell.
The following options are available:
+
- `-c` or `--is-command-substitution` returns 0 if fish is currently executing a command substitution.
+
- `-b` or `--is-block` returns 0 if fish is currently executing a block of code.
+
- `-i` or `--is-interactive` returns 0 if fish is interactive - that is, connected to a keyboard.
+
- `-l` or `--is-login` returns 0 if fish is a login shell - that is, if fish should perform login tasks such as setting up the PATH.
+
- `--is-full-job-control` returns 0 if full job control is enabled.
+
- `--is-interactive-job-control` returns 0 if interactive job control is enabled.
+
- `--is-no-job-control` returns 0 if no job control is enabled.
+
- `-f` or `--current-filename` prints the filename of the currently running script.
+
- `-n` or `--current-line-number` prints the line number of the currently running script.
+
- `-j CONTROLTYPE` or `--job-control=CONTROLTYPE` sets the job control type, which can be `none`, `full`, or `interactive`.
+
- `-t` or `--print-stack-trace` prints a stack trace of all function calls on the call stack.
+
- `-h` or `--help` displays a help message and exit.
diff --git a/doc_src/switch.txt b/doc_src/switch.txt
index 7245b63f6..9bba2bb0d 100644
--- a/doc_src/switch.txt
+++ b/doc_src/switch.txt
@@ -7,29 +7,18 @@ switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
\subsection switch-description Description
-`switch` performs one of several blocks of commands, depending on whether
-a specified value equals one of several wildcarded values. `case` is used
-together with the `switch` statement in order to determine which block should
-be executed.
+`switch` performs one of several blocks of commands, depending on whether a specified value equals one of several wildcarded values. `case` is used together with the `switch` statement in order to determine which block should be executed.
-Each `case` command is given one or more parameters. The first `case`
-command with a parameter that matches the string specified in the
-switch command will be evaluated. `case` parameters may contain
-wildcards. These need to be escaped or quoted in order to avoid
-regular wildcard expansion using filenames.
+Each `case` command is given one or more parameters. The first `case` command with a parameter that matches the string specified in the switch command will be evaluated. `case` parameters may contain wildcards. These need to be escaped or quoted in order to avoid regular wildcard expansion using filenames.
-Note that fish does not fall through on case statements. Only the
-first matching case is executed.
+Note that fish does not fall through on case statements. Only the first matching case is executed.
+
+Note that command substitutions in a case statement will be evaluated even if its body is not taken. All substitutions, including command substitutions, must be performed before the value can be compared against the parameter.
-Note that command substitutions in a case statement will be
-evaluated even if its body is not taken. All substitutions, including
-command substitutions, must be performed before the value can be compared
-against the parameter.
\subsection switch-example Example
-If the variable \$animal contains the name of an animal, the following
-code would attempt to classify it:
+If the variable \$animal contains the name of an animal, the following code would attempt to classify it:
\fish
switch $animal
@@ -48,4 +37,3 @@ end
If the above code was run with `$animal` set to `whale`, the output
would be `mammal`.
-
diff --git a/doc_src/test.txt b/doc_src/test.txt
index 4b7c3a9dc..632e7901a 100644
--- a/doc_src/test.txt
+++ b/doc_src/test.txt
@@ -10,50 +10,83 @@ test [EXPRESSION]
Tests the expression given and sets the exit status to 0 if true, and 1 if false. An expression is made up of one or more operators and their arguments.
The following operators are available to examine files and directories:
+
- `-b FILE` returns true if `FILE` is a block device.
+
- `-c FILE` returns true if `FILE` is a character device.
+
- `-d FILE` returns true if `FILE` is a directory.
+
- `-e FILE` returns true if `FILE` exists.
+
- `-f FILE` returns true if `FILE` is a regular file.
+
- `-g FILE` returns true if `FILE` has the set-group-ID bit set.
+
- `-G FILE` returns true if `FILE` exists and has the same group ID as the current user.
+
- `-L FILE` returns true if `FILE` is a symbolic link.
+
- `-O FILE` returns true if `FILE` exists and is owned by the current user.
+
- `-p FILE` returns true if `FILE` is a named pipe.
+
- `-r FILE` returns true if `FILE` is marked as readable.
+
- `-s FILE` returns true if the size of `FILE` is greater than zero.
+
- `-S FILE` returns true if `FILE` is a socket.
+
- `-t FD` returns true if the file descriptor `FD` is a terminal (TTY).
+
- `-u FILE` returns true if `FILE` has the set-user-ID bit set.
+
- `-w FILE` returns true if `FILE` is marked as writable; note that this does not check if the filesystem is read-only.
+
- `-x FILE` returns true if `FILE` is marked as executable.
The following operators are available to compare and examine text strings:
+
- `STRING1 = STRING2` returns true if the strings `STRING1` and `STRING2` are identical.
+
- `STRING1 != STRING2` returns true if the strings `STRING1` and `STRING2` are not identical.
+
- `-n STRING` returns true if the length of `STRING` is non-zero.
+
- `-z STRING` returns true if the length of `STRING` is zero.
The following operators are available to compare and examine numbers:
+
- `NUM1 -eq NUM2` returns true if `NUM1` and `NUM2` are numerically equal.
+
- `NUM1 -ne NUM2` returns true if `NUM1` and `NUM2` are not numerically equal.
+
- `NUM1 -gt NUM2` returns true if `NUM1` is greater than `NUM2`.
+
- `NUM1 -ge NUM2` returns true if `NUM1` is greater than or equal to `NUM2`.
+
- `NUM1 -lt NUM2` returns true if `NUM1` is less than `NUM2`.
+
- `NUM1 -le NUM2` returns true if `NUM1` is less than or equal to `NUM2`.
Note that only integers are supported. For more complex mathematical operations, including fractions, the `env` program may be useful. Consult the documentation for your operating system.
Expressions can be combined using the following operators:
+
- `COND1 -a COND2` returns true if both `COND1` and `COND2` are true.
+
- `COND1 -o COND2` returns true if either `COND1` or `COND2` are true.
Expressions can be inverted using the `!` operator:
+
- `! EXPRESSION` returns true if `EXPRESSION` is false, and false if `EXPRESSION` is true.
Expressions can be grouped using parentheses.
+
- `( EXPRESSION )` returns the value of `EXPRESSION`.
-Note that parentheses will usually require escaping with `\\(` to avoid being interpreted as a command substitution.
+
+ Note that parentheses will usually require escaping with `\(` to avoid being interpreted as a command substitution.
+
\subsection test-example Examples
@@ -81,9 +114,13 @@ if test \( -f /foo -o -f /bar \) -a \( -f /baz -o -f /bat \)
end.
\endfish
+
\subsection test-standards Standards
`test` implements a subset of the IEEE Std 1003.1-2008 (POSIX.1) standard. The following exceptions apply:
+
- The `<` and `>` operators for comparing strings are not implemented.
+
- Because this test is a shell builtin and not a standalone utility, using the -c flag on a special file descriptors like standard input and output may not return the same result when invoked from within a pipe as one would expect when invoking the `test` utility in another shell.
+
In cases such as this, one can use `command` `test` to explicitly use the system's standalone `test` rather than this `builtin` `test`.
diff --git a/doc_src/trap.txt b/doc_src/trap.txt
index 9c607ad43..3537e760b 100644
--- a/doc_src/trap.txt
+++ b/doc_src/trap.txt
@@ -7,39 +7,32 @@ trap [OPTIONS] [[ARG] SIGSPEC ... ]
\subsection trap-description Description
-`trap` is a wrapper around the fish event delivery
-framework. It exists for backwards compatibility with POSIX
-shells. For other uses, it is recommended to define an event handler.
+`trap` is a wrapper around the fish event delivery framework. It exists for backwards compatibility with POSIX shells. For other uses, it is recommended to define an event handler.
The following parameters are available:
- `ARG` is the command to be executed on signal delivery.
+
- `SIGSPEC` is the name of the signal to trap.
+
- `-h` or `--help` displays help and exits.
+
- `-l` or `--list-signals` prints a list of signal names.
+
- `-p` or `--print` prints all defined signal handlers.
-If `ARG` and `SIGSPEC` are both specified, `ARG` is the command to be
-executed when the signal specified by `SIGSPEC` is delivered.
+If `ARG` and `SIGSPEC` are both specified, `ARG` is the command to be executed when the signal specified by `SIGSPEC` is delivered.
-If `ARG` is absent (and there is a single SIGSPEC) or -, each specified
-signal is reset to its original disposition (the value it had upon
-entrance to the shell). If `ARG` is the null string the signal
-specified by each `SIGSPEC` is ignored by the shell and by the commands
-it invokes.
+If `ARG` is absent (and there is a single SIGSPEC) or -, each specified signal is reset to its original disposition (the value it had upon entrance to the shell). If `ARG` is the null string the signal specified by each `SIGSPEC` is ignored by the shell and by the commands it invokes.
-If `ARG` is not present and `-p` has been supplied, then the trap commands
-associated with each `SIGSPEC` are displayed. If no arguments are
-supplied or if only `-p` is given, `trap` prints the list of commands
-associated with each signal.
+If `ARG` is not present and `-p` has been supplied, then the trap commands associated with each `SIGSPEC` are displayed. If no arguments are supplied or if only `-p` is given, `trap` prints the list of commands associated with each signal.
Signal names are case insensitive and the `SIG` prefix is optional.
-The return status is 1 if any `SIGSPEC` is invalid; otherwise trap
-returns 0.
+The return status is 1 if any `SIGSPEC` is invalid; otherwise trap returns 0.
\subsection trap-example Example
+
\fish
trap "status --print-stack-trace" SIGUSR1
# Prints a stack trace each time the SIGUSR1 signal is sent to the shell.
diff --git a/doc_src/tutorial.hdr b/doc_src/tutorial.hdr
index 39992144a..94cca97ba 100644
--- a/doc_src/tutorial.hdr
+++ b/doc_src/tutorial.hdr
@@ -5,27 +5,49 @@