[fpc-pascal] Documentation, syntax diagrams

[Jürgen Hestermann]

Am 2014-01-10 09:09, schrieb Michael Van Canneyt:
 >> But why is the heading part of the diagram?
 > Because that is how the typesetting mechanism for syntax diagrams work.

That's not true (at least not in diagrams other than in Free Pascal).
It is very illogical to begin a diagram with the name of what the diagramm should specify.
The name has to be put *in front* of the diagram but not inside.
That's like writing a procedure or function and the first command
after the begin is a (recursively) call of the procedure itself.
This would lead to an endless loop.

See page 61 where "object types" are declared with a correct diagramm.
The diagram name ("object types") is on an extra line and
the diagram itself (which starts with 2 arrows) begins on the next line.
So when I start my run throught the diagram at the 2 arrows the first word
I can get is "packed" (and not "object types").
The arrows/line starts *after* the name, not before.
But already the next line is incorrect again because "heritage" is
part of the diagram (the line/2 arrows start left of it but should not).

Look at http://en.wikipedia.org/wiki/Syntax_diagram and see the diagrams at the bottom.
These are correct syntax diagrams.
The name ("expression:", "term:", "factor:", etc.) is on one line
and the diagram (the line which here starts with a circle) begins on the next line.
Name and diagram can also be on one line (though this makes it already less clear)
but the name of the diagram should never appear after the 2 arrows (which start
the path).