Adding to DocBook DTD

[paul.boparai]

Hi,

I have an element that I would like to add to the docbook DTD. This
element is a wrapper element that I would like to wrap all of the
standard docbook elements. This element is called "changebar". So
for example I would like changebar to appear like:

<changebar>
<chapter>
.........
</chapter>
</changebar>

<changebar>
<orderedlist>
.........
</orderedlist>
</changebar>

<changebar>
<para>
.........
</para>
</changebar>

Does anyone know how I can do that in the docbook DTD?

Thanks

 

[Joseph Kesselman]

STRONG suggestion that a much easier thing to do would be to add a
changed="yes" attribute to elements you want to mark this way. That can
be done without altering the DTD, since additional attributes are
treated as annotations and ignored by DTD validation. And in fact that's
the right approach in any case; change flags *ARE* annotations rather
than being part of the document's semantics, and really should be
handled as attributes rather than as element structure even if they were
going to become an official part of DocBook.

To make it really useful, I woudl suggest taking it a step further to
changeversion="3.2" or changedate="20070524" -- so a processor can
report what has changed since a particular point in time, or render
nested changebars (which is something IBM's SCRIPT/DCF system was able
to do, though it was working on SGML markup rather than XML).

 

[paul.boparai]

Thank you for your reply.

Our team had went over the idea of using a changebar attribute. But
the reason we decided to use an element is because we would like to
conditionalize the changebar according to the different countries our
manuals will be sent out to. So in the end it was decided a changebar
element with country attributes are the way to go. There are other
reasons as well and also it would be nice to know how to add elements
to every level of a document. Any suggestions?

Thanks

 

[Joseph Kesselman]

conditionalize the changebar according to the different countries our

manuals will be sent out to. So in the end it was decided a changebar
element with country attributes are the way to go.

Could be done with a changebar attribute having country flags in its values.

also it would be nice to know how to add elements
to every level of a document.

Can't be done without major changes to the DTD unless the DTD already
provides a mechanism for it using Parameter Entities or something of
that sort. And even if the hooks are there, doing this risks losing the
ability to exchange these documents with other users/tools working in
Docbook unless they too are prepared to accept unexpected elements and
make some assumptions about exactly how to attempt to work past them.

Ignoring additional attributes really is a lot easier than ignoring
additional structure.

So my suggestion is "It's going to hurt when you do that." If you don't
like that suggestion, all I can suggest is digging into the DocBook DTDs
to see whether they do have the hooks for this, or if you're going to
have to patch them to death to make this work... and digging into all
your tools to see whether they'll support it or will blow up in your face.

 

[Joseph Kesselman]

The other solution would be to create Processing Instructions for
start-change-bar and end-change-bar. (Or, for somewhat less chaos,
start-change-bar-on-next-element). Structurally ugly, but PIs are not
validated; they're directives/hints to specific applications and apps
which don't care about them are supposed to ignore them.

By the way, this question of "how do I extend a language" is precisely
why namespaces and schemas were introduced. If you're really going to
need this capability, I'd suggest dumping DTDs and moving over.

 

[Richard Tobin]

STRONG suggestion that a much easier thing to do would be to add a
changed="yes" attribute to elements you want to mark this way. That can
be done without altering the DTD, since additional attributes are
treated as annotations and ignored by DTD validation.

I'm baffled by this comment. All attributes must be declared for DTD
validity.

-- Richard

 

[paul.boparai]

Thanks again for your replies. I know attributes and processing
instructions will make things easier. And switcing away from DTDs
would be great too, but we really can't do that with the system we are
using. We are so deep within it it would mean changing 200 manuals of
Docbook DTD related content.

Anyways, I know how to get it so that changbar elements can wrap a
para. These two lines of code will do it:

<!ENTITY % local.indexdivcomponent.mix "|changebar">
<!ENTITY % local.list.class "|changebar">

But in terms of wrapping chapters, sections, lists, etc, I am still
having no luck. Any further sugggestions?

 

[Joe Kesselman]

I'm baffled by this comment. All attributes must be declared for DTD
validity.

