OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Subject: Re: DOCBOOK: Proposal for BNF/EBNF markup


/ "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 |



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Powered by eList eXpress LLC