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>
§ion1;
§ion2;
§ion3;
</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>
§ion3_a;
§ion3_b;
§ion3_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?
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
And the other document file:
TIP: You can even move the entities all together out of your documents, see the answer I wrote on this question 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.
A chapter file (put in the directory
changes), as which is included by the previous document. Ifxi:includeis used as above, it will stop rendering, if thehrefattribute can not be solved.Here the
xi:includeis used with a fallback, so if thehrefattribute of thexi:includecould 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 thehrefand FIXME section!Be careful with referencing back to the entities file
../entities.entThis again can give nasty errors when it can not be resolved.