Update Guidebook with menucolor docs

diff --git a/doc/Guidebook.mn b/doc/Guidebook.mn
index 4293fdb3e81d332949ebc42c9826a546e7997f9a..89dee0ae061af836f12dfd93c035c4a766a18c29 100644 (file)
--- a/doc/Guidebook.mn
+++ b/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 

diff --git a/doc/Guidebook.tex b/doc/Guidebook.tex
index 5f1ae5e4b215549ac55283cd61363766b68cf69e..67ca18cc18d6583e4fc5ac3a0543c0206e919426 100644 (file)
--- a/doc/Guidebook.tex
+++ b/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}