From 7a5823fd605af80df483e1d3f3629e60503488de Mon Sep 17 00:00:00 2001 From: axel Date: Wed, 20 Sep 2006 00:52:03 +1000 Subject: [PATCH] Documentation updates from Beni Cherniavsky darcs-hash:20060919145203-ac50b-bc87b8f5e6a18395e4bc3e364da4a40ad97850e7.gz --- doc_src/and.txt | 3 +-- doc_src/begin.txt | 3 +-- doc_src/bind.txt | 13 ++++++++++--- doc_src/block.txt | 4 ++-- doc_src/break.txt | 18 ++++++++---------- doc_src/builtin.txt | 1 - doc_src/case.txt | 11 +++++------ doc_src/contains.txt | 1 - doc_src/continue.txt | 21 ++++++++++----------- doc_src/count.txt | 1 - doc_src/else.txt | 12 ++++++------ doc_src/end.txt | 9 +++++---- doc_src/exec.txt | 1 - doc_src/fish_pager.txt | 1 - doc_src/fishd.txt | 1 - doc_src/for.txt | 16 +++++++++------- doc_src/function.txt | 3 ++- doc_src/help.txt | 8 +++++--- doc_src/if.txt | 10 +++++----- doc_src/mimedb.txt | 1 - doc_src/nextd.txt | 8 ++++---- doc_src/not.txt | 4 +--- doc_src/open.txt | 1 - doc_src/or.txt | 4 ++-- doc_src/psub.txt | 1 - doc_src/random.txt | 1 - doc_src/return.txt | 15 ++++++++------- doc_src/set.txt | 6 ++++-- doc_src/set_color.txt | 1 - doc_src/status.txt | 3 +-- doc_src/switch.txt | 17 +++++++++-------- doc_src/trap.txt | 1 - doc_src/type.txt | 1 - doc_src/ulimit.txt | 1 - doc_src/umask.txt | 1 - doc_src/vared.txt | 1 - doc_src/while.txt | 12 +++++++++--- 37 files changed, 107 insertions(+), 109 deletions(-) diff --git a/doc_src/and.txt b/doc_src/and.txt index bd884b1b6..f36adfb3f 100644 --- a/doc_src/and.txt +++ b/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. diff --git a/doc_src/begin.txt b/doc_src/begin.txt index 62bb38101..ecdac1c89 100644 --- a/doc_src/begin.txt +++ b/doc_src/begin.txt @@ -1,8 +1,7 @@ - \section begin begin - Start a new block of code \subsection begin-synopsis Synopsis - begin; [COMMAND;...] end + begin; [COMMANDS...;] end \subsection begin-description Description diff --git a/doc_src/bind.txt b/doc_src/bind.txt index 54e0cd9fe..b56451826 100644 --- a/doc_src/bind.txt +++ b/doc_src/bind.txt @@ -1,14 +1,21 @@ \section bind bind - Handle key bindings. \subsection bind-synopsis Synopsis -bind [OPTIONS] [BINDINGS...] +bind [OPTIONS] [BINDINGS...] -The bind builtin causes fish to add the readline style bindings specified by BINDINGS to the list of key bindings. For more information on specifying keyboard bindings, use man readline to access the readline documentation. +The bind builtin causes fish to add the readline style bindings specified by BINDINGS to the list of key bindings, as if they appeared in your ~/.fish_inputrc file. + +For more information on the syntax keyboard bindings, use man +readline to access the readline documentation. The availiable commands +are listed in the Command Line Editor section +of the fish manual - but you may also use any fish command! To write such +commands, see the commandline builtin. It's good +practice to put the code into a function -b +and bind to the function name. \subsection bind-description Description - -M MODE or --set-mode=MODE sets the current input mode to MODE. - \subsection bind-example Example bind -M vi changes to the vi input mode diff --git a/doc_src/block.txt b/doc_src/block.txt index 8e38c04b9..a1256bb87 100644 --- a/doc_src/block.txt +++ b/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 -
block -g
+
+block -g
 \#Do something that should not be interrupted
 block -e
 