Darn. You're right; I slipped a gear somehow. Either I was thinking of
one of the "lazy" partial evaluation modes some parsers offer, or I was
confusing it with something else...

 

[Joe Kesselman]

Anyways, I know how to get it so that changbar elements can wrap a
para. These two lines of code will do it:

<!ENTITY % local.indexdivcomponent.mix "|changebar">
<!ENTITY % local.list.class "|changebar">

But in terms of wrapping chapters, sections, lists, etc, I am still
having no luck. Any further sugggestions?

Unless there's a similar entity defining a list of children which you
can add changebar to, no suggestions. I'm afraid I'm not willing to
grovel through the DocBook DTD to try to resolve this for you, not on a
volunteer basis anyway.

Note too that unless changebar itself limits its contents, you risk
opening up the DTD much more than just adding the wrapper. Which is
another reason I think you're heading down a blind alley with this
solution. But de gustibus...

 

[Magnus Henriksson]

Hi,

I have an element that I would like to add to the docbook DTD. This
element is a wrapper element that I would like to wrap all of the
standard docbook elements. This element is called "changebar". So
for example I would like changebar to appear like:

<changebar>
<chapter>
.........
</chapter>
</changebar>

<changebar>
<orderedlist>
.........
</orderedlist>
</changebar>

<changebar>
<para>
.........
</para>
</changebar>

Does anyone know how I can do that in the docbook DTD?

Thanks

What would the content model of the changebar element look like? And
what would the content model of all other elements look like?

Introducing an element that can be used anywhere and contain anything
makes validation rather pointless. Much better to use attributes or PIs,
like others have suggested.

// Magnus

 

[David Carlisle]

Hi,

I have an element that I would like to add to the docbook DTD. This
element is a wrapper element that I would like to wrap all of the
standard docbook elements. This element is called "changebar". So
for example I would like changebar to appear like:

<changebar>
<chapter>
.........
</chapter>
</changebar>

<changebar>
<orderedlist>
.........
</orderedlist>
</changebar>

<changebar>
<para>
.........
</para>
</changebar>

Does anyone know how I can do that in the docbook DTD?

Thanks

You could do that,
just declare changebar to have content model ANY (so it allows any
docbook elements as children) then add it to the parameter entities that
control the content model of every element in which you want to allow
changebar.

But it's really not worth doing this, the resulting dtd would
essentially allow any element everywhere: you want a book to be inside a
para? no problem. just wrap it in changebar!
<para>
<changebar>
<book>

would be dtd valid.

what you want to say is that a changebar-in-para has the content model
of book, but you can't say that in a DTD, you need a more expressive
language such as xsd, relaxng or schematron, or just demand dtd validity
_after_ removing changebar elements.

does your docbook processing really need dtd-valid input? Certainly the
XSLT stysheets don't require this, so you could just allow <changebar>
and make suitable changes to the xsl to handle this element without
changing the dtd at all.

Davd

 

[Peter Flynn]

Thank you for your reply.

Our team had went over the idea of using a changebar attribute. But
the reason we decided to use an element is because we would like to
conditionalize the changebar according to the different countries our
manuals will be sent out to.

But DocBook already provides for this kind of conditionalism as well
(it's called an effectivity). If you need a more-than-one-value
attribute with validation, add an ENTITIES type (see the example at
http://www.thescripts.com/forum/thread87060.html).

Trying to do this with a container element will end in tears.

So in the end it was decided a changebar element with country
attributes are the way to go. There are other reasons as well and
also it would be nice to know how to add elements to every level of a
document. Any suggestions?

Don't.

It *is* possible (read Eve Maler and Jeanne El Andaloussi's book on
DTDs, and the chapter on modifying DTDs in my book on SGML and XML
Tools) and then make yourself completely familiar with the parameterized
construction of the DocBook DTD.

I very, very strongly recommend that you do not do this. DocBook already
provides a simple way of adding attributes for this kind of control, and
I think you will find it much more effective to use than trying to
re-constrain every content model in the DTD.

///Peter