Re: DOCBOOK: Proposal for BNF/EBNF markup

["Eve L. Maler" <Eve.Maler@east.sun.com>]

See below for comments:

At 02:48 PM 3/22/00 -0500, Norman Walsh wrote:
>/ "Eve L. Maler" <elm@east.sun.com> was heard to say:
>| 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.
>
>I'm not sure I follow your description in either case. Given what you
>originally suggested:
>
>   <!ELEMENT prod (lhs, rhs)>
>   <!ELEMENT lhs (#PCDATA)>
>   <!ELEMENT rhs (rhsline+)>
>   <!ELEMENT rhsline (#PCDATA|nt|lineannotation|co)*>
>
>Is this not how you'd markup production 29 from the XML Rec?
>
><prod>
>   <lhs>markupdecl</lhs>
>   <rhs>
>     <rhsline><nt>elementdecl</nt></rhsline>
>     <rhsline><nt>AttlistDecl</nt></rhsline>
>     <rhsline><nt>EntityDecl</nt></rhsline>
>     <rhsline><nt>NotationDecl</nt></rhsline>
>     <rhsline><nt>PI</nt></rhsline>
>     <rhsline><nt>Comment</nt></rhsline>
>     <rhsline>
>       <lineannotation>VC: Proper Declaration/PE Nesting</lineannotation>
>     </rhsline>
>     <rhsline>
>       <lineannotation>WFC: PEs in Internal Subset</lineannotation>
>     </rhsline>
>   </rhs>
></prod>
>
>Looking at that, I see two things:
>
>  1. They aren't lines (look at how [29] is formatted)
>  2. Sbr isn't relevant at all, what I want to do is separate alternate
>     right-hand-sides.

No, rhsline is not equivalent to alternate right-hand sides.  It's 
equivalent to the output of yet another line of rhs "stuff."  The way 
XMLspec does it, you actually have multiple rhs elements (instead of 
multiple rhsline elements), and each one contains simply a "line" of rhs 
code.  All the occurrence symbols are literally typed into the content of 
rhs/rhsline.

I now understand why you were thinking of it this way (and I also realize I 
should have provided an example in my proposal!): It's pretty natural to 
interpret each rhs/rhsline as "an alternate rhs."  But that's not what 
XMLspec did at all, partly because it gets into modeling and we wanted to 
draw the line as early as possible.

Here, in fact, is how the "markupLine" non-terminal in XML is marked up in 
real XMLspec:

<prod id="NT-markupdecl">
<lhs>markupdecl</lhs>
<rhs><nt def="NT-elementdecl">elementdecl</nt> | <nt
def="NT-AttlistDecl">AttlistDecl</nt> | <nt def="NT-EntityDecl">EntityDecl</nt>
| <nt def="NT-NotationDecl">NotationDecl</nt> | <nt def="NT-PI">PI</nt> | <nt
def="NT-Comment">Comment</nt>
</rhs><vc def="vc-PEinMarkupDecl"/><wfc def="wfc-PEinInternalSubset"/>
</prod>

>| >How does lineannotation in this context map to XMLSpec?
>|
>| It's the same as the com (comment) element.
>
>Ok. And that has the same formatting expectations as constraint, but
>isn't a constraint and probably isn't linked. Yes?

No, not exactly.  An example of a comment is in the Char production 
(http://www.w3.org/TR/REC-xml#charsets).  It's the stuff between /* and 
*/.  The way a constraint element works, at least in XMLspec, is way different:

- It's empty, and it links to a constraintnote element.
- At the point where it appears in the production, you output [Constraint: 
constraint-note-title-goes-here], and make this link to the constraintnote.

>| >   <!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.
>
>Do we really need a constraintnote? Seems to me we could leave
>the processing of the notes up to the author (sections, list
>items, what have you).

Aha, I see we talked past each other because you were assuming that the 
constraint element had content, when really it's just a sort of footnote 
that draws you to the constraint note text.  We could allow it to link to 
anything titled, I suppose.

>What should we do about the linking semantics? I'd sortof like
>to make the linking attribute on nonterminal an XPointer...so it
>could be internal or external. If not, I guess we need both a
>linkend and a url attribute.

Now that XLink and XPointer are getting close to cooked, it would be ideal 
to have just a single nonterminal element that allows you point both inside 
and outside.  (XMLspec will do that eventually too.)  But that probably 
wants to be dictated by whatever else DocBook is doing in the linking space.

>| 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).
>
>Um, you weren't planning to make bnf linespecific were you? And what
>did you think of my suggestion that it should be in an rhs?

Yep, my proposal did have %linespecific.attrib; on bnf...  But I don't 
actually know of any cases where bnf is used in XML-related W3C specs 
(though it may be), and it's just a nice-to-have anyway.  You can always 
shove a lot of stuff into the regular production markup, and the essence of 
a production is that it has to have a left-hand side and a right-hand side, 
so you're not gaining much flexibility with it.

Okay, I can't stand it anymore. :-)  I'm going to whip up a fresh proposal 
with examples by this afternoon, so we're all on the same page...

         Eve

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