Documentation updates, mostly corrections and cla<rifications to the docs for a few builtins

darcs-hash:20060608235811-ac50b-76b4fd54cb0911dd00f19f4a7c761f188d6ca068.gz

doc_src/doc.hdr

@@ -2444,7 +2444,7 @@ DAMAGES.
 
 <hr>
 
-\section faq-cwd-symlink Why does cd, pwd and other fish commands always resolve symlinked directories to their canonical path?
+\section faq-cwd-symlink Why does cd, $PWD and and various fish commands always resolve symlinked directories to their canonical path?
 
 <i>
 For example if ~/images is a symlink to ~/Documents/Images, if I write

doc_src/function.txt

@@ -1,16 +1,16 @@
 \section function function - create a function
 
 \subsection function-synopsis Synopsis
- <tt>function [OPTIONS] NAME; BODY; end </tt>
+ <code>function [OPTIONS] NAME; BODY; end </code>
 
 \subsection function-description Description
 
 - \c -b or \c --key-binding specifies that the function is a key biding. Key binding functions work exactly like regular functions except that they can not be tab-completed, and may contain the '-' character.
-- <tt>-d DESCRIPTION</tt> or \c --description=DESCRIPTION is a description of what the function does, suitable as a completion description
+- <code>-d DESCRIPTION</code> or \c --description=DESCRIPTION is a description of what the function does, suitable as a completion description
-- <tt>-j PID</tt> or <tt> --on-job-exit PID</tt> tells fish to run this function when the job with group id PID exits
+- <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
-- <tt>-p PID</tt> or <tt> --on-process-exit PID</tt> tells fish to run this function when the fish child process with process id PID exits
+- <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
-- <tt>-s</tt> or <tt>--on-signal SIGSPEC</tt> 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>-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)
-- <tt>-v</tt> or <tt>--on-variable VARIABLE_NAME</tt> tells fish to run this function when the variable VARIABLE_NAME changes value
+- <code>-v</code> or <code>--on-variable VARIABLE_NAME</code> tells fish to run this function when the variable VARIABLE_NAME changes value
 
 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
@@ -22,7 +22,7 @@ function hi
 end
 </pre>
 
-will write <tt>hello</tt> whenever the user enters \c hi.
+will write <code>hello</code> whenever the user enters \c hi.
 
 If the user enters any additional arguments after the function, they
 are inserted into the environment variable <a href="index.html#variables-arrays">array</a> argv.

doc_src/functions.txt

@@ -1,17 +1,22 @@
 \section functions functions - print or erase functions
 
 \subsection function-synopsis Synopsis
-<tt>functions [-e] FUNCTIONS...</tt>
+<code>functions [-e] FUNCTIONS...</code>
 
 \subsection functions-description Description
 
 This builtin command is used to print or erase functions.
 
-- <tt>-e</tt> or <tt>--erase</tt> causes the specified functions to be erased.
+- <code>-a</code> or <code>--all</code> list all functions, even those whose name start with an underscore.
-- <tt>-n</tt> or <tt>--names</tt> List only the names of all defined functions
+- <code>-d DESCRIPTION</code> or <code>--description=DESCRIPTION</code> change 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
 
 If \c functions is called with no arguments, the names and definition
 of all functions are printed, otherwise, the specified function
 definitions will be printed.
 
+If a function is automatically loaded, using <code>functions -e</code>
+to erase it will not remove the function.
 

doc_src/jobs.txt

@@ -1,18 +1,19 @@
 \section jobs jobs - print currently running jobs
 
 \subsection jobs-synopsis
-<tt>jobs [OPTIONS] [PID]</tt>
+<code>jobs [OPTIONS] [PID]</code>
 
 \subsection jobs-description Description
-The <tt>jobs</tt> builtin causes fish to print a list of the currently
+The <code>jobs</code> builtin causes fish to print a list of the currently
 running jobs and their status.
 
 jobs accepts the following switches:
 
-- <tt>-c</tt> or <tt>--command</tt> print the command name for each process in jobs
+- <code>-c</code> or <code>--command</code> print the command name for each process in jobs
-- <tt>-g</tt> or <tt>--group</tt> only print the group id of each job
+- <code>-g</code> or <code>--group</code> only print the group id of each job
-- <tt>-l</tt> or <tt>--last</tt> only the last job to be started is printed
+- <code>-h</code> or <code>--help</code> display a help message and exit
-- <tt>-p</tt> or <tt>--process</tt> print the process id for each process in all jobs
+- <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
 
 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

doc_src/set.txt

@@ -38,10 +38,15 @@ expanding or assigning to an array variable, the index will be
 calculated from the end of the array. For example, the index -1 means
 the last index of an array.
 
+The scoping rules when creating or updating a variable are:
+
 -# If a variable is explicitly set to either universal, global or local, that setting will be honored. If a variable of the same name exists in a different scope, that variable will not be changed.
 -# If a variable is not explicitly set to be either universal, global or local, but has been previously defined, the previos variable scope is used.
 -# If a variable is not explicitly set to be either universal, global or local and has never before been defined, the variable will be local to the currently executing functions. If no function is executing, the variable will be global.
 
+The exporting rules when creating or updating a variable are identical
+to the scoping rules for variables:
+
 -# If a variable is explicitly set to either be exported or not exported, that setting will be honored.
 -# If a variable is not explicitly set to be exported or not exported, but has been previously defined, the previous exporting rule for the variable is kept.
 -# If a variable is not explicitly set to be either global or local and has never before been defined, the variable will not be exported.
@@ -65,7 +70,7 @@ variable assignments where sucessfully performed, with a non-zero exit
 status otherwise. In query mode, the exit status is the number of
 variables that where not found. In erase mode, 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 readprotected or if the
+commandline was invalid, if the variable was write-protected or if the
 variable did not exist.
 
 \subsection set-example Example