[PATCH v3] time.1: ffix

[PATCH v3] time.1: ffix

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 4506 bytes --]

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

v3: Quote groff_man_style(7) regarding use of unbreakable space \~.
v2: Include more background on proper ellipsis usage.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v3] time.1: ffix

[Alejandro Colomar]

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

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@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 --]

Re: [PATCH v3] time.1: ffix

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1883 bytes --]

Hi Alex,

At 2023-07-30T17:35:06+0200, Alejandro Colomar wrote:
> 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.

Readability.

Consider the synopsis of groff(1) itself.

        groff [-abcCeEgGijklNpRsStUVXzZ] [-d cs] [-d name=string]
              [-D enc] [-f fam] [-F dir] [-I dir] [-K enc] [-L arg]
              [-m name] [-M dir] [-n num] [-o list] [-P arg] [-r cn]
              [-r reg=expr] [-T dev] [-w name] [-W name] [file ...]

Pasting into this email, it's stripped of all its formatting, a scenario
we can imagine affects some number of users, especially those confused
by the old overstriking convention and who employ crude tools.

        groff [-abcCeEgGijklNpRsStUVXzZ] [-dcs] [-d name=string]
              [-Denc] [-ffam] [-Fdir] [-Idir] [-Kenc] [-Larg]
              [-mname] [-Mdir] [-nnum] [-olist] [-Parg] [-rcn]
              [-rreg=expr] [-Tdev] [-wname] [-Wname] [file ...]

Is that as easy to make sense of?  Maybe it is for some people,
especially if they already know that groff doesn't ever use a single
dash as a prefix for a long option name.  But there are conventions
other than GNU's.

    xclock [ -help ] [ -analog | -digital ] [ -brief ] [ -chime ] [ -hd
    color ] [ -hl color ] [ -update seconds ] [ -strftime format ] [
    -twelve | ‐twentyfour | ‐utime ] [ -padding number ] [ -norender ] [
    -render ] [ -sharp ] [ -face pattern ]

That actually proves to be a better example of bad formatting than I had
hoped for--look at all those problems!  Anyway, an expert can figure out
that "-utime" doesn't refer to an option "-u" that takes a metasyntactic
"time" as an argument.  But we shouldn't write man pages only for the
attention of experts.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Spaces in synopses of commands (was: [PATCH v3] time.1: ffix)

[Alejandro Colomar]

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

Hi Branden,

On 2023-07-30 17:45, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-07-30T17:35:06+0200, Alejandro Colomar wrote:
>> 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.
> 
> Readability.
> 
> Consider the synopsis of groff(1) itself.
> 
>         groff [-abcCeEgGijklNpRsStUVXzZ] [-d cs] [-d name=string]
>               [-D enc] [-f fam] [-F dir] [-I dir] [-K enc] [-L arg]
>               [-m name] [-M dir] [-n num] [-o list] [-P arg] [-r cn]
>               [-r reg=expr] [-T dev] [-w name] [-W name] [file ...]
> 
> Pasting into this email, it's stripped of all its formatting, a scenario
> we can imagine affects some number of users, especially those confused
> by the old overstriking convention and who employ crude tools.
> 
>         groff [-abcCeEgGijklNpRsStUVXzZ] [-dcs] [-d name=string]
>               [-Denc] [-ffam] [-Fdir] [-Idir] [-Kenc] [-Larg]
>               [-mname] [-Mdir] [-nnum] [-olist] [-Parg] [-rcn]
>               [-rreg=expr] [-Tdev] [-wname] [-Wname] [file ...]

I agree that having a space between an option and its argument improves
readability.  However, between a positional argument and the ellipsis
that marks that it can appear multiple times, I don't think the same
reasoning applies; at least not so obviously.

I'm referring to  [file ...] vs  [file...].

Cheers,
Alex

> 
> Is that as easy to make sense of?  Maybe it is for some people,
> especially if they already know that groff doesn't ever use a single
> dash as a prefix for a long option name.  But there are conventions
> other than GNU's.
> 
>     xclock [ -help ] [ -analog | -digital ] [ -brief ] [ -chime ] [ -hd
>     color ] [ -hl color ] [ -update seconds ] [ -strftime format ] [
>     -twelve | ‐twentyfour | ‐utime ] [ -padding number ] [ -norender ] [
>     -render ] [ -sharp ] [ -face pattern ]
> 
> That actually proves to be a better example of bad formatting than I had
> hoped for--look at all those problems!  Anyway, an expert can figure out
> that "-utime" doesn't refer to an option "-u" that takes a metasyntactic
> "time" as an argument.  But we shouldn't write man pages only for the
> attention of experts.
> 
> Regards,
> Branden

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Spaces in synopses of commands (was: [PATCH v3] time.1: ffix)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 911 bytes --]

Hi Alex,

At 2023-07-30T17:49:28+0200, Alejandro Colomar wrote:
> I agree that having a space between an option and its argument improves
> readability.  However, between a positional argument and the ellipsis
> that marks that it can appear multiple times, I don't think the same
> reasoning applies; at least not so obviously.
> 
> I'm referring to  [file ...] vs  [file...].

Oh.  The point of this is that the arguments (operands in this case)
remain whitespace-delimited, where it might not be the case for a
repeatable single-letter option.

foobar [-adX] [-v...] file ...
foobar [-h | --help]

  -v...  Be more verbose.  The option letter can be repeated, increasing
         the verbosity level.

"[-v ...]" would imply that only "-v -v -v" is allowed, instead of
"-vvv".

I think this is a matter of achieving an accurate and unambiguous
synopsis grammar.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Spaces in synopses of commands (was: [PATCH v3] time.1: ffix)

[Alejandro Colomar]

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

On 2023-07-30 18:13, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-07-30T17:49:28+0200, Alejandro Colomar wrote:
>> I agree that having a space between an option and its argument improves
>> readability.  However, between a positional argument and the ellipsis
>> that marks that it can appear multiple times, I don't think the same
>> reasoning applies; at least not so obviously.
>>
>> I'm referring to  [file ...] vs  [file...].
> 
> Oh.  The point of this is that the arguments (operands in this case)
> remain whitespace-delimited, where it might not be the case for a
> repeatable single-letter option.
> 
> foobar [-adX] [-v...] file ...
> foobar [-h | --help]
> 
>   -v...  Be more verbose.  The option letter can be repeated, increasing
>          the verbosity level.
> 
> "[-v ...]" would imply that only "-v -v -v" is allowed, instead of
> "-vvv".
> 
> I think this is a matter of achieving an accurate and unambiguous
> synopsis grammar.

Thanks; that kind of objective reasoning is what I wanted.  Would you
mind stating it in the commit message for posterity?  :-)

Cheers,
Alex

> 
> Regards,
> Branden

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

On synopsis grammar (was: Spaces in synopses of commands)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 9847 bytes --]

[adding groff list so that more people can argue with me, since I once
again found a soapbox to mount]

At 2023-07-30T18:14:53+0200, Alejandro Colomar wrote:
> On 2023-07-30 18:13, G. Branden Robinson wrote:
> > I think this is a matter of achieving an accurate and unambiguous
> > synopsis grammar.
> 
> Thanks; that kind of objective reasoning is what I wanted.  Would you
> mind stating it in the commit message for posterity?  :-)

