PATCH: 3.1.6-dev-20: Misc. doc stuff

["Bart Schaefer" <schaefer@xxxxxxxxxxxxxxxxxxxxxxx>]

This is against -dev-20, which means it almost certainly conflicts with
the big alternate-set patch in 10230, but only in one spot in compwid.yo.

* Fix yodl endlist() macro to force a blank line after the last list
  item in texi translations.  Also catch one spot where endlist() was
  used incorrectly to close a startitem().
* Clean up a few more occurrences of "wordcode".
* Fix some typographical errors.
* Enter the compstate keys into the variables index for quick lookup.
* Note that :x doesn't work on parameters.
* Make a concept index entry for `ZLE'.

I intended to do some similar things in compsys.yo, particularly with
respect to adding index entries for various magic words, but didn't yet.

Index: Doc/ztexi.yo
===================================================================
@@ -180,6 +180,7 @@
   startitem()\
 )
 def(endlist)(0)(\
+  NOTRANS(@item)NL()\
   enditem()\
 )
 def(list)(1)(\
Index: Doc/Zsh/builtins.yo
===================================================================
@@ -93,8 +93,9 @@
 when no definition was found.  In the latter case the function remains
 undefined and marked for autoloading.
 
-With the tt(-w) flag, the var(name)s are taken as names of wordcode
-files and all functions defined in them are marked for autoloading.
+With the tt(-w) flag, the var(name)s are taken as names of files compiled
+with the tt(zcompile) builtin, and all functions defined in them are
+marked for autoloading.
 )
 findex(bg)
 cindex(jobs, backgrounding)
@@ -1291,7 +1292,7 @@
 Equivalent to tt(whence -c).
 )
 findex(zcompile)
-cindex(wordcode, creation)
+cindex(.zwc files, creation)
 cindex(compilation)
 xitem(tt(zcompile) [ tt(-U) ] [ tt(-z) | tt(-k) ] [ tt(-r) | tt(-m) ] var(file) [ var(name) ... ])
 xitem(tt(zcompile) tt(-c) [ tt(-M) ] [ tt(-z) | tt(-k) ] [ tt(-r) | tt(-m) ] var(file) [ var(name) ... ])
@@ -1394,13 +1395,13 @@
 xitem(tt(zmodload -e) [ ... ])
 xitem(tt(zmodload) [ tt(-a) [ tt(-bcpf) [ tt(-I) ] ] ] [ tt(-iL) ] ...)
 item(tt(zmodload) tt(-u) [ tt(-abcdpf) [ tt(-I) ] ] [ tt(-iL) ] ...)(
-tt(zmodload) performs operations relating to zsh's loadable modules.
+Performs operations relating to zsh's loadable modules.
 This feature is not available on all operating systems,
 or on all installations on a particular operating system.
 
-Without arguments all currently loaded binary modules are printed.
-The tt(-L) option causes this list to be in the form of a series of
-tt(zmodload) commands.  Forms with arguments are:
+Without arguments the names of all currently loaded binary modules are
+printed.  The tt(-L) option causes this list to be in the form of a
+series of tt(zmodload) commands.  Forms with arguments are:
 
 startitem()
 xitem(tt(zmodload) [ tt(-i) ] var(name) ... )
@@ -1484,7 +1485,7 @@
 xitem(tt(zmodload) tt(-af) [ tt(-L) ])
 xitem(tt(zmodload) tt(-af) [ tt(-i) ] var(name) [ var(function) ... ])
 item(tt(zmodload) tt(-uf) [ tt(-i) ] var(function) ...)(
-The tt(-p) option is like the tt(-b), tt(-p), and tt(-c) options, but
+The tt(-f) option is like the tt(-b), tt(-p), and tt(-c) options, but
 makes tt(zmodload) work on autoloaded math functions instead. 
 )
 xitem(tt(zmodload) tt(-a) [ tt(-L) ])
@@ -1493,7 +1494,7 @@
 Equivalent to tt(-ab) and tt(-ub).
 )
 item(tt(zmodload -e) [ var(string) ... ])(
-The tt(-e) option without arguments lists all loaded modules loaded.
+The tt(-e) option without arguments lists all loaded modules.
 With arguments only the return status is set to zero
 if all var(string)s given as arguments are names of loaded modules
 and to one if at least on var(string) is not the name of a
@@ -1502,11 +1503,11 @@
 )
 enditem()
 
-Note that tt(zsh) makes no difference between modules that were linked 
+Note that tt(zsh) makes no distinction between modules that were linked 
 into the shell and modules that are loaded dynamically. In both cases
 this builtin command has to be used to make available the builtins and
 other things defined by modules (unless the module is autoloaded on
-these definitions). This is even true for systems that don't support
+these definitions). This is true even for systems that don't support
 dynamic loading of modules.
 )
 enditem()
Index: Doc/Zsh/compctl.yo
===================================================================
@@ -123,7 +123,7 @@
 in an abbreviated form;  with a list of var(options), all completions
 with those flags set (not counting extended completion) are listed.
 )
-endlist()
+enditem()
 
 If the tt(PLUS()) flag is alone and followed immediately by the var(command)
 list, the completion behavior for all the commands in the list is reset to
Index: Doc/Zsh/compwid.yo
===================================================================
@@ -118,6 +118,7 @@
 The keys are:
 
 startitem()
+vindex(context, compstate)
 item(tt(context))(
 This will be set by the completion code to the overall context
 in which completion is attempted. Possible values are:
@@ -159,31 +160,37 @@
 )
 enditem()
 )
+vindex(vared, compstate)
 item(tt(vared))(
 If completion is called while editing a line using the tt(vared)
 builtin, the value of this key is set to the name of the parameter
 given as argument to tt(vared). If tt(vared) is not currently used,
 this key is unset.
 )
+vindex(parameter, compstate)
 item(tt(parameter))(
 The name of the parameter when completing in a subscript or in the
 value of a parameter assignment.
 )
+vindex(redirect, compstate)
 item(tt(redirect))(
 The redirection operator when completing in a redirection position,
 i.e. one of tt(<), tt(>), etc.
 )
+vindex(quoting, compstate)
 item(tt(quoting))(
 When completing inside single quotes, this is set to the string
 tt(single); inside double quotes, the string
 tt(double); inside backticks, the string tt(backtick).
 Otherwise it is unset.
 )
+vindex(quote, compstate)
 item(tt(quote))(
 When completing inside quotes, this contains the quotation character
 (i.e. either a single quote, a double quote, or a backtick).  Otherwise it
 is unset.
 )
+vindex(all_quotes, compstate)
 item(tt(all_quotes))(
 The tt(-q) option of the tt(compset) builtin command (see below)
 allows breaking a quoted string into separate words and completing one 
@@ -195,18 +202,21 @@
 character in the value always corresponds to the innermost quoting
 level.
 )
+vindex(nmatches, compstate)
 item(tt(nmatches))(
 The number of matches generated and accepted by the completion code so
 far, excluding those matches that are only accepted by ignoring the
 tt(fignore) parameter and the tt(-a) option of the tt(compadd) builtin 
 command.
 )
+vindex(alternate_nmatches, compstate)
 item(tt(alternate_nmatches))(
 Like tt(nmatches), but counts only matches in the alternate set. I.e. file
 names with one of the suffixes from the tt(fignore) array and matches
 put into the alternate set using the tt(-a) option of the tt(compadd)
 builtin command (see below) are not counted.
 )
+vindex(restore, compstate)
 item(tt(restore))(
 This is set to tt(auto) before a function is entered, which forces the
 special parameters mentioned above (tt(words), tt(CURRENT), tt(PREFIX),
@@ -214,6 +224,7 @@
 previous values when the function exits.   If a function unsets it or
 sets it to any other string, they will not be restored.
 )
+vindex(list, compstate)
 item(tt(list))(
 This controls whether or how the list of matches will be displayed.  If it
 is unset or empty they will never be listed; if its value begins with
@@ -236,11 +247,13 @@
 appropriately on entry to a completion widget and may be changed
 there.
 )
+vindex(list_max, compstate)
 item(tt(list_max))(
 Initially this is set to the value of the tt(LISTMAX) parameter.
 It may be set to any other numeric value; when the widget exits this value
 will be used in the same way as the value of tt(LISTMAX).
 )
+vindex(list_lines, compstate)
 item(tt(list_lines))(
 This gives the number of lines that are needed to display the full
 list of completions. Note that to calculate the total number of lines
@@ -248,12 +261,14 @@
 line to this value, this is available as the value of the tt(BLINES)
 special parameter.
 )
+vindex(last_prompt, compstate)
 item(tt(last_prompt))(
 If this is set to an non-empty string for every match added, the
 completion code will move the cursor back to the previous prompt after
 the list of completions has been displayed.  Initially this is set or
 unset according to the tt(ALWAYS_LAST_PROMPT) option.
 )
+vindex(insert, compstate)
 item(tt(insert))(
 This controls the manner in which a match is inserted into the command
 line.  On entry to the widget function, if it is unset the command line is
@@ -281,6 +296,7 @@
 It may also be set to tt(all), which makes all matches generated be
 inserted into the line.
 )
+vindex(to_end, compstate)
 item(tt(to_end))(
 Specifies the occasions on which the cursor is moved to the end of a string
 when a match is inserted.  On entry to a widget function, it may be
@@ -294,6 +310,7 @@
 be moved to the end of the string always or never respectively.  Any
 other string is treated as tt(match).
 )
+vindex(old_list, compstate)
 item(tt(old_list))(
 This is set to tt(yes) if there is still a valid list of completions
 from a previous completion at the time the widget is invoked.  This will
@@ -307,6 +324,7 @@
 to use this old list.  If the widget generated new matches, they will
 not be used.
 )
+vindex(old_insert, compstate)
 item(tt(old_insert))(
 On entry to the widget this will be set to the number of the match of
 an old list of completions that is currently inserted into the command
@@ -318,14 +336,17 @@
 the value of the tt(insert) key specifies that another match should be
 inserted, this will be inserted after the old one.
 )
+vindex(exact, compstate)
 item(tt(exact))(
 Controls the behaviour when the tt(REC_EXACT) option is set.  It will be
 set to tt(accept) if an exact match would be accepted, and will be unset
 otherwise.
 )
+vindex(exact_string, compstate)
 item(tt(exact_string))(
 The string of an exact match if one was found, otherwise unset.
 )
+vindex(pattern_match, compstate)
 item(tt(pattern_match))(
 Locally controls the behaviour given by the tt(GLOB_COMPLETE) option.
 Initially it is set to `tt(*)' if and only if the option is set.
