From mboxrd@z Thu Jan 1 00:00:00 1970 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: (qmail 23537 invoked from network); 28 Apr 2020 19:59:55 -0000 Received: from ns1.primenet.com.au (HELO primenet.com.au) (203.24.36.2) by inbox.vuxu.org with UTF8ESMTPZ; 28 Apr 2020 19:59:55 -0000 Received: (qmail 23811 invoked by alias); 28 Apr 2020 19:59:48 -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: 45739 Received: (qmail 6598 invoked by uid 1010); 28 Apr 2020 19:59:48 -0000 X-Qmail-Scanner-Diagnostics: from out1-smtp.messagingengine.com by f.primenet.com.au (envelope-from , uid 7791) with qmail-scanner-2.11 (clamdscan: 0.102.2/25793. spamassassin: 3.4.4. Clear:RC:0(66.111.4.25):SA:0(-2.6/5.0):. Processed in 0.882881 secs); 28 Apr 2020 19:59:48 -0000 X-Envelope-From: d.s@daniel.shahaf.name X-Qmail-Scanner-Mime-Attachments: | X-Qmail-Scanner-Zip-Files: | Received-SPF: none (ns1.primenet.com.au: domain at daniel.shahaf.name does not designate permitted sender hosts) X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduhedriedugddugedvucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucenucfjughrpefhvffufffkofgggfestdektddtre dttdenucfhrhhomhepffgrnhhivghlucfuhhgrhhgrfhcuoegurdhssegurghnihgvlhdr shhhrghhrghfrdhnrghmvgeqnecukfhppeejledrudektddrudeftddrudegjeenucevlh hushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpegurdhssegurghn ihgvlhdrshhhrghhrghfrdhnrghmvg X-ME-Proxy: From: Daniel Shahaf To: zsh-workers@zsh.org Subject: [PATCH] docs: Clarifications about zstyle patterns. Date: Tue, 28 Apr 2020 19:59:10 +0000 Message-Id: <20200428195910.552-1-danielsh@tarpaulin.shahaf.local2> X-Mailer: git-send-email 2.20.1 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Qmail-Scanner-2.11: added fake Content-Type header Content-Type: text/plain - Consistently use the term "pattern" rather than "context" or "style pattern" - Correct statements about order of precedence of patterns - Give the rationale for the "rule of thumb" --- Turns out that zshcompsys(1) and zshzftpsys(1) both document the pattern precedence semantics. This patch just updates them to describe the incumbent semantics correctly, same as workers/45722 did. No prejudice to the ongoing discussion (workers/45730) is intended. Cheers, Daniel Doc/Zsh/compsys.yo | 30 ++++++++++++++++++------------ Doc/Zsh/zftpsys.yo | 8 +++----- 2 files changed, 21 insertions(+), 17 deletions(-) diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index 6ceb4d59d..384398094 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -49,7 +49,7 @@ Styles modify various operations of the completion system, such as output formatting, but also what kinds of completers are used (and in what order), or which tags are examined. Styles may accept arguments and are manipulated using the tt(zstyle) command described in -ifzman(see zmanref(zshmodules))\ +ifzman(zmanref(zshmodules))\ ifnzman(noderef(The zsh/zutil Module)). In summary, tags describe em(what) the completion objects are, and style @@ -658,8 +658,8 @@ ifnzman(noderef(Bindable Commands)). When looking up styles the completion system uses full context names, including the tag. Looking up the value of a style therefore consists of two things: the context, which is matched to the most specific (best -fitting) style pattern, and the name of the style itself, which must be -matched exactly. The following examples demonstrate that style patterns +fitting) pattern, and the name of the style itself, which must be +matched exactly. The following examples demonstrate that patterns may be loosely defined for styles that apply broadly, or as tightly defined as desired for styles that apply in narrower circumstances. @@ -673,7 +673,7 @@ example(zstyle ':completion:*' verbose yes) in a startup file (probably tt(.zshrc)). This gives the tt(verbose) style the value tt(yes) in every context inside the completion system, unless that context has a more -specific definition. It is best to avoid giving the context as `tt(*)' +specific definition. It is best to avoid giving the pattern as `tt(*)' in case the style has some meaning outside the completion system. Many such general purpose styles can be configured simply by using the @@ -710,15 +710,21 @@ as tt(menu) and tt(list-rows-first). Note that the order in which styles are em(defined) does not matter; the style mechanism uses the most specific possible match for a particular -style to determine the set of values. More precisely, strings are +style to determine the set of values. Strings are preferred over patterns (for example, `tt(:completion::complete:::foo)' is more specific than `tt(:completion::complete:::*')), and longer patterns are -preferred over shorter patterns. - -A good rule of thumb is that any completion style pattern that needs to -include more than one wildcard (tt(*)) and that does not end in a tag -name, should include all six colons (tt(:)), possibly surrounding -additional wildcards. +preferred over the pattern `tt(*)'. See +ifzman(zmanref(zmodules))ifnzman(noderef(The zsh/zutil Module)) +for details. + +Context patterns that use something other than a wildcard (tt(*)) to match the +middle parts of the context DASH()- the var(completer), var(command), and +var(argument) in +tt(:completion:)var(function)tt(:)var(completer)tt(:)var(command)tt(:)var(argument)tt(:)var(tag) +DASH()- should include all six colons (tt(:)) explicitly. Without this, +a pattern such as tt(:completion:*:foo:*) could match tt(foo) against a +component other than the intended one (for example, against var(completer) when +a match against var(command) was intended). Style names like those of tags are arbitrary and depend on the completion function. However, the following two sections list some of the most diff --git a/Doc/Zsh/zftpsys.yo b/Doc/Zsh/zftpsys.yo index 349039edc..c2fbdd23f 100644 --- a/Doc/Zsh/zftpsys.yo +++ b/Doc/Zsh/zftpsys.yo @@ -518,13 +518,11 @@ command `tt(zstyle ':zftp:*') var(style) var(value) ...'. defines the var(style) to have value var(value); more than one value may be given, although that is not useful in the cases described here. These values will then be used throughout the zftp function system. For more -precise control, the first argument, which gives a context in which the +precise control, the first argument, which gives a pattern that matches em(contexts) in which the style applies, can be modified to include a particular function, as for example `tt(:zftp:zfget)': the style will then have the given value only -in the tt(zfget) function. Values for the same style in different contexts -may be set; the most specific function will be used, where -strings are held to be more specific than patterns, and longer patterns and -shorter patterns. Note that only the top level function name, as called by +in the tt(zfget) function, and will override styles set under `tt(:zftp:*)'. +Note that only the top level function name, as called by the user, is used; calling of lower level functions is transparent to the user. Hence modifications to the title bar in tt(zftp_chpwd) use the contexts tt(:zftp:zfopen), tt(:zftp:zfcd), etc., depending where it was