I think I'll add it to the explanation of the example synopsis in
groff_man_style(7), too.  ;-)

While I'd love for synopsis grammar to be _fully_ unambiguous, one
unfortunate case did arise in discussion with mandoc maintainer Ingo
Schwarze on the groff mailing list in the past year or two.

Consider:

foocmd [-abort] file ...

Is this a command that takes up to 5 different options -a, -b, -o, -r,
-t, or a command that takes one option called "abort"?

A program in the BSD tradition might suggest one answer and a program in
the X11 tradition another.  I assume that this is not a new observation,
and is why the GNU project introduced (or adopted from some
now-forgotten progenitor) the double-dash long-option-name convention.

While we could eliminate the ambiguity by insisting upon a practice of
setting each short option in its own set of optional-argument brackets,
that would come at a significant cost in visual clutter.

Consider the groff(1) command, already ornamented richly with options.

    groff [-abcCeEgGijklNpRsStUVXzZ] [-d ctext] [-d string=text]
          [-D fallback‐encoding] [-f font‐family] [-F font‐directory]
          [-I inclusion‐directory] [-K input‐encoding] [-L spooler‐
          argument] [-m macro‐package] [-M macro‐directory] [-n page‐
          number] [-o page‐list] [-P postprocessor‐argument]
          [-r cnumeric‐expression] [-r register=numeric‐expression]
          [-T output‐device] [-w warning‐category] [-W warning‐category]
          [file ...]

In a quest for zero ambiguity, we might say:

    groff [-a] [-b] [-c] [-C] [-e] [-E] [-g] [-G] [-i] [-j] [-k] [-l]
          [-N] [-p] [-R] [-s] [-S] [-t] [-U] [-V] [-X] [-z] [-Z]
          [-d ctext] [-d string=text] [-D fallback‐encoding]
          [-f font‐family] [-F font‐directory] [-I inclusion‐directory]
          [-K input‐encoding] [-L spooler‐ argument] [-m macro‐package]
          [-M macro‐directory] [-n page‐number] [-o page‐list]
          [-P postprocessor‐argument] [-r cnumeric‐expression]
          [-r register=numeric‐expression] [-T output‐device]
          [-w warning‐category] [-W warning‐category] [file ...]

And with that done, we might as well lexicographically order all the
options.

    groff [-a] [-b] [-c] [-C] [-d ctext] [-d string=text]
          [-D fallback‐encoding] [-e] [-E] [-f font‐family]
          [-F font‐directory] [-g] [-G] [-i] [-I inclusion‐directory]
          [-j] [-k] [-K input‐encoding] [-l] [-L spooler‐argument]
          [-m macro‐package] [-M macro‐directory] [-n page‐number] [-N]
          [-o page‐list] [-p] [-P postprocessor‐argument]
          [-r cnumeric‐expression] [-r register=numeric‐expression]
          [-R] [-s] [-S] [-t] [-T output‐device] [-U] [-V]
          [-w warning‐category] [-W warning‐category] [-X] [-z] [-Z]
          [file ...]

...but that doesn't seem like an improvement to me.  Options that don't
take arguments are typically of Boolean sense.  (Occasionally, as with
some applications of '-v', they model an incrementation operation of
some kind.)  "Argumentful" options require further decision-making from
the user and it thus seems useful, to me, to segregate the two
categories.  Some traditions evolve for good reasons.  :)

As an aside, one might wonder why the groff(1) page uses such long
metasyntactic variable names in 1.23.0 when it did not in 1.22.4.  After
years of working on groff's ~60 man pages, I came to adopt a handful of
principles.

1.  A command should always offer a usage message via '--help',
    presenting a (plain text) synopsis much like the above.

2.  That synopsis, and the one in the corresponding man page, should
    match.

3.  A _usage_ message should be _useful_.

    $ foo --barblegarg
    foo: error: unrecognized option 'barblegarg'
    foo: usage: foo [options] [files]

    is so un-useful as to be user-hostile.  A programmer who writes this
    should be frank about their contempt for the user and drop such
    "usage advice" entirely.[1]

    Consider the novice user of groff.  They might wonder, "is lowercase
    'm' the flag letter for the macro package name and '-M' the one to
    add a macro search directory, or the other way around"?  Output like
    I presented for it above answers such a question.

4.  A usage message should not dump an _explanation_ of all options.  A
    person accustomed to the Unix command line philosophy of "no news is
    good news" will rightly be dismayed when a command invocation they
    expect to perform some task quietly and return to the shell prompt
    instead spews a gout of text to the terminal.  If many options are
    supported, and/or their explanations demand much space to present,
    the _actual problem_ with the command can easily scroll away.  Yes,
    maybe everybody has terminals with scrollback buffer these days, but
    it's still rude.  When something has gone wrong, a user's immediate
    response should not be to pound on the keyboard some more, but to
    pause, take a breath if necessary, and gather useful information
    from the screen.  If our "helpful" command hasn't left the most
    important information _on_ the screen, that's harder to do.

5.  It's okay to present a lengthy usage message, with much detail, if
    a user explicitly requests "--help".  But because lengthy runs of
    text can get out of sync, I prefer to maintain such things in one
    place--the command's man page.

6.  Ideally, you'd store things like metasyntactic variable names for
    command-line options in a data structure inside the command's
    sources, and a mechanism, possibly an environment variable or an
    otherwise "maintainer mode" command-line option, would dump a
    well-formed synopsis in man(7) format[2] using this information to
    the standard output.  As part of package build, one could then apply
    this output to a templated man page document to produce the shipping
    page.

    I first had this idea something like 25 years ago and I'm sure many
    other people have, too, it being such an obvious application of the
    DRY principle.  I can only guess that it didn't happen because
    getopt_long() is a GNU thing; GNU people (okay, let's be precise:
    GNU Emacs people), historically, have held man pages beneath
    contempt; and nobody else had both the traction and desire to get it
    done.  (Engineers paid to work on or adjacent to the Linux kernel
    seem always to have struggled, either with themselves or their
    managers, to justify expending more than a minimal effort on
    documentation of any sort.  Thus did both sides of GNU/Linux's white
    picket fence become brownfields.)

7.  One place we _don't_ need information rich metasyntactic variable
    names is where we're going to spend a lot of words explaining them
    anyway.  So after over-applying a principle of militant synchrony,
    I found that "Options" sections of man pages[3] could get by
    pedagogically just as well with short ones; they were easier to cope
    with typographically as well, improving the regularity of formatting
    (which is helpful to the reader, visually) and reducing the need for
    *roff stunts in man page sources to achieve consistent indentation
    in a series of tagged paragraphs.

    Consider again groff(1) options.  Here's the synopsis/usage message
    again, abbreviated.

    groff [-K input‐encoding] [-L spooler‐argument] [-T output‐device]

    And here's the corresponding material from its man page's "Options"
    section.

       -K enc Set input encoding used by preconv(1) to enc; implies -k.

       -L arg Pass  arg  to the print spooler program.  If multiple args
              are required, pass each with a separate -L option.   groff
              does not prefix an option dash to arg before passing it to
              the spooler program.

       -T dev Direct troff to format the input  for  the  output  device
              dev.  groff then calls an output driver to convert troff’s
              output to a form appropriate for dev; see subsection “Out‐
              put devices” below.

    (I haven't forgotten that you prefer two spaces between a tag and
    the body of a tagged paragraph.  I agree that it would look better.
    I still intend to add a tunable parameter for that [defaulting to
    2n], probably around the same time I do so for the base paragraph
    indentation amount.)

    We don't need a metasyntactic variable name as long as your arm when
    explaining fully in adjacent text what the parameter means.  At the
    same time, replacing all such names in the foregoing example with
    just "x" would be laconic to excess.

