RSS Feed
Download our iPhone app
Browse DevX
Sign up for e-mail newsletters from DevX


DocBook: Write Once, Read Anywhere Documentation : Page 3

DocBook enables developers to create technical documentation in XML. Learn how to use it to transform its XML output to PDF and HTML automatically and integrate it into your development environment.

Splitting Your Book
For a large document, putting it all in one XML file can quickly become unmanageable—especially if it is being edited by multiple people. One way to overcome this is to break up your document into smaller files, each dedicated to a chapter or a group of logically related chapters. This way, multiple people can edit different parts of the document without affecting any other parts. And you know when you've made a mistake because the DocBook build will fail.

You also can factor common chapters out into separate files so that they can be reused in different books. For example, you may want to include the standard product copyright section at the top of your training manual as well as in your installation guide. Each document is a separate book, but they contain some common content. DocBook files can be included in other DocBook files using <xi:include>. For example, to structure your sample document into a book file and two chapter files, change the main file simple.xml to this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
<book >
  <title>DocBook Framework Overview</title>

    <releaseinfo>V 1.0</releaseinfo>


  <xi:include href="intro.xml" xmlns:xi="http://www.w3.org/2003/XInclude" />
  <xi:include href="basics.xml" xmlns:xi="http://www.w3.org/2003/XInclude" />

And decompose each of the chapter elements into intro.xml:

<?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"> <chapter id="intro"> <title>Introduction</title> <para>DocBook is simple to use and provides a rich set of tags for common elements.</para> </chapter>

and basics.xml:

<?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"> <chapter id="basics"> <title>Basic Elements</title> <para>This section describes the basic tags.</para> </chapter>

Note that since each chapter resides in its own file, if you want to be able to edit it using an XML editor or plugin it must also reference the correct DTD. To enable the Velocity framework to handle multiple files per book, ensure that Saxon (the underlying XSLT engine used by Velocity) is configured to correctly resolve <xi:include> elements. Edit the build-docbook.xml file and modify the Saxon entry to enlist xerces to handle the <xi:include> elements:

<java classname="com.icl.saxon.StyleSheet" fork="true"
    dir="${basedir}" classpathref="dbf.classpath">
        <jvmarg value="-Djavax.xml.parsers.DocumentBuilderFactory=
/> <jvmarg value="-Djavax.xml.parsers.SAXParserFactory=
/> <jvmarg value="-Dorg.apache.xerces.xni.parser.XMLParserConfiguration=
/> <arg line="-x org.apache.xml.resolver.tools.ResolvingXMLReader"/> <arg line="-y org.apache.xml.resolver.tools.ResolvingXMLReader"/> <arg line="-r org.apache.xml.resolver.tools.CatalogResolver"/> <arg value="-o"/> <arg value="@{output}"/> <arg value="@{input}"/> <arg value="@{style}"/> </java>

Close Icon
Thanks for your registration, follow us on our social networks to keep up-to-date