[PATCH 27/31] docs: demote uncommon section heads to subsections

"G. Branden Robinson" <[email protected]> Thu, 23 Apr 2026 18:01:18 -0500
Newsgroups	gmane.editors.nano.devel
Message-ID	<20260423230118.jladgcvqqhtjbv7v@illithid>
Despite their length, nano's man pages did not use the man(7)'s
subsectioning macro `SS` at all.  Employ it to retain familiar man page
section headings and arrange uncommon headings as subsections instead.

Set subsection headings in sentence case, not full capitals.

In nano(1), I contrived a new subsection heading "Summary" for the
material that normally immediately follows the "Description" section
heading.  It's uncommon to start that section with a big admonition, but
I was uncertain about relocating it.
---
 doc/nano.1   | 15 ++++++++-------
 doc/nanorc.5 |  6 +++---
 doc/rnano.1  |  5 +++--
 3 files changed, 14 insertions(+), 12 deletions(-)

diff --git a/doc/nano.1 b/doc/nano.1
index e91487fb..5bf55845 100644
--- a/doc/nano.1
+++ b/doc/nano.1
@@ -42,7 +42,8 @@ .SH SYNOPSIS
 .IR file ].\|.\|.
 .YS
 .
-.SH NOTICES
+.SH DESCRIPTION
+.SS Notices
 Since version 9.0, all lines are scrolled horizontally together
 (when the cursor approaches the edge), by just the amount needed,
 instead of scrolling only the current line by a large step.
@@ -75,9 +76,8 @@ .SH NOTICES
 bind M\-B linter main
 .EE
 .RE
-.P
 .
-.SH DESCRIPTION
+.SS Summary
 \fBnano\fR is a small and friendly text editor.  It copies the look and feel
 of Pico, but is free software, and implements several features that Pico
 lacks, such as: opening multiple files, scrolling per line, undo/redo,
@@ -107,7 +107,7 @@ .SH DESCRIPTION
 As a special case: if instead of a filename a dash (\fB\-\fR) is given,
 \fBnano\fR will read data from standard input.
 .
-.SH EDITING
+.SS Editing
 Entering text and moving around in a file is straightforward: typing the
 letters and using the normal cursor movement keys.  Commands are entered
 by using the Control (\[ha]) and the Alt or Meta (M\-) keys.
@@ -571,7 +571,7 @@ .SH OPTIONS
 \fB\[ha]W\fR writes out a file, and \fB\[ha]E\fR executes a command.
 Note that this option overrides option \fB\-p\fR \%(\fB\-\-preserve\fR).
 .
-.SH TOGGLES
+.SS Toggles
 Several of the above options can be switched on and off also while
 \fBnano\fR is running.  For example, \fBM\-L\fR toggles the
 hard-wrapping of long lines, \fBM\-S\fR toggles soft-wrapping,
@@ -656,11 +656,12 @@ .SH BUGS
 If you are able to reproduce the crash and you want to get a backtrace, define
 the environment variable \%\fINANO_NOCATCH\fR.
 .
-.SH HOMEPAGE
+.SH SEE ALSO
+.SS Homepage
 .UR https://nano\-editor.org/
 .UE
 .
-.SH SEE ALSO
+.P
 .BR nanorc (5)
 .P
 \fI/usr/share/doc/nano/\fR (or equivalent on your system)
diff --git a/doc/nanorc.5 b/doc/nanorc.5
index 4ef5581e..503cb03a 100644
--- a/doc/nanorc.5
+++ b/doc/nanorc.5
@@ -33,7 +33,7 @@ .SH DESCRIPTION
 whichever is encountered first.  If \fB\-\-rcfile\fR is given,
 \fBnano\fR reads just the specified settings file.
 .
-.SH NOTICES
+.SS Notices
 Since version 9.0, all lines are scrolled horizontally together
 (when the cursor approaches the edge), by just the amount needed,
 instead of scrolling only the current line by a large step.
@@ -453,7 +453,7 @@ .SH OPTIONS
 With \fBM\-Z\fR the title bar plus status bar can be toggled.
 With \fBM\-X\fR the help lines.
 .
-.SH SYNTAX HIGHLIGHTING
+.SS "Syntax highlighting"
 Coloring the different syntactic elements of a file
 is done via regular expressions (see the \fBcolor\fR command below).
 This is inherently imperfect, because regular expressions are not
@@ -600,7 +600,7 @@ .SH SYNTAX HIGHLIGHTING
 slightly improve a syntax defined in one of the system-installed
 files (which normally are not writable).
 .
-.SH REBINDING KEYS
+.SS "Rebinding keys"
 Key bindings can be changed via the following three commands:
 .RS 3
 .TP
diff --git a/doc/rnano.1 b/doc/rnano.1
index 3d2ddab8..6032a1d8 100644
--- a/doc/rnano.1
+++ b/doc/rnano.1
@@ -77,9 +77,10 @@ .SH BUGS
 Savannah bug tracker
 .UE .
 .
-.SH HOMEPAGE
+.SH SEE ALSO
+.SS Homepage
 .UR https://nano\-editor.org/
 .UE
 .
-.SH SEE ALSO
+.P
 .BR nano (1)
-- 
2.30.2
signature.asc (application/pgp-signature, 833 B)