The Unix-Haters' Handbook is due for a second edition, isn't it?  ;-)

Regards,
Branden

[1] "Use the source, Luke," a.k.a. "see Figure 1."

[2] or some JSONic thing easily transformed into man(7) or another
    desired format

[3] Full disclosure: mandoc maintainer and mdoc(7) advocate Ingo
    Schwarze opposes the existence of "Options" sections in man pages.

    https://lists.gnu.org/archive/html/groff/2018-11/msg00031.html

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Spaces in synopses of commands (was: [PATCH v3] time.1: ffix)

[Lennart Jablonka]

Quoth G. Branden Robinson:
>> I'm referring to  [file ...] vs  [file...].
>
>Oh.  The point of this is that the arguments (operands in this case)
>remain whitespace-delimited, where it might not be the case for a
>repeatable single-letter option.
>
>foobar [-adX] [-v...] file ...
>foobar [-h | --help]
>
>  -v...  Be more verbose.  The option letter can be repeated, increasing
>         the verbosity level.
>
>"[-v ...]" would imply that only "-v -v -v" is allowed, instead of
>"-vvv".

Only if you can’t group options.   It is an issue that there are 
a few different options syntaxes and often, the specific one used 
is not documented.   I’d argue that’s acceptable for those 
utilities adhering to the POSIX Utility Syntax Guidelines;  that 
is, those that just use getopt.   And thus,

	foobar [-v ...]

	 -v ...  Be more verbose.  This options can be specified
	         multiple times to increase the verbosity level.

Makes it reasonably clear that you can make it very verbose by 
both -vvv and -v -v -v.

>I think this is a matter of achieving an accurate and unambiguous
>synopsis grammar.

Now, if you do not adhere to the guidelines—if you require -vvv or 
don’t allow grouping or both—you likely want a different synopsis 
syntax anyway:  Then, -asdf could be interpreted as “the 
single-dash long options asdf” and you shouldn’t write the short 
options as -adX.

None of this invalidates your explanation of ellipses and space 
therebefor.   But I don’t like your explanation.   Point is, 
I wouldn’t have gotten the idea of not putting a space there in 
the first place:  An ellipsis is most always delimited by spaces, 
in synopses as in prose.

Now, for opinions differing from yours:  In mdoc world, the 
ellipses frequently are part of the argument, as in

	.Ar path ...

and thus also italicized.   In POSIX, an ellipsis is not 
italicized and not delimited by spaces, as in

	p̲a̲t̲h̲...
	[-o f̲o̲r̲m̲a̲t̲]...

boldface, italics, spaces and ellipses in synopses of commands, and *nix history

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 15534 bytes --]

Hi Lennart,

At 2023-07-31T11:48:22+0000, Lennart Jablonka wrote:
> Quoth G. Branden Robinson:
> > "[-v ...]" would imply that only "-v -v -v" is allowed, instead of
> > "-vvv".
> 
> Only if you can’t group options.

I term this "clustering", but yes.  And most Unix `argv` interpreters
support doing so, at least those that make it into libraries used by
more than one application.

> It is an issue that there are a few different options syntaxes and
> often, the specific one used is not documented.

I suppose it'd be too demanding to ask authors of command-line programs
to document which they use in the Synopsis sections of their man pages.

Imagine:

Synopsis
     tbl [-C] [file ...]

     tbl --help

     tbl -v
     tbl --version

     Arguments are parsed by getopt_long(3).

Only the last line is not already present.

If a lot of people actually _did_ this, then you'd know from its absence
that someone might be using a hand-rolled argument parser, and to watch
out for land mines for the usual quality-of-implementation issues that
accompany NIH syndrome.

> I’d argue that’s acceptable for those utilities adhering to the POSIX
> Utility Syntax Guidelines;  that is, those that just use getopt.  And
> thus,
> 
> 	foobar [-v ...]
> 
> 	 -v ...  Be more verbose.  This options can be specified
> 	         multiple times to increase the verbosity level.
> 
> Makes it reasonably clear that you can make it very verbose by both
> -vvv and -v -v -v.

I don't have a mastery of those Guidelines but I accept that they can
contextualize the syntax enough to remove the ambiguity.

> Now, if you do not adhere to the guidelines—if you require -vvv or
> don’t allow grouping or both—you likely want a different synopsis
> syntax anyway: Then, -asdf could be interpreted as “the single-dash
> long options asdf” and you shouldn’t write the short options as -adX.

Yes.  It used to matter a great deal that nearly every X11 client
application in the world applied a different conventions here, but a
consistent one thanks to the ubiquity of the X Toolkit Intrinsics
library.  Eventually, when GTK+ and Qt came along, that convention was
discarded.

> None of this invalidates your explanation of ellipses and space
> therebefor.  But I don’t like your explanation.   Point is, I wouldn’t
> have gotten the idea of not putting a space there in the first place:
> An ellipsis is most always delimited by spaces, in synopses as in
> prose.
[rearranged]
> In POSIX, an ellipsis is not italicized and not delimited by spaces,
> as in
> 
> 	p̲a̲t̲h̲...
> 	[-o f̲o̲r̲m̲a̲t̲]...

Applying the rules of prose here is what makes me nervous about your
interpretation.  And POSIX's, for that matter; `argv` processing is far
less forgiving of whitespace errors than readers of prose are.

I have no serious beef with POSIX if they supply enough context in their
interpretation guidelines for people to make sense of their synopsis
notation.  The hazard lies in people who don't write to those guidelines
thoughtlessly aping POSIX's notation, unmoored from its context.

I find that two rules are popular among software developers.

1.  Don't write technical documentation.
2.  If you find you must write technical documentation, do it badly.

> Now, for opinions differing from yours:  In mdoc world, the ellipses
> frequently are part of the argument, as in
> 
> 	.Ar path ...
> 
> and thus also italicized.

I know, and I hate it; the ellipsis doesn't merit italicization any more
than option brackets do.  mdoc(7) is expressive enough that you don't
actually type the brackets; you use its `Op` macro.  To me, it is
telling that, thus having full control of the styling of synopsis
brackets, mdoc's author(s) (most prominently Cynthia Livingston, in the
macro language's second and final edition) set them in roman.[7]

Thanks for raising this.  The fix was straightforward, and you can
expect it in my next push to groff Git.[9]

