Code cleanups and API documentation updates

darcs-hash:20051023121429-ac50b-6ff72171b5a90b6e398bd84e748388c1dba831d9.gz

doc_src/doc.hdr

@@ -563,6 +563,7 @@ certain environment variables.
 - \c CDPATH, which is an array of directories in which to search for the new directory for the \c cd builtin.
 - \c fish_color_normal, \c fish_color_command, \c fish_color_substitution, \c fish_color_redirection, \c fish_color_end, \c fish_color_error, \c fish_color_param, \c fish_color_comment, \c fish_color_match, \c fish_color_search_match, \c fish_color_cwd, \c fish_pager_color_prefix, \c fish_pager_color_completion, \c fish_pager_color_description and \c fish_pager_color_progress are used to change the color of various elements in \c fish. These variables are universal, i.e. when changing them, their new value will be used by all running fish sessions. The new value will also be retained when restarting fish.
 - \c PATH, which is an array of directories in which to search for commands
+- \c umask, which is the current file creation mask. The preffered way to change the umask variable is through the <a href="commands.html#umask">umask shellscript function</a>. An attempt to set umask to an invalid value will always fail.
 
 \c fish also sends additional information to the user through the
 values of certain environment variables. The user can not change the values of these variables. They are:
@@ -635,6 +636,7 @@ builtins or shellscript functions, and can only be used inside fish.
 - <a href="builtins.html#switch">switch</a>, conditionally execute a block of commands
 - <a href="commands.html#tokenize">tokenize</a>, split a string up into multiple tokens
 - <a href="builtins.html#ulimit">ulimit</a>, set or get the shells resurce usage limits
+- <a href="commandss.html#umask">umask</a>, set or get the file creation mask
 - <a href="builtins.html#while">while</a>, perform a block of commands while a condition is met
 
 For more information about these commands, use the <tt>--help</tt>

doc_src/umask.txt

@@ -10,9 +10,30 @@ With no argument, the current file-creation mask is printed, if an
 argument is specified, it is the new file creation mask. The mask may
 be specified as an octal number, in which case it is interpreted as
 the rights that should be masked away, i.e. it is the inverse of the
-file permissions any new files will have. If a synbolic mask is
-specified, the actual file permission bits, and not the inverse, are
-specified.
+file permissions any new files will have. 
+
+If a symbolic mask is specified, the actual file permission bits, and
+not the inverse, should be specified. A symbolic mask is a comma
+separated list of rights. Each right consists of three parts:
+
+- The first part specifies to whom this set of right applies, and can
+be one of \c u, \c g, \c o or \c a, where \c u specifies the user who
+owns the file, \c g specifies the group owner of the file, \c o
+specifiec other users rights and \c a specifies all three should be
+changed.
+- The second part of a right specifies the mode, and can be one of \c
+=, \c + or \c -, where \c = specifies that the rights should be set to
+the new value, \c + specifies that the specified right should be added
+to those previously specified and \c - specifies that the specified
+rights should be removed from those previously specified.
+- The third part of a right specifies what rights should be changed
+and can be any compination of \c r, \c w and \c x, representing
+read, write and execute rights.
+
+If the first and second parts are skipped, they are assumed to be \c a
+and \c =, respectively. As an example, <code>r,u+w</code> means all
+users should have read access and the file owner should also have
+write access.
 
 - <code>-h</code> or <code>--help</code> print this message
 - <code>-S</code> or <code>--symbolic</code> prints the file-creation mask in symbolic form instead of octal form. Use <code>man chmod</code> for more information.