Re: [Optional] versus <required|mandatory> parameters

[G. Branden Robinson]

Hi John,

I think I can speak to this.

At 2023-02-22T16:24:33+1100, John Gardner wrote:
> What's the recommended convention for marking up *required* arguments?
> Square brackets indicate optional arguments more often than not, and
> something like this is ambiguous to readers:
> 
> *upgrade* | *update* *package*

Yes.

> This could be interpreted in two different ways (expressed using BNF):
> 
> <subcmd> := ("upgrade" | "update") <package>
> Or
> <subcmd> := ("upgrade" | "update" <package>)

Yes.

Normally, mandatory (required) arguments get no special markup.
However, as you note, sometimes selection among a group of mandatory
arguments is possible (or necessary).

In groff_man(7), I used to advise braces in for this type of situation.

k00lzip {--create | --extract | --test} [-abdeg] [-f archive] member ...

But I no longer do; instead, I decided it was clearer to the user to
have multiple synopses for this situation.

Here's what groff_man_style(7) says today.

  Command synopsis macros
    .SY and .YS aid you to construct a command synopsis that has the
    classical Unix appearance.  They break the output line.
...
    .SY command
        Begin synopsis.  A new paragraph begins at the left margin (as
        with .P) unless .SY has already been called without a
        corresponding .YS, in which case only a break is performed.
        Automatic hyphenation is disabled.  command is set in bold.  If
        a break is required, lines after the first are indented by the
        width of command plus a space.

    .YS End synopsis.  The previous indentation amount and initial
        hyphenation mode are restored.

    Multiple .SY/.YS blocks can be specified, for instance to
    distinguish differing modes of operation of a complex command like
    tar(1); each will be vertically separated as paragraphs are.

    .SY can be repeated before .YS to indicate synonymous ways of
    invoking a particular mode of operation.

Particularly with commands that have a rich (crusty old codgers of all
ages would say "excessive") option interface, it can be overwhelming to
present multiple mandatory "options" along with several discretionary
ones.

This gets worse in terms of visual and conceptual clutter when any of
the options, mandatory or not, takes arguments.

And things become downright _unclear_ when _some_ of the discretionary
options are only meaningful with certain selections of the mandatory
ones.

Documentation cowboys think they're being cool when they cram all this
shit onto one logical synopsis line.  (It rarely all fits on a physical
one.)

Consider grotty(1), which takes one set of (truly optional) options when
it's running in overstriking (Teletype compatibility) mode, and a subset
of those when it emits SGR escape sequences, along with a couple of
others that are meaningless in overstriking mode.

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

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

    grotty --help

    grotty -v
    grotty --version

Ingo has suggested that it is excessive to document the help and version
options, but the splitting of the first two, I'll defend while quoting
Milton and Melville with my arms wrapped around a Genesis device.

Regards,
Branden

signature.asc
Description: PGP signature