1 files changed, 32 insertions, 19 deletions
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index 7d4e6fccb..d44b40a3b 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -319,6 +319,19 @@ forms of expansion.
 Note that if a `tt(&)' is used within glob qualifiers an extra backslash
 is needed as a tt(&) is a special character in this case.
 
+Also note that the order of expansions affects the interpretation of
+var(l) and var(r).  When used in a history expansion, which occurs before
+any other expansions, var(l) and var(r) are treated as literal strings
+(except as explained for tt(HIST_SUBST_PATTERN) below).  When used in
+parameter expansion, the replacement of var(r) into the parameter's value
+is done first, and then any additional process, parameter, command,
+arithmetic, or brace references are applied, which may evaluate those
+substitutions and expansions more than once if var(l) appears more than
+once in the starting value.  When used in a glob qualifier, any
+substitutions or expansions are performed once at the time the qualifier
+is parsed, even before the `tt(:s)' expression itself is divided into
+var(l) and var(r) sides.
+
 If the option tt(HIST_SUBST_PATTERN) is set, var(l) is treated as
 a pattern of the usual form described in
 ifzman(the section FILENAME GENERATION below)\
@@ -917,6 +930,25 @@ array index order.  Note that `tt(a)' is therefore equivalent to the
 default but `tt(Oa)' is useful for obtaining an array's elements in reverse
 order.
 )
+item(tt(b))(
+Quote with backslashes only characters that are special to pattern
+matching. This is useful when the contents of the variable are to be
+tested using tt(GLOB_SUBST), including the tt(${~)var(...)tt(}) switch.
+
+Quoting using one of the tt(q) family of flags does not work
+for this purpose since quotes are not stripped from non-pattern
+characters by tt(GLOB_SUBST).  In other words,
+
+example(pattern=${(q)str}
+[[ $str = ${~pattern} ]])
+
+works if tt($str) is `tt(a*b)' but not if it is `tt(a b)', whereas
+
+example(pattern=${(b)str}
+[[ $str = ${~pattern} ]])
+
+is always true for any possible value of tt($str).
+)
 item(tt(c))(
 With tt(${#)var(name)tt(}), count the total number of characters in an array,
 as if the elements were concatenated with spaces between them.  This is not
@@ -1021,25 +1053,6 @@ form of single quoting is used that only quotes the string if needed to
 protect special characters.  Typically this form gives the most readable
 output.
 )
-item(tt(b))(
-Quote with backslashes only characters that are special to pattern
-matching. This is useful when the contents of the variable are to be
-tested using tt(GLOB_SUBST), including the tt(${~)var(...)tt(}) switch.
-
-Quoting using one of the tt(q) family of flags does not work
-for this purpose since quotes are not stripped from non-pattern
-characters by tt(GLOB_SUBST).  In other words,
-
-example(pattern=${(q)str}
-[[ $str = ${~pattern} ]])
-
-works if tt($str) is tt('a*b') but not if it is tt('a b'), whereas
-
-example(pattern=${(b)str}
-[[ $str = ${~pattern} ]])
-
-is always true for any possible value of tt($str).
-)
 item(tt(Q))(
 Remove one level of quotes from the resulting words.
 )