Define strings for directional single quotation marks.
groff_man_style(7):
Notes
Some tips on composing and troubleshooting your man pages follow.
...
• When and how should I use quotation marks?
...
Obtaining directional single quotation marks is more of a
challenge. Historically, man pages used ` and ', which troff
rendered on typesetters as ‘ and ’, exclusively for them.
However, in recent years, some distributors of groff have chosen
to override the meanings of these characters in man pages,
remapping them to their Unicode Basic Latin code points.
Unfortunately, ` and ' are the only reliable means of obtaining
directional single quotation marks in AT&T troff; in that
implementation, often no special character escape sequences exist
to obtain them. Further, AT&T troff’s special character
identifiers, like its font names, were device‐specific. To
achieve quotation portably in man pages rendered both by AT&T and
more modern troffs, consider adding a preamble to your page after
the TH call as follows.
.ie \n(.g \{\
. ds oq \[oq]\"
. ds cq \[cq]\"
.\}
.el \{\
. ds oq `\"
. ds cq '\"
.\}
You must then use the \* escape sequence to interpolate the
quotation mark strings.
The command
.RB \*(oq "while !\& git pull; do sleep 10; done" \*(cq
retries an update from the repository until it succeeds.
If this procedure seems complex, petition your distributor to
revert their remapping of the ` and ' characters.
Unbreakable spaces in AT&T troff were always non-adjustable.
Define a string to use groff's `\~` extension if possible.
groff_man_style(7):
Portability
...
\~ Adjustable non‐breaking space. Use this escape sequence
to prevent a break inside a short phrase or between a
numerical quantity and its corresponding unit(s).
Before starting the motor,
set the output speed to\~1.
There are 1,024\~bytes in 1\~KiB.
CSTR\~#8 documents the B\~language.
\~ is a GNU extension also supported by Heirloom Doctools
troff 050915 (September 2005), mandoc 1.9.14
(2009‐11‐16), neatroff (commit 1c6ab0f6e, 2016‐09‐13),
and Plan 9 from User Space troff (commit 93f8143600,
2022‐08‐12), but not by DWB or Solaris troffs.
Fixes bad rendering in DWB 3.3 troff:
@@ -999 +999 @@
- file. -s|-s~-v may also be followed by arguments -p
+ file. -s|-s -v may also be followed by arguments -p
@@ -1005 +1005 @@
- entries which match both. -s|-s~-v may be followed by one
+ entries which match both. -s|-s -v may be followed by one
Solaris 10 troff _would_ misrender as well, but a different portability
problem keeps some of the foregoing text from rendering at all.
Old *roffs don't support the `ti` special character. Compensate.
Before (DWB, Solaris 10):
The --nethackrc:RC-file option will use RC-file instead of
the default run-time configuration file (typically
/.nethackrc) and the --no-nethackrc option can be used to
skip any run-time configuration file.
Before (Plan 9):
The --nethackrc:RC-file option will use RC-file instead of
the default run-time configuration file (typically
ti/.nethackrc) and the --no-nethackrc option can be used to
skip any run-time configuration file.
After (all):
The --nethackrc:RC-file option will use RC-file instead of
the default run-time configuration file (typically
~/.nethackrc) and the --no-nethackrc option can be used to
skip any run-time configuration file.
Favor the very old `lq` and `rq` extension _strings_ over special
characters of the same name. This fixes missing punctuation and text
when rendering this document with DWB and Solaris 10 nroffs, and
misrendered text with Plan 9 nroff.
Before (DWB, Solaris 10):
discovery mode (also known as explore mode). -D will start
the game in debug mode (also known as wizard mode) after
changing the character name to wizard, if the player is
allowed. Otherwise it will switch to -X. Control of who is
allowed to use debug mode is done via the
Before (Plan 9):
discovery mode (also known as explore mode). -D will start
the game in debug mode (also known as wizard mode) after
changing the character name to lqwizardrq, if the player is
allowed. Otherwise it will switch to -X. Control of who is
allowed to use debug mode is done via the lqWIZARDS=rq line in
NetHack's sysconf file.
After (all):
The -X option will start the game in a special non-scoring
discovery mode (also known as explore mode). -D will start
the game in debug mode (also known as wizard mode) after
changing the character name to "wizard", if the player is
allowed. Otherwise it will switch to -X. Control of who is
allowed to use debug mode is done via the "WIZARDS=" line in
NetHack's sysconf file.
(There are minor differences in the page offset amount, and Plan 9 uses
UTF-8 double quotation marks, U+201C and U+201D.)
groff_man(7):
Strings
The following strings are defined for use in man pages. None of
these is necessary in a contemporary man page; see
groff_man_style(7). ...
...
\*(lq
\*(rq interpolate special character escape sequences for left and
right double‐quotation marks, \(lq and \(rq, respectively.
(I see that I should reword the foregoing to something like "None is
necessary in man pages targeting only contemporary *roff formatters".)
History
... 4BSD (1980) added lq and rq strings. ... Unix System V (1988)
incorporated the lq and rq strings.
Except for EX/EE, James Clark implemented the foregoing features in
early versions of groff. ... Plan 9 from User Space’s troff ...
incorporated the lq and rq strings in 2025.
groff_man_style(7):
Notes
Some tips on composing and troubleshooting your man pages follow.
...
• When and how should I use quotation marks?
As noted above in subsection “Font style macros”, apply quotation
marks to “brief specimens of literal text, such as article
titles, inline examples, mentions of individual characters or
short strings, and (sub)section headings in man pages”. Multi‐
word literals, such as Unix commands with arguments, when set
inline (as opposed to displayed between EX and EE), should be
quoted to ensure that the boundaries of the literal are clear
even when the material is stripped of font styling by, for
example, copy‐and‐paste operations. groff, Heirloom Doctools
troff, neatroff, and mandoc support all of the special characters
\[oq], \[cq], \[lq], \[rq], \[aq], and \[dq] described in
subsection “Portability” above. DWB, Plan 9, and Solaris troffs
do not. Interpolating the strings \*(lq and \*(rq portably
yields directional double quotation marks, if available, in all
these formatters (though neatroff does not supply a man macro
package), but they cannot reliably be used in macro arguments.
Per the final sentence above, do a little dance to avoid using these
strings in macro arguments.
Paragraphing macros in *roff systems generally break the output line,
and the same is true of all of man(7)'s paragraphing macros.
groff_man(7):
Paragraphing macros
These macros break the output line. An ordinary paragraph (P)
indents all output lines by the same amount. A hanging paragraph
(HP) is a cosmetic variant of P with a hanging indent. Definition
lists frequently occur in man pages; these can be set as tagged
paragraphs, which have one (TP) or more (TQ) leading tags followed
by a paragraph that has an additional indentation.
NetHack's man pages already preponderantly use man(7) `IR` macro for
this purpose. Align outliers.
The "SEE ALSO" section of doc/mn.7 is a partial exception. While the
rest of the document sets cross-referenced man page topics in italics,
this section of the page does not. It seems likely that this decision
was made in deliberate imitation of Seventh Edition Unix manuals (1979)
or their descendants in USG/USL and BSD Unices. That feature of the
Unix man pages, however, was not deliberate per Doug McIlroy, the author
of the man(7) macros and editor of Volume 1 of the Seventh Edition Unix
Programmer's Manual, per his communication on the groff mailing list.
But NetHack has a policy of not modifying Matt Bishop's "mn" macro
file or its man page, so I leave that exception in place.
References:
https://lists.gnu.org/archive/html/groff/2021-08/msg00023.htmlhttps://lists.gnu.org/archive/html/groff/2021-08/msg00040.htmlhttps://github.com/NetHack/NetHack/pull/977#issuecomment-1424996578
Sectioning and paragraphing macros always break the output line.
(Sub)sectioning macros always set text after the heading as a paragraph.
Fixes:
$ mandoc -T lint doc/*.[67] # output edited
doc/makedefs.6:49:2: WARNING: skipping paragraph macro: PP after SH
doc/nethack.6:367:2: WARNING: skipping paragraph macro: br after PP
doc/nethack.6:365:2: WARNING: skipping paragraph macro: PP empty
doc/nethack.6:157:2: WARNING: skipping paragraph macro: PP after SH
doc/nethack.6:431:2: WARNING: skipping paragraph macro: PP after SH
doc/nethack.6:673:2: WARNING: skipping paragraph macro: PP after SH
doc/nethack.6:676:2: WARNING: skipping paragraph macro: PP after SH
doc/recover.6:29:2: WARNING: skipping paragraph macro: PP after SH
doc/recover.6:125:2: WARNING: skipping paragraph macro: PP after SH
doc/recover.6:141:2: WARNING: skipping paragraph macro: PP after SH
doc/mnh.7:23:2: WARNING: skipping paragraph macro: PP after SH
doc/mnh.7:46:2: WARNING: skipping paragraph macro: PP after SH
Explain meaning of stacked paragraph tags naming environment variables.
Drop call of deprecated man(7) `DT` macro and invocation of `ta` request
to set tab stops to attempt table-like layout. (The latter made the
former nilpotent anyway.) Replace this material with calls of tagged
paragraphing macro `TP` and groff man(7)'s `TQ` extension for setting
multiple tags with a paragraph. The result takes up more screen lines,
but renders well with more formatters.
Set indentation of tagged paragraph using a constant numeric expression
to accommodate pseudo-roff formatters that don't implement arithmetic
evaluation. (Some of these ignore _any_ indentation, regardless.)
Slightly recast descriptions of environment variables.
Set file name literals in italics.
Protect file and environment variable names from hyphenation.
Fixes:
an.tmac:doc/nethack.6:608: style: use of deprecated macro: .DT
* Define string to exercise groff's hyphenless break point feature.
This helps with file names and URLs. On formatters that don't claim
compatibility with groff, define the string as nothing, getting the
same result as before (a _highly_ ragged right margin, jarring
adjustment, or overset lines).
* If the formatter does not claim compatibility with groff, define a
copy of groff man(7)'s `TQ` macro to ease stacking of paragraph tags.
* Set file name literals in italics. Stop quoting them (which was
inconsistently done anyway).
* Revise "FILES" section.
- Drop redundant `PP` paragraphing call.
$ mandoc -T lint doc/nethack.6
...
mandoc: doc/nethack.6:432:2: WARNING: skipping paragraph macro: PP after SH
...
groff_man(7):
.SH [heading‐text]
Set heading‐text as a section heading. ... Text lines after
the call are set as an ordinary paragraph (P).
- Drop call of deprecated man(7) `DT` macro and invocation of `ta`
request to set tab stops to attempt table-like layout. (The latter
made the former nilpotent anyway.) Replace this material with calls
of tagged paragraphing macro `TP` and groff man(7)'s `TQ` extension
for setting multiple tags with a paragraph. The result takes up
more screen lines, but renders well with more formatters.
- Fine-tune styling of file names.
groff_man_style(7):
Use italics for file and path names, ... for variant
(user‐replaceable) portions of syntax synopses, ... and
anywhere a parameter requiring replacement by the user is
encountered. An exception involves variant text in a
context already typeset in italics, such as file or path
names with replaceable components; in such cases, follow the
convention of mathematical typography: set the file or path
name in italics as usual but use roman for the variant part
(see IR and RI below), and italics again in running roman
text when referring to the variant material.
Solaris 10, DWB 3.3, and Plan 9 from User Space nroffs formatted the
table of file names and descriptions quite badly.
Before:
nethack The program itself.
Guidebook | Guidebook.txt NetHack's user manual.
data, oracles, rumors Data files used by NetHack.
bogusmon Another data file.
engrave, epitaph, tribute Still more data files.
symbols Data file holding sets of speci-
fications
for how to display monsters,
objects, and
map features.
options Data file containing a descrip-
tion of the
build-time option settings.
help, hh, cmdhelp Help data files. ('cmdhelp' is
obsolete.)
...
Now (pagination on AT&T nroffs is omitted):
nethack
The program itself.
Guidebook
Guidebook.txt
NetHack's user manual.
data
oracles
rumors
Data files used by NetHack.
bogusmon
Another data file.
engrave
epitaph
tribute
Still more data files.
symbols
Data file holding sets of specifications for how to
display monsters, objects, and map features.
options
Data file containing a description of the build-time
option settings.
help
hh
cmdhelp
Help data files. (cmdhelp is obsolete.)
Fixes:
an.tmac:doc/nethack.6:444: style: use of deprecated macro: .DT
Not a serious issue in my opinion, but worth fixing. DWB does not
misrender the document, and the "stack" referred to is not the runtime
stack employed by the operating system, but one in the *roff language
runtime.
The diagnostic appears to be spurious in this case, but it isn't always.
https://github.com/n-t-roff/DWB3.3/issues/10
No *roff known to me interprets arguments to the `br` request. They
don't complain, either, but some day that may change.
https://savannah.gnu.org/bugs/?61450
groff_man_style(7):
• Option dashes are specified with the \- escape sequence; this is
an important practice to make them clearly visible and to
facilitate copy‐and‐paste from the rendered man page to a shell
prompt or text file.
...
\- Minus sign. \- produces the basic Latin hyphen‐minus
(U+002D) specifying Unix command‐line options and frequently
used in file names. “-” is a hyphen in roff; some output
devices format it as U+2010 (hyphen).
...pacifying a warning from the forthcoming groff 1.25.
Fixes:
troff:doc/dlb.6:159: warning: end of sentence detected before end of text line [-w style]
troff:doc/makedefs.6:53: warning: end of sentence detected before end of text line [-w style]
troff:doc/makedefs.6:55: warning: end of sentence detected before end of text line [-w style]
troff:doc/makedefs.6:58: warning: end of sentence detected before end of text line [-w style]
troff:doc/makedefs.6:153: warning: end of sentence detected before end of text line [-w style]
troff:doc/makedefs.6:159: warning: end of sentence detected before end of text line [-w style]
troff:doc/makedefs.6:166: warning: end of sentence detected before end of text line [-w style]
troff:doc/makedefs.6:222: warning: end of sentence detected before end of text line [-w style]
troff:doc/makedefs.6:245: warning: end of sentence detected before end of text line [-w style]
troff:doc/makedefs.6:279: warning: end of sentence detected before end of text line [-w style]
troff:doc/mnh.7:30: warning: end of sentence detected before end of text line [-w style]
troff:doc/nethack.6:225: warning: end of sentence detected before end of text line [-w style]
troff:doc/nethack.6:226: warning: end of sentence detected before end of text line [-w style]
troff:doc/nethack.6:230: warning: end of sentence detected before end of text line [-w style]
troff:doc/nethack.6:234: warning: end of sentence detected before end of text line [-w style]
troff:doc/nethack.6:236: warning: end of sentence detected before end of text line [-w style]
troff:doc/nethack.6:524: warning: end of sentence detected before end of text line [-w style]
troff:doc/nethack.6:577: warning: end of sentence detected before end of text line [-w style]
troff:doc/recover.6:155: warning: end of sentence detected before end of text line [-w style]
Aligns with other NetHack man pages and fixes:
$ nroff -ww -z -rCHECKSTYLE=4 -man doc/*.[67]
an.tmac:doc/mnh.7:2: style: .TH missing fourth argument; suggest package/project name and version (e.g., "groff 1.23.0")
Replace instances of blank line paragraphing with `PP` macro calls.
There are three problems with the style of paragraphing that this commit
fixes.
1. A `br` break request is redundant with an adjacent blank text line.
2. A `br` request is also redundant with a paragraphing macro call.
3. When you use a paragraphing macro call instead of a blank text line,
you get the configured amount inter-paragraph space. When
typesetting with the man(7) package, the default inter-paragraph
space amount is 0.4v. A blank text line usually puts 1v of empty
space into the document.
See groff_man_style(7).
Fixes:
$ nroff -ww -z -rCHECKSTYLE=4 -man doc/*.[67]
an.tmac:doc/nethack.6:435: style: blank line in input
an.tmac:doc/nethack.6:442: style: blank line in input
an.tmac:doc/nethack.6:535: style: blank line in input
an.tmac:doc/nethack.6:539: style: blank line in input
an.tmac:doc/nethack.6:543: style: blank line in input
an.tmac:doc/nethack.6:568: style: blank line in input
an.tmac:doc/nethack.6:572: style: blank line in input
Unix terminal drivers started transitioning away from paper terminals
and toward video terminals, and therefore away from '#' and '@' as the
"erase" and "kill" characters, respectively, before NetHack was born.
groff_man_style(7):
Portability
...
\e Format the roff escape character on the output; widely
used in man pages to render a backslash glyph. It works
reliably as long as the “ec” request is not used, which
should never happen in man pages, and it is slightly more
portable than the more explicit \[rs] (“reverse solidus”)
special character escape sequence.
This change's purpose is to put things right in case the change I'm
proposing next to delete this language entirely gets reverted.
Also fix a case hidden by a comment.
Fixes:
$ nroff -ww -z -man doc/*.[67]
troff:doc/nethack.6:68: warning: escape character ignored before '@'
troff:doc/nethack.6:292: warning: escape character ignored before '@'
Fixes four issues that prevented `make WANT_LIBNH=1 all` from producing
a libnh.a that could be linked into a host program on macOS. Before
these patches, it built but the resulting archive was unusable: macOS
ld errored on a nested liblua archive member, was missing date.o and
hacklib symbols (`populate_nomakedefs`, `eos`, `lcase`, `mungspaces`,
...), and had duplicate definitions of `main`, `whoami`, etc.
Specific changes:
1. sys/libnh/libnhmain.c: drop `static` on `whoami()`. src/earlyarg.c
declares it `extern` and calls it from `scores_only()`; the static
makes it file-local and that reference goes unresolved.
2. sys/libnh/libnhmain.c: gate the emscripten-only code in get_nhuuid
with `#ifdef __EMSCRIPTEN__` instead of `#ifdef NHUUID`. The macOS
hints define NHUUID for the libnh build (they did so unconditionally
before NO_NHUUID even existed), so on native builds the compiler
tried to call `emscripten_run_script_int` / `_string` and failed
with implicit-function-declaration errors. __EMSCRIPTEN__ is the
real signal for "this is being cross-compiled to WASM."
3. sys/unix/hints/macOS.500: in the WANT_LIBNH block, add an explicit
`recover: lua_support` dependency (gated by MAKEFILE_TOP). When
$(GAME) is overridden to empty, the regular `recover: $(GAME)` chain
no longer triggers `lua_support`, so include/nhlua.h never gets
generated and recover.c's transitive #include of hack.h fails.
4. sys/unix/hints/macOS.500: rewrite the libnh.a rule. The previous
`ar rcs libnh.a $(HOBJ) $(LIBNHSYSOBJ) liblua-$(LUA_VERSION).a` had
four problems: (a) ar archives liblua.a as a single opaque member
that macOS ld can't dereference, (b) date.o (DATE_O, kept separate
from HOBJ) was never archived, so `populate_nomakedefs` and
`nomakedefs` were missing, (c) hacklib.a was likewise omitted, and
(d) HOBJ already contains $(SYSOBJ) (with unixmain.o) and $(WINOBJ)
(the tty windowport), which duplicated symbols from libnhmain.o /
winshim.o.
The fix uses `libtool -static` so hacklib.a and liblua's archive
have their members merged rather than nested, depends on $(LUALIB)
so lua_support runs first, includes $(DATE_O) and $(TARGET_HACKLIB),
and uses $(filter-out $(SYSOBJ) $(WINOBJ),$(HOBJ)) to drop the
duplicates.
Verified by clean rebuild on macOS 26 (arm64, Apple clang 17):
make spotless
make fetch-Lua
make WANT_LIBNH=1 all
and link-tested with a tiny harness that calls
shim_graphics_set_callback() against the resulting libnh.a.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Bug report stated:
"If 'mention_decor' is set in config file or NETHACKOPTIONS,
starting the game tells you that you are standing on stairs
which lead out of the dungeon. But if you also start the
tutorial, you won't be on those stairs--they won't even exist
until the tutorial is exited.
The stairs message can't be suppressed until the program
knows whether the tutorial will be entered, and since
prompting is one of the ways to decide that."
What this does:
Don't heed mention_decor option during the primary rcfile()
processing.
Do heed it after the tutorial.
Note:
If mention_decor is expected to actually be active during the
tutorial, then the rcfile_only_this_option(opt_mention_decor)
likely has to be moved to a different line, which should be
easy enough.
The previous fix, while valid, still prompts for input during early
options processing if stdin is a tty. It really shouldn't be doing
that during early options such as --showpaths, so alter the placement
of the program_state.earlyoptions flag within *main().
GitHub issue https://github.com/NetHack/NetHack/issues/1513
Starting a new game, at the
'Shall I pick character's race, role, gender and alignment for you? [ynaq]'
prompt, the game shows as 'Version 5.0.0-0 Unix Work-in-progress'
but then once the game has started and you check #version you see
the correct 'Unix NetHack Version 5.0.0-0 post-release' feedback.
Closes#1513
Try using emscripten_run_script_string("crypto.randomUUID()");
I need to commit this to the repository to test it elsewhere.
If there isn't a revert shortly after this, it must have at least
built without issue.
Detect Workbench depth, display-database MaxDepth, and free chip RAM;
if any signals AMIV can't run (e.g. A1000 with 4-colour WB), swap
windowprocs to amii_procs before opening any screens.
SYSCF is for multi-user system-admin lockdown; single-user Amigas
don't need it, and assure_syscf_file() killing the binary when run
outside NetHack: was breaking normal launches.
Reference __stkinit so the linker pulls swapstack.o from libnix.a;
without it the program runs on the inherited shell stack and crashes
inside Lua / level-gen.
G. Branden Robinson