Well, there is already a Wiki about creating rail-diagrams at <https://sourceforge.net/p/oorexx/wiki/how-to-change-oorexx-docs/>!
The ooRexx Wiki home is at: <https://sourceforge.net/p/oorexx/wiki/Home/>. ---rony On 01.03.2020 19:39, Rony G. Flatscher wrote: > > While incorporating the documentation for EventSemaphore and MutexSemaphore I > had a need to create > some rail-diagrams for the methods. It may be the case that others may have a > need for that > earlier or later, therefore this posting. > > Remembering that Erich once posted the information that he would use some web > based service for > that I researched and (think that I) found it at: > <https://www.bottlecaps.de/rr/ui>. This site is > able to create rail-diagrams from W3C's EBNF notations that can be submitted > directly there ("Edit > Grammar" tab) which then gets displayed in the "View Diagram" tab, which > allows to export the > rail-diagram either as svg or png. > > As the rexxref rail-diagrams are stored in > "docs\trunk\rexxref\en-US\images\classes\" in svg form > I chose to use the "svg" download option. > > E.g. if you enter the EBNF "acquire ::= 'acquire(' timeout? ')'" in the > "Edit Grammar" tab, the > "View Diagram" will display something like: > > The downloaded file is in xhtml and includes among other things the > formatting definitions of the > web service and also the svg-data, e.g.: > > <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" > "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";> > <html xmlns="http://www.w3.org/1999/xhtml";> > <head> > <meta http-equiv="Content-Type" content="application/xhtml+xml; > charset=UTF-8" /> > <meta name="generator" content="Railroad Diagram Generator 1.60" /> > <style type="text/css"> > ::-moz-selection > { > color: #FFFCF0; > background: #0F0C00; > } > ::selection > { > color: #FFFCF0; > background: #0F0C00; > } > .ebnf a, .grammar a > { > text-decoration: none; > } > .ebnf a:hover, .grammar a:hover > { > color: #050400; > text-decoration: underline; > } > .signature > { > color: #806600; > font-size: 11px; > text-align: right; > } > body > { > font: normal 12px Verdana, sans-serif; > color: #0F0C00; > background: #FFFCF0; > } > a:link, a:visited > { > color: #0F0C00; > } > a:link.signature, a:visited.signature > { > color: #806600; > } > a.button, #tabs li a > { > padding: 0.25em 0.5em; > border: 1px solid #806600; > background: #F1E8C6; > color: #806600; > text-decoration: none; > font-weight: bold; > } > a.button:hover, #tabs li a:hover > { > color: #050400; > background: #FFF6D1; > border-color: #050400; > } > #tabs > { > padding: 3px 10px; > margin-left: 0; > margin-top: 58px; > border-bottom: 1px solid #0F0C00; > } > #tabs li > { > list-style: none; > margin-left: 5px; > display: inline; > } > #tabs li a > { > border-bottom: 1px solid #0F0C00; > } > #tabs li a.active > { > color: #0F0C00; > background: #FFFCF0; > border-color: #0F0C00; > border-bottom: 1px solid #FFFCF0; > outline: none; > } > #divs div > { > display: none; > overflow:auto; > } > #divs div.active > { > display: block; > } > #text > { > border-color: #806600; > background: #FFFEFA; > color: #050400; > } > .small > { > vertical-align: top; > text-align: right; > font-size: 9px; > font-weight: normal; > line-height: 120%; > } > td.small > { > padding-top: 0px; > } > .hidden > { > visibility: hidden; > } > td:hover .hidden > { > visibility: visible; > } > div.download > { > display: none; > background: #FFFCF0; > position: absolute; > right: 34px; > top: 94px; > padding: 10px; > border: 1px dotted #0F0C00; > } > #divs div.ebnf, .ebnf code > { > display: block; > padding: 10px; > background: #FFF6D1; > width: 1000px; > } > #divs div.grammar > { > display: block; > padding-left: 16px; > padding-top: 2px; > padding-bottom: 2px; > background: #FFF6D1; > } > pre > { > margin: 0px; > } > .ebnf div > { > padding-left: 13ch; > text-indent: -13ch; > } > .ebnf code, .grammar code, textarea, pre > { > font:12px SFMono-Regular,Consolas,Liberation > Mono,Menlo,Courier,monospace; > } > tr.option-line td:first-child > { > text-align: right > } > tr.option-text td > { > padding-bottom: 10px > } > table.palette > { > border-top: 1px solid #050400; > border-right: 1px solid #050400; > margin-bottom: 4px > } > td.palette > { > border-bottom: 1px solid #050400; > border-left: 1px solid #050400; > } > a.palette > { > padding: 2px 3px 2px 10px; > text-decoration: none; > } > .palette > { > -webkit-user-select: none; > -khtml-user-select: none; > -moz-user-select: none; > -o-user-select: none; > -ms-user-select: none; > } > </style><svg xmlns="http://www.w3.org/2000/svg";> > <defs> > <style type="text/css"> > @namespace "http://www.w3.org/2000/svg";; > .line {fill: none; stroke: #332900;} > .bold-line {stroke: #141000; shape-rendering: crispEdges; > stroke-width: 2; } > .thin-line {stroke: #1F1800; shape-rendering: crispEdges} > .filled {fill: #332900; stroke: none;} > text.terminal {font-family: Verdana, Sans-serif; > font-size: 12px; > fill: #141000; > font-weight: bold; > } > text.nonterminal {font-family: Verdana, Sans-serif; > font-size: 12px; > fill: #1A1400; > font-weight: normal; > } > text.regexp {font-family: Verdana, Sans-serif; > font-size: 12px; > fill: #1F1800; > font-weight: normal; > } > rect, circle, polygon {fill: #332900; stroke: #332900;} > rect.terminal {fill: #FFDB4D; stroke: #332900;} > rect.nonterminal {fill: #FFEC9E; stroke: #332900;} > rect.text {fill: none; stroke: none;} > polygon.regexp {fill: #FFF4C7; stroke: #332900;} > </style> > </defs></svg></head> > <body> > *<xhtml:p xmlns:xhtml="http://www.w3.org/1999/xhtml"; > style="font-size: 14px; > font-weight:bold"><xhtml:a name="acquire">acquire:</xhtml:a></xhtml:p><svg > xmlns="http://www.w3.org/2000/svg"; width="309" height="69">* > <defs> > <style type="text/css"> > @namespace "http://www.w3.org/2000/svg";; > .line {fill: none; stroke: #332900;} > .bold-line {stroke: #141000; shape-rendering: crispEdges; > stroke-width: 2; } > .thin-line {stroke: #1F1800; shape-rendering: crispEdges} > .filled {fill: #332900; stroke: none;} > text.terminal {font-family: Verdana, Sans-serif; > font-size: 12px; > fill: #141000; > font-weight: bold; > } > text.nonterminal {font-family: Verdana, Sans-serif; > font-size: 12px; > fill: #1A1400; > font-weight: normal; > } > text.regexp {font-family: Verdana, Sans-serif; > font-size: 12px; > fill: #1F1800; > font-weight: normal; > } > rect, circle, polygon {fill: #332900; stroke: #332900;} > rect.terminal {fill: #FFDB4D; stroke: #332900;} > rect.nonterminal {fill: #FFEC9E; stroke: #332900;} > rect.text {fill: none; stroke: none;} > polygon.regexp {fill: #FFF4C7; stroke: #332900;} > </style> > </defs> > *<polygon points="9 17 1 13 1 21"/>****<polygon points="17 17 9 13 9 > 21"/>****<rect x="31" > y="3" width="76" height="32" rx="10"/>****<rect x="29" y="1" width="76" > height="32" > class="terminal" rx="10"/>****<text class="terminal" x="39" > y="21">acquire(</text><a > xmlns:xlink="http://www.w3.org/1999/xlink"; xlink:href="#timeout" > xlink:title="timeout">****<rect x="147" y="35" width="68" > height="32"/>****<rect x="145" > y="33" width="68" height="32" class="nonterminal"/>****<text > class="nonterminal" x="155" > y="53">timeout</text></a><rect x="255" y="3" width="26" height="32" > rx="10"/>****<rect x="253" > y="1" width="26" height="32" class="terminal" rx="10"/>****<text > class="terminal" x="263" > y="21">)</text>****<svg:path xmlns:svg="http://www.w3.org/2000/svg"; > class="line" d="m17 17 h2 > m0 0 h10 m76 0 h10 m20 0 h10 m0 0 h78 m-108 0 h20 m88 0 h20 m-128 0 q10 0 > 10 10 m108 0 q0 -10 > 10 -10 m-118 10 v12 m108 0 v-12 m-108 12 q0 10 10 10 m88 0 q10 0 10 -10 > m-98 10 h10 m68 0 h10 > m20 -32 h10 m26 0 h10 m3 0 h-3"/>****<polygon points="299 17 307 13 307 > 21"/>****<polygon > points="299 17 291 13 291 21"/></svg>*<xhtml:p > xmlns:xhtml="http://www.w3.org/1999/xhtml";> > <xhtml:div class="ebnf"><xhtml:code> > <div><a href="#acquire" title="acquire">acquire</a> ::= > 'acquire(' <a href="#timeout" title="timeout">timeout</a>? > ')'</div></xhtml:code></xhtml:div> > </xhtml:p> > <xhtml:p xmlns:xhtml="http://www.w3.org/1999/xhtml";>no > references</xhtml:p><xhtml:br xmlns:xhtml="http://www.w3.org/1999/xhtml"; > /><xhtml:hr xmlns:xhtml="http://www.w3.org/1999/xhtml"; /> > <xhtml:p xmlns:xhtml="http://www.w3.org/1999/xhtml";> > <xhtml:table class="signature" border="0"> > <xhtml:tr> > <xhtml:td style="width: 100%"> </xhtml:td> > <xhtml:td valign="top"> > <xhtml:nobr class="signature">... generated by <xhtml:a > name="Railroad-Diagram-Generator" class="signature" > title="https://www.bottlecaps.de/rr/ui"; > href="https://www.bottlecaps.de/rr/ui"; target="_blank">Railroad Diagram > Generator</xhtml:a></xhtml:nobr> > </xhtml:td> > <xhtml:td><xhtml:a name="Railroad-Diagram-Generator" > title="https://www.bottlecaps.de/rr/ui"; > href="https://www.bottlecaps.de/rr/ui"; target="_blank"><svg > xmlns="http://www.w3.org/2000/svg"; width="16" height="16"> > <g transform="scale(0.178)"> > <circle cx="45" cy="45" r="45" > style="stroke:none; fill:#FFCC00"/> > <circle cx="45" cy="45" r="42" > style="stroke:#332900; stroke-width:2px; fill:#FFCC00"/> > <line x1="15" y1="15" x2="75" y2="75" > stroke="#332900" style="stroke-width:9px;"/> > <line x1="15" y1="75" x2="75" y2="15" > stroke="#332900" style="stroke-width:9px;"/> > <text x="7" y="54" style="font-size:26px; > font-family:Arial, Sans-serif; font-weight:bold; fill: #332900">R</text> > <text x="64" y="54" style="font-size:26px; > font-family:Arial, Sans-serif; font-weight:bold; fill: #332900">R</text> > </g></svg></xhtml:a></xhtml:td> > </xhtml:tr> > </xhtml:table> > </xhtml:p> > </body> > </html> > > In the above sample the text relevant for our svg-format is colored in green. > The blue colored > line contains at the very end the bounding box needed for this particular svg > and needs to be > copied to the boilerplate svg file as demonstrated below. > > Note: the red text needs either to be deleted or to be commented out in XML > terms (i.e. enquoted > with "<!--" and "-->"). > > The below svg file that was saved as "mutexsemaphore_acquire.svg" and used > one of Erich's svg > files as boilerplate by copying over the formatting settings. Here the > content of > "mutexsemaphore_acquire.svg": > > <svg xmlns="http://www.w3.org/2000/svg"; *width="309" height="69"*> > <defs> > <style type="text/css"> > @namespace "http://www.w3.org/2000/svg";; > .line {fill: none; stroke: #1F1F1F;} > .bold-line {stroke: #0A0A0A; shape-rendering: crispEdges; > stroke-width: 2; } > .thin-line {stroke: #0F0F0F; shape-rendering: crispEdges} > .filled {fill: #1F1F1F; stroke: none;} > text.terminal {font-family: Verdana, Sans-serif; > font-size: 12px; > fill: #0A0A0A; > font-weight: bold; > } > text.nonterminal {font-family: Verdana, Sans-serif; font-style: > italic; > font-size: 12px; > fill: #0D0D0D; > font-weight: normal; > } > text.regexp {font-family: Verdana, Sans-serif; > font-size: 12px; > fill: #0F0F0F; > font-weight: normal; > } > rect, circle, polygon {fill: #1F1F1F; stroke: #1F1F1F;} > rect.terminal {fill: #cccccc; stroke: #1F1F1F;} > rect.nonterminal {fill: #E3E3E3; stroke: #1F1F1F;} > rect.text {fill: none; stroke: none;} > polygon.regexp {fill: #EFEFEF; stroke: #1F1F1F;} > </style> > </defs> > > <polygon points="9 17 1 13 1 21"/> <polygon points="17 17 9 13 9 > 21"/> <rect x="31" y="3" > width="76" height="32" rx="10"/> <rect x="29" y="1" width="76" > height="32" class="terminal" > rx="10"/> <text class="terminal" x="39" y="21">acquire(</text> <!-- <a > xmlns:xlink="http://www.w3.org/1999/xlink"; xlink:href="#timeout" > xlink:title="timeout"> --> > <rect x="147" y="35" width="68" height="32"/> <rect x="145" y="33" > width="68" height="32" > class="nonterminal"/> <text class="nonterminal" x="155" > y="53">timeout</text> <!-- </a> --> > <rect x="255" y="3" width="26" height="32" rx="10"/> <rect x="253" y="1" > width="26" > height="32" class="terminal" rx="10"/> <text class="terminal" x="263" > y="21">)</text> > <svg:path xmlns:svg="http://www.w3.org/2000/svg"; class="line" d="m17 17 > h2 m0 0 h10 m76 0 h10 > m20 0 h10 m0 0 h78 m-108 0 h20 m88 0 h20 m-128 0 q10 0 10 10 m108 0 q0 > -10 10 -10 m-118 10 v12 > m108 0 v-12 m-108 12 q0 10 10 10 m88 0 q10 0 10 -10 m-98 10 h10 m68 0 h10 > m20 -32 h10 m26 0 > h10 m3 0 h-3"/> <polygon points="299 17 307 13 307 21"/> <polygon > points="299 17 291 13 291 > 21"/></svg> > > So the green text was copied over from the generated xhtml file, the red one > was commented out > (would also be possible to fully remove it). > > Of course, the more complex the EBNF the more watchouts for those > interspersed xhtml links > (opening tag "<a..>" and closing tag "</a>") is necessary. > > But other than that it seems to be a straight-forward and easy procedure. > > ---rony > > P.S.: The W3C EBNF does not know of Rexx' default values, hence they cannot > be currently > represented. Maybe once ooRexx 5.0 went GA it may become interesting to > tackle this. >
_______________________________________________ Oorexx-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/oorexx-devel
