12716: Document and index REPLY/reply paramters properly.

8 files changed, 53 insertions, 19 deletions

diff --git a/ChangeLog b/ChangeLog
index 644e7694a..e18e55bea 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2000-08-28  Bart Schaefer  <schaefer@brasslantern.com>
+
+	* 12716: Doc/Zsh/builtins.yo, Doc/Zsh/compctl.yo,
+	Doc/Zsh/compsys.yo, Doc/Zsh/expn.yo, Doc/Zsh/grammar.yo,
+	Doc/Zsh/mod_zutil.yo, Doc/Zsh/params.yo: Documentation and index
+	entries for the REPLY and reply parameters, plus index entries for
+	a couple of paramters used by the completion system.
+
 2000-08-28  Sven Wischnowsky  <wischnow@zsh.org>
 
 	* 12710: Src/exec.c: fix for `function' without names
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index 3f9aa398f..f11b2e981 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -752,11 +752,15 @@ findex(read)
 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 @@ function used for completion (specified with the tt(-K) flag to
 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
diff --git a/Doc/Zsh/compctl.yo b/Doc/Zsh/compctl.yo
index cee73c897..821916161 100644
--- a/Doc/Zsh/compctl.yo
+++ b/Doc/Zsh/compctl.yo
@@ -305,6 +305,7 @@ completions.  The tt(fignore) special parameter is not applied to the
 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 @@ and suffixes, menucompletion is started immediately if tt(AUTO_MENU) is
 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 @@ call to a function using the tt(-K) option.  Otherwise it contains the
 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
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 65297bf70..e3513ee2c 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -2963,6 +2963,9 @@ example(tt(:foo:LPAR()LPAR()a\:bar b\:baz)tt(RPAR()RPAR()))
 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 @@ typeset -A opt_args)
 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 @@ otherwise it will be invoked with some extra strings placed after the
 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[@])').
 
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index 17e2d9bb1..91b78b7fd 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -1623,6 +1623,8 @@ will be taken  as the var(string); `tt([)', `tt({)', and `tt(<)' match
 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
diff --git a/Doc/Zsh/grammar.yo b/Doc/Zsh/grammar.yo
index d5282d22e..df5bb8581 100644
--- a/Doc/Zsh/grammar.yo
+++ b/Doc/Zsh/grammar.yo
@@ -203,6 +203,7 @@ cindex(user selection)
 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
diff --git a/Doc/Zsh/mod_zutil.yo b/Doc/Zsh/mod_zutil.yo
index 3fca82e07..e22197ea2 100644
--- a/Doc/Zsh/mod_zutil.yo
+++ b/Doc/Zsh/mod_zutil.yo
@@ -36,6 +36,7 @@ done in the form of calls to tt(zstyle).  Forms with arguments:
 
 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
diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index 0ba4b37b2..c3e8c4679 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -679,6 +679,21 @@ item(tt(POSTEDIT) <S>)(
 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 execution trace prompt.  Default is `tt(PLUS()%N:%i> )', which displays
 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 @@ An array (colon-separated list) whose first nine values can be used in
 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
@@ -738,6 +738,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>)
 vindex(RPS1)