Documentation updates

darcs-hash:20061111105208-ac50b-27e335ba701b021d3119206e91d68c8504d45c2b.gz

4 files changed, 82 insertions, 21 deletions

diff --git a/doc_src/if.txt b/doc_src/if.txt
index f1238002..ed19fbe0 100644
--- a/doc_src/if.txt
+++ b/doc_src/if.txt
@@ -5,10 +5,15 @@
 
 \subsection if-description Description
 
-<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.
+<tt>if</tt> will execute the command CONDITION.  If the condition's
+exit status is 0, the commands COMMANDS_TRUE will execute.  If the
+exit status is not 0 and <tt>else</tt> is given, COMMANDS_FALSE will
+be executed.  
+
+In order to use the exit status of mutiple commands as the condition
+of an if block, use <a href="#begin"><tt>begin; ...; end</tt></a> and
+the short circut commands <a href="commands.html#and">and</a> and <a
+href="commands.html#or">or</a>.
 
 The exit status of the last foreground command to exit can always be
 accessed using the <a href="index.html#variables-status">$status</a>
diff --git a/doc_src/index.hdr b/doc_src/index.hdr
index 643c41fc..b74e2645 100644
--- a/doc_src/index.hdr
+++ b/doc_src/index.hdr
@@ -262,7 +262,26 @@ the example above, these are simply passed on to the ls command. For
 more information on functions, see the documentation for the <a
 href='commands.html#function'>function</a> builtin.
 
-\subsubsection Autoloading functions
+\subsubsection syntax-function-wrappers Defining wrapper functions
+
+One of the most common used for functions is to slightly alter the
+behaviour of an already existing command. For example, one might want
+to redefine the \c ls command to display colors. The switch for
+turning on colors on GNU systems is \c '--color=auto'. A wrapper
+around \c ls might look like this:
+
+<pre>function ls
+	ls --color=auto $argv
+end
+</pre>
+
+There are a few important things that need to be noted about wrapper
+functions:
+
+- Wrappers should always take care to add the $argv variable to the list of parameters to the wrapped command. This makes sure that if the user specifies any additional parameters to the function, they are passed on to the underlying command.
+- If the wrapped command is not the first command to be called by the wrapper, it is necessary to prefix the call to the command with the word 'command' in order to tell fish that the function should not call itself, but rather a command with the same name. Failing to do so will cause infinite recursion bugs.
+
+\subsubsection syntax-function-autoloading Autoloading functions
 
 Functions can be defined on the commandline or in a configuration
 file, but they can also be automatically loaded. This method of
@@ -293,6 +312,25 @@ definition for the specified function and nothing else, otherwise it
 is possible that autoloading a function files requires that the
 function already be loaded, i.e. a circular dependency.
 
+\subsection syntax-conditional Conditional execution of code
+
+There are four fish builtins that let you execute commands only if a
+specific criterion is met. These builtins are 
+<a href="commands.html#if">if</a>, 
+<a href="commands.html#switch">switch</a>, 
+<a href="commands.html#and">and</a> and 
+<a href="commands.html#or">or</a>.
+
+The \c switch command is used to execute one of possibly many blocks
+of commands depending on the value of a string. See the documentation
+for <a href="commands.html#switch">switch</a> for more information.
+
+The other conditionals use the <a href='#variables-status'>exit
+status</a> of a command to decide if a command or a block of commands
+should be executed. See the documentation for 
+<a href="commands.html#if">if</a>, <a href="commands.html#and">and</a>
+and <a href="commands.html#or">or</a> for more information.
+
 \subsection syntax-words Some common words
 
 This is a short explanation of some of the commonly used words in fish.
@@ -300,7 +338,7 @@ This is a short explanation of some of the commonly used words in fish.
 - argument, a parameter given to a command
 - builtin, a command that is implemented in the shell. Builtins are commands that are so closely tied to the shell that it is impossible to implement them as external commands.
 - command, a program that the shell can run.
-- function, a block of commands and arguments that can be called as if they where a single command. By using functions, it is possible to string together multiple smaller commands into one more advanced command.
+- function, a block of commands that can be called as if they where a single command. By using functions, it is possible to string together multiple smaller commands into one more advanced command.
 - job, a running pipeline or command
 - pipeline, a set of commands stringed together so that the output of one command is the input of the next command
 - redirection, a operation that changes one of the input/output streams associated with a job
@@ -326,13 +364,13 @@ shell. By tapping the tab key, the user asks \c fish to guess the rest
 of the command or parameter that the user is currently typing. If \c
 fish can only find one possible completion, \c fish will write it
 out. If there is more than one completion, \c fish will write out the