@@ -339,6 +360,7 @@
 builtin commands adding matches are not used if this is set to a
 non-empty string.
 )
+vindex(pattern_insert, compstate)
 item(tt(pattern_insert))(
 Normally this is set to tt(menu), which specifies that menu-completion will
 be used whenever the matches were generated using pattern matching. If it
@@ -346,10 +368,12 @@
 not selected by other option settings, the code will insert an
 unambiguous string for the generated matches as with normal completion.
 )
+vindex(unambiguous, compstate)
 item(tt(unambiguous))(
 This key is read-only and will always be set to the unambiguous string
 the completion code has generated for all matches added so far.
 )
+vindex(unambiguous_cursor, compstate)
 item(tt(unambiguous_cursor))(
 This gives the position the cursor would be placed at if the
 unambiguous string in the tt(unambiguous) key were inserted, relative to
Index: Doc/Zsh/expn.yo
===================================================================
@@ -162,15 +162,16 @@
 )
 item(tt(q))(
 Quote the substituted words, escaping further substitutions.  Works
-with history expansion and parameter expansion, though in the second
-case it is only useful if the resulting text is to be re-evaluated
-such as by tt(eval).
+with history expansion and parameter expansion, though for parameters
+it is only useful if the resulting text is to be re-evaluated such as
+by tt(eval).
 )
 item(tt(Q))(
 Remove one level of quotes from the substituted words.
 )
 item(tt(x))(
-Like tt(q), but break into words at each blank.
+Like tt(q), but break into words at each blank.  Does not work with
+parameter expansion.
 )
 item(tt(l))(
 Convert the words to all lowercase.
Index: Doc/Zsh/filelist.yo
===================================================================
@@ -11,5 +11,5 @@
 list(tt(/etc/zprofile))
 list(tt(/etc/zshrc))
 list(tt(/etc/zlogin))
-list(tt(/etc/zlogout)   (installation-specific - tt(/etc) is the default))
+list(tt(/etc/zlogout)    (installation-specific - tt(/etc) is the default))
 endlist()
Index: Doc/Zsh/files.yo
===================================================================
@@ -47,12 +47,12 @@
 ifnzman(includefile(Zsh/filelist.yo))

 
 Any of these files may be pre-compiled with the tt(zcompile) builtin
-command (
+command (\
 ifzman(\
-see zmanref(zshbuiltins)
+see zmanref(zshbuiltins)\
 )\
 ifnzman(\
-noderef(Shell Builtin Commands)
+noderef(Shell Builtin Commands)\
 )\
 ).  If a compiled file exists (named for the original file plus the
 tt(.zwc) extension) and it is newer than the original file, the compiled
Index: Doc/Zsh/redirect.yo
===================================================================
@@ -208,7 +208,7 @@
 set, an error is caused.  This is the bf(csh) behavior and tt(CSH_NULLCMD)
 is set by default when emulating bf(csh).
 
-If the option (SH_NULLCMD) is set, the builtin tt(`:') is inserted as a
+If the option tt(SH_NULLCMD) is set, the builtin `tt(:)' is inserted as a
 command with the given redirections.  This is the default when emulating
 bf(sh) or bf(ksh).
 
Index: Doc/Zsh/zle.yo
===================================================================
@@ -2,6 +2,7 @@
 chapter(Zsh Line Editor)
 cindex(line editor)
 cindex(editor, line)
+cindex(ZLE)
 sect(Description)
 pindex(ZLE, use of)
 If the tt(ZLE) option is set (which it is by default in interactive shells)

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