Re: DOCBOOK: newbie: partitioning docbook documents

[Henrik Motakef <henrik dot motakef at web dot de>]

Robert Krüger <krueger@signal7.de> writes:

> could someone point me to a tutorial or the part in the documentation that 
> explains how to partition a document into many files? At the moment I would 
> like to do two things:
> 
> - put each section of an article into a separate file
> - and put code examples that I use as programlistings in a separate file

External entities are not easily usable with non-XML data like
programlistings. You might want to look into XInclude, a W3C spec for
such things.

You will need a special XInclude processor for this, however -
inclusions are not processed automagically by the parser, as with
external entities. IIRC, both libxslt (and its command-line processor
xsltproc) and 4xslt from the Python 4Suite package can resolve
XIncludes before XSLT-processing.

Another possible drawback: I think that you can only include complete
XML documents, not "well-balanced" fragments, i.e. they have to have
one single root element.

> could anyone give me a working example for the two things I describe 
> above.

--- book.xml:

<?xml version="1.0"?>
<book xmlns:xi="http://www.w3.org/2001/XInclude";>
  <bookinfo><!-- ... --></bookinfo>
  <xi:include href="section1.xml"/>
</book>

--- section1.xml:

<section xmlns:xi="http://www.w3.org/2001/XInclude";>
  <title>Section 1</title>
  <programlisting>
    <xi:include href="hello.c" parse="text"/>
  </programlisting>
</section>

--- hello.c:

#include <stdio.h>

int main(int argc, char **argv)
{
    printf("Hello, World!\n");
    return 0;
}

If you run book.xml through an XInclude-Processor (which, as stated
above, some XSLT processors can do for you), the following output
results:

$ xmllint --xinclude book.xml
<?xml version="1.0"?>
<book xmlns:xi="http://www.w3.org/2001/XInclude";>
  <bookinfo><!-- ... --></bookinfo>
  <section xmlns:xi="http://www.w3.org/2001/XInclude";>
  <title>Section 1</title>
  <programlisting>
    #include &lt;stdio.h&gt;

int main(int argc, char **argv)
{
    printf(&quot;Hello, World!\n&quot;);
    return 0;
}

  </programlisting>
</section>
</book>

xmllint is included with the libxml library, see
<http://xmlsoft.org>. 

There is a tutorial on XInclude at XML.com:
<http://www.xml.com/pub/a/2002/07/31/xinclude.html>

The W3C spec is at <http://www.w3.org/TR/xinclude/>

hth
Henrik