The best way to handle big documentation is to break it into multiple files. Docbook allows you to do that by using XInclude. Here is how it is done.
<?xml version="1.0" encoding="UTF-8"?> <!-- Here is the master file called book.xml --> <!-- Note the word 'book' after DOCTYPE below.--> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <book> <title>My Docbook Title</title> <!-- Include intro chapter from external file, intro.xml --> <xi:include href="intro.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </book>
<?xml version="1.0" encoding="UTF-8"?> <!-- Here is the intro.xml file to be include inside book.xml --> <!-- Note the word 'chapter' after DOCTYPE below.--> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <chapter id="intro"> <title>Intro</title> <para>Imported chapter.</para> </chapter>
To validate the files, you can use xmllint --noout --xinclude --postvalid --noent book.xml.
To create the PDF for your whole document, run
xsltproc --xinclude /path/to/your/docbook-xsl/fo/docbook.xsl book.xml > book.fo fop -fo book.fo -pdf book.pdf
For more details, see http://www.sagehill.net/docbookxsl/ModularDoc.html.
About the author
Xuan Ngo is the founder of OpenWritings.net. He currently lives in Montreal, Canada. He loves to write about programming and open source subjects.