3

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?

4

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.

  • 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 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). – amon Sep 22 '16 at 20:34

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.