27304: add ${(q-)..} flag

1 files changed, 16 insertions, 8 deletions

diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index bab12cc3f..59b6aeb87 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -825,14 +825,22 @@ have `tt(foo=bar)' and `tt(bar=baz)', the strings tt(${(P)foo}),
 tt(${(P)${foo}}), and tt(${(P)$(echo bar)}) will be expanded to `tt(baz)'.
 )
 item(tt(q))(
-Quote the resulting words with backslashes; unprintable or invalid
-characters are quoted using the tt($'\)var(NNN)tt(') form, with separate
-quotes for each octet.  If this flag is given
-twice, the resulting words are quoted in single quotes and if it is
-given three times, the words are quoted in double quotes; in these forms
-no special handling of unprintable or invalid characters is attempted.  If
-the flag is given four times, the words are quoted in single quotes
-preceded by a tt($).
+Quote characters that are special to the shell in the resulting words with
+backslashes; unprintable or invalid characters are quoted using the
+tt($'\)var(NNN)tt(') form, with separate quotes for each octet.
+
+If this flag is given twice, the resulting words are quoted in single
+quotes and if it is given three times, the words are quoted in double
+quotes; in these forms no special handling of unprintable or invalid
+characters is attempted.  If the flag is given four times, the words are
+quoted in single quotes preceded by a tt($).  Note that in all three of
+these forms quoting is done unconditionally, even if this does not change
+the way the resulting string would be interpreted by the shell.
+
+If a tt(q-) is given (only a single tt(q) may appear), a minimal
+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(Q))(
 Remove one level of quotes from the resulting words.