From 7f73edad7a7547d357e540ca26264768c1eddbfb Mon Sep 17 00:00:00 2001 From: Daniel Shahaf Date: Tue, 28 Apr 2020 19:59:10 +0000 Subject: 45739: docs: Clarifications about zstyle patterns. - 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" --- Doc/Zsh/compsys.yo | 28 +++++++++++++++++----------- Doc/Zsh/zftpsys.yo | 8 +++----- 2 files changed, 20 insertions(+), 16 deletions(-) (limited to 'Doc') diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index a1a1da935..1ce17dccc 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 -- cgit 1.4.1