Re: comments toward completion system docs

[Peter Stephenson <p.w.stephenson@xxxxxxxxxxxx>]

Note this has been moved to zsh-workers.

I've included some of your suggestions in the documentation and added
minor bits of my own.  I haven't touched _arguments any further yet.

I haven't changed the order of the manual, since it's a reference work
which is designed to put the basic parts first, but I've tried to ensure
the reader knows where to go.  As I mentioned, the new roadmap is an
important part of this.

Index: Doc/Zsh/compsys.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/compsys.yo,v
retrieving revision 1.191
diff -u -r1.191 compsys.yo
--- Doc/Zsh/compsys.yo	20 Sep 2006 14:09:56 -0000	1.191
+++ Doc/Zsh/compsys.yo	20 Sep 2006 21:50:58 -0000
@@ -5,12 +5,84 @@
 cindex(completion, controlling)
 sect(Description)
 
-This describes the shell code for the new completion system.  It consists
-of various shell functions; those beginning `tt(comp)' are to be called
-directly, while those beginning `tt(_)' are called by the
-completion code.  The shell functions of the second set, which implement
+This describes the shell code for the `new' completion system, referred
+to as tt(compsys).  It is written in shell functions based on the
+features described in
+ifzman(zmanref(zshcompwid))\
+ifnzman(the previous chapter, noderef(Completion Widgets)).
+
+The features are contextual, sensitive to the point at which completion is
+started.  Many completions are already provided.
+For this reason, a user can perform a great many tasks without
+knowing any details beyond how to initialize the system, which is
+described
+ifzman(below in INITIALIZATION)\
+ifnzman(in noderef(Initialization)).
+
+The context that decides what completion is to be performed may be
+startitemize()
+itemiz(\
+an argument or option position: these describe the position on the
+command line at which completion is requested.  For example `first argument
+to rmdir, the word being completed names a directory';
+)
+itemiz(\
+a special context, denoting an element in the shell's syntax.  For example
+`a word in command position' or `an array subscript'.
+)
+enditemize()
+
+A full context specification contains other elements, as we shall describe.
+
+Besides commands names and contexts, the system employs two more
+concepts, em(styles) and em(tags).  These provide ways for the user
+to configure the system's behaviour.
+
+Tags play a dual role.  They serve as a classification system for
+the matches, typically indicating a class of object that the user
+may need to distinguish.  For example, when completing arguments of the
+tt(ls) command the user may prefer to try tt(files) before tt(directories),
+so both of these are tags.  They also appear as the rightmost
+element in a context specification.
+
+Styles modify various operations of the completion system, such as
+output formatting, but also what kinds of completers are used (and in
+what order), or which tags are examined.  Styles may accept arguments
+and are manipulated using the tt(zstyle) command described in
+ifzman(see zmanref(zshmodules))\
+ifnzman(noderef(The zsh/zutil Module)).
+
+In summary, tags describe em(what) the completion objects are, and style
+tt(how) they are to be completed.  At various points of execution, the
+completion system checks what styles and/or tags are defined for the
+current context, and uses that to modify its behavior.  The full
+description of context handling, which determines how tags and other
+elements of the context influence the behaviour of styles, is described
+ifzman(below in COMPLETION SYSTEM CONFIGURATION)\
+ifnzman(in noderef(Completion System Configuration)).
+
+When a completion is requested, a dispatcher function is called;
+see the description of tt(_main_complete) in the list of control functions
+below. This dispatcher decides which function should
+be called to produce the completions, and calls it. The result is
+passed to one or more em(completers), functions that implement
+individual completion strategies: simple completion, error correction,
+completion with error correction, menu selection, etc.
+
+More generally, the shell functions contained in the completion system are
+of two types:
+startitemize()
+itemiz(\
+those beginning `tt(comp)' are to be called directly; there are only
+a few of these;
+)
+itemiz(\
+those beginning `tt(_)' are called by the
+completion code.  The shell functions of this set, which implement
 completion behaviour and may be bound to keystrokes, are referred to
-as `widgets'.
+as `widgets'.  These proliferate as new completions are required.
+)
+enditemize()
 
 startmenu()
 menu(Initialization)
@@ -464,8 +536,9 @@
 completion system.  The context used for lookup may vary during the same
 call to the completion system.
 
-The context string always consists of the following fields, separated
-by colons and with a leading colon before the first:
+The context string always consists of a fixed set of fields, separated
+by colons and with a leading colon before the first, in the form
+tt(:completion:)var(function)tt(:)var(completer)tt(:)var(command)tt(:)var(argument)tt(:)tt(tag).  These have the following meaning:
 
 startitemize()
 itemiz(\
@@ -510,13 +583,19 @@
 UNIX-style options and arguments, so many completions do not set this.
 )
 itemiz(\
-The var(tag).  Tags are used to discriminate between the types
-of matches a completion function can generate in a certain context and
-are described further below.
+The var(tag).  As described previously, tags are used to discriminate between
+the types of matches a completion function can generate in a certain context.
+Any completion function may use any tag name it likes, but a list of the
+more common ones is given below.
 )
 enditemize()
 
