[Top][All Lists]

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

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

From: John Gardner
Subject: Re: [Optional] versus <required|mandatory> parameters
Date: Sun, 5 Mar 2023 20:24:48 +1100

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
case involves reStructuredText files which will be used to generate man
pages using Sphinx <>, 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 <> 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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]