I speculate that mdoc's italicization of ellipses would have been
regarded as a problem, but that it was overlooked, and here's why.
Chronologically, it appears to me that Livingston was still working in
the pre-x86 Unix tradition, even if at what we now recognize to be its
twilight.  People still had access to, and consulted, typeset manuals.

https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD-Tahoe/usr/doc/usd/

4.3BSD-Tahoe was 1988.  mdoc(7) arrived in 4.3BSD-Reno in 1990.

"The manual was intended to be typeset; some detail is sacrificed on
terminals." (man(1), _Unix Time-Sharing System Programmer's Manual_,
Eighth Edition, Volume 1, February 1985)

Try telling the difference between a roman ellipsis and an italic one,
when you can actually get italics instead of underlining.  I surmise
that, as a serious *roff macro package developer, Livingston did more of
her proofreading and validation with respect to typeset, rather than
terminal, output.  At least that's the approach I'd _recommend_: more
can go wrong on a typesetter--it's a better QA testbed.

But if she did, then among people concerned with man pages, she was a
member of a dying breed.

It is now the early 1990s.  Enter the thundering hordes of 386BSD and
Linux users, nearly all of them somewhat new to Unix.[10]  Every single
one of them has a VGA video card.  These same hordes can't afford
printed manuals (except for a few who took the time to print them using
university resources) and do _all_ of their reading of documentation on
VGA monitors.  The Web at first doesn't exist yet, and later, nothing's
on it--certainly not Unix documentation from which several publishers
derive revenue.  These new users know little of *roff.  If they even
know that any documentation beyond man pages exists, they don't know how
to type a troff/nroff/groff command to view it.  And if they do, it will
often look ugly because macro package authors neglected to ensure that
output degraded well when rendered to a terminal.  I claim this because
I have seen first-hand what the ms and mm packages from DWB 3.3 troff
do.  groff's implementations haven't been without defect, but I fixed
some bugs in terminal output for 1.23.0.  More fixes are in Git.

So what did the thundering hordes do?  They read man pages, only man
pages,[11] only via the man(1) command [this, at least, is excusable],
and only ever on VGA monitors.  Keep in mind that in the 1990s, a
significant portion of the *BSD and GNU/Linux user community seldom or
never started an X server.  The proud achievement of XFree86 was pulling
a hardware support story together well enough that by about 2002, nearly
every installer CD or USB stick gambled on X working, and defaulted to
a graphical environment.  (Too bad about the other XFree86 issues.[1])

Why does this matter?  Why are you reading this?

Because the VGA character cell attribute model not only didn't
contemplate italics, the devices also didn't support underlining.[8]

In terms of stroke weight, the glyphs on your screen could be normal or
heavy (bold).  And, at least on GNU/Linux, people badly wanted man page
names to be marked up differently than regular text.[6]

And so it was done.  In bold.  Because that's all VGA had to offer.  Man
pages had demanded since 1979 that three text styles be available.  The
display hardware that every 386BSD and Linux user was running supported
two.  The, uh, obvious solution was just to use bold for everything.
Screw italics, who needs 'em?  And thus, the man(1)-using community
ejected itself from paradise with such force that it forgot that man
page cross references (or to a large extent, anything else) were ever
set in italics in the first place.

