[PATCH 08/31] docs: use idiomatic *roff ellipsis

"G. Branden Robinson" <[email protected]> Thu, 23 Apr 2026 17:58:18 -0500
Newsgroups	gmane.editors.nano.devel
Message-ID	<20260423225818.ks7apii3j2iajrow@illithid>
groff_man_style(7):
   Synopsis macros
...
     •  Symbols that are neither to be typed literally nor replaced at
        the user’s discretion appear in the roman style; brackets
        surround optional arguments, and an ellipsis indicates that the
        previous syntactic element may be repeated arbitrarily.  Where
        whitespace separates optional arguments, a space precedes the
        ellipsis.
Notes
     Some tips on composing and troubleshooting your man pages follow.
...
     • Why doesn’t the package provide a string to insert an ellipsis?

       Examples of ellipsis usage are shown above, in subsection
       “Synopsis macros”.  The idiomatic roff ellipsis is three dots
       (periods) with thin space escape sequences \| internally
       separating them.  Since dots both begin control lines and are
       candidate end‐of‐sentence characters, however, it is sometimes
       necessary to prefix and/or suffix an ellipsis with the dummy
       character escape sequence \&.  That fact stands even if a string
       is defined to contain the sequence; further, if the string ends
       with \&, end‐of‐sentence detection is defeated when you use the
       string at the end of an actual sentence.  (Ending a sentence with
       an ellipsis is often poor style, but not always.)  A hypothetical
       string EL that contained an ellipsis, but not the trailing dummy
       character \&, would then need to be suffixed with the latter when
       not ending a sentence.

           Instead of...              ...do this.
       ──────────────────────────────────────────────────
       .ds EL \&.\|.\|.         Arguments are
       Arguments are            .IR src‐file\~ .\|.\|.\&
       .IR src‐file\~ \*(EL\&   .IR dest‐dir .
       .IR dest‐dir .
       ──────────────────────────────────────────────────

       The first column practices a false economy; the savings in typing
       is offset by the cost of obscuring even the suggestion of an
       ellipsis to a casual reader of the source document, and reduced
       portability to non‐roff man page formatters that cannot handle
       string definitions.

       Unicode defines an ellipsis code point, and some fonts have an
       ellipsis glyph, which some man pages have accessed non‐portably
       with the font‐dependent \N escape sequence.  We discourage their
       use; on terminals, they may crowd the dots into a half‐width
       character cell, and do not render at all if the output device
       lacks the glyph.  In synopses, missing ellipses can mislead the
       reader.  Dots and space are universally supported.

squash ellipsis
---
 doc/nano.1   |  6 +++---
 doc/nanorc.5 | 18 +++++++++---------
 2 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/doc/nano.1 b/doc/nano.1
index 84d1c513..a11cd3d7 100644
--- a/doc/nano.1
+++ b/doc/nano.1
@@ -25,9 +25,9 @@ .SH NAME
 .
 .SH SYNOPSIS
 .B nano
-.RI [ options "] [[\fB+" line [\fB, column "]] " file ]...
+.RI [ options "] [[\fB+" line [\fB, column "]] " file ].\|.\|.
 .P
-.BR nano " [" \fIoptions "] [[" + [ crCR ]{ / | ? } \fIstring "] " \fIfile ]...
+.BR nano " [" \fIoptions "] [[" + [ crCR ]{ / | ? } \fIstring "] " \fIfile ].\|.\|.
 .
 .SH NOTICES
 Since version 9.0, all lines are scrolled horizontally together
@@ -341,7 +341,7 @@ .SH OPTIONS
 point to vary along with the width of the screen if the screen is resized.
 The default value is \fB\-8\fR.
 .TP
-.B "\-s ""\fIprogram\fR [\fIargument \fR...]\fB""\fR, \fB\-\-speller=""\fIprogram\fR [\fIargument \fR...]\fB"""
+.B "\-s ""\fIprogram\fR [\fIargument \fR.\|.\|.]\fB""\fR, \fB\-\-speller=""\fIprogram\fR [\fIargument \fR.\|.\|.]\fB"""
 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
diff --git a/doc/nanorc.5 b/doc/nanorc.5
index cc8341f0..93b04f17 100644
--- a/doc/nanorc.5
+++ b/doc/nanorc.5
@@ -355,7 +355,7 @@ .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
-.B set speller """\fIprogram\fR [\fIargument \fR...]\fB"""
+.B set speller """\fIprogram\fR [\fIargument \fR.\|.\|.]\fB"""
 Use the given \fIprogram\fR to do spell checking and correcting, instead of
 using the built-in corrector that calls \fBhunspell\fR(1) or \fBspell\fR(1).
 .TP
@@ -486,7 +486,7 @@ .SH SYNTAX HIGHLIGHTING
 For each kind of file a separate syntax can be defined
 via the following commands:
 .TP
-.BI syntax " name \fR[" """" fileregex """ " \fR...]
+.BI syntax " name \fR[" """" fileregex """ " \fR.\|.\|.]
 Start the definition of a syntax with this \fIname\fR.
 All subsequent \fBcolor\fR and other such commands
 are added to this syntax, until a new \fBsyntax\fR
@@ -504,12 +504,12 @@ .SH SYNTAX HIGHLIGHTING
 The syntax \fBnone\fR is reserved; specifying it on the command line
 is the same as not having a syntax at all.
 .TP
-.BI "header """ regex """ " \fR...
+.BI "header """ regex """ " \fR.\|.\|.
 If from all defined syntaxes no \fIfileregex\fR matched, then compare
 this \fIregex\fR (or regexes) against the first line of the current file,
 to determine whether this syntax should be used for it.
 .TP
-.BI "magic """ regex """ " \fR...
+.BI "magic """ regex """ " \fR.\|.\|.
 If no \fIfileregex\fR matched and no \fBheader\fR regex matched
 either, then compare this \fIregex\fR (or regexes) against the
 result of querying the \fBmagic\fR database about the current
@@ -517,10 +517,10 @@ .SH SYNTAX HIGHLIGHTING
 (This querying is done only when \fBlibmagic\fR is actually installed
 on the system and \fB\-\-magic\fR or \fBset magic\fR was given.)
 .TP
-.BI formatter " program " \fR[ "argument " \fR...]
+.BI formatter " program " \fR[ "argument " \fR.\|.\|.]
 Run the given \fIprogram\fR on the full contents of the current buffer.
 .TP
-.BI linter " program " \fR[ "argument " \fR...]
+.BI linter " program " \fR[ "argument " \fR.\|.\|.]
 Use the given \fIprogram\fR to run a syntax check on the current buffer.
 .TP
 .BI "comment """ string """"
@@ -539,7 +539,7 @@ .SH SYNTAX HIGHLIGHTING
 Python that want to see only spaces for indentation.
 This overrides the setting of the \fBtabstospaces\fR option.
 .TP
-.BI "color \fR[\fBbold,\fR][\fBitalic,\fR]" fgcolor , bgcolor " """ regex """ " \fR...
+.BI "color \fR[\fBbold,\fR][\fBitalic,\fR]" fgcolor , bgcolor " """ regex """ " \fR.\|.\|.
 Paint all pieces of text that match the extended regular expression
 \fIregex\fR with the given foreground and background colors, at least
 one of which must be specified.  Valid color names are:
@@ -571,7 +571,7 @@ .SH SYNTAX HIGHLIGHTING
 All coloring commands are applied in the order in which they are specified,
 which means that later commands can recolor stuff that was colored earlier.
 .TP
-.BI "icolor \fR[\fBbold,\fR][\fBitalic,\fR]" fgcolor , bgcolor " """ regex """ " \fR...
+.BI "icolor \fR[\fBbold,\fR][\fBitalic,\fR]" fgcolor , bgcolor " """ regex """ " \fR.\|.\|.
 Same as above, except that the matching is case insensitive.
 .TP
 .BI "color \fR[\fBbold,\fR][\fBitalic,\fR]" fgcolor , bgcolor " start=""" fromrx """ end=""" torx """"
@@ -591,7 +591,7 @@ .SH SYNTAX HIGHLIGHTING
 \fIsyntaxfile\fR may contain only the above commands, from \fBsyntax\fR
 to \fBicolor\fR.
 .TP
-.BI extendsyntax " name command argument " \fR...
+.BI extendsyntax " name command argument " \fR.\|.\|.
 Extend the syntax previously defined as \fIname\fR with another
 \fI\%command\fR.  This allows adding a new \fB\%color\fR, \fB\%icolor\fR,
 \fB\%header\fR, \fB\%magic\fR, \fB\%formatter\fR, \fB\%linter\fR,
-- 
2.30.2
signature.asc (application/pgp-signature, 833 B)