From 2e521d7b631e46d64ac8b274c8fe84bf21cb83ea Mon Sep 17 00:00:00 2001 From: dana Date: Sun, 5 Jan 2020 12:03:59 -0600 Subject: 45184: Clarify documentation of %-sequences understood by compadd -[Xx] --- Doc/Zsh/compsys.yo | 20 +++++++++----------- Doc/Zsh/compwid.yo | 24 ++++++++++++++++++++++++ 2 files changed, 33 insertions(+), 11 deletions(-) (limited to 'Doc/Zsh') 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 -- cgit 1.4.1