PATCH: Document REPLY/reply, misc. other parameter indexing

["Bart Schaefer" <schaefer@xxxxxxxxxxxxxxxxxxxxxxx>]

I noticed that the REPLY documentation was out of place in the section on
the read builtin (it applies to any read, not just -l/-c) and in the course
of fixing that I noticed that REPLY wasn't in the variables index.  That in
turn caused me to notice that PROMPT et al. were out of alphabetical order,
probably so they'd show up after PS1 -- but what's psvar doing in the middle
between PROMPT4 and prompt?  So I just alphabetized them.

Finally, I thought that some of the variables passed around heavily by name
in the completion system deserved at least some mention in the index.  There
are probably others that I didn't catch.

I wish I could figure out when the docs are intended to use `tt(foo)' and
when just tt(foo) without the ticks.  (The difficulty is that in info the
typewriter face is lost and you can't see the emphasis without the `...'.)
I chose to make nearby paragraphs consistent with each other, even if things
aren't consistent across more widely separated uses.

Index: Doc/Zsh/builtins.yo
===================================================================
@@ -752,11 +752,15 @@
 vindex(IFS, use of)
 item(tt(read) [ tt(-rzpqAclneEt) ] [ tt(-k) [ var(num) ] ] \
 [ tt(-u)var(n) ] [ var(name)[tt(?)var(prompt)] ] [ var(name) ...  ])(
+vindex(REPLY, use of)
+vindex(reply, use of)
 Read one line and break it into fields using the characters
 in tt($IFS) as separators, except as noted below.
 The first field is assigned to the first var(name), the second field
 to the second var(name), etc., with leftover
 fields assigned to the last var(name).
+If var(name) is omitted then
+tt(REPLY) is used for scalars and tt(reply) for arrays.
 
 startitem()
 item(tt(-r))(
@@ -805,8 +809,7 @@
 tt(compctl)).  If the tt(-c) flag is given, the words of the
 current command are read. If the tt(-l) flag is given, the whole
 line is assigned as a scalar.  If both flags are present, tt(-l)
-is used and tt(-c) is ignored.  If var(name) is omitted then
-tt(REPLY) is used for scalars and tt(reply) for arrays.
+is used and tt(-c) is ignored.
 )
 item(tt(-n))(
 Together with tt(-c), the number of the word the cursor is on is
Index: Doc/Zsh/compctl.yo
===================================================================
@@ -305,6 +305,7 @@
 resulting files.  Note that tt(-g) is faster for filenames.
 )
 item(tt(-K) var(function))(
+vindex(reply, use of)
 Call the given function to get the completions.  Unless the name
 starts with an underscore, the function is
 passed two arguments: the prefix and the suffix of the word on which
@@ -431,6 +432,7 @@
 set and this flag is used.
 )
 item(tt(-y) var(func-or-var))(
+vindex(reply, use of)
 The list provided by var(func-or-var) is displayed instead of the list
 of completions whenever a listing is required; the actual completions
 to be inserted are not affected.  It can be provided in two
@@ -441,7 +443,7 @@
 name of a function which will be executed to create the list.  The
 function will be passed as an argument list all matching completions,
 including prefixes and suffixes expanded in full, and should set the
-array var(reply) to the result.  In both cases, the display list will
+array tt(reply) to the result.  In both cases, the display list will
 only be retrieved after a complete list of matches has been created.
 
 Note that the returned list does not have to correspond, even in
Index: Doc/Zsh/compsys.yo
===================================================================
@@ -2963,6 +2963,9 @@
 The matches will be listed together with their descriptions if the
 tt(description) style for the tt(values) tag is set.
 
+vindex(context, use of)
+vindex(line, use of)
+vindex(opt_args, use of)
 An var(action) of the form `tt(->)var(string)' is used by functions
 that implement a state machine. In this case, the `var(string)'s (with
 all leading and trailing spaces and tabs removed) of all actions that
@@ -2983,6 +2986,7 @@
 This will ensure that tt(_arguments) does not create unused global
 parameters.
 
+vindex(expl, use of)
 A string in braces is evaluated to generate the matches and if the
 var(action) does not begin with an opening parentheses or brace, it
 is also split into separate words and executed. If the var(action)
@@ -2991,7 +2995,7 @@
 first word which can be given as arguments to the tt(compadd) builtin
 command and which make sure that the var(message) given
 in the description will be shown above the matches. These arguments
