Merge remote-tracking branch 'origin/master' into 5.9

Right now, as we're preparing to tag the 5.8 release, the 5.9 branch is
maintained as a topic branch off master.

* origin/master:
  45287: zshexpn: Describe parameter elision and add some introductory prose
  45302: bin_umask(): Queue signals around umask().
  users/24656: docs: Add an example of setting and querying zstyles
  users/24659: Cross-ref doc for matchers.
  45296: D02glob: Clean up after test from users/24633
  45290: New helper script for listing XFail tests.
  users/24633: Add an xfail test for users/24619.
  unposted: additional typo fix
  45280: _git: add -local variants
  users/24628 (fixed): More doc for selectw-word-style widgets.
  45266: Fix losetup completion, broken in da085b7a20729401c725f91ae930200d0deda64f (41720).
  unposted: Fix punctuation.
  use /dev/fd on Cygwin for process substitution
  unposted: Two additional typo fixes.
  Fix typos reported by codespell in shell code
  Fix typos reported by codespell in Src/
  45269: Fix misspellings in completions and elsewhere.
  45261: _gcc: Detect clang-as-gcc
  unposted: internal: Remove Vim modeline that interferes with ztst.vim.
  unposted: internal: ztst.vim: Use :syn-sync to work around (#x) and "`\\\\\\\\`" confusing the highlighting.
  unposted: internal: zyodl.vim: Support glob qualifiers in example()'s
  unposted: internal: zyodl.vim: Support yodl comments.
  github #44: Allow completion for picocom to list symlinks to character devices
  45245: _gcc: add some clang specific warnings
  45231: _rsync: When completing remote modules, ignore more of the motd.
  unposted: _tac: Eliminate superfluous variable
  45226: _man: Improve completion of file paths
  45184: Clarify documentation of %-sequences understood by compadd -[Xx]
  45239: Remove 'appendhistory' from zsh-newuser-install
  45218: add more options to swaks completion
  45196: fix completion after make -C, allowing for -C being used multiple times
  unposted (after 45183): Fix yodl error: "contrib.yo:4457: No macro: back(...)".
  45181: Fix workers/45164: ${(S)%%} will now consider the empty string as a potential match.
  45183: Improve documentation examples
  unposted: Add some tests for ${(S)}, including a regression test for workers/45164.
  45169/0002 (tweaked for trailing newlines): Add an expected-to-fail test for workers/44007.
  45169/0001: In the test suite, allow test cases to be marked as expected to fail.
  users/24582 + users/24583: Add regression tests for the previous commit.
  24581: Fix array assignments in shell word splitting and completion.
  45160: zshexpn: Expand documentation of (S)
  45150 + 45152: zshexpn: Use a more minimal example in the documentation of (#b).
  unposted: internal: Vim ztst support: Add an ftplugin in addition to the syntax highlighter.
  45130: _multi_parts: Always pass -f to compadd if given by caller
  unposted: zerrmsg(): Fix macro guard missed in previous commit
  unposted: ChangeLog for last commit
  internal: Allow %L in zerrmsg() in non-debug builds, too.

7 files changed, 183 insertions, 75 deletions

diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index 415bce613..ada69c99a 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -39,11 +39,11 @@ be familiar to most command line users.
 
 Typically, options are single letters preceded by a hyphen (tt(-)).
 Options that take an argument accept it either immediately following the
-option letter or after white space, for example `tt(print -C3 *)' or
-`tt(print -C 3 *)' are equivalent.  Arguments to options are not the
+option letter or after white space, for example `tt(print -C3 {1..9})' or
+`tt(print -C 3 {1..9})' are equivalent.  Arguments to options are not the
 same as arguments to the command; the documentation indicates which is
 which.  Options that do not take an argument may be combined in a single
-word, for example `tt(print -ca *)' and `tt(print -c -a *)' are
+word, for example `tt(print -rca -- *)' and `tt(print -r -c -a -- *)' are
 equivalent.
 
 Some shell builtin commands also take options that begin with `tt(+)'
@@ -54,14 +54,14 @@ Options (together with their individual arguments, if any) must appear
 in a group before any non-option arguments; once the first non-option
 argument has been found, option processing is terminated.
 
-All builtin commands other than precommand modifiers, even those that
-have no options, can be given the argument `tt(-)tt(-)' to terminate option
-processing.  This indicates that the following words are non-option
-arguments, but is otherwise ignored.  This is useful in cases where
-arguments to the command may begin with `tt(-)'.  For historical
-reasons, most builtin commands also recognize a single `tt(-)' in a
-separate word for this purpose; note that this is less standard and
-use of `tt(-)tt(-)' is recommended.
+All builtin commands other than `tt(echo)' and precommand modifiers,
+even those that have no options, can be given the argument `tt(-)tt(-)'
+to terminate option processing.  This indicates that the following words
+are non-option arguments, but is otherwise ignored.  This is useful in
+cases where arguments to the command may begin with `tt(-)'.  For
+historical reasons, most builtin commands (including `tt(echo)') also
+recognize a single `tt(-)' in a separate word for this purpose; note
+that this is less standard and use of `tt(-)tt(-)' is recommended.
 
 startitem()
 prefix(-)
@@ -114,9 +114,9 @@ var(text) is any non-empty string, it is replaced by the text
 a literal string, not a pattern.  A trailing space in var(value) is not
 special in this case.  For example,
 
-example(alias -s ps=gv)
+example(alias -s ps='gv --')
 
-will cause the command `tt(*.ps)' to be expanded to `tt(gv *.ps)'.  As
+will cause the command `tt(*.ps)' to be expanded to `tt(gv -- *.ps)'.  As
 alias expansion is carried out earlier than globbing, the `tt(*.ps)' will
 then be expanded.  Suffix aliases constitute a different name space from
 other aliases (so in the above example it is still possible
@@ -1258,7 +1258,10 @@ If given together with tt(-o) or tt(-O), sorting is performed
 case-independently.
 )
 item(tt(-l))(
-Print the arguments separated by newlines instead of spaces.
+Print the arguments separated by newlines instead of spaces.  Note: if
+the list of arguments is empty, tt(print -l) will still output one empty
+line. To print a possibly-empty list of arguments one per line, use
+tt(print -C1), as in `tt(print -rC1 -- "$list[@]")'.
 )
 item(tt(-m))(
 Take the first argument as a pattern (should be quoted), and remove
@@ -1269,7 +1272,9 @@ item(tt(-n))(
 Do not add a newline to the output.
 )
 item(tt(-N))(
-Print the arguments separated and terminated by nulls.
+Print the arguments separated and terminated by nulls. Again,
+tt(print -rNC1 -- "$list[@]") is a canonical way to print an
+arbitrary list as null-delimited records.
 )
 item(tt(-o))(
 Print the arguments sorted in ascending order.
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 130e85148..c2d20ca40 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 
@@ -2064,6 +2060,9 @@ specification.  The value should be in the form described in
 ifzman(the section `Completion Matching Control' in zmanref(zshcompwid))\
 ifnzman(noderef(Completion Matching Control))\
 .  For examples of this, see the description of the tt(tag-order) style.
+
+For notes comparing the use of this and the tt(matcher-list) style, see
+under the description of the tt(tag-order) style.
 )
 kindex(matcher-list, completion style)
 item(tt(matcher-list))(
@@ -2128,6 +2127,9 @@ If there is no current matcher or it is empty, and the option
 tt(NO_CASE_GLOB) is in effect, the matching for files is performed
 case-insensitively in any case.  However, any matcher must
 explicitly specify case-insensitive matching if that is required.
+
+For notes comparing the use of this and the tt(matcher) style, see
+under the description of the tt(tag-order) style.
 )
 kindex(max-errors, completion style)
 item(tt(max-errors))(
@@ -4588,7 +4590,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 
diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index 558342711..c6bf745b7 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -2227,7 +2227,20 @@ is set in the context tt(:zle:*) to tt(true) if the word style is
 tt(bash) and tt(false) otherwise.  It may be overridden by setting it in
 the more specific context tt(:zle:forward-word*).
 
-Here are some examples of use of the styles, actually taken from the
+It is possible to create widgets with specific behaviour by defining
+a new widget implemented by the appropriate generic function, then
+setting a style for the context of the specific widget.  For example,
+the following defines a widget tt(backward-kill-space-word) using
+tt(backward-kill-word-match), the generic widget implementing
+tt(backward-kill-word) behaviour, and ensures that the new widget
+always implements space-delimited behaviour.
+
+example(zle -N backward-kill-space-word backward-kill-word-match
+zstyle :zle:backward-kill-space-word word-style space)
+
+The widget tt(backward-kill-space-word) can now be bound to a key.
+
+Here are some further examples of use of the styles, actually taken from the
 simplified interface in tt(select-word-style):
 
 example(zstyle ':zle:*' word-style standard
@@ -4418,24 +4431,28 @@ the elements from the tt(input) list in each run.  If no var(command) is
 provided, then no var(arg) list may be provided, and in that event the
 default command is `tt(print)' with arguments `tt(-r -)tt(-)'.
 
-For example, to get a long tt(ls) listing of all plain files in the
-current directory or its subdirectories:
+For example, to get a long tt(ls) listing of all non-hidden plain files
+in the current directory or its subdirectories:
 
 example(autoload -U zargs
-zargs -- **/*(.) -- ls -l)
+zargs -- **/*(.) -- ls -ld --)
+
+The first and third occurrences of `tt(-)tt(-)' are used to mark the end
+of options for tt(zargs) and tt(ls) respectively to guard against
+filenames starting with `tt(-)', while the second is used to separate the
+list of files from the command to run (`tt(ls -ld --)').
+
+The first `tt(-)tt(-)' would also be needed if there was a chance the
+list might be empty as in:
 
-Note that `tt(-)tt(-)' is used both to mark the end of the var(option)
-list and to mark the end of the var(input) list, so it must appear twice
-whenever the var(input) list may be empty.  If there is guaranteed to be
-at least one var(input) and the first var(input) does not begin with a
-`tt(-)', then the first `tt(-)tt(-)' may be omitted.
+example(zargs -r -- ./*.back+LPAR()#qN+RPAR() -- rm -f)
 
 In the event that the string `tt(-)tt(-)' is or may be an var(input), the
 tt(-e) option may be used to change the end-of-inputs marker.  Note that
 this does em(not) change the end-of-options marker.  For example, to use
 `tt(..)' as the marker:
 
-example(zargs -e.. -- **/*(.) .. ls -l)
+example(zargs -e.. -- **/*(.) .. ls -ld --)
 
 This is a good choice in that example because no plain file can be named
 `tt(..)', but the best end-marker depends on the circumstances.
diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index d7147dbd7..c129b4228 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -400,7 +400,7 @@ backslashes.
 For example, the following piece of filename generation code
 with the tt(EXTENDED_GLOB) option:
 
-example(print *.c+LPAR()#q:s/#%+LPAR()#b+RPAR()s+LPAR()*+RPAR().c/'S${match[1]}.C'/+RPAR())
+example(print -r -- *.c+LPAR()#q:s/#%+LPAR()#b+RPAR()s+LPAR()*+RPAR().c/'S${match[1]}.C'/+RPAR())
 
 takes the expansion of tt(*.c) and applies the glob qualifiers in the
 tt(LPAR()#q)var(...)tt(RPAR()) expression, which consists of a substitution
@@ -582,7 +582,25 @@ and subscript notation to access individual array elements.
 Note in particular the fact that words of unquoted parameters are not
 automatically split on whitespace unless the option tt(SH_WORD_SPLIT) is
 set; see references to this option below for more details.  This is an
-important difference from other shells.
+important difference from other shells.  However, as in other shells,
+null words are elided from unquoted parameters' expansions.
+
+With default options, after the assignments:
+
+example(array=("first word" "" "third word")
+scalar="only word")
+
+then tt($array) substitutes two words, `tt(first word)' and `tt(third
+word)', and tt($scalar) substitutes a single word `tt(only word)'.  Note
+that second element of tt(array) was elided.  Scalar parameters can
+be elided too if their value is null (empty).  To avoid elision, use quoting as
+follows: tt("$scalar") for scalars and tt("${array[@]}") or tt("${(@)array}")
+for arrays.  (The last two forms are equivalent.)
+
+Parameter expansions can involve em(flags), as in `tt(${(@kv)aliases})',
+and other operators, such as `tt(${PREFIX:-"/usr/local"})'.  Parameter
+expansions can also be nested.  These topics will be introduced below.
+The full rules are complicated and are noted at the end.
 
 In the expansions discussed below that require a pattern, the form of
 the pattern is the same as that used for filename generation;
@@ -594,17 +612,8 @@ noderef(Modifiers) in noderef(History Expansion) can be
 applied:  for example, tt(${i:s/foo/bar/}) performs string
 substitution on the expansion of parameter tt($i).
 
-In the following descriptions, `word' refers to a single word
+In the following descriptions, `var(word)' refers to a single word
 substituted on the command line, not necessarily a space delimited word.
-With default options, after the assignments:
-
-example(array=("first word" "second word")
-scalar="only word")
-
-then tt($array) substitutes two words, `tt(first word)' and `tt(second
-word)', and tt($scalar) substitutes a single word `tt(only word)'.  This
-may be modified by explicit or implicit word-splitting, however.  The
-full rules are complicated and are noted at the end.
 
 startitem()
 item(tt(${)var(name)tt(}))(
@@ -1394,11 +1403,40 @@ used with the tt(${)...tt(/)...tt(}) forms.
 
 startitem()
 item(tt(S))(
-Search substrings as well as beginnings or ends; with tt(#) start
-from the beginning and with tt(%) start from the end of the string.
+With tt(#) or tt(##), search for the match that starts closest to the start of
+the string (a `substring match'). Of all matches at a particular position,
+tt(#) selects the shortest and tt(##) the longest:
+
+example(% str="aXbXc"
+% echo ${+LPAR()S+RPAR()str#X*}
+abXc
+% echo ${+LPAR()S+RPAR()str##X*}
+a
+% )
+
+With tt(%) or tt(%%), search for the match that starts closest to the end of
+the string:
+
+example(% str="aXbXc"
+% echo ${+LPAR()S+RPAR()str%X*}
+aXbc
+% echo ${+LPAR()S+RPAR()str%%X*}
+aXb
+% )
+
+(Note that tt(%) and tt(%%) don't search for the match that ends closest to the
+end of the string, as one might expect.)
+
 With substitution via tt(${)...tt(/)...tt(}) or
 tt(${)...tt(//)...tt(}), specifies non-greedy matching, i.e. that the
-shortest instead of the longest match should be replaced.
+shortest instead of the longest match should be replaced:
+
+example(% str="abab"
+% echo ${str/*b/_}
+_
+% echo ${+LPAR()S+RPAR()str/*b/_}
+_ab
+% )
 )
 item(tt(I:)var(expr)tt(:))(
 Search the var(expr)th match (where var(expr) evaluates to a number).
@@ -2264,12 +2302,13 @@ parentheses can be referenced.
 
 For example,
 
-example(foo="a string with a message"
-if [[ $foo = (a|an)' '(#b)(*)' '* ]]; then
+example(foo="a_string_with_a_message"
+if [[ $foo = (a|an)_(#b)(*) ]]; then
   print ${foo[$mbegin[1],$mend[1]]}
 fi)
 
-prints `tt(string with a)'.  Note that the first parenthesis is before the
+prints `tt(string_with_a_message)'.
+Note that the first set of parentheses is before the
 tt((#b)) and does not create a backreference.
 
 Backreferences work with all forms of pattern matching other than filename
@@ -2492,11 +2531,11 @@ therefore matches files in the current directory as well as
 subdirectories.
 Thus:
 
-example(ls (*/)#bar)
+example(ls -ld -- (*/)#bar)
 
 or
 
-example(ls **/bar)
+example(ls -ld -- **/bar)
 
 does a recursive directory search for files named `tt(bar)' (potentially
 including the file `tt(bar)' in the current directory).  This form does not
@@ -2511,11 +2550,11 @@ they are treated as if both a tt(/) plus a further tt(*) are present.
 Hence:
 
 example(setopt GLOBSTARSHORT
-ls **.c)
+ls -ld -- **.c)
 
 is equivalent to
 
-example(ls **/*.c)
+example(ls -ld -- **/*.c)
 subsect(Glob Qualifiers)
 cindex(globbing, qualifiers)
 cindex(qualifiers, globbing)
@@ -2707,7 +2746,7 @@ appropriate test.  For example,
 
 example(nt+LPAR()RPAR() { [[ $REPLY -nt $NTREF ]] }
 NTREF=reffile
-ls -l *(+nt))
+ls -ld -- *(+nt))
 
 lists all files in the directory that have been modified more recently than
 tt(reffile).
@@ -2898,36 +2937,36 @@ is performed, although note that the presence of the parentheses
 causes the entire expression to be subjected to any global pattern matching
 options such as tt(NULL_GLOB). Thus:
 
-example(ls *(-/))
+example(ls -ld -- *(-/))
 
 lists all directories and symbolic links that point to directories,
 and
 
-example(ls *(-@))
+example(ls -ld -- *(-@))
 
 lists all broken symbolic links, and
 
-example(ls *(%W))
+example(ls -ld -- *(%W))
 
 lists all world-writable device files in the current directory, and
 
-example(ls *(W,X))
+example(ls -ld -- *(W,X))
 
 lists all files in the current directory that are
 world-writable or world-executable, and
 
-example(echo /tmp/foo*(u0^@:t))
+example(print -rC1 /tmp/foo*(u0^@:t))
 
 outputs the basename of all root-owned files beginning with the string
 `tt(foo)' in tt(/tmp), ignoring symlinks, and
 
-example(ls *.*~(lex|parse).[ch](^D^l1))
+example(ls -ld -- *.*~(lex|parse).[ch](^D^l1))
 
 lists all files having a link count of one whose names contain a dot
 (but not those starting with a dot, since tt(GLOB_DOTS) is explicitly
 switched off) except for tt(lex.c), tt(lex.h), tt(parse.c) and tt(parse.h).
 
-example(print b*.pro+LPAR()#q:s/pro/shmo/+RPAR()(#q.:s/builtin/shmiltin/))
+example(print -rC1 b*.pro+LPAR()#q:s/pro/shmo/+RPAR()(#q.:s/builtin/shmiltin/))
 
 demonstrates how colon modifiers and other qualifiers may be chained
 together.  The ordinary qualifier `tt(.)' is applied first, then the colon
diff --git a/Doc/Zsh/mod_zpty.yo b/Doc/Zsh/mod_zpty.yo
index 6f20c4b75..3ca031c01 100644
--- a/Doc/Zsh/mod_zpty.yo
+++ b/Doc/Zsh/mod_zpty.yo
@@ -25,7 +25,7 @@ monitored with ZLE descriptor handlers (see ifzman(zmanref(zshzle))\
 ifnzman(noderef(Zle Builtins))) or manipulated with tt(sysread) and
 tt(syswrite) (see ifzman(THE ZSH/SYSTEM MODULE in zmanref(zshmodules))\
 ifnzman(noderef(The zsh/system Module))).  em(Warning): Use of tt(sysread)
-and tt(syswrite) is em(not) recommended, use tt(zpty -r) and tt(zpty -w)
+and tt(syswrite) is em(not) recommended; use tt(zpty -r) and tt(zpty -w)
 unless you know exactly what you are doing.
 )
 item(tt(zpty) tt(-d) [ var(name) ... ])(
diff --git a/Doc/Zsh/mod_zutil.yo b/Doc/Zsh/mod_zutil.yo
index 1e35d2245..e556e2b37 100644
--- a/Doc/Zsh/mod_zutil.yo
+++ b/Doc/Zsh/mod_zutil.yo
@@ -17,18 +17,37 @@ item(tt(zstyle -m) var(context) var(style) var(pattern))(
 This builtin command is used to define and lookup styles.  Styles are
 pairs of names and values, where the values consist of any number of
 strings.  They are stored together with patterns and lookup is done by
-giving a string, called the `context', which is compared to the
-patterns.  The definition stored for the first matching pattern will be 
-returned.
+giving a string, called the `em(context)', which is matched against the
+patterns.  The definition stored for the most specific pattern that matches
+will be returned.
 
-For ordering of comparisons, patterns are searched from most specific to
-least specific, and patterns that are equally specific keep the order in 
-which they were defined.  A pattern is considered to be more specific
+A pattern is considered to be more specific
 than another if it contains more components (substrings separated by
 colons) or if the patterns for the components are more specific, where 
 simple strings are considered to be more specific than patterns and
 complex patterns are considered to be more specific than the pattern
-`tt(*)'.
+`tt(*)'.  A `tt(*)' in the pattern will match zero or more characters
+in the context; colons are not treated specially in this regard.
+If two patterns are equally specific, the tie is broken in favour of
+the pattern that was defined first.
+
+em(Example)
+
+For example, to define your preferred form of precipitation depending on which
+city you're in, you might set the following in your tt(zshrc):
+
+example(zstyle ':weather:europe:*' preferred-precipitation rain
+zstyle ':weather:europe:germany:* preferred-precipitation none
+zstyle ':weather:europe:germany:*:munich' preferred-precipitation snow)
+
+Then, the fictional `tt(weather)' plugin might run under the hood a command
+such as
+
+example(zstyle -s ":weather:${continent}:${country}:${county}:${city}" preferred-precipitation REPLY)
+
+in order to retrieve your preference into the scalar variable tt($REPLY).
+
+em(Usage)
 
 The first form (without arguments) lists the definitions.  Styles
 are shown in alphabetic order and patterns are shown in the order
@@ -39,7 +58,7 @@ tt(zstyle).  The optional first argument is a pattern which will be matched
 against the string supplied as the pattern for the context; note that
 this means, for example, `tt(zstyle -L ":completion:*")' will
 match any supplied pattern beginning `tt(:completion:)', not
-just tt(":completion:*"):  use tt(":completion:\*") to match that.
+just tt(":completion:*"):  use tt(':completion:\*') to match that.
 The optional second argument limits the output to a specific var(style) (not a
 pattern).  tt(-L) is not compatible with any other options.