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