25052: update docs for use of colour highlighting

ChangeLog

@@ -1,5 +1,9 @@
 2008-05-16  Peter Stephenson  <pws@csr.com>
 
+	* 25052: Doc/Zsh/compctl.yo, Doc/Zsh/compsys.yo,
+	Doc/Zsh/mod_complist.yo, Doc/Zsh/prompt.yo: update some
+	documentation for use of colour highlighting.
+
 	* unposted: Etc/CONTRIBUTORS: update main shell list; still
 	need to update list for functions.
 

Doc/Zsh/compctl.yo

@@ -469,7 +469,8 @@ be shown if there was at least one match added for the explanation
 string.
 
 The sequences tt(%B), tt(%b), tt(%S), tt(%s), tt(%U), and tt(%u) specify
-output attributes (bold, standout, and underline) and tt(%{...%}) can
+output attributes (bold, standout, and underline), tt(%F), tt(%f), tt(%K),
+tt(%k) specify foreground and background colours, and tt(%{...%}) can
 be used to include literal escape sequences as in prompts.
 )
 item(tt(-Y) var(explanation))(

Doc/Zsh/compsys.yo

@@ -1512,9 +1512,15 @@ 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 sequences to
-specify output attributes, such as `tt(%B)', `tt(%S)' and
-`tt(%{)...tt(%})'.
+what these matches are.  This string may also contain the following
+sequences to specify output attributes,
+ifnzman(noderef(Prompt Expansion))\
+ifzman(as described in the section PROMPT EXPANSION 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 tt(%G) sequence is not available; an argument
+to `tt(%{)' should be used instead.
 
 The style is tested with each tag valid for the current completion
 before it is tested for the tt(descriptions) tag.  Hence different format 
@@ -1870,9 +1876,10 @@ width, padded to the  right with spaces, while the lowercase form will
 be replaced by a variable width string.  As in other prompt strings, the
 escape sequences `tt(%S)', `tt(%s)', `tt(%B)', `tt(%b)', `tt(%U)',
 `tt(%u)' for entering and leaving the display modes
-standout, bold and underline are also available, as is the form
+standout, bold and underline, and `tt(%F)', `tt(%f)', `tt(%K)', `tt(%k)' for
+changing the foreground background colour, are also available, as is the form
 `tt(%{)...tt(%})' for enclosing escape sequences which display with zero
-width.
+(or, with a numeric argument, some other) width.
 
 After deleting this prompt the variable tt(LISTPROMPT) should be unset for
 the the removal to take effect.

Doc/Zsh/mod_complist.yo

@@ -160,7 +160,8 @@ To enable scrolling through a completion list, the tt(LISTPROMPT)
 parameter must be set.  Its value will be used as the prompt; if it
 is the empty string, a default prompt will be used.  The value may
 contain escapes of the form `tt(%x)'.  It supports the escapes
-`tt(%B)', `tt(%b)', `tt(%S)', `tt(%s)', `tt(%U)', `tt(%u)' and
+`tt(%B)', `tt(%b)', `tt(%S)', `tt(%s)', `tt(%U)', `tt(%u)', `tt(%F)',
+`tt(%f)', `tt(%K)', `tt(%k)' and
 `tt(%{...%})' used also in shell prompts as well as three pairs of
 additional sequences: a `tt(%l)' or `tt(%L)' is replaced by the number
 of the last line shown and the total number of lines in the form

Doc/Zsh/prompt.yo

@@ -191,7 +191,8 @@ following the tt(%F), for example tt(%F{red}).  In the latter case
 the values allowed are as described for the tt(fg) tt(zle_highlight)
 attribute;
 ifzman(see em(Character Highlighting) in zmanref(zshzle))\
-ifnzman(noderef(Character Highlighting)).
+ifnzman(noderef(Character Highlighting)).  This means that numeric
+colours are allowed in the second format also.
 )
 item(tt(%K) LPAR()tt(%k)RPAR())(
 Start (stop) using a different bacKground colour.  The syntax is