Dita Wiki
How to format DITA's syntax-diagram notation
DITA's programming domain contains a complex specialization of <figure> called <syntaxdiagram>. A syntax diagram represents the syntax of programming statements, commands, bindings, and so forth. Its elements represent groupings and organization of the parts of syntax that go into a statement, method, or function as used in programming or a command used in the console operation of a computer.
A related element, called <synph> (short for syntax phrase), allows encoding inline representations of programming syntax, and contains many of the same elements as syntaxdiagram. It does not the grouping elements,which represent block constructions. The formatting of its constituent elements is the same as for the main syntax-diagram, other than being all flow-oriented. Basically, <synph> is to HTML's <span> as <syntax-diagram> is to HTML's <div> or <table>, except that the DITA specialization contains only syntax-related markup.
Two other elements in DITA's software domain cover the simple case of dialog or interaction between a computer and a user: <systemoutput> and <userinput>. By contrast, the <syntaxdiagram> and <synph> family covers actual programming syntax, not interaction.
Within this topic is a description of how to read the Railroad Track form of output:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/index.jsp?topic=/db2/rbafzmsthowtous.htm
Output options that should be considered:
- Unix BNF ("bars and braces") (current implementation in DITA Open Toolkit; apparently needs work)
- IBM's character-graphic based Railroad tracks (with ANSI character fallback for HTML)
- The original IBM solution involves a C program that builds a matrix of character graphics, not yet considered for contribution to Open Source
- Pascal graphically drawn railroad tracks (these could be done as SVG by interpreting the syntax diagram elements/attr values as drawing orders)
- Screen readable format (there is a form of output called dotted decimal; could be based on the current BNF set of templates, using alternate flow style of lines and indents vs bars and brace notation)
Don to look up the published IBM Technical Report on how to author Syntax Diagram markup (out of Raleigh about 10 years ago)
Status: still looking. Might be a Technical Disclosure instead--different publishing site.
Links Analysis of syntax diagrams (background on relationship of railroad track visualization to BNF):
- Case Closed: the 500 Language Problem is Cracked
- Semi-automatic Grammar Recovery
- Automatic generation of Syntax Diagrams with a Given Grammar
- Factbites--Syntax Diagram
Other publications:
- CASCON 2004 Workshop Report; The Production of Accessible Software – Issues and Challenges; IBM Technical Report: TR-74.203-16; October 2004
- PDF link does not work. Google the title and browse the cached HTML version instead.
- Improved accessibility of syntax diagrams using Scalable Vector graphics and the dotted decimal format
http://www.priorartdatabase.com/IPCOM/000130427/ (Don is looking for the free, public citation for this disclosure)
Examples online:
http://tech.groups.yahoo.com/group/dita-users/message/601 (discussion with links)
- Introduction (to Standard C notation)
- Converting a PCCTS Grammar into Syntax Diagrams
No longer available on the Web--Converting a PCCTS Grammar--from photocopy
The head of IBM's iSeries documentation group provided these samples from their web site.
Smaller diagrams - go down to "Built-in functions" and follow most any link under there:
Larger groups in one set of syntax:
Syntax overload - follow this link, and scroll down to "CASE expressions" for a reasonably complex one, and to "CAST specification" for a really big one (there are other big ones in here too):