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. W
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, s
Hi John,
> this is something that's been eating away at me every time I've
> resorted to using square-brackets as a logical grouping mechanism;
> i.e., stuff like
>
> [[*upgrade* | *update*] *package*]
That's using [] to mean two different things so is clearly a bad idea.
:-)
> This could be int
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* | *u
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*
This could be interpreted in two different ways (expressed using BNF):
:= ("upg