As any 1980s PC gamer or USENET binary newsgroup aficionado could tell
you, another thing that VGA hardware could do was color.  (CGA and EGA
were marginal and MDA/Hercules so neglected that I don't know if any
386BSD or Linux kernel hackers even bothered to write drivers for them.
x86 Unix users were nothing if not class-conscious.  "Here's a nickel,
kid, buy yourself a better graphics card.")

It didn't take a genius to figure out that you could fake having
additional styles by applying color attributes to man pages (as was done
in GNU ls in early days--was it in "fileutils" back then?).  This, too,
started a tradition that persists to this day.[5]

Now, to be candid, no veteran of the 1990s BSD/Linux wars has ever
admitted to me that this is what happened.  But I was there and
familiar with the hardware, if wholly ignorant at the time of any Unix
before 4.3BSD and SunOS 4.

I'll always appreciate Ingo Schwarze relating this account:

"At some point after groff was first released (1990) but before 4.4BSD
(1993), Cynthia suggested to simplify the macros and the manual pages by
making groff mandatory and dropping support for Kernighan's troff, but
the Berkeley Computer Systems Reasearch Group objected, insisting that
support for Kernighan's troff was retained."

https://lists.gnu.org/archive/html/groff/2020-10/msg00170.html

That was a noteworthy place to draw a line, given that this decision was
taken during the very peak of animosity and litigation between the AT&T
and BSD Unix worlds,[2] and anything that AT&T locked up had to be
discarded or reimplemented, due to fear of a legal injunction
prohibiting distribution of one's software.[3]  Thus it was done, and
BSD adopted groff itself to replace the then-proprietary (and
expensively licensed) AT&T/DWB troff.[4]

It's hard to understand why the decision Ingo describes was taken.  A
charitable interpretation is that some CSRG people hoped that Kernighan
would find some way to get his troff into the free world.  A less
charitable one is that Charles Hannum, a founder of NetBSD and as rabid
an anti-GNU, anti-copyleft personality as I have ever met, had to learn
at _someone_'s feet, and that someone was at CSRG at the time.

What might have been, eh?

Anyway, an italic ellipsis in a synopsis is always wrong, I submit.

I also don't approve of the esthetics of boldfaced man page cross
references.  They are neither typographically pleasant nor historically
informed.  But _you_, the man page reader, can have them if you want.

groff_man_style(7):

    -dMF=man‐page‐topic‐font
        Set the font used for man page topics named in .TH and .MR
        calls; the default is “I” (italic style of the default family).
        Any valid argument to groff’s “.ft” request may be used.  If the
        MF string ends in “I”, it is assumed to be an oblique typeface,
        and italic corrections are applied before and after man page
        topics.

I expect

.ds MF B

to become a popular addition to man.local files after Alex lands the
"Mister Sed" (MR.sed)  change.  But people might try the default, along
with, if their terminal emulator's up to it,

MANROFFOPT="-P -i"

for a little while, just to see if they like 'em.

Regards,
Branden

[1] https://dwheeler.com/essays/gpl-compatible.html#xfree86
[2] https://en.wikipedia.org/wiki/UNIX_System_Laboratories,_Inc._v._Berkeley_Software_Design,_Inc.

[3] "[Keith] Bostic pioneered the technique of doing a mass net-based
    development effort. He solicited folks to rewrite the Unix utilities
    from scratch based solely on their published descriptions."

    https://www.oreilly.com/openbook/opensources/book/kirkmck.html

    Applying this technique to SunOS 4.0's troff documentation, my
    understanding is that this is exactly what James Clark did for GNU
    troff (and the programs around it--tbl in particular carries
    evidence to this day of having been targeted at Unix troff at some
    point--why, oh, why does it not create environments to manage
    formatting parameters?).

[4] https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/usr.bin/groff/

    I cannot now remember where I saw it, but my recollection is that
    a price schedule for DWB troff was something like $2,000.  I don't
    know if that was per-site, per-CPU, or per-seat.

[5] https://bugs.archlinux.org/task/79053

    At some point, less(1) users are going to have to decide which they
    want more: colorful man pages or OSC 8 hyperlinks.

    We _could_ support color attributes in man pages directly in groff.
    I feel sure it would horrify Ingo.  It might horrify me.  It would
    take a lot of design work (ironically, in groff's mdoc(7)
    implementation, which is based on 4.4BSD's, much of that work may be
    already done, for other reasons).  Right now I doubt whether it
    would be worth the trouble or even satisfy the people who want it.
    less(1)'s support for colorizing man pages works by pattern matching
    terminal output when the *roff output driver's geriatric--literally
    pre-termcap--and ambiguous overstriking output convention is used.
    I would not bet on it being completely robust.  grotty(1) talks
    about these matters.  The mechanism I can conceive would still
    require SGR support, to which people, including Ingo, are opposed
    anyway.  ¯_(ツ)_/¯

[6] mdoc didn't.  Courier roman on Times roman, or--on terminals--roman
    on roman was fine for them.

    (mdoc originally used a string called `xR` to control the typeface
    of the man page topic name.)

    https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/src/share/tmac/tmac.doc.old

    https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/share/tmac/tmac.doc
    https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/share/tmac/tmac.doc-ditroff
    https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/share/tmac/tmac.doc-nroff

[7] See the definitions of the `Op` macro...

    https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/share/tmac/tmac.doc

    ...and of the `lB` and `rB` strings.

    https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/share/tmac/tmac.doc-ditroff
    https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.4BSD/usr/share/tmac/tmac.doc-nroff

[8] If you were a product (or purchasing) manager ticking off boxes on a
    requirements checklist, VGA _did_ support underlining in text mode.
    In practice...

    https://en.wikipedia.org/wiki/VGA_text_mode

[9]

diff --git a/tmac/doc.tmac b/tmac/doc.tmac
index 70ec41ea2..6267d2a08 100644
--- a/tmac/doc.tmac
+++ b/tmac/doc.tmac
@@ -359,7 +359,7 @@
 .  ie        "\$1"|" \
 .    ds doc-arg\n[doc-arg-count] \f[R]|\f[]
 .  el \{ .ie "\$1"..." \
-.    ds doc-arg\n[doc-arg-count] \|.\|.\|.
+.    ds doc-arg\n[doc-arg-count] \f[R]\|.\|.\|.\f[]
 .  el \
 .    ds doc-arg\n[doc-arg-count] "\$1
 .  \}

[10] Serious and experienced Unix users in 1993 invariably had $10,000+
     workstations, paid for by their employers and running RISC
     processors of some sort, for their daily drivers, not a $1,500
     bucket of bolts with an 80386.

[11] Yes, there was, and still is, the Linux Documentation Project.  For
     a while, people devoted loving attention to these works.  I learned
     a lot from them.  The Linux Manpage HOWTO document has not been
     updated in 20 years.

     https://tldp.org/HOWTO/Man-Page/
     http://www.schweikhardt.net/man_page_howto.html

     I'm sure there is some kind of message for me in that fact.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: boldface, italics, spaces and ellipses in synopses of commands, and *nix history

[Lennart Jablonka]

>> I’d argue that’s acceptable for those utilities adhering to the POSIX
>> Utility Syntax Guidelines;  that is, those that just use getopt.  And
>> thus,
>>
>> 	foobar [-v ...]
>>
>> 	 -v ...  Be more verbose.  This options can be specified
>> 	         multiple times to increase the verbosity level.
>>
>> Makes it reasonably clear that you can make it very verbose by both
>> -vvv and -v -v -v.
>
>I don't have a mastery of those Guidelines but I accept that they can
>contextualize the syntax enough to remove the ambiguity.

Actually, reading it again, I would just drop the ellipsis.

	foobar [-v]

	 -v  Be more verbose.  This option can be specified
	     multiple times to increase the verbosity level.

>> None of this invalidates your explanation of ellipses and space
>> therebefor.  But I don’t like your explanation.   Point is, I wouldn’t
>> have gotten the idea of not putting a space there in the first place:
>> An ellipsis is most always delimited by spaces, in synopses as in
>> prose.
>[rearranged]
>> In POSIX, an ellipsis is not italicized and not delimited by spaces,
>> as in
>>
>> 	p̲a̲t̲h̲...
>> 	[-o f̲o̲r̲m̲a̲t̲]...
>
>Applying the rules of prose here is what makes me nervous about your
>interpretation.  And POSIX's, for that matter; `argv` processing is far
>less forgiving of whitespace errors than readers of prose are.

Oh, but synopses are prose!   You say that you want unambiguous 
synopses, I agree;  but you still need to read the options’ 
descriptions to know all about the utility’s command-line syntax.   
You don’t embed regular expressions for the arguments in the 
synopsis.   While there are styles for specifying different 
requirements, like having multiple symbolic command lines for 
alternatives with largely different syntaxes (e.g., a symbolic 
command line per sub-command), there are still requirements only 
expressed in the DESCRIPTION:  One option might be optional unless 
a certain other option is given.   You wouldn’t write 
[-a] [-b -a], you’d just write [-a] [-b], or rather [-ab].   If 
you should follow quite strict rules in you synopses (and you 
should), it still is more or less free-form.   And I’m not 
a forgiving reader of prose with whitespace errors.

>I have no serious beef with POSIX if they supply enough context in their
>interpretation guidelines for people to make sense of their synopsis
>notation.  The hazard lies in people who don't write to those guidelines
>thoughtlessly aping POSIX's notation, unmoored from its context.
>
>I find that two rules are popular among software developers.
>
>1.  Don't write technical documentation.
>2.  If you find you must write technical documentation, do it badly.

Exactly.   Which means:  All we can and something we should do is 
have guidelines.   Saying nothing of what those guidelines should 
be.

>> Now, for opinions differing from yours:  In mdoc world, the ellipses
>> frequently are part of the argument, as in
>>
>> 	.Ar path ...
>>
>> and thus also italicized.
>
>I know, and I hate it; the ellipsis doesn't merit italicization any more
>than option brackets do.  mdoc(7) is expressive enough that you don't
>actually type the brackets; you use its `Op` macro.  To me, it is
>telling that, thus having full control of the styling of synopsis
>brackets, mdoc's author(s) (most prominently Cynthia Livingston, in the
>macro language's second and final edition) set them in roman.[7]

I’m inclined to agree, though here I value convention over 
taste—and the convention for mdoc manuals has been from the start 
to italicize the ellipses.

>Thanks for raising this.  The fix was straightforward, and you can
>expect it in my next push to groff Git.[9]

>[9]
>
>diff --git a/tmac/doc.tmac b/tmac/doc.tmac
>index 70ec41ea2..6267d2a08 100644
>--- a/tmac/doc.tmac
>+++ b/tmac/doc.tmac
>@@ -359,7 +359,7 @@
> .  ie        "\$1"|" \
> .    ds doc-arg\n[doc-arg-count] \f[R]|\f[]
> .  el \{ .ie "\$1"..." \
>-.    ds doc-arg\n[doc-arg-count] \|.\|.\|.
>+.    ds doc-arg\n[doc-arg-count] \f[R]\|.\|.\|.\f[]
> .  el \
> .    ds doc-arg\n[doc-arg-count] "\$1
> .  \}

Heh, that sneaky spreading of ellipses is funny.   I don’t think it 
should be there, but whatever.   Do note that this only works if 
the ellipsis is its own argument:  Not having read doc.tmac more 
closely this looks like it somewhat contradicts your position on 
spaces with ellipses.

	foobar [-o option] ...  \" .Ar ...

	 -o option  Apply more options.  Because there’s only so
	            much space for single-letter options, you see.

	The -o options:

	.\" .Ar v...
	 v...  Be verbose.  The more v, the more verbose.

Oops, now the first ellipsis looks better than the second one.   
Yeah, I dislike that hack.

>I speculate that mdoc's italicization of ellipses would have been
>regarded as a problem, but that it was overlooked, and here's why.

This sounds like a reasonable explanation.

>Chronologically, it appears to me that Livingston was still working in
>the pre-x86 Unix tradition, even if at what we now recognize to be its
>twilight.  People still had access to, and consulted, typeset manuals.
>
>https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD-Tahoe/usr/doc/usd/
>
>4.3BSD-Tahoe was 1988.  mdoc(7) arrived in 4.3BSD-Reno in 1990.
>
>"The manual was intended to be typeset; some detail is sacrificed on
>terminals." (man(1), _Unix Time-Sharing System Programmer's Manual_,
>Eighth Edition, Volume 1, February 1985)

