Re: DOCBOOK: Proposal #2 for BNF/EBNF markup

[Norman Walsh <ndw at nwalsh dot com>]

/ "Eve L. Maler" <Eve.Maler@east.sun.com> was heard to say:
| At 12:53 PM 4/5/00 -0400, Norman Walsh wrote:
| >I don't think we need a constraintnote element. How the author
| >chooses to indicate constraints should be up to them. For
| >example, I think formalparas might work just fine in some
| >cases. I particularly don't think that constraintnote should be
| >an admonition.
| 
| Fair enough, I guess.  It does have to be something with a guaranteed 
| title, though, since the processing expectation is to pick it up and 
| display it in the production.  For DocBook purposes, I guess it doesn't 
| make sense to force people to encode their constraint text in a consistent 
| way (if we're not willing to make a constraintnote element), but in a real 
| authoring environment, I'd want to enforce picking one way to do 
| it.  Constraints are important normative info; you can't be sloppy about them.

Toying with the stylesheets :-), I'm convinced that you're
right.  How about 'constraintdef' instead of 'constraintnote'
(I'm thinking this is more like a definition (a la glossdef)
than a note).

| >New issues:
| >
| >  - I changed the linking attribute from 'def' to 'linkend' for consistency
| 
| Oops, yeah.

Except that they aren't IDREFs. So maybe 'def' is better, but

 - You suggested that constraint should be empty, but that it
   might point to an external resource by xpointer. Um, I have
   qualms about that. I think we should either make it an IDREF
   or allow it to have content. I don't think we can reasonably
   expect stylesheets to reach over the web and grab stuff,
   especially since most of the stuff they could grab would be
   in different DTDs or even HTML.

I'm starting to think the semantic for 'nt' and 'constraint'
should be that the generate content if empty (in which case they
must have an IDREF (expressed as an xpointer)) or they can
contain content. [Can you say #CONREF? :-)]

| >  - You give productionset a required title, then didn't use the title in
| >    your examples. So I made the title optional.
| 
| Sorry -- I was giving examples of individual productions, not groups of 
| productions in a set.  In the original XML spec, you'll notice that each of 
| the productions for which I gave examples is part of a set, which is 
| named.  But I can agree with not requiring the title; e.g., to my 
| knowledge, it's never used in any TOCs or anything.

I don't feel strongly about this one. But I don't want to have
to add informalproductionset in the future :-), so we might as
well make it optional now, I guess.

| >  - Making constraint empty requires that the stylesheet be able to generate
| >    something reasonable. Maybe we should allow it to have content or be
| >    empty, as per my description of NT above (and not without precedent,
| >    consider the semantics of 'link' with endterm)
| 
| As I noted above, you could just require that it point to something with a 
| title, so the title can be grabbed and displayed.  Alternatively, we could 
| mandate that the constraint text be stuffed into the constraint element 
| inside the production, but I'm not crazy about it.  I don't want to allow a 
| title inside the constraint element, because that opens up the possibility 
| that a constraint that applies n different productions (which happens 
| sometimes) will be assigned different titles.

I don't want the constraint text in the 'constraint' element,
just the text that should be "hot" in the link to the
constraint.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | To the man who is afraid
http://www.oasis-open.org/docbook/ | everything rustles.--Sophocles
Chair, DocBook Technical Committee |