[PATCH] Clarify documentation of % sequences used by compadd -[Xx]

[dana <dana@xxxxxxx>]

I wanted to link the documentation on these sequences to someone on IRC who
was having trouble passing pre-formatted text to `_message -r`, and i found
that they were only mentioned in the context of the format style. Since
compadd handles them the same regardless of how it gets them (from any number
of utility functions), i feel like it's a bit clearer to explain it there.

dana


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