From: Rony G. Flatscher <Rony.F<latscher@wu...> - 2009-09-21 06:46:55
Jean-Louis Faucher has done an incredible work on the rail-diagrams in
the OOo-documentation, which he subsumes under the term "docMusings".
The rail-diagrams now really look like rail-diagrams, making it very
easy (especially for necomers and end-user programmers) to understand
the syntax, even extremely complicated ones as the STREAM-BIF.
Jean-Louis' log-page seems to be at:
The latest "rexxref.pdf" built by him experimentally is in a zip-archive
there, an unzipped version can be found and loaded from:
>From here, I see several alternatives :
Don't change the current doc, because the new pdfs are big and the build
process becomes longer when transforming to images.
Keep the textual syntax diagrams in the source and transform them during the
build. This is the technique I use currently.
Replace the current doc by the transformed doc where the textual syntax
diagrams have been replaced by a reference to an image. The syntax diagrams
are described in a separate file (one per sgml file), using the DITA XML
If the DITA XML is considered too verbose, a more concise description can be
generated, like BNF or equivalent (to define).
Now I plan to continue the work on the transform script, to implement the
options -dsssl and -xslt. The idea is to generate either a file that can be
processed by Jade or a file that can be processed by an XSLT processor.It
should be possible to pass from one format to the other format, a kind of
roundtrip. After all, there are very few things to adapt... That would allow
to edit the source with an XML editor, test other toolsets, while using Jade
and Tex to generate the pdf/html.