Program usage message style

["J. Lewis Muir" <jlmuir%imca-cat.org@localhost>]

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