[PATCH] docs: clarify glob-qualifier syntax

[dana <dana@xxxxxxx>]

inspired by someone on github again:

1. they were confused by it saying that bare glob qualifiers can't
   contain '(', when the example for the e qualifier shows exactly that.
   i think just adding 'unquoted' to the rule covers it

2. it took me a minute to realise what it means for a '~' to be
   'special'. afaict it's just the effects of EXTENDED_GLOB

3. i noticed that it doesn't mention you can use (...) for the e/P
   delimiters. assuming that wasn't a deliberate omission

4. in trying to explain that quoting the e/P qualifier arg doesn't
   protect the end delimiter, i was unsure if i should mention that this
   isn't a concern if the delimiter is a meta-character -- i think a
   trick noticed/invented by bart, but i can't find the thread. is it ok
   to make that official?

ps: it seems like the ability to use <...> as the delimiters is broken.
haven't investigated

dana


diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index 70212dbc8..362d21994 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -2800,8 +2800,8 @@ will be inserted in the argument list.
 
 pindex(BARE_GLOB_QUAL, use of)
 If the option tt(BARE_GLOB_QUAL) is set, then a trailing set of parentheses
-containing no `tt(|)' or `tt(LPAR())' characters (or `tt(~)' if it is special)
-is taken as a set of
+containing no unquoted `tt(|)' or `tt(LPAR())' characters (or `tt(~)' if
+it is special due to tt(EXTENDED_GLOB)) is taken as a set of
 glob qualifiers.  A glob subexpression that would normally be taken as glob
 qualifiers, for example `tt((^x))', can be forced to be treated as part of
 the glob pattern by doubling the parentheses, in this case producing
diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo
index bf62241d8..aabd80d08 100644
--- a/Doc/Zsh/options.yo
+++ b/Doc/Zsh/options.yo
@@ -440,7 +440,7 @@ cindex(globbing qualifiers, enable)
 cindex(enable globbing qualifiers)
 item(tt(BARE_GLOB_QUAL) <Z>)(
 In a glob pattern, treat a trailing set of parentheses as a qualifier
-list, if it contains no `tt(|)', `tt(LPAR())' or (if special) `tt(~)'
+list, if it contains no unquoted `tt(|)', `tt(LPAR())' or (if special) `tt(~)'
 characters.  See noderef(Filename Generation).
 )
 pindex(BRACE_CCL)


diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index 70212dbc8..ef3ea45aa 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -2951,9 +2951,10 @@ the status of the last command).
 
 In the first form, the first character after the `tt(e)'
 will be used as a separator and anything up to the next matching separator
-will be taken  as the var(string); `tt([)', `tt({)', and `tt(<)' match
-`tt(])', `tt(})', and `tt(>)', respectively, while any other character
-matches itself. Note that expansions must be quoted in the var(string)
+will be taken  as the var(string); `tt(LPAR())', `tt([)', `tt({)', and
+`tt(<)' match `tt(RPAR())', `tt(])', `tt(})', and `tt(>)', respectively,
+while any other character matches itself.
+Note that expansions must be quoted in the var(string)
 to prevent them from being expanded before globbing is done.
 var(string) is then executed as shell code.  The string tt(globqual)
 is appended to the array tt(zsh_eval_context) the duration of


diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index 70212dbc8..51b359c53 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -2955,6 +2955,8 @@ will be taken  as the var(string); `tt([)', `tt({)', and `tt(<)' match
 `tt(])', `tt(})', and `tt(>)', respectively, while any other character
 matches itself. Note that expansions must be quoted in the var(string)
 to prevent them from being expanded before globbing is done.
+Quoting does not protect an end separator that appears in the var(string)
+unless it is a metacharacter.
 var(string) is then executed as shell code.  The string tt(globqual)
 is appended to the array tt(zsh_eval_context) the duration of
 execution.