[PATCH 24/31] docs: stack multiple paragraph tags with `TQ` call

"G. Branden Robinson" <[email protected]> Thu, 23 Apr 2026 18:00:51 -0500
Newsgroups	gmane.editors.nano.devel
Message-ID	<20260423230051.4iigsaaxtvpvrjxt@illithid>
Paragraph tags can get quite hairy syntactically because they are housed
in a one-line input trap.  This can force the use of font selection
escape sequences and encourages cleverness over clarity.  The imposition
of a comma separation syntax for synonymous forms of the same
command-line option, as is common in GNU programs, exacerbates the
foregoing problem.  Use groff man(7)'s `TQ` extension macro to improve
source document readability and maintainability.

This change also arranges option presentation congruently with that in
nano's Texinfo manual.

groff_man(7):
     .TQ    Set an additional tag for a paragraph tagged with TP,
            planting a one‐line input trap as with TP.

            TQ is a GNU extension supported by Heirloom Doctools troff
            (since Git snapshot 151218) and mandoc (since 1.14.5) but
            not by DWB, Plan 9, or Solaris troffs.
...
   History
...
     ... Later, groff 1.20 (2009) resurrected EX/EE and originated
     SY/YS, TQ, MT/ME, and UR/UE.

This macro's definition is also short, simple, and universally portable
to troffs, should a page-local version be demanded.
---
 doc/nano.1   | 237 ++++++++++++++++++++++++++++++++++++++-------------
 doc/nanorc.5 |   6 +-
 doc/rnano.1  |   4 +-
 3 files changed, 185 insertions(+), 62 deletions(-)

diff --git a/doc/nano.1 b/doc/nano.1
index 19c84e82..6376f47d 100644
--- a/doc/nano.1
+++ b/doc/nano.1
@@ -128,52 +128,74 @@ .SH EDITING
 .
 .SH OPTIONS
 .TP
-.BR \-A ", " \-\-smarthome
+.B \-A
+.TQ
+.B \-\-smarthome
 Make the Home key smarter.  When Home is pressed anywhere but at the
 very beginning of non-whitespace characters on a line, the cursor jumps
 to that beginning (either forwards or backwards).  If the cursor is
 already at that position, it jumps to the true beginning of the line.
 .TP
-.BR \-B ", " \-\-backup
+.B \-B
+.TQ
+.B \-\-backup
 When saving a file, back up the previous version of it, using the current
 filename suffixed with a tilde (\fB\[ti]\fR).
 .TP
-.BI \-C " directory\fR, " \-\-backupdir= directory
+.BI "\-C " directory
+.TQ
+.BI \-\-backupdir= directory
 Make and keep not just one backup file, but make and keep a uniquely numbered
 one every time a file is saved \[em] when backups are enabled (\fB\-B\fR).
 The uniquely numbered files are stored in the specified \fIdirectory\fR.
 .TP
-.BR \-D ", " \-\-boldtext
+.B \-D
+.TQ
+.B \-\-boldtext
 For the interface, use bold instead of reverse video.
 This can be overridden for specific elements by setting the options
 \fB\%titlecolor\fR, \fB\%statuscolor\fR, \fB\%promptcolor\fR,
 \fB\%minicolor\fR, \fB\%keycolor\fR, \fB\%numbercolor\fR, and/or
 \fB\%selectedcolor\fR in your \fInanorc\fR file.  See \fBnanorc\fR(5).
 .TP
-.BR \-E ", " \-\-tabstospaces
+.B \-E
+.TQ
+.B \-\-tabstospaces
 Convert each typed tab to spaces \[em] to the number of spaces
 that a tab at that position would take up.
 (Note: pasted tabs are not converted.)
 .TP
-.BR \-F ", " \-\-multibuffer
+.B \-F
+.TQ
+.B \-\-multibuffer
 Read a file into a new buffer by default.
 .TP
-.BR \-G ", " \-\-locking
+.B \-G
+.TQ
+.B \-\-locking
 Use vim-style file locking when editing files.
 .TP
-.BR \-H ", " \-\-historylog
+.B \-H
+.TQ
+.B \-\-historylog
 Save the last hundred search strings and replacement strings and
 executed commands, so they can be easily reused in later sessions.
 .TP
-.BR \-I ", " \-\-ignorercfiles
+.B \-I
+.TQ
+.B \-\-ignorercfiles
 Don't look at the system's \fInanorc\fR nor at the user's \fInanorc\fR.
 .TP
