From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-1.0 required=5.0 tests=MAILING_LIST_MULTI, RCVD_IN_DNSWL_NONE autolearn=ham autolearn_force=no version=3.4.2 Received: from primenet.com.au (ns1.primenet.com.au [203.24.36.2]) by inbox.vuxu.org (OpenSMTPD) with ESMTP id 2a958abe for ; Thu, 2 Jan 2020 02:54:21 +0000 (UTC) Received: (qmail 21604 invoked by alias); 2 Jan 2020 02:54:16 -0000 Mailing-List: contact zsh-workers-help@zsh.org; run by ezmlm Precedence: bulk X-No-Archive: yes List-Id: Zsh Workers List List-Post: List-Help: List-Unsubscribe: X-Seq: 45184 Received: (qmail 13867 invoked by uid 1010); 2 Jan 2020 02:54:16 -0000 X-Qmail-Scanner-Diagnostics: from mail-yw1-f48.google.com by f.primenet.com.au (envelope-from , uid 7791) with qmail-scanner-2.11 (clamdscan: 0.102.1/25677. spamassassin: 3.4.2. Clear:RC:0(209.85.161.48):SA:0(-1.9/5.0):. Processed in 0.735684 secs); 02 Jan 2020 02:54:16 -0000 X-Envelope-From: dana@dana.is X-Qmail-Scanner-Mime-Attachments: | X-Qmail-Scanner-Zip-Files: | Received-SPF: pass (ns1.primenet.com.au: SPF record at _netblocks.google.com designates 209.85.161.48 as permitted sender) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:content-transfer-encoding:mime-version :subject:message-id:date:to; bh=rqt/OjrQ246nE1z75hCfPhRtdSjz5GJcn8F4bZNxGqY=; b=HJ8tmO5p2t/zKt+g+/bvC2t3OLKmt/E6F0+oyUUj49TeR5/sBPxnMwDnXAv7QMhucA 2C13RurlUfEpVBSnbHwRLmCLNvmN1L8Ey5t1C1C1KlC1cnRQaolde0MnkxqMVUeCjRD6 GK/5b6Tb2aH8kpWUkp9oWqdD00D6GclHPa/T4iMJOVRNN3WB1NV5tvXOAbUUCLbqx9Q4 ItzyPttHz7aJivmeVycva1Mc0NeqADgLK4jC/GxlTz4WbpoKzerczLUes3LhBIthnmHu OmOwGPMOcCkjEOaj80LLsU6nrAE3nuN/KkaSuy3xGQyiy8YMZSU6aCXfTG2jdI9haoj5 8vwg== X-Gm-Message-State: APjAAAUWJmeR5GEVbyKDbJHWO0EpBlD8VXG4wTX4Mvc2UAy559AACe6E +2h/9SgFuhI8zFWnBrvOR0I43smaOxdWMw== X-Google-Smtp-Source: APXvYqyzyfaBVIRy9jowQv1et/CjbWIwEv1iB4o/jZbp4V+XgOuk0gBDuLmubpnjgoJvJU73lYD9Fg== X-Received: by 2002:a81:3845:: with SMTP id f66mr62348507ywa.220.1577933622400; Wed, 01 Jan 2020 18:53:42 -0800 (PST) From: dana Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Mime-Version: 1.0 (Mac OS X Mail 12.4 \(3445.104.11\)) Subject: [PATCH] Clarify documentation of % sequences used by compadd -[Xx] Message-Id: <7F4C3CB9-1A41-46DA-995C-49FA17D4618E@dana.is> Date: Wed, 1 Jan 2020 20:55:43 -0600 To: Zsh Workers List X-Mailer: Apple Mail (2.3445.104.11) 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