45184: Clarify documentation of %-sequences understood by compadd -[Xx]

2 files changed, 33 insertions, 11 deletions

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 130e85148..ce3e6ea1e 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -1609,16 +1609,12 @@ item(tt(format))(
 If this is set for the tt(descriptions) tag, its value is used as a
 string to display above matches in completion lists.  The sequence
 `tt(%d)' in this string will be replaced with a short description of
-what these matches are.  This string may also contain the following
-sequences to specify output attributes
-ifnzman((see noderef(Prompt Expansion)))\
-ifzman(as described in the section EXPANSION OF PROMPT SEQUENCES in
-zmanref(zshmisc)):
-`tt(%B)', `tt(%S)', `tt(%U)', `tt(%F)', `tt(%K)' and their lower case
-counterparts, as well as `tt(%{)...tt(%})'.  `tt(%F)', `tt(%K)' and
-`tt(%{)...tt(%})' take arguments in the same form as prompt
-expansion.  Note that the sequence `tt(%G)' is not available; an argument
-to `tt(%{)' should be used instead.
+what these matches are.  This string may also contain the output
+attribute sequences understood by tt(compadd -X)
+(see
+ifzman(zmanref(zshcompwid))\
+ifnzman(noderef(Completion Widgets))\
+).
 
 The style is tested with each tag valid for the current completion
 before it is tested for the tt(descriptions) tag.  Hence different format 
@@ -4588,7 +4584,9 @@ not set with the former.
 If the tt(-r) option is given, no style is used; the var(descr) is
 taken literally as the string to display.  This is most useful
 when the var(descr) comes from a pre-processed argument list
-which already contains an expanded description.
+which already contains an expanded description.  Note that this
+option does not disable the `tt(%)'-sequence parsing done by
+tt(compadd).
 
 The tt(-12VJ) options and the var(group) are passed to tt(compadd) and
 hence determine the group the message string is added to.
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index b74db8408..0b98d07b2 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -590,6 +590,30 @@ different name spaces.
 item(tt(-X) var(explanation))(
 The var(explanation) string will be printed with the list of matches,
 above the group currently selected.
+
+Within the var(explanation), the following sequences may be used to
+specify output attributes
+ifnzman((see noderef(Prompt Expansion)))\
+ifzman(as described in the section EXPANSION OF PROMPT SEQUENCES in
+zmanref(zshmisc)):
+`tt(%B)', `tt(%S)', `tt(%U)', `tt(%F)', `tt(%K)' and their lower case
+counterparts, as well as `tt(%{)...tt(%})'.  `tt(%F)', `tt(%K)' and
+`tt(%{)...tt(%})' take arguments in the same form as prompt
+expansion.  (Note that the sequence `tt(%G)' is not available; an
+argument to `tt(%{)' should be used instead.)  The sequence `tt(%%)'
+produces a literal `tt(%)'.
+
+These sequences are most often employed by users when customising the
+tt(format) style
+(see
+ifzman(zmanref(zshcompsys))\
+ifnzman(noderef(Completion System))\
+),
+but they must also be taken into account when writing completion
+functions, as passing descriptions with unescaped `tt(%)' characters
+to utility functions such as tt(_arguments) and tt(_message) may
+produce unexpected results. If arbitrary text is to be passed in a
+description, it can be escaped using e.g. tt(${my_str//\%/%%}).
 )
 item(tt(-x) var(message))(
 Like tt(-X), but the var(message) will be printed even if there are no