diff options
| author |  axel <axel@liljencrantz.se> | 2006-09-20 00:52:03 +1000 |
|---|---|---|
| committer | axel <axel@liljencrantz.se> | 2006-09-20 00:52:03 +1000 |
| commit | 7a5823fd605af80df483e1d3f3629e60503488de (patch) | |
| tree | 714e61c3c6cddec3eb7499e99121de2f3efdcb4e | |
| parent | 81d61c467b2fc42e7e890198fb2bd203b27aff44 (diff) | |
Documentation updates from Beni Cherniavsky
darcs-hash:20060919145203-ac50b-bc87b8f5e6a18395e4bc3e364da4a40ad97850e7.gz
37 files changed, 106 insertions, 108 deletions
diff --git a/doc_src/and.txt b/doc_src/and.txt index bd884b1b..f36adfb3 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 62bb3810..ecdac1c8 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 - <tt>begin; [COMMAND;...] end </tt> + <tt>begin; [COMMANDS...;] end</tt> \subsection begin-description Description diff --git a/doc_src/bind.txt b/doc_src/bind.txt index 54e0cd9f..b5645182 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 -<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 diff --git a/doc_src/block.txt b/doc_src/block.txt index 8e38c04b..a1256bb8 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 -<pre>block -g +<pre> +block -g \#Do something that should not be interrupted block -e </pre> diff --git a/doc_src/break.txt b/doc_src/break.txt index ebeb4adc..9e511872 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 <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> if grep smurf $i; -<br> echo Smurfs are present in $i; -<br> break; -<br> end; -<br>end; -</tt> -</p> +<pre> +for i in *.c + if grep smurf $i + echo Smurfs are present in $i + break + end +end +</pre> diff --git a/doc_src/builtin.txt b/doc_src/builtin.txt index 528f058e..70d202ac 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 714d7582..c8354755 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 -<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 would be \c mammal. -</p> + +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 735562d1..b785c9b9 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 43335240..47009393 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 -<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; -<br> if grep smurf $i; -<br> continue; -<br> end; -<br> rm $i; -<br>end; -</tt> -</p> + +<pre> +for i in *.tmp + if grep smurf $i + continue + end + rm $i +end +</pre> diff --git a/doc_src/count.txt b/doc_src/count.txt index db9c5e37..dcadea90 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 8f684e3f..035abd62 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 -<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 -status is zero, the command COMMAND_TRUE will execute. If it is -not zero and COMMAND_FALSE is specified, COMMAND_FALSE will be -executed. +<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. \subsection else-example Example diff --git a/doc_src/end.txt b/doc_src/end.txt index 4e891fb3..5849e339 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 -<pre>for VARNAME in [VALUES...]; COMMANDS; end -if CONDITION; COMMAND_TRUE [else; COMMAND_FALSE] end -while CONDITION; COMMANDS; end -switch VALUE; [case [WILDCARD...]; [COMMANDS...];...] end +<pre> 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 diff --git a/doc_src/exec.txt b/doc_src/exec.txt index c915b58b..fca95b7a 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 35830239..b1e7b837 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 5414d927..cc59b1b8 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 83fee0dc..b4b3dfaf 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 -<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 -by <tt>COMMANDS</tt> multiple times. Each time the environment variable -specified by <tt>VARNAME</tt> is assigned a new value from <tt>VALUES</tt>. +<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 +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> diff --git a/doc_src/function.txt b/doc_src/function.txt index 51225f55..37ed23fc 100644 --- a/doc_src/function.txt +++ b/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> diff --git a/doc_src/help.txt b/doc_src/help.txt index 93c9a847..6191a5d5 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 <tt>--help</tt> option. \subsection help-example Example diff --git a/doc_src/if.txt b/doc_src/if.txt index f8bd5a65..fca3ecf0 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 -<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 -status is zero, the command COMMAND_TRUE will execute. If it is -not zero and COMMAND_FALSE is specified, COMMAND_FALSE will be -executed. +<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. \subsection if-example Example diff --git a/doc_src/mimedb.txt b/doc_src/mimedb.txt index 917c41e3..2f404dc3 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 c33a4dd8..91ec46d2 100644 --- a/doc_src/nextd.txt +++ b/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 -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 +\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. diff --git a/doc_src/not.txt b/doc_src/not.txt index 5fa59d01..a40818cf 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 - <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. diff --git a/doc_src/open.txt b/doc_src/open.txt index 455fd1ee..5a191e3b 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 8ac3c3a2..dc36b535 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 d69c16fb..6fd0950c 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 5b0713c3..9e08126d 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 a3c97809..4009130a 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 - <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> +function false return 1 -end</pre> -</p> +end +</pre> + diff --git a/doc_src/set.txt b/doc_src/set.txt index 8354dbef..c5f20b1c 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 -<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>. diff --git a/doc_src/set_color.txt b/doc_src/set_color.txt index 02c5ad23..08effe69 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 08617c6d..f65a9b4b 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 <tt>status [OPTION]</tt> diff --git a/doc_src/switch.txt b/doc_src/switch.txt index efa39abd..100e21f0 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 - <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 -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: -<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> diff --git a/doc_src/trap.txt b/doc_src/trap.txt index a94039a8..bd44d458 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 26afca76..f0ca6d37 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 204dd7c2..ff0f60ea 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 793ef1f4..04ad8987 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 e32ee80d..1278533b 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 3a59afc5..6b2bebb0 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 -<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. |