how-to-change-oorexx-docs

This is a collection of How To's to help you when changing ooRexx documentation.

• How to generate Railroad Diagrams
  • Syntax diagram example
    • EBNF input
    • SVG output

How to generate Railroad Diagrams

Since ooRexx 5.0 all docs use new graphical railroad syntax diagrams. Instead of the previous inlined ASCII character diagrams, the new graphical syntax diagrams are included Scalable Vector Graphics (SVG) images. We're generating these SVG images with the help of a web-based tool called Railroad Diagram Generator (RDG).

RDG accepts input in an EBNF-format and generates SVG images packed into an XHTML file.

RDG is not a one-to-one replacement for the previous ASCII character diagrams—it does not provide all forms of use that these diagrams showed.

To generate the SVG images, follow these steps:

1. Set up RDG options. On http://bottlecaps.de/rr/ui select tab "Options"
   • uncheck "Show EBNF"
   • set "Color" to "#CCCCCC" (which automatically sets approprate values for "Hue", "Saturation" and "Lightness")
   • set "Graphics width" to 860 (this limits the maximum SVG width, which makes them fit nicely on a page when included with a scale factor of 55%.
   • uncheck options "Direct recursion elimination", "Factoring", "Inline literals", and "Keep epsilon nonterminals"
2. On tab "Edit Grammar" copy/paste or Browse.. and then Load an EBNF grammar (name.ebnf file)
3. Switch to tab "View Diagram", click Radio button "SVG", Download, Save as name.xhtml into the same directory as the .ebnf file

The downloaded XHTML file contains all diagrams as embedded SVG's, so there's some post-processing necessary

• to split out each SVG and save it as a separate .svg file,
• to add font-style: italic; to each SVG's CSS text.nonterminal {…} definition (which makes function/method arguments italic), and
• to remove links added by RDG to each "nonterminal" (which would otherwise show up when hovering over a function/method argument)

The post-processing tool, ebnfXHTML.rex, can be found in sandbox/erich/docs/tools/.

Download ebnfXHTML.rex, and run it in the directory containing the .xhtml and the .svg files. It will compare all existing .svg files against the SVG images embedded in the .xhtml file and list all changes it finds, but without making any changes to the actual files yet. Check that the reported changes are correct and run again ebnfXHTML --write to write the changes.

Note that you should svn add any newly created .svg files, so that they get synced into the repository upon the next svn ci.

Syntax diagram example

EBNF input

funct_xmp ::= function_name '(' expression? (',' expression?)* ')'

SVG output