[Top][All Lists]

[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>
<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).

— John

reply via email to

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