Help cleanup

Large list of changes, including formatting and typos for most commands.

More substantive changes have been made to alias, bind, block, break,
builtin, case, cd, commandline, count, else, emit, fish_config, funced,
function, functions, history, math, mimedb, nextd, not, popd, prevd,
pushd, pwd, random, read, set, set_color, switch, test, trap, type,
ulimit, umask, and while.

70 files changed, 722 insertions, 505 deletions

diff --git a/doc_src/alias.txt b/doc_src/alias.txt
index 2ab277e9..84288c18 100644
--- a/doc_src/alias.txt
+++ b/doc_src/alias.txt
@@ -6,13 +6,29 @@ alias NAME=DEFINITION</pre>
 
 \subsection alias-description Description
 
-Alias is a shellscript wrapper around the function builtin.
+\c alias is a simple wrapper for the \c function builtin.
 It exists for backwards compatibility with Posix
 shells. For other uses, it is recommended to define a <a
 href='#function'>function</a>.
 
-Alias does not keep track of which functions have been defined using
-alias, nor does it allow erasing of aliases.
+\c fish does not keep track of which functions have been defined using
+\c alias. They must be erased using <code>functions -e</code>.
+
+- NAME is the name of the alias
+- DEFINITION is the actual command to execute. The string " $argv" will be appended.
+
+You cannot create an alias to a function with the same name.
+
+\subsection alias-example Example
+
+The following code will create \c rmi, which runs \c rm with additional
+arguments on every invocation.
+
+<code>alias rmi "rm -i"</code>
+
+This is equivalent to entering the following function:
+
+<pre>function rmi
+    rm -i $argv
+end</pre>
 
-- NAME is the name of the function to define
-- DEFINITION is the body of the function. The string " $argv" will be appended to the body.
diff --git a/doc_src/and.txt b/doc_src/and.txt
index 0562fae9..3eb42c19 100644
--- a/doc_src/and.txt
+++ b/doc_src/and.txt
@@ -5,10 +5,10 @@
 
 \subsection and-description Description
 
-The \c and builtin is used to execute a command if the current exit
+\c and is used to execute a command if the current exit
 status (as set by the last previous command) is 0.
 
-The and command does not change the current exit status.
+\c and does not change the current exit status.
 
 The exit status of the last foreground command to exit can always be
 accessed using the <a href="index.html#variables-status">$status</a>
@@ -16,10 +16,10 @@ variable.
 
 \subsection and-example Example
 
-The following code runs the \c make command to build a program, if the
-build succeeds, the program is installed. If either step fails,
-<tt>make clean</tt> is run, which removes the files created by the
-build process
+The following code runs the \c make command to build a program. If the
+build succeeds, <code>make</code>'s exit status is 0, and the program is installed. If either step fails,
+the exit status is 1, and <tt>make clean</tt> is run, which removes the files created by the.
+build process.
 
 <pre>
 make; and make install; or make clean
diff --git a/doc_src/begin.txt b/doc_src/begin.txt
index f5f7f53e..fafe9849 100644
--- a/doc_src/begin.txt
+++ b/doc_src/begin.txt
@@ -5,15 +5,18 @@
 
 \subsection begin-description Description
 
-The \c begin builtin is used to create a new block of code. The block
+\c begin is used to create a new block of code.
+
+The block
 is unconditionally executed. <code>begin; ...; end</tt> is equivalent
-to <tt>if true; ...; end</tt>. 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 <tt>if true; ...; end</tt>.
+
+\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 dc607b06..9c8f593a 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
 <tt>bg [PID...]</tt>
 
 \subsection bg-description Description
-Sends the specified jobs to the background. A background job is
+
+\c bg sends <a href="index.html#syntax-job-control">jobs</a> 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 <a href="index.html#expand-process">process expansion</a>.
 
 \subsection bg-example Example
 
-<tt>bg \%0</tt> will put the job with job id 0 in the background.
+<tt>bg \%1</tt> will put the job with job ID 1 in the background.
 
diff --git a/doc_src/bind.txt b/doc_src/bind.txt
index 3bf9fb45..614a1495 100644
--- a/doc_src/bind.txt
+++ b/doc_src/bind.txt
@@ -5,33 +5,34 @@
 
 \subsection bind-description Description
 
-The <tt>bind</tt> builtin causes fish to add a key binding from the specified sequence.
+<tt>bind</tt> 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
+<a href="index.html#escapes">fish escape sequences</a>. 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
-<tt>\\ew</tt>. Control character can be written in much the same way
-using the \c \\c escape, for example Control-x can be written as
+<tt>\\ew</tt>. 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
 <tt>\\cx</tt>. 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, <code>''</code>). 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. <tt>bind '' self-insert</tt> 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 <tt>bind
