* [PATCH] docs: Clarifications about zstyle patterns.
@ 2020-04-28 19:59 Daniel Shahaf
0 siblings, 0 replies; only message in thread
From: Daniel Shahaf @ 2020-04-28 19:59 UTC (permalink / raw)
- 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.
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
@@ -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
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
+preferred over the pattern `tt(*)'. See
+ifzman(zmanref(zmodules))ifnzman(noderef(The zsh/zutil Module))
+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
+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
@@ -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
^ permalink raw reply [flat|nested] only message in thread
only message in thread, back to index
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-04-28 19:59 [PATCH] docs: Clarifications about zstyle patterns Daniel Shahaf
Archives are clonable: git clone --mirror http://inbox.vuxu.org/zsh-workers
Example config snippet for mirrors
Newsgroup available over NNTP:
AGPL code for this site: git clone https://public-inbox.org/public-inbox.git