What I found in 4.3BSD-Reno’s mdoc.samples(7) and think is funny:

	[mdoc's] purpose is to allow translation of man pages from
	.Xr troff 1
	to
	.Xr TeX Coming\ Soon
	and vice versa.

Is (was then) there an equivalent to nroff for TeX?   I think not.

>And so it was done.  In bold.  Because that's all VGA had to offer.  Man
>pages had demanded since 1979 that three text styles be available.  The
>display hardware that every 386BSD and Linux user was running supported
>two.  The, uh, obvious solution was just to use bold for everything.
>Screw italics, who needs 'em?  And thus, the man(1)-using community
>ejected itself from paradise with such force that it forgot that man
>page cross references (or to a large extent, anything else) were ever
>set in italics in the first place.

So that’s why!

>It didn't take a genius to figure out that you could fake having
>additional styles by applying color attributes to man pages (as was done
>in GNU ls in early days--was it in "fileutils" back then?).  This, too,
>started a tradition that persists to this day.[5]

Couldn’t they have rendered italics as a different color then?

>Anyway, an italic ellipsis in a synopsis is always wrong, I submit.

If using mdoc, it’s less wrong to follow the established, if bad, 
convention of making ellipses for arguments italic, I submit.

>I also don't approve of the esthetics of boldfaced man page cross
>references.  They are neither typographically pleasant nor historically
>informed.  But _you_, the man page reader, can have them if you want.

And here you have my fullest agreement.

>[5] https://bugs.archlinux.org/task/79053
>
>    At some point, less(1) users are going to have to decide which they
>    want more: colorful man pages or OSC 8 hyperlinks.
>
>    We _could_ support color attributes in man pages directly in groff.
>    I feel sure it would horrify Ingo.  It might horrify me.  It would
>    take a lot of design work (ironically, in groff's mdoc(7)
>    implementation, which is based on 4.4BSD's, much of that work may be
>    already done, for other reasons).  Right now I doubt whether it
>    would be worth the trouble or even satisfy the people who want it.
>    less(1)'s support for colorizing man pages works by pattern matching
>    terminal output when the *roff output driver's geriatric--literally
>    pre-termcap--and ambiguous overstriking output convention is used.
>    I would not bet on it being completely robust.  grotty(1) talks
>    about these matters.  The mechanism I can conceive would still
>    require SGR support, to which people, including Ingo, are opposed
>    anyway.  ¯_(ツ)_/¯

Wouldn’t it be easiest to let grotty use terminfo?   Then whoever 
wishes to have colorful man pages would simply write a terminfo 
file and set MANROFFOPT=-P-Txterm-colorful.

Re: boldface, italics, spaces and ellipses in synopses of commands, and *nix history

[G. Branden Robinson]

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

Hi Lennart,

At 2023-07-31T18:40:11+0000, Lennart Jablonka wrote:
> > > I’d argue that’s acceptable for those utilities adhering to the
> > > POSIX Utility Syntax Guidelines;  that is, those that just use
> > > getopt.
[...]
> Actually, reading it again, I would just drop the ellipsis.
> 
> 	foobar [-v]
> 
> 	 -v  Be more verbose.  This option can be specified
> 	     multiple times to increase the verbosity level.

That's fine.  Syntactical issues can always be kicked upstairs to the
semantic level.  At some cost.

> > Applying the rules of prose here is what makes me nervous about your
> > interpretation.  And POSIX's, for that matter; `argv` processing is
> > far less forgiving of whitespace errors than readers of prose are.
> 
> Oh, but synopses are prose!

Maybe we're using different definitions of "prose".  I reckon I'm using
it to mean "sentential, natural language utterances that are not verse".

> You say that you want unambiguous synopses, I agree;  but you still
> need to read the options’ descriptions to know all about the utility’s
> command-line syntax.

Normally, you don't.  Not to grasp its _syntax_.

> You don’t embed regular expressions for the arguments in the synopsis.

No, because synopsis syntax maps to a subset of regular expression
syntax.

foo -> foo
foo? -> [foo]
foo+ -> foo ...
foo* -> [foo] ...
(foo|bar)? -> [foo|bar]

It's a little clumsier, formally, to express alternation of a mandatory
argument.

baz (foo|bar) -> baz foo
                 baz bar

This is a concern mostly for interfaces like tar(1)'s, which seems to
trip up everybody when they first learn it.

> While there are styles for specifying different requirements, like
> having multiple symbolic command lines for alternatives with largely
> different syntaxes (e.g., a symbolic command line per sub-command),

A gentler version of this is seen in grotty(1), where the availability
of certain options is modal.

    grotty [-dfho] [-i|-r] [-F dir] [file ...]

    grotty -c [-bBdfhouU] [-F dir] [file ...]

    grotty --help

    grotty -v
    grotty --version

> there are still requirements only expressed in the DESCRIPTION:  One
> option might be optional unless a certain other option is given.

You can get a fair way toward that; see above.

> You wouldn’t write [-a] [-b -a], you’d just write [-a]
> [-b], or rather [-ab].

I might critique this if I understood what you were trying to
express with it.

> If you should follow quite strict rules in you synopses (and you
> should), it still is more or less free-form.

I invite you to review the synopsis suggestions offered in
groff_man_style(7) and point out any ambiguity problems more severe than
those of POSIX's Guidelines conventions.  I didn't have those in mind
when writing them--just general practice, which is chaotic and not
difficult to improve upon.

> Exactly.   Which means:  All we can and something we should do is have
> guidelines.   Saying nothing of what those guidelines should be.

We can say more than that.  If no objective criteria for comparing
synopsis language conventions exist, then let's develop some.

> > I know, and I hate it; the ellipsis doesn't merit italicization any
> > more than option brackets do.  mdoc(7) is expressive enough that you
> > don't actually type the brackets; you use its `Op` macro.  To me, it
> > is telling that, thus having full control of the styling of synopsis
> > brackets, mdoc's author(s) (most prominently Cynthia Livingston, in
> > the macro language's second and final edition) set them in roman.[7]
> 
> I’m inclined to agree, though here I value convention over taste—and
> the convention for mdoc manuals has been from the start to italicize
> the ellipses.

I'm not anxious to sacrifice so much to taste.  :)

> > Thanks for raising this.  The fix was straightforward, and you can
> > expect it in my next push to groff Git.[9]

I may not be willing to die on this hill, but I'm willing to risk being
MEDEVACed from it.  It won't matter, if everybody who really cares about
mdoc(7) is loyal to mandoc(1) unto death, which seems to approximately
be the case.

My goal is that it not be obvious to the causal reader of a man page
whether man(7) or mdoc(7) was used to compose it.  So I'm not tolerant
of gratuitous rendering differences, and in groff 1.23.0 I made changes
to both packages to align them better with each other.  I'm happy if
only an expert man page author can tell without looking at the source.

> Heh, that sneaky spreading of ellipses is funny.

Alex had a comment about that too, and I remember making a mental note
to respond to it, but not actually doing so.  So I will now.  You may
already know this, but on terminal devices, \| (like \^) does not render
as anything at all.  So we lose the interest of maybe 95% of the man
page reading community right away.

Illustration attached, in source and a PNG of rendered PostScript.

> I don’t think it should be there, but whatever.

It's a practice that has at least a decade on mdoc(7)'s italic ellipsis.

https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/man/man0/intro

> Do note that this only works if the ellipsis is its own argument:  Not
> having read doc.tmac more closely this looks like it somewhat
> contradicts your position on spaces with ellipses.

The position I adopted was not ab initio but a consequence of other
rules I apply to synopsis interpretation.  I'm not enamored of option
reduplication (i.e., "-vvvv")--just accept an integral option argument,
you lazy sods--nor of any strain it puts on my synopsis guidelines.

> 	foobar [-o option] ...  \" .Ar ...
> 
> 	 -o option  Apply more options.  Because there’s only so
> 	            much space for single-letter options, you see.
> 
> 	The -o options:
> 
> 	.\" .Ar v...
> 	 v...  Be verbose.  The more v, the more verbose.
> 
> Oops, now the first ellipsis looks better than the second one.   Yeah,
> I dislike that hack.

It may not be clear to everyone, but mdoc(7)'s special handling of "..."
only applies when it appears as its own token.  _But_ there are a lot of
rules about how mdoc(7) processes tokens in its utterly bespoke approach
to input interpretation, unlike any other *roff macro package.

For example, I cannot completely account for the behavior of:

.Fl x Op Fl v Ar file ... Op Fl v... Op Fl v Ns ...

And bugs _have_ been found both in groff's and mandoc's implementations.

As another case--a real-world one--the correct resolution of
https://savannah.gnu.org/bugs/?63289 is not yet decidable to me.

If I ever master the package, maybe I'll get a chance to improve the
groff_mdoc(7) page.

> What I found in 4.3BSD-Reno’s mdoc.samples(7) and think is funny:
> 
> 	[mdoc's] purpose is to allow translation of man pages from
> 	.Xr troff 1
> 	to
> 	.Xr TeX Coming\ Soon
> 	and vice versa.
> 
> Is (was then) there an equivalent to nroff for TeX?   I think not.

Nope.  Interconvertibility of *roff and TeX may have been a forlorn hope
at the time, but even if not, the issue was muddled for about 20 years
by the Web appearing and SGML and then XML sucking up every molecule of
oxygen (and talent) in the problem space.  (It inhaled James Clark, I
assume to his remunerative benefit.)  Nowadays the best hope would
appear to lie in pandoc, which at least had the wisdom to build on a
foundation that should be strong enough for the task: Haskell.

> > And so it was done.  In bold.  Because that's all VGA had to offer.
> > Man pages had demanded since 1979 that three text styles be
> > available.  The display hardware that every 386BSD and Linux user
> > was running supported two.  The, uh, obvious solution was just to
> > use bold for everything.  Screw italics, who needs 'em?  And thus,
> > the man(1)-using community ejected itself from paradise with such
> > force that it forgot that man page cross references (or to a large
> > extent, anything else) were ever set in italics in the first place.
> 
> So that’s why!

It's conjecture that I have shared several times before, in forums where
people who are placed to know better could tell me I'm full of fecalith.

If I ever run into Rik Faith, I'll ask him.  If he doesn't know, or know
who can tell me, perhaps no one does.  It might have been one of those
decisions made by community gestalt rather than any deliberative
process.

> > It didn't take a genius to figure out that you could fake having
> > additional styles by applying color attributes to man pages (as was
> > done in GNU ls in early days--was it in "fileutils" back then?).
> > This, too, started a tradition that persists to this day.
> 
> Couldn’t they have rendered italics as a different color then?

They could, and before long, they did.  The Linux console driver _today_
by default (at least on my Debian-based box) renders bold in bright
white (stroke thickness does not vary, I assume because the tiny font
and therefore character cell size cannot accommodate anything wider),
underscored cells in cyan, and "true" italics in (light) green.

Back in the day (1990s) you'd get red for bold, I think, and blue for
underscore (which was a stupid choice, because it had low contrast with
the black background--but it stuck for years; this might also have been
a factor in driving man page authors to use bold for everything).[1]
Sometimes the colors were reversed, thanks to a magnificent own-goal in
the chaotic days of early ncurses development.[2]  By the time _that_
got fixed, followers of the displaced ncurses maintainer swore that
they'd never use it or terminfo again, and pledged undying loyalty to
S-Lang, the moldering corpse of termcap, or programming the terminal
directly, because who cares about portability?  Some of these are the
same people who will, upon considering any exhibit of code they don't
like, play the "layering violation" card as the first or second move,
often without any consideration of how that term actually _applies_.

I would advise against anyone playing a drinking game wherein they throw
one back every time I complain about something.  It'd be lethal.

> > Anyway, an italic ellipsis in a synopsis is always wrong, I submit.
> 
> If using mdoc, it’s less wrong to follow the established, if bad,
> convention of making ellipses for arguments italic, I submit.

If I see you from the MEDEVAC chopper, I'll wave.

> > I also don't approve of the esthetics of boldfaced man page cross
> > references.  They are neither typographically pleasant nor
> > historically informed.
> 
> And here you have my fullest agreement.

I even persuaded Ingo.[3]  Not to change mandoc(1), but to concede the
historical point.  Which feels to me like a bigger win anyway.

> Wouldn’t it be easiest to let grotty use terminfo?   Then whoever
> wishes to have colorful man pages would simply write a terminfo file
> and set MANROFFOPT=-P-Txterm-colorful.

Indeed.

https://savannah.gnu.org/bugs/?63583

Regards,
Branden

[1] As far as I know, it was a long time before anyone in the free Unix
    world bothered to support SGR 3 [real italics].  I have no doubt
    that the ritual auto-da-fé of loyalty to Teletype Model 37-esque
    overstriking largely accounts for this passivity.  It is a bitter
    indictment of our community that we stuck to stuff like ul(1) and
    col(1) to massage the output of nroff(1) when even Unix Version 7
    (1979) nroff countenanced the achievement of stylistic markup via
    escape sequences, as I confirmed first-hand.

    https://lists.gnu.org/archive/html/groff/2022-06/msg00048.html

    ...just not for the default output device.  The Teletype was
    manufactured by Western Electric.  This is the same company--the
    same subsidiary of the AT&T monopoly--that manufactured telephones.
    Our community's loyalty to overstriking is closely analogous to
    insisting upon being able to connect a rotary dial telephone to the
    existing network.  No, worse--to placing a rotary dial on everyone's
    mobile phone by default and requiring an upgrade to touch-tone
    dialing.  (And yes, I know mobile communications are not conducted
    using DTMF; even land lines migrated away from that after the phone
    phreaks figured out how to issue administrative commands in-band via
    that means.  That's the point.  The zombie inertia in this area is
    breathtaking.  Is it unconscious rather than deliberate?  So much
    the worse.)

[2] https://invisible-island.net/ncurses/ncurses.faq.html#interchanged_colors
[3] https://lists.gnu.org/archive/html/groff/2021-08/msg00034.html

[-- Attachment #1.2: ellipsis-spacing.man --]
[-- Type: application/x-troff-man, Size: 193 bytes --]

[-- Attachment #1.3: ellipsis-spacing.png --]
[-- Type: image/png, Size: 13943 bytes --]

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: boldface, italics, spaces and ellipses in synopses of commands, and *nix history

[Alejandro Colomar]

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

Hi Branden,

On 2023-08-01 00:20, G. Branden Robinson wrote:

>>> Thanks for raising this.  The fix was straightforward, and you can
>>> expect it in my next push to groff Git.[9]
> 
> I may not be willing to die on this hill, but I'm willing to risk being
> MEDEVACed from it.  It won't matter, if everybody who really cares about
> mdoc(7) is loyal to mandoc(1) unto death, which seems to approximately
> be the case.
> 
> My goal is that it not be obvious to the causal reader of a man page
> whether man(7) or mdoc(7) was used to compose it.  So I'm not tolerant
> of gratuitous rendering differences, and in groff 1.23.0 I made changes
> to both packages to align them better with each other.  I'm happy if
> only an expert man page author can tell without looking at the source.

Function prototypes are the biggest difference, IMO.  I prefer how man(7)
pages show function prototypes (the type and the variable are formatted
differently).  Though I'll give to mdoc(7) that parentheses and commas in
roman are nice.

.3 pages are easily distinguished in the first screenful of text
without looking at the source, in the SYNOPSIS.

Cheers,
Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

function prototypes, man(7), and mdoc(7) (was: boldface, italics, spaces and ellipses in synopses of commands, and *nix history)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1809 bytes --]

Hi Alex,

At 2023-08-01T01:03:38+0200, Alejandro Colomar wrote:
> > My goal is that it not be obvious to the causal reader of a man page
> > whether man(7) or mdoc(7) was used to compose it.
> 
> Function prototypes are the biggest difference, IMO.  I prefer how
> man(7) pages show function prototypes (the type and the variable are
> formatted differently).  Though I'll give to mdoc(7) that parentheses
> and commas in roman are nice.

You will scandalize some people by suggesting that bold isn't the best
choice for all literals.  ;-)

> .3 pages are easily distinguished in the first screenful of text
> without looking at the source, in the SYNOPSIS.

I think it might be tricky to achieve parity here without either:

1.  imposing eyeball-bleeding complexity on man(7) authors; or
2.  implementing the most radical of my man(7) reform proposals:
    an extensible semantic tagging mechanism.

https://lists.gnu.org/archive/html/groff/2022-12/msg00075.html

I'll see how we weather the `MR` storm before sailing into that one.

In any event I'd need to devote some serious time to considering the
shape of the problem of function declarations.  Possibly their hopeless
variability is what led mdoc(7)'s designer(s) to implement its
challenging "called"/"parsable" system of argument interpretation.

And think--C language declaration syntax has gotten _more_ complex since
mdoc fossilized around the time ANSI C froze.  Type qualifiers are far
more often used now, and attributes were, if not inconceivable, then on
a distant horizon.

But maybe that won't matter: with only three font styles available
(though we probably _could_ employ bold-italics if we _had_ to), there
is a limit to how many different sorts of things we can represent.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: function prototypes, man(7), and mdoc(7) (was: boldface, italics, spaces and ellipses in synopses of commands, and *nix history)

[Alejandro Colomar]

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

Hi Branden,

On 2023-08-01 22:01, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-08-01T01:03:38+0200, Alejandro Colomar wrote:
>>> My goal is that it not be obvious to the causal reader of a man page
>>> whether man(7) or mdoc(7) was used to compose it.
>>
>> Function prototypes are the biggest difference, IMO.  I prefer how
>> man(7) pages show function prototypes (the type and the variable are
>> formatted differently).  Though I'll give to mdoc(7) that parentheses
>> and commas in roman are nice.
> 
> You will scandalize some people by suggesting that bold isn't the best
> choice for all literals.  ;-)

I enjoy scandalizing people.  ;-)

