From 749f2ffb0e443411d1dcf189c852b9001e1a14b0 Mon Sep 17 00:00:00 2001
From: PatR <rankin@nethack.org>
Date: Fri, 12 Apr 2024 11:52:26 -0700
Subject: [PATCH] update 'hitpointbar' documentation

---
 doc/Guidebook.mn  | 27 ++++++++++++++++++++++++---
 doc/Guidebook.tex | 29 ++++++++++++++++++++++++++---
 2 files changed, 50 insertions(+), 6 deletions(-)

diff --git a/doc/Guidebook.mn b/doc/Guidebook.mn
index 1df677b4e..0d0232850 100644
--- a/doc/Guidebook.mn
+++ b/doc/Guidebook.mn
@@ -46,7 +46,7 @@
 .ds f0 \*(vr
 .ds f1 \" empty
 .\"DO NOT REMOVE NH_DATESUB .ds f2 DATE(%B %-d, %Y)
-.ds f2 March 21, 2024
+.ds f2 April 12, 2024
 .
 .\" A note on some special characters:
 .\" \(lq = left double quote
@@ -4057,8 +4057,29 @@ In text windowing, text highlighting or inverse video is often used;
 with tiles, generally displays a small plus-symbol beside the object
 on the top of the pile.
 .lp hitpointbar
-Show a hit point bar graph behind your name and title.
-Only available for TTY, Curses, and Windows GUI, and only when statushilites is on.
+Show a hit point bar graph behind your name and title in the status
+display (default off).
+.lp ""
+The \(lqcurses\(rq interface supports it even if the status highlighting
+feature has been disabled when building the program.
+The \(lqtty\(rq and \(lqmswin\(rq (aka \(lqWindows GUI\(rq) interfaces
+support it only if status highlighting is left enabled when building.
+You don't need to set up any highlighting rules in order to display
+the bar.
+If there is one for hitpoints in effect and it specifies color, that
+color will be used for the bar.
+However if it specifies video attributes, they will be ignored in
+favor of \fIinverse\fP.
+For tty and curses, \fIblink\fP will also be used if the current
+hitpoint value is at or below the \fIcritical HP\fP threshold.
+.lp ""
+The \(lqQt\(rq interface also supports hitpointbar, by drawing
+a solid bar above the name and title with a hard-coded color scheme.
+(As of this writing, having the bar enabled unintentionally inhibits
+resizing the status panel.
+To resize that, use the \f(CR#optionsfull\fP command to toggle the
+\fIhitpointbar\fP option off, perform the resize while it's off, then
+use the same command to toggle it back on.)
 .lp horsename
 Name your starting horse (for example \(lqhorsename:Trigger\(rq).
 Cannot be set with the \(oq\f(CRO\fP\(cq command.
diff --git a/doc/Guidebook.tex b/doc/Guidebook.tex
index 1d90e5203..57d69e381 100644
--- a/doc/Guidebook.tex
+++ b/doc/Guidebook.tex
@@ -48,7 +48,7 @@
 \author{Original version - Eric S. Raymond\\
 (Edited and expanded for 3.7.0 by Mike Stephenson and others)}
 %DO NOT REMOVE NH_DATESUB \date{DATE(%B %-d, %Y)}
-\date{March 21, 2024}
+\date{April 12, 2024}
 
 \maketitle
 
@@ -4433,8 +4433,31 @@ with tiles, generally displays a small plus-symbol beside the object
 on the top of the pile.
 %.lp
 \item[\ib{hitpointbar}]
-Show a hit point bar graph behind your name and title.
-Only available for TTY, Curses, and Windows GUI, and only when statushilites is on.
+Show a hit point bar graph behind your name and title in the status
+display (default off).
+\\
+%.lp
+The ``curses'' interface supports it even if the status highlighting
+feature has been disabled when building the program.
+The ``tty'' and ``mswin'' (aka ``Windows GUI'') interfaces
+support it only if status highlighting is left enabled when building.
+You don't need to set up any highlighting rules in order to display
+the bar.
+If there is one for hitpoints in effect and it specifies color, that
+color will be used for the bar.
+However if it specifies video attributes, they will be ignored in
+favor of {\it inverse}.
+For tty and curses, {\it blink\/} will also be used if the current
+hitpoint value is at or below the {\it critical HP\/} threshold.
+\\
+%.lp
+The ``Qt'' interface also supports hitpointbar, by drawing
+a solid bar above the name and title with a hard-coded color scheme.
+(As of this writing, having the bar enabled unintentionally inhibits
+resizing the status panel.
+To resize that, use the {\tt \#optionsfull} command to toggle the
+{\it hitpointbar\/} option off, perform the resize while it's off, then
+use the same command to toggle it back on.)
 %.lp
 \item[\ib{horsename}]
 Name your starting horse (for example, ``{\tt horsename:Trigger}'').