I'm sorry but the example you gave for the EBNF diagram it totally
confussing. I can't "read" the picture and understand what the syntax is.
It would seem to me that you would have to be an expert in EBNF to tell the
difference between what is something I code in the statement and special
symbols of EBNF.
EBND does not get my vote.
With railroad tracks, it's simple.follow the track: wherever it leads you is
what you can code. No special symbols. It handles complex diagrams. Even
a simple person like myself can follow it without training.
Thanks,
Johns
_____
From: Bill Turner, WB4ALM [mailto:[EMAIL PROTECTED]
Sent: Monday, August 25, 2008 9:46 PM
To: Open Object Rexx Developer Mailing List
Subject: Re: [Oorexx-devel] Railroad tracks in docs
For my two cents worth, I prefer see language definitions stated in one of
the BNF variants.
In particular, a slight modification to the Extended Backus-Naur Form (EBNF)
is my preferred "syntax description".
In EBNF, the '<' '>' '[' ']' '{' '}' '|' ';' and '+'
Special Characters have special meaning in the syntax diagrams, and if any
of these are required in the actual definitions they must be quoted. (In
actual practice, any REQUIRED characters are quoted, and the term <quote> is
frequently used to represent a real quote.
1. Definitions are terminated by a semicolon.
2. Terms or options are enclosed in angle brackets.
E.G. <new>
3. Required characters are enclosed in a pair of single quotes.
4. Optional items enclosed in square brackets.
E.G. [<item-x>]
5. Alternative choices are separated by the '|' symbol.
E.G., <alternative-A> | <alternative-B>
6. Where you have a list of items, and one or more MUST be selected, the
items are enclosed in curly brackets.
E.G. { <option1> | <option2> | <option3> }
7. Items repeating 0 or more times are followed by an ellipse (...)
More accurately, the ellipse means "may be repeated 0 or more times"
E.G. <word> ::= <letter> ...
8. Items repeating 1 or more times are followed by a '+'
E.G. <digits> ::= <digit>+
9. Where items need to be grouped they are enclosed in simple parentheses
10. When text can be displayed in color, then I prefer using color rather
than quoting required text.
Overlay_function ::= 'OVERLAY(' <new> ',' <target> [',' [<n>] [','
[<length>] [','<pad>]]] ')'
Overlay_function ::= OVERLAY( <new>,<target> [,[<n>] [,[<length>]
[,<pad>]]] )
By the way OVERLAY(<new>,<target>,,,) is not valid according to the above
diagram.
But OVERLAY(<new>,<target>,,,<pad>) is.
- - - - -
Using the above rules, I think the following is a correct definition for
"quote" in Rexx.
As it turn out, defining the term <quote> and <quotedString> in many
languages are frequently the hardest - especially when you allow them to be
used the way we do. (Which I like!)
<Quote> ::= { <SingleQuoteChar> | <DoubleQuoteChar> };
<QuotedString> ::= { <SingleQuoteChar> [<text>] [<DoubleQuoteChar>]
[<text>] <SingleQuoteChar> |
<DoubleQuoteChar> [<text>] [<SingleQuoteChar>]
[<text>] <DoubleQuoteChar> |
<SingleQuoteChar> [<text>]
[<SingleQuoteChar><SingleQuoteChar>] [<text>] <SingleQuoteChar> |
<DoubleQuoteChar> [<text>]
[<DoubleQuoteChar><DoubleQuoteChar>] [<text>] <DoubleQuoteChar> |
};
<SingleQuoteChar> ::= { ApostropheChar | ''' };
<DoubleQuoteChar> ::= { QuoteChar | '"' };
- - - - -
I found Mike's syntax to be very easy to read and understand, and I don't
think that the use of the square brackets to indicate optional items is
going to cause anybody reading grief, as long as we all agree on what
documentation rules we are actually going to use. Besides, unless I'm
missing something, in Rexx the square bracket is only used to indicate a
specific element of an array.
Railroad Tracks?
NO! Never been able to explain them adequately to my programming students -
and usually because they require multiple lines to display, it's easy to
"lose your place".
BNF notation can be used to PRECISELY define a language, and if a single
element requires "more than one line", then either the element is too
complex, or it needs to be sub-defined for clarity. Personally, I like the
use of the angle brackets in defining "terms" , because then I know what the
actual "term name" is, and can expect to find a textual definition of that
term a little later on in the documentation.
If we stick to a standard variation of BNF, then there are many tools that
we can use to assist us, in defining the language, and in keeping it as pure
and simple as can be. We also may find tools that we can use to assist in
the creation of actual documentation as well. Of course, we can also write a
few of those tools in Rexx, but that is another story...
- - - -
All said, I would suggest that we use a standard notation such as the
Extended Backus-Naur Form as defined in ISO-14977 and
demonstrated in the wikipedia defintions at:
http://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form
- - - -
/s/ Bill Turner, wb4alm
-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Oorexx-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/oorexx-devel