---key-names</tt> for a list of all available named keys)
+prefix. (See \c terminfo(5) for more information, or use <tt>bind
+--key-names</tt> 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:
 
-- <tt>-a</tt> or <tt>--all</tt> 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.
-- <tt>-e</tt> or <tt>--erase</tt> Erase mode. All non-switch arguments are interpreted as character sequences and any commands associated with those sequences are erased.
-- <tt>-h</tt> or <tt>--help</tt> Display help and exit
 - <tt>-k</tt> or <tt>--key</tt> Specify a key name, such as 'left' or 'backspace' instead of a character sequence
 - <tt>-K</tt> or <tt>--key-names</tt> Display a list of available key names
 - <tt>-f</tt> or <tt>--function-names</tt> Display a list of available input functions
 
-\subsection bind-example Example
+\subsection bind-example Examples
 
-<tt>bind \\cd 'exit'</tt> causes fish to exit on Control-d
+<tt>bind \\cd 'exit'</tt> causes \c fish to exit when Control-d is pressed.
 
-<tt>bind -k ppage history-search-backward</tt> Causes fish to perform a history search when the page up key is pressed
+<tt>bind -k ppage history-search-backward</tt> performs a history search when the Page Up key is pressed.
 
diff --git a/doc_src/block.txt b/doc_src/block.txt
index 670a39b2..0f4cff38 100644
--- a/doc_src/block.txt
+++ b/doc_src/block.txt
@@ -5,15 +5,36 @@
 
 \subsection block-description Description
 
-- <tt>-l</tt> or <tt>--local</tt> Release the block at the end of the currently innermost block scope
+\c block prevents events triggered by \c fish or the
+<a href="commands.html#emit"><code>emit</code></a> 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 <code>begin</code>, <code>if</code>, <code>while</code> or
+<code>for</code>
+
+The following parameters are available:
+
+- <tt>-l</tt> or <tt>--local</tt> Release the block automatically at the end of the current innermost code block scope
 - <tt>-g</tt> or <tt>--global</tt> Never automatically release the lock
 - <tt>-e</tt> or <tt>--erase</tt> Release global block
 
 \subsection block-example Example
 
 <pre>
+# 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
 </pre>
 
diff --git a/doc_src/break.txt b/doc_src/break.txt
index 9e511872..3f46bb8c 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
  <tt>LOOP_CONSTRUCT; [COMMANDS...] break; [COMMANDS...] end</tt>
 
 \subsection break-description Description
-The \c break builtin is used to halt a currently running loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement.
+
+\c break halts a currently running loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement.
+
+There are no parameters for <code>break</code>.
 
 \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.
 
 <pre>
 for i in *.c
diff --git a/doc_src/breakpoint.txt b/doc_src/breakpoint.txt
index f3332c75..744727fa 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 <a href="index.html#debugging">Debugging fish
+scripts</a> in the \c fish manual.
+
+There are no parameters for <code>breakpoint</code>.
diff --git a/doc_src/builtin.txt b/doc_src/builtin.txt
index a077a1bf..fd93f703 100644
--- a/doc_src/builtin.txt
+++ b/doc_src/builtin.txt
@@ -5,12 +5,12 @@
 
 \subsection builtin-description Description
 
-- <tt>-n</tt> or <tt>--names</tt> 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:
 
-\subsection builtin-example Example
+- <tt>-n</tt> or <tt>--names</tt> List the names of all defined builtins
 
-<tt>builtin jobs</tt>
+\subsection builtin-example Example
 
-causes fish to execute the jobs builtin, even if a function named jobs exists.
+<tt>builtin jobs</tt> executes the jobs builtin, even if a function named jobs exists.
diff --git a/doc_src/case.txt b/doc_src/case.txt
index 468cc3c4..b5601cdb 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 13184e10..c1a5875a 100644
--- a/doc_src/cd.txt
+++ b/doc_src/cd.txt
@@ -4,8 +4,21 @@
 <tt>cd [DIRECTORY]</tt>
 
 \subsection cd-description Description
-Changes the current directory. If <tt>DIRECTORY</tt> 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.
+
+<code>cd /usr/src/fish-shell</code> changes the working directory to
+<code>/usr/src/fish-shell</code>.
diff --git a/doc_src/command.txt b/doc_src/command.txt
index 885cca5f..19baccd4 100644
--- a/doc_src/command.txt
+++ b/doc_src/command.txt
@@ -4,11 +4,9 @@
 <tt>command COMMANDNAME [OPTIONS...]</tt>
 
 \subsection command-description Description
-prefixing a command with the word 'command' forces fish to ignore any functions or builtins with the same name.
-
-\subsection command-example Example
 
+\c command forces the shell to execute the program \c COMMANDNAME and ignore any functions or builtins with the same name.
 
-<tt>command ls</tt>
+\subsection command-example Example
 
-causes fish to execute the ls program, even if there exists a 'ls' function.
+<tt>command ls</tt> 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 df03ab13..ab771e96 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
 <tt>commandline [OPTIONS] [CMD]</tt>
 
 \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 <code>complete -C STRING</code>, 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 <code>complete -C STRING</code>, \c commandline will consider the
+specified string to be the current contents of the command line.
 
 \subsection commandline-example Example
 
-<tt>commandline -j $history[3]</tt>
-
-replaces the job under the cursor with the third item from the
-commandline history.
+<tt>commandline -j $history[3]</tt> 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 f6d00a15..c2085ccb 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
 <tt>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] </tt>
 
 \subsection complete-description Description
 
-For an introduction to how to specify completions, see the section <a
-href='index.html#completion-own'>Writing your own completions</a> of
+For an introduction to specifying completions, see <a
+href='index.html#completion-own'>Writing your own completions</a> in
 the fish manual.
 
 - <tt>COMMAND</tt> 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 1a08a2ac..cc746358 100644
--- a/doc_src/contains.txt
+++ b/doc_src/contains.txt
@@ -5,12 +5,14 @@
 
 \subsection contains-description Description
 
-- \c -i or \c --index print the word index
-- \c -h or \c --help display this message
+\c contains tests whether the set \c VALUES contains the string
+<code>KEY</code>. If so, \c contains exits with status 0; if not, it exits
+with status 1.
 
-Test if the set VALUES contains the string KEY. Return status is 0 if
-yes, 1 otherwise
+The following options are available:
 
+- \c -i or \c --index print the word index
+- \c -h or \c --help display this message
 
 \subsection contains-example Example
 <pre>
@@ -21,4 +23,4 @@ for i in ~/bin /usr/local/bin
 end
 </pre>
 
-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 47009393..9b1803f5 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
 <tt>LOOP_CONSTRUCT; [COMMANDS...;] continue; [COMMANDS...;] end</tt>
 
 \subsection continue-description Description
-The \c continue builtin is used to skip the current lap of the innermost currently running loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement.
+\c continue skips the remainder of the current iteration of the current inner loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> 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.
 
 <pre>
 for i in *.tmp
diff --git a/doc_src/count.txt b/doc_src/count.txt
index 1484588a..7923ca00 100644
--- a/doc_src/count.txt
+++ b/doc_src/count.txt
@@ -5,20 +5,13 @@
 
 \subsection count-description Description
 
