PATCH: Reorganize and clarify `Expansion' documentation

["Bart Schaefer" <schaefer@xxxxxxxxxxxxxxxx>]

This patch is bigger than the actual wording changes require, because I
moved two entire sections around in expn.yo.  The changes are:

Rearrange sections to match the order in which substitutions occur.  This
also puts the section on history modifiers above the reference to it in
filename generation, which makes more sense, and puts filename expansion
and generation close together.

Rearrange some text in "Parameter Expansion" to clarify it.  Also mention
SH_WORD_SPLIT under ${NAME} (it was only under ${=SPEC} before).

Make "Parameter Expansion Flags" a subsection and add it to the concept
index.

Consistently refer to "history expansion" rather than sometimes "history
substitution."  Fix a couple of other expansion/substitution misuses.

Additional changes in this patch:

Move "Zsh Line Editor" to immediately before "Programmable Completion" so
that "Parameters" is closer to "Parameter Expansion" and to group line
editor chapters together near the end.

Replace "one ore more" (note typo) with "at least one" in a couple of
places in alternate `for' grammars.  Fix a var() that should be tt().

Move a misplaced sentence in "Redirection" and fix a couple of typos; make
mention of READNULLCMD where appropriate.

Index: Doc/zsh.yo
===================================================================
RCS file: /extra/cvsroot/zsh/zsh-3.1/Doc/zsh.yo,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 zsh.yo
--- zsh.yo	1998/06/01 17:08:42	1.1.1.1
+++ zsh.yo	1998/06/14 22:11:35
@@ -59,10 +59,10 @@
 ifnzman(includefile(Zsh/prompt.yo))

 ifnzman(includefile(Zsh/restricted.yo))

 ifnzman(includefile(Zsh/expn.yo))

-ifnzman(includefile(Zsh/zle.yo))

 ifnzman(includefile(Zsh/params.yo))

 ifnzman(includefile(Zsh/options.yo))

 ifnzman(includefile(Zsh/builtins.yo))

