Login | Register
My pages Projects Community openCollabNet

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.

xml2docbook.py has the following usage:

  • [-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="prepare">
    <apply failonerror="true" executable="python"
            dir="${basedir}" dest="www" 
            relative="false">
        <arg value="${xml2docbook}"/>
        <arg value="-p"/>
        <arg value="${docs.dir}"/>
        <arg value="-prop"/>
        <arg value="build.properties"/>
        <arg value="-d"/>
        <arg value="${build.dir}"/>
        <arg value="-c" />
        <arg value="${condition}" />
        
        <srcfile/>
        <fileset id="xmlinputs" dir="doc" casesensitive="yes">
            <include name="**/*.${input.extension}"/>
            <exclude name="build.xml"/>
        </fileset>
    <mapper type="glob" from="*.${input.extension}" to="*.docbook"/>
    </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, its file must contain a root=“true” attribute. The other files are included directory or indirectly from the root document.

Example 1. index.xml

<article id="root-article" root="true"
    xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation =
'http://slackerdoc.tigris.org/xsd/slackerdoc.xsd'
    >
<title>Slacker's Docbook </title>

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

<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>
<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><a href="http://www.jedit.org">
<img src="http://www.jedit.org/made-with-jedit-7.png"
alt="Made with jEdit"/> </a>
</p>



<include src="motivation.xml" mode="xml" />
<include src="userguide.xml" mode="xml" />
<include src="styletest.xml" mode="xml" />
<include src="topics/specialtopics.xml" mode="xml" c="remark" />
<include src="history.xml" mode="xml" />
<include src="bibliography.xml" mode="xml" />

<index id="keywordindex" />

</article>

<include src=“index.xml” mode=“text”/>


The external files encountered by xml2docbook get entity definitions in a generated file called 00-generatedEntities.dtd. Any root document that processed by xml2docbook.py will refer to this DTD at the top:

Example 2. ../www/00-generatedEntities.dtd

<!ENTITY uml.xml2html.png SYSTEM "uml/xml2html.png" >
<!ENTITY history.docbook SYSTEM "history.docbook" >
<!ENTITY http...www.jedit.org.made.with.jedit.7.png SYSTEM
"http%3A/www.jedit.org/made-with-jedit-7.png" >
<!ENTITY motivation.docbook SYSTEM "motivation.docbook" >
<!ENTITY bibliography.docbook SYSTEM "bibliography.docbook" >
<!ENTITY topics.specialtopics.docbook SYSTEM
"topics/specialtopics.docbook" >
<!ENTITY styletest.docbook SYSTEM "styletest.docbook" >
<!ENTITY userguide.docbook SYSTEM "userguide.docbook" >
<!ENTITY uml.textproc.png SYSTEM "uml/textproc.png" >
<!ENTITY uml.entitymgr.png SYSTEM "uml/entitymgr.png" >
<!ENTITY uml.nodemapper.png SYSTEM "uml/nodemapper.png" >

<include src=“../www/00-generatedEntities.dtd” mode=“text”/>