-The <tt>count</tt> builtin prints the number of arguments that were
+<tt>count</tt> 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.
-
-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.
-
-Count exits with a non-zero exit status if no arguments were passed
+environment variable array contains.
+
+\c count does not accept any options, including '-h'.
+
+\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 efd4ac79..abc498b8 100644
--- a/doc_src/dirh.txt
+++ b/doc_src/dirh.txt
@@ -4,5 +4,9 @@
 <tt>dirh</tt>
 
 \subsection dirh-description Description
+
 <tt>dirh</tt> prints the current directory history. The current position in the
-history is highlighted using <tt>$fish_color_history_current</tt>.
+history is highlighted using the color defined in the
+<tt>fish_color_history_current</tt> environment variable.
+
+\c dirh does not accept any parameters.
diff --git a/doc_src/dirs.txt b/doc_src/dirs.txt
index b5b9c0ae..e5238107 100644
--- a/doc_src/dirs.txt
+++ b/doc_src/dirs.txt
@@ -4,4 +4,7 @@
 <tt>dirs</tt>
 
 \subsection dirs-description Description
-<tt>dirs</tt> prints the current directory stack.
+<tt>dirs</tt> prints the current directory stack, as created by the
+<code><a href="#pushd">pushd</a></code> command.
+
+\c dirs does not accept any parameters.
diff --git a/doc_src/echo.txt b/doc_src/echo.txt
index cfa9849e..01ddf5a5 100644
--- a/doc_src/echo.txt
+++ b/doc_src/echo.txt
@@ -3,19 +3,21 @@
 \subsection echo-synopsis Synopsis
  <tt>echo [STRING]</tt>
 
-\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 e0f8b85b..66d8be3f 100644
--- a/doc_src/else.txt
+++ b/doc_src/else.txt
@@ -4,14 +4,18 @@
 <tt>if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end</tt>
 
 \subsection else-description Description
-<tt>if</tt> 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
-<tt>else</tt> is given, COMMANDS_FALSE will be executed.  Hint: use
-<a href="#begin"><tt>begin; ...; end</tt></a> for complex conditions.
+<tt>if</tt> 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
+<tt>else</tt> is given, \c COMMANDS_FALSE will be executed.
 
 \subsection else-example Example
 
-The command <tt>if test -f foo.txt; echo foo.txt exists; else; echo foo.txt does not exist; end</tt>
-will print <tt>foo.txt exists</tt> if the file foo.txt
-exists and is a regular file, otherwise it will print
-<tt>foo.txt does not exist</tt>.
+The following code tests whether a file \c foo.txt exists as a regular file.
+
+<pre>
+if test -f foo.txt
+    echo foo.txt exists
+else
+    echo foo.txt does not exist
+end
+</pre>
diff --git a/doc_src/emit.txt b/doc_src/emit.txt
index c0faab82..f00e4233 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 5849e339..2d301e33 100644
--- a/doc_src/end.txt
+++ b/doc_src/end.txt
@@ -10,7 +10,9 @@ switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
 </pre>
 
 \subsection end-description Description
-<tt>end</tt> ends a block of commands. For more information, read the
+<tt>end</tt> 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 68fc6fc9..0227255a 100644
--- a/doc_src/eval.txt
+++ b/doc_src/eval.txt
@@ -4,13 +4,16 @@
 <tt>eval [COMMANDS...]</tt>
 
 \subsection eval-description Description
-The <tt>eval</tt> 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.
+<tt>eval</tt> 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.
+
 <pre>
 set cmd ls
 eval $cmd
 </pre>
 
-will call the ls command.
diff --git a/doc_src/exec.txt b/doc_src/exec.txt
index e0e661fb..27f6d887 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
 
-<tt>exec emacs</tt> starts up the emacs text editor. When emacs exits,
-the session will terminate.
+<tt>exec emacs</tt> 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 aa96fe95..cdcf54d4 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
 <tt>exit [STATUS]</tt>
 
 \subsection exit-description Description
 
-The <tt>exit</tt> builtin causes fish to exit. If <tt>STATUS</tt> is
+\c exit causes fish to exit. If <tt>STATUS</tt> 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 <a
 href="#source">.</a> builtin) the rest of the file will be skipped,
diff --git a/doc_src/fg.txt b/doc_src/fg.txt
index db983ee9..53b5154f 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
 <tt>fg [PID]</tt>
 
 \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 <a href="index.html#syntax-job-control">job</a> 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 <a href="index.html#expand-process">process expansion</a>.
 
 \subsection fg-example Example
 
-<tt>fg \%0</tt> will put the job with job id 0 in the foreground.
+<tt>fg \%1</tt> will put the job with job ID 1 in the foreground.
diff --git a/doc_src/fish.txt b/doc_src/fish.txt
index faa69a14..ed28cffd 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 <a href='index.html'>in HTML</a> by using the
 <a href='#help'>help</a> command from inside fish.
 
+The following options are available:
+
 - <code>-c</code> or <code>--command=COMMANDS</code> evaluate the specified commands instead of reading from the commandline
 - <code>-d</code> or <code>--debug-level=DEBUG_LEVEL</code> specify the verbosity level of fish. A higher number means higher verbosity. The default level is 1.
 - <code>-h</code> or <code>--help</code> display help and exit
diff --git a/doc_src/fish_config.txt b/doc_src/fish_config.txt
index 78191477..a9627bb2 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 <code>fish_config</code>.
+
+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 68d0647c..c5daeace 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:
 
 - <tt>-h</tt> or <tt>--help</tt> displays this help message and then exits
 - <tt>-i</tt> or <tt>--no-indent</tt> do not indent commands
diff --git a/doc_src/fish_pager.txt b/doc_src/fish_pager.txt
index 304f6214..9efa26b1 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 d400619c..5cf5abf9 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 <a href="index.html#variables-status">$status</a> seen outside of fish_prompt.
+The exit status of commands within \c fish_prompt will not modify the value of <a href="index.html#variables-status">$status</a> 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 1369f9d1..cff5ce0b 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 <code>fish_update_completions</code>.
diff --git a/doc_src/fishd.txt b/doc_src/fishd.txt
index 074e8f5d..0eb3088a 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:
 
 - <tt>-h</tt> or <tt>--help</tt> displays this help message and then exits
 - <tt>-v</tt> or <tt>--version</tt> 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.
