This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Proposal for BNF/EBNF markup
- To: docbook at lists dot oasis-open dot org
- Subject: DOCBOOK: Proposal for BNF/EBNF markup
- From: "Eve L. Maler" <elm at east dot sun dot com>
- Date: Sun, 19 Mar 2000 16:06:10 -0500
- Reply-To: docbook at lists dot oasis-open dot org
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