12

The man page for tar in Arch Linux SYNOPSIS section starts with:

tar {A|c|d|r|t|u|x}[GnSkUWOmpsMBiajJzZhPlRvwo] [ARG...]

I perfectly understand that in this situation it means that exactly one of the options in the curly braces must be given because it says so further down in the man page.

Is there some kind of standard or convention on using {} around a list of mutually exclusive options?

All I can find is a User's group tutorial on man from 1998 where it says:

Some options will have a limited list of choices. A list of choices will be comma separated and put between braces.

{choice1,choice2} {yes,no}

Seems like every convention (like this one from the Open Group) or man page describes only square brackets ([]) or vertical lines (|).

thanasisp
  • 8,122
umbasa
  • 129
  • 1
    Usually I'd think <> as being compulsory, but I suppose that's reserved for arguments as opposed to options. Counter: Ubuntu's version of the GNU tar manpage (http://manpages.ubuntu.com/manpages/trusty/en/man1/tar.1.html, for one) doesn't use this form, neither does http://linux.die.net/man/1/tar or Debian. I think you might be looking at BSD tar's manpage, so if a convention exists, it might be a BSD thing. – muru Mar 03 '15 at 17:13
  • upstream for arch man-pages is http://man7.org, tar page is exactly the same http://man7.org/linux/man-pages/man1/tar.1.html. – umbasa Mar 03 '15 at 20:29
  • 2
    I always thought that command line syntax came out of ENBF, but {} in ENBF means exactly the opposite (repetition of argument instead of one possible choice like in tar situation). I tried to google {} syntax with aim to windows and it seems like {} is very common on windows, it even has a description on technet. Sigh, Maybe I'm trying too hard to find the truth. – umbasa Mar 03 '15 at 20:41

2 Answers2

7

This is a great question (and still open years later). I think the answer is now officially answered in this Google document:

  • Required items: no brackets
  • Optional mutually exclusive items: square brackets, pipe delimited
  • Required mutually exclusive items: curly braces, pipe delimited
enharmonic
  • 702
TSG
  • 1,698
1

Is there some kind of standard or convention on using {} around list of mutually exclusive options?

I was researching the significance of the meaning of options that are specified in curly braces ({}) vs options specified in square brackets ([]) when I came across your question. It was the only source of information that I found useful with respect to what I was seeking to understand, namely why are the options stated in curly braces.

As you wrote:

I perfectly understand that in this situation it means that exactly one of them must be given...

Reading the man page for netstat I came to the understanding that the options were those options available for use with a command that must be used/stated prior to using any other options that may be listed with the command AND exactly only one of the listed options separated by the vertical bar can be used.

An example of the above can be found in the man page for the netstat command:

netstat {--route|-r} [address_family_options] [--extend|-e[--extend|-e]] [--verbose|-v] [--numeric|-n] [--numeric-hosts][--numeric-ports][--numeric-ports] [--continuous|-c] [delay]

Source: netstat(8) | Linux man page

In essence one can use exactly one of --route or -r (they mean the same thing) but the option must precede the other listed options.

I only took the time to respond to your question because the question appears to remain open but it appears to me you answered your own question :)

A convention is merely a widely established practice. Whether explicitly stated or not, the fact that you find the man documents regularly in this format indicates that the convention (assuming I stated it correctly above) is firmly established.

Is there a "standard"? To me that depends on what definition you want to adopt for "standard". To me there is little, to no, distinction between the meaning of the words convention and standard, in the sense that we are using the term here. In this sense I regard the two words to mean something along the lines of "something that is mutually agreed upon and used and accepted as the norm".

Thank you for your time in helping me to understand this convention/standard.

Darren Gansberg
  • 111