21.8. Linking documents together

DocBook provides a modular framework where many separate documents can be linked together into a master document. Fragments from different documents can also be reused in different contexts. It is therefore important to consider whether your document should be constructed as an article or a chapter. Chapters are essentially portions of a book, and can therefore be linked together into a larger document very easily. Articles are essentially standalone documents, but they can also be assembled together into a larger document at the component level.

Should you wish to link several articles together into a book, DocBook provides a mechanism to assign an id to a section. In the example below, a section has been assigned an id. This id must be unique within the document.

  <section xml:id="mod2_1">
<title>Getting started with DHIS2</title> ....

In order to include an article into a book, an Xinclude statement must be used. The following example shows how.

<chapter>
<title>Getting started with DHIS2</title> 
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhis2_user_man_mod2.xml"
 xpointer="mod2_1" encoding="UTF-8"/>
... 

Note that the file name and id have been assigned in the parent document, referring to the actual file (href) and particular fragment of the child document that should be referenced in the parent document (xpointer).

Including chapters in a book is very simple. The example below illustrates how:

<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhis2_user_man_
mod1.xml" encoding="UTF-8"/> 

In this case, there is no need to explicitly reference a part of the document, unless you only want to include a portion of the chapter. If you want to use a section of the chapter, you can assign an id to that section, and then reference that section through an xpointer.