+
+  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
+- \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 2ffffe40..67a46fc3 100644
--- a/doc_src/for.txt
+++ b/doc_src/for.txt
@@ -5,8 +5,8 @@
 
 \subsection for-description Description
 <tt>for</tt> 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 19a12f3b..8b070b97 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
+<code>NAME</code>.
 
-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
 
 - <code>-e command</code> or <code>--editor command</code> 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 944e699c..c81961bf 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
- <tt>funcsave FUNCTION_NAME</tt>
+<tt>funcsave FUNCTION_NAME</tt>
 
 \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 10d9eec0..c072c551 100644
--- a/doc_src/function.txt
+++ b/doc_src/function.txt
@@ -5,32 +5,28 @@
 
 \subsection function-description Description
 
-- <code>-d DESCRIPTION</code> or \c --description=DESCRIPTION is a description of what the function does, suitable as a completion description
-- <code>-e</code> or <code>--on-event EVENT_NAME</code> tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt.
-- <code>-j PID</code> or <code> --on-job-exit PID</code> 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.
-- <code>-p PID</code> or <code> --on-process-exit PID</code> tells fish to run this function when the fish child process with process id PID exits
-- <code>-s</code> or <code>--on-signal SIGSPEC</code> 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)
-- <code>-v</code> or <code>--on-variable VARIABLE_NAME</code> tells fish to run this function when the variable VARIABLE_NAME changes value
+\c function creates a new function \c NAME with the body <code>BODY</code>.
 
-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
+A function is a list of commands that will be executed when the name of the
+function is given as a command.
 
-<pre>
-function hi
-	echo hello
-end
-</pre>
+The following options are available:
 
-will write <code>hello</code> whenever the user enters \c hi.
+- <code>-d DESCRIPTION</code> or \c --description=DESCRIPTION is a description of what the function does, suitable as a completion description.
+- <code>-e</code> or <code>--on-event EVENT_NAME</code> tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt.
+- <code>-j PID</code> or <code> --on-job-exit PID</code> 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.
+- <code>-p PID</code> or <code> --on-process-exit PID</code> tells fish to run this function when the fish child process with process ID PID exits.
+- <code>-s</code> or <code>--on-signal SIGSPEC</code> 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).
+- <code>-v</code> or <code>--on-variable VARIABLE_NAME</code> 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 <a href="index.html#variables-arrays">variable array</a> argv.
+are inserted into the environment <a href="index.html#variables-arrays">variable array</a>
+<code>$argv</code>.
 
 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 <a href="#emit">emit</a> 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 928cd545..c1f0115e 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
-<code>functions [-e] FUNCTIONS...</code>
+<pre>functions [-n]
+functions -c OLDNAME NEWNAME
+functions -d DESCRIPTION FUNCTION
+functions [-eq] FUNCTIONS...</pre>
 
 \subsection functions-description Description
 
-This builtin command is used to print or erase functions.
+\c functions prints or erases functions.
 
-- <code>-a</code> or <code>--all</code> list all functions, even those whose name start with an underscore.
+The following options are available:
+
+- <code>-a</code> or <code>--all</code> lists all functions, even those whose name start with an underscore.
 - <code>-c OLDNAME NEWNAME</code> or <code>--copy OLDNAME NEWNAME</code> creates a new function named NEWNAME, using the definition of the OLDNAME function.
-- <code>-d DESCRIPTION</code> or <code>--description=DESCRIPTION</code> change the description of this function
+- <code>-d DESCRIPTION</code> or <code>--description=DESCRIPTION</code> changes the description of this function.
 - <code>-e</code> or <code>--erase</code> causes the specified functions to be erased.
-- <code>-h</code> or <code>--help</code> display a help message and exit
-- <code>-n</code> or <code>--names</code> list only the names of all defined functions, not their definition
-- <code>-q</code> or <code>--query</code> 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.
+- <code>-h</code> or <code>--help</code> displays a help message and exits.
+- <code>-n</code> or <code>--names</code> lists the names of all defined functions.
+- <code>-q</code> or <code>--query</code> tests if the specified functions exist.
+
+The default behavior of <code>functions</code>, 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.
 
-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
+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 <code>functions
+-e</code>. 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.
+
+Only one function's description can be changed in a single invocation
+of <code>functions -d</code>.
+
+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
+
+<code>functions -n</code> displays a list of currently-defined functions.
+
+<code>functions -c foo bar</code> copies the \c foo function to a new function called
+<code>bar</code>.
 
-The exit status of the functions builtin is the number functions
-specified in the argument list that do not exist.
+<code>functions -e bar</code> erases the function <code>bar</code>.
diff --git a/doc_src/help.txt b/doc_src/help.txt
index 3dc90e9a..c4c05382 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 <tt>--help</tt> option.
 
 \subsection help-example Example
diff --git a/doc_src/history.txt b/doc_src/history.txt
index 8f7b6916..33ee4d66 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
 <pre>
@@ -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.
 
-\subsection history-examples Example
+The following options are available:
 
-<pre>
-history --save
-Save all changes in history file
+- \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.
 
-history --clear
-Delete all history items
+If \c --search is specified without \c --contains or <code>--prefix</code>,
+\c --contains will be assumed.
 
-history --search --contains "foo"
-Searches commands containing "foo" string
+If \c --delete is specified without \c --contains or <code>--prefix</code>,
+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.
 
-history --search --prefix "foo"
-Searches for commands with prefix "foo"
+\subsection history-examples Example
 
-history --delete --contains "foo"
-Interactively delete commands containing string "foo"
+<code>history --clear</code> deletes all history items
 
-history --delete --prefix "foo"
-Interactively delete commands with prefix "foo"
+<code>history --search --contains "foo"</code> outputs a list of all previous
+commands containing the string "foo".
 
-history --delete "foo"
-Delete command "foo" from history
-</pre>
+<code>history --delete --prefix "foo"</code> interactively deletes the record
+of previous commands which start with "foo".
diff --git a/doc_src/if.txt b/doc_src/if.txt
index dae82ca6..94d2763a 100644
--- a/doc_src/if.txt
+++ b/doc_src/if.txt
@@ -5,15 +5,15 @@
 
 \subsection if-description Description
 
