Documentation updates from Beni Cherniavsky

darcs-hash:20060919145203-ac50b-bc87b8f5e6a18395e4bc3e364da4a40ad97850e7.gz

doc_src/and.txt

@@ -1,4 +1,3 @@
-
 \section and and - Conditionally execute a command
 
 \subsection and-synopsis Synopsis
@@ -7,7 +6,7 @@
 \subsection and-description Description
 
 The \c and builtin is used to execute a command if the current exit
-status (as set by the last previous command) is zero
+status (as set by the last previous command) is 0.
 
 The and command does not change the current exit status.
 

doc_src/begin.txt

@@ -1,8 +1,7 @@
-
 \section begin begin - Start a new block of code
 
 \subsection begin-synopsis Synopsis
- <tt>begin; [COMMAND;...] end </tt>
+ <tt>begin; [COMMANDS...;] end</tt>
 
 \subsection begin-description Description
 

doc_src/bind.txt

@@ -1,14 +1,21 @@
 \section bind bind - Handle key bindings.
 
 \subsection bind-synopsis Synopsis
-<tt>bind [OPTIONS] [BINDINGS...] </tt>
+<tt>bind [OPTIONS] [BINDINGS...]</tt>
 
-The <tt>bind</tt> builtin causes fish to add the readline style bindings specified by <tt>BINDINGS</tt> to the list of key bindings. For more information on specifying keyboard bindings, use <tt>man readline</tt> to access the readline documentation.
+The <tt>bind</tt> builtin causes fish to add the readline style bindings specified by BINDINGS to the list of key bindings, as if they appeared in your <tt>~/.fish_inputrc</tt> file.
+
+For more information on the syntax keyboard bindings, use <tt>man
+readline</tt> to access the readline documentation. The availiable commands
+are listed in the <a href="index.html#editor">Command Line Editor</a> section
+of the fish manual - but you may also use any fish command! To write such
+commands, see the <a href="#commandline">commandline</a> builtin. It's good
+practice to put the code into a <tt><a href="#function">function</a> -b</tt>
+and bind to the function name.
 
 \subsection bind-description Description
 - <tt>-M MODE</tt> or <tt>--set-mode=MODE</tt> sets the current input mode to MODE. 
 
-
 \subsection bind-example Example
 
 <tt>bind -M vi</tt> changes to the vi input mode

doc_src/block.txt

@@ -1,4 +1,3 @@
-
 \section block block - Temporarily block delivery of events
 
 \subsection block-synopsis Synopsis
@@ -12,7 +11,8 @@
 
 \subsection block-example Example
 
-<pre>block -g
+<pre>
+block -g
 \#Do something that should not be interrupted
 block -e
 </pre>

doc_src/break.txt

@@ -1,4 +1,3 @@
-
 \section break break - stop the innermost currently evaluated loop
 
 \subsection break-synopsis Synopsis
@@ -9,13 +8,12 @@ The \c break builtin is used to halt a currently running loop, such as a <a href
 
 \subsection break-example Example
 The following code searches all .c files for smurfs, and halts at the first occurrence.
-<p>
-<tt>for i in *.c;
-<br>&nbsp;&nbsp;&nbsp;&nbsp;if grep smurf $i;
-<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;echo Smurfs are present in $i;
-<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;break;
-<br>&nbsp;&nbsp;&nbsp;&nbsp;end;
-<br>end;
-</tt>
-</p>
 
+<pre>
+for i in *.c
+    if grep smurf $i
+        echo Smurfs are present in $i
+        break
+    end
+end
+</pre>

doc_src/builtin.txt

@@ -1,4 +1,3 @@
-
 \section builtin builtin - run a builtin command
 
 \subsection builtin-synopsis Synopsis

doc_src/case.txt

@@ -1,7 +1,7 @@
 \section case case - conditionally execute a block of commands
 
 \subsection case-synopsis Synopsis
-<tt>switch VALUE; [case [WILDCARD...]; [COMMANDS...];...] end</tt>
+<tt>switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end</tt>
 
 \subsection case-description Description
 
@@ -32,7 +32,6 @@ forms of parameter expansion have been performed for the case command.
 If the variable \$animal contains the name of an animal, the following
 code would attempt to classify it:
 
-<p>
 <pre>
 switch $animal
     case cat
