Login | Register
My pages Projects Community openCollabNet

2.  User's Guide

[ fromfile: userguide.xml id: userguide ]

xml2docbook.py is the script which generates standard Docbook from Slacker's Docbook. It is the first step in the build process, designated in build.xml as target name docbookfiles.

To see what tags were added above and beyond standard docbook, see Appendix A.

xml2docbook.py has the following usage:

  • [-prop propfile] - the property file used for loading optional properties, which can be used to customize further how the document is generated. See the section called “ Build properties for configuration ” for more details.

  • [-p srcdir] - the prefix to chop off when calculating relative pathnames.

  • [-d destdir] - place generated docbook/dtd files (default is the current directory).

  • [-c condition(,condition)*] - include conditional elements in the output.

  • file1 [file2, file3, ...] - filenames to process

Typically, this step is run from inside an ant build script.

<target name="docbookfiles"
            description="generates Standard Docbook/xml from Slacker's docbook/xml"
            depends="validate, prepare">
        <apply executable="python"
                dir="${docs.dir}" failonerror="true"
                dest="${build.dir}" relative="true">
            <arg value="${slacker.dir}/bin/xml2docbook.py"/>
            <arg value="-p"/>
            <arg value="${docs.dir}"/>
            <arg value="-prop"/>
            <arg value="${basedir}/build.properties"/>
            <arg value="-d"/>
            <arg value="${build.dir}"/>
            <arg value="-c" />
            <arg value="${condition}" />
            <srcfile/>
            <fileset id="xmlinputs" dir="${docs.dir}" casesensitive="yes">
                <include name="**/*.xml" />
                <exclude name="build.xml"/>
            </fileset>
        <mapper type="glob" from="*.xml" to="*.xml"/>
        </apply>
</target>

To create an html manual from the result, you need to run the generated root document through an xslt processor such as xsltproc, given the docbook stylesheets.

Figure 1.  From XML to HTML or PDF

From XML to HTML or PDF

One document must be designated a "root" document for XSLTproc. The other XML files are included directly or indirectly from the root document using the <xi:include> syntax.

Example 1. examples/index-example.xml

<?xml version="1.0" encoding="UTF-8"?>
<article id="index-example" root="true"
    xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation =
'http://slackerdoc.tigris.org/xsd/slackerdoc.xsd'
    xmlns:xi="http://www.w3.org/2001/XInclude" >
<title>Slacker's Docbook </title>

<articleinfo>
 <date>@date@</date>
  <releaseinfo>@version@ </releaseinfo>

<abstract><p> Slacker's Docbook is yet another Docbook preprocessor.
It is a document format, plus scripts, stylesheets and libraries for
converting documents into  standard Docbook/XML. Bulleted lists,
conditional processing, subdocument and sourecode example inclusions,
easy incorporation of images, and a host of other commonly faced
problems are solved by Slacker's Docbook. In particular, it can be
used to develop multiple versions (such as a textbook and overhead
slides) of a document from a single source. This system was designed
for writing computer science courseware (tutorials, assignments,
exams), so it well suited for writing books that contain many
sourcecode examples. </p></abstract>
</articleinfo>
<p> This is a self-documenting document about how to
write self-documenting documentation. It was written in
XML, but you are probably reading it in XHTML or PDF, after
it has gone through a number of transformations,
including Docbook XML as an intermediate file format.
</p>

<p> This project is hosted on <a
href="http://slackerdoc.tigris.org/">Slackerdoc.Tigris.org</a>. From
there, you can gain access to file releases, as well as the subversion
repository. You are welcome to join the project if you wish to
contribute.
</p>


<p> We include the next sections using XInclude directives, which is
processed independently of slacker's docbook,
to join together child documents into a larger whole. Note
&lt;include&gt; tag reformats included files as program listings, in
contrast to XInclude's version in the <tt>xi</tt> namespace. </p>

<xi:include href="motivation.xml" />
<xi:include href="userguide.xml"  />
<xi:include href="styletest.xml"  />
<xi:include href="history.xml" />
<xi:include href="bibliography.xml"  />

<index id="keywordindex" />

</article>