PATCH: Misc. documentation stuff

["Bart Schaefer" <schaefer@xxxxxxxxxxxxxxxxxxxxxxx>]

This patch includes:

* Add some minimal doc for `compfiles' and `compgroups'.  It'd be really
  nice if some knowledgable person (hi, Sven) could explain the syntax
  of these and other commands in computil in a little more detail.  The
  same goes for zregexparse (hi, Tanaka) in zutil.

* Fix some typos under "Matching Control" in compwid.

* Alphabetize the builtins in computil and add findex entries.

* Break up one long paragraph and fix some typos under the zstyle command
  in zutil.

* Break up the long first paragraph under zparseopts and shuffle the
  order around a little.  Add an analogy to `shift' to better explain
  `zparseopts -D'.

I also added back a minimal reference to `compfmt' because it's still
defined in computil.c and therefore will show up in command completion
listings and `hash -m' output and so forth.  But it might be better to
simply remove it entirely.

Index: Doc/Zsh/builtins.yo
===================================================================
@@ -176,6 +176,9 @@
 module(compcall)(zsh/compctl)
 module(compctl)(zsh/compctl)
 module(compdescribe)(zsh/computil)
+module(compfiles)(zsh/computil)
+alias(compfmt)(zformat -f)
+module(compgroups)(zsh/computil)
 module(compquote)(zsh/computil)
 module(comptags)(zsh/computil)
 module(comptry)(zsh/computil)
Index: Doc/Zsh/compwid.yo
===================================================================
@@ -787,7 +787,7 @@
 texinode(Matching Control)(Examples)(Condition Codes)(Completion Widgets)
 sect(Matching Control)
 
-It is possible by use of the 
+It is possible by use of the
 tt(-M) option of the tt(compadd) builtin command to specify how the
 characters in the string to be completed (referred to here as the
 command line) map onto the characters in the list of matches produced by
@@ -796,14 +796,16 @@
 the tt(GLOB_COMPLETE) option is set or the tt(pattern_match) of the
 tt(compstate) special association is set to a non-empty string.
 
