[PATCH 25/31] docs: migrate command synopses to SY/YS macros

"G. Branden Robinson" <[email protected]> Thu, 23 Apr 2026 18:01:00 -0500
Newsgroups	gmane.editors.nano.devel
Message-ID	<20260423230100.nu6v2yy3lcakoqvd@illithid>
Command synopses can get hairy syntactically because often what they
document is complex.  Use groff man(7)'s `SY` and `YS` extension macros
to improve source document readability and maintainability.

groff_man(7):
   Synopsis macros
     Use SY and YS to summarize syntax using familiar Unix conventions.
     Heirloom Doctools troff (since Git snapshot 151218) and mandoc
     (since 1.14.5) support these GNU extensions; DWB, Plan 9, and
     Solaris troffs do not.

     .SY keyword [suffix]
            Begin synopsis.  Adjustment and automatic hyphenation are
            disabled.  If SY has already been called without a
            corresponding YS, a break is performed.  keyword and any
            suffix are set in bold.  When suffix is present, the package
            sets the next word after it without intervening space.  If a
            break is required in subsequent text (up to a paragraphing,
            sectioning, or YS macro call), lines after the first are
            indented.  Unless the previous synopsis’s indentation is
            reused (see YS below), output lines after the first indent
            by the width of the pending output line up to the end of
            keyword plus a space, if keyword is the only argument, and
            up to the end of suffix otherwise.

     .YS [reuse‐indentation]
            End synopsis, breaking the line and restoring indentation,
            adjustment, and hyphenation to their previous states.  If an
            argument is given, the indentation corresponding to the
            previous SY call is reused by the next SY call instead of
            being computed.
...
   History
...
     ... Later, groff 1.20 (2009) resurrected EX/EE and originated
     SY/YS, TQ, MT/ME, and UR/UE.
...
Authors
...
     ... Lemberg and Eric S. Raymond ⟨[email protected]⟩ contributed
     EX/EE, MT/ME, UR/UE, TQ, and an early version of the SY/YS macros
     to groff 1.20 (2009).  G. Branden Robinson ⟨g.branden.robinson@
     gmail.com⟩ implemented the AD and MF strings; CS, CT, and U
     registers; and the MR macro for groff 1.23 (2023), and the BP, PO,
     and TS registers and a revised implementation of the SY/YS macros
     for groff 1.24 (2026).

While groff man(7) did alter `SY`/`YS` behavior in groff 1.24, the
nano(1) and rnano(1) man pages still render acceptably with older
versions.

$ ~/groff-1.23.0/bin/nroff -man -T utf8 -P -cbou doc/nano.1 \
  doc/rnano.1 | sed -n '/^SYNOPSIS/,/^\(NOTICES\|DESCRIPTION\)/p'
SYNOPSIS
       nano [options] [[+line[,column]] file]...

       nano [options] [[+[crCR]{/|?}string] file]...

NOTICES
SYNOPSIS
       rnano [options] [[+line[,column]] file]...

       rnano [options] [[+[crCR]{/|?}string] file]...

DESCRIPTION
---
 doc/nano.1  | 19 ++++++++++++++++---
 doc/rnano.1 | 19 ++++++++++++++++---
 2 files changed, 32 insertions(+), 6 deletions(-)

diff --git a/doc/nano.1 b/doc/nano.1
index 6376f47d..04a8e0ad 100644
--- a/doc/nano.1
+++ b/doc/nano.1
@@ -24,10 +24,23 @@ .SH NAME
 .hw ncurses quickblank
 .
 .SH SYNOPSIS
-.B nano
-.RI [ options "] [[\fB+" line [\fB, column "]] " file ].\|.\|.
+.SY nano
+.RI [ options ]
+.RB [[ +\c
+.IR line [\c
+.BI , column\c
+]]
+.IR file ].\|.\|.
+.YS
+.
 .P
-.BR nano " [" \fIoptions "] [[" + [ crCR ]{ / | ? } \fIstring "] " \fIfile ].\|.\|.
+.SY nano
+.RI [ options ]
+.RB [[ + [ crCR ]\c
+.RB { / | ? }\c
+.IR string ]
+.IR file ].\|.\|.
+.YS
 .
 .SH NOTICES
 Since version 9.0, all lines are scrolled horizontally together
diff --git a/doc/rnano.1 b/doc/rnano.1
index 4c23ed44..5dd6bf21 100644
--- a/doc/rnano.1
+++ b/doc/rnano.1
@@ -22,10 +22,23 @@ .SH NAME
 rnano \- a restricted nano
 .
 .SH SYNOPSIS
-.B rnano
-.RI [ options "] [[\fB+" line [\fB, column "]] " file ]...
+.SY rnano
+.RI [ options ]
+.RB [[ +\c
+.IR line [\c
+.BI , column\c
+]]
+.IR file ].\|.\|.
+.YS
+.
 .P
-.BR rnano " [" \fIoptions "] [[" + [ crCR ]{ / | ? } \fIstring "] " \fIfile ]...
+.SY rnano
+.RI [ options ]
+.RB [[ + [ crCR ]\c
+.RB { / | ? }\c
+.IR string ]
+.IR file ].\|.\|.
+.YS
 .
 .SH DESCRIPTION
 \fBrnano\fR runs the \fBnano\fR editor in restricted mode.  This allows
-- 
2.30.2
signature.asc (application/pgp-signature, 833 B)