Hi Branden, On 2023-07-30 17:21, G. Branden Robinson wrote: > 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. > > 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. That's the reason to use a non-breaking space over a breaking space. However, I'd also like to see justification for using a non-breaking space over no space at all. Cheers, Alex > [...] > • 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 -- <http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
