[docs] Some rewording to the builtins

Plus some additional examples.

doc_src/and.txt

@@ -7,7 +7,7 @@ COMMAND1; and COMMAND2
 
 \subsection and-description Description
 
-`and` is used to execute a command if the current exit status (as set by the previous command) is 0.
+`and` is used to execute a command if the previous command was successful (returned a status of 0).
 
 `and` statements may be used as part of the condition in an <a href="#if">`if`</a> or <a href="#while">`while`</a> block. See the documentation for <a href="#if">`if`</a> and <a href="#while">`while`</a> for examples.
 

doc_src/begin.txt

@@ -9,9 +9,9 @@ begin; [COMMANDS...;] end
 
 `begin` is used to create a new block of code.
 
-The block is unconditionally executed. `begin; ...; end` is equivalent to `if true; ...; end`.
+A block allows the introduction of a new variable scope, redirection of the input or output of a set of commands as a group, or to specify precedence when using the conditional commands like `and`.
 
-`begin` is used to group a number of commands into a block. This allows the introduction of a new variable scope, redirection of the input or output of a set of commands as a group, or to specify precedence when using the conditional commands like `and`.
+The block is unconditionally executed. `begin; ...; end` is equivalent to `if true; ...; end`.
 
 `begin` does not change the current exit status itself. After the block has completed, `$status` will be set to the status returned by the most recent command.
 
@@ -23,6 +23,7 @@ The following code sets a number of variables inside of a block scope. Since the
 \fish
 begin
     set -l PIRATE Yarrr
+
     ...
 end
 

doc_src/bg.txt

@@ -7,7 +7,9 @@ bg [PID...]
 
 \subsection bg-description Description
 
-`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 process group IDs are put in the background.
+`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 process group IDs are put in the background.
 
 When at least one of the arguments isn't a valid job specifier (i.e. PID),
 `bg` will print an error without backgrounding anything.

doc_src/bind.txt

