DOCBOOK: Proposal for BNF/EBNF markup

["Eve L. Maler" <elm@East.Sun.COM>]

This message contains a proposal for BNF/EBNF markup.  I based it on the 
XMLspec DTD [1], a DTD I maintain which is in widespread use but has a 
couple of known inconveniences in this area.  I'm taking the opportunity to 
try and fix those now, along with making the whole thing "speak DocBook."

It meets these requirements:

- Express enough production details to allow for linking between
   definitions of, and references to, non-terminals
- Allow for grouping and titling of productions
- Allow for comments interspersed among the production details
- Allow for linking to special constraints
- Allow for free-form BNF content, a la synopsis

It is a non-requirement to support literate programming or full modeling of 
a production. The main theme of the design is that it's intended for the 
purpose of documentation.

Proposal:

<!-- add productionset to %formal.class; -->
<!ELEMENT productionset
	((%formalobject.title.content;), (prod|prodrecap|bnf)+)>
<!ELEMENT productionset %common.attrib;>

<!ELEMENT prod (lhs, rhs)>
<!ATTLIST prod %idreq.common.attrib;>

<!ELEMENT lhs (#PCDATA)>
<!ATTLIST lhs %common.attrib;>

<!ELEMENT rhs (rhsline+)>
<!ATTLIST rhs %common.attrib;>

<!ELEMENT rhsline (#PCDATA|nt|lineannotation|co)*>
<!ATTLIST rhsline %common.attrib;>

<!-- add nt to %tech.char.class; -->
<!ELEMENT nt (#PCDATA)>
<!ATTLIST nt
	%common.attrib;
	%required-XLink-to-production-ID;
 >

<!ELEMENT prodrecap EMPTY>
<!ATTLIST prodrecap
	%common.attrib;
	%required-XLink-to-production-ID;
 >

<!ELEMENT bnf (%same-as-rhsline;)*>
<!ATTLIST bnf
	%idreq.common.attrib;
	%linespecific.attrib;
 >

Description and rationale:

- A productionset is a formal object that creates a grouping of related 
productions; the grouping must have a title.  Productions may be expressed 
in one of several ways.  A prod is a production with fairly detailed 
markup, a la cmdsynopsis or funcsynopsis.  A prodrecap is a reference to an 
existing production, reproduced in this productionset for convenience.  A 
bnf is a free-form production with no special internal markup, a la 
synopsis (it has basically the same content model as programlisting, but 
has a required ID).

- A prod has an lhs (left-hand side) and an rhs (right-hand side).  The 
latter contains a series of rhslines, each of which will be presented in 
normal circumstances on separate lines of the production display.  The 
reason for the rhs container is that the current XMLspec design has no such 
container, and it's a royal pain to format.  The reason for breaking up its 
content into lines is that this was deemed (by the original XML 
specification editors) to be a necessary compromise between purity of 
modeling and practicalities of successful formatting.  It's possible that 
an sbr (syntax break), an element already in DocBook, is a better strategy 
here.

- An rhsline contains free text along with three items that need special 
markup.  An nt (non-terminal) is a reference to a non-terminal that links 
to the production where that non-terminal is defined.  A lineannotation is 
an inline comment that describes some feature of that line of the rhs, and 
will typically be found at the end of the line.  A co is a callout to a 
further description or constraint (the XMLspec DTD has an elaborate setup 
for documenting "constraints," but that seems like overkill for DocBook, 
which doesn't specialize in normative specification text).

- The content model for nt could have been EMPTY, assuming that the 
production was always defined in the current document (or in some other 
accessible place), but in practice it's easier to just supply the name.  It 
might be possible for, e.g., an XSL stylesheet to try and generate a name 
whenever no content is supplied, but this is more trouble than it's worth.

- The way DocBook's co works is backwards from XMLspec's 
constraint/constraintnote element pair, in that it assigns an ID to the co 
and makes the callout item reference it.  I actually prefer the way XMLspec 
works, but wanted to stick to known DocBook functionality.

Processing expectations:

- A productionset gets vertically set off and its title is given 
prominence.  Optionally, a table of productions is made, where the set can 
be a first-level TOC division and the individual productions can be 
second-level TOC divisions.  An xref to a productionset should generate the 
set's title.

- The contents of prod and bnf should be in a monospaced font.

- The contents of bnf should have their whitespace preserved.

- Each prod and bnf is assigned a production number, which is output to its 
left surrounded by square brackets.  An xref to either one should generate 
the production number in square brackets.

- Between the lhs and the rhs, a "gets" or "equals" symbol is 
generated.  The one used for XML specifications is ":==".  If possible, all 
the "gets" symbols should be vertically aligned.

- The first rhsline should be output directly to the right of the "gets" 
symbol.  Subsequent rhslines should start on new lines, and start at the 
same level of indentation as the first one.

- An nt (whether in text or in a production) should be linked to the 
production that defines it.

- A prodrecap should generate in place the content of the prod or bnf 
referenced.  It can output a production number, but if it does, it should 
distinguish the appearance of the number from other "live" numbers in the 
same set.  The production number can also link to the place where the 
production is defined "live."

What do y'all think?  If we come up with a design for this that we're happy 
with, I can start to harmonize the XMLspec version with it as appropriate.

	Eve

[1]
   http://www.w3.org/XML/1998/06/xmlspec.dtd (latest DTD)
   http://www.w3.org/XML/1998/06/xmlspec-v20.dtd (this release)
   http://www.w3.org/XML/1998/06/xmlspec-report.htm (latest doc'n)
   http://www.w3.org/XML/1998/06/xmlspec-report-v20.htm (this release of doc'n)

Eve Maler                                    +1 781 442 3190
Sun Microsystems XML Technology Center    elm @ east.sun.com