-longest common prefix that all completions have in common. If all
-completions differ on the first character, a list of all possible
-completions is printed. The list features descriptions of the
-completions and if the list doesn't fit the screen, it is scrollable
-by using the arrow keys, the page up/page down keys or the space
-bar. Press any other key will exit the list and insert the pressed key
-into the command line.
+longest prefix that all completions have in common. If the completions
+differ on the first character, a list of all possible completions is
+printed. The list features descriptions of the completions and if the
+list doesn't fit the screen, it is scrollable by using the arrow keys,
+the page up/page down keys, the tab key or the space bar. Pressing any
+other key will exit the list and insert the pressed key into the
+command line.
 
 These are the general purpose tab completions that \c fish provides:
 
@@ -351,14 +389,14 @@ manual pages as completions.
 - The 'make' program uses all targets in the Makefile in 
 the current directory as completions.
 - The 'mount' command uses all mount points specified in fstab as completions.
-- The 'ssh' command uses all hosts in that are stored 
+- The 'ssh' command uses all hosts that are stored 
 in the known_hosts file as completions. (see the ssh documentation for more information) 
 - The 'su' command uses all users on the system as completions.
 - The \c apt-get, \c rpm and \c yum commands use all installed packages as completions.
 
 \subsection completion-own Writing your own completions
 
-Specifying your own completions is not complicated. To specify a
+Specifying your own completions is not difficult. To specify a
 completion, use the \c complete command. \c complete takes
 as a parameter the name of the command to specify a completion
 for. For example, to add a completion for the program \c myprog, one
@@ -430,10 +468,14 @@ If a star (*) or a question mark (?) is present in the parameter, \c
 fish attempts to match the given parameter to any files in such a
 way that:
 
-- '?' can match any character except '/'.
+- '?' can match any single character except '/'.
 - '*' can match any string of characters not containing '/'. This includes matching an empty string.
 - '**' matches any string of characters. This includes matching an empty string. The string may include the '/' character but does not need to.
 
+File names beginning with a dot are not considered when wildcarding
+unless a dot is specifically given as the first character of the file
+name.
+
 Examples:
 
 <code>a*</code> matches any files beginning with an 'a' in the current directory.
@@ -1294,6 +1336,7 @@ g++, javac, java, gcj, lpr, doxygen, whois, find)
 - The code validator should warn about unknown commands.
 - The large number of interned strings means that autounloading frees less memory than it should. Completion strings should probably be either refcounted or not shared at all.
 - Auto-newlines
+- Completions for uncompressing archives, like unrar could look into the compressed file and allow you to select what files to extract
 
 \subsection bugs Known bugs and issues
 
@@ -1304,6 +1347,7 @@ g++, javac, java, gcj, lpr, doxygen, whois, find)
 - Can't complete directories as commands unless there is a slash
 - ls should use dircolors
 - Doxygen called when it shouldn't?
+- Delete-word is broken on the commandline 'sudo update-alternatives --config x-'
 
 If you think you have found a bug not described here, please send a
 report to <a href="mailto:fish-users@lists.sf.net">fish-users@lists.sf.net</a>.
diff --git a/doc_src/license.hdr b/doc_src/license.hdr
index c7b93126..5e433a01 100644
--- a/doc_src/license.hdr
+++ b/doc_src/license.hdr
@@ -1,7 +1,7 @@
 /** \page license Licenses
 
-Fish Copyright (C) 2005 Axel Liljencrantz. Fish is released under the
-GNU General Public License, version 2. The license agreement is
+Fish Copyright (C) 2005-2006 Axel Liljencrantz. Fish is released under
+the GNU General Public License, version 2. The license agreement is
 included below.
 
 Fish contains code under the BSD license, namely versions of the
diff --git a/user_doc.head.html b/user_doc.head.html
index f5ee9ab1..342bf99b 100644
--- a/user_doc.head.html
+++ b/user_doc.head.html
@@ -6,13 +6,25 @@
 Override the default doxygen stylesheet to make the difference between different header levels larger
 -->
 <style type='text/css'>
-H2 
+H1
 {
+	font-size: 180%;
+}
+H2
+{
+	font-size: 150%;
 }
-
 H3
 {
-	padding-left:2%;
+	padding-left:10%;
+	font-size: 120%;
+}
+H4
+{
+	padding-left:10%;
+	font-style: italic;
+	font-weight: normal;
+	font-size: 90%;
 }
 </style>
 </head>