From 44c840500042ae97a5257560bed8a05ec55a6893 Mon Sep 17 00:00:00 2001
From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Date: Tue, 5 May 2026 18:16:36 -0500
Subject: [PATCH] doc/nethack.6: Revise primary synopsis

Set it as a hanging paragraph, as is idiomatic for Unix command
synopses.  Tighten formatting: set synopsis syntax characters adjacently
to operands.  Also drop explicit line breaks, permitting synopsis to
exercise the configured line length of the selected output device.

Temporarily disable adjustment in a manner more friendly to the system's
(or user's) configuration.[1]  Stop attempting to manipulate
hyphenation; there's no portable way to do that.[2]

Before and after, as rendered with Solaris 10, DWB 3.3, and Plan 9
troffs:

-     nethack [ -d|--directory directory ] [ -w|--windowtype
-     interface ]
-     [ --nethackrc:rc-file | --no-nethackrc ] [ -n ] [ -dec |
-     -ibm ]
-     [ -u player-name ] [ -X | -D ] [ -p profession ] [ -r race ]
-     [ -@ ]
+     nethack [-d|--directory directory]
+          [-w|--windowtype interface]
+          [--nethackrc:rc-file|--no-nethackrc] [-n] [-dec|-ibm]
+          [-u player-name] [-X|-D] [-p profession] [-r race] [-@]

Not shown: Literal text is in bold, and option arguments in italics.

(Full disclosure: The aforementioned formatters use different page
offsets [left margin sizes], and Plan 9 nroff doesn't render _any_
typeface changes, ever, for any document using any macro package.)

Before and after, as rendered with groff, mandoc, and Heirloom Doctools
troff:

-       [ --nethackrc:rc-file | --no-nethackrc ] [ -n ] [ -dec | -ibm ]
-       [ -u player-name ] [ -X | -D ] [ -p profession ] [ -r race ] [ -@ ]
+       nethack [-d|--directory directory] [-w|--windowtype interface]
+              [--nethackrc:rc-file|--no-nethackrc] [-n] [-dec|-ibm]
+              [-u player-name] [-X|-D] [-p profession] [-r race] [-@]

(Full disclosure: groff 1.24.x man(7) uses a default line length of
80n,[3] up from the 78n of its previous releases going back to 2002, and
used by Heirloom Doctools and mandoc.)

[1] https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/tmac/an.tmac?h=1.24.1#n159
[2] https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/tmac/an.tmac?h=1.24.1#n202
[3] https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/NEWS?h=1.24.1#n509
---
 doc/nethack.6 | 68 ++++++++++++++++-----------------------------------
 1 file changed, 21 insertions(+), 47 deletions(-)

diff --git a/doc/nethack.6 b/doc/nethack.6
index 45e8dc011..1944df6a4 100644
--- a/doc/nethack.6
+++ b/doc/nethack.6
@@ -51,54 +51,29 @@
 .SH NAME
 nethack \- Exploring The Mazes of Menace
 .SH SYNOPSIS
+.HP
+.nr sA \n(.j \" Save the adjustment mode.
 .na
-.hy 0
-.\" Some options ordering is explicit (-d first, -u before -D), others
-.\" have been arranged to fit within an 80-column page with nearly full
-.\" lines while avoiding splitting "[" and "-opt ]" or "[ -opt" and "]"
-.\" across line boundaries.  It would be better to do that with 'roff magic.
 .B nethack
-[
-.BR \-d | \-\-directory
-.I directory
-]
-.\" '.B token newline .I token' will include a space between the two tokens;
-.\" '.BI token token' will not.  Likewise for .BR, .RB, &c.
-[
-.BR \-w | \-\-windowtype
-.I interface
-]
-.br
-[
-.BI \-\-nethackrc: rc-file
-|
-.B \-\-no\-nethackrc
-]
-[
-.B \-n
-]
-[
-.BR \-dec " | " \-ibm
-]
-.br
-[
-.B \-u
-.I player-name
-]
-[
-.BR \-X " | " \-D
-]
-[
-.B \-p
-.I profession
-]
-[
-.B \-r
-.I race
-]
-[
-.B \-@
+.RB [ \-d | \-\-directory\*_\c
+.IR directory ]
+.RB [ \-w | \-\-windowtype\*_\c
+.IR interface ]
+\%[\c
+.BI \-\-nethackrc: rc-file\c
+|\c
+.B \-\-no\-nethackrc\c
 ]
+.RB [ \-n ]
+.RB [ \-dec | \-ibm ]
+.RB [ \-u\*_\c
+.IR player-name ]
+.RB [ \-X | \-D ]
+.RB [ \-p\*_\c
+.IR profession ]
+.RB [ \-r\*_\c
+.IR race ]
+.RB [ \-@ ]
 .PP
 Also
 [
@@ -150,8 +125,7 @@ Also
 .B nethack
 .BR \-\-version [ :copy | :dump\c
 .RB | :show ]
-.ad
-.hy 14
+.ad \n(sA \" Restore the adjustment mode.
 .\" Make sure path is not hyphenated below
 .hw nethackdir
 .SH DESCRIPTION