-are taken from the array parameter tt(expl) which will be set up
+are taken from the array parameter `tt(expl)' which will be set up
 before executing the var(action) and hence may be used in it (normally 
 in an expansion like `tt($expl[@])').
 
Index: Doc/Zsh/expn.yo
===================================================================
@@ -1623,6 +1623,8 @@
 matches itself. Note that expansions must be quoted in the var(string)
 to prevent them from being expanded before globbing is done.
 
+vindex(REPLY, use of)
+vindex(reply, use of)
 During the execution of var(string) the filename currently being tested is
 available in the parameter tt(REPLY); the parameter may be altered to
 a string to be inserted into the list instead of the original
Index: Doc/Zsh/grammar.yo
===================================================================
@@ -203,6 +203,7 @@
 cindex(selection, user)
 item(tt(select) var(name) [ tt(in) var(word) ... var(term) ] tt(do) var(list) tt(done))(
 where var(term) is one or more newline or tt(;) to terminate the var(word)s.
+vindex(REPLY, use of)
 Print the set of var(word)s, each preceded by a number.
 If the tt(in) var(word) is omitted, use the positional parameters.
 The tt(PROMPT3) prompt is printed and a line is read from the line editor
Index: Doc/Zsh/mod_zutil.yo
===================================================================
@@ -36,6 +36,7 @@
 
 startitem()
 item(tt(zstyle) [ tt(-) | tt(-)tt(-) | tt(-e) ] var(pattern) var(style) var(strings) ...)(
+vindex(reply, use of)
 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
Index: Doc/Zsh/params.yo
===================================================================
@@ -679,6 +679,21 @@
 This string is output whenever the line editor exits.
 It usually contains termcap strings to reset the terminal.
 )
+vindex(PROMPT)
+xitem(tt(PROMPT) <S> <Z>)
+vindex(PROMPT2)
+xitem(tt(PROMPT2) <S> <Z>)
+vindex(PROMPT3)
+xitem(tt(PROMPT3) <S> <Z>)
+vindex(PROMPT4)
+item(tt(PROMPT4) <S> <Z>)(
+Same as tt(PS1), tt(PS2), tt(PS3) and tt(PS4),
+respectively.
+)
+vindex(prompt)
+item(tt(prompt) <S> <Z>)(
+Same as tt(PS1).
+)
 vindex(PS1)
 item(tt(PS1) <S>)(
 The primary prompt string, printed before a command is read.
@@ -705,17 +720,6 @@
 the name of the current shell structure and the line number within it.
 In sh or ksh emulation, the default is `tt(PLUS() )'.
 )
-vindex(PROMPT)
-xitem(tt(PROMPT) <S> <Z>)
-vindex(PROMPT2)
-xitem(tt(PROMPT2) <S> <Z>)
-vindex(PROMPT3)
-xitem(tt(PROMPT3) <S> <Z>)
-vindex(PROMPT4)
-item(tt(PROMPT4) <S> <Z>)(
-Same as tt(PS1), tt(PS2), tt(PS3) and tt(PS4),
-respectively.
-)
 vindex(psvar)
 vindex(PSVAR)
 item(tt(psvar) <S> <Z> (tt(PSVAR) <S>))(
@@ -723,10 +727,6 @@
 tt(PROMPT) strings.  Setting tt(psvar) also sets tt(PSVAR), and
 vice versa.
 )
-vindex(prompt)
-item(tt(prompt) <S> <Z>)(
-Same as tt(PS1).
-)
 vindex(READNULLCMD)
 item(tt(READNULLCMD) <S>)(
 The command name to assume if a single input redirection
@@ -737,6 +737,19 @@
 If nonnegative, commands whose combined user and system execution times
 (measured in seconds) are greater than this value have timing
 statistics printed for them.
+)
+vindex(REPLY)
+item(tt(REPLY))(
+This parameter is reserved by convention to pass string values between
+shell scripts and shell builtins in situations where a function call or
+redirection are impossible or undesirable.  The tt(read) builtin and the
+tt(select) complex command may set tt(REPLY), and filename generation both
+sets and examines its value when evaluating certain expressions.  Some
+modules also employ tt(REPLY) for similar purposes.
+)
+vindex(reply)
+item(tt(reply))(
+As tt(REPLY), but for array values rather than strings.
 )
 vindex(RPROMPT)
 xitem(tt(RPROMPT) <S>)

-- 
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