5

So, I'm writing a CLI for an API, and I ran into a point where one of the commands support has two optional arguments, id and fields

I want to know how to show that these arguments are optional, BUT, you have to supply at least ONE of them, or even both. I'm not sure how to word the Google search, so I haven't been able to turn anything up. My best guess is something like Usage: support [id=...]||[fields=...] but I'd like to know the standard.

Gilles 'SO- stop being evil'
  • 829,060
Christopher Wirt
  • 151
  • 2
    They are not optional. <id=|fields=>. – jordanm May 29 '14 at 16:14
  • Except last I knew | implies either, but not both, right..? – Christopher Wirt May 29 '14 at 17:29
  • 1
    I would do something like this: <[id=…] [fields=…]>. Both can happen, and though neither must happen, there is an implication that something is required. – HalosGhost May 29 '14 at 20:50
  • The easiest way around this is to make both optional, in one of two ways: (a) provide a default action for the no argument case or (b) print an error message and exit. As far as I can tell, the POSIX Utility Conventions do not have a way to express the "one or more of the following set, but at most one of each" requirement. You could also imitate dd, and just call it field_id which you explain in the details. – jw013 May 30 '14 at 01:18

1 Answers1

3

POSIX doesn't have anything to say about how to document commands, nor does any standard that I know.

A common convention is to list two separate command lines, one with id, one with fields.

support id=… [OPTION…]
support fields=… [OPTION…]

Alternatively, you can use {id|fields} to indicate that either can be specified (but not both). This is useful when the rest of the command line would be the same, to avoid repeating said rest. On the other hand, it is somewhat less readable.

support {id=NAME|fields=FIELD1,FIELD2} [OPTION]…

Example: the cpio man page under FreeBSD, Solaris, Linux use different lines for the different modes (indicated by the choice between -i, -o and -p). So does POSIX itself. The Linux man page uses {-i|--extract} to indicate that either -i or --extract can be used; I find the use of braces without alternatives in the FreeBSD man page strange.

Gilles 'SO- stop being evil'
  • 829,060
  • Firstly, http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html and secondly, they CAN do both.. Read the question or get out. – Christopher Wirt May 30 '14 at 02:06
  • 2
    @ChristopherWirt That's the notation used by the POSIX specification, not a notation that's necessarily supposed to be used in the documentation of compliant products. The spec itself uses the multiple-line notation in pax (which is similar to my cpio example, being a newer interface for a tool with a similar purpose). P.S. Be nice or get out. – Gilles 'SO- stop being evil' May 30 '14 at 02:11
  • @Giles, you still didn't answer the question at all. Its not too hard to show an either/or, but in my case they can have both of them – Christopher Wirt May 30 '14 at 02:35