Nested <!ENTITY> Tags?

[Ed Dennison]

I'm starting to look at DocBook-XML (not SGML) for producing a large
documentation set. The hierarchy of DocBook elements for organizing
the content is (more or less);

set
book
part
chapter
sect1
sect2
....

Most of the examples and documentation for DocBook-XML describe using
<!ENTITY> tags within a DOCTYPE element to break up a book into
multiple chapter files, like this:

<!DOCTYPE book
PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
"file:///c:\home\db\dtd\docbookx.dtd"
[
<!ENTITY preface SYSTEM "userguide.preface.xml" >
<!ENTITY ch1 SYSTEM "userguide.ch1.xml" >

<book>
&preface;
&ch1;
&ch2;
</book>

This works fine. But suppose I would like to include my books within a
set. If I do something similar in a set container file:

<!DOCTYPE set
PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
"file:///c:\home\db\dtd\docbookx.dtd"
[
<!ENTITY userguide SYSTEM "userguide.book.xml" >

<set>
&userguide;
&reference;
</set>

This does not work fine -- attempting to parse the set file generates
errors because of multiple DOCTYPE elements in a single file (the
DOCTYPE elements in the included book XML files).

As far as I can tell, this means that if I want to use the set
element, each of my DocBook books must be implemented as a single XML
file. This is not practical for large books (such as N. Walsh's
example of an aircraft maintenance manual).

I am interested in what kinds of approaches people take when using
DocBook-XML to work with large documentation sets? Do you eschew the
use of the set element? Use some kind of mechanical means to merge the
parts of a book before processing?

Thanks,

Ed Dennison
Cognex Corporation

e-mail ed at the obvious domain.

 

[Richard Tobin]

<!DOCTYPE book
PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
"file:///c:\home\db\dtd\docbookx.dtd"
[
<!ENTITY preface SYSTEM "userguide.preface.xml" >
<!ENTITY ch1 SYSTEM "userguide.ch1.xml" >

<book>
&preface;
&ch1;
&ch2;
</book>

First of all, note that you could have split out the chapter entity
definitions into an external parameter entity, and used another
external entity to package up all the chapters:

userguide-defs.pe:

<!ENTITY preface SYSTEM "userguide.preface.xml" >
<!ENTITY ch1 SYSTEM "userguide.ch1.xml" >
<!ENTITY ch2 SYSTEM "userguide.ch2.xml" >
<!ENTITY userguide-chapters SYSTEM "userguide-chapters.xml">

userguide-chapters.xml:

&preface;
&ch1;
&ch2;

userguide.xml:

<!DOCTYPE book
PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
"file:///c:\home\db\dtd\docbookx.dtd"
[
<!ENTITY % userguide-defs SYSTEM "userguide-defs.pe" >
%userguide-defs;
]<book>
&userguide-chapters;
</book>

Then you could do this:

<!DOCTYPE set
PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
"file:///c:\home\db\dtd\docbookx.dtd"
[
<!ENTITY % userguide-defs SYSTEM "userguide-defs.pe" >
%userguide-defs;
<!ENTITY % reference-defs SYSTEM "reference-defs.pe" >
%reference-defs;
]
<set>
<book>
&userguide-chapters;
</book>
<book>
&reference-chapters;
</book>
</set>

Still rather more overhead than is desirable, but maybe good enough.

(NB you will have to choose different entity names for the chapters
in each book.)

-- Richard

 

[Magnus Henriksson]

--snip--

I am interested in what kinds of approaches people take when using
DocBook-XML to work with large documentation sets? Do you eschew the
use of the set element? Use some kind of mechanical means to merge the
parts of a book before processing?

--snip--

Chapter 19 [http://www.sagehill.net/docbookxsl/ModularDoc.html] in 'DocBook
XSL: The Complete Guide' [http://www.sagehill.net/docbookxsl/] has some
pretty good advice for working with modular DocBook files. Assuming you are
processing your sources with N. Walsh's styulesheets.


// Magnus