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 #2 for BNF/EBNF markup


/ "Eve L. Maler" <Eve.Maler@east.sun.com> was heard to say:
| Here is round 2 of my BNF proposal.  Changes:
| - Added constraint and constraintnote elements

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.

| - I kept the names lhs and rhs because they are so common in CoSci

Yep.

| - I kept the name nt because otherwise it really clogs up the code

Hmm. Mumble. Maybe.

| - I kept constraint as an empty element

That's OK, but see my issue below.

| - You really only want to put lineannotations at the ends of lines, but 
| because it's a mixed content model, the DTD can't control the combination 
| of sbr's, lineannotations, and line breaks inserted unilaterally by the 
| formatter.

Caveat author, I guess.

| - Note that rhs is not line-specific.  The sbr element just forces a break, 
| but it's entirely possible that the rhs content will also be flowed onto 
| several lines just because the column in which it needs to appear has 
| limited room.

I think that's reasonable. I'm a little uncomfortable with sbr,
but I guess these are really just presentational linebreaks.

| - I don't think we can make the nt element empty and then generate its 
| content (the nonterminal's name ) reliably, so we have to do a bit of 
| "duplication" (and take the risk of error) and have authors supply the 
| content inside the element.

Yep. It can be a processing expectation that *if* it's empty,
the stylesheet is expected to generate the name, but if it's not
empty, the content should be used.

New issues:

 - I changed the linking attribute from 'def' to 'linkend' for consistency
 - You give productionset a required title, then didn't use the title in
   your examples. So I made the title optional.
 - 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)

| 			*		*		*
| 
| <!-- add productionset to %formal.class; -->

There were some typos in your decls; here's a proper
customization layer:

<!ENTITY % local.tech.char.class "|nt">
<!ENTITY % local.formal.class "|productionset">
<!ENTITY % docbook PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
                   "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd">
%docbook;

<!-- add productionset to %formal.class; -->
<!ELEMENT productionset
	((%formalobject.title.content;)?, (production|productionrecap)+)>
<!ATTLIST productionset %common.attrib;>

<!ELEMENT production (lhs, rhs, constraint*)>
<!ATTLIST production
	%idreq.common.attrib;
>

<!ELEMENT lhs (#PCDATA)>
<!ATTLIST lhs %common.attrib;>

<!ELEMENT rhs (#PCDATA|nt|lineannotation|sbr)*>
<!ATTLIST rhs %common.attrib;>

<!-- add nt to %tech.char.class; -->
<!ENTITY % required-XLink-to-production-ID "linkend IDREF #REQUIRED">
<!ELEMENT nt (#PCDATA)>
<!ATTLIST nt
	%common.attrib;
	%required-XLink-to-production-ID;
>

<!ELEMENT constraint EMPTY>
<!ENTITY % required-XLink-to-constraint-ID "linkend IDREF #REQUIRED">
<!ATTLIST constraint
	%common.attrib;
	%required-XLink-to-constraint-ID;
>

<!ELEMENT productionrecap EMPTY>
<!ATTLIST productionrecap
	%common.attrib;
	%required-XLink-to-production-ID;
>

| 			*		*		*
| 
| Examples based on the XML specification, but using this proposal; see 
| http://www.w3.org/TR/REC-xml for how they're supposed to be presented:

The examples, patched to validate against the DTD:

<!DOCTYPE book SYSTEM "ebnf.dtd" [
]>
<book>
<title>Book Title</title>
<chapter><title>Chapter Title</title>
<para>Content.</para>

<productionset>
<production id="NT-Char">
<lhs>Char</lhs>
<rhs>#x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD]
<!-- The above line break in the source file has nothing to do with the
line breaks in the output. -->
| [#x10000-#x10FFFF]
<lineannotation>any Unicode character, excluding the surrogate
blocks, FFFE, and FFFF.
</lineannotation>
</rhs>
</production>
</productionset>

<productionset>
<production id="NT-SDDecl">
<lhs>SDDecl</lhs>
<rhs><nt linkend="NT-S">S</nt> 'standalone' <nt linkend="NT-Eq">Eq</nt>
<!-- The above line break in the source file has nothing to do with the
line breaks in the output. -->
(("'" ('yes' | 'no') "'") | ('"' ('yes' | 'no') '"'))
</rhs>
<constraint linkend="check-rmd"/>
</production>
</productionset>

<productionset>
<production id="NT-element">
<lhs>element</lhs>
<rhs>
<nt linkend="NT-EmptyElemTag">EmptyElemTag</nt>
<sbr/><!-- There will be a line break in the output because of the sbr. -->
| <nt linkend="NT-STag">STag</nt> <nt linkend="NT-content">content</nt>
<!-- The above line break has nothing to do with the output. -->
<nt linkend="NT-ETag">ETag</nt>
</rhs>
<constraint linkend="GIMatch"/>
<constraint linkend="elementvalid"/>
</production>
</productionset>

<para>A bunch of anchors to make the preceding examples valid:
<anchor id="NT-S"/>
<anchor id="NT-Eq"/>
<anchor id="NT-content"/>
<anchor id="check-rmd"/>
<anchor id="NT-ETag"/>
<anchor id="elementvalid"/>
<anchor id="GIMatch"/>
<anchor id="NT-EmptyElemTag"/>
<anchor id="NT-STag"/>
</para>

</chapter>
</book>

I'm pretty pleased with this. I'll see what I can do stylesheet wise.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | The shoe that fits one person
http://www.oasis-open.org/docbook/ | pinches another; there is no
Chair, DocBook Technical Committee | recipe for living that suits all
                                   | cases.--Jung



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


Powered by eList eXpress LLC