[PATCH 00/31]: revise man pages
"G. Branden Robinson" <[email protected]> Thu, 23 Apr 2026 17:53:22 -0500
| Newsgroups | gmane.editors.nano.devel |
|---|---|
| Message-ID | <20260423225322.pm5am3nlugiwhwgo@illithid> |
Hi folks,
I have some revisions to propose to nano's man pages. They do a variety
of things, summarized below; I attempted to sort what seemed like the
most "correct" and/or least subjective ones first.
My objectives were to make the man pages more idiomatic as I understand
historical and contemporary composition practices, to exercise groff
man(7) features I believe to be of value to composers and human readers
of man pages, and to improve consistency among the documents internally
and with nano's Texinfo manual. All of this has the ultimate objective
of being helpful to nano users.
Summary:
$ git log --reverse --oneline origin..HEAD
b89b6802 docs: sync rnano's synopsis markup with nano's
6254d8ff docs: add a synopsis to rnano(1)
98c5e430 docs: drop blank lines from man pages
70f09f1f docs: replace `sp` requests with `P` or `IP` calls
0e64f6f4 docs: move `hw` and update request invocation
bbd8f31e docs: use `EX`/`EE` calls for monospaced examples
1372fb2e docs: employ `UR`, `UE`, `MT`, `ME` macros
9619a683 docs: use idiomatic *roff ellipsis
2fe71b94 docs: use groff-style special character syntax
56ca7acd docs: fix unescaped hyphens in literals
5d8ccf49 docs: favor groff `\[dq]` over multiple " marks
fee738ac docs: favor `\[ha]` special character over `^`
3fc011c1 docs: favor `\[ti]` special character over `~`
5a1295e1 docs: style function names with bold not backticks
6eca6e93 docs: consistently set file names in italics
6a85cba7 docs: consistently set "nano" command name in bold
4cd39c76 docs: set inline literal in bold
25b4a695 docs: set "foreign" software in italics, not bold
e8d8221e docs: set signal, environment var names in italics
57a547d0 docs: consistently use minus sign for M- notation
76061ed3 docs: "e.g." takes a comma afterward
e6eca59a docs: use typographer's quotation marks
102fc25f docs: quote inline multiword literals
59c3bd9a docs: stack multiple paragraph tags with `TQ` call
3ac2a938 docs: migrate command synopses to SY/YS macros
16d756cc docs: revise man page footers
9c007142 docs: demote uncommon section heads to subsections
dbe05646 docs: downcase man page identifiers, section heads
9deea22b docs: parallelize wording between man pages
8851dc86 docs: migrate man pages to hyperlinking MR macro
f77500de docs: apply "poor man's keeps"
Attachments:
1. a PDF of nano's man pages for U.S. letter paper
2. a PDF of nano's man pages for A4 paper
3. a gzipped tar archive of the documents after each patch, rendered
for the terminal and produced with:
nroff -dAD=l -man -T utf8 doc/*.[15]
...which can be productively reviewed with
diff -u GBR{00,01} | less -R
and so forth. Some patches produce no visible difference in
rendering.
Individual patches are forthcoming.
I welcome feedback and commentary.
Regards,
Branden
nano-man-us-letter.pdf
(application/pdf, 64.3 KB) - not displayed
nano-man-a4.pdf
(application/pdf, 64.1 KB) - not displayed
nano-man-utf8-sgr.tar.gz
(application/gzip, 612.1 KB) - not displayed