-.BI \-J " number\fR, " \-\-guidestripe= number
+.BI "\-J " number
+.TQ
+.BI \-\-guidestripe= number
 Draw a vertical stripe at the given column, to help judge the width of the
 text.  (The color of the stripe can be changed with \fBset \%stripecolor\fR
 in your \fInanorc\fR file.)
 .TP
-.BR \-K ", " \-\-rawsequences
+.B \-K
+.TQ
+.B \-\-rawsequences
 Interpret escape sequences directly, instead of asking \fIncurses\fR
 to translate them.  (If you need this option to get some keys to work
 properly, it means that the \fIterminfo\fR terminal description that
@@ -181,34 +203,48 @@ .SH OPTIONS
 This can happen when you ssh into a BSD machine, for example.)
 Using this option disables \fBnano\fR's mouse support.
 .TP
-.BR \-L ", " \-\-nonewlines
+.B \-L
+.TQ
+.B \-\-nonewlines
 Don't automatically add a newline when a text does not end with one.
 (This can cause you to save non-POSIX text files.)
 .TP
-.BR \-M ", " \-\-trimblanks
+.B \-M
+.TQ
+.B \-\-trimblanks
 Snip trailing whitespace from the wrapped line when automatic
 hard-wrapping occurs or when text is justified.
 .TP
-.BR \-N ", " \-\-noconvert
+.B \-N
+.TQ
+.B \-\-noconvert
 Disable automatic conversion of files from DOS format.
 .TP
-.BR \-O ", " \-\-bookstyle
+.B \-O
+.TQ
+.B \-\-bookstyle
 When justifying, treat any line that starts with whitespace as the
 beginning of a paragraph (unless auto-indenting is on).
 .TP
-.BR \-P ", " \-\-positionlog
+.B \-P
+.TQ
+.B \-\-positionlog
 For the 200 most recent files, log the last position of the cursor,
 and place it at that position again upon reopening such a file.
 Also save and restore the positions of any anchors.
 .TP
