In this document, we have shown how XML related technologies are used in an applicative context: extraction, transformation and presentation of information. But one important application is the use of XML for storing and publishing texts; in fact, it was this type of application that motivated SGML, the ancestor of XML and that influenced many of the features we described in this document. This is why, we decided to also use XML technologies for organizing this document. In fact, the first version was written using LaTeX but it was later retrofitted into XML when we realized that we might as well practice what we preach given the fact that there are many excellent XML technologies for technical documentation publication.
This appendix briefly describes the organization of this document as a set of about 50
valid XML files (taking the example files into account) valid to according the
DocBook 5.0 schema [51], written in RELAX NG Compact. A document of this
size is inconvenient to manipulate as a whole, so we make an extensive use of
Xinclude
to combine chapters and sections written in separate files. The
DocBook 5.0 RELAX NG Compact being the result of many years of experience, it is designed to be
modular so it is possible to get the validation of each section and chapter separately. With
modern XML editors, such as <oXygen/>, we can profit from real-time valid
completions and validation which are very useful when writing a document. Using
validation scenarios, it is even possible to validate references
between different files within the global final document. The examples are
Xinclude
d directly from the source XML used for testing. With
the proper organization, that means that the examples are always up to date. Of course,
making sure that the surrounding text still describes what is going on is still a hand made
error prone process... We
have also developed some special templates that include only subparts of examples in order
to shorten the document while staying in parallel with the source programs.
The publication process, shown in Figure C.1 is also done using some XML technologies presented in this document: from a single set of DocBook files, there are already stylesheets to transform them into either a single HTML file or, as we did, a set of related HTML files (a process called chunking in the DocBook jargon). But more, there also exist stylesheets to transform XML files into an XSL-FO file which is then rendered as a pdf file.
The DocBook 5.0 schema and stylesheets are already well developed but more interesting is
the fact that they are designed to be extensible [43]. So it was
possible for us to add a new XML tag (we called it refline
) designed to
indicate the line number within a listing. So in order that the XML file still be
valid, we could extend the original schema incrementally by adding this new tag. We then also
added a new template to implement the intended semantics to the original DocBook 5.0
stylesheets which are also designed to be customized either by means of parameters,
definition of new templates or redefinition of existing templates.
Example C.1 shows the structure of most of the Docbook elements that we used when writing this document. It can serve as a reminder when writing a technical document to be processed by a Docbook stylesheet.
Figure C.1. Overview of organization of the DocBook XML source files of this document
We do not show here all the XML files involved but only the main organization. Inclusion of files is shown by indentation: an included file is more indented than its including file. This figure can be compared with Figure 1.3 (page ).
![]() |
Example C.1. [DBTemplates.xml
] Examples of the most common uses of DocBook 5
elements in this document.
1 <?xml version="1.0" encoding="UTF-8"?> <!-- example uses of the most common docbook templates --> <?oxygen RNGSchema="DBx.rnc" type="compact"?> <!DOCTYPE book [ 5 <!ENTITY % ralient SYSTEM "rali.ent"> %ralient; ]> <chapter xmlns="http://docbook.org/ns/docbook" 10 xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xl="http://www.w3.org/1999/xlink" xml:id="chap_XXX"> <title>Some DocBook 5 templates</title> 15 <info> <keywordset><keyword>keyword for this document</keyword></keywordset> </info> 20 <indexterm class="startofrange" xml:id="section_start"> <primary>instance document</primary> </indexterm> <!-- range of the section --> <indexterm class="endofrange" startref="section_start"/> 25 <section xml:id="sec_title"> <title>Title</title> <indexterm><primary>index term</primary></indexterm> 30 <!-- list : bulleted --> <itemizedlist spacing="compact"> <listitem> <para>first bullet...</para> </listitem> 35 <listitem> <para>second bullet...</para> </listitem> </itemizedlist> 40 <!-- list : definition --> <variablelist> <?dbfo list-presentation="blocks"?> <!-- if terms are too long --> <varlistentry> <term>TERM</term> 45 <listitem><simpara>DEF</simpara></listitem> </varlistentry> </variablelist> <!-- figure --> 50 <figure xml:id="fig_NAME" floatstyle="before"> <title>TITLE</title> <simpara>CAPTION at the top</simpara> <mediaobject> <imageobject role="html"><!-- role are needed only for a pdf that do not appear in HTML --> 55 <imagedata fileref="images/WineTree.png" contentwidth="8in" width="8in"/> </imageobject> <imageobject role="fo"> <imagedata fileref="images/WineTree.pdf" scale="75"/> </imageobject> 60 </mediaobject> <caption><simpara/></caption><!-- if a line is wanted at the bottom --> </figure> <!-- table --> 65 <table xml:id="tab_NAME" shortentry="1"> <title>TITLE</title> <titleabbrev>TITLE small</titleabbrev> <?db-fo keep-together="always"?> <!-- to force a table to be on the same page --> <tgroup cols="2" align="left"> 70 <tbody> <row> <entry>ROW1_COL1</entry> <entry>ROW1_COL2</entry> </row> 75 <row> <entry>ROW2_COL2</entry> <entry>ROW2_COL2</entry> </row> </tbody> 80 </tgroup> <caption><simpara>CAPTION</simpara></caption> </table> 85 <!-- example listing --> <example xml:id="fileName.ext"> <title>[<link xl:href="&r-root;fileName.ext"><filename>fileName.ext</filename></link>] a title </title> <indexterm> <primary>examples</primary> 90 <secondary>fileName.ext</secondary> </indexterm> <simpara>caption to appear at the example.</simpara> <!-- listing with callouts --> <programlistingco> 95 <areaspec units="linecolumn"> <area xml:id="co_id" coords="L 70"/> </areaspec> <programlisting linenumbering="numbered"> <!--<xi:include href="file..." parse="text"/>--></programlisting> 100 <calloutlist> <callout arearefs="co_id"> <para>XXX</para> </callout> </calloutlist> 105 </programlistingco> </example> <para> <!-- things that can appear in a paragraph... --> <!-- references to line numbers in a listing (personal extension to docbook) --> 110 <refline lineid="co_id"/> <!--<refline lineid="co_id" source="yes"/>--> <refline lineid="co_id" linkend="fileName.ext"/> <!-- italics and bold face --> 115 <emphasis>italics</emphasis> <emphasis role="strong">bold</emphasis> <!-- link to an external url --> <link xl:href="http:..."/> 120 <link xl:href="http:...">TEXT</link> <!-- references to an ID, can also be used for refering to a bibliography entries --> <xref linkend="ID"/> 125 <xref linkend="ID" xrefstyle="select: label page"/> <!-- index terms --> <indexterm class="startofrange" xml:id="PRIMARY_start"> <primary>PRIMARY</primary> 130 </indexterm> <indexterm class="endofrange" startref="PRIMARY_start"/> <indexterm><primary>PRIMARY</primary></indexterm> </para> 135 </section> <!-- forcing a page break or clearing floats--> <?hard-pagebreak?> <?float-clear?> 140 <!-- bibliography entry --> <bibliography> <biblioentry xml:id="ID"> <authorgroup> 145 <author> <personname> <firstname>FIRSTNAME</firstname> <surname>NAME</surname> </personname> 150 </author> </authorgroup> <publishername>PUB</publishername> <pubdate>YYYY</pubdate> <title>TITRE</title> 155 </biblioentry> </bibliography> </chapter>