diff --git a/doc_src/break.txt b/doc_src/break.txt
index ebeb4adce..9e5118728 100644
--- a/doc_src/break.txt
+++ b/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 
-for i in *.c;
-
    if grep smurf $i;
-
        echo Smurfs are present in $i;
-
        break;
-
    end;
-
end;
-
-

 
+
+for i in *.c
+    if grep smurf $i
+        echo Smurfs are present in $i
+        break
+    end
+end
+

diff --git a/doc_src/builtin.txt b/doc_src/builtin.txt
index 528f058e5..70d202ac1 100644
--- a/doc_src/builtin.txt
+++ b/doc_src/builtin.txt
@@ -1,4 +1,3 @@
-
 \section builtin builtin - run a builtin command
 
 \subsection builtin-synopsis Synopsis
diff --git a/doc_src/case.txt b/doc_src/case.txt
index 714d75827..c83547551 100644
--- a/doc_src/case.txt
+++ b/doc_src/case.txt
@@ -1,7 +1,7 @@
 \section case case - conditionally execute a block of commands
 
 \subsection case-synopsis Synopsis
-switch VALUE; [case [WILDCARD...]; [COMMANDS...];...] end
+switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
 
 \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:
 
-

 
 switch $animal
     case cat
@@ -47,7 +46,7 @@ switch $animal
         echo I have no idea what a $animal is
 end
 

-

-

-If the above code was run with \c \$animal set to \c whale, the output would be \c mammal.
-

+
+If the above code was run with \c \$animal set to \c whale, the output
+would be \c mammal.
+
diff --git a/doc_src/contains.txt b/doc_src/contains.txt
index 735562d11..b785c9b90 100644
--- a/doc_src/contains.txt
+++ b/doc_src/contains.txt
@@ -1,4 +1,3 @@
-
 \section contains contains - Test if a word is present in a list
 
 \subsection contains-synopsis Synopsis
diff --git a/doc_src/continue.txt b/doc_src/continue.txt
index 43335240a..470093936 100644
--- a/doc_src/continue.txt
+++ b/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
-LOOP_CONSTRUCT; [COMMANDS...] continue; [COMMANDS...] end
+LOOP_CONSTRUCT; [COMMANDS...;] continue; [COMMANDS...;] end
 
 \subsection continue-description Description
 The \c continue builtin is used to skip the current lap of the innermost currently running loop, such as a for loop or a while loop. It is usually added inside of a conditional block such as an if statement or a switch statement.
 
 \subsection continue-example Example
 The following code removes all tmp files without smurfs.
-

-for i in *.tmp;
-
    if grep smurf $i;
-
        continue;
-
    end;
-
    rm $i;
-
end;
-
-

+
+
+for i in *.tmp
+    if grep smurf $i
+        continue
+    end
+    rm $i
+end
+

diff --git a/doc_src/count.txt b/doc_src/count.txt
index db9c5e37c..dcadea909 100644
--- a/doc_src/count.txt
+++ b/doc_src/count.txt
@@ -1,4 +1,3 @@
-
 \section count count - Count the number of elements of an array
 
 \subsection count-synopsis Synopsis
diff --git a/doc_src/else.txt b/doc_src/else.txt
index 8f684e3f6..035abd624 100644
--- a/doc_src/else.txt
+++ b/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
-if CONDITION; COMMAND_TRUE [else; COMMAND_FALSE] end;
+if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end
 
 \subsection else-description Description
-if will execute the command CONDITION. If the commands exit
-status is zero, the command COMMAND_TRUE will execute. If it is
-not zero and COMMAND_FALSE is specified, COMMAND_FALSE will be
-executed.
+if will execute the command CONDITION.  If the condition's exit
+status is 0, the commands COMMANDS_TRUE will execute.  If it is not 0 and
+else is given, COMMANDS_FALSE will be executed.  Hint: use
+begin; ...; end for complex conditions.
 
 \subsection else-example Example
 
diff --git a/doc_src/end.txt b/doc_src/end.txt
index 4e891fb3f..5849e339c 100644
--- a/doc_src/end.txt
+++ b/doc_src/end.txt
@@ -1,11 +1,12 @@
 \section end end - end a block of commands.
 
 \subsection end-synopsis Synopsis
