[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Optional] versus <required|mandatory> parameters
From: |
John Gardner |
Subject: |
[Optional] versus <required|mandatory> parameters |
Date: |
Wed, 22 Feb 2023 16:24:33 +1100 |
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):
<subcmd> := ("upgrade" | "update") <package>
Or
<subcmd> := ("upgrade" | "update" <package>)
Angle brackets seem to be the prevailing convention in usage messages,
--help output, and plain-text option summaries. However, I rarely ever see
this used in orthodox man pages: mdoc(7) has various enclosure macros like
.Aq, .Brq, .Pq *et al*, but nothing like its .Op macro, which semantically
identifies its contents as "optional" in the context of wherever it's used.
I know I'm overthinking this, but 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*]
How have other folks dealt with this issue? (If at all).
Regards,
— John
- [Optional] versus <required|mandatory> parameters,
John Gardner <=