36437: Document interaction of $region_highlight and $zle_highlight.

ChangeLog

@@ -1,5 +1,8 @@
 2015-09-07  Daniel Shahaf  <d.s@daniel.shahaf.name>
 
+	* 36437: Doc/Zsh/zle.yo Src/Zle/zle.h: Document interaction of
+	$region_highlight and $zle_highlight.
+
 	* unposted: Doc/Zsh/zle.yo: ZLE_STATE: fix obvious documentation
 	typo.
 

Doc/Zsh/zle.yo

@@ -955,6 +955,11 @@ any predisplay string should be highlighted in bold.
 
 Note that the effect of tt(region_highlight) is not saved and disappears
 as soon as the line is accepted.
+
+The final highlighting on the command line depends on both tt(region_highlight)
+and tt(zle_highlight); see
+ifzman(the section CHARACTER HIGHLIGHTING below)\
+ifnzman(noderef(Character Highlighting)) for details.
 )
 vindex(UNDO_CHANGE_NO)
 item(tt(UNDO_CHANGE_NO) (integer))(
@@ -2521,6 +2526,12 @@ Following a command to paste text, the characters that were inserted.
 )
 enditem()
 
+When tt(region_highlight) is set, the contexts that describe a region DASH()-
+tt(isearch), tt(region), tt(suffix), and tt(paste) DASH()-
+are applied first, then tt(region_highlight) is applied, then the remaining
+tt(zle_highlight) contexts are applied.  If a particular character is
+affected by multiple specifications, the last specification wins.
+
 tt(zle_highlight) may contain additional fields for controlling how
 terminal sequences to change colours are output.  Each of the following is
 followed by a colon and a string in the same form as for key bindings.

Src/Zle/zle.h

@@ -431,6 +431,8 @@ struct region_highlight {
  * 2: suffix
  * 3: pasted text
  */
+/* If you change this, update the documentation of zle_highlight/region_highlight
+ * interaction in Doc/Zsh/zle.yo. */
 #define N_SPECIAL_HIGHLIGHTS	(4)