@@ -47,7 +46,7 @@ switch $animal
         echo I have no idea what a $animal is
 end
 </pre>
-</p>
+
-<p>
+If the above code was run with \c \$animal set to \c whale, the output
-If the above code was run with \c \$animal set to \c whale, the output would be \c mammal.
+would be \c mammal.
-</p>
+

doc_src/contains.txt

@@ -1,4 +1,3 @@
-
 \section contains contains - Test if a word is present in a list
 
 \subsection contains-synopsis Synopsis

doc_src/continue.txt

@@ -1,20 +1,19 @@
-
 \section continue continue - skip the rest of the current lap of the innermost currently evaluated loop
 
 \subsection continue-synopsis Synopsis
-<tt>LOOP_CONSTRUCT; [COMMANDS...] continue; [COMMANDS...] end</tt>
+<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.
 
 \subsection continue-example Example
 The following code removes all tmp files without smurfs.
-<p>
+
-<tt>for i in *.tmp;
+<pre>
-<br>&nbsp;&nbsp;&nbsp;&nbsp;if grep smurf $i;
+for i in *.tmp
-<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;continue;
+    if grep smurf $i
-<br>&nbsp;&nbsp;&nbsp;&nbsp;end;
+        continue
-<br>&nbsp;&nbsp;&nbsp;&nbsp;rm $i;
+    end
-<br>end;
+    rm $i
-</tt>
+end
-</p>
+</pre>

doc_src/count.txt

@@ -1,4 +1,3 @@
-
 \section count count - Count the number of elements of an array
 
 \subsection count-synopsis Synopsis

doc_src/else.txt

@@ -1,13 +1,13 @@
-\section else else - execute command if a condition is not met.
+\section else else - execute command if a condition is not met
 
 \subsection else-synopsis Synopsis
-<tt>if CONDITION; COMMAND_TRUE [else; COMMAND_FALSE] end;</tt>
+<tt>if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end</tt>
 
 \subsection else-description Description
-<tt>if</tt> will execute the command CONDITION. If the commands exit
+<tt>if</tt> will execute the command CONDITION.  If the condition's exit
-status is zero, the command COMMAND_TRUE will execute. If it is
+status is 0, the commands COMMANDS_TRUE will execute.  If it is not 0 and
-not zero and COMMAND_FALSE is specified, COMMAND_FALSE will be
+<tt>else</tt> is given, COMMANDS_FALSE will be executed.  Hint: use
-executed.
+<a href="#begin"><tt>begin; ...; end</tt></a> for complex conditions.
 
 \subsection else-example Example
 

doc_src/end.txt

@@ -1,11 +1,12 @@
 \section end end - end a block of commands.
 
 \subsection end-synopsis Synopsis
-<pre>for VARNAME in [VALUES...]; COMMANDS; end
+<pre>
-if CONDITION; COMMAND_TRUE [else; COMMAND_FALSE] end
-while CONDITION; COMMANDS; end
-switch VALUE; [case [WILDCARD...]; [COMMANDS...];...] end
 begin; [COMMANDS...] end
+if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end
+while CONDITION; COMMANDS...; end
+for VARNAME in [VALUES...]; COMMANDS...; end
+switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
 </pre>
 
 \subsection end-description Description

doc_src/exec.txt

@@ -1,4 +1,3 @@
-
 \section exec exec - Execute command in current process
 
 \subsection exec-synopsis Synopsis

doc_src/fish_pager.txt

@@ -1,4 +1,3 @@
-
 \section fish_pager fish_pager - Internal command used by fish
 
 \subsection fish_pager-description Description

doc_src/fishd.txt

@@ -1,4 +1,3 @@
-
 \section fishd fishd - Universal variable daemon
 
 \subsection fishd-synopsis Synopsis

doc_src/for.txt

@@ -1,13 +1,13 @@
-
 \section for for - perform a set of commands multiple times.
 
 \subsection for-synopsis Synopsis
-<tt>for VARNAME in [VALUES...]; [COMMANDS...]; end</tt>
+<tt>for VARNAME in [VALUES...]; COMMANDS...; end</tt>
 
 \subsection for-description Description
