Re: [PATCH v3] time.1: ffix

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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


[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux