Re: DOCBOOK-APPS: Question about Sets in DocBook

[Bob Stayton <bobs@caldera.com>]

On Tue, Jan 15, 2002 at 01:42:59PM +0100, Anita Ross (EED) wrote:
> I am a new user to DobBook. I am writing 6 related but
> separate technical documents that will be rendered as HTML
> and pdf. Each book will contain  5 to 10 chapters. In the
> DocBook Help (Section 2.4), it explains that the docs can
> be put in physical chunks by creating separate "books" and
> putting those books into a "set". However, when I do that,
> my XML Spy editor will not validate the book because there
> is no book tag at the beginning or end of the file.
> 
> So, is set then the best way for creating physical chunks
> for what will be rendered as HTML files for the online Help
> that I am creating?

Perhaps not.  If, as you say, the technical documents
are separate, then they can be authored and processed
as separate book documents.  In such a case, each document
would start with:

<?xml version="1.0?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd">
<book>
...

You would need to put the collection of books into a set
if you wanted to form cross references between the
books using <link> or <xref>.  Those elements use the ID/IDREF
mechanism, which requires that the reference and the
target be in the same document. The set becomes that
document, of which the books are a part.

The downside is that you have to convert your
valid book document files into book system entity files.
Then you can declare a collection of system entities and refer
to them in the set document, as described in Norm's book.

But the system entity form must not have a <!DOCTYPE>
declaration element at the top.  Unfortunately,
without the <!DOCTYPE>, most XML editors will not treat
the file as a valid file, because it specifies no DTD to
validate against.  I've always found this to be an odd
limitation of the XML spec that was carried over
from the SGML spec.  Why can't the processor simply
ignore any <!DOCTYPE> declaration in system entities?

Anyway, some people get around this problem by using an
editor that "fakes" a DOCTYPE declaration, usually acting
on an embedded comment or processing instruction in the
file.  Others create a wrapper file for each book, which is
essentially a 'set' document that contains just one book
entity reference, to be used for validation purposes only.

Using modular XML files is not as easy as it should be.
If you don't need cross references between your books,
just keep them as separate book documents.


Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
Caldera International, Inc.                 fax:   (831) 429-1887
                                            email: bobs@caldera.com