Mark up ellipses properly. They should be in roman. The item preceding
an ellipsis should be in the singular. Use unbreakable space between
metasyntactic variable and subsequent ellipsis. (Whitespace-separated
arguments should be separated from a subsequent ellipsis. "[-v...]"
suggests that both "-vv" and "-v -v" are permitted; "[-v ...]" suggests
only the latter.)
Quoting groff_man_style(7):
• 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
syntactical element may be repeated arbitrarily.
[...]
• The dummy character escape sequence \& follows the ellipsis when
further text will follow after space on the output line, keeping
its last period from being interpreted as the end of a sentence
and causing additional inter‐sentence space to be placed after it.
[...]
\| Thin space (one‐sixth em on typesetters, zero‐width on
terminals); a non‐breaking space. Used primarily in ellipses
(“.\|.\|.”) to space the dots more pleasantly on typesetting
devices like dvi, pdf, and ps.
[...]
Several features of the above example are of note. [...]
• The non‐breaking adjustable space escape sequence \~ is used to
prevent the output line from being broken within the option
brackets; see subsection “Portability” below.
[...]
• Why doesn’t the package provide a string to insert an ellipsis?
Examples of ellipsis usage are shown above, in subsection
“Command 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.
There is an ellipsis code point in Unicode, and some fonts have
an ellipsis glyph, which some man pages have accessed in a non‐
portable way with the font‐dependent \N escape sequence. We
discourage the use of these; on terminals, they may crowd the
dots into a half‐width character cell, and will not render at
all if the output device doesn’t have the glyph. In syntax
synopses, missing ellipses can cause great confusion. Dots and
space are universally supported.
Signed-off-by: G. Branden Robinson <g.branden.robinson@xxxxxxxxx>
---
man1/time.1 | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/man1/time.1 b/man1/time.1
index efb818cfd..8902b4b96 100644
--- a/man1/time.1
+++ b/man1/time.1
@@ -9,7 +9,7 @@ .SH NAME
time \- time a simple command or give resource usage
.SH SYNOPSIS
.B time
-.RI [ options ] " command " [ arguments... ]
+.RI [ option \~.\|.\|.\&] " command " [ argument \~.\|.\|.]
.SH DESCRIPTION
The
.B time
--
2.30.2
v4: Motivate why we don't jam ellipses up against whitespace-separated
arguments.
v3: Quote groff_man_style(7) regarding use of unbreakable space \~.
v2: Include more background on proper ellipsis usage.
Regards,
Branden
Attachment:
signature.asc
Description: PGP signature
