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

[G. Branden Robinson]

Hi John,

At 2023-03-05T20:24:48+1100, John Gardner wrote:
> 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.

Sure.  When you have to describe languages where white space does not
reliably separate lexical elements, (paired?) delimiters become
necessary.

A fortiori, Backus-Naur form exists for good reasons.  But people don't
need a command of it to profitably use the Unix command line.

To pretend that they do--for the sake of "consistency", I suppose--I
think trades away a good deal of readability and comprehensibility.

Doug and Ingo pretty much talked me out of introducing a tbl(7) man page
on similar grounds.

http://lists.gnu.org/r/groff/2022-09/msg00011.html

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

Yes indeed.

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

You're terse compared to some recent discussions.  :)

https://savannah.gnu.org/bugs/?63808
https://savannah.gnu.org/bugs/?63827

Regards,
Branden

signature.asc
Description: PGP signature