-The var(spec) given as argument to the tt(-m) option consists of one
-or more matching descriptions separated by
+The var(match-spec) given as argument to the tt(-M) option (see
+ifzman(`Builtin Commands' above)\
+ifnzman(noderef(Builtin Commands))\
+) consists of one or more matching descriptions separated by
 whitespace.  Each description consists of a letter followed by a colon
 and then the patterns describing which character sequences on the line match
 which character sequences in the trial completion.  Any sequence of
 characters not handled in this fashion must match exactly, as usual.
 
-The forms of var(spec) understood are as follows. In each case, the
+The forms of var(match-spec) understood are as follows. In each case, the
 form with an uppercase initial character retains the string already
 typed on the command line as the final result of completion, while with
 a lowercase initial character the string on the command line is changed
@@ -920,7 +922,7 @@
 instead of the first part. As described above, this matches at the
 beginning of the trial completion, independent of other characters or
 substrings at the beginning of the command line word which are ignored
-by the same or other var(spec)s.
+by the same or other var(match-spec)s.
 
 The second example makes completion case insensitive.  This is just
 the same as in the option example, except here we wish to retain the
Index: Doc/Zsh/mod_computil.yo
===================================================================
--- mod_computil.yo	2000/05/21 23:41:52	1.11
+++ mod_computil.yo	2000/06/25 17:52:19
@@ -13,18 +13,14 @@
 completion functions.  In summary, these builtin commands are:
 
 startitem()
-item(tt(compquote) var(names) ...)(
-There may be reasons to write completion functions that have to add
-the matches using the tt(-Q) option to tt(compadd) and perform quoting
-themselves.  Instead of interpreting the first character of the
-tt(all_quotes) key of the tt(compstate) special association and using
-the tt(q) flag for parameter expansions, one can use this builtin
-command.  The arguments are the names of scalar or array parameters
-and the values of these parameters are quoted as needed for the
-innermost quoting level.
-
-The return value is non-zero in case of an error and zero otherwise.
+findex(comparguments)
+item(tt(comparguments))(
+This is used by the tt(_arguments) function to do the argument and
+command line parsing.  Like tt(compdescribe) it has an option tt(-i) to 
+do the parsing and initialize some internal state and various options
+to access the state information to decide what should be completed.
 )
+findex(compdescribe)
 item(tt(compdescribe))(
 This is used by the tt(_describe) function to build the displays for
 the matches and to get the strings to add as matches with their
@@ -44,16 +40,41 @@
 matches for them in the fifth array.  These are then directly given to
 tt(compadd) to register the matches with the completion code.
 )
-item(tt(comparguments))(
-This is used by the tt(_arguments) function to do the argument and
-command line parsing.  Like tt(compdescribe) it has an option tt(-i) to 
-do the parsing and initialize some internal state and various options
-to access the state information to decide what should be completed.
+findex(compfiles)
+item(tt(compfiles))(
+Used by the tt(_path_files) function to optimize complex recursive
+filename generation (globbing).
+)
+findex(compfmt)
+item(tt(compfmt))(
+An obsolete form of `tt(zformat -f)'.  Do not use this.
+)
+findex(compgroups)
+item(tt(compgroups))(
+Used by the tt(_tags) function to implement the internals of the
+tt(group-order) style.
+)
+findex(compquote)
+item(tt(compquote) var(names) ...)(
+There may be reasons to write completion functions that have to add
+the matches using the tt(-Q) option to tt(compadd) and perform quoting
+themselves.  Instead of interpreting the first character of the
+tt(all_quotes) key of the tt(compstate) special association and using
+the tt(q) flag for parameter expansions, one can use this builtin
+command.  The arguments are the names of scalar or array parameters
+and the values of these parameters are quoted as needed for the
+innermost quoting level.
+
+The return value is non-zero in case of an error and zero otherwise.
 )
+findex(comptags)
+findex(comptry)
+xitem(tt(comptags))
+item(tt(comptry))(
+These implements the internals of the tags mechanism.
+)
+findex(compvalues)
 item(tt(compvalues))(
 Like tt(comparguments), but for the tt(_values) function.
-)
-item(tt(comptags), tt(comptry))(
-This implements the internals of the tags mechanism.
 )
 enditem()
Index: Doc/Zsh/mod_zutil.yo
===================================================================
@@ -19,8 +19,10 @@
 strings.  They are stored together with patterns and lookup is done by
 giving a string, called the `context', which is compared to the
 patterns.  The definition stored for the first matching pattern will be 
-returned.  For this, the patterns are ordered from most specific to
-less specific and patterns that are equally specific keep the order in 
+returned.
+
+For ordering of comparisons, patterns are searched from most specific to
+least specific, and patterns that are equally specific keep the order in 
 which they were defined.  A pattern is considered to be more specific
 than another if it contains more components (substrings separated by
 colons) or if the patterns for the components are more specific, where 
@@ -33,16 +35,16 @@
 done in the form of calls to tt(zstyle).  Forms with arguments:
 
 startitem()
-item(tt(zstyle) [ tt(-e) | tt(-) | tt(-)tt(-) ] var(pattern) var(style) var(strings) ...)(
+item(tt(zstyle) [ tt(-) | tt(-)tt(-) | tt(-e) ] var(pattern) var(style) var(strings) ...)(
 Defines the given var(style) for the var(pattern) with the var(strings) as
 the value.  If the tt(-e) option is given, the var(strings) will be
 concatenated (separated by spaces) and the resulting string will be
-evaluated (in the same way as it is dome by the tt(eval) builtin
+evaluated (in the same way as it is done by the tt(eval) builtin
 command) when the style is looked up.  In this case the parameter
-tt(reply) will be used to get the strings to return after the
-evaluation.  Before evaluating the value, tt(reply) will be unset and
-if it is still unset after the evaluation, this will be handled as if
-the style were not set.
+`tt(reply)' must be assigned to set the strings returned after the
+evaluation.  Before evaluating the value, tt(reply) is unset, and
+if it is still unset after the evaluation, the style is treated as if
+it were not set.
 )
 item(tt(zstyle -d) [ var(pattern) [ var(styles) ... ] ])(
 Delete style definitions. Without arguments all definitions are deleted,
@@ -76,7 +78,7 @@
 )
 item(tt(zstyle -a) var(context) var(style) var(name))(
 The value is stored in var(name) as an array. If var(name) is declared 
-as an associative array,  the first, third, etc. stringare used as the
+as an associative array,  the first, third, etc. strings are used as the
 keys and the other strings are used as the values.
 )
 xitem(tt(zstyle -t) var(context) var(style) [ var(strings) ...])
@@ -89,8 +91,9 @@
 at least one of the var(strings) is equal to at least one of the strings
 in the value. If the style is not defined, the status is tt(2).
 
