Merge of 22076, 22165, 22360, and 22365.

Doc/Zsh/expn.yo

@@ -444,6 +444,7 @@ element of var(name) is substituted, one element per word.  Otherwise, the
 expansion results in one word only; with tt(KSH_ARRAYS), this is the first
 element of an array.  No field splitting is done on the result unless the
 tt(SH_WORD_SPLIT) option is set.
+See also the flags tt(=) and tt(s:)var(string)tt(:).
 )
 item(tt(${PLUS())var(name)tt(}))(
 If var(name) is the name of a set parameter `tt(1)' is substituted,
@@ -453,6 +454,9 @@ item(tt(${)var(name)tt(:-)var(word)tt(}))(
 If var(name) is set and is non-null then substitute its
 value; otherwise substitute var(word). If var(name) is
 missing, substitute var(word).
+Note that you can use standard shell quoting in the var(word) value to
+selectively override the splitting done by the tt(SH_WORD_SPLIT) option
+and the tt(=) flag, but not the tt(s:)var(string)tt(:) flag.
 )
 xitem(tt(${)var(name)tt(:=)var(word)tt(}))
 item(tt(${)var(name)tt(::=)var(word)tt(}))(
@@ -470,6 +474,9 @@ If var(word) is omitted, then a standard message is printed.
 item(tt(${)var(name)tt(:PLUS())var(word)tt(}))(
 If var(name) is set and is non-null then substitute
 var(word); otherwise substitute nothing.
+Note that you can use standard shell quoting in the var(word) value to
+selectively override the splitting done by the tt(SH_WORD_SPLIT) option
+and the tt(=) flag, but not the tt(s:)var(string)tt(:) flag.
 )
 enditem()
 
@@ -835,8 +842,8 @@ in string arguments to any of the flags described below.
 item(tt(j:)var(string)tt(:))(
 Join the words of arrays together using var(string) as a separator.
 pindex(SH_WORD_SPLIT, use of)
-Note that this occurs before field splitting by the tt(SH_WORD_SPLIT)
-option.
+Note that this occurs before field splitting by the tt(s:)var(string)tt(:)
+flag or the tt(SH_WORD_SPLIT) option.
 )
 item(tt(l:)var(expr)tt(::)var(string1)tt(::)var(string2)tt(:))(
 Pad the resulting words on the left.  Each word will be truncated if
@@ -851,10 +858,11 @@ As tt(l), but pad the words on the right and insert var(string2)
 on the right.
 )
 item(tt(s:)var(string)tt(:))(
-Force field splitting (see the option tt(SH_WORD_SPLIT)) at the
+Force field splitting at the
 separator var(string).  Note that a var(string) of two or more
-characters means all must all match in sequence; this differs from
+characters means that all of them must match in sequence; this differs from
 the treatment of two or more characters in the tt(IFS) parameter.
+See also the tt(=) flag and the tt(SH_WORD_SPLIT) option.
 )
 enditem()
 
@@ -1309,7 +1317,7 @@ tt(IFS) parameter
 item(tt([:IFSSPACE:]))(
 The character is an IFS white space character; see the documentation
 for tt(IFS) in
-ifzman(the zmanref(zshparams) manual page)\
+ifzman(the zmanref(zshparam) manual page)\
 ifnzman(noderef(Parameters Used By The Shell))\
 .
 )
@@ -1499,7 +1507,8 @@ parentheses may be nested.  There are special rules for parentheses followed
 by `tt(#)' or `tt(##)'.  Only the last match of the parenthesis is
 remembered: for example, in `tt([[ abab = (#b)([ab])# ]])', only the final
 `tt(b)' is stored in tt(match[1]).  Thus extra parentheses may be necessary
-to match the complete segment: for example, use `tt(X((ab|cd)#)Y)' to match
+to match the complete segment: for example, use
+`tt(X+LPAR()(ab|cd)#+RPAR()Y)' to match
 a whole string of either `tt(ab)' or `tt(cd)' between `tt(X)' and `tt(Y)',
 using the value of tt($match[1]) rather than tt($match[2]).
 
@@ -1553,12 +1562,13 @@ The `tt((#s))' flag succeeds only at the start of the test string, and the
 correspond to `tt(^)' and `tt($)' in standard regular expressions.  They
 are useful for matching path segments in patterns other than those in
 filename generation (where path segments are in any case treated
-separately).  For example, `tt(*((#s)|/)test((#e)|/)*)' matches a path
-segment `tt(test)' in any of the following strings: tt(test),
+separately).  For example, `tt(*((#s)|/)test+LPAR()(#e)|/+RPAR()*)' matches
+a path segment `tt(test)' in any of the following strings: tt(test),
 tt(test/at/start), tt(at/end/test), tt(in/test/middle).
 
 Another use is in parameter substitution; for example
-`tt(${array/(#s)A*Z(#e)})' will remove only elements of an array which
+`tt(${array/(#s)A*Z+LPAR()#e+RPAR()})' will remove only elements of an
+array which
 match the complete pattern `tt(A*Z)'.  There are other ways of performing
 many operations of this type, however the combination of the substitution
 operations `tt(/)' and `tt(//)' with the `tt((#s))' and `tt((#e))' flags
@@ -1574,7 +1584,8 @@ item(tt(q))(
 A `tt(q)' and everything up to the closing parenthesis of the globbing
 flags are ignored by the pattern matching code.  This is intended to
 support the use of glob qualifiers, see below.  The result is that
-the pattern `tt((#b)(*).c(#q.))' can be used both for globbing and for
+the pattern `tt((#b)(*).c+LPAR()#q.+RPAR())' can be used both for globbing
+and for
 matching against a string.  In the former case, the `tt((#q.))' will be
 treated as a glob qualifier and the `tt((#b))' will not be useful, while in
 the latter case the `tt((#b))' is useful for backreferences and the
@@ -1654,8 +1665,8 @@ the pattern
 tt(LPAR()#a1)tt(RPAR()cat)tt(LPAR()#a0)tt(RPAR()dog)tt(LPAR()#a1)tt(RPAR()fox)
 is equivalent.  Note that the point at which an error is first found is the
 crucial one for establishing whether to use approximation; for example,
-tt((#a1)abc(#a0)xyz) will not match tt(abcdxyz), because the error occurs
-at the `tt(x)', where approximation is turned off.
+tt((#a1)abc+LPAR()#a0+RPAR()xyz) will not match tt(abcdxyz), because the
+error occurs at the `tt(x)', where approximation is turned off.
 
 Entire path segments may be matched approximately, so that
 `tt((#a1)/foo/d/is/available/at/the/bar)' allows one error in any path
@@ -1863,7 +1874,7 @@ characters following the tt(PLUS()) that are alphanumeric or underscore.
 Typically var(cmd) will be the name of a shell function that contains the
 appropriate test.  For example,
 
-example(nt() { [[ $REPLY -nt $NTREF ]] }
+example(nt+LPAR()RPAR() { [[ $REPLY -nt $NTREF ]] }
 NTREF=reffile
 ls -l *(+nt))
 
@@ -1958,11 +1969,13 @@ they are sorted by the time of the last access, modification, or
 inode change respectively; if tt(d), files in subdirectories appear before
 those in the current directory at each level of the search DASH()- this is best
 combined with other criteria, for example `tt(odon)' to sort on names for
-files within the same directory.  Note that tt(a), tt(m), and tt(c) compare
+files within the same directory; if tt(N), no sorting is performed.
+Note that tt(a), tt(m), and tt(c) compare
 the age against the current time, hence the first name in the list is the
 youngest file. Also note that the modifiers tt(^) and tt(-) are used,
 so `tt(*(^-oL))' gives a list of all files sorted by file size in descending
-order, following any symbolic links.
+order, following any symbolic links.  Unless tt(oN) is used, multiple order
+specifiers may occur to resolve ties.
 )
 item(tt(O)var(c))(
 like `tt(o)', but sorts in descending order; i.e. `tt(*(^oc))' is the
@@ -2022,7 +2035,7 @@ 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).
 
-example(print b*.pro(#q:s/pro/shmo/)(#q.:s/builtin/shmiltin/))
+example(print b*.pro+LPAR()#q:s/pro/shmo/+RPAR()(#q.:s/builtin/shmiltin/))
 
 demonstrates how colon modifiers and other qualifiers may be chained
 together.  The ordinary qualifier `tt(.)' is applied first, then the colon