[Top][All Lists]

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

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

From: G. Branden Robinson
Subject: Re: [Optional] versus <required|mandatory> parameters
Date: Sun, 5 Mar 2023 04:15:48 -0600

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

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.

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


Attachment: signature.asc
Description: PGP signature

reply via email to

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