-<tt>if</tt> 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 <tt>else</tt> is given, COMMANDS_FALSE will
+<tt>if</tt> 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 <tt>else</tt> 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 <a href="#begin"><tt>begin; ...; end</tt></a> and
-the short circuit commands <a href="commands.html#and">and</a> and <a
-href="commands.html#or">or</a>.
+the short circuit commands <a href="commands.html#and"><tt>and</tt></a>
+and <a href="commands.html#or"><tt>or</tt></a>.
 
 The exit status of the last foreground command to exit can always be
 accessed using the <a href="index.html#variables-status">$status</a>
diff --git a/doc_src/isatty.txt b/doc_src/isatty.txt
index bccf8ab8..d3b52892 100644
--- a/doc_src/isatty.txt
+++ b/doc_src/isatty.txt
@@ -4,12 +4,11 @@
  <tt>isatty [FILE DESCRIPTOR]</tt>
 
 \subsection isatty-description Description
-The <tt>isatty</tt> command is used to test if a file descriptor is a tty.
+<tt>isatty</tt> 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.
+<tt>FILE DESCRIPTOR</tt> may be either the number of a file descriptor, or one of the
+strings <tt>stdin</tt>, \c stdout and <tt>stderr</tt>.
 
 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 d4ea33dd..8b96d127 100644
--- a/doc_src/jobs.txt
+++ b/doc_src/jobs.txt
@@ -4,18 +4,22 @@
 <code>jobs [OPTIONS] [PID]</code>
 
 \subsection jobs-description Description
-The <code>jobs</code> builtin causes fish to print a list of the currently
-running jobs and their status.
+<code>jobs</code> prints a list of the currently
+running <a href="index.html#syntax-job-control">jobs</a> and their status.
 
 jobs accepts the following switches:
 
-- <code>-c</code> or <code>--command</code> print the command name for each process in jobs
-- <code>-g</code> or <code>--group</code> only print the group id of each job
-- <code>-h</code> or <code>--help</code> display a help message and exit
-- <code>-l</code> or <code>--last</code> only the last job to be started is printed
-- <code>-p</code> or <code>--pid</code> print the process id for each process in all jobs
+- <code>-c</code> or <code>--command</code> prints the command name for each process in jobs.
+- <code>-g</code> or <code>--group</code> only prints the group ID of each job.
+- <code>-h</code> or <code>--help</code> displays a help message and exits.
+- <code>-l</code> or <code>--last</code> prints only the last job to be started.
+- <code>-p</code> or <code>--pid</code> 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
+
+<code>jobs</code> outputs a summary of the current jobs.
diff --git a/doc_src/math.txt b/doc_src/math.txt
index 9455e0da..9904a2cc 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 <code>math 1+1</code>.
+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
+
+<code>math 1+1</code> outputs 2.
+
+<code>math $status-128</code> outputs the numerical exit status of the
+last command minus 128.
diff --git a/doc_src/mimedb.txt b/doc_src/mimedb.txt
index 6a4e9944..e38597eb 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 <code>FILES</code>. 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 5adbc915..dba94ce0 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
-<tt>nextd [-l | --list] [pos]</tt>
+<tt>nextd [-l | --list] [POS]</tt>
 
 \subsection nextd-description Description
-<tt>nextd</tt> moves forwards <tt>pos</tt> positions in the history of visited
-directories; if the end of the history has been hit, a warning is printed. If
-the <code>-l></code> or <code>--list</code> flag is specified, the current
-history is also displayed.
+<tt>nextd</tt> moves forwards <tt>POS</tt> positions in the history of visited
+directories; if the end of the history has been hit, a warning is printed.
+
+If the <code>-l></code> or <code>--list</code> flag is specified, the current
+directory history is also displayed.
+
+\subsection nextd-example Example
+
+<pre>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</pre>
diff --git a/doc_src/not.txt b/doc_src/not.txt
index bb053da7..a1a1d206 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.
+
 <pre>
 if not test -f spoon
 	echo There is no spoon
diff --git a/doc_src/open.txt b/doc_src/open.txt
index 0a4b8958..4dc03f9b 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 <a href="commands.html#mimedb">mimedb</a> command.
+\c open opens a file in its default application, using the \c xdg-open command if it exists, or else the <a href="commands.html#mimedb">mimedb</a> command.
 
 \subsection open-example Example
 
diff --git a/doc_src/or.txt b/doc_src/or.txt
index a33cb50d..3567917f 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 <a href="index.html#variables-status">$status</a>
@@ -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,
 <tt>make clean</tt> is run, which removes the files created by the
-build process
+build process.
 
 <pre>
 make; and make install; or make clean
diff --git a/doc_src/popd.txt b/doc_src/popd.txt
index b3c87584..deb3719f 100644
--- a/doc_src/popd.txt
+++ b/doc_src/popd.txt
@@ -4,5 +4,21 @@
 <tt>popd</tt>
 
 \subsection popd-description Description
+
 <tt>popd</tt> 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 <a
+href="#pushd"><tt>pushd</tt></a> to add directories to the stack.
+
+\subsection popd-example Example
+
+<pre>
+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
+</pre>
diff --git a/doc_src/prevd.txt b/doc_src/prevd.txt
index 83d6b909..b72fc375 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
-<tt>prevd [-l | --list] [pos]</tt>
+<tt>prevd [-l | --list] [POS]</tt>
 
 \subsection prevd-description Description
 
-<tt>prevd</tt> moves backwards <tt>pos</tt> positions in the history
+<tt>prevd</tt> moves backwards <tt>POS</tt> positions in the history
 of visited directories; if the beginning of the history has been hit,
