Re: Command Notation

[Scott McClare <smcclare -at- DY4 -dot- COM>]

> -----Original Message-----
> From: Anne Weiner [SMTP:annew -at- INTERDYN -dot- COM]
> Sent: Wednesday, July 29, 1998 9:33 PM
> Subject:      Command Notation
>
>Folks,
>
>Lo these many years I was involved in a project whereby a command
syntax
>was documented. I remember that in the planning stage we discussed two
>different alternatives for notation, one was "railroad diagramming" (I
>think), the other was a hyphenated term which I have completely
>forgotten.

>Now I'm involved in a similar project and would like a reference to the
>second notation. Wouldn't you know I'd want *that* one! I'd really
>appreciate someone jogging my failing memory. If you could also mention
>a resource, I'd be thrilled.

It looks to me like you're thinking of the "Backus-Naur" syntax.  I'm
not aware of any print reference that documents it (perhaps someone else
on the list can enlighten all of us!), but maybe you can glean something
from the BNF entry in the Jargon File:

----- Cut Here -----

:BNF: /B-N-F/ /n./  1. [techspeak] Acronym for `Backus-Naur
   Form', a metasyntactic notation used to specify the syntax of
   programming languages, command sets, and the like.  Widely used for
   language descriptions but seldom documented anywhere, so that it
   must usually be learned by osmosis from other hackers.  Consider
   this BNF for a U.S. postal address:

      <postal-address> ::= <name-part> <street-address> <zip-part>

      <personal-part> ::= <name> | <initial> "."

      <name-part> ::= <personal-part> <last-name> [<jr-part>] <EOL>
                    | <personal-part> <name-part>

      <street-address> ::= [<apt>] <house-num> <street-name> <EOL>

      <zip-part> ::= <town-name> "," <state-code> <ZIP-code> <EOL>

   This translates into English as: "A postal-address consists of a
   name-part, followed by a street-address part, followed by a
   zip-code part.  A personal-part consists of either a first name or
   an initial followed by a dot.  A name-part consists of either: a
   personal-part followed by a last name followed by an optional
   `jr-part' (Jr., Sr., or dynastic number) and end-of-line, or a
   personal part followed by a name part (this rule illustrates the
   use of recursion in BNFs, covering the case of people who use
   multiple first and middle names and/or initials).  A street address
   consists of an optional apartment specifier, followed by a street
   number, followed by a street name.  A zip-part consists of a
   town-name, followed by a comma, followed by a state code, followed
   by a ZIP-code followed by an end-of-line."  Note that many things
   (such as the format of a personal-part, apartment specifier, or
   ZIP-code) are left unspecified.  These are presumed to be obvious
   from context or detailed somewhere nearby.  See also {parse}.
   2. Any of a number number of variants and extensions of BNF proper,
   possibly containing some or all of the {regexp} wildcards such
   as `*' or `+'.  In fact the example above isn't the pure
   form invented for the Algol-60 report; it uses `[]', which was
   introduced a few years later in IBM's PL/I definition but is now
   universally recognized.  3. In {{science-fiction fandom}}, a
   `Big-Name Fan' (someone famous or notorious).  Years ago a fan
   started handing out black-on-green BNF buttons at SF conventions;
   this confused the hacker contingent terribly.

----- Cut Here -----

Backus-Naur is very similar to the command description syntax used in
the old MS-DOS manuals; you might be able to find a suitable substitute
there.

Incidentally, the Jargon File (the public-domain, canonical glossary of
hacker lingo) makes very amusing reading; it can be found at
http://www.jargon.org/.  Enjoy.

Scott

--
Scott McClare - Technical Writer
DY 4 Systems Inc. (613) 599-9199 x516
smcclare -at- dy4 -dot- com
"Though this be madness, yet there is method in't." - Polonius