-
for VARNAME in [VALUES...]; COMMANDS; end
-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
 

 
 \subsection end-description Description
diff --git a/doc_src/exec.txt b/doc_src/exec.txt
index c915b58b0..fca95b7ae 100644
--- a/doc_src/exec.txt
+++ b/doc_src/exec.txt
@@ -1,4 +1,3 @@
-
 \section exec exec - Execute command in current process
 
 \subsection exec-synopsis Synopsis
diff --git a/doc_src/fish_pager.txt b/doc_src/fish_pager.txt
index 35830239b..b1e7b8371 100644
--- a/doc_src/fish_pager.txt
+++ b/doc_src/fish_pager.txt
@@ -1,4 +1,3 @@
-
 \section fish_pager fish_pager - Internal command used by fish
 
 \subsection fish_pager-description Description
diff --git a/doc_src/fishd.txt b/doc_src/fishd.txt
index 5414d9278..cc59b1b85 100644
--- a/doc_src/fishd.txt
+++ b/doc_src/fishd.txt
@@ -1,4 +1,3 @@
-
 \section fishd fishd - Universal variable daemon
 
 \subsection fishd-synopsis Synopsis
diff --git a/doc_src/for.txt b/doc_src/for.txt
index 83fee0dc5..b4b3dfaf1 100644
--- a/doc_src/for.txt
+++ b/doc_src/for.txt
@@ -1,13 +1,13 @@
-
 \section for for - perform a set of commands multiple times.
 
 \subsection for-synopsis Synopsis
-for VARNAME in [VALUES...]; [COMMANDS...]; end
+for VARNAME in [VALUES...]; COMMANDS...; end
 
 \subsection for-description Description
-for is a loop construct. It will perform the commands specified
-by COMMANDS multiple times. Each time the environment variable
-specified by VARNAME is assigned a new value from VALUES.
+for is a loop construct. It will perform the commands specified by
+COMMANDS multiple times. Each time the environment variable specified by
+VARNAME is assigned a new value from VALUES. If VALUES is empty, COMMANDS will
+not be executed at all.
 
 \subsection for-example Example
 
@@ -17,7 +17,9 @@ The command
 
 would output:
 
-
foo
+
+foo
 bar
-baz
		
+baz
+
		
 
diff --git a/doc_src/function.txt b/doc_src/function.txt
index 51225f55e..37ed23fc1 100644
--- a/doc_src/function.txt
+++ b/doc_src/function.txt
@@ -29,7 +29,8 @@ are inserted into the environment variable
 
 \subsection function-example Example
 
-
function ll
+
+function ll
 	ls -l $argv
 end
 

diff --git a/doc_src/help.txt b/doc_src/help.txt
index 93c9a8475..6191a5d58 100644
--- a/doc_src/help.txt
+++ b/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
-the documentation, otherwise fish will search for a suitable browser.
+If the BROWSER environment variable is set, it will be used to display the
+documentation, otherwise fish will search for a suitable browser.
+
+Note also that most builtin commands display their help in the terminal when
+given the --help option.
 
 \subsection help-example Example
 
diff --git a/doc_src/if.txt b/doc_src/if.txt
index f8bd5a655..fca3ecf03 100644
--- a/doc_src/if.txt
+++ b/doc_src/if.txt
@@ -1,13 +1,13 @@
 \section if if - Conditionally execute a command
 
 \subsection if-synopsis Synopsis
-if CONDITION; COMMAND_TRUE [else; COMMAND_FALSE] end;
+if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end
 
 \subsection if-description Description
-if will execute the command CONDITION. If the commands exit
-status is zero, the command COMMAND_TRUE will execute. If it is
-not zero and COMMAND_FALSE is specified, COMMAND_FALSE will be
-executed.
+if will execute the command CONDITION.  If the condition's exit
+status is 0, the commands COMMANDS_TRUE will execute.  If it is not 0 and
+else is given, COMMANDS_FALSE will be executed.  Hint: use
+begin; ...; end for complex conditions.
 
 \subsection if-example Example
 