-a warning is printed. If the <code>-l</code> or <code>--list</code>
-flag is specified, the current history is also displayed.
+a warning is printed.
+
+If the <code>-l</code> or <code>--list</code> flag is specified, the current
+history is also displayed.
+
+\subsection prevd-example Example
+
+<pre>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</pre>
diff --git a/doc_src/psub.txt b/doc_src/psub.txt
index c12278d3..7f4dbedd 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 <tt>psub</tt>, \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 3093cbaa..dbcd7f91 100644
--- a/doc_src/pushd.txt
+++ b/doc_src/pushd.txt
@@ -4,6 +4,20 @@
 <tt>pushd [DIRECTORY]</tt>
 
 \subsection pushd-description Description
-The <tt>pushd</tt> function adds DIRECTORY to the top of the directory stack
-and makes it the current directory. Use <tt>popd</tt> to pop it off and
+The <tt>pushd</tt> function adds \c DIRECTORY to the top of the directory stack
+and makes it the current working directory. <a href="#popd"><tt>popd</tt></a> will pop it off and
 return to the original directory.
+
+\subsection pushd-example Example
+
+<pre>
+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
+</pre>
diff --git a/doc_src/pwd.txt b/doc_src/pwd.txt
index 92bb5e55..138e8dcb 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
  <tt>pwd</tt>
 
 \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 ad9b658a..b6bb9df0 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 d69d715b..1e8aef37 100644
--- a/doc_src/read.txt
+++ b/doc_src/read.txt
@@ -5,27 +5,29 @@
 
 \subsection read-description Description
 
-The <tt>read</tt> builtin causes fish to read one line from standard
-input and store the result in one or more environment variables.
+<tt>read</tt> reads one line from standard
+input and stores the result in one or more environment variables.
 
-- <tt>-c CMD</tt> or <tt>--command=CMD</tt> specifies that the initial string in the interactive mode command buffer should be CMD.
-- <tt>-g</tt> or <tt>--global</tt> specifies that the variables will be made global.
-- <tt>-l</tt> or <tt>--local</tt> specifies that the variables will be made local.
+The following options are available:
+
+- <tt>-c CMD</tt> or <tt>--command=CMD</tt> sets the initial string in the interactive mode command buffer to <tt>CMD</tt>.
+- <tt>-g</tt> or <tt>--global</tt> makes the variables global (default behaviour).
+- <tt>-l</tt> or <tt>--local</tt> makes the variables local.
 - <tt>-m NAME</tt> or <tt>--mode-name=NAME</tt> 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.
-- <tt>-p PROMPT_CMD</tt> or <tt>--prompt=PROMPT_CMD</tt> 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 <tt>set_color green; echo read; set_color normal; echo "> "</tt>.
-- <code>-s</code> or <code>--shell</code> Use syntax highlighting, tab completions and command termination suitable for entering shellscript code
-- <code>-u</code> or <code>--unexport</code> causes the specified environment not to be exported to child processes
-- <code>-U</code> or <code>--universal</code> 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.
-- <code>-x</code> or <code>--export</code> causes the specified environment variable to be exported to child processes
-
-Read starts by reading a single line of input from stdin, the line is
-then tokenized using the <tt>IFS</tt> environment variable. Each variable
-specified in <tt>VARIABLES</tt> is then assigned one tokenized string
-element. If there are more tokens than variables, the complete
-remainder is assigned to the last variable.
+- <tt>-p PROMPT_CMD</tt> or <tt>--prompt=PROMPT_CMD</tt> uses the output of the shell command \c PROMPT_CMD as the prompt for the interactive mode. The default prompt command is <tt>set_color green; echo read; set_color normal; echo "> "</tt>.
+- <code>-s</code> or <code>--shell</code> enables syntax highlighting, tab completions and command termination suitable for entering shellscript code in the interactive mode.
+- <code>-u</code> or <code>--unexport</code> prevents the variables from being exported to child processes (default behaviour).
+- <code>-U</code> or <code>--universal</code> causes the specified environment variable to be made universal.
+- <code>-x</code> or <code>--export</code> exports the variables to child processes.
+
+\c read reads a single line of input from stdin, breaks it into tokens
+based on the <tt>IFS</tt> environment variable, and then assigns one
+token to each variable specified in <tt>VARIABLES</tt>. If there are more
+tokens than variables, the complete remainder is assigned to the last variable.
 
 \subsection read-example Example
 
-<tt>echo hello|read foo</tt>
+The following code stores the value 'hello' in the environment variable
+<tt>$foo</tt>.
 
-Will cause the variable \$foo to be assigned the value hello.
+<tt>echo hello|read foo</tt>
diff --git a/doc_src/return.txt b/doc_src/return.txt
index 2cfd5ab6..9563cf39 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
 <tt>function NAME; [COMMANDS...;] return [STATUS]; [COMMANDS...;] end</tt>
 
 \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 <a
+\c return halts a currently running function. The exit status is set
+to \c STATUS if it is given.
+
+It is usually added inside of a conditional block such as an <a
 href="#if">if</a> statement or a <a href="#switch">switch</a>
 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 e46cd9c4..e9e67392 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
 <pre>
@@ -10,23 +10,31 @@ set (-e | --erase) [SCOPE_OPTIONS] VARIABLE_NAME
 set (-e | --erase) [SCOPE_OPTIONS] VARIABLE_NAME[INDICES]...
 </pre>
 
-The <code>set</code> builtin causes fish to assign the variable <code>VARIABLE_NAME</code> the values <code>VALUES...</code>.
-
 \subsection set-description Description
-- <code>-e</code> or <code>--erase</code> causes the specified environment variable to be erased
+
+<code>set</code> manipulates <a href="index.html#variables">environment
+variables</a>.
+
+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
+<code>VARIABLE_NAME</code> the values <code>VALUES...</code>.
+
+The following options control variable scope:
 - <code>-l</code> or <code>--local</code> 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
 - <code>-g</code> or <code>--global</code> causes the specified environment variable to be given a global scope. Non-global variables disappear when the block they belong to ends
 - <code>-U</code> or <code>--universal</code> 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.
 - <code>-n</code> or <code>--names</code> List only the names of all defined variables, not their value
-- <code>-q</code> or <code>--query</code> 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.
 - <code>-u</code> or <code>--unexport</code> causes the specified environment not to be exported to child processes
 - <code>-x</code> or <code>--export</code> causes the specified environment variable to be exported to child processes