-As an example, the context name
+The context is gradually put together as the functions are executed, starting
+with the main entry point, which adds tt(:completion:) and the var(function)
+element if necessary.  The completer then adds the var(completer) element.
+The contextual completion adds the var(command) and var(argument) options.
+Finally, the var(tag) is added when the types of completion are known.
+For example, the context name
 
 example(tt(:completion::complete:dvips:option-o-1:files))
 
@@ -527,12 +606,7 @@
 
 and the completion function will generate filenames.
 
-Each type of completion the system can perform in a given context is
-described by a `tag', a short descriptive string such as tt(files) in
-the example above.  Any completion function may use any tag name it
-likes, but a list of the more common ones is given below.
-
-Usually completion will be tried by all possible tags in an order given
+Usually completion will be tried for all possible tags in an order given
 by the completion function.  However, this can be altered by using the
 tt(tag-order) style.  Completion is then restricted to the list of given
 tags in the given order.
@@ -591,7 +665,7 @@
 ifnzman(noderef(Completion Widgets)))\
 ).  For example,
 
-example(tt(ztyle -e ':completion:*' hosts 'reply=($myhosts)'))
+example(tt(zstyle -e ':completion:*' hosts 'reply=($myhosts)'))
 
 This forces the value of the tt(hosts) style to be read from the
 variable tt(myhosts) each time a host name is needed; this is useful
Index: Doc/Zsh/compwid.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/compwid.yo,v
retrieving revision 1.38
diff -u -r1.38 compwid.yo
--- Doc/Zsh/compwid.yo	7 Mar 2006 12:52:28 -0000	1.38
+++ Doc/Zsh/compwid.yo	20 Sep 2006 21:50:59 -0000
@@ -11,9 +11,9 @@
 ifzman(zmanref(zshcompsys))\
 ifnzman(the next chapter, noderef(Completion System)),
 and users with no interest in adding to that system (or, potentially,
-writing their own DASH()- see dictionary entry for `hubris') should skip this
-section.  The older system based on the tt(compctl) builtin command is
-described in
+writing their own DASH()- see dictionary entry for `hubris') should skip
+the current section.  The older system based on the tt(compctl) builtin
+command is described in
 ifzman(zmanref(zshcompctl))\
 ifnzman(noderef(Completion Using compctl)).
 
Index: Doc/Zsh/roadmap.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/roadmap.yo,v
retrieving revision 1.7
diff -u -r1.7 roadmap.yo
--- Doc/Zsh/roadmap.yo	15 Feb 2006 09:43:38 -0000	1.7
+++ Doc/Zsh/roadmap.yo	20 Sep 2006 21:50:59 -0000
@@ -40,14 +40,33 @@
 tt(HISTSIZE) and tt(SAVEHIST) in ifzman(zmanref(zshparam))\
 ifnzman(noderef(Parameters Used By The Shell)).
 
-The line editor provides an extensive completion system and the shell
-is supplied with completions for many commonly used commands.  Note
-that the new completion system referred to as tt(compsys) is preferred
-over the older tt(compctl) system.  The completion system must be enabled
-explicitly when the shell starts.  For more information see
+subsect(Completion)
+
+Completion is a feature present in many shells. It allows the user to
+type only a part (usually the prefix) of a word and have the shell fill
+in the rest.  The completion system in zsh is programmable.  For
+example, the shell can be set to complete email addresses in
+arguments to the mail command from your tt(~/.abook/addressbook);
+usernames, hostnames, and even remote paths in arguments to scp, and so
+on.  Anything that can be written in or glued together with zsh can be
+the source of what the line editor offers as possible completions.
+
+Zsh has two completion systems, an old, so called tt(compctl) completion
+(named after the builtin command that serves as its complete and only
+user interface), and a new one, referred to as tt(compsys),
+organized as library of builtin and user-defined functions.
+The two systems differ in their interface for specifying the completion
+behavior.  The new system is more customizable and is supplied with
+completions for many commonly used commands; it is therefore to be
+preferred.
+
+The completion system must be enabled explicitly when the shell starts.
+For more information see
 ifzman(zmanref(zshcompsys))\
 ifnzman(noderef(Completion System)).
 
+subsect(Extending the line editor)
+
 Apart from completion, the line editor is highly extensible by means of
 shell functions.  Some useful functions are provided with the shell; they
 provide facilities such as:

-- 
Peter Stephenson <p.w.stephenson@xxxxxxxxxxxx>
Web page now at http://homepage.ntlworld.com/p.w.stephenson/