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

[John Gardner]

Hi Branden,

Documentation cowboys think they're being cool when they cram all this shit
> onto one logical synopsis line.
>

Synopses for command-line programs (i.e., man pages allocated to sections 1
or 8) are only a small part of the problem. When documenting file formats,
configuration files, schemata, and APIs written in languages other than
C/C++, the need to delineate alias groups becomes much more prevalent.

On an unrelated note, I've recently found myself using the same stylistic
conventions used in man pages for denoting *literal* and *placeholder* text
in syntax descriptions (specifically those containing expository characters
like brackets and pipes, which users aren't expected to type). The most
recent
<https://github.com/Cutlery-Drawer/simh/blob/a8fd111bc28c5e5fd72e4514d60723f3169e4d49/doc/altairz80_doc.rst#id11>
case involves reStructuredText files which will be used to generate man
pages using Sphinx <https://www.sphinx-doc.org/>, so the font choices are
still somehow relevant…

(Anywho, sorry for the long-winded rambling…)
— John

On Wed, 22 Feb 2023 at 17:06, G. Branden Robinson <
g.branden.robinson@gmail.com> wrote:

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