From 561d08e53b4ef50851d6dbe64addec7e72af1e7e Mon Sep 17 00:00:00 2001
From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Date: Tue, 5 May 2026 19:23:30 -0500
Subject: [PATCH] doc/*.6: Improve formatting of carets
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

...on typesetters and UTF-8 terminals.

groff_man_style(7):
   Portability
...
     Several special characters are also widely portable.  Except for
     \-, \[em], and \[ga], AT&T troff did not consistently define the
     characters listed below, but its descendants, like DWB, Plan 9, or
     Solaris troff, can be made to support them by defining them in font
     description files, making them aliases of existing glyphs if
     necessary; see groff_font(5).  groff’s extended notation for
     special characters, \[xx], is also supported by mandoc(1), Heirloom
     Doctools troff, and neatroff, but not DWB, Plan 9, or Solaris
     troffs.
...
     \[ha]  Basic Latin circumflex accent (“hat”).  Some output devices
            format “^” as U+02C6 (modifier letter circumflex accent).
Notes
     Some tips on composing and troubleshooting your man pages follow.
...
     • Escape sequences of the form \[xx] don’t format correctly.

       The \[xx] special character escape sequence is a GNU troff
       extension also supported by mandoc, Heirloom Doctools troff, and
       neatroff.  DWB, Plan 9, and Solaris troffs don’t implement it.
       If your man page requires portability to these formatters, spell
       such escape sequences as “\(xx”; no closing parenthesis is used.
       xx must be exactly two characters; groff_char(7) lists portable
       special character identifiers.
---
 doc/dlb.6      | 14 ++++++++------
 doc/makedefs.6 | 16 +++++++++-------
 doc/recover.6  | 16 +++++++++-------
 3 files changed, 26 insertions(+), 20 deletions(-)

diff --git a/doc/dlb.6 b/doc/dlb.6
index c002537ce..e314989d2 100644
--- a/doc/dlb.6
+++ b/doc/dlb.6
@@ -11,6 +11,8 @@
 ..
 .NB $NHDT-Branch: keni-gitset $
 .NR $NHDT-Revision: 1.13 $
+.ie \n(.g .ds ^ \(ha
+.el       .ds ^ ^
 .\" groff and AT&T-descended troffs use different hyphenation patterns. 
 .\" Don't hyphenate the last word on a page or column, or
 .\" before/after last/first 2 characters of a word.
@@ -69,18 +71,18 @@ Unlike
 is configured with a default set of file names to process.
 .ig
 .PP
-^?ALLDOCS
+\*^?ALLDOCS
 This facility is optional and may be excluded during NetHack
 configuration.
-^:
-^?DLB
+\*^:
+\*^?DLB
 This facility is optional but is included in this NetHack
 configuration.
-^:
+\*^:
 This facility is optional and was excluded from this NetHack
 configuration.
-^.
-^.
+\*^.
+\*^.
 ..
 .SS Operations
 .B c
diff --git a/doc/makedefs.6 b/doc/makedefs.6
index c9e617db6..9c33ef6e3 100644
--- a/doc/makedefs.6
+++ b/doc/makedefs.6
@@ -10,6 +10,8 @@
 ..
 .NB $NHDT-Branch: NetHack-5 $
 .NR $NHDT-Revision: 1.22 $
+.ie \n(.g .ds ^ \(ha
+.el       .ds ^ ^
 .\" groff and AT&T-descended troffs use different hyphenation patterns.
 .\" Don't hyphenate the last word on a page or column, or
 .\" before/after last/first 2 characters of a word.
@@ -220,7 +222,7 @@ The default conditional state is printing enabled.
 .IP - 4
 Any line
 .I NOT
-starting with a caret (^) is either suppressed or passed through unchanged
+starting with a caret (\*^) is either suppressed or passed through unchanged
 depending on the current conditional state.
 .IP - 4
 Any line starting with a caret is a control line; as in C, zero or more spaces
@@ -243,21 +245,21 @@ configuration are different from unknown.
 .P
 Control lines:
 .RS
-.IP ^^ 4
+.IP \*^\*^ 4
 a line starting with a (single) literal caret
-.IP ^#
+.IP \*^#
 a comment
-.IP ^?\fIID
+.IP \*^?\fIID
 if the
 .I ID
 is defined set the conditional state to TRUE
-.IP ^!\fIID
+.IP \*^!\fIID
 if the
 .I ID
 is not defined set the conditional state to TRUE
-.IP ^:
+.IP \*^:
 else; invert the conditional state
-.IP ^.
+.IP \*^.
 end the most recent conditional
 .RE
 .\".SH EXAMPLES
diff --git a/doc/recover.6 b/doc/recover.6
index 1fcdff662..5d78684ee 100644
--- a/doc/recover.6
+++ b/doc/recover.6
@@ -10,7 +10,9 @@
 ..
 .NB $NHDT-Branch: NetHack-5 $
 .NR $NHDT-Revision: 1.12 $
-.\" groff and AT&T-descended troffs use different hyphenation patterns. 
+.ie \n(.g .ds ^ \(ha
+.el       .ds ^ ^
+.\" groff and AT&T-descended troffs use different hyphenation patterns.
 .\" Don't hyphenate the last word on a page or column, or
 .\" before/after last/first 2 characters of a word.
 .ie \n(.g .hy 12
@@ -49,26 +51,26 @@ specified by the game administrator during compilation
 (usually /usr/games/lib/nethackdir).
 .ig
 .PP
-^?ALLDOCS
+\*^?ALLDOCS
 For recovery to be possible,
 .I nethack
 must have been compiled with the INSURANCE option, and the run-time option
 .I checkpoint
 must also have been on.
-^:
-^?INSURANCE
+\*^:
+\*^?INSURANCE
 For recovery to be possible,
 .I nethack
 must have been compiled with the INSURANCE option (this configuration was),
 and the run-time option
 .I checkpoint
 must also have been on.
-^:
+\*^:
 This configuration of
 .I nethack
 was created without support for recovery.
-^.
-^.
+\*^.
+\*^.
 ..
 NetHack normally writes out files for levels as the player leaves them,
 so they will be ready for return visits.