begin; ...; end is equivalent
-to if true; ...; end. The begin command is used to group any
-number of commands into a block. The reason for doing so is usually
-either to introduce a new variable scope, to redirect the input or
+to if true; ...; end.
+
+\c 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 \c and.
-The \c begin command does not change the current exit status.
+\c begin does not change the current exit status.
\subsection begin-example Example
diff --git a/doc_src/bg.txt b/doc_src/bg.txt
index dc607b064..9c8f593a6 100644
--- a/doc_src/bg.txt
+++ b/doc_src/bg.txt
@@ -1,16 +1,17 @@
-\section bg bg - send to background
+\section bg bg - send jobs to background
\subsection bg-synopsis Synopsis
bg [PID...]
\subsection bg-description Description
-Sends the specified jobs to the background. A background job is
+
+\c 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 group ids are put in the background.
+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 \%0 will put the job with job id 0 in the background.
+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 3bf9fb453..614a14950 100644
--- a/doc_src/bind.txt
+++ b/doc_src/bind.txt
@@ -5,33 +5,34 @@
\subsection bind-description Description
-The bind builtin causes fish to add a key binding from the specified sequence.
+bind adds a binding for the specified key sequence to the
+specified command.
-SEQUENCE is the character sequence to bind to. Usually, one would use
-fish escape sequences to express them. For example, because pressing
+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
\c \\e escape. For example, Alt-w can be written as
-\\ew. Control character can be written in much the same way
-using the \c \\c escape, for example Control-x can be written as
+\\ew. The control character can be written in much the same way
+using the \c \\c escape, for example Control-x (^X) can be written as
\\cx. Note that Alt-based key bindings are case sensitive and
-Control base key bindings are not. This is not a design choice in
-fish, it is simply how terminals work.
+Control-based key bindings are not. This is a constraint of text-based
+termainls, not \c fish.
-If SEQUENCE is the empty string, i.e. an empty set of quotes, this is
-interpreted as the default keybinding. It will be used whenever no
+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 \c 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 e.g. control sequences being
+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 man 5 terminfo for more information, or use bind
---key-names for a list of all available named keys)
+prefix. (See \c 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
@@ -45,19 +46,19 @@ 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 you want to autoload bindings each time you start shell, you should
-define them inside fish_user_key_bindings function.
+Key bindings are not saved between sessions by default. To save custom
+keybindings, edit the \c fish_user_key_bindings function and insert the
+appropirate \c bind statements.
+
+The following parameters are available:
-- -a or --all If --key-names is specified, show all key names, not only the ones that actually are defined for the current terminal. If erase mode is specified, this switch will cause all current bindings to be erased.
-- -e or --erase Erase mode. All non-switch arguments are interpreted as character sequences and any commands associated with those sequences are erased.
-- -h or --help Display help and exit
- -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
-\subsection bind-example Example
+\subsection bind-example Examples
-bind \\cd 'exit' causes fish to exit on Control-d
+bind \\cd 'exit' causes \c fish to exit when Control-d is pressed.
-bind -k ppage history-search-backward Causes fish to perform a history search when the page up key is pressed
+bind -k ppage history-search-backward performs a history search when the Page Up key is pressed.
diff --git a/doc_src/block.txt b/doc_src/block.txt
index 670a39b28..0f4cff383 100644
--- a/doc_src/block.txt
+++ b/doc_src/block.txt
@@ -5,15 +5,36 @@
\subsection block-description Description
-- -l or --local Release the block at the end of the currently innermost block scope
+\c block prevents events triggered by \c fish or the
+emit command from
+being delivered and acted upon while the block is in place.
+
+In functions, \c 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.
+
+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
+# Create a function that listens for events
+function --on-event foo foo; echo 'foo fired'; end
+# Block the delivery of events
block -g
-\#Do something that should not be interrupted
+emit foo
+# No output will be produced
block -e
+# 'foo fired' will now be printed
diff --git a/doc_src/break.txt b/doc_src/break.txt
index 9e5118728..3f46bb8cc 100644
--- a/doc_src/break.txt
+++ b/doc_src/break.txt
@@ -1,13 +1,16 @@
-\section break break - stop the innermost currently evaluated loop
+\section break break - stop the current inner loop
\subsection break-synopsis Synopsis
LOOP_CONSTRUCT; [COMMANDS...] break; [COMMANDS...] end
\subsection break-description Description
-The \c break builtin is used to halt 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.
+
+\c 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 smurfs, and halts at the first occurrence.
+The following code searches all .c files for "smurf", and halts at the first occurrence.
for i in *.c
diff --git a/doc_src/breakpoint.txt b/doc_src/breakpoint.txt
index f3332c755..744727fa1 100644
--- a/doc_src/breakpoint.txt
+++ b/doc_src/breakpoint.txt
@@ -5,6 +5,10 @@
\subsection breakpoint-description Description
-The \c breakpoint builtin is used to halt a running script and launch
-an interactive debug prompt.
+\c breakpoint is used to halt a running script and launch
+an interactive debugging prompt.
+For more details, see Debugging fish
+scripts in the \c fish manual.
+
+There are no parameters for breakpoint.
diff --git a/doc_src/builtin.txt b/doc_src/builtin.txt
index a077a1bf1..fd93f703b 100644
--- a/doc_src/builtin.txt
+++ b/doc_src/builtin.txt
@@ -5,12 +5,12 @@
\subsection builtin-description Description
-- -n or --names List the names of all defined builtins
+\c builtin forces the shell to use a builtin command, rather than a function or program.
-Prefixing a command with the word 'builtin' forces fish to ignore any functions with the same name.
+The following parameters are available:
+
+- -n or --names List the names of all defined builtins
\subsection builtin-example Example
-builtin jobs
-
-causes fish to execute the jobs builtin, even if a function named jobs exists.
+builtin jobs executes the jobs builtin, even if a function named jobs exists.
diff --git a/doc_src/case.txt b/doc_src/case.txt
index 468cc3c49..b5601cdb7 100644
--- a/doc_src/case.txt
+++ b/doc_src/case.txt
@@ -5,27 +5,24 @@
\subsection case-description Description
-The \c switch statement is used to perform one of several blocks of
-commands depending on whether a specified value equals one of several
-wildcarded values. The \c case statement is used together with the \c
-switch statement in order to determine which block should be
-performed.
+\c switch performs one of several blocks of commands, depending on whether
+a specified value equals one of several wildcarded values. \c case is used
+together with the \c switch statement in order to determine which block should
+be executed.
-Each \c case command is given one or more parameter. The first \c case
+Each \c case command is given one or more parameters. The first \c case
command with a parameter that matches the string specified in the
switch command will be evaluated. \c 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. Though the
-syntax may look a bit like C switch statements, it behaves more like
-the case statements of traditional shells.
+Note that fish does not fall through on case statements. Only the
+first matching case is executed.
-Also note that command substitutions in a case statement will be
-evaluated even if it's body is not taken. This may seem
-counterintuitive at first, but it is unavoidable, since it would be
-impossible to know if a case command will evaluate to true before all
-forms of parameter expansion have been performed for the case command.
+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
@@ -42,6 +39,7 @@ switch $animal
echo bird
case shark trout stingray
echo fish
+ # Note that the next case has a wildcard which is quoted
case '*'
echo I have no idea what a $animal is
end
diff --git a/doc_src/cd.txt b/doc_src/cd.txt
index 13184e107..c1a5875a4 100644
--- a/doc_src/cd.txt
+++ b/doc_src/cd.txt
@@ -4,8 +4,21 @@
cd [DIRECTORY]
\subsection cd-description Description
-Changes the current directory. If DIRECTORY is supplied it will become
-the new directory. If \c DIRECTORY is a relative path, the paths found in the
-CDPATH environment variable array will be tried as prefixes for the specified
-path. If CDPATH is not set, it is assumed to be '.'. If \c DIRECTORY is not
-specified, \$HOME will be the new directory.
+\c cd changes the current working directory.
+
+If \c DIRECTORY is supplied, it will become the new directory. If no parameter
+is given, the contents of the \c HOME environment variable will be used.
+
+If \c DIRECTORY is a relative path, the paths found in the
+\c CDPATH environment variable array will be tried as prefixes for the specified
+path.
+
+Note that the shell will attempt to change directory without requiring \c cd
+if the name of a directory is provided (starting with '.', '/' or '~').
+
+\subsection cd-example Examples
+
+\c cd changes the working directory to your home directory.
+
+cd /usr/src/fish-shell changes the working directory to
+/usr/src/fish-shell.
diff --git a/doc_src/command.txt b/doc_src/command.txt
index 885cca5f3..19baccd46 100644
--- a/doc_src/command.txt
+++ b/doc_src/command.txt
@@ -4,11 +4,9 @@
command COMMANDNAME [OPTIONS...]
\subsection command-description Description
-prefixing a command with the word 'command' forces fish to ignore any functions or builtins with the same name.
+
+\c command forces the shell to execute the program \c 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 there exists a 'ls' function.
+command ls causes fish to execute the \c ls program, even if an 'ls' function exists.
diff --git a/doc_src/commandline.txt b/doc_src/commandline.txt
index df03ab13f..ab771e96d 100644
--- a/doc_src/commandline.txt
+++ b/doc_src/commandline.txt
@@ -1,32 +1,34 @@
-\section commandline commandline - set or get the current commandline buffer
+\section commandline commandline - set or get the current command line buffer
\subsection commandline-synopsis Synopsis
commandline [OPTIONS] [CMD]
\subsection commandline-description Description
+\c commandline can be used to set or get the current contents of the command
+line buffer.
-- \c CMD is the new value of the commandline. If unspecified, the
- current value of the commandline is written to standard output. All
- output from the commandline builtin is escaped, i.e. quotes are
- removed, backslash escapes are expanded, etc..
+With no parameters, \c commandline returns the current value of the command
+line.
-The following switches change what the commandline builtin does
+With \c CMD specified, the command line buffer is erased and replaced with
+the contents of \c CMD.
+
+The following options are available:
- \c -C or \c --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.
- \c -f or \c --function inject readline functions into the
- reader. This option can not be combined with any other option. It
+ 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.
-
-The following switches change the way \c commandline updates the
-commandline buffer
+The following options change the way \c commandline updates the
+command line buffer:
- \c -a or \c --append do not remove the current commandline, append
the specified string at the end of it
@@ -35,29 +37,27 @@ commandline buffer
- \c -r or \c --replace remove the current commandline and replace it
with the specified string (default)
-The following switches change what part of the commandline is printed
-or updated
+The following options change what part of the commandline is printed
+or updated:
- \c -b or \c --current-buffer select the entire buffer (default)
- \c -j or \c --current-job select the current job
- \c -p or \c --current-process select the current process
- \c -t or \c --current-token select the current token.
-The following switch changes the way \c commandline prints the current
-commandline buffer
+The following options change the way \c commandline prints the current
+commandline buffer:
- \c -c or \c --cut-at-cursor only print selection up until the
current cursor position
- \c -o or \c --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 commandline.
+If \c commandline is called during a call to complete a given string
+using complete -C STRING, \c commandline will consider the
+specified string to be the current contents of the command line.
\subsection commandline-example Example
-commandline -j $history[3]
-
-replaces the job under the cursor with the third item from the
-commandline 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 f6d00a154..c2085ccb8 100644
--- a/doc_src/complete.txt
+++ b/doc_src/complete.txt
@@ -1,12 +1,12 @@
-\section complete complete - edit command specific tab-completions.
+\section complete complete - edit command specific tab-completions
\subsection complete-synopsis Synopsis
complete (-c|--command|-p|--path) COMMAND [(-s|--short-option) SHORT_OPTION] [(-l|--long-option|-o|--old-option) LONG_OPTION [(-a||--arguments) OPTION_ARGUMENTS] [(-d|--description) DESCRIPTION]
\subsection complete-description Description
-For an introduction to how to specify completions, see the section Writing your own completions of
+For an introduction to specifying completions, see Writing your own completions in
the fish manual.
- COMMAND is the name of the command for which to add a completion
diff --git a/doc_src/contains.txt b/doc_src/contains.txt
index 1a08a2ac1..cc7463588 100644
--- a/doc_src/contains.txt
+++ b/doc_src/contains.txt
@@ -5,13 +5,15 @@
\subsection contains-description Description
+\c contains tests whether the set \c VALUES contains the string
+KEY. If so, \c contains exits with status 0; if not, it exits
+with status 1.
+
+The following options are available:
+
- \c -i or \c --index print the word index
- \c -h or \c --help display this message
-Test if the set VALUES contains the string KEY. Return status is 0 if
-yes, 1 otherwise
-
-
\subsection contains-example Example
for i in ~/bin /usr/local/bin
@@ -21,4 +23,4 @@ for i in ~/bin /usr/local/bin
end
-The above code tests if ~/bin and /usr/local/bin are in the path and if they are not, they are added.
+The above code tests if \c ~/bin and \c /usr/local/bin are in the path and adds them if not.
diff --git a/doc_src/continue.txt b/doc_src/continue.txt
index 470093936..9b1803f56 100644
--- a/doc_src/continue.txt
+++ b/doc_src/continue.txt
@@ -1,13 +1,13 @@
-\section continue continue - skip the rest of the current lap of the innermost currently evaluated loop
+\section continue continue - skip the remainder of the current iteration of the current inner loop
\subsection continue-synopsis Synopsis
LOOP_CONSTRUCT; [COMMANDS...;] continue; [COMMANDS...;] end
\subsection continue-description Description
-The \c continue builtin is used to skip the current lap of the innermost 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.
+\c 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 without smurfs.
+The following code removes all tmp files that do not contain the word smurf.
for i in *.tmp
diff --git a/doc_src/count.txt b/doc_src/count.txt
index 1484588a8..7923ca00a 100644
--- a/doc_src/count.txt
+++ b/doc_src/count.txt
@@ -5,20 +5,13 @@
\subsection count-description Description
-The count builtin prints the number of arguments that were
+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, but this is not the only
-potential usage for the count command.
+environment variable array contains.
-The count command does not accept any options, not even '-h'. This way
-the user does not have to worry about an array containing elements
-such as dashes. \c fish performs a special check when invoking the
-count command, and if the user uses a help option, this help page is
-displayed, but if a help option is contained inside of a variable or
-is the result of expansion, it will simply be counted like any other
-argument.
+\c count does not accept any options, including '-h'.
-Count exits with a non-zero exit status if no arguments were passed
+\c 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
diff --git a/doc_src/dirh.txt b/doc_src/dirh.txt
index efd4ac79f..abc498b87 100644
--- a/doc_src/dirh.txt
+++ b/doc_src/dirh.txt
@@ -4,5 +4,9 @@
dirh
\subsection dirh-description Description
+
dirh prints the current directory history. The current position in the
-history is highlighted using $fish_color_history_current.
+history is highlighted using the color defined in the
+fish_color_history_current environment variable.
+
+\c dirh does not accept any parameters.
diff --git a/doc_src/dirs.txt b/doc_src/dirs.txt
index b5b9c0aea..e52381076 100644
--- a/doc_src/dirs.txt
+++ b/doc_src/dirs.txt
@@ -4,4 +4,7 @@
dirs
\subsection dirs-description Description
-dirs prints the current directory stack.
+dirs prints the current directory stack, as created by the
+pushd command.
+
+\c dirs does not accept any parameters.
diff --git a/doc_src/echo.txt b/doc_src/echo.txt
index cfa9849ef..01ddf5a58 100644
--- a/doc_src/echo.txt
+++ b/doc_src/echo.txt
@@ -3,19 +3,21 @@
\subsection echo-synopsis Synopsis
echo [STRING]
-\subsection echo-description Description
-
-Display a line of text.
-
+\subsection echo-description Description
+
+\c echo displays a string of text.
+
+The following options are available:
+
- \c -n, \c Do not output a newline
-- \c -s, \c Do not separate arguments with spaces
+- \c -s, \c Do not separate arguments with spaces
- \c -E, \c Disable interpretation of backslash escapes (default)
- \c -e, \c Enable interpretation of backslash escapes
- \c -h, \c --help Display this help
\subsection echo-escapes Escape Sequences
-If -e is in effect, the following sequences are recognized:
+If \c -e is used, the following sequences are recognized:
- \c \\\\ \c backslash
- \\a alert (BEL)
diff --git a/doc_src/else.txt b/doc_src/else.txt
index e0f8b85bb..66d8be3fe 100644
--- a/doc_src/else.txt
+++ b/doc_src/else.txt
@@ -4,14 +4,18 @@
if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end
\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. Hint: use
-begin; ...; end for complex conditions.
+if will execute the command \c CONDITION. If the condition's exit
+status is 0, the commands \c COMMANDS_TRUE will execute. If it is not 0 and
+else is given, \c COMMANDS_FALSE will be executed.
\subsection else-example Example
-The command if test -f foo.txt; echo foo.txt exists; else; echo foo.txt does not exist; end
-will print foo.txt exists if the file foo.txt
-exists and is a regular file, otherwise it will print
-foo.txt does not exist.
+The following code tests whether a file \c foo.txt exists as a regular file.
+
+
+if test -f foo.txt
+ echo foo.txt exists
+else
+ echo foo.txt does not exist
+end
+
diff --git a/doc_src/emit.txt b/doc_src/emit.txt
index c0faab82f..f00e42339 100644
--- a/doc_src/emit.txt
+++ b/doc_src/emit.txt
@@ -5,7 +5,7 @@
\subsection emit-description Description
-The emit builtin fires a generic fish event. Such events can be caught by special functions called event handlers. The arguments are passed to the event handlers as function arguments.
+\c 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
diff --git a/doc_src/end.txt b/doc_src/end.txt
index 5849e339c..2d301e339 100644
--- a/doc_src/end.txt
+++ b/doc_src/end.txt
@@ -10,7 +10,9 @@ switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
\subsection end-description Description
-end ends a block of commands. For more information, read the
+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.
diff --git a/doc_src/eval.txt b/doc_src/eval.txt
index 68fc6fc93..0227255a0 100644
--- a/doc_src/eval.txt
+++ b/doc_src/eval.txt
@@ -4,13 +4,16 @@
eval [COMMANDS...]
\subsection eval-description Description
-The eval function causes fish to evaluate 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.
+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 folloing code will call the ls command. Note that \c fish does not
+support the use of environment variables as direct commands; \c eval can
+be used to work around this.
+
set cmd ls
eval $cmd
-will call the ls command.
diff --git a/doc_src/exec.txt b/doc_src/exec.txt
index e0e661fb2..27f6d8876 100644
--- a/doc_src/exec.txt
+++ b/doc_src/exec.txt
@@ -5,11 +5,11 @@
\subsection exec-description Description
-The \c exec builtin is used to replace the currently running shells
-process image with a new command. On successful completion, exec never
-returns. exec can not be used inside a pipeline.
+\c exec replaces the currently running shell with a new command.
+On successful completion, \c exec never returns. \c exec cannot be used
+inside a pipeline.
\subsection exec-example Example
-exec emacs starts up the emacs text editor. When emacs exits,
-the session will terminate.
+exec emacs starts up the emacs text editor, and exits \c fish.
+When emacs exits, the session will terminate.
diff --git a/doc_src/exit.txt b/doc_src/exit.txt
index aa96fe95c..cdcf54d46 100644
--- a/doc_src/exit.txt
+++ b/doc_src/exit.txt
@@ -1,13 +1,13 @@
-\section exit exit - exit the shell.
+\section exit exit - exit the shell
\subsection exit-synopsis Synopsis
exit [STATUS]
\subsection exit-description Description
-The exit builtin causes fish to exit. If STATUS is
+\c 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.
+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,
diff --git a/doc_src/fg.txt b/doc_src/fg.txt
index db983ee9a..53b5154f6 100644
--- a/doc_src/fg.txt
+++ b/doc_src/fg.txt
@@ -1,14 +1,14 @@
-\section fg fg - send job to foreground
+\section fg fg - bring job to foreground
\subsection fg-synopsis Synopsis
fg [PID]
\subsection fg-description Description
-Sends the specified job to the foreground. 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.
+\c 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 \%0 will put the job with job id 0 in the foreground.
+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 faa69a14c..ed28cffde 100644
--- a/doc_src/fish.txt
+++ b/doc_src/fish.txt
@@ -5,10 +5,12 @@ fish [-h] [-v] [-c command] [FILE [ARGUMENTS...]]
\subsection fish-description Description
-A commandline shell written mainly with interactive use in mind. The
+\c 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
diff --git a/doc_src/fish_config.txt b/doc_src/fish_config.txt
index 78191477a..a9627bb23 100644
--- a/doc_src/fish_config.txt
+++ b/doc_src/fish_config.txt
@@ -1,5 +1,22 @@
-\section fish_config fish_config - Start up the web-based configuration interface
+\section fish_config fish_config - start the web-based configuration interface
\subsection fish_config-description Description
-This command starts up the web-based configuration interface, which allows you to edit your colors and view your functions, variables, and history.
+\c 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.
+
+\c 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.
+
+There are no parameters for fish_config.
+
+If the \c 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
+
+\c 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 68d0647c9..c5daeace9 100644
--- a/doc_src/fish_indent.txt
+++ b/doc_src/fish_indent.txt
@@ -5,11 +5,11 @@
\subsection fish_indent-description Description
-\c fish_indent is used to indent or otherwise prettify a piece of fish
+\c fish_indent is used to indent a piece of fish
code. \c fish_indent reads commands from standard input and outputs
them to standard output.
-\c fish_indent understands the following options:
+The following options are available:
- -h or --help displays this help message and then exits
- -i or --no-indent do not indent commands
diff --git a/doc_src/fish_pager.txt b/doc_src/fish_pager.txt
index 304f62140..9efa26b11 100644
--- a/doc_src/fish_pager.txt
+++ b/doc_src/fish_pager.txt
@@ -2,7 +2,6 @@
\subsection fish_pager-description Description
-This command is used internally by fish to display a list of
-completions. It should not be used by other commands, as it's
-interface is liable to change in the future.
+\c fish_pager is used internally by fish. It should not be used by other
+commands, as its interface is liable to change in the future.
diff --git a/doc_src/fish_prompt.txt b/doc_src/fish_prompt.txt
index d400619c8..5cf5abf9e 100644
--- a/doc_src/fish_prompt.txt
+++ b/doc_src/fish_prompt.txt
@@ -11,7 +11,10 @@ By defining the \c fish_prompt function, the user can choose a custom
prompt. The \c 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 \c fish_prompt will not modify the $status seen outside of fish_prompt.
+The exit status of commands within \c fish_prompt will not modify the value of $status outside of the \c fish_prompt function.
+
+\c fish ships with a number of example prompts that can be chosen with the
+\c fish_config command.
\subsection fish_prompt-example Example
diff --git a/doc_src/fish_update_completions.txt b/doc_src/fish_update_completions.txt
index 1369f9d11..cff5ce0b5 100644
--- a/doc_src/fish_update_completions.txt
+++ b/doc_src/fish_update_completions.txt
@@ -1,6 +1,9 @@
-\section fish_update_completions fish_update_completions - Update man-page completions
+\section fish_update_completions fish_update_completions - Update completions using manual pages
\subsection fish_update_completions-description Description
-This command parses your installed man pages and writes completion files to the fish config directory. This does not overwrite custom completions.
+\c fish_update_completions parses manual pages installed on the system, and attempts to create completion files in the \c fish configuration directory.
+This does not overwrite custom completions.
+
+There are no parameters for fish_update_completions.
diff --git a/doc_src/fishd.txt b/doc_src/fishd.txt
index 074e8f5d8..0eb3088a4 100644
--- a/doc_src/fishd.txt
+++ b/doc_src/fishd.txt
@@ -6,26 +6,28 @@
\subsection fishd-description Description
The \c fishd daemon is used to load, save and distribute universal
-variable information. fish automatically connects to fishd via a socket
-on startup. If no instance of fishd is running, fish spawns a new
-fishd instance. fishd will create a socket in /tmp, and wait for
-incoming connections from universal variable clients, such as fish,
-When no clients are connected, fishd will automatically shut down.
+variable information. \c fish automatically connects to \c fishd via a socket
+on startup.
+
+\c fishd is started and stopped automatically.
+
+The following options are available if starting \c fishd manually:
- -h or --help displays this help message and then exits
- -v or --version displays the current fish version and then exits
\subsection fishd-files Files
-\c ~/.config/fish/fishd.MACHINE_ID permanent storage location for universal
-variable data. MACHINE_ID is generally based on the machine's MAC address.
-The data is stored as a set of \c set and \c set_export commands such as
-would be parsed by fishd. The file must always be stored in ASCII format.
-If an instance of fishd is running (which is generally the case), manual
-modifications to ~/.fishd.MACHINE_ID will be lost. Do NOT edit this file manually!
+- \c ~/.config/fish/fishd.MACHINE_ID - permanent storage location for universal
+ variable data. \c MACHINE_ID is generally based on the machine's MAC address.
-\c /tmp/fishd.socket.USERNAME the socket which fishd uses to communicate
+ The data is stored as a set of \c set and \c set_export commands such as
+ would be parsed by fishd. The file must always be stored in YAML format.
+ If an instance of fishd is running (which is generally the case), manual
+ modifications to \c ~/.fishd.MACHINE_ID will be lost. Do NOT edit this file manually!
+
+- \c /tmp/fishd.socket.USERNAME - the socket which fishd uses to communicate
with all clients.
-/tmp/fishd.log.USERNAME the fishd log file
+- /tmp/fishd.log.USERNAME - the fishd log file
diff --git a/doc_src/for.txt b/doc_src/for.txt
index 2ffffe40a..67a46fc39 100644
--- a/doc_src/for.txt
+++ b/doc_src/for.txt
@@ -5,8 +5,8 @@
\subsection for-description Description
for is a loop construct. It will perform the commands specified by
-COMMANDS multiple times. Each time the environment variable specified by
-VARNAME is assigned a new value from VALUES. If VALUES is empty, COMMANDS will
+\c COMMANDS multiple times. On each iteration, the environment variable specified by
+\c VARNAME is assigned a new value from \c VALUES. If \c VALUES is empty, \c COMMANDS will
not be executed at all.
\subsection for-example Example
diff --git a/doc_src/funced.txt b/doc_src/funced.txt
index 19a12f3b0..8b070b97a 100644
--- a/doc_src/funced.txt
+++ b/doc_src/funced.txt
@@ -5,13 +5,14 @@
\subsection funced-description Description
-Use the funced command to edit the definition of a function. If there is no
-function with the name specified, a skeleton function is inserted. If the
-function exists, its definition will be shown in your editor or on the command
-line.
+\c funced provides an interface to edit the definition of the function
+NAME.
-By default, funced edits functions using the text editor in your $EDITOR
-variable, if set; otherwise it uses the built-in editor.
+If the \c $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 \c 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
diff --git a/doc_src/funcsave.txt b/doc_src/funcsave.txt
index 944e699c0..c81961bf2 100644
--- a/doc_src/funcsave.txt
+++ b/doc_src/funcsave.txt
@@ -1,12 +1,13 @@
\section funcsave funcsave - save the definition of a function to the user's autoload directory
\subsection funcsave-synopsis Synopsis
- funcsave FUNCTION_NAME
+funcsave FUNCTION_NAME
\subsection funcsave-description Description
-funcsave is used to save the current definition of a function to
-a file which will be autoloaded by current and future fish
+\c 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 10d9eec05..c072c5518 100644
--- a/doc_src/function.txt
+++ b/doc_src/function.txt
@@ -5,32 +5,28 @@
\subsection function-description Description
-- -d DESCRIPTION or \c --description=DESCRIPTION is a description of what the function does, suitable as a completion description
+\c function creates a new function \c 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.
+
+The following options are available:
+
+- -d DESCRIPTION or \c --description=DESCRIPTION is a description of what the function does, suitable as a completion description.
- -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)
-- -v or --on-variable VARIABLE_NAME tells fish to run this function when the variable VARIABLE_NAME changes value
-
-This builtin command is used to create a new function. A function is a
-list of commands that will be executed when the name of the function
-is entered. The function
-
-
-function hi
- echo hello
-end
-
-
-will write hello whenever the user enters \c hi.
+- -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).
+- -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.
+are inserted into the environment variable array
+$argv.
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:
-- \c fish_prompt, which is emitted whenever a new fish prompt is about to be displayed
-- \c fish_command_not_found, which is emitted whenever a command lookup failed
+- \c fish_prompt, which is emitted whenever a new fish prompt is about to be displayed.
+- \c fish_command_not_found, which is emitted whenever a command lookup failed.
\subsection function-example Example
diff --git a/doc_src/functions.txt b/doc_src/functions.txt
index 928cd545a..c1f0115e4 100644
--- a/doc_src/functions.txt
+++ b/doc_src/functions.txt
@@ -1,31 +1,51 @@
\section functions functions - print or erase functions
\subsection function-synopsis Synopsis
-functions [-e] FUNCTIONS...
+functions [-n]
+functions -c OLDNAME NEWNAME
+functions -d DESCRIPTION FUNCTION
+functions [-eq] FUNCTIONS...
\subsection functions-description Description
-This builtin command is used to print or erase functions.
+\c functions prints or erases functions.
-- -a or --all list all functions, even those whose name start with an underscore.
+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 change the description of this 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 display a help message and exit
-- -n or --names list only the names of all defined functions, not their definition
-- -q or --query test if the specified functions exist. Does not output anything, but the builtins exit status is the number of functions specified that were not defined.
+- -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 \c functions when called with no arguments,
-is to print the names and definitions of all defined functions. If any
-non-switch parameters are given, only the definition of the specified
+The default behavior of functions, when called with no arguments,
+is to print the names of all defined functions. Unless the \c -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.
-Automatically loaded functions can not be removed using functions
--e. Either remove the definition file or change the
+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.
-Function copies, created with -c, will not have any event/signal/on-exit
-notifications that the original may have had.
+Copying a function using \c -c copies only the body of the function, and
+does not attach any event notifications from the original function.
-The exit status of the functions builtin is the number functions
-specified in the argument list that do not exist.
+Only one function's description can be changed in a single invocation
+of functions -d.
+
+The exit status of \c functions is the number of functions
+specified in the argument list that do not exist, which can be used in
+concert with the \c -q option.
+
+\subsection functions-example Examples
+
+functions -n displays a list of currently-defined functions.
+
+functions -c foo bar copies the \c 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 3dc90e9a8..c4c053826 100644
--- a/doc_src/help.txt
+++ b/doc_src/help.txt
@@ -5,12 +5,14 @@
\subsection help-description Description
-The \c help command is used to display a section of the fish help documentation.
+\c help displays the fish help documentation.
+
+If a \c 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.
+documentation. Otherwise, fish will search for a suitable browser.
-Note also that most builtin commands display their help in the terminal when
+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 8f7b69164..33ee4d662 100644
--- a/doc_src/history.txt
+++ b/doc_src/history.txt
@@ -1,4 +1,4 @@
-\section history history - Show and manipulate user's command history
+\section history history - Show and manipulate command history
\subsection history-synopsis Synopsis
@@ -8,29 +8,37 @@ history (--search | --delete ) (--prefix "prefix string" | --contains "search st
\subsection history-description Description
-history is used to list, search and delete user's command history
+\c history is used to list, search and delete the history of commands used.
+
+The following options are available:
+
+- \c --save saves all changes in the history file. The shell automatically
+saves the history file; this option is provided for internal use.
+- \c --clear clears the history file. A prompt is displayed before the history
+is erased.
+- \c --search returns history items in keeping with the \c --prefix or
+\c --contains options.
+- \c --delete deletes history items.
+- \c --prefix searches or deletes items in the history that begin with the
+specified text string.
+- \c --contains searches or deletes items in the history that contain the
+specified text string.
+
+If \c --search is specified without \c --contains or --prefix,
+\c --contains will be assumed.
+
+If \c --delete is specified without \c --contains or --prefix,
+only a history item which exactly matches the parameter will be erased. No
+prompt will be given. If \c --delete is specified with either of these
+parameters, an interactive prompt will be displayed before any items are
+deleted.
\subsection history-examples Example
-
-history --save
-Save all changes in history file
+history --clear deletes all history items
-history --clear
-Delete all history items
+history --search --contains "foo" outputs a list of all previous
+commands containing the string "foo".
-history --search --contains "foo"
-Searches commands containing "foo" string
-
-history --search --prefix "foo"
-Searches for commands with prefix "foo"
-
-history --delete --contains "foo"
-Interactively delete commands containing string "foo"
-
-history --delete --prefix "foo"
-Interactively delete commands with prefix "foo"
-
-history --delete "foo"
-Delete command "foo" from history
-
+history --delete --prefix "foo" interactively deletes the record
+of previous commands which start with "foo".
diff --git a/doc_src/if.txt b/doc_src/if.txt
index dae82ca6c..94d2763a6 100644
--- a/doc_src/if.txt
+++ b/doc_src/if.txt
@@ -5,15 +5,15 @@
\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
+if will execute the command \c CONDITION. If the condition's
+exit status is 0, the commands \c COMMANDS_TRUE will execute. If the
+exit status is not 0 and else is given, \c 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.
+the short circuit commands and
+and or.
The exit status of the last foreground command to exit can always be
accessed using the $status
diff --git a/doc_src/isatty.txt b/doc_src/isatty.txt
index bccf8ab86..d3b52892c 100644
--- a/doc_src/isatty.txt
+++ b/doc_src/isatty.txt
@@ -4,12 +4,11 @@
isatty [FILE DESCRIPTOR]
\subsection isatty-description Description
-The isatty command is used to test if a file descriptor is a tty.
+isatty tests if a file descriptor is a tty.
-FILE DESCRIPTOR may be either the number of a file descriptor, or one of the
-strings stdin, stdout and stderr.
+FILE DESCRIPTOR may be either the number of a file descriptor, or one of the
+strings stdin, \c stdout and stderr.
If the specified file descriptor is a tty, the exit status of the command is
-zero, otherwise, it is non-zero.
-
+zero. Otherwise, it is non-zero.
diff --git a/doc_src/jobs.txt b/doc_src/jobs.txt
index d4ea33dd3..8b96d1278 100644
--- a/doc_src/jobs.txt
+++ b/doc_src/jobs.txt
@@ -4,18 +4,22 @@
jobs [OPTIONS] [PID]
\subsection jobs-description Description
-The jobs builtin causes fish to print a list of the currently
-running jobs and their status.
+jobs prints a list of the currently
+running jobs and their status.
jobs accepts the following switches:
-- -c or --command print the command name for each process in jobs
-- -g or --group only print the group id of each job
-- -h or --help display a help message and exit
-- -l or --last only the last job to be started is printed
-- -p or --pid print the process id for each process in all jobs
+- -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\%.
+
+\subsection jobs-example Example
+
+jobs outputs a summary of the current jobs.
diff --git a/doc_src/math.txt b/doc_src/math.txt
index 9455e0da0..9904a2cce 100644
--- a/doc_src/math.txt
+++ b/doc_src/math.txt
@@ -6,10 +6,10 @@
\subsection math-description Description
-math is used to perform mathematical calculations. It is only a very
-thin wrapper for the bc program, that makes it possible to specify an
+\c 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. Simply use a command like math 1+1.
+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
@@ -18,3 +18,9 @@ order to perform calculations involving environment 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.
diff --git a/doc_src/mimedb.txt b/doc_src/mimedb.txt
index 6a4e99446..e38597ebc 100644
--- a/doc_src/mimedb.txt
+++ b/doc_src/mimedb.txt
@@ -5,21 +5,22 @@
\subsection mimedb-description Description
-- \c FILES is a list of files to analyse
-- \c -t, \c --input-file-data the specified files type should be determined both by their filename and by their contents (Default)
-- \c -f, \c --input-filename the specified files type should be determined by their filename
-- \c -i, \c --input-mime the arguments are not files but mimetypes
-- \c -m, \c --output-mime the output will be the mimetype of each file (Default)
-- \c -f, \c --output-description the output will be the description of each mimetype
-- \c -a, \c --output-action the output will be the default action of each mimetype
-- \c -l, \c --launch launch the default action for the specified file(s)
-- \c -h, \c --help display a help message and exit
-- \c -v, \c --version display version number and exit
+\c mimedb queries the MIME type database and the \c .desktop files
+installed on the system in order to find information on
+the files listed in FILES. The information that \c 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. \c mimedb can also
+be used to launch the default action for this file.
-The mimedb command is used to query the mimetype database and the
-.desktop files installed on the system in order to find information on
-a file. The information that mimedb can retrieve includes the mimetype
-for a file, a description of the type and what its default action
-is. mimedb can also be used to launch the default action for this
-file.
+The following options are available:
+
+- \c -t, \c --input-file-data determines the files' type both by their filename and by their contents (default behaviour).
+- \c -f, \c --input-filename determines the files' type by their filename.
+- \c -i, \c --input-mime specifies that the arguments are not files, but MIME types.
+- \c -m, \c --output-mime outputs the MIME type of each file (default behaviour).
+- \c -f, \c --output-description outputs the description of each MIME type.
+- \c -a, \c --output-action outputs the default action of each MIME type.
+- \c -l, \c --launch launches the default action for the specified files.
+- \c -h, \c --help displays a help message and exit.
+- \c -v, \c --version displays the version number and exits.
diff --git a/doc_src/nextd.txt b/doc_src/nextd.txt
index 5adbc915f..dba94ce02 100644
--- a/doc_src/nextd.txt
+++ b/doc_src/nextd.txt
@@ -1,10 +1,22 @@
\section nextd nextd - move forward through directory history
\subsection nextd-synopsis Synopsis
-nextd [-l | --list] [pos]
+nextd [-l | --list] [POS]
\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
-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
+
+cd /usr/src
+# Working directory is now /usr/src
+cd /usr/src/fish-shell
+# Working directory is now /usr/src/fish-shell
+prevd
+# Working directory is now /usr/src
+nextd
+# Working directory is now /usr/src/fish-shell
diff --git a/doc_src/not.txt b/doc_src/not.txt
index bb053da74..a1a1d2063 100644
--- a/doc_src/not.txt
+++ b/doc_src/not.txt
@@ -5,11 +5,13 @@
\subsection not-description Description
-The \c not builtin is used to negate the exit status of another command.
+\c not negates the exit status of another command. If the exit status
+is zero, \c not returns 1. Otherwise, \c not returns 0.
\subsection not-example Example
The following code reports an error and exits if no file named spoon can be found.
+
if not test -f spoon
echo There is no spoon
diff --git a/doc_src/open.txt b/doc_src/open.txt
index 0a4b89585..4dc03f9b7 100644
--- a/doc_src/open.txt
+++ b/doc_src/open.txt
@@ -5,7 +5,7 @@
\subsection open-description Description
-The \c open command is used to open a file in its default application. \c open is implemented using the \c xdg-open command if it exists, or else the mimedb command.
+\c open opens a file in its default application, using the \c xdg-open command if it exists, or else the mimedb command.
\subsection open-example Example
diff --git a/doc_src/or.txt b/doc_src/or.txt
index a33cb50d7..3567917f9 100644
--- a/doc_src/or.txt
+++ b/doc_src/or.txt
@@ -5,10 +5,10 @@
\subsection or-description Description
-The \c or builtin is used to execute a command if the current exit
+\c or is used to execute a command if the current exit
status (as set by the last previous command) is not 0.
-The or command does not change the current exit status.
+\c 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
@@ -16,10 +16,10 @@ variable.
\subsection or-example Example
-The following code runs the \c make command to build a program, if the
+The following code runs the \c 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
+build process.
make; and make install; or make clean
diff --git a/doc_src/popd.txt b/doc_src/popd.txt
index b3c87584d..deb3719f6 100644
--- a/doc_src/popd.txt
+++ b/doc_src/popd.txt
@@ -4,5 +4,21 @@
popd
\subsection popd-description Description
+
popd removes the top directory from the directory stack and
-cd's to the new top directory.
+changes the working directory to the new top directory. Use pushd to add directories to the stack.
+
+\subsection popd-example Example
+
+
+pushd /usr/src
+# Working directory is now /usr/src
+# Directory stack contains /usr/src
+pushd /usr/src/fish-shell
+# Working directory is now /usr/src/fish-shell
+# Directory stack contains /usr/src /usr/src/fish-shell
+popd
+# Working directory is now /usr/src
+# Directory stack contains /usr/src
+
diff --git a/doc_src/prevd.txt b/doc_src/prevd.txt
index 83d6b9093..b72fc3752 100644
--- a/doc_src/prevd.txt
+++ b/doc_src/prevd.txt
@@ -1,11 +1,24 @@
\section prevd prevd - move backward through directory history
\subsection prevd-synopsis Synopsis
-prevd [-l | --list] [pos]
+prevd [-l | --list] [POS]
\subsection prevd-description Description
-prevd moves backwards pos positions in the history
+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.
+a warning is printed.
+
+If the -l or --list flag is specified, the current
+history is also displayed.
+
+\subsection prevd-example Example
+
+cd /usr/src
+# Working directory is now /usr/src
+cd /usr/src/fish-shell
+# Working directory is now /usr/src/fish-shell
+prevd
+# Working directory is now /usr/src
+nextd
+# Working directory is now /usr/src/fish-shell
diff --git a/doc_src/psub.txt b/doc_src/psub.txt
index c12278d3e..7f4dbedd4 100644
--- a/doc_src/psub.txt
+++ b/doc_src/psub.txt
@@ -11,12 +11,12 @@ 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. The psub shellscript function, which when combined with a
+program. \c psub combined with a
regular command substitution provides the same functionality.
-If the \c -f or \c --file switch is given to psub, psub will use a
+If the \c -f or \c --file switch is given to psub, \c 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
+process. This will cause \c 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.
diff --git a/doc_src/pushd.txt b/doc_src/pushd.txt
index 3093cbaa0..dbcd7f917 100644
--- a/doc_src/pushd.txt
+++ b/doc_src/pushd.txt
@@ -4,6 +4,20 @@
pushd [DIRECTORY]
\subsection pushd-description Description
-The pushd function adds DIRECTORY to the top of the directory stack
-and makes it the current directory. Use popd to pop it off and
+The pushd function adds \c 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
+
+
+pushd /usr/src
+# Working directory is now /usr/src
+# Directory stack contains /usr/src
+pushd /usr/src/fish-shell
+# Working directory is now /usr/src/fish-shell
+# Directory stack contains /usr/src /usr/src/fish-shell
+popd
+# Working directory is now /usr/src
+# Directory stack contains /usr/src
+
diff --git a/doc_src/pwd.txt b/doc_src/pwd.txt
index 92bb5e551..138e8dcb1 100644
--- a/doc_src/pwd.txt
+++ b/doc_src/pwd.txt
@@ -1,8 +1,10 @@
-\section pwd pwd - returns the current directory
+\section pwd pwd - output the current working directory
\subsection pwd-synopsis Synopsis
pwd
\subsection pwd-description Description
-Returns the current directory. Note that fish always resolves symbolic links in the current directory path.
+\c pwd outputs (prints) the current working directory.
+
+Note that \c fish always resolves symbolic links in the current directory path.
diff --git a/doc_src/random.txt b/doc_src/random.txt
index ad9b658a0..b6bb9df09 100644
--- a/doc_src/random.txt
+++ b/doc_src/random.txt
@@ -5,10 +5,11 @@
\subsection random-description Description
-The \c random command is used to generate a random number in the
-interval 0<=N<32767. If an argument is given, it is used to seed the
-random number generator. This can be useful for debugging purposes,
-where it can be desirable to get the same random number sequence
+\c random outputs a random number from 0 to 32766, inclusive.
+
+If a \c 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.
diff --git a/doc_src/read.txt b/doc_src/read.txt
index d69d715b7..1e8aef373 100644
--- a/doc_src/read.txt
+++ b/doc_src/read.txt
@@ -5,27 +5,29 @@
\subsection read-description Description
-The read builtin causes fish to read one line from standard
-input and store the result in one or more environment variables.
+read reads one line from standard
+input and stores the result in one or more environment variables.
-- -c CMD or --command=CMD specifies that the initial string in the interactive mode command buffer should be CMD.
-- -g or --global specifies that the variables will be made global.
-- -l or --local specifies that the variables will be made local.
+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 (default behaviour).
+- -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 specifies that the output of the shell command PROMPT_CMD should be used as the prompt for the interactive mode prompt. The default prompt command is set_color green; echo read; set_color normal; echo "> ".
-- -s or --shell Use syntax highlighting, tab completions and command termination suitable for entering shellscript code
-- -u or --unexport causes the specified environment not to be exported to child processes
-- -U or --universal causes the specified environment variable to be made universal. 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 environment variable to be exported to child processes
+- -p PROMPT_CMD or --prompt=PROMPT_CMD uses the output of the shell command \c 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 environment variable to be made universal.
+- -x or --export exports the variables to child processes.
-Read starts by reading a single line of input from stdin, the line is
-then tokenized using the IFS environment variable. Each variable
-specified in VARIABLES is then assigned one tokenized string
-element. If there are more tokens than variables, the complete
-remainder is assigned to the last variable.
+\c read reads a single line of input from stdin, breaks it into tokens
+based on the IFS environment 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.
\subsection read-example Example
-echo hello|read foo
+The following code stores the value 'hello' in the environment variable
+$foo.
-Will cause the variable \$foo to be assigned the value hello.
+echo hello|read foo
diff --git a/doc_src/return.txt b/doc_src/return.txt
index 2cfd5ab62..9563cf399 100644
--- a/doc_src/return.txt
+++ b/doc_src/return.txt
@@ -1,19 +1,19 @@
-\section return return - stop the innermost currently evaluated function
+\section return return - stop the current inner function
\subsection return-synopsis Synopsis
function NAME; [COMMANDS...;] return [STATUS]; [COMMANDS...;] end
\subsection return-description Description
-The \c return builtin is used to halt a currently running 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.
-- \c STATUS is the return status of the function. If unspecified, the status is unchanged.
-
\subsection return-example Example
The following code is an implementation of the false command as a fish function
diff --git a/doc_src/set.txt b/doc_src/set.txt
index e46cd9c47..e9e67392e 100644
--- a/doc_src/set.txt
+++ b/doc_src/set.txt
@@ -1,4 +1,4 @@
-\section set set - handle environment variables.
+\section set set - display and change environment variables.
\subsection set-synopsis Synopsis
@@ -10,31 +10,39 @@ set (-e | --erase) [SCOPE_OPTIONS] VARIABLE_NAME
set (-e | --erase) [SCOPE_OPTIONS] VARIABLE_NAME[INDICES]...
-The set builtin causes fish to assign the variable VARIABLE_NAME the values VALUES....
-
\subsection set-description Description
-- -e or --erase causes the specified environment variable to be erased
-- -l or --local forces the specified environment 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 environment variable to be given a global scope. Non-global variables disappear when the block they belong to ends
-- -U or --universal causes the specified environment 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.
-- -n or --names List only the names of all defined variables, not their value
-- -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.
-- -u or --unexport causes the specified environment not to be exported to child processes
-- -x or --export causes the specified environment variable to be exported to child processes
-- -L or --long do not abbreviate long values when printing set variables
+
+set manipulates environment
+variables.
If set is called with no arguments, the names and values of all
environment 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, \c set assigns the variable
+VARIABLE_NAME the values VALUES....
+
+The following options control variable scope:
+- -l or --local forces the specified environment 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 environment variable to be given a global scope. Non-global variables disappear when the block they belong to ends
+- -U or --universal causes the specified environment 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.
+- -n or --names List only the names of all defined variables, not their value
+- -u or --unexport causes the specified environment not to be exported to child processes
+- -x or --export causes the specified environment variable to be exported to child processes
+
+The following options are available:
+- -e or --erase causes the specified environment 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.
+- -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
+changed. When array indices are specified to \c 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
@@ -63,17 +71,17 @@ be specified. That way, a global variable can be erased even if a
local variable with the same name exists. Scope can not be specified
when erasing a slice of an array. The innermost scope is always used.
-The set command requires all switch arguments to come before any
-non-switch arguments. For example, set flags -l will have
+\c 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
+In assignment mode, \c 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
+were not found. In erase mode, \c 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.
diff --git a/doc_src/set_color.txt b/doc_src/set_color.txt
index 79eca8e0b..546889cd7 100644
--- a/doc_src/set_color.txt
+++ b/doc_src/set_color.txt
@@ -5,37 +5,36 @@
\subsection set_color-description Description
-Change the foreground and/or background color of the terminal.
-COLOR is one of black, red, green, brown, yellow, blue, magenta,
+\c set_color changes the foreground and/or background color of the terminal.
+\c 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.
+as A0FF33 or f2f. \c fish will choose the closest supported color.
-- \c -b, \c --background Set the background color
-- \c -c, \c --print-colors Prints a list of all valid color names
-- \c -h, \c --help Display help message and exit
-- \c -o, \c --bold Set bold or extra bright mode
-- \c -u, \c --underline Set underlined mode
+The following options are available:
+- \c -b, \c --background \c COLOR sets the background color.
+- \c -c, \c --print-colors prints a list of all valid color names.
+- \c -h, \c --help displays a help message and exit.
+- \c -o, \c --bold sets bold or extra bright mode.
+- \c -u, \c --underline sets underlined mode.
Calling set_color normal will set the terminal color to
-whatever is the default color of the terminal.
+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. This is not a
-bug in set_color but a missing feature in the terminal emulator.
+Not all terminal emulators support all these features.
-set_color uses the terminfo database to look up how to change terminal
+\c 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. Download and install the latest version of
-ncurses and recompile fish against it in order to fix this issue.
+terminals that support it.
\subsection set_color-example Examples
set_color red; echo "Roses are red"
diff --git a/doc_src/source.txt b/doc_src/source.txt
index d92d1cc96..069583754 100644
--- a/doc_src/source.txt
+++ b/doc_src/source.txt
@@ -5,24 +5,22 @@
\subsection source-description Description
-Evaluates the commands of the specified file in the current
+\c . (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
-environment variables, etc., will remain. If additional arguments are
+environment variables 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.
-The return status of . is the return status of the last job to
+The return status of \c . is the return status of the last job to
execute. If something goes wrong while opening or reading the file,
-. exits with a non-zero status.
+\c . exits with a non-zero status.
\subsection source-example Example
-. ~/.config/fish/config.fish
-
-causes fish to reread its initialization file.
+. ~/.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 a14ee9195..d6238ae3b 100644
--- a/doc_src/status.txt
+++ b/doc_src/status.txt
@@ -6,16 +6,16 @@
\subsection status-description Description
With no arguments, status displays a summary of the current login and job control status of the shell.
-The following arguments 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, i.e.connected to a keyboard
-- -l or --is-login returns 0 if fish is a login shell, i.e. 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 set the job control type. Can be one of: none, full, interactive
-- -t or --print-stack-trace prints a stack trace of all function calls on the call stack
-- -h or --help display a help message and exit
+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 cbfb4be9a..7b9b0308e 100644
--- a/doc_src/switch.txt
+++ b/doc_src/switch.txt
@@ -5,27 +5,24 @@
\subsection switch-description Description
-The \c switch statement is used to perform one of several blocks of
-commands depending on whether a specified value equals one of several
-wildcarded values. The \c case statement is used together with the \c
-switch statement in order to determine which block should be
-performed.
+\c switch performs one of several blocks of commands, depending on whether
+a specified value equals one of several wildcarded values. \c case is used
+together with the \c switch statement in order to determine which block should
+be executed.
-Each \c case command is given one or more parameter. The first \c case
+Each \c case command is given one or more parameters. The first \c case
command with a parameter that matches the string specified in the
switch command will be evaluated. \c 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. Though the
-syntax may look a bit like C switch statements, it behaves more like
-the case statements of traditional shells.
+Note that fish does not fall through on case statements. Only the
+first matching case is executed.
-Also note that command substitutions in a case statement will be
-evaluated even if it's body is not taken. This may seem
-counterintuitive at first, but it is unavoidable, since it would be
-impossible to know if a case command will evaluate to true before all
-forms of parameter expansion have been performed for the case command.
+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
diff --git a/doc_src/test.txt b/doc_src/test.txt
index b48790573..600e7ea78 100644
--- a/doc_src/test.txt
+++ b/doc_src/test.txt
@@ -3,41 +3,40 @@
\subsection test-synopsis Synopsis
test [EXPRESSION]
-\subsection test-description Description
-
-Tests the expression given and returns true or false.
+\subsection test-description Description
-- \c -h, \c Display this help
-- \c -G, \c File owned by effective group ID
-- \c -L, \c File is symlink
-- \c -O, \c File owned by effective user ID
-- \c -S, \c File is socket
-- \c -a, \c Logical and
-- \c -b, \c File is block device
-- \c -c, \c File is character device
-- \c -d, \c File is a directory
-- \c -e, \c File exists
-- \c -f, \c File is regular
-- \c -f, \c File is set-group-ID
-- \c -k, \c File has sticky bit set
-- \c -n, \c String length is non-zero
-- \c -o, \c Logical or
-- \c -p, \c File is named pipe
-- \c -r, \c File is readable
-- \c -s, \c File size is non-zero
-- \c -t, \c FD is terminal
-- \c -u, \c File set-user-ID bit is set
-- \c -w, \c File is writable
-- \c -x, \c File is executable
-- \c -z, \c String length is zero
+Tests the expression given and sets the exit status to 0 if true,
+and 1 if false.
+
+The following options are available:
+- \c -h displays a help message and then exits.
+- -L FILE returns true if \c FILE is a symbolic link.
+- -S FILE returns true if \c FILE is a socket.
+- COND1 -a COND2 combines two conditions with a logical and.
+- -b FILE returns true if \c FILE is a block device.
+- -c FILE returns true if \c FILE is a character device.
+- -d FILE returns true if \c FILE is a directory.
+- -e FILE returns true if \c FILE exists.
+- -f FILE returns true if \c FILE is a regular file.
+- -f FILE returns true if \c FILE has set-group-ID bit set.
+- -n STRING returns true if the length of \c STRING is non-zero.
+- COND1 -o COND2 combines two conditions with a logical or.
+- -p FILE returns true if \c FILE is a named pipe.
+- -r FILE returns true if \c FILE is readable.
+- -s FILE returns true if the size of \c FILE is non-zero.
+- -t FD returns true if \c FD is a terminal (TTY).
+- -u FILE returns true if \c FILE has set-user-ID bit set.
+- -w FILE returns true if \c FILE is writable.
+- -x FILE returns true if \c FILE is executable.
+- -z STRING returns true if \c STRING length is zero.
\subsection test-example Example
- if test -d "/"
- echo "Fish is cool"
- end
+if test -d "/"
+ echo "Fish is cool"
+end
-Because "/" is a directory the expression will evaluate
-to true, and "Fish is cool" will be echoed
+Because "/" is a directory, the expression will evaluate to true, and
+"Fish is cool" will be output.
diff --git a/doc_src/trap.txt b/doc_src/trap.txt
index bd44d4584..aaaa5b2b6 100644
--- a/doc_src/trap.txt
+++ b/doc_src/trap.txt
@@ -5,32 +5,39 @@
\subsection trap-description Description
-Trap is a shellscript wrapper around the fish event delivery
-framework. It exists for backwards compatibility with Posix
-shells. For other uses, it is recommended to define a event handler.
-- ARG is the command to be executed on signal delivery
-- SIGSPEC is the name of the signal to trap
-- \c -h or \c --help Display help and exit
-- \c -l or \c --list-signals print a list of signal names
-- \c -p or \c --print print all defined signal handlers
+The following parameters are available:
-If ARG and SIGSPEC are both specified, ARG is the command to be
-executed when the signal specified by SIGSPEC is delivered.
+- \c ARG is the command to be executed on signal delivery.
+- \c SIGSPEC is the name of the signal to trap.
+- \c -h or \c --help displays help and exits.
+- \c -l or \c --list-signals prints a list of signal names.
+- \c -p or \c --print prints all defined signal handlers.
-If ARG is absent (and there is a single SIGSPEC) or -, each specified
+If \c ARG and \c SIGSPEC are both specified, \c ARG is the command to be
+executed when the signal specified by \c SIGSPEC is delivered.
+
+If \c 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
+entrance to the shell). If \c ARG is the null string the signal
+specified by each \c 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
+If \c ARG is not present and \c -p has been supplied, then the trap commands
+associated with each \c SIGSPEC are displayed. If no arguments are
+supplied or if only \c -p is given, \c trap prints the list of commands
associated with each signal.
-Signal names are case insensitive and the SIG prefix is optional.
+Signal names are case insensitive and the \c SIG prefix is optional.
-The return status is 1 if any SIGSPEC is invalid; otherwise trap
+The return status is 1 if any \c SIGSPEC is invalid; otherwise trap
returns 0.
+
+\subsection trap-example Example
+
+trap "status --print-stack-trace" SIGUSR1 prints a stack trace
+each time the \c SIGUSR1 signal is sent to the shell.
diff --git a/doc_src/type.txt b/doc_src/type.txt
index dde723644..9b5699f35 100644
--- a/doc_src/type.txt
+++ b/doc_src/type.txt
@@ -1,21 +1,23 @@
-\section type type - indicate how a name would be interpreted if used as a command name
+\section type type - indicate how a command would be interpreted
\subsection type-synopsis Synopsis
- type [OPTIONS] name [name ...]
+ type [OPTIONS] NAME [NAME ...]
\subsection type-description Description
-With no options, indicate how each name would be interpreted if used as a command name.
+With no options, \c type indicates how each \c NAME would be interpreted if used as a command name.
-- \c -h or \c --help print this message
-- \c -a or \c --all print all of possible definitions of the specified names
-- \c -f or \c --no-functions suppresses function and builtin lookup
-- \c -t or \c --type print a string which is one of keyword, function, builtin, or file if name is a shell reserved word, function, builtin, or disk file, respectively
-- \c -p or \c --path either return the name of the disk file that would be executed if name were specified as a command name, or nothing if 'type -t name' would not return 'file'
-- \c -P or \c --force-path either return the name of the disk file that would be executed if name were specified as a command name, or nothing no file with the specified name could be found in the PATH
+The following options are available:
-\c type returns a zero exit status if the specified command was found,
-otherwise the exit status is one.
+- \c -h or \c --help prints help and then exits.
+- \c -a or \c --all prints all of possible definitions of the specified names.
+- \c -f or \c --no-functions suppresses function and builtin lookup.
+- \c -t or \c --type prints keyword, function, builtin, or file if \c NAME is a shell reserved word, function, builtin, or disk file, respectively.
+- \c -p or \c --path returns the name of the disk file that would be executed, or nothing if 'type -t name' would not return 'file'.
+- \c -P or \c --force-path returns the name of the disk file that would be executed, or nothing no file with the specified name could be found in the $PATH.
+
+\c type sets the exit status to 0 if the specified command was found,
+and 1 if it could not be found.
\subsection type-example Example
diff --git a/doc_src/ulimit.txt b/doc_src/ulimit.txt
index 6e21eba30..7b4e3c451 100644
--- a/doc_src/ulimit.txt
+++ b/doc_src/ulimit.txt
@@ -1,67 +1,66 @@
-\section ulimit ulimit - set or get the shells resource usage limits
+\section ulimit ulimit - set or get resource usage limits
\subsection ulimit-synopsis Synopsis
ulimit [OPTIONS] [LIMIT]
\subsection ulimit-description Description
-The ulimit builtin is used to set the resource usage limits of the
-shell and any processes spawned by it. If a new limit value is
-omitted, the current value of the limit of the resource is printed.
+\c ulimit builtin sets or outputs the resource usage limits of the
+shell and any processes spawned by it. If a new limit value is
+omitted, the current value of the limit of the resource is printed; otherwise,
+the specified limit is set to the new value.
Use one of the following switches to specify which resource limit to set or report:
-- -c or --core-size The maximum size of core files created. By setting this limit to zero, core dumps can be disabled.
-- -d or --data-size The maximum size of a process's data segment
-- -f or --file-size The maximum size of files created by the shell
-- -l or --lock-size The maximum size that may be locked into memory
-- -m or --resident-set-size The maximum resident set size
-- -n or --file-descriptor-count The maximum number of open file descriptors (most systems do not allow this value to be set)
-- -s or --stack-size The maximum stack size
-- -t or --cpu-time The maximum amount of cpu time in seconds
-- -u or --process-count The maximum number of processes available to a single user
-- -v or --virtual-memory-size The maximum amount of virtual memory available to the shell. If supported by OS.
+- -c or --core-size: the maximum size of core files created. By setting this limit to zero, core dumps can be disabled.
+- -d or --data-size: the maximum size of a process' data segment.
+- -f or --file-size: the maximum size of files created by the shell.
+- -l or --lock-size: the maximum size that may be locked into memory.
+- -m or --resident-set-size: the maximum resident set size.
+- -n or --file-descriptor-count: the maximum number of open file descriptors (most systems do not allow this value to be set).
+- -s or --stack-size: the maximum stack size.
+- -t or --cpu-time: the maximum amount of CPU time in seconds.
+- -u or --process-count: the maximum number of processes available to a single user.
+- -v or --virtual-memory-size The maximum amount of virtual memory available to the shell.
Note that not all these limits are available in all operating systems.
The value of limit can be a number in the unit specified for
-the resource or one of the special values hard, soft, or unlimited,
+the resource or one of the special values hard, soft, or unlimited,
which stand for the current hard limit, the current soft limit, and no
limit, respectively.
If limit is given, it is the new value of the specified resource. If
-no option is given, then -f is assumed. Values are in kilobytes,
-except for -t, which is in seconds and -n and -u, which are unscaled
+no option is given, then \c -f is assumed. Values are in kilobytes,
+except for \c -t, which is in seconds and \c -n and \c -u, which are unscaled
values. The return status is 0 unless an invalid option or argument is
supplied, or an error occurs while setting a new limit.
-ulimit also accepts the following switches that determine what type of
+\c ulimit also accepts the following switches that determine what type of
limit to set:
-- -H or --hard Set hard resource limit
-- -S or --soft Set soft resource limit
+- -H or --hard sets hard resource limit
+- -S or --soft sets soft resource limit
-A hard limit can only be decreased, once it is set it can not be
+A hard limit can only be decreased. Once it is set it cannot be
increased; a soft limit may be increased up to the value of the hard
limit. If neither -H nor -S is specified, both the soft and hard
limits are updated when assigning a new limit value, and the soft
limit is used when reporting the current value.
-The following additional options are also understood by ulimit:
+The following additional options are also understood by ulimit:
-- -a or --all Print all current limits
-- -h or --help Display help and exit
+- -a or --all prints all current limits
+- -h or --help displays help and exits.
-The fish implementation of ulimit should behave identically to the
+The \c fish implementation of \c ulimit should behave identically to the
implementation in bash, except for these differences:
-- Fish ulimit supports GNU-style long options for all switches
-- Fish ulimit does not support the -p option for getting the pipe size. The bash implementation consists of a compile-time check that empirically guesses this number by writing to a pipe and waiting for SIGPIPE. Fish does not do this because it this method of determining pipe size is unreliable. Depending on bash version, there may also be further additional limits to set in bash that do not exist in fish.
-- Fish ulimit does not support getting or setting multiple limits in one command, except reporting all values using the -a switch
+- Fish \c ulimit supports GNU-style long options for all switches
+- Fish \c ulimit does not support the \c -p option for getting the pipe size. The bash implementation consists of a compile-time check that empirically guesses this number by writing to a pipe and waiting for SIGPIPE. Fish does not do this because it this method of determining pipe size is unreliable. Depending on bash version, there may also be further additional limits to set in bash that do not exist in fish.
+- Fish \c ulimit does not support getting or setting multiple limits in one command, except reporting all values using the -a switch
\subsection ulimit-example Example
-ulimit -Hs 64
-
-would set the hard stack size limit to 64 kB:
+ulimit -Hs 64 sets the hard stack size limit to 64 kB.
diff --git a/doc_src/umask.txt b/doc_src/umask.txt
index 0a75e3db7..bc9aac0c1 100644
--- a/doc_src/umask.txt
+++ b/doc_src/umask.txt
@@ -1,17 +1,31 @@
-\section umask umask - set or get the file-creation mask
+\section umask umask - set or get the file creation mode mask
\subsection umask-synopsis Synopsis
umask [OPTIONS] [MASK]
\subsection umask-description Description
-With no argument, the current file-creation mask is printed, if an
-argument is specified, it is the new file creation mask. The mask may
-be specified as an octal number, in which case it is interpreted as
-the rights that should be masked away, i.e. it is the inverse of the
-file permissions any new files will have.
+\c umask displays and manipulates the "umask", or file creation mode mask,
+which is used to restrict the default access to files.
-If a symbolic mask is specified, the actual file permission bits, and
+The umask may be expressed either as an octal number, which represents
+the rights that will be removed by default, or symbolically, which represents
+the only rights that will be granted by default.
+
+Access rights are explained in the manual page for the \c chmod(1) program.
+
+With no parameters, the current file creation mode mask is printed as
+an octal number.
+
+- -h or --help prints this message.
+- -S or --symbolic prints the umask in symbolic form instead of octal form.
+- -p or --as-command outputs the umask in a form that may be reused as input
+
+If a numeric mask is specified as a parameter, the current shell's umask
+will be set to that value, and the rights specified by that mask will be
+removed from new files and directories by default.
+
+If a symbolic mask is specified, the desired permission bits, and
not the inverse, should be specified. A symbolic mask is a comma
separated list of rights. Each right consists of three parts:
@@ -34,12 +48,7 @@ and \c =, respectively. As an example, r,u+w means all
users should have read access and the file owner should also have
write access.
-- -h or --help print this message
-- -S or --symbolic prints the file-creation mask in symbolic form instead of octal form. Use man chmod for more information.
-- -p or --as-command prints any output in a form that may be reused as input
-
-The umask implementation in fish should behave identically to the one
-in bash.
+Note that symbolic masks currently do not work as intended.
\subsection umask-example Example
diff --git a/doc_src/vared.txt b/doc_src/vared.txt
index 9f1cef531..609172d78 100644
--- a/doc_src/vared.txt
+++ b/doc_src/vared.txt
@@ -5,8 +5,8 @@
\subsection vared-description Description
-vared is used to interactively edit the value of an environment
-variable. Array variables as a whole can not be edited using vared,
+\c vared is used to interactively edit the value of an environment
+variable. Array variables as a whole can not be edited using \c vared,
but individual array elements can.
\subsection vared-example Example
diff --git a/doc_src/while.txt b/doc_src/while.txt
index 1ec643d2f..496c36c22 100644
--- a/doc_src/while.txt
+++ b/doc_src/while.txt
@@ -4,16 +4,18 @@
while CONDITION; COMMANDS...; end
\subsection while-description Description
-The while builtin causes fish to continually execute CONDITION and
-execute COMMANDS as long as CONDITION returned with status 0. If CONDITION is
-false on the first time, COMMANDS will not be executed at all. Hints: use
-begin; ...; end for complex conditions; more
+while repeatedly executes CONDITION, and if the exit status
+is 0, then executes COMMANDS.
+
+If the exit status of \c CONDITION is non-zero on the first iteration,
+\c COMMANDS will not be executed at all.
+
+Use begin; ...; end for complex conditions; more
complex control can be achieved with while true containing a
break.
\subsection while-example Example
while test -f foo.txt; echo file exists; sleep 10; end
-
-causes fish to print the line 'file exists' at 10 second intervals as long as
+outputs 'file exists' at 10 second intervals as long as
the file foo.txt exists.