6

Often, command line parameters are documented using a vaguely EBNF-ish notation such as the following:

  • The output of dir /? on Windows:

    DIR [drive:][path][filename] [/A[[:]attributes]] [/B] [/C] [/D] [/L] [/N]
  [/O[[:]sortorder]] [/P] [/Q] [/R] [/S] [/T[[:]timefield]] [/W] [/X] [/4]

  • The output of netsh /? on Windows:

    Usage: netsh [-a AliasFile] [-c Context] [-r RemoteMachine] [-u [DomainName\]UserName] [-p Password | *]
             [Command | -f ScriptFile]

  • The documentation for expand on microsoft.com:

    expand [-r] source [destination] [-dsource.cab [-f:files]] [source.cab [-f:filesdestination] [-i]

  • The Linux man page for date:

    date [OPTION]... [+FORMAT]
date [-u|--utc|--universal] [MMDDhhmm[[CC]YY][.ss]]

  • The Linux man page for compress:

    compress [ -f ] [ -v ] [ -c ] [ -V ] [ -r ] [ -b bits ] [ name ... ]

These notations all have similar formats:

  • [] used to indicate optional parameters.
  • | used to separate exclusive choices.
  • ... used to mean that the preceding thing occurs multiple times ([x]... and [x...] are the same form of this).
  • Not shown in examples: () for grouping, especially when non-optional parameters and a | is involved.

My question is: I've always just taken it as a given that command line parameters are documented this way. It's easy to understand because it's pretty much ubiquitous, and when I document them myself I just naturally do it this way. However, does this notation have a name?

For example, if I were to write some documentation guidelines that said "all command line parameters must be documented in _______ format" or something along those lines, what would I say?

Jason C
  • 391
  • 2
  • 14

1 Answers1

5

For POSIX systems there is a set of "Utility Argument Syntax" conventions published by The Open Group: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html

Somewhat related are the GNU guidelines (https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html) but they only specify how the arguments should look like, not how the documentation should be written.

Mael
  • 2,305
  • 1
  • 13
  • 26
  • I'm accepting this, and thanks a lot that is extremely helpful and what I am looking for. The reason it took me a few minutes is from your link I tried to go back to earlier POSIX standards to see when that started, and also tried to build a connection to Microsoft's similar syntax. I didn't find any additional interesting info: MS's [command line standard](https://technet.microsoft.com/en-us/library/ee156811.aspx) does not cover documentation, and I wasn't able to put together a historical connection based on time, but I'm assuming that the POSIX standard served as a basis all around. – Jason C Sep 22 '16 at 14:54
  • It might be worth pointing out that this syntax was probably borrowed from [EBNF notation (Extended Backus–Naur Form)](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form). – amon Sep 22 '16 at 20:34