This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: Proposal for BNF/EBNF markup
- To: docbook at lists dot oasis-open dot org
- Subject: Re: DOCBOOK: Proposal for BNF/EBNF markup
- From: Norman Walsh <ndw at nwalsh dot com>
- Date: Wed, 22 Mar 2000 06:35:06 -0500
- References: <4.2.0.58.20000319113445.00aa88a0@abnaki.East.Sun.Com>
- Reply-To: docbook at lists dot oasis-open dot org
/ "Eve L. Maler" <elm@east.sun.com> was heard to say:
| - 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
I definitely want the wrapper (having attempted to write a stylesheet
for XMLSpec :-), but I'm uncomfortable with the name rhslines for the
inner element. Maybe 'prodrhs' instead. Or something.
I think the thing to keep in mind is that productions with multiple RHS
are just a shortcut for multiple productions. I could say:
LHS = RHS1
LHS = RHS2
LHS = RHS3
But I'd rather say
LHS = RHS1
| RHS2
| RHS3
Or maybe that's not relevant.
| modeling and practicalities of successful formatting. It's possible that
| an sbr (syntax break), an element already in DocBook, is a better strategy
| here.
No, I like the idea of having wrappers around the RHS options.
| - 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
How does lineannotation in this context map to XMLSpec?
| 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).
Hmmm. I think folks are going to want to be able to produce things that
look a lot like XMLSpec productions with this. That's become a common
documentation model for these things.
I'm not opposed to adding a new element to DocBook for this purpose.
<!ELEMENT rhsline (#PCDATA|nt|lineannotation|constraint)*>
where constraint has some non-empty content model.
| - 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.
It does mean that some checking should be done on the content of <nt>'s
that do have IDREFs though, yes? :-)
| - 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.
For this application, I think the linking has to work the other
way around. "This is the constraint: foo" and "here's where you
look for more information about what 'foo' means". I think this
is especially true since constraints in productions basically
have to be pretty short strings in order to hope for reasonable
formatting.
| - The contents of bnf should have their whitespace preserved.
What is bnf, just a PCDATA way of making anything I want go in a
production? This seems like it would be very hard to
format. Maybe it needs to be
<!ELEMENT prod (lhs, (rhs|bnf))>
| - An nt (whether in text or in a production) should be linked to the
| production that defines it.
Because the user adds an IDREF, yes? Or simply because it has the same
content as some other productions LHS?
| 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.
It looks like a good start to me. Other users who have expressed an
interest in BNF, please speak up now! :-)
Be seeing you,
norm
--
Norman Walsh <ndw@nwalsh.com> | Resist the urge to hurry; it will
http://www.oasis-open.org/docbook/ | only slow you down--Bruce Eckel
Chair, DocBook Technical Committee |