-<tt>for</tt> is a loop construct. It will perform the commands specified
+<tt>for</tt> is a loop construct. It will perform the commands specified by
-by <tt>COMMANDS</tt> multiple times. Each time the environment variable
+COMMANDS multiple times. Each time the environment variable specified by
-specified by <tt>VARNAME</tt> is assigned a new value from <tt>VALUES</tt>.
+VARNAME is assigned a new value from VALUES. If VALUES is empty, COMMANDS will
+not be executed at all.
 
 \subsection for-example Example
 
@@ -17,7 +17,9 @@ The command
 
 would output:
 
-<pre>foo
+<pre>
+foo
 bar
-baz</pre>		
+baz
+</pre>		
 

doc_src/function.txt

@@ -29,7 +29,8 @@ are inserted into the environment <a href="index.html#variables-arrays">variable
 
 \subsection function-example Example
 
-<pre>function ll
+<pre>
+function ll
 	ls -l $argv
 end
 </pre>

doc_src/help.txt

@@ -1,4 +1,3 @@
-
 \section help help - Display fish documentation
 
 \subsection help-synopsis Synopsis
@@ -8,8 +7,11 @@
 
 The \c help command is used to display a section of the fish help documentation.
 
-If the BROWSER environment variable is set, it will be used to display
+If the BROWSER environment variable is set, it will be used to display the
-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
+given the <tt>--help</tt> option.
 
 \subsection help-example Example
 

doc_src/if.txt

@@ -1,13 +1,13 @@
 \section if if - Conditionally execute a command
 
 \subsection if-synopsis Synopsis
-<tt>if CONDITION; COMMAND_TRUE [else; COMMAND_FALSE] end;</tt>
+<tt>if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end</tt>
 
 \subsection if-description Description
-<tt>if</tt> will execute the command CONDITION. If the commands exit
+<tt>if</tt> will execute the command CONDITION.  If the condition's exit
-status is zero, the command COMMAND_TRUE will execute. If it is
+status is 0, the commands COMMANDS_TRUE will execute.  If it is not 0 and
-not zero and COMMAND_FALSE is specified, COMMAND_FALSE will be
+<tt>else</tt> is given, COMMANDS_FALSE will be executed.  Hint: use
-executed.
+<a href="#begin"><tt>begin; ...; end</tt></a> for complex conditions.
 
 \subsection if-example Example
 

doc_src/mimedb.txt

@@ -1,4 +1,3 @@
-
 \section mimedb mimedb - Lookup file information via the mime database
 
 \subsection mimedb-synopsis Synopsis

doc_src/nextd.txt

@@ -3,8 +3,8 @@
 \subsection nextd-synopsis Synopsis
 <tt>nextd [-l | --list] [pos]</tt>
 
-\subsection nextd-description Description <tt>nextd</tt> moves
+\subsection nextd-description Description
-forwards <tt>pos</tt> positions in the history of visited directories;
+<tt>nextd</tt> moves forwards <tt>pos</tt> positions in the history of visited
-if the end of the history has been hit, a warning is printed. If the
+directories; if the end of the history has been hit, a warning is printed. If
-<code>-l></code> or <code>--list</code> flag is specified, the current
+the <code>-l></code> or <code>--list</code> flag is specified, the current
 history is also displayed.

doc_src/not.txt

@@ -1,14 +1,12 @@
-
 \section not not - Negate the exit status of a job
 
 \subsection not-synopsis Synopsis
- <tt>not COMMAND [OPTIONS...]</tt>
+<tt>not COMMAND [OPTIONS...]</tt>
 
 \subsection not-description Description
 
 The \c not builtin is used to negate the exit status of another command. 
 
-
 \subsection not-example Example
 
 The following code reports an error and exits if no file named spoon can be found.

doc_src/open.txt

@@ -1,4 +1,3 @@
-
 \section open open - Open file in it's default application
 
 \subsection open-synopsis Synopsis

doc_src/or.txt

@@ -1,4 +1,3 @@
-
 \section or or - Conditionally execute a command
 
 \subsection or-synopsis Synopsis
@@ -6,7 +5,8 @@
 
 \subsection or-description Description
 
-The \c or builtin is used to execute a command if the current exit status (as set by the last previous command) is non-zero
+The \c or builtin 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.
 

doc_src/psub.txt

@@ -1,4 +1,3 @@
-
 \section psub psub - Perform process substitution
 
 \subsection psub-synopsis Synopsis

doc_src/random.txt

@@ -1,4 +1,3 @@
-
 \section random random - Generate random number
 
 \subsection random-synopsis Synopsis

