Hello!
I'm trying to figure out the best style for program usage messages, and
I'm running into some questions and wondering if anyone might be able to
help. My questions are:
1. Should the "u" in "usage:" be uppercase?
I see in the NetBSD source code style guide at
src/share/misc/style
that it's lowercase, but I see in the following that it's uppercase:
src/usr.sbin/npf/npfctl/npfctl.c
src/external/bsd/blacklist/bin/blacklistctl.c
(These are just two examples I happened to look at.)
2. How should mutually exclusive required arguments be grouped?
For example, in
src/usr.sbin/npf/npfctl/npfctl.c
it has a multi-line usage message that starts like this:
Usage: npfctl start | stop | flush | show | stats
and another line like this:
npfctl rule "rule-name" { list | flush }
Are braces preferred like in the second line? (I've seen some
programs use parentheses.) If so, why does the first line not use
them? My thought is that it's because there's no need to group them
since they are all at the same level and have no arguments before
nor after them, whereas in the second usage line, there are leading
arguments and then a mutually exclusive list.
3. How should literal arguments be differentiated from nonliteral ones?
For example, the npfctl usage message includes (among others) the
following lines:
npfctl validate | reload [<rule-file>]
npfctl rule "rule-name" { list | flush }
Here, validate, reload, rule, list, and flush are literals, and
<rule-file> and "rule-name" are nonliterals, but one is enclosed
in angle brackets while the other is enclosed in double-quotes.
Why is "rule-name" not <rule-name>? Or, why are "rule-name" and
<rule-file> not just rule-name and rule-file, respectively (i.e.,
no differentiation of literals from nonliterals is attempted in the
usage message)?
4. Should multi-line usage messages use a tab to align their left margins?
For example, npfctl's usage message has a tab character instead of
a space after "Usage:" and before subsequent lines. Is that the
preferred style?
I would understand if the answer to one or all of these is that there
is no preferred style. On the other hand, if there is a preferred
style and it would be a help, I'd be happy to submit a patch for
src/share/misc/style that tries to clarify these based on the answers
received.
Thanks!
Lewis