-The tt(-T) option is like tt(-t) but returns zero if the style is not
-set for any matching pattern.
+The tt(-T) option tests the values of the style like tt(-t), but it
+returns zero (rather than tt(2)) if the style is not defined for any
+matching pattern.
 )
 item(tt(zstyle -m) var(context) var(style) var(pattern))(
 Match a value. Returns status zero if the 
@@ -135,64 +138,85 @@
 )
 findex(zregexparse)
 item(tt(zregexparse))(
-This implements the internals of the `tt(_regex_arguments)'.
+This implements some internals of the tt(_regex_arguments) function.
 )
 findex(zparseopts)
 item(tt(zparseopts) [ tt(-D) ] [ tt(-K) ] [ tt(-E) ] [ tt(-a) var(array) ] [ tt(-A) var(assoc) ] var(specs))(
-This builtin simplifies the parsing of options in positional
-parameters, i.e. the set of arguments given by tt($*).  Each var(spec)
-describes one option and should be of the form
-`var(name)[tt(+)][tt(:)[tt(:)][tt(-)]][tt(=)var(array)]'.  The var(name) is
-the name of the option (without the leading `tt(-)').  If only the option
-name is given, the option takes no argument and if it is found in the
-positional parameters it will be placed in the var(array) specified with
-the tt(-a) option; if the optional `tt(=)var(array)' is given, it will
-instead be put into that array.  If one or two colons are given, the
-option takes an argument; with one colon, the argument is mandatory
-and with two colons it is optional.  The argument will also be inserted into 
-the var(array).  A mandatory arguments is added as a separate 
-string and an optional argument is put into a single string together
-with the option name, unless a `tt(-)' appears after the colon, in
-which case the argument will be put into the same word even for mandatory
-arguments (note that this makes empty strings as arguments
-indistinguishable).  Finally, if a `tt(+)' appears after var(name) the
-option may appears more than once in the positional parameters and will
-hence be inserted more than once in the var(array); without the `tt(+)'
-the option will be inserted only once in the var(array) with arguments 
-of later options overwriting earlier once.  Any of the special
-characters can appear in the option name provided it is preceded by a
-backslash.
+This builtin simplifies the parsing of options in positional parameters,
+i.e. the set of arguments given by tt($*).  Each var(spec) describes one
+option and must be of the form `var(opt)[tt(=)var(array)]'.  If an option
+described by var(opt) is found in the positional parameters it is copied
+into the var(array) specified with the tt(-a) option; if the optional
+`tt(=)var(array)' is given, it is instead copied into that array.
 
+Note that it is an error to give any var(spec) without an
+`tt(=)var(array)' unless one of the tt(-a) or tt(-A) options is used.
+
 Unless the tt(-E) option is given, parsing stops at the first string
-that isn't described by one of the var(specs) And even with tt(-E),
+that isn't described by one of the var(specs).  Even with tt(-E),
 parsing always stops at a positional parameter equal to `tt(-)' or
 `tt(-)tt(-)'.
+
+The var(opt) description must be one of the following.  Any of the special
+characters can appear in the option name provided it is preceded by a
+backslash.
+
+startitem()
+xitem(var(name))
+item(var(name)tt(+))(
+The var(name) is the name of the option without the leading `tt(-)'.  To
+specify a GNU-style long option, one of the usual two leading `tt(-)' must
+be included in var(name); for example, a `tt(--file)' option is
+represented by a var(name) of `tt(-file)'.
+
+If a `tt(+)' appears after var(name), the option is appended to var(array)
+each time it is found in the positional parameters; without the `tt(+)'
+only the em(last) occurrence of the option is preserved.
+
+If one of these forms is used, the option takes no argument, so parsing
+stops if the next positional parameter does not also begin with `tt(-)'
+(unless the tt(-E) option is used).
+)
+xitem(var(name)tt(:))
+xitem(var(name)tt(:-))
+item(var(name)tt(::))(
+If one or two colons are given, the option takes an argument; with one
+colon, the argument is mandatory and with two colons it is optional.  The
+argument is appended to the var(array) after the option itself.
+
+An optional argument is put into the same array element as the option name
+(note that this makes empty strings as arguments indistinguishable).  A
+mandatory argument is added as a separate element unless the `tt(:-)' form
+is used, in which case the argument is put into the same element.
+
+A `tt(+)' as described above may appear between the var(name) and the
+first colon.
+)
+enditem()
 
-The other
+The options of tt(zparseopts) itself are:
 
 startitem()
 item(tt(-a) var(array))(
-As described above, this specifies the default array to store the
-recognised options in.
+As described above, this names the default array in which to store the
+recognised options.
 )
 item(tt(-A) var(assoc))(
-If this is given, the options and their values will also
-be put into an associative array with the option names as keys and the 
-arguments (if any) as the values.  Note that it is an error to give
-var(specs) without a `tt(=)var(array)' and not use either the tt(-a)
-or tt(-A) option.
+If this is given, the options and their values are also put into an
+associative array with the option names as keys and the arguments (if any)
+as the values.
 )
 item(tt(-D))(
-If this option is given, all options found are removed from the
-positional parameters, up to but not including any not described by the
-var(specs).  This means that any options processed by tt(zparseopts) are
-removed from the positional parameters.
+If this option is given, all options found are removed from the positional
+parameters of the calling shell or shell function, up to but not including
+any not described by the var(specs).  This is similar to using the tt(shift)
+builtin.
 )
 item(tt(-K))(
 With this option, the arrays specified with the tt(-a) and tt(-A)
-options and with the `tt(=)var(array)' forms will be left unchanged
-when none of the var(specs) for them is used.  This allows to assign
-default values to them before calling tt(zparseopts).
+options and with the `tt(=)var(array)' forms are kept unchanged when none
+of the var(specs) for them is used.  This allows assignment of default
+values to them before calling tt(zparseopts).
 )
 item(tt(-E))(
 This changes the parsing rules to em(not) stop at the first string

-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com

Zsh: http://www.zsh.org | PHPerl Project: http://phperl.sourceforge.net