doc_src/return.txt

@@ -1,8 +1,7 @@
-
 \section return return - Stop the innermost currently evaluated function
 
 \subsection return-synopsis Synopsis
- <tt>function NAME; [COMMANDS...] return [STATUS]; [COMMANDS...] end</tt>
+<tt>function NAME; [COMMANDS...;] return [STATUS]; [COMMANDS...;] end</tt>
 
 \subsection return-description Description 
 
@@ -17,9 +16,11 @@ function.
 
 \subsection return-example Example
 The following code is an implementation of the false command as a fish function
-<p>
+
-<pre>function false
+<pre>
-	return 1
+function false
-end</pre>
+	return 1
-</p>
+end
+</pre>
+
 

doc_src/set.txt

@@ -1,12 +1,14 @@
 \section set set - Handle environment variables.
 
 \subsection set-synopsis Synopsis
-<pre>set [SCOPE_OPTIONS]
+<pre>
+set [SCOPE_OPTIONS]
 set [OPTIONS] VARIABLE_NAME VALUES...
 set [OPTIONS] VARIABLE_NAME[INDICES]... VALUES...
 set (-q | --query) [SCOPE_OPTIONS] VARIABLE_NAMES...
 set (-e | --erase) [SCOPE_OPTIONS] VARIABLE_NAME
-set (-e | --erase) [SCOPE_OPTIONS] VARIABLE_NAME[INDICES]... </pre>
+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>.
 

doc_src/set_color.txt

@@ -1,4 +1,3 @@
-
 \section set_color set_color - Set the terminal color
 
 \subsection set_color-synopsis Synopsis

doc_src/status.txt

@@ -1,5 +1,4 @@
-
+\section status status - Query fish runtime information
-\section status status - Display fish runtime information
 
 \subsection status-synopsis Synopsis
  <tt>status [OPTION]</tt>

doc_src/switch.txt

@@ -1,8 +1,7 @@
-
 \section switch switch - conditionally execute a block of commands
 
 \subsection switch-synopsis Synopsis
- <tt>switch VALUE; [case [WILDCARD...]; [COMMANDS...];...] end</tt>
+<tt>switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end</tt>
 
 \subsection switch-description Description
 
@@ -22,12 +21,17 @@ 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 stamantes of traditional shells.
 
+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.
+
 \subsection switch-example Example
 
-If the variable \$animal contains the name of an animal, the
+If the variable \$animal contains the name of an animal, the following
-following code would attempt to classify it:
+code would attempt to classify it:
 
-<p>
 <pre>
 switch $animal
     case cat
@@ -42,10 +46,7 @@ switch $animal
         echo I have no idea what a $animal is
 end
 </pre>
-</p>
-<p>
 
 If the above code was run with \c \$animal set to \c whale, the output
 would be \c mammal.
 
-</p>

doc_src/trap.txt

@@ -1,4 +1,3 @@
-
 \section trap trap - perform an action when the shell receives a signal
 
 \subsection trap-synopsis Synopsis

doc_src/type.txt

@@ -1,4 +1,3 @@
-
 \section type type - Indicate how a name would be interpreted if used as a command name
 
 \subsection type-synopsis Synopsis

doc_src/ulimit.txt

@@ -1,4 +1,3 @@
-
 \section ulimit ulimit - Set or get the shells resource usage limits
 
 \subsection ulimit-synopsis Synopsis

doc_src/umask.txt

@@ -1,4 +1,3 @@
-
 \section umask umask - Set or get the shells resource usage limits
 
 \subsection umask-synopsis Synopsis

doc_src/vared.txt

@@ -1,4 +1,3 @@
-
 \section vared vared - Interactively edit the value of an environment variable 
 
 \subsection vared-synopsis Synopsis

doc_src/while.txt

@@ -1,13 +1,19 @@
 \section while while - perform a command multiple times
 
 \subsection while-synopsis Synopsis
-<tt>while CONDITION; COMMANDS; end</tt>
+<tt>while CONDITION; COMMANDS...; end</tt>
 
 \subsection while-synopsis Synopsis
-The <tt>while</tt> builtin causes fish to continually execute the command COMMANDS while the command CONDITION returns with status 0.
+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
+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 the file foo.txt exists.
+causes fish to print the line 'file exists' at 10 second intervals as long as
+the file foo.txt exists.