Modular sections

You may find a need to further divide your content into smaller modules such as sections. For example, you might need to produce different versions of a document for beginning and advanced users. Each chapter might share the same title and introduction between versions, but the sections in each chapter may need to be different. This is easy to set up because an XInclude'd document can also be an XInclude'ing document. You can create a chapter module that contains the title and introductory material, and then a series of XIncludes for the section modules. Below is what one version of a chapter might look like. Another version of the chapter would use a different selection of XIncludes. Then you can create separate book documents that use XInclude to pull in the different chapter modules, as in the following example.

<chapter>
<title>Using a mouse</title>
<para>A mouse is an easy device to use ...</para>
<xi:include  href="rolling.section.xml"  
             xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include  href="leftclick.section.xml"  
             xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include  href="rightclick.section.xml"  
             xmlns:xi="http://www.w3.org/2001/XInclude" />
...
</chapter>

If you want to modularize the introductory material as well, then you need a slightly different XInclude. If you just put the title and introductory paragraphs in a separate file module, then the module would not validate because its content is not contained in a document element. But you can wrap the content in a placeholder chapter element, and then use the xpointer() syntax to select only its content, not the chapter element itself. The following example shows how it can be done:

<chapter>
<xi:include  href="chapintro.xml"
             xpointer="xpointer(/chapter/*)"  
             xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include  href="rolling.section.xml"  
             xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include  href="leftclick.section.xml"  
             xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include  href="rightclick.section.xml"  
             xmlns:xi="http://www.w3.org/2001/XInclude" />
...
</chapter>

The xpointer="xpointer(/chapter/*)" attribute is used to locate a selection within the chapintro.xml file. It will select all elements inside the intro chapter element, but not the chapter element itself. It would select the highlighted text in the following example.

<chapter>
<title>Using a mouse</title>
<para>A mouse is an easy device to use.</para>
<para>All computers seem to have one now.</para>
</chapter>

This enables you to validate the chapintro.xml file module, and still gives you a valid document when its content is included in the chapter itself.

If you decide to modularize your content down to the section level, then you should probably use section tags rather than sect1, sect2, etc. The section element can be included inside other section elements. That lets you assemble content in any arrangement of nesting that makes logical sense, without having to edit tags to get the element nesting right.

The trade off with using section is that you have to be strictly careful about where you place your section elements. Putting a sect1 element inside another sect1 will be flagged as in a validation error But you can put a section element inside another section element; in fact, that is the whole point of that element. Whether you include a section before or after the end tag of another section element changes its section level. The following is an example of using a section XInclude in two different locations:

<chapter>
  ...
  <section>              section level 1
    ...
    <xi:include  href="IDEdrives"  
                 xmlns:xi="http://www.w3.org/2001/XInclude" />  section level 2
  </section>
  <xi:include  href="IDEdrives"  
               xmlns:xi="http://www.w3.org/2001/XInclude" />  section level 1
</chapter>

Either location is valid, and the stylesheets will process either without error. It is up to the author to make sure their sections are nested according to the intended logic of the content.