Update Guidebook with menucolor docs

doc/Guidebook.mn

@@ -2051,6 +2051,9 @@ An obsolete synonym for ``gender:male''.
 Cannot be set with the `O' command.
 .lp mention_walls
 Give feedback when walking against a wall (default off).
+.lp menucolors
+Enable coloring menu lines (default off).
+See ``Configuring Menu Colors'' on how to configure the colors.
 .lp menustyle
 Controls the interface used when you need to choose various objects (in
 response to the Drop command, for instance).  The value specified should
@@ -2604,6 +2607,56 @@ The second example results in the exclusion of any corpse from autopickup.
 The last example results in the exclusion of items known to be cursed from
 autopickup.
 .hn 2
+Configuring Menu Colors
+.pg
+Some platforms allow you to define colors used in menu lines when the
+line matches a user-defined pattern. At this time the tty, win32tty and
+win32gui support this.
+.pg
+In general, the config file entries to configure the menu color mappings
+look like this:
+.si
+.lp MENUCOLOR="pattern"=color&attribute
+.ei
+.PS "menu color"
+.PL pattern
+the pattern to match;
+.PL color
+the color to use for lines matching the pattern;
+.PL attribute
+the attribute to use for lines matching the pattern. The attribute is
+optional, and if left out, you must also leave out the preceding ampersand.
+If no attribute is defined, no attribute is used.
+.PE
+.lp ""
+For explanation on pattern format and the matching routines, see
+the pattern in the ``Configuring User Sounds'' -section.
+.lp ""
+Allowed colors are black, red, green, brown, blue, magenta, cyan, gray,
+orange, lightgreen, yellow, lightblue, lightmagenta, lightcyan, and white.
+.lp ""
+Allowed attributes are none, bold, dim, underline, blink, and inverse.
+Note that the platform used may interpret the attributes any way it
+wants.
+.lp ""
+Here's an example of menu colors using NetHack's internal
+pattern matching facility:
+.sd
+.si
+MENUCOLOR="* blessed *"=green
+MENUCOLOR="* cursed *"=red
+MENUCOLOR="* cursed *(being worn)"=red&underline
+.ei
+.ed
+specifies that any menu line with " blessed " contained
+in it will be shown in green color, lines with " cursed " will be
+shown in red, and lines with " cursed " followed by "(being worn)"
+on the same line will be shown in red color and underlined.
+You can have multiple MENUCOLOR entries in your config file,
+and the last MENUCOLOR-line in your config file that matches
+a menu line will be used for the line.
+.pg
+.hn 2
 Configuring User Sounds
 .pg
 Some platforms allow you to define sound files to be played when a message 

doc/Guidebook.tex

@@ -2479,6 +2479,10 @@ An obsolete synonym for ``{\tt gender:male}''.  Cannot be set with the
 \item[\ib{mention\_walls}]
 Give feedback when walking against a wall (default off).
 %.lp
+\item[\ib{menucolors}]
+Enable coloring menu lines (default off).
+See ``{\it Configuring Menu Colors\/}'' on how to configure the colors.
+%.lp
 \item[\ib{menustyle}]
 Controls the interface used when you need to choose various objects (in
 response to the Drop command, for instance).  The value specified should
@@ -3141,6 +3145,71 @@ The second example results in the exclusion of any corpse from autopickup.
 The last example results in the exclusion of items known to be cursed from
 autopickup.
 
+%.lp
+%.hn 2
+\subsection*{Configuring Menu Colors}
+
+%.pg
+Some platforms allow you to define colors used in menu lines when the
+line matches a user-defined pattern. At this time the tty, win32tty and
+win32gui support this.
+
+%.pg
+In general, the config file entries to configure the menu color mappings
+look like this:
+\begin{verbatim}
+    MENUCOLOR="pattern"=color&attribute
+\end{verbatim}
+
+\blist{}
+%.lp
+\item[\ib{pattern}]
+the pattern to match;
+%.lp
+\item[\ib{color}]
+the color to use for lines matching the pattern;
+%.lp
+\item[\ib{attribute}]
+the attribute to use for lines matching the pattern. The attribute is
+optional, and if left out, you must also leave out the preceding ampersand.
+If no attribute is defined, no attribute is used.
+\elist
+
+%.lp ""
+For explanation on pattern format and the matching routines, see
+the pattern in the {\it Configuring User Sounds} -section.
+
+%.lp ""
+Allowed colors are {\it black}, {\it red}, {\it green}, {\it brown},
+{\it blue}, {\it magenta}, {\it cyan}, {\it gray}, {\it orange},
+{\it lightgreen}, {\it yellow}, {\it lightblue}, {\it lightmagenta},
+{\it lightcyan}, and {\it white}.
+
+%.lp ""
+Allowed attributes are {\it none}, {\it bold}, {\it dim}, {\it underline},
+{\it blink}, and {\it inverse}.
+Note that the platform used may interpret the attributes any way it
+wants.
+
+%.lp ""
+Here's an example of menu colors using NetHack's internal
+pattern matching facility:
+
+\begin{verbatim}
+    MENUCOLOR="* blessed *"=green
+    MENUCOLOR="* cursed *"=red
+    MENUCOLOR="* cursed *(being worn)"=red&underline
+\end{verbatim}
+
+specifies that any menu line with " blessed " contained
+in it will be shown in green color, lines with " cursed " will be
+shown in red, and lines with " cursed " followed by "(being worn)"
+on the same line will be shown in red color and underlined.
+You can have multiple MENUCOLOR entries in your config file,
+and the last MENUCOLOR-line in your config file that matches
+a menu line will be used for the line.
+%.pg
+
 %.lp
 %.hn 2
 \subsection*{Configuring User Sounds}