@@ -26,7 +26,7 @@ If the `-k` switch is used, the name of the key (such as 'down', 'up' or 'backsp
 
 When `COMMAND` is a shellscript command, it is a good practice to put the actual code into a <a href="#function">function</a> and simply bind to the function name. This way it becomes significantly easier to test the function while editing, and the result is usually more readable as well.
 
-If such a script produces output, the script needs to finish by calling `commandline -f repaint` in order to tell fish that a repaint is in order.
+If a script produces output, it should finish by calling `commandline -f repaint` to tell fish that a repaint is in order.
 
 When multiple `COMMAND`s are provided, they are all run in the specified order when the key is pressed. Note that special input functions cannot be combined with ordinary shell script commands. The commands must be entirely a sequence of special input functions (from `bind -f`) or all shell script commands (i.e., valid fish script).
 

doc_src/case.txt

@@ -7,7 +7,7 @@ switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
 
 \subsection case-description Description
 
-`switch` performs one of several blocks of commands, depending on whether a specified value equals one of several wildcarded values. `case` is used together with the `switch` statement in order to determine which block should be executed.
+`switch` executes one of several blocks of commands, depending on whether a specified value matches one of several values. `case` is used together with the `switch` statement in order to determine which block should be executed.
 
 Each `case` command is given one or more parameters. The first `case` command with a parameter that matches the string specified in the switch command will be evaluated. `case` parameters may contain wildcards. These need to be escaped or quoted in order to avoid regular wildcard expansion using filenames.
 
@@ -18,8 +18,7 @@ Note that command substitutions in a case statement will be evaluated even if it
 
 \subsection case-example Example
 
-If the variable \$animal contains the name of an animal, the following
-code would attempt to classify it:
+Say \$animal contains the name of an animal. Then this code would classify it:
 
 \fish
 switch $animal
@@ -40,3 +39,4 @@ end
 If the above code was run with `$animal` set to `whale`, the output
 would be `mammal`.
 
+If `$animal` was set to "banana", it would print "I have no idea what a banana is".

doc_src/command.txt

@@ -17,7 +17,7 @@ The following options are available:
 
 - `-s` or `--search` returns the name of the external command that would be executed, or nothing if no file with the specified name could be found in the `$PATH`.
 
-With the `-s` option, `command` treats every argument as a separate command to look up and sets the exit status to 0 if any of the specified commands were found, or 1 if no commands could be found. Additionally passing a `-q` or `--quiet` option prevents any paths from being printed, like the `type -q`, for testing only the exit status.
+With the `-s` option, `command` treats every argument as a separate command to look up and sets the exit status to 0 if any of the specified commands were found, or 1 if no commands could be found. Additionally passing a `-q` or `--quiet` option prevents any paths from being printed, like `type -q`, for testing only the exit status.
 
 For basic compatibility with POSIX `command`, the `-v` flag is recognized as an alias for `-s`.
 
@@ -26,3 +26,5 @@ For basic compatibility with POSIX `command`, the `-v` flag is recognized as an
 `command ls` causes fish to execute the `ls` program, even if an `ls` function exists.
 
 `command -s ls` returns the path to the `ls` program.
+
+`command -sq git; and command git log` runs `git log` only if `git` exists.

doc_src/contains.txt

@@ -13,10 +13,20 @@ The following options are available:
 
 - `-i` or `--index` print the word index
 
-Note that, like GNU tools, `contains` interprets all arguments starting with a `-` as options to contains, until it reaches an argument that is `--` (two dashes). See the examples below.
+Note that, like GNU tools and most of fish's builtins, `contains` interprets all arguments starting with a `-` as options to contains, until it reaches an argument that is `--` (two dashes). See the examples below.
 
 \subsection contains-example Example
 
+If $animals is a list of animals, the following will test if it contains a cat:
+
+\fish
+if contains cat $animals
+   echo Your animal list is evil!
+end
+\endfish
+
+This code will add some directories to $PATH if they aren't yet included:
+
 \fish
 for i in ~/bin /usr/local/bin
     if not contains $i $PATH
@@ -25,7 +35,7 @@ for i in ~/bin /usr/local/bin
 end
 \endfish
 
-The above code tests if `~/bin` and `/usr/local/bin` are in the path and adds them if not.
+While this will check if `hasargs` was run with the `-q` option:
 
 \fish
 function hasargs
@@ -35,4 +45,4 @@ function hasargs
 end
 \endfish
 
-The above code checks for `-q` in the argument list, using the `--` argument to demarcate options to `contains` from the key to search for.
+The `--` here stops `contains` from treating `-q` to an option to itself. Instead it treats it as a normal string to check.

doc_src/continue.txt

@@ -18,6 +18,9 @@ for i in *.tmp
     if grep smurf $i
         continue
     end
+    # This "rm" is skipped over if "continue" is executed.
     rm $i
+    # As is this "echo"
+    echo $i
 end
 \endfish

doc_src/count.txt

@@ -9,7 +9,7 @@ count $VARIABLE
 
 `count` prints the number of arguments that were passed to it. This is usually used to find out how many elements an environment variable array contains.
 
-`count` does not accept any options, including `-h` or `--help`.
+`count` does not accept any options, not even `-h` or `--help`.
 
 `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.
 

doc_src/eval.txt

@@ -8,6 +8,7 @@ eval [COMMANDS...]
 \subsection eval-description Description
 `eval` evaluates the specified parameters as a command. If more than one parameter is specified, all parameters will be joined using a space character as a separator.
 
+If your command does not need access to stdin, consider using `source` instead.
 
 \subsection eval-example Example
 

doc_src/or.txt

@@ -7,7 +7,7 @@ COMMAND1; or COMMAND2
 
 \subsection or-description Description
 
-`or` is used to execute a command if the current exit status (as set by the previous command) is not 0.
+`or` is used to execute a command if the previous command was not successful (returned a status of something other than 0).
 
 `or` statements may be used as part of the condition in an <a href="#if">`and`</a> or <a href="#while">`while`</a> block. See the documentation
 for <a href="#if">`if`</a> and <a href="#while">`while`</a> for examples.