-- <code>-L</code> or <code>--long</code> do not abbreviate long values when printing set 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.
+The following options are available:
+- <code>-e</code> or <code>--erase</code> causes the specified environment variable to be erased
+- <code>-q</code> or <code>--query</code> 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.
+- <code>-L</code> or <code>--long</code> 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
@@ -34,7 +42,7 @@ elements, it will become an array with zero elements.
 
 If the variable name is one or more array elements, such as
 <code>PATH[1 3 7]</code>, 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. <code>set PATH[1]
 PATH[4] /bin /sbin</code>. 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, <code>set flags -l</code> will have
+\c set requires all options to come before any
+other arguments. For example, <code>set flags -l</code> will have
 the effect of setting the value of the variable <code>flags</code> 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. <code>if set output
 (command)</code>. 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 79eca8e0..546889cd 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 <tt>set_color normal</tt> 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, <code>set_color white</code> will result
 in a grey font color, while <code>set_color --bold white</code> 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
 <pre>set_color red; echo "Roses are red"
diff --git a/doc_src/source.txt b/doc_src/source.txt
index d92d1cc9..06958375 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. <tt>fish < FILENAME</tt>) 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
 
-<tt>. ~/.config/fish/config.fish</tt>
-
-causes fish to reread its initialization file.
+<tt>. ~/.config/fish/config.fish</tt> causes fish to re-read its initialization file.
 
diff --git a/doc_src/status.txt b/doc_src/status.txt
index a14ee919..d6238ae3 100644
--- a/doc_src/status.txt
+++ b/doc_src/status.txt
@@ -6,16 +6,16 @@
 \subsection status-description Description
 With no arguments, <tt>status</tt> displays a summary of the current login and job control status of the shell.
 
-The following arguments are available:
-- <tt>-c</tt> or <tt>--is-command-substitution</tt> returns 0 if fish is currently executing a command substitution
-- <tt>-b</tt> or <tt>--is-block</tt> returns 0 if fish is currently executing a block of code
-- <tt>-i</tt> or <tt>--is-interactive</tt> returns 0 if fish is interactive, i.e.connected to a keyboard
-- <tt>-l</tt> or <tt>--is-login</tt> returns 0 if fish is a login shell, i.e. if fish should perform login tasks such as setting up the PATH.
-- <tt>--is-full-job-control</tt> returns 0 if full job control is enabled
-- <tt>--is-interactive-job-control</tt> returns 0 if interactive job control is enabled
-- <tt>--is-no-job-control</tt> returns 0 if no job control is enabled
-- <tt>-f</tt> or <tt>--current-filename</tt> prints the filename of the currently running script
-- <tt>-n</tt> or <tt>--current-line-number</tt> prints the line number of the currently running script
-- <tt>-j CONTROLTYPE</tt> or <tt>--job-control=CONTROLTYPE</tt> set the job control type.  Can be one of: none, full, interactive
-- <tt>-t</tt> or <tt>--print-stack-trace</tt> prints a stack trace of all function calls on the call stack
-- <tt>-h</tt> or <tt>--help</tt> display a help message and exit
+The following options are available:
+- <tt>-c</tt> or <tt>--is-command-substitution</tt> returns 0 if fish is currently executing a command substitution.
+- <tt>-b</tt> or <tt>--is-block</tt> returns 0 if fish is currently executing a block of code.
+- <tt>-i</tt> or <tt>--is-interactive</tt> returns 0 if fish is interactive - that is, connected to a keyboard.
+- <tt>-l</tt> or <tt>--is-login</tt> returns 0 if fish is a login shell - that is, if fish should perform login tasks such as setting up the PATH.
+- <tt>--is-full-job-control</tt> returns 0 if full job control is enabled.
+- <tt>--is-interactive-job-control</tt> returns 0 if interactive job control is enabled.
+- <tt>--is-no-job-control</tt> returns 0 if no job control is enabled.
+- <tt>-f</tt> or <tt>--current-filename</tt> prints the filename of the currently running script.
+- <tt>-n</tt> or <tt>--current-line-number</tt> prints the line number of the currently running script.
+- <tt>-j CONTROLTYPE</tt> or <tt>--job-control=CONTROLTYPE</tt> sets the job control type, which can be <tt>none</tt>, <tt>full</tt>, or <tt>interactive</tt>.
+- <tt>-t</tt> or <tt>--print-stack-trace</tt> prints a stack trace of all function calls on the call stack.
+- <tt>-h</tt> or <tt>--help</tt> displays a help message and exit.
diff --git a/doc_src/switch.txt b/doc_src/switch.txt
index cbfb4be9..7b9b0308 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 b4879057..600e7ea7 100644
--- a/doc_src/test.txt
+++ b/doc_src/test.txt
@@ -3,41 +3,40 @@
 \subsection test-synopsis Synopsis
  <tt>test [EXPRESSION]</tt>
 
-\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.
+- <tt>-L FILE</tt> returns true if \c FILE is a symbolic link.
+- <tt>-S FILE</tt> returns true if \c FILE is a socket.
+- <tt>COND1 -a COND2</tt> combines two conditions with a logical and.
+- <tt>-b FILE</tt> returns true if \c FILE is a block device.
+- <tt>-c FILE</tt> returns true if \c FILE is a character device.
+- <tt>-d FILE</tt> returns true if \c FILE is a directory.
+- <tt>-e FILE</tt> returns true if \c FILE exists.
+- <tt>-f FILE</tt> returns true if \c FILE is a regular file.
+- <tt>-f FILE</tt> returns true if \c FILE has set-group-ID bit set.
+- <tt>-n STRING</tt> returns true if the length of \c STRING is non-zero.
+- <tt>COND1 -o COND2</tt> combines two conditions with a logical or.
+- <tt>-p FILE</tt> returns true if \c FILE is a named pipe.
+- <tt>-r FILE</tt> returns true if \c FILE is readable.
+- <tt>-s FILE</tt> returns true if the size of \c FILE is non-zero.
+- <tt>-t FD</tt> returns true if \c FD is a terminal (TTY).
+- <tt>-u FILE</tt> returns true if \c FILE has set-user-ID bit set.
+- <tt>-w FILE</tt> returns true if \c FILE is writable.
+- <tt>-x FILE</tt> returns true if \c FILE is executable.
+- <tt>-z STRING</tt> returns true if \c STRING length is zero.
 
 \subsection test-example Example
 
 <pre>
