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"

ChangeLog

@@ -1,5 +1,8 @@
 2020-05-02  Daniel Shahaf  <d.s@daniel.shahaf.name>
 
+	* 45739: Doc/Zsh/compsys.yo, Doc/Zsh/zftpsys.yo: docs:
+	Clarifications about zstyle patterns.
+
 	* 45722: Doc/Zsh/mod_zutil.yo, V05styles.ztst: docs: Change
 	zstyle example to a non-hierarchical one
 

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
+fitting) pattern, and the name of the style itself, which must be
-matched exactly.  The following examples demonstrate that style patterns
+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.
+preferred over the pattern `tt(*)'. See 
+ifzman(zmanref(zmodules))ifnzman(noderef(The zsh/zutil Module))
+for details.
 
-A good rule of thumb is that any completion style pattern that needs to
+Context patterns that use something other than a wildcard (tt(*)) to match the
-include more than one wildcard (tt(*)) and that does not end in a tag
+middle parts of the context DASH()- the var(completer), var(command), and
-name, should include all six colons (tt(:)), possibly surrounding
+var(argument) in
-additional wildcards.
+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

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
+in the tt(zfget) function, and will override styles set under `tt(:zftp:*)'.
-may be set; the most specific function will be used, where
+Note that only the top level function name, as called by
-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
 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