54043, 54055: allow highlighing attributes to be turned back off

1 files changed, 31 insertions, 12 deletions

diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo
index e20184121..29a8b8597 100644
--- a/Doc/Zsh/zle.yo
+++ b/Doc/Zsh/zle.yo
@@ -990,14 +990,14 @@ The var(token) is preserved verbatim but not parsed in any way.
 Plugins may use this to identify array elements they have added: for example,
 a plugin might set var(token) to its (the plugin's) name and then use
 `tt(region_highlight=+LPAR() ${region_highlight:#*memo=)var(token)tt(} +RPAR())'
-in order to remove array elements it have added.
+in order to remove array elements it added.
 
 (This example uses the `tt(${)var(name)tt(:#)var(pattern)tt(})' array-grepping
 syntax described in
 sectref(Parameter Expansion)(zshexpn).))
 enditemize()
 
-For example, 
+For example,
 
 example(region_highlight=("P0 20 bold memo=foobar"))
 
@@ -1009,12 +1009,16 @@ as soon as the line is accepted.
 
 Note that zsh 5.8 and older do not support the `tt(memo=)var(token)' field
 and may misparse the third (highlight specification) field when a memo
-is given.
-COMMENT(The syntax `tt(0 20 bold, memo=foobar)' (with an auxiliary comma)
-happens to work on both zsh <=5.8 and zsh 5.9-to-be, but that seems to be more of
+is given. COMMENT(The syntax `tt(0 20 bold, memo=foobar)' (with an auxiliary comma)
+happens to work on both zsh <=5.8 and zsh 5.9, but that seems to be more of
 an accident of implementation than something we should make a first-class-citizen
 API promise.  It's mentioned in the "Incompatibilities" section of README.)
 
+Where a particular region is covered by multiple entries in
+tt(region_highlight), their effects are merged. In the case of conflicts, later
+entries take precedence over earlier ones. This precedence ordering can be
+overridden by specifying layers.
+
 The final highlighting on the command line depends on both tt(region_highlight)
 and tt(zle_highlight); see
 sectref(Character Highlighting)(below) for details.
@@ -2818,9 +2822,16 @@ not all types of highlighting are available on all terminals:
 
 startitem()
 item(tt(none))(
-No highlighting is applied to the given context.  It is not useful for
-this to appear with other types of highlighting; it is used to override
-a default.
+No additional highlighting is applied to the given context.  It is not
+useful for this to appear with other types of highlighting; it is used to
+override a default.  Any inherited highlighting is retained so for example,
+with tt(region:none), highlighting associated with tt(default) is still used
+for the region.
+)
+item(tt(reset))(
+The terminal's default highlighting is applied to the given context.
+This can be useful as a way to clear all inherited highlighting, so
+may be used before naming other types of highlighting.
 )
 item(tt(fg=)var(colour))(
 The foreground colour should be set to var(colour), a decimal integer,
@@ -2888,12 +2899,20 @@ the associative array tt(.zle.hlgroups) to determine the actual highlighting.
 item(tt(layer=)var(layer))(
 The layer is used to determine precedence when multiple highlighting regions
 overlap. The var(layer) is a decimal integer, with higher numbers taking
-precedence over lower numbers. The default layer is 10 with 30 used as the
-default for tt(special), 20 for tt(region) and tt(isearch) and 15 for
-tt(paste).
-)
+precedence over lower numbers. This cannot be used with the tt(default) and
+tt(ellipsis) fields of tt(zle_highlight) because they treated as base layers.
+With the other fields 30 applies by default for tt(special), 20 for tt(region)
+and tt(isearch) and 15 for tt(paste). Highlighting defined in
+tt(region_highlight) defaults to layer 10 and would take precedence over
+highlighting for any fields of tt(zle_highlight) that are assigned to the same
+layer.)
 enditem()
 
+In addition, the simple highlighting types can be prefixed with tt("no") to
+explicitly disable them. This is useful where highlighting is merged with
+inherited highlighting from other definitions. Note that tt(nobold) selects a
+normal font weight so also has the effect of disabling tt(faint).
+
 The characters described above as `special' are as follows.  The
 formatting described here is used irrespective of whether the characters
 are highlighted: