Re[2]: Documenting a Programming Language. WAS:Syntax Diagra

[Dan Roberts <Dan_Roberts -at- IBI -dot- COM>]

     I remember IBM going from the linear approach with the brackets and
     braces and | bars to the syntax diagrams (which somehow acquired the
     name 'railroad' diagrams - tho i'm not sure why). The idea was that
     the linear approach was difficult to read and understand and remember
     the various distinctions between what brackets means and braces meant
     and brackets inside braces and braces inside brackets and .....

     for example, you might have:
     pkzip {-a|-h|-v{b|o|d}} "targetfile" "sourcefile"

     The syntax diagrams, while a beast to code in BookMaster, where
     considered to be easier to read and understand and clearer in
     indicating required and optional portions of the syntax.

     for example

     pkzip--|-------------|-targetfile-----sourcefile
            |--- -a ------|
            |--- -h ------|
            |--- -v opt---|

        I'd generall vote for the syntax diagram. If the diagram becomes out of
control with options and branches and such, you can always break it apart into
pieces, or you can compress parts (as in the '-v opt' above) to move stuff from
the diagram into text.

______________________________ Reply Separator _________________________________
Subject: Re: Documenting a Programming Language. WAS:Syntax Diagrams
Author:  Peter Gold <pgold -at- netcom -dot- com> at tcpgate
Date:    11/20/96 10:58 AM


[snipped]

I never did this myself, but I recall a discussion of syntax diagram
models a friend of mine presented some time back. There's something like
a "railroad" diagram and another form of notation that I can't recall the
name of.

Both are ascii text, but one is sort of graphic about options and branches,
and the other is more linear as: