Re: DOCBOOK: Proposal for BNF/EBNF markup

["Eve L. Maler" <elm at east dot sun dot com>]

At 06:35 AM 3/22/00 -0500, Norman Walsh wrote:
>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.

Sorry, I wasn't clear about the semantics of rhsline.  It is literally to 
create several lines in the output for convenience of reading/formatting -- 
it has no production semantics whatsoever.  That's why I suggested (further 
down in my proposal) that maybe we want to allow the rhs element to contain 
the sbr element, which is already in DocBook for this purpose.  The rhsline 
approach is just the one that XMLspec happened to take.

>| - 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?

It's the same as the com (comment) element.

>| 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.

Okay, in that case, I can flesh out the proposal with XMLspec-like 
constraint/constraintnote stuff.

>| - 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? :-)

Yes, ideally, although we haven't been doing that in XMLspec.  Actually, 
what XMLspec does is to have two elements, nt (for references to 
productions in the current document) and xnt (for references to productions 
in other documents); the former bears an IDREF and the latter bears a URI 
reference.  On the former, you could guarantee access to the production, 
and therefore snatch up its lhs content and reproduce it in place of an 
empty nt.  Thoughts?

>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.

Great.  With this and the encouragement to add constraint stuff above, I'm 
very happy.

>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

bnf is the free-form workaround when you want to include content in the 
production that the markup doesn't support, kind of like synopsis.  I toyed 
with just reusing programlisting here at first, but it doesn't require an 
ID.  Same problem with synopsis itself (which, come to think of it, is a 
closer match than programlisting because a production is a meta-thing, 
whereas a listing is a thing-itself).

>| - 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?

The former.  It gets explicitly linked.

         Eve

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