diff --git a/doc_src/mimedb.txt b/doc_src/mimedb.txt
index 917c41e3d..2f404dc39 100644
--- a/doc_src/mimedb.txt
+++ b/doc_src/mimedb.txt
@@ -1,4 +1,3 @@
-
 \section mimedb mimedb - Lookup file information via the mime database
 
 \subsection mimedb-synopsis Synopsis
diff --git a/doc_src/nextd.txt b/doc_src/nextd.txt
index c33a4dd86..91ec46d2f 100644
--- a/doc_src/nextd.txt
+++ b/doc_src/nextd.txt
@@ -3,8 +3,8 @@
 \subsection nextd-synopsis Synopsis
 nextd [-l | --list] [pos]
 
-\subsection nextd-description Description nextd moves
-forwards pos positions in the history of visited directories;
-if the end of the history has been hit, a warning is printed. If the
--l> or --list flag is specified, the current
+\subsection nextd-description Description
+nextd moves forwards pos positions in the history of visited
+directories; if the end of the history has been hit, a warning is printed. If
+the -l> or --list flag is specified, the current
 history is also displayed.
diff --git a/doc_src/not.txt b/doc_src/not.txt
index 5fa59d01e..a40818cf2 100644
--- a/doc_src/not.txt
+++ b/doc_src/not.txt
@@ -1,14 +1,12 @@
-
 \section not not - Negate the exit status of a job
 
 \subsection not-synopsis Synopsis
- not COMMAND [OPTIONS...]
+not COMMAND [OPTIONS...]
 
 \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.
diff --git a/doc_src/open.txt b/doc_src/open.txt
index 455fd1ee3..5a191e3b9 100644
--- a/doc_src/open.txt
+++ b/doc_src/open.txt
@@ -1,4 +1,3 @@
-
 \section open open - Open file in it's default application
 
 \subsection open-synopsis Synopsis
diff --git a/doc_src/or.txt b/doc_src/or.txt
index 8ac3c3a28..dc36b535c 100644
--- a/doc_src/or.txt
+++ b/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.
 
diff --git a/doc_src/psub.txt b/doc_src/psub.txt
index d69c16fb6..6fd0950c0 100644
--- a/doc_src/psub.txt
+++ b/doc_src/psub.txt
@@ -1,4 +1,3 @@
-
 \section psub psub - Perform process substitution
 
 \subsection psub-synopsis Synopsis
diff --git a/doc_src/random.txt b/doc_src/random.txt
index 5b0713c32..9e08126d2 100644
--- a/doc_src/random.txt
+++ b/doc_src/random.txt
@@ -1,4 +1,3 @@
-
 \section random random - Generate random number
 
 \subsection random-synopsis Synopsis
diff --git a/doc_src/return.txt b/doc_src/return.txt
index a3c97809f..4009130a4 100644
--- a/doc_src/return.txt
+++ b/doc_src/return.txt
@@ -1,8 +1,7 @@
-
 \section return return - Stop the innermost currently evaluated function
 
 \subsection return-synopsis Synopsis
- function NAME; [COMMANDS...] return [STATUS]; [COMMANDS...] end
+function NAME; [COMMANDS...;] return [STATUS]; [COMMANDS...;] end
 
 \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
-

-
function false
-	return 1
-end

-

+
+
+function false
+	return 1
+end
+

+
 
diff --git a/doc_src/set.txt b/doc_src/set.txt
index 8354dbef7..c5f20b1ca 100644
--- a/doc_src/set.txt
+++ b/doc_src/set.txt
@@ -1,12 +1,14 @@
 \section set set - Handle environment variables.
 
 \subsection set-synopsis Synopsis
-
set [SCOPE_OPTIONS]
+
+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]... 

+set (-e | --erase) [SCOPE_OPTIONS] VARIABLE_NAME[INDICES]...
+

 
 The set builtin causes fish to assign the variable VARIABLE_NAME the values VALUES....
 
