Request for Help

[venta]

Does anyone have any experience of using DocBook ? I'm having a bit of a nightmare with it, and am fast coming to the conclusion that the thing I want to do can't easily be done.

I'm writing a series of pages, which will be (eventually) grouped loosely together. I've written each as an <article> - which means that, by default, the DocBook XSLT transform generates a table of contents for each page.

To get round this, I've been adding a lt;suppresstoc> element, which my XSL style sheet does this with:

<xsl:template match="suppresstoc">
<xsl:param name="generate.toc">
article nop
</xsl:param>
<xsl:apply-templates />
</xsl:template>

(I'm happy to believe this is quite The Wrong Thing, suggestions welcome.)

This works, so long as you don't do anything dangerous like trying to validate your XML. If you do, it complains quite reasonably that it doesn't know anything about this <suppresstoc> element.

I've tried adding the element in this manner:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[
<!ELEMENT suppresstoc (sect1)>
]<

But xmllint is having none of it... because the DocBook DTD maintains that the article document goes:

<article>
<articleinfo>
...
</articleinfo>
<sect1>

... with no content before the sect1, except for the articleinfo. I can't find anywhere to put the suppresstoc tag such that it doesn't violate the DocBook DTD.

So... I'm keen not to modify the DTD because (a) what I know about DTDs/XML/xslt fits conveniently on a very small stamp and (b) it's just easier to refer to the standard one, and saves us maintenance bother. Is there anyway I can define an element which does what I want in a conformant way ?

Even better, is there a standard way of suppressing the ToC which would avoid all this bother in the first place ?

Comments

[venta.livejournal.com]

In case anyone's genuinely interested...

I can write two different XSL stylesheets, one which suppresses the ToC and one which doesnt and (with a bit of syntax help from hjalfi) can cause the makefile which does the xsltproc to run files through the appropriate one.

I don't like this as a solution, but it's the best I've come up with so far.

[ewx.livejournal.com]

I'm not very up on XML but I wondered if namespaces were an answer?

[venta.livejournal.com]

Yes, someone here suggested namespaces. I wasn't sure where to put them or what to do with them, though :(

I'm finding it hard to find an "in" to this tangle, as everything seems terribly self-referential. There is a DTD which specifies XML... it's written in XML, etc.

[ewx.livejournal.com]

AIUI (and I am bluffing here, probably fairly obviously) by putting your new element in a separate namespace you basically make it invisible to DocBook-specific tools but leave it visible to anything that is (or you choose to make) aware of your new namespace. I assume on no information whatsoever that there's some way to make XSLT recognizes elements from more than one namespace.

Looking at the DTD I see that the definition of article is indirected in a way that I can't quite follow, but Customizing DocBook or something similar might point you in the right direction for using that to override it.

[venta.livejournal.com]

I had read the Customising DocBook page, but failed to abstract anything useful from it. Or at least, anything more useful than a suspicion that those methods require me to modify the DTD.

My understanding of namespaces matches yours but sadly I only have a conceptual understanding, not an actual what-do-I-type-where understanding :)

[leathellin.livejournal.com]

Oh dear. You could email me and I can have a look if you want. Or you may want to carry on as you are (I would have to pretend I knew nothing about this post then obviously :-)

[venta.livejournal.com]

What should I email you, boss ?

I think my current system is probably the least dangerous approach, but I'm curious to know more about the whole business. Maybe I should just corner you for an hour when you're back for Christmas :)