Can ENTITY declarations be nested in referenced XML files?

Question

I'm working on a rather large DocBook XML document. The main book has the chapters but includes all the subsections by reference using entities. Something like this:

main.book.xml:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
[
<!ENTITY section1 SYSTEM "../fragments/section1.xml">
<!ENTITY section2 SYSTEM "../fragments/section2.xml">
<!ENTITY section3 SYSTEM "../fragments/section3.xml">
<!ENTITY section3_a SYSTEM "../fragments/section3_a.xml">
<!ENTITY section3_b SYSTEM "../fragments/section3_b.xml">
<!ENTITY section3_c SYSTEM "../fragments/section3_c.xml">
]>

<book>
    <chapter>
        <title>Chapter 1</title>
        &section1;
        &section2;
        &section3;
    </chapter>
</book>

Section 3 is in turn divided into three more xml files whose content is included by reference like so:

section3.xml:

<?xml version="1.0" encoding="UTF-8"?>
<section id="Section3">
    <title>Section 3</title>
    &section3_a;
    &section3_b;
    &section3_c;
</section>

QUESTION: Is there a way to move the ENTITY declarations used only by Section 3 (i.e. section3_a, section3_b, etc) to section3.xml instead of declaring them in main.book.xml?

Answer 1

Yes, this is possible, just add them to the document, you are using them. But I strongly discourage the use of entities, for including other document (parts)! As soon or later you will run in the difficulty, that one (or more) of the document (parts) are not available. Your document will not render and searching for the issue causing it is rather nasty. A far better solution is to use XInclude, for inclusion of documents.

Solution with ENTITY entries

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" 
    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
[
    <!ENTITY section1 SYSTEM "../fragments/section1.xml">
    <!ENTITY section2 SYSTEM "../fragments/section2.xml">
    <!ENTITY section3 SYSTEM "../fragments/section3.xml">
]>

<book>
    <chapter>
        <title>Chapter 1</title>
        &section1;
        &section2;
        &section3;
    </chapter>
</book>

And the other document file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
[
    <!ENTITY section3_a SYSTEM "../fragments/section3_a.xml">
    <!ENTITY section3_b SYSTEM "../fragments/section3_b.xml">
    <!ENTITY section3_c SYSTEM "../fragments/section3_c.xml">
]>
<section id="Section3">
    <title>Section 3</title>
    &section3_a;
    &section3_b;
    &section3_c;
</section>

TIP: You can even move the entities all together out of your documents, see the answer I wrote on this question http://stackoverflow.com/questions/2600827/docbook-macros

Solution with XInclude

Here then an example of how to set up documents with XInclude. Entity entries are used for small strings. And using XInclude, for file inclusion.

<?xml version='1.0' encoding='UTF-8'?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" 
    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
    <!ENTITY maven.project.version "(not set)">
    <!ENTITY % entities SYSTEM "entities.ent" >

    %entities;

]>

<book>
    <title>&product.name;</title>
    <subtitle>Release Notes</subtitle>
    <bookinfo>
        <date>&product.release.date;</date>
        <releaseinfo><?eval ${project.version}?></releaseinfo>
    </bookinfo>

    <!-- Include chapters -->
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="changes/chapter-release-2.0.xml" />
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="changes/chapter-release-2.1.xml" />
</book>

A chapter file (put in the directory changes), as which is included by the previous document. If xi:include is used as above, it will stop rendering, if the href attribute can not be solved.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" 
    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
    <!ENTITY  section-changes        "section-changes-v2.0.xml">
    <!ENTITY %  entities     SYSTEM  "../entities.ent">

    %entities;

]>

<chapter  id="release-2.0">
    <title>Release 2.0</title>
    <para>
        Information given in this chapter applies for <emphasis>&product.name; v2.0</emphasis>.
    </para>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="&section-changes;">
        <xi:fallback><para>FIXME File not found: "&section-changes;"</para></xi:fallback>
    </xi:include>

</chapter>

Here the xi:include is used with a fallback, so if the href attribute of the xi:include could not be solved, the fallback is rendered into the document (This will show a paragraph with FIXME in it. Here using actually an entity, for referencing the document (location). This is great as that reference can then be used in the href and FIXME section!

Be careful with referencing back to the entities file ../entities.ent This again can give nasty errors when it can not be resolved.