-.BI "\-Q \[dq]" regex "\[dq]\fR, \fB\-\-quotestr=\[dq]" regex \[dq]
+.BI "\-Q \[dq]" regex \[dq]
+.TQ
+.BI \-\-quotestr=\[dq] regex \[dq]
 Set the regular expression for matching the quoting part of a line.
 The default value is \[lq]\fB\[ha]([\ \\t]*([!#%:;>|}]|//))+\fR\[rq].
 (Note that \fB\\t\fR stands for an actual Tab.)
 This makes it possible to rejustify blocks of quoted text when composing
 email, and to rewrap blocks of line comments when writing source code.
 .TP
-.BR \-R ", " \-\-restricted
+.B \-R
+.TQ
+.B \-\-restricted
 Restricted mode: don't read or write to any file not specified on the
 command line.  This means: don't read or write history files;
 don't allow suspending; don't allow spell checking;
@@ -217,16 +253,22 @@ .SH OPTIONS
 Restricted mode can also be activated by invoking \fBnano\fR
 with any name beginning with \[lq]r\[rq] (e.g., \[lq]rnano\[rq]).
 .TP
-.BR \-S ", " \-\-softwrap
+.B \-S
+.TQ
+.B \-\-softwrap
 Display over multiple screen rows lines that exceed the screen's width.
 (You can make this soft-wrapping occur at whitespace instead of rudely at
 the screen's edge, by using also \fB\-\-atblanks\fR.)
 .TP
-.BI \-T " number\fR, " \-\-tabsize= number
+.BI "\-T " number
+.TQ
+.BI \-\-tabsize= number
 Set the size (width) of a tab to \fInumber\fR columns.  The value of
 \fInumber\fR must be greater than 0.  The default value is \fB8\fR.
 .TP
-.BR \-U ", " \-\-quickblank
+.B \-U
+.TQ
+.B \-\-quickblank
 Make status-bar messages disappear after 1 keystroke instead of after 20.
 Note that option \fB\-c\fR (\fB\-\-constantshow\fR) overrides this.
 When option \fB\-\-minibar\fR or \fB\-\-zero\fR is in effect,
@@ -234,31 +276,45 @@ .SH OPTIONS
 0.8 seconds instead of after the default 1.5 seconds.
 .
 .TP
-.BR \-V ", " \-\-version
+.B \-V
+.TQ
+.B \-\-version
 Show the current version number and exit.
 .TP
-.BR \-W ", " \-\-wordbounds
+.B \-W
+.TQ
+.B \-\-wordbounds
 Detect word boundaries differently by treating punctuation
 characters as part of a word.
 .TP
-.BI "\-X \[dq]" characters "\[dq]\fR, \fB\-\-wordchars=\[dq]" characters \[dq]
+.BI "\-X \[dq]" characters \[dq]
+.TQ
+.BI \-\-wordchars=\[dq] characters \[dq]
 Specify which other characters (besides the normal alphanumeric ones)
 should be considered as part of a word.  When using this option, you
 probably want to omit \fB\-W\fR (\fB\-\-wordbounds\fR).
 .TP
-.BI \-Y " name\fR, " \-\-syntax= name
+.BI "\-Y " name
+.TQ
+.BI \-\-syntax= name
 Specify the name of the syntax highlighting to use from among the ones
 defined in the \fInanorc\fR files.
 .TP
-.BR \-Z ", " \-\-zap
+.B \-Z
+.TQ
+.B \-\-zap
 Let an unmodified Backspace or Delete erase the marked region
 (instead of a single character, and without affecting the cutbuffer).
 .TP
-.BR \-a ", " \-\-atblanks
+.B \-a
+.TQ
+.B \-\-atblanks
 When doing soft line wrapping, wrap lines at whitespace
 instead of always at the edge of the screen.
 .TP
-.BR \-b ", " \-\-breaklonglines
+.B \-b
+.TQ
+.B \-\-breaklonglines
 Automatically hard-wrap the current line when it becomes overlong,
 that is: when it becomes wider than the value given with \fB\-r\fR
 (\fB\-\-fill\fR).  The default value for \fB\-r\fR is the terminal's
@@ -266,118 +322,169 @@ .SH OPTIONS
 (This option is the opposite of \fB\-w\fR (\fB\-\-nowrap\fR) \[em]
 the last one given takes effect.)
 .TP
-.BR \-c ", " \-\-constantshow
+.B \-c
+.TQ
+.B \-\-constantshow
 Constantly report the cursor position on the status bar.
 Note that this overrides option \fB\-U\fR (\fB\-\-quickblank\fR).
 .TP
-.BR \-d ", " \-\-rebinddelete
+.B \-d
+.TQ
+.B \-\-rebinddelete
 Interpret the Delete and Backspace keys differently so that both Backspace
 and Delete work properly.  You should only use this option when on your
 system either Backspace acts like Delete or Delete acts like Backspace.
 .TP
-.BR \-e ", " \-\-emptyline
+.B \-e
+.TQ
+.B \-\-emptyline
 Do not use the line below the title bar, leaving it entirely blank.
 .TP
-.BI \-f " file\fR, " \-\-rcfile= file
+.BI "\-f " file
+.TQ
+.BI \-\-rcfile= file
 Read only this \fIfile\fR for setting \fBnano\fR's options, instead of reading
 both the system-wide and the user's \fInanorc\fR files.
 .TP
-.BR \-g ", " \-\-showcursor
+.B \-g
+.TQ
+.B \-\-showcursor
 Make the cursor visible in the file browser (putting it on the
 highlighted item) and in the help viewer.  Useful for braille users
 and people with poor vision.
 .TP
-.BR \-h ", " \-\-help
+.B \-h
+.TQ
+.B \-\-help
 Show a summary of the available command-line options and exit.
 .TP
-.BR \-i ", " \-\-autoindent
+.B \-i
+.TQ
+.B \-\-autoindent
 Automatically indent a newly created line to the same number of tabs
 and/or spaces as the previous line (or as the next line if the previous
 line is the beginning of a paragraph).
 .TP
-.BR \-j ", " \-\-jumpyscrolling
+.B \-j
+.TQ
+.B \-\-jumpyscrolling
 Scroll the buffer contents per half-screen instead of per line.
 .TP
-.BR \-k ", " \-\-cutfromcursor
+.B \-k
+.TQ
+.B \-\-cutfromcursor
 Make the 'Cut Text' command (normally \fB\[ha]K\fR) cut from the current cursor
 position to the end of the line, instead of cutting the entire line.
 .TP
-.BR \-l ", " \-\-linenumbers
+.B \-l
+.TQ
+.B \-\-linenumbers
 Display line numbers to the left of the text area.
 (Any line with an anchor additionally gets a mark in the margin.)
 .TP
-.BR \-m ", " \-\-mouse
+.B \-m
+.TQ
+.B \-\-mouse
 Enable mouse support, if available for your system.  When enabled, mouse
 clicks can be used to place the cursor, set the mark (with a double
 click), and execute shortcuts.  The mouse works in the X Window
 System, and on the console when gpm is running.  Text can still be
 selected through dragging by holding down the Shift key.
 .TP
-.BR \-n ", " \-\-noread
+.B \-n
+.TQ
+.B \-\-noread
 Treat any name given on the command line as a new file.  This allows
 \fBnano\fR to write to named pipes: it starts with a blank buffer,
 and writes to the pipe when the user saves the \[lq]file\[rq].  This way
 \fBnano\fR can be used as an editor in combination with for instance
 \fBgpg\fR without having to write sensitive data to disk first.
 .TP
-.BI \-o " directory\fR, " \-\-operatingdir= directory
+.BI "\-o " directory
+.TQ
+.BI \-\-operatingdir= directory
 Change to the given \fIdirectory\fR, and allow reading and writing
 files only in this directory and its subdirectories.
 .TP
-.BR \-p ", " \-\-preserve
+.B \-p
+.TQ
+.B \-\-preserve
 Preserve the XOFF and XON sequences (\fB\[ha]S\fR and \fB\[ha]Q\fR) so that
 they are caught by the terminal (stopping and resuming the output).
 Note that option \fB\-/\fR (\fB\-\-modernbindings\fR) overrides this.
 .TP
-.BR \-q ", " \-\-indicator
+.B \-q
+.TQ
+.B \-\-indicator
 Display a \[lq]scrollbar\[rq] on the righthand side of the edit window.
 It shows the position of the viewport in the buffer
 and how much of the buffer is covered by the viewport.
 .TP
-.BI \-r " number\fR, " \-\-fill= number
+.BI "\-r " number
+.TQ
+.BI \-\-fill= number
 Set the target width for justifying and automatic hard-wrapping at this
 \fInumber\fR of columns.  If the value is 0 or less, wrapping occurs
 at the width of the screen minus \fInumber\fR columns, allowing the wrap
 point to vary along with the width of the screen if the screen is resized.
 The default value is \fB\-8\fR.
 .TP
-.BI "\-s \[dq]" "program \fR[\fIargument \fR.\|.\|.]" "\[dq]\fR, \
-\fB\-\-speller=\[dq]" "program \fR[\fIargument \fR.\|.\|.]" \[dq]
+.BI "\-s \[dq]" "program \fR[\fIargument \fR.\|.\|.]" "\[dq]
+.TQ
+.BI \-\-speller=\[dq] "program \fR[\fIargument \fR.\|.\|.]" \[dq]
 Use this command to perform spell checking and correcting, instead of
 using the built-in corrector that calls \fBhunspell\fR(1) or \fBspell\fR(1).
 .TP
-.BR \-t ", " \-\-saveonexit
+.B \-t
+.TQ
+.B \-\-saveonexit
 Save a changed buffer without prompting (when exiting with \fB\[ha]X\fR).
 .TP
-.BR \-u ", " \-\-unix
+.B \-u
+.TQ
+.B \-\-unix
 Save a file by default in Unix format.  This overrides \fBnano\fR's
 default behavior of saving a file in the format that it had.
 (This option has no effect when you also use \fB\-\-noconvert\fR.)
 .TP
-.BR \-v ", " \-\-view
+.B \-v
+.TQ
+.B \-\-view
 Just view the file and disallow editing: read-only mode.
 This mode allows the user to open also other files for viewing,
 unless \fB\-\-restricted\fR is given too.
 .TP
-.BR \-w ", " \-\-nowrap
+.B \-w
+.TQ
+.B \-\-nowrap
 Do not automatically hard-wrap the current line when it becomes overlong.
 This is the default.  (This option is the opposite of \fB\-b\fR
 (\fB\-\-breaklonglines\fR) \[em] the last one given takes effect.)
 .TP
-.BR \-x ", " \-\-nohelp
+.B \-x
+.TQ
+.B \-\-nohelp
 Don't show the two help lines at the bottom of the screen.
 .TP
-.BR \-y ", " \-\-afterends
+.B \-y
+.TQ
+.B \-\-afterends
 Make Ctrl+Right and Ctrl+Delete stop at word ends instead of beginnings.
 .TP
-.BR \-z ", " \-\-listsyntaxes
+.B \-z
+.TQ
+.B \-\-listsyntaxes
 List the names of the available syntaxes and exit.
 .TP
-.BR \-! ", " \-\-magic
+.B \-!
+.TQ
+.B \-\-magic
 When neither the file's name nor its first line give a clue,
 try using \fIlibmagic\fR to determine the applicable syntax.
 .TP
-.BR \-@ ", " \-\-colonparsing
+.B \-@
+.TQ
+.B \-\-colonparsing
 When a filename given on the command line ends in a colon plus digits
 and this filename does not exist, then snip the colon plus digits and
 understand the digits as a line number.  If the trimmed filename does
@@ -387,7 +494,9 @@ .SH OPTIONS
 the original filename as is.  To disable this colon parsing for some
 file, use \fB+1\fR or similar before the relevant filename.
 .TP
-.BR \-% ", " \-\-stateflags
+.B \-%
+.TQ
+.B \-\-stateflags
 Use the top-right corner of the screen for showing some state flags:
 \fBI\fR when auto-indenting, \fBM\fR when the mark is on, \fBL\fR when
 hard-wrapping (breaking long lines), \fBR\fR when recording a macro,
@@ -395,7 +504,9 @@ .SH OPTIONS
 When the buffer is modified, a star (\fB*\fR) is shown after the
 filename in the center of the title bar.
 .TP
-.BR \-_ ", " \-\-minibar
+.B \-_
+.TQ
+.B \-\-minibar
 Suppress the title bar and instead show information about
 the current buffer at the bottom of the screen, in the space
 for the status bar.  In this \[lq]mini bar\[rq] the filename is shown
@@ -412,7 +523,9 @@ .SH OPTIONS
 \fB\-\-constantshow\fR is used, and can be toggled on and off with \fBM\-C\fR.
 The state flags are displayed only when \fB\-\-stateflags\fR is used.
 .TP
-.BR \-0 ", " \-\-zero
+.B \-0
+.TQ
+.B \-\-zero
 Hide all elements of the interface (title bar, status bar, and help lines)
 and use all rows of the terminal for showing the contents of the buffer.
 The status bar appears only when there is a significant message,
@@ -420,7 +533,9 @@ .SH OPTIONS
 With \fBM\-Z\fR the title bar plus status bar can be toggled.
 With \fBM\-X\fR the help lines.
 .TP
-.BR \-1 ", " \-\-solosidescroll
+.B \-1
+.TQ
+.B \-\-solosidescroll
 When the cursor approaches the right edge of the edit window, scroll only the
 current line sideways by a large amount, instead of scrolling all visible lines
 sideways by just the amount needed to keep the cursor in view.
@@ -428,7 +543,9 @@ .SH OPTIONS
 The single-line jerky sideways scrolling enabled by this option was the old
 behavior \[em] the only behavior that \fBnano\fR knew.
 .TP
-.BR \-/ ", " \-\-modernbindings
+.B \-/
+.TQ
+.B \-\-modernbindings
 Use key bindings similar to the ones that most modern programs use:
 \fB\[ha]X\fR cuts, \fB\[ha]C\fR copies, \fB\[ha]V\fR pastes,
 \fB\[ha]Z\fR undoes, \fB\[ha]Y\fR redoes,
diff --git a/doc/nanorc.5 b/doc/nanorc.5
index 1164ad42..fcebd7f0 100644
--- a/doc/nanorc.5
+++ b/doc/nanorc.5
@@ -1135,7 +1135,11 @@ .SH FILES
 .I /etc/nanorc
 System-wide configuration file.
 .TP
-.IR \[ti]/.nanorc " or " $XDG_CONFIG_HOME/nano/nanorc " or " \[ti]/.config/nano/nanorc
+.I \[ti]/.nanorc
+.TQ
+.I $XDG_CONFIG_HOME/nano/nanorc
+.TQ
+.I \[ti]/.config/nano/nanorc
 Per-user configuration file.
 .TP
 .I /usr/share/nano/*
diff --git a/doc/rnano.1 b/doc/rnano.1
index b8f3e8b1..4c23ed44 100644
--- a/doc/rnano.1
+++ b/doc/rnano.1
@@ -50,7 +50,9 @@ .SH DESCRIPTION
 .
 .SH OPTIONS
 .TP
-.BR \-h ", " \-\-help
+.B \-h
+.TQ
+.B \-\-help
 Show the available command-line options and exit.
 .P
 For all existing options, see the \fBnano\fR(1) man page.
-- 
2.30.2
signature.asc (application/pgp-signature, 833 B)