+ifnzman(includefile(Zsh/zle.yo))

 ifnzman(includefile(Zsh/compctl.yo))

 ifnzman(includefile(Zsh/modules.yo))

 ifzshall(\
Index: Doc/Zsh/builtins.yo
===================================================================
RCS file: /extra/cvsroot/zsh/zsh-3.1/Doc/Zsh/builtins.yo,v
retrieving revision 1.2
diff -u -r1.2 builtins.yo
--- builtins.yo	1998/06/14 05:24:26	1.2
+++ builtins.yo	1998/06/14 22:14:00
@@ -1,4 +1,4 @@
-texinode(Shell Builtin Commands)(Programmable Completion)(Options)(Top)
+texinode(Shell Builtin Commands)(Zsh Line Editor)(Options)(Top)
 chapter(Shell Builtin Commands)
 ifzman(\
 sect(Shell Builtin Commands)
Index: Doc/Zsh/compctl.yo
===================================================================
RCS file: /extra/cvsroot/zsh/zsh-3.1/Doc/Zsh/compctl.yo,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 compctl.yo
--- compctl.yo	1998/06/01 17:08:42	1.1.1.1
+++ compctl.yo	1998/06/14 22:07:13
@@ -1,4 +1,4 @@
-texinode(Programmable Completion)(Zsh Modules)(Shell Builtin Commands)(Top)
+texinode(Programmable Completion)(Zsh Modules)(Zsh Line Editor)(Top)
 chapter(Programmable Completion)
 cindex(completion, programmable)
 cindex(completion, controlling)
Index: Doc/Zsh/expn.yo
===================================================================
RCS file: /extra/cvsroot/zsh/zsh-3.1/Doc/Zsh/expn.yo,v
retrieving revision 1.2
diff -u -r1.2 expn.yo
--- expn.yo	1998/06/12 08:28:50	1.2
+++ expn.yo	1998/06/14 22:09:26
@@ -1,4 +1,4 @@
-texinode(Expansion)(Zsh Line Editor)(Restricted Shell)(Top)
+texinode(Expansion)(Parameters)(Restricted Shell)(Top)
 chapter(Expansion)
 cindex(expansion)
 sect(Description)
@@ -32,87 +32,232 @@
 is performed immediately after em(alias substitution),
 preceding the set of five substitutions mentioned above.
 startmenu()
-menu(Filename Expansion)
+menu(History Expansion)
 menu(Process Substitution)
 menu(Parameter Expansion)
 menu(Command Substitution)
 menu(Arithmetic Expansion)
 menu(Brace Expansion)
+menu(Filename Expansion)
 menu(Filename Generation)
-menu(History Expansion)
 endmenu()
-texinode(Filename Expansion)(Process Substitution)()(Expansion)
-sect(Filename Expansion)
-cindex(filename expansion)
-cindex(expansion, filename)
-Each word is checked to see if it begins with an unquoted `tt(~)'.
-If it does, then the word up to a `tt(/)',
-or the end of the word if there is no `tt(/)',
-is checked to see if it can be substituted in one of the ways
-described here.  If so, then the `tt(~)' and the checked portion are
-replaced with the appropriate substitute value.
+texinode(History Expansion)(Process Substitution)()(Expansion)
+sect(History Expansion)
+cindex(history)
+cindex(history expansion)
+cindex(expansion, history)
+History expansion allows you to use words from previous command
+lines in the command line you are typing.  This simplifies spelling
+corrections and the repetition of complicated commands or arguments.
+Command lines are saved in the history list, the size of which
+is controlled by the tt(HISTSIZE)
+vindex(HISTSIZE, use of)
+variable.  The most recent command is retained in any case.
+A history expansion begins with the first character of the
+tt(histchars) parameter which is `tt(!)'
+by default and may occur anywhere on the command line; history
+expansions do not nest.  The `tt(!)' can be escaped with `tt(\)'
+or can be enclosed between a pair of single quotes (tt('')) to suppress
+its special meaning. Double quotes will em(not) work for this.
 
-A `tt(~)' by itself is replaced by the value of tt($HOME).
-A `tt(~)' followed by a `tt(PLUS())' or a `tt(-)' is replaced by the value of
-tt($PWD) or tt($OLDPWD), respectively.
+Input lines containing history expansions are echoed on the
+terminal after being expanded, but before any other
+expansions take place or the command gets executed.
+startmenu()
+menu(Event Designators)
+menu(Word Designators)
+menu(Modifiers)
+endmenu()
+texinode(Event Designators)(Word Designators)()(History Expansion)
+subsect(Event Designators)
+cindex(history event designators)
+cindex(event designators, history)
+An event designator is a reference to a command-line entry in
+the history list.
 
-A `tt(~)' followed by a number is replaced by the directory at that
-position in the directory stack.
-`tt(~0)' is equivalent to `tt(~PLUS())',
-and `tt(~1)' is the top of the stack.
-`tt(~PLUS())' followed by a number is replaced by the directory at that
-position in the directory stack.
-`tt(~PLUS()0)' is equivalent to `tt(~PLUS())',
-and `tt(~PLUS()1)' is the top of the stack.
-`tt(~-)' followed by a number is replaced by the directory that
-many positions from the bottom of the stack.
-`tt(~-0)' is the bottom of the stack.
-pindex(PUSHD_MINUS, use of)
-The tt(PUSHD_MINUS)
-option exchanges the effects of `tt(~PLUS())' and `tt(~-)' where they are
-followed by a number.
+startitem()
+item(tt(!))(
+Start a history expansion, except when followed by a blank, newline,
+`tt(=)' or `tt(LPAR())'.
+)
+item(tt(!!))(
+Refer to the previous command.
+By itself, this expansion
+repeats the previous command.
+)
+item(tt(!)var(n))(
+Refer to command-line var(n).
+)
+item(tt(!-)var(n))(
+Refer to the current command-line minus var(n).
+)
+item(tt(!)var(str))(
+Refer to the most recent command starting with var(str).
+)
+item(tt(!?)var(str)[tt(?)])(
+Refer to the most recent command containing var(str).
+)
+item(tt(!#))(
+Refer to the current command line typed in so far.  The line is
+treated as if it were complete up to and including the word before the
+one with the `tt(!#)' reference.
+)
+item(tt(!{)...tt(}))(
+Insulate a history reference from adjacent characters (if necessary).
+)
+enditem()
+texinode(Word Designators)(Modifiers)(Event Designators)(History Expansion)
+subsect(Word Designators)
+cindex(history word designators)
+cindex(word designators, history)
+A word designator indicates which word or words of a given command line will
+be included in a history reference.  A `tt(:)'
+separates the event specification from the word designator.
+It can be omitted if the word designator begins with a
+`tt(^)', `tt($)', `tt(*)', `tt(-)' or `tt(%)'.
+Word designators include:
 
-cindex(directories, named)
-cindex(named directories)
-A `tt(~)' followed by anything not already covered is looked up as a
-named directory, and replaced by the value of that named directory if found.
-Named directories are typically home directories for users on the system.
-They may also be defined if the text after the `tt(~)' is the name
-of a string shell parameter whose value begins with a `tt(/)'.
-It is also possible to define directory names using the tt(-d) option to the
-tt(hash) builtin.
+startsitem()
+sitem(tt(0))(The first input word (command).)
+sitem(var(n))(The var(n)th argument.)
+sitem(tt(^))(The first argument.  That is, tt(1).)
+sitem(tt($))(The last argument.)
+sitem(tt(%))(The word matched by (the most recent) tt(?)var(str) search.)
+sitem(var(x)tt(-)var(y))(A range of words; var(x) defaults to tt(0).)
+sitem(tt(*))(All the arguments, or a null value if there are none.)
+sitem(var(x)tt(*))(Abbreviates `var(x)tt(-$)'.)
+sitem(var(x)tt(-))(Like `var(x)tt(*)' but omitting word tt($).)
+endsitem()
 
-In certain circumstances (in prompts, for instance), when the shell
-prints a path, the path is checked to see if it has a named
-directory as its prefix.  If so, then the prefix portion
-is replaced with a `tt(~)' followed by the name of the directory.
-The shortest way of referring to the directory is used,
-with ties broken in favour of using a named directory,
-except when the directory is tt(/) itself.
+Note that a `tt(%)' word designator will only work when used as
+`tt(!%)', `tt(!:%)' or `tt(!?)var(str)tt(?:%)',
+and only when used after a tt(!?) expansion.  Anything else will result
+in an error, although the error may not be the most obvious one.
+texinode(Modifiers)()(Word Designators)(History Expansion)
+subsect(Modifiers)
+cindex(modifiers, history)
+cindex(history modifiers)
+After the optional word designator, you can add
+a sequence of one or more of the following modifiers,
+each preceded by a `tt(:)'.  These modifiers also work on the result
+of em(filename generation) and em(parameter expansion), except where
+noted.
 
-If a word begins with an unquoted `tt(=)'
-and the tt(EQUALS) option is set,
-the remainder of the word is taken as the
-name of a command or alias.  If a command
-exists by that name, the word is replaced
-by the full pathname of the command.
-If an alias exists by that name, the word
-is replaced with the text of the alias.
+startitem()
+item(tt(h))(
+Remove a trailing pathname component, leaving the head.
+)
+item(tt(r))(
+Remove a trailing suffix of the form `tt(.)var(xxx)', leaving the basename.
+)
+item(tt(e))(
+Remove all but the suffix.
+)
+item(tt(t))(
+Remove all leading pathname components, leaving the tail.
+)
+item(tt(p))(
+Print the new command but do not execute it.  Only works with history
+expansion.
+)
+item(tt(q))(
+Quote the substituted words, escaping further substitutions.  Only
+works with history expansion.
+)
+item(tt(x))(
+Like tt(q), but break into words at each blank.
+)
+item(tt(l))(
+Convert the words to all lowercase.
+)
+item(tt(u))(
+Convert the words to all uppercase.
+)
+item(tt(f))(
+(This and the following
+tt(F), tt(w) and tt(W) modifier only work with parameter and
+filename expansion.)
+Repeats the immediately (without a colon) following modifier until the
+resulting word doesn't change any more.
+)
+item(tt(F:)var(expr)tt(:))(
+Like tt(f), but repeats only var(n) times if the expression
+var(expr) evaluates to var(n).  Any character can be used instead of
+the `tt(:)', if any of `tt(LPAR())', `tt([)', or `tt({)'
+is used as the opening delimiter
+the second one has to be 'tt(RPAR())', `tt(])', or `tt(})' respectively.
+)
+item(tt(w))(
+Makes the immediately following modifier work on each word in the
+string.
+)
+item(tt(W:)var(sep)tt(:))(
+Like tt(w) but words are considered to be the parts of the string
+that are separated by var(sep). Any character can be used instead of
+the `tt(:)'; opening parentheses are handled specially, see above.
+)
+item(tt(s/)var(l)tt(/)var(r)[tt(/)])(
+Substitute var(r) for var(l) as described below.
+Unless preceded immediately by a tt(g), with no colon between,
+the substitution is done only for the
+first string that matches var(l).  For arrays and filename
+expansion, this applies to each word of the expanded text.
+)
+item(tt(&))(
+Repeat the previous tt(s) substitution.  Like tt(s), may be preceded
+immediately by a tt(g).  In variable expansion the tt(&) must appear
+inside braces, and in filename expansion it must be quoted with a
+backslash.
+)
+enditem()
 
-Filename expansion is performed on the right hand side of a parameter
-assignment, including those appearing after commands of the
-tt(typeset) family.  In this case, the right hand side will be treated
-as a colon-separated list in the manner of the tt(PATH) parameter,
-so that a `tt(~)' or an `tt(=)' following a `tt(:)' is eligible for expansion.
-All such behaviour can be
-disabled by quoting the `tt(~)', the `tt(=)', or the whole expression (but not
-simply the colon); the tt(EQUALS) option is also respected.
+The tt(s/l/r/) substitution works as follows.  The left-hand side of
+substitutions are not regular expressions, but character strings.  Any
+character can be used as the delimiter in place of `tt(/)'.  A
+backslash quotes the delimiter character.  The character `tt(&)', in
+the right-hand-side var(r), is replaced by the text from the
+left-hand-side var(l).  The `tt(&)' can be quoted with a backslash.  A
+null var(l) uses the previous string either from the previous var(l)
+or from the contextual scan string var(s) from `tt(!?)var(s)'.  You can
+omit the rightmost delimiter if a newline immediately follows var(r);
+the rightmost `tt(?)' in a context scan can similarly be omitted.
+Note the same record of the last var(l) and var(r) is maintained
+across all forms of expansion.
 
-If the option tt(MAGIC_EQUAL_SUBST) is set, any unquoted shell
-argument in the form `var(identifier)tt(=)var(expression)' becomes eligible
-for file expansion as described in the previous paragraph.  Quoting the
-first `tt(=)' also inhibits this.
-texinode(Process Substitution)(Parameter Expansion)(Filename Expansion)(Expansion)
+By default, a history reference with no event specification refers to the same
+line as the last history reference on that command line, unless it is the
+first history reference in a command.  In that case, a history reference
+with no event specification always refers to the previous command.  However,
+if the option tt(CSH_JUNKIE_HISTORY) is set,
+pindex(CSH_JUNKIE_HISTORY, use of)
+then history reference with no
+event specification will em(always) refer to the previous command.
+
+For example, `tt(!!:1)'
+will always refer to the first word of the previous command, and `tt(!!$)'
+will always refer to the last word of the previous command.  And with
+tt(CSH_JUNKIE_HISTORY) set, then `tt(!:1)' and `tt(!$)'
+will function in the same manner as `tt(!!:1)' and `tt(!!$)',
+respectively.  However, if tt(CSH_JUNKIE_HISTORY) is unset, then
+`tt(!:1)' and `tt(!$)'
+will refer to the first and last words respectively, of the last command
+referenced on the current command line.  However, if they are the first history
+reference on the command line, then they refer to the previous command.
+
+The character sequence `tt(^)var(foo)tt(^)var(bar)'
+repeats the last command, replacing the string var(foo) with var(bar).
+
+If the shell encounters the character sequence `tt(!")'
+in the input, the history mechanism is temporarily disabled until
+the current list is fully parsed.  The `tt(!")'
+is removed from the input, and any subsequent `tt(!)'
+characters have no special significance.
+
+A less convenient but more comprehensible
+form of command history support
+is provided by the tt(fc) builtin.
+findex(fc, use of)
+texinode(Process Substitution)(Parameter Expansion)(History Expansion)(Expansion)
 sect(Process Substitution)
 cindex(process substitution)
 cindex(substitution, process)
@@ -182,8 +327,9 @@
 
 If var(name) is an array parameter, then the values of each
 element of var(name) is substituted, one element per word.
-Otherwise, the expansion results in one word only; no
-field splitting is done on the result.
+Otherwise, the expansion results in one word only; no field
+splitting is done on the result unless the tt(SH_WORD_SPLIT)
+option is set.
 )
 item(tt(${PLUS())var(name)tt(}))(
 If var(name) is the name of a set parameter `tt(1)' is substituted,
@@ -199,10 +345,6 @@
 set it to var(word); the value of the parameter is then
 substituted.
 )
-item(tt(${)var(name)tt(::=)var(word)tt(}))(
-Set var(name) to var(word); the value of the parameter is then
-substituted.
-)
 item(tt(${)var(name)tt(:?)var(word)tt(}))(
 If var(name) is set and is non-null, then substitute
 its value; otherwise, print var(word) and exit from the shell.
@@ -212,6 +354,17 @@
 If var(name) is set and is non-null then substitute
 var(word); otherwise substitute nothing.
 )
+enditem()
+
+If the colon is omitted from one of the above expressions
+containing a colon, then the shell only checks whether
+var(name) is set or not, not whether it is null.
+
+startitem()
+item(tt(${)var(name)tt(::=)var(word)tt(}))(
+Set var(name) to var(word); the value of the parameter is then
+substituted.
+)
 xitem(tt(${)var(name)tt(#)var(pattern)tt(}))
 item(tt(${)var(name)tt(##)var(pattern)tt(}))(
 If the var(pattern) matches the beginning of the value of
@@ -267,7 +420,7 @@
 Internally, each such expansion is converted into the
 equivalent list for brace expansion.  E.g., tt(${^var}) becomes
 tt({$var[1],$var[2],)...tt(}), and is processed as described in
-noderef(Brace Expansion) below.
+noderef(Brace Expansion) above.
 If word splitting is also in effect the
 tt($var[)var(N)tt(]) may themselves be split into different list
 elements.
@@ -294,15 +447,15 @@
 )
 enditem()
 
-If the colon is omitted from one of the above expressions
-containing a colon, then the shell only checks whether
-var(name) is set or not, not whether it is null.
-
-If a tt(${)...tt(}) type parameter expression or a tt($LPAR())...tt(RPAR())
-type command
-substitution is used in place of var(name) above, it is substituted first
-and the result is used as it were the value of var(name).
-
+If a tt(${)...tt(}) type parameter expression or a
+tt($LPAR())...tt(RPAR()) type command substitution is used in place of
+var(name) above, it is substituted first and the result is used as if
+it were the value of var(name).
+
+subsect(Parameter Expansion Flags)
+cindex(parameter expansion flags)
+cindex(flags, parameter expansion)
+cindex(expansion, parameter, flags)
 If the opening brace is directly followed by an opening parenthesis,
 the string up to the matching closing parenthesis will be taken as a
 list of flags.  Where arguments are valid, any character, or the
@@ -439,7 +592,7 @@
 subjected to em(parameter expansion), em(command substitution)
 and em(arithmetic expansion) before it is evaluated.
 See noderef(Arithmetic Evaluation).
-texinode(Brace Expansion)(Filename Generation)(Arithmetic Expansion)(Expansion)
+texinode(Brace Expansion)(Filename Expansion)(Arithmetic Expansion)(Expansion)
 sect(Brace Expansion)
 cindex(brace expansion)
 cindex(expansion, brace)
@@ -451,22 +604,93 @@
 may be nested.  Commas may be quoted in order to
 include them literally in a word.
 
-An expression of the form `tt({)var(n1)tt(..)var(n2)tt(})',
-where var(n1) and var(n2) are integers,
-is expanded to every number between
-var(n1) and var(n2) inclusive.  If either number begins with a
-zero, all the resulting numbers will be padded with leading zeroes to
-that minimum width.  If the numbers are in decreasing order the
-resulting sequence will also be in decreasing order.
+An expression of the form `tt({)var(n1)tt(..)var(n2)tt(})',
+where var(n1) and var(n2) are integers,
+is expanded to every number between
+var(n1) and var(n2) inclusive.  If either number begins with a
+zero, all the resulting numbers will be padded with leading zeroes to
+that minimum width.  If the numbers are in decreasing order the
+resulting sequence will also be in decreasing order.
+
+If a brace expression matches none of the above forms, it is left
+unchanged, unless the tt(BRACE_CCL) option is set.
+pindex(BRACE_CCL, use of)
+In that case, it is expanded to a sorted list of the individual
+characters between the braces, in the manner of a search set.
+`tt(-)' is treated specially as in a search set, but `tt(^)' or `tt(!)' as
+the first character is treated normally.
+texinode(Filename Expansion)(Filename Generation)(Brace Expansion)(Expansion)
+sect(Filename Expansion)
+cindex(filename expansion)
+cindex(expansion, filename)
+Each word is checked to see if it begins with an unquoted `tt(~)'.
+If it does, then the word up to a `tt(/)',
+or the end of the word if there is no `tt(/)',
+is checked to see if it can be substituted in one of the ways
+described here.  If so, then the `tt(~)' and the checked portion are
+replaced with the appropriate substitute value.
+
+A `tt(~)' by itself is replaced by the value of tt($HOME).
+A `tt(~)' followed by a `tt(PLUS())' or a `tt(-)' is replaced by the value of
+tt($PWD) or tt($OLDPWD), respectively.
+
+A `tt(~)' followed by a number is replaced by the directory at that
+position in the directory stack.
+`tt(~0)' is equivalent to `tt(~PLUS())',
+and `tt(~1)' is the top of the stack.
+`tt(~PLUS())' followed by a number is replaced by the directory at that
+position in the directory stack.
+`tt(~PLUS()0)' is equivalent to `tt(~PLUS())',
+and `tt(~PLUS()1)' is the top of the stack.
+`tt(~-)' followed by a number is replaced by the directory that
+many positions from the bottom of the stack.
+`tt(~-0)' is the bottom of the stack.
+pindex(PUSHD_MINUS, use of)
+The tt(PUSHD_MINUS)
+option exchanges the effects of `tt(~PLUS())' and `tt(~-)' where they are
+followed by a number.
+
+cindex(directories, named)
+cindex(named directories)
+A `tt(~)' followed by anything not already covered is looked up as a
+named directory, and replaced by the value of that named directory if found.
+Named directories are typically home directories for users on the system.
+They may also be defined if the text after the `tt(~)' is the name
+of a string shell parameter whose value begins with a `tt(/)'.
+It is also possible to define directory names using the tt(-d) option to the
+tt(hash) builtin.
+
+In certain circumstances (in prompts, for instance), when the shell
+prints a path, the path is checked to see if it has a named
+directory as its prefix.  If so, then the prefix portion
+is replaced with a `tt(~)' followed by the name of the directory.
+The shortest way of referring to the directory is used,
+with ties broken in favour of using a named directory,
+except when the directory is tt(/) itself.
 
-If a brace expression matches none of the above forms, it is left
-unchanged, unless the tt(BRACE_CCL) option is set.
-pindex(BRACE_CCL, use of)
-In that case, it is expanded to a sorted list of the individual
-characters between the braces, in the manner of a search set.
-`tt(-)' is treated specially as in a search set, but `tt(^)' or `tt(!)' as
-the first character is treated normally.
-texinode(Filename Generation)(History Expansion)(Brace Expansion)(Expansion)
+If a word begins with an unquoted `tt(=)'
+and the tt(EQUALS) option is set,
+the remainder of the word is taken as the
+name of a command or alias.  If a command
+exists by that name, the word is replaced
+by the full pathname of the command.
+If an alias exists by that name, the word
+is replaced with the text of the alias.
+
+Filename expansion is performed on the right hand side of a parameter
+assignment, including those appearing after commands of the
+tt(typeset) family.  In this case, the right hand side will be treated
+as a colon-separated list in the manner of the tt(PATH) parameter,
+so that a `tt(~)' or an `tt(=)' following a `tt(:)' is eligible for expansion.
+All such behaviour can be
+disabled by quoting the `tt(~)', the `tt(=)', or the whole expression (but not
+simply the colon); the tt(EQUALS) option is also respected.
+
+If the option tt(MAGIC_EQUAL_SUBST) is set, any unquoted shell
+argument in the form `var(identifier)tt(=)var(expression)' becomes eligible
+for file expansion as described in the previous paragraph.  Quoting the
+first `tt(=)' also inhibits this.
+texinode(Filename Generation)()(Filename Expansion)(Expansion)
 sect(Filename Generation)
 cindex(filename generation)
 cindex(globbing)
@@ -603,6 +827,7 @@
 
 does a recursive directory search for files named `tt(bar)', not following
 symbolic links.  To follow links, use `tt(***/)'.
+
 subsect(Glob Qualifiers)
 cindex(globbing, qualifiers)
 cindex(qualifiers, globbing)
@@ -798,219 +1023,3 @@
 lists all files having a link count of one whose names contain a dot
 (but not those starting with a dot, since tt(GLOB_DOTS) is explicitly
 switched off) except for tt(lex.c), tt(lex.h), tt(parse.c) and tt(parse.h).
-texinode(History Expansion)()(Filename Generation)(Expansion)
-sect(History Expansion)
-cindex(history)
-cindex(history expansion)
-cindex(expansion, history)
-History substitution allows you to use words from previous command
-lines in the command line you are typing.  This simplifies spelling
-corrections and the repetition of complicated commands or arguments.
-Command lines are saved in the history list, the size of which
-is controlled by the tt(HISTSIZE)
-vindex(HISTSIZE, use of)
-variable.  The most recent command is retained in any case.
-A history substitution begins with the first character of the
-tt(histchars) parameter which is `tt(!)'
-by default and may occur anywhere on the command line; history
-substitutions do not nest.  The `tt(!)' can be escaped with `tt(\)'
-or can be enclosed between a pair of single quotes (tt('')) to suppress
-its special meaning. Double quotes will em(not) work for this.
-
-Input lines containing history substitutions are echoed on the
-terminal after being expanded, but before any other
-substitutions take place or the command gets executed.
-startmenu()
-menu(Event Designators)
-menu(Word Designators)
-menu(Modifiers)
-endmenu()
-texinode(Event Designators)(Word Designators)()(History Expansion)
-subsect(Event Designators)
-cindex(history event designators)
-cindex(event designators, history)
-An event designator is a reference to a command-line entry in
-the history list.
-
-startitem()
-item(tt(!))(
-Start a history substitution, except when followed by a blank, newline,
-`tt(=)' or `tt(LPAR())'.
-)
-item(tt(!!))(
-Refer to the previous command.
-By itself, this substitution
-repeats the previous command.
-)
-item(tt(!)var(n))(
-Refer to command-line var(n).
-)
-item(tt(!-)var(n))(
-Refer to the current command-line minus var(n).
-)
-item(tt(!)var(str))(
-Refer to the most recent command starting with var(str).
-)
-item(tt(!?)var(str)[tt(?)])(
-Refer to the most recent command containing var(str).
-)
-item(tt(!#))(
-Refer to the current command line typed in so far.  The line is
-treated as if it were complete up to and including the word before the
-one with the `tt(!#)' reference.
-)
-item(tt(!{)...tt(}))(
-Insulate a history reference from adjacent characters (if necessary).
-)
-enditem()
-texinode(Word Designators)(Modifiers)(Event Designators)(History Expansion)
-subsect(Word Designators)
-cindex(history word designators)
-cindex(word designators, history)
-A word designator indicates which word or words of a given command line will
-be included in a history reference.  A `tt(:)'
-separates the event specification from the word designator.
-It can be omitted if the word designator begins with a
-`tt(^)', `tt($)', `tt(*)', `tt(-)' or `tt(%)'.
-Word designators include:
-
-startsitem()
-sitem(tt(0))(The first input word (command).)
-sitem(var(n))(The var(n)th argument.)
-sitem(tt(^))(The first argument.  That is, tt(1).)
-sitem(tt($))(The last argument.)
-sitem(tt(%))(The word matched by (the most recent) tt(?)var(str) search.)
-sitem(var(x)tt(-)var(y))(A range of words; var(x) defaults to tt(0).)
-sitem(tt(*))(All the arguments, or a null value if there are none.)
-sitem(var(x)tt(*))(Abbreviates `var(x)tt(-$)'.)
-sitem(var(x)tt(-))(Like `var(x)tt(*)' but omitting word tt($).)
-endsitem()
-
-Note that a `tt(%)' word designator will only work when used as
-`tt(!%)', `tt(!:%)' or `tt(!?)var(str)tt(?:%)',
-and only when used after a tt(!?) substitution.  Anything else will result
-in an error, although the error may not be the most obvious one.
-texinode(Modifiers)()(Word Designators)(History Expansion)
-subsect(Modifiers)
-cindex(modifiers, history)
-cindex(history modifiers)
-After the optional word designator, you can add
-a sequence of one or more of the following modifiers,
-each preceded by a `tt(:)'.  These modifiers also work on the result
-of em(filename generation) and em(parameter expansion), except where
-noted.
-
-startitem()
-item(tt(h))(
-Remove a trailing pathname component, leaving the head.
-)
-item(tt(r))(
-Remove a trailing suffix of the form `tt(.)var(xxx)', leaving the basename.
-)
-item(tt(e))(
-Remove all but the suffix.
-)
-item(tt(t))(
-Remove all leading pathname components, leaving the tail.
-)
-item(tt(p))(
-Print the new command but do not execute it.  Only works with history
-expansion.
-)
-item(tt(q))(
-Quote the substituted words, escaping further substitutions.  Only
-works with history expansion.
-)
-item(tt(x))(
-Like tt(q), but break into words at each blank.
-)
-item(tt(l))(
-Convert the words to all lowercase.
-)
-item(tt(u))(
-Convert the words to all uppercase.
-)
-item(tt(f))(
-(This and the following
-tt(F), tt(w) and tt(W) modifier only work with parameter and
-filename expansion.)
-Repeats the immediately (without a colon) following modifier until the
-resulting word doesn't change any more.
-)
-item(tt(F:)var(expr)tt(:))(
-Like tt(f), but repeats only var(n) times if the expression
-var(expr) evaluates to var(n).  Any character can be used instead of
-the `tt(:)', if any of `tt(LPAR())', `tt([)', or `tt({)'
-is used as the opening delimiter
-the second one has to be 'tt(RPAR())', `tt(])', or `tt(})' respectively.
-)
-item(tt(w))(
-Makes the immediately following modifier work on each word in the
-string.
-)
-item(tt(W:)var(sep)tt(:))(
-Like tt(w) but words are considered to be the parts of the string
-that are separated by var(sep). Any character can be used instead of
-the `tt(:)'; opening parentheses are handled specially, see above.
-)
-item(tt(s/)var(l)tt(/)var(r)[tt(/)])(
-Substitute var(r) for var(l) as described below.
-Unless preceded immediately by a tt(g), with no colon between,
-the substitution is done only for the
-first string that matches var(l).  For arrays and filename
-substitution, this applies to each word of the expanded text.
-)
-item(tt(&))(
-Repeat the previous tt(s) substitution.  Like tt(s), may be preceded
-immediately by a tt(g).  In variable expansion the tt(&) must appear
-inside braces, and in filename expansion it must be quoted with a
-backslash.
-)
-enditem()
-
-The tt(s/l/r/) substitution works as follows.  The left-hand side of
-substitutions are not regular expressions, but character strings.  Any
-character can be used as the delimiter in place of `tt(/)'.  A
-backslash quotes the delimiter character.  The character `tt(&)', in
-the right-hand-side var(r), is replaced by the text from the
-left-hand-side var(l).  The `tt(&)' can be quoted with a backslash.  A
-null var(l) uses the previous string either from the previous var(l)
-or from the contextual scan string var(s) from `tt(!?)var(s)'.  You can
-omit the rightmost delimiter if a newline immediately follows var(r);
-the rightmost `tt(?)' in a context scan can similarly be omitted.
-Note the same record of the last var(l) and var(r) is maintained
-across all forms of expansion.
-
-By default, a history reference with no event specification refers to the same
-line as the last history reference on that command line, unless it is the
-first history reference in a command.  In that case, a history reference
-with no event specification always refers to the previous command.  However,
-if the option tt(CSH_JUNKIE_HISTORY) is set,
-pindex(CSH_JUNKIE_HISTORY, use of)
-then history reference with no
-event specification will em(always) refer to the previous command.
-
-For example, `tt(!!:1)'
-will always refer to the first word of the previous command, and `tt(!!$)'
-will always refer to the last word of the previous command.  And with
-tt(CSH_JUNKIE_HISTORY) set, then `tt(!:1)' and `tt(!$)'
-will function in the same manner as `tt(!!:1)' and `tt(!!$)',
-respectively.  However, if tt(CSH_JUNKIE_HISTORY) is unset, then
-`tt(!:1)' and `tt(!$)'
-will refer to the first and last words respectively, of the last command
-referenced on the current command line.  However, if they are the first history
-reference on the command line, then they refer to the previous command.
-
-The character sequence `tt(^)var(foo)tt(^)var(bar)'
-repeats the last command, replacing the string var(foo) with var(bar).
-
-If the shell encounters the character sequence `tt(!")'
-in the input, the history mechanism is temporarily disabled until
-the current list is fully parsed.  The `tt(!")'
-is removed from the input, and any subsequent `tt(!)'
-characters have no special significance.
-
-A less convenient but more comprehensible
-form of command history support
-is provided by the tt(fc) builtin.
-findex(fc, use of)
Index: Doc/Zsh/grammar.yo
===================================================================
RCS file: /extra/cvsroot/zsh/zsh-3.1/Doc/Zsh/grammar.yo,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 grammar.yo
--- grammar.yo	1998/06/01 17:08:42	1.1.1.1
+++ grammar.yo	1998/06/14 05:33:43
@@ -117,7 +117,7 @@
 cindex(for loops)
 cindex(loops, for)
 item(tt(for) var(name) [ tt(in) var(word) ... var(term) ] tt(do) var(list) tt(done))(
-where var(term) is one ore more newline or tt(;).
+where var(term) is at least one newline or tt(;).
 Expand the list of var(word)s, and set the parameter
 var(name) to each of them in turn, executing
 var(list) each time.  If the tt(in) var(word) is omitted,
@@ -232,13 +232,13 @@
 An alternate form of tt(if).
 )
 item(tt(if) var(list) var(sublist))(
-A short form of previous one.
+A short form of the alternate `if'.
 )
 item(tt(for) var(name) tt(LPAR()) var(word) ... tt(RPAR()) var(sublist))(
 A short form of tt(for).
 )
 item(tt(for) var(name) [ tt(in) var(word) ... var(term) ] var(sublist))(
-where var(term) is one ore more newline or tt(;).
+where var(term) is at least one newline or tt(;).
 Another short form of tt(for).
 )
 item(tt(for LPAR()LPAR()) [var(expr1)] tt(;) [var(expr2)] tt(;) [var(expr3)] tt(RPAR()RPAR()) var(sublist))(
@@ -260,7 +260,7 @@
 An alternative form of tt(case).
 )
 item(tt(select) var(name) [ tt(in) var(word) var(term) ] var(sublist))(
-where var(term) is one ore more newline or var(;).
+where var(term) is at least one newline or tt(;).
 A short form of tt(select).
 )
 enditem()
Index: Doc/Zsh/guide.yo
===================================================================
RCS file: /extra/cvsroot/zsh/zsh-3.1/Doc/Zsh/guide.yo,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 guide.yo
--- guide.yo	1998/06/01 17:08:42	1.1.1.1
+++ guide.yo	1998/06/14 22:17:47
@@ -24,10 +24,10 @@
 menu(Prompt Expansion)
 menu(Restricted Shell)
 menu(Expansion)
-menu(Zsh Line Editor)
 menu(Parameters)
 menu(Options)
 menu(Shell Builtin Commands)
+menu(Zsh Line Editor)
 menu(Programmable Completion)
 menu(Zsh Modules)
 
@@ -64,23 +64,14 @@
 
 Expansion
 
-menu(Filename Expansion)
+menu(History Expansion)
 menu(Process Substitution)
 menu(Parameter Expansion)
 menu(Command Substitution)
 menu(Arithmetic Expansion)
 menu(Brace Expansion)
+menu(Filename Expansion)
 menu(Filename Generation)
-menu(History Expansion)
-
-Zsh Line Editor
-
-menu(Movement)
-menu(History Control)
-menu(Modifying Text)
-menu(Arguments)
-menu(Completion)
-menu(Miscellaneous)
 
 Parameters
 
@@ -94,6 +85,15 @@
 
 menu(Description of Options)
 menu(Single Letter Options)
+
+Zsh Line Editor
+
+menu(Movement)
+menu(History Control)
+menu(Modifying Text)
+menu(Arguments)
+menu(Completion)
+menu(Miscellaneous)
 
 Programmable Completion
 
Index: Doc/Zsh/params.yo
===================================================================
RCS file: /extra/cvsroot/zsh/zsh-3.1/Doc/Zsh/params.yo,v
retrieving revision 1.1.1.1
diff -u -r1.1.1.1 params.yo
--- params.yo	1998/06/01 17:08:43	1.1.1.1
+++ params.yo	1998/06/14 22:09:45
@@ -1,4 +1,4 @@
-texinode(Parameters)(Options)(Zsh Line Editor)(Top)
+texinode(Parameters)(Options)(Expansion)(Top)
 chapter(Parameters)
 cindex(parameters)
 sect(Description)
Index: Doc/Zsh/redirect.yo
===================================================================
RCS file: /extra/cvsroot/zsh/zsh-3.1/Doc/Zsh/redirect.yo,v
retrieving revision 1.2
diff -u -r1.2 redirect.yo
--- redirect.yo	1998/06/12 08:30:24	1.2
+++ redirect.yo	1998/06/14 05:51:14
@@ -141,6 +141,9 @@
 will truncate all files in the current directory,
 assuming there's at least one.  (Without the tt(MULTIOS)
 option, it would create an empty file called `tt(*)'.)
+Similarly, you can do
+
+nofill(tt(echo exit 0 >> *.sh))
 
 If the user tries to open a file descriptor for reading more than once,
 the shell opens the file descriptor as a pipe to a process that copies
@@ -154,11 +157,9 @@
 
 nofill(tt(sort <f{oo,ubar}))
 
-is equivalent to `tt(cat foo fubar | sort)'.  Similarly, you can do
-
-nofill(tt(echo exit 0 >> *.sh))
+is equivalent to `tt(cat foo fubar | sort)'.
 
-Note that a pipe is in implicit redirection; thus
+Note that a pipe is an implicit redirection; thus
 
 nofill(tt(cat bar | sort <foo))
 
@@ -174,7 +175,8 @@
 
 If a simple command consists of one or more redirection operators
 and zero or more parameter assignments, but no command name,
-the command `tt(cat)' is assumed.  Thus
+the command named in the shell variable tt(READNULLCMD) is assumed.
+(If tt(READNULLCMD) is empty or not set, `tt(cat)' is used.)  Thus
 
 nofill(tt(< file))
 
Index: Doc/Zsh/zle.yo
===================================================================
RCS file: /extra/cvsroot/zsh/zsh-3.1/Doc/Zsh/zle.yo,v
retrieving revision 1.2
diff -u -r1.2 zle.yo
--- zle.yo	1998/06/13 04:28:21	1.2
+++ zle.yo	1998/06/14 22:14:49
@@ -1,4 +1,4 @@
-texinode(Zsh Line Editor)(Parameters)(Expansion)(Top)
+texinode(Zsh Line Editor)(Programmable Completion)(Shell Builtin Commands)(Top)
 chapter(Zsh Line Editor)
 cindex(line editor)
 cindex(editor, line)

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