diff --git a/doc_src/set_color.txt b/doc_src/set_color.txt
index 02c5ad231..08effe69c 100644
--- a/doc_src/set_color.txt
+++ b/doc_src/set_color.txt
@@ -1,4 +1,3 @@
-
 \section set_color set_color - Set the terminal color
 
 \subsection set_color-synopsis Synopsis
diff --git a/doc_src/status.txt b/doc_src/status.txt
index 08617c6d9..f65a9b4ba 100644
--- a/doc_src/status.txt
+++ b/doc_src/status.txt
@@ -1,5 +1,4 @@
-
-\section status status - Display fish runtime information
+\section status status - Query fish runtime information
 
 \subsection status-synopsis Synopsis
  status [OPTION]
diff --git a/doc_src/switch.txt b/doc_src/switch.txt
index efa39abd7..100e21f06 100644
--- a/doc_src/switch.txt
+++ b/doc_src/switch.txt
@@ -1,8 +1,7 @@
-
 \section switch switch - conditionally execute a block of commands
 
 \subsection switch-synopsis Synopsis
- switch VALUE; [case [WILDCARD...]; [COMMANDS...];...] end
+switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
 
 \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
-following code would attempt to classify it:
+If the variable \$animal contains the name of an animal, the following
+code would attempt to classify it:
 
-

 
 switch $animal
     case cat
@@ -42,10 +46,7 @@ switch $animal
         echo I have no idea what a $animal is
 end
 

-

-

 
 If the above code was run with \c \$animal set to \c whale, the output
 would be \c mammal.
 
-

diff --git a/doc_src/trap.txt b/doc_src/trap.txt
index a94039a8f..bd44d4584 100644
--- a/doc_src/trap.txt
+++ b/doc_src/trap.txt
@@ -1,4 +1,3 @@
-
 \section trap trap - perform an action when the shell receives a signal
 
 \subsection trap-synopsis Synopsis
diff --git a/doc_src/type.txt b/doc_src/type.txt
index 26afca76a..f0ca6d37e 100644
--- a/doc_src/type.txt
+++ b/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
diff --git a/doc_src/ulimit.txt b/doc_src/ulimit.txt
index 204dd7c2c..ff0f60ea0 100644
--- a/doc_src/ulimit.txt
+++ b/doc_src/ulimit.txt
@@ -1,4 +1,3 @@
-
 \section ulimit ulimit - Set or get the shells resource usage limits
 
 \subsection ulimit-synopsis Synopsis
diff --git a/doc_src/umask.txt b/doc_src/umask.txt
index 793ef1f43..04ad89877 100644
--- a/doc_src/umask.txt
+++ b/doc_src/umask.txt
@@ -1,4 +1,3 @@
-
 \section umask umask - Set or get the shells resource usage limits
 
 \subsection umask-synopsis Synopsis
diff --git a/doc_src/vared.txt b/doc_src/vared.txt
index e32ee80dd..1278533bf 100644
--- a/doc_src/vared.txt
+++ b/doc_src/vared.txt
@@ -1,4 +1,3 @@
-
 \section vared vared - Interactively edit the value of an environment variable 
 
 \subsection vared-synopsis Synopsis
diff --git a/doc_src/while.txt b/doc_src/while.txt
index 3a59afc57..6b2bebb01 100644
--- a/doc_src/while.txt
+++ b/doc_src/while.txt
@@ -1,13 +1,19 @@
 \section while while - perform a command multiple times
 
 \subsection while-synopsis Synopsis
-while CONDITION; COMMANDS; end
+while CONDITION; COMMANDS...; end
 
 \subsection while-synopsis Synopsis
-The while builtin causes fish to continually execute the command COMMANDS while the command CONDITION returns with status 0.
+The while builtin causes fish to continually execute CONDITION and
+execute COMMANDS as long as CONDITION returned with status 0. If CONDITION is
+false on the first time, COMMANDS will not be executed at all. Hints: use
+begin; ...; end for complex conditions; more
+complex control can be achieved with while true containing a
+break.
 
 \subsection while-example Example
 
 while test -f foo.txt; echo file exists; sleep 10; end
 
-causes fish to print the line 'file exists' at 10 second intervals as long as 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.