«

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" >
<!ENTITY ch2 SYSTEM "userguide.ch2.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" >
<!ENTITY reference SYSTEM "reference.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.

In article <> ,
Ed Dennison <> wrote:

><!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" >
> <!ENTITY ch2 SYSTEM "userguide.ch2.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
--
Spam filter: to mail me from a .com/.net site, put my surname in the headers.

FreeBSD rules!

"Ed Dennison" <> wrote in message
news: m...


--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