[PATCH v2 1/2] time.1: ffix

[PATCH v2 1/2] time.1: ffix

[G. Branden Robinson]

v2: Include more background on proper ellipsis usage.

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.
[...]
    • 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@gmail.com>
---
 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

Re: [PATCH v2 1/2] time.1: ffix

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 4905 bytes --]

Hi Branden,

On 2023-07-28 19:02, G. Branden Robinson wrote:

Huh!  Do you own a DeLorean?

I was very confused, because this v2 series ended up in my mailbox
as being older than the v1.

> v2: Include more background on proper ellipsis usage.

Thanks!

> 
> 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.

Sorry for not noticing earlier.  Please also document why an unbreakable
space should be added between the metasyntactic variable and the subsequent
ellipsis.  I've seen both kinds of uses all around, and would like to
have some reasons to prefer one over the other.

Cheers,
Alex

> 
> 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.
> [...]
>     • 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@gmail.com>
> ---
>  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 #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]