doc/multifiles.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE chapter SYSTEM "../doc.dtd">
   3 <?xml-stylesheet type="text/css" href="xmldoc.css"?>
   4
   5 <!--
   6       XML documentation system
   7       Original author :  Arjen Baart - arjen@andromeda.nl
   8       Version         : $Revision: 1.3 $
   9 -->
  10
  11 <chapter>
  12 <heading>Using multiple files</heading>
  13 <para>
  14 The XMLDoc system allows you to use multiple files for both input
  15 and output.
  16 <emph>Well, not really. Multiple output files is not implemented yet :-)</emph>
  17 </para>
  18 <section>
  19 <heading><label name='include'/>Multiple input files</heading>
  20 <para>
  21 You do not need to create one single big XML file that contains
  22 all of your story.
  23 Especially when writing a large book or report, it is often convenient
  24 to origanize your document in multiple files.
  25 For example, one file for each chapter and a single 'root' document
  26 with all the header stuff, such as a title page and a table of
  27 contents which binds all chapters together.
  28 As a matter of fact, this XMLDoc guide is organized in such a way.
  29 </para>
  30 <para>
  31 To include another XML file in your root document, use the
  32 standard XML <strong>XInclude</strong> system with a single attribute to specify
  33 the name of the file to be included.
  34 Other attributes, as well as the <strong>fallback</strong> element,
  35 are of course supported as well.
  36 Refer to the <reference href='http://www.w3.org/TR/2006/REC-xinclude-20061115/'>
  37 XML Inclusions</reference> standard for more information.
  38 For example, this chapter is in a file called "multifiles.xml", which
  39 is included in the main document with:
  40 </para>
  41
  42 <verbatim>
  43 &lt;xi:include href="multifiles.xml"
  44     xmlns:xi="http://www.w3.org/2001/XInclude"/&gt;
  45 </verbatim>
  46
  47 <para>
  48 Remember to put the <strong>xi:include</strong> in the proper namespace.
  49 Normally, the included files must be valid XML files as well.
  50 To include other kinds of files, such as raw text or source code, the attribute
  51 <strong>parse='text'</strong> must be added to the <strong>include</strong> element.
  52 When including another XML document, the included XML file starts with the
  53 usual XML declaration, but has
  54 a different root element declared in the &lt;!DOCTYPE...&gt; declaration:
  55 </para>
  56
  57 <verbatim>
  58 &lt;?xml version="1.0"?&gt;
  59 &lt;!DOCTYPE chapter SYSTEM "../doc.dtd"&gt;
  60 &lt;chapter&gt;
  61 &lt;--  The content of this chapter --&gt;
  62 &lt;/chapter&gt;
  63 </verbatim>
  64
  65 </section>
  66 <section>
  67 <heading>Multiple output files</heading>
  68 <para>
  69 Creating multiple output files would be a handy feature.
  70 Certainly when you create your documents for the web, it would be nice
  71 to have one title page with an index or table of contents
  72 and put each chapter or section in a separate HTML or XML file.
  73 Unfortunately, to implement this, we need the &lt;xsl:document&gt; element
  74 which is proposed in version 1.1 of the XSLT recommendation.
  75 We'll have to wait until this is supported by the XSLT processor;
  76 just hang in there for a while.
  77 </para>
  78 </section>
  79 </chapter>