-    if test -d "/"
-	echo "Fish is cool"
-    end
+if test -d "/"
+    echo "Fish is cool"
+end
 </pre> 
 
-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 bd44d458..aaaa5b2b 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 <a
+\c trap is a wrapper around the fish event delivery
+framework. It exists for backwards compatibility with POSIX
+shells. For other uses, it is recommended to define an <a
 href='index.html#event'>event handler</a>.
 
-- 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
+
+<code>trap "status --print-stack-trace" SIGUSR1</code> 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 dde72364..9b5699f3 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
- <tt>type [OPTIONS] name [name ...]</tt>
+ <tt>type [OPTIONS] NAME [NAME ...]</tt>
 
 \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 <tt>keyword</tt>, <tt>function</tt>, <tt>builtin</tt>, or <tt>file</tt> 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 <tt>$PATH</tt>.
+
+\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 6e21eba3..7b4e3c45 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
 <tt>ulimit [OPTIONS] [LIMIT]</tt>
 
 \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:
 
-- <code>-c</code> or <code>--core-size</code> The maximum size of core files created. By setting this limit to zero, core dumps can be disabled.
-- <code>-d</code> or <code>--data-size</code> The maximum size of a process's data segment
-- <code>-f</code> or <code>--file-size</code> The maximum size of files created by the shell
-- <code>-l</code> or <code>--lock-size</code> The maximum size that may be locked into memory
-- <code>-m</code> or <code>--resident-set-size</code> The maximum resident set size
-- <code>-n</code> or <code>--file-descriptor-count</code> The maximum number of open file descriptors (most systems do not allow this value to be set)
-- <code>-s</code> or <code>--stack-size</code> The maximum stack size
-- <code>-t</code> or <code>--cpu-time</code> The maximum amount of cpu time in seconds
-- <code>-u</code> or <code>--process-count</code> The maximum number of processes available to a single user
-- <code>-v</code> or <code>--virtual-memory-size</code> The maximum amount of virtual memory available to the shell. If supported by OS.
+- <code>-c</code> or <code>--core-size</code>: the maximum size of core files created. By setting this limit to zero, core dumps can be disabled.
+- <code>-d</code> or <code>--data-size</code>: the maximum size of a process' data segment.
+- <code>-f</code> or <code>--file-size</code>: the maximum size of files created by the shell.
+- <code>-l</code> or <code>--lock-size</code>: the maximum size that may be locked into memory.
+- <code>-m</code> or <code>--resident-set-size</code>: the maximum resident set size.
+- <code>-n</code> or <code>--file-descriptor-count</code>: the maximum number of open file descriptors (most systems do not allow this value to be set).
+- <code>-s</code> or <code>--stack-size</code>: the maximum stack size.
+- <code>-t</code> or <code>--cpu-time</code>: the maximum amount of CPU time in seconds.
+- <code>-u</code> or <code>--process-count</code>: the maximum number of processes available to a single user.
+- <code>-v</code> or <code>--virtual-memory-size</code> 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 <tt>hard</tt>, <tt>soft</tt>, or <tt>unlimited</tt>,
 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:
 
-- <code>-H</code> or <code>--hard</code> Set hard resource limit
-- <code>-S</code> or <code>--soft</code> Set soft resource limit
+- <code>-H</code> or <code>--hard</code> sets hard resource limit
+- <code>-S</code> or <code>--soft</code> 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 <tt>ulimit</tt>:
 
-- <code>-a</code> or <code>--all</code> Print all current limits
-- <code>-h</code> or <code>--help</code> Display help and exit
+- <code>-a</code> or <code>--all</code> prints all current limits
+- <code>-h</code> or <code>--help</code> 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
 
-<tt>ulimit -Hs 64</tt>
-
-would set the hard stack size limit to 64 kB:
+<tt>ulimit -Hs 64</tt> sets the hard stack size limit to 64 kB.
 
diff --git a/doc_src/umask.txt b/doc_src/umask.txt
index 0a75e3db..bc9aac0c 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
 <code>umask [OPTIONS] [MASK]</code>
 
 \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.
+
+- <code>-h</code> or <code>--help</code> prints this message.
+- <code>-S</code> or <code>--symbolic</code> prints the umask in symbolic form instead of octal form.
+- <code>-p</code> or <code>--as-command</code> 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, <code>r,u+w</code> means all
 users should have read access and the file owner should also have
 write access.
 
-- <code>-h</code> or <code>--help</code> print this message
-- <code>-S</code> or <code>--symbolic</code> prints the file-creation mask in symbolic form instead of octal form. Use <code>man chmod</code> for more information.
-- <code>-p</code> or <code>--as-command</code> 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 9f1cef53..609172d7 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 1ec643d2..496c36c2 100644
--- a/doc_src/while.txt
+++ b/doc_src/while.txt
@@ -4,16 +4,18 @@
 <tt>while CONDITION; COMMANDS...; end</tt>
 
 \subsection while-description Description
-The <tt>while</tt> 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
-<a href="#begin"><tt>begin; ...; end</tt></a> for complex conditions; more
+<tt>while</tt> repeatedly executes <tt>CONDITION</tt>, and if the exit status
+is 0, then executes <tt>COMMANDS</tt>.
+
+If the exit status of \c CONDITION is non-zero on the first iteration,
+\c COMMANDS will not be executed at all.
+
+Use <a href="#begin"><tt>begin; ...; end</tt></a> for complex conditions; more
 complex control can be achieved with <tt>while true</tt> containing a
 <a href="#break">break</a>.
 
 \subsection while-example Example
 
 <tt>while test -f foo.txt; echo file exists; sleep 10; end</tt>
-
-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.