> 
>> .3 pages are easily distinguished in the first screenful of text
>> without looking at the source, in the SYNOPSIS.
> 
> I think it might be tricky to achieve parity here without either:
> 
> 1.  imposing eyeball-bleeding complexity on man(7) authors; or
> 2.  implementing the most radical of my man(7) reform proposals:
>     an extensible semantic tagging mechanism.
> 
> https://lists.gnu.org/archive/html/groff/2022-12/msg00075.html
> 
> I'll see how we weather the `MR` storm before sailing into that one.

Huh, I didn't know this meaning of weather (I didn't even know it could
be a verb!).  Interesting.

And yes, MR will take a lot of time from us, I expect.  Just remember
about references to specific sections or even subsections within a
page.  I have been thinking about these things, and some day I'll share
my thoughts, but I can resume them in "everything we suggested doesn't
scale well".

I'd fight that battle before going for macros specific to functions.
Oh, and if you manage to have full-paragraph or even full-document
knowledge before even starting to print a line, these macros might be
even more juicy to add (just imagine not having to hand-craft the
alignment of continuation lines of function declarations and yet
having a nice alignment for a page).  :)

> 
> In any event I'd need to devote some serious time to considering the
> shape of the problem of function declarations.  Possibly their hopeless
> variability is what led mdoc(7)'s designer(s) to implement its
> challenging "called"/"parsable" system of argument interpretation.
> 
> And think--C language declaration syntax has gotten _more_ complex since
> mdoc fossilized around the time ANSI C froze.  Type qualifiers are far
> more often used now, and attributes were, if not inconceivable, then on
> a distant horizon.

And consider my proposal for a GCC extension to use array notation in a
backwards manner with buf[.size].  It won't be nice.

> 
> But maybe that won't matter: with only three font styles available
> (though we probably _could_ employ bold-italics if we _had_ to), there
> is a limit to how many different sorts of things we can represent.

We'll see.

Cheers,
Alex

> 
> Regards,
> Branden

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]