[PATCH] zstyle: Correct and expand docs (was: Re: Most minimal configuration challenge)

[Daniel Shahaf <d.s@daniel.shahaf.name>]

I noticed the contradictory claims about equally v. more specific on
lines 55-56 of mod_zutil.yo, and along the way fixed some preëxisting
issues.

Daniel


diff --git a/Doc/Zsh/mod_zutil.yo b/Doc/Zsh/mod_zutil.yo
index 3cf9e5028..ef0ee64a3 100644
--- a/Doc/Zsh/mod_zutil.yo
+++ b/Doc/Zsh/mod_zutil.yo
@@ -17,15 +17,16 @@ 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 `em(context)', which is matched against the
-patterns.  The definition stored for the most specific pattern that matches
-will be returned.
+giving a string, called the `em(context)', which patterns are matched against.
+The definition stored for that style name the most specific pattern that
+matches the context will be returned.
 
+COMMENT(See the "Calculate the weight" common in Src/Modules/zutil.c)
 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
+any pattern other than `tt(*)' is considered to be more specific than the pattern
 `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
@@ -51,8 +52,19 @@ in order to retrieve your preference into the scalar variable tt($REPLY).
 On Sundays tt($REPLY) would be set to `tt(snow)'; in Europe it would be set
 to `tt(rain)'; and on Sundays in Europe it would be set to `tt(snow)' again,
 because the patterns `tt(:weather:europe:*)' and `tt(:weather:*:Sunday:*)' both
-match the var(context) argument to tt(zstyle -s), are equally specific, and the
-latter is more specific (because it has more colon-separated components).
+match the var(context) argument to tt(zstyle -s) and the
+latter pattern has more colon-separated components, and therefore is more
+specific.  A definition such as
+
+example(zstyle ':weather:e*:Sunday:*gib*' preferred-precipitation cloudless-skies)
+
+would be more specific still, since it has the same number of colon-separated
+components but the components are more specific; and the definition
+
+example(zstyle ':weather:europe:Sunday:waxing-gibbous' meteorites)
+
+would be more specific than any other definition that might also match,
+since none of its colon-separated components is a pattern.
 
 em(Usage)