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.2 $
   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 <strong>include</strong> element with a single attribute to specify
  33 the name of the file to be included.
  34 For example, this chapter is in a file called "multifiles.xml", which
  35 is included in the main document with:
  36 <verbatim>
  37 &lt;include href="multifiles.xml"/&gt;
  38 </verbatim>
  39 There is one restriction to including other files: The included files
  40 must be valid XML files as well.
  41 It is not possible to include other kinds of files, such as raw text
  42 or source code.
  43 So, the included XML file starts with the usual XML declaration, but has
  44 a different root element declared in the &lt;!DOCTYPE...&gt; declaration:
  45
  46 <verbatim>
  47 &lt;?xml version="1.0"?&gt;
  48 &lt;!DOCTYPE chapter SYSTEM "../doc.dtd"&gt;
  49 &lt;chapter&gt;
  50 &lt;--  The content of this chapter --&gt;
  51 &lt;/chapter&gt;
  52 </verbatim>
  53
  54 </para>
  55 </section>
  56 <section>
  57 <heading>Multiple output files</heading>
  58 <para>
  59 Creating multiple output files would be a handy feature.
  60 Certainly when you create your documents for the web, it would be nice
  61 to have one title page with an index or table of contents
  62 and put each chapter or section in a separate HTML or XML file.
  63 Unfortunately, to implement this, we need the &lt;xsl:document&gt; element
  64 which is proposed in version 1.1 of the XSLT recommendation.
  65 We'll have to wait until this is supported by the XSLT processor;
  66 just hang in there for a while.
  67 </para>
  68 </section>
  69 </chapter>