File: spiel.html

package info (click to toggle)
lg-issue75 2-1
links: PTS
area: main
in suites: sarge
size: 1,100 kB
ctags: 212
sloc: perl: 228; makefile: 62; sh: 34
file content (733 lines) | stat: -rw-r--r-- 25,286 bytes
<!--startcut  ==============================================-->
<!-- *** BEGIN HTML header *** -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML><HEAD>
<title>Writing Documentation, Part III: DocBook/XML LG #75</title>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#0000AF"
ALINK="#FF0000">
<!-- *** END HTML header *** -->

<CENTER>
<A HREF="http://www.linuxgazette.com/">
<IMG ALT="LINUX GAZETTE" SRC="../gx/lglogo.png" 
	WIDTH="600" HEIGHT="124" border="0"></A> 
<BR>

<!-- *** BEGIN navbar *** -->
<IMG ALT="" SRC="../gx/navbar/left.jpg" WIDTH="14" HEIGHT="45" BORDER="0" ALIGN="bottom"><A HREF="piszcz.html"><IMG ALT="[ Prev ]" SRC="../gx/navbar/prev.jpg" WIDTH="16" HEIGHT="45" BORDER="0" ALIGN="bottom"></A><A HREF="index.html"><IMG ALT="[ Table of Contents ]" SRC="../gx/navbar/toc.jpg" WIDTH="220" HEIGHT="45" BORDER="0" ALIGN="bottom" ></A><A HREF="../index.html"><IMG ALT="[ Front Page ]" SRC="../gx/navbar/frontpage.jpg" WIDTH="137" HEIGHT="45" BORDER="0" ALIGN="bottom"></A><A HREF="http://www.linuxgazette.com/cgi-bin/talkback/all.py?site=LG&article=http://www.linuxgazette.com/issue75/spiel.html"><IMG ALT="[ Talkback ]" SRC="../gx/navbar/talkback.jpg" WIDTH="121" HEIGHT="45" BORDER="0" ALIGN="bottom"  ></A><A HREF="../faq/index.html"><IMG ALT="[ FAQ ]" SRC="./../gx/navbar/faq.jpg"WIDTH="62" HEIGHT="45" BORDER="0" ALIGN="bottom"></A><A HREF="williamson.html"><IMG ALT="[ Next ]" SRC="../gx/navbar/next.jpg" WIDTH="15" HEIGHT="45" BORDER="0" ALIGN="bottom"  ></A><IMG ALT="" SRC="../gx/navbar/right.jpg" WIDTH="15" HEIGHT="45" ALIGN="bottom">
<!-- *** END navbar *** -->
<P>
</CENTER>

<!--endcut ============================================================-->

<H4 ALIGN="center">
"Linux Gazette...<I>making Linux just a little more fun!</I>"
</H4>

<P> <HR> <P> 
<!--===================================================================-->

<center>
<H1><font color="maroon">Writing Documentation, Part III: DocBook/XML</font></H1>
<H4>By <a href="mailto:cspiel@hammersmith-consulting.com">Christoph Spiel</a></H4>
</center>
<P> <HR> <P>  

<!-- END header -->




<p>To cite from ``DocBook -- The Definitive Guide'' (see <a href="#further 
reading">Further Reading</a> at the end of this section), <em>DocBook provides
a system for writing structured documents using SGML or XML</em>. In the
following, I shall focus on the XML-variant of DocBook, because the
SGML-variant is being phased out.</p>

<p>DocBook has been developed with a slightly different mindset than the 
systems I discussed in the two previous articles  
(<A HREF="../issue73/spiel.html">POD article</A>, 
<A HREF="../issue74/spiel.html">LaTeX/latex2html article</A>).
</p>

<ul>
<li>``Text'' in a DocBook document is better understood as ``textual data''.
Along the same lines, a DocBook document is better thought of as a
human-readable database.</li>

<li>DocBook, as a standard, prescribes how valid documents must be formed and
how the output produced from a DocBook document has to ``look''. I put quotes
around ``look'', because DocBook documents are not restricted to being viewed on
a screen, but can also be transformed into speech, for example in a car
navigation system. (Imagine your SUV asking you: ``Do you want to install KDE
version 3 now?'')</li>

<li>When transformed into any output format, DocBook documents are rigidly
verified whether they conform to a given structure. This structure is defined
in so-called document type descriptions, or DTDs for short. 

<blockquote>By changing the DTD, almost arbitrary constraints can be imposed on
a DocBook document. For example, an organizing committee of a conference
might adapt the DocBook DTD in such way that all the article of the conference's
proceedings will have a uniform look and all the necessary author
information.</blockquote>
</li>
</ul>

<p>The particular features of DocBook mentioned, imply uses of DocBook
documents that are not possible, at least not easily, with POD or LaTeX
documents.</p>

<ul>
<li>Because of their structure, DocBook documents are easily created,
modified, or queried programmatically. 

<p>For example, we load the <code>XML::DOM</code> module into Perl to access
XML compliant documents, and Python ships with the <code>xml.dom</code>
module, which has been designed for the same purpose.</p>

<p>The World Wide Web Consortium (W3C, <a href="http://www.w3c.org)">
http://www.w3c.org)</a> has even defined a language for XML translations,
called XSLT (see for example <a href="http://www.w3.org/TR/xslt">
http://www.w3.org/TR/xslt</a> and <a href= 
"http://www.oasis-open.org/cover/xsl.html).">
http://www.oasis-open.org/cover/xsl.html).</a> XSLT itself is a language
defined within the SGML framework, which makes XML and XSL look quite similar:
loads of angle brackets.</p>
</li>

<li>Various tools transform DocBook sources into HTML, TeX, GNU Texinfo and
many other -- including audio -- formats. This is again different to the
source formats we looked at before, where only a single application does the
transformation. 

<p>Popular transformation tools are:</p>

<ul>
<li>OpenJade (http://openjade.sourceforge.net/), which uses DSSSL (see for
example <a href="http://www.jclark.com/dsssl/">
http://www.jclark.com/dsssl/</a> and <a href= 
"http://www.oasis-open.org/cover/dsssl.html),">
http://www.oasis-open.org/cover/dsssl.html),</a> as a Lisp-like language to
describe the transformations from XML-DocBook to HTML, TeX, and so on and</li>

<li>Saxon (http://saxon.sourceforge.net/), which uses XSL to do the job.</li>
</ul>

<p>The installation of both tools including the necessary <a href= 
"http://sourceforge.net/projects/docbook">DSSSL stylesheets</a> or <a href= 
"http://sourceforge.net/projects/docbook">XSL stylesheets</a> is quite tricky,
thus I would like to recommend to beginners the installation from <em>
.deb</em> or <em>.rpm</em> packages.</p>
</li>
</ul>

<p>Being general purpose translators, both tools are not restricted to
transforming DocBook documents. If you feed them the right style sheets, they
will do other translations, too.</p>

<h3><a name="syntax">Syntax</a></h3>

<p>The DocBook/XML syntax resembles HTML. The fundamental difference between
the two being the strictness with which the syntax is enforced. Many HTML
browsers are extremely forgiving about unterminated elements, and they often
silently ignore unknown elements or attributes. DocBook/XML translators reject
non-DTD complying input with detailed error messages, and refuse to produce
any output in such cases.
</p>

<p>DocBook/XML is spoken in several variants, where the variants differ in
interpreting the closing tag of an element. The most verbose dialect always
closes <code>&lt;tag&gt;</code> with <code>&lt;/tag&gt;</code>. Another
variant allows for abbreviating the closing tag to <code>&lt;/&gt;</code>, yet
another allows dropping the closing tag for empty elements all together. I
prefer writing out every end tag, a style that has proven advantageous in
deeply nested structures such as nested lists. So, in this article only the
form <code>&lt;tag&gt; ... &lt;/tag&gt;</code> will appear.</p>

<p>Special characters are written with the ampersand-semicolon convention as
they are in HTML. The most frequently used special characters are</p>

<ul>
<li>Ampersand, ``<code>&amp;amp;</code>''</li>

<li>Less-Than Sign, ``<code>&amp;lt;</code>'' and</li>

<li>Greater-Than Sign, ``<code>&amp;gt;</code>''.</li>
</ul>

<p>Comments are bracketed between ``<code>&lt;!--</code>'' and
``<code>--</code>&gt;''.</p>

<h3><a name="document structure">Document Structure</a></h3>

<p>As already mentioned, DocBook documents must adhere to the structure that
is defined in a DTD. Every document starts with selecting a particular
DTD:</p>

<pre>
    &lt;!DOCTYPE                                       (1)
     book                                           (2)
     PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"    (3)
     "/usr/share/sgml/db41xml/docbookx.dtd"         (4)
     [ ]                                            (5)
    &gt;
</pre>

<p>where I have broken the expression (from ``&lt;'' to ``&gt;'') into several
lines for easier analysis, and added numbers in parentheses for reference.</p>

<p>Part&nbsp;(1) tells the system that we are about to choose our DTD.
Part&nbsp;(2) defines element <a href="#item_book"><code>book</code></a> to be
the root element of our document. part&nbsp;(3), the public identifier selects
the DTD to use. The public identifier is the string in quotes. The system
identifier, part&nbsp;(4) tells the translation tools where to find the DTD on
the local computer system. Within the square brackets, part&nbsp;(5), we could
place so called entity definitions, but I do not want go into detail on
entities in this introduction, so we leave this space empty.</p>

<p>Now, we start the text with the root element, in our case <a href= 
"#item_book"><code>book</code></a>. What elements go into <a href=
"#item_book"><code>book</code></a> is defined in the DocBook DTD. These are,
for example, <code>bookinfo</code> or <code>chapter</code>. For a
comprehensive list of allowed elements, consult ``The Definitive Guide''. The
elements allowed within <code>bookinfo</code> or <code>chapter</code> are also
defined in the DocBook DTD as are all elements. The only way constructing a
valid document is by obeying all the rules prescribed by the DTD.</p>

<p>What might look like a drag on first sight -- Rules? Rules suck! -- is the
key to open up the document to programmatic access. As the document complies
to the DTD, all post-processing can rely on that very fact. Good for the
programmers of the post-processors! I have to admit that the number of
elements and the elements' mutual relationships is tough to pick up. However,
the relations are logical: a chapter contains one ore more (introductory)
paragraphs and one or more Level&nbsp;1 sections. No section, on the other
hand, contains a chapter, that would be nonsense. Having a copy of ``The
Definitive Guide'' right next to the keyboard also helps to learn DocBook.
Further down, there is a short compilation of commonly used tags.</p>

<p>Here comes a very short, but complete DocBook document.</p>

<pre>
    &lt;!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
                          "/usr/share/sgml/db41xml/docbookx.dtd" []&gt;
</pre>

<pre>
    &lt;book&gt;
        &lt;bookinfo&gt;
            &lt;title&gt;XYZ (version 0.8.15) User's Manual&lt;/title&gt;
        &lt;/bookinfo&gt;
</pre>

<pre>
        &lt;chapter id = "chapter-introduction"&gt;
            &lt;title&gt;Introduction&lt;/title&gt;
</pre>

<pre>
            &lt;para&gt;
                This chapter provides a quick introduction to XYZ.
            &lt;/para&gt;
</pre>

<pre>
            &lt;sect1 id = "section-syntax"&gt;
                &lt;title&gt;Syntax&lt;/title&gt;
</pre>

<pre>
                &lt;para&gt;
                    In this section we present an outline of the
                    syntax of the XYZ language.
                &lt;/para&gt;
            &lt;/sect1&gt;
</pre>

<pre>
            &lt;sect1 id = "section-core-library"&gt;
                &lt;title&gt;Core Library&lt;/title&gt;
</pre>

<pre>
                &lt;para&gt;
                    Even if no additional libraries are loaded to a
                    XYZ program, it has access to some core library
                    functions.
                &lt;/para&gt;
            &lt;/sect1&gt;
        &lt;/chapter&gt;
</pre>

<pre>
        &lt;chapter id = "chapter-commands"&gt;
            &lt;title&gt;Commands&lt;/title&gt;
</pre>

<pre>
            &lt;sect1 id = "section-interactive-commands"&gt;
                &lt;title&gt;Interactive Commands&lt;/title&gt;
</pre>

<pre>
                &lt;para&gt;
                    ...
                &lt;/para&gt;
</pre>

<pre>
                &lt;sect2 id = "section-interactive-commands-argumentless"&gt;
                    &lt;title&gt;Argumentless Commands&lt;/title&gt;
</pre>

<pre>
                    &lt;para&gt;
                        ...
                    &lt;/para&gt;
                &lt;/sect2&gt;
            &lt;/sect1&gt;
</pre>

<pre>
            &lt;sect1 id = "section-non-interactive-commands"&gt;
                &lt;title&gt;Non-Interactive Commands&lt;/title&gt;
</pre>

<pre>
                &lt;para&gt;
                    ...
                &lt;/para&gt;
</pre>

<pre>
                &lt;sect2 id = "section-non-interactive-commands-argumentless"&gt;
                    &lt;title&gt;Argumentless Commands&lt;/title&gt;
</pre>

<pre>
                    &lt;para&gt;
                        ...
                    &lt;/para&gt;
                &lt;/sect2&gt;
            &lt;/sect1&gt;
        &lt;/chapter&gt;
    &lt;/book&gt;
</pre>

<h3><a name="useful tags">Useful Tags</a></h3>

<p>To help the aspiring DocBook writer making sense of the loads of elements,
the DocBook standard defines, I have compiled a bunch of useful tags, which
are used often.</p>

<h4><a name="root section tags">Root Section Tags</a></h4>

<p>Root section tags define the outermost element of any document.</p>

<dl>
<dt><strong><a name="item_book"><code>book</code></a></strong><br>
</dt>

<dd>&lt;book&gt; 

<pre>
  I&lt;paragraphs or chapters&gt;
</pre>

<p>&lt;/book&gt;</p>
</dd>

<dt><strong><a name="item_article"><code>article</code></a></strong><br>
</dt>

<dd>&lt;article&gt; 

<pre>
  I&lt;paragraphs or level 1 sections&gt;
</pre>

<p>&lt;/article&gt;</p>
</dd>
</dl>

<h4><a name="sectioning tags">Sectioning Tags</a></h4>

<p>Sectioning elements divide the document into logical parts like chapters,
sections, paragraphs, and so on.</p>

<dl>
<dt><strong><a name="item_chapter%2C_sect1%2C_%2E%2E%2E%2C_sect6"><code>
chapter</code>, <code>sect1</code>, ..., <code>sect6</code></a></strong><br>
</dt>

<dd>&lt;chapter id = "<em>label</em>"&gt; 

<p><em>title</em></p>

<p>followed by</p>

<p><em>paragraphs or level N+1 sections</em></p>

<p>&lt;/chapter&gt;</p>

<p>Define a section. Commonly, chapter and section elements carry the <code>
id</code> attribute, which allows for referencing the elements with, for
example, &lt;xref linkend = "label"&gt;&lt;/xref&gt;.</p>
</dd>

<dt><strong><a name="item_para"><code>para</code></a></strong><br>
</dt>

<dd>&lt;para&gt; 

<p><em>paragraph text</em></p>

<p>&lt;/para&gt;</p>

<p>Group several lines of text together to form a paragraph. This is the
workhorse element in many documents.</p>
</dd>

<dt><strong><a name="item_programlisting"><code>
programlisting</code></a></strong><br>
</dt>

<dd>&lt;programlisting role = "<em>language</em>"&gt; 

<p><em>program text</em></p>

<p>&lt;/programlisting&gt;</p>

<p>Render a longish piece of program text -- preserving the line breaks.
The program is assumed to be written in the language specified in the
<code>role</code> attribute. Note
that within <a href="#item_programlisting"><code>programlisting</code></a> all
special characters retain their meaning!</p>

<p>This means in particular that you cannot use the control characters
``<code>&lt;</code>'', ``<code>&gt;</code>'', and ``<code>&amp;</code>'' inside
of it.  The several workarounds for this problem.  Either you replace all 
control characters with their mnemonic equivalents (``<code>&amp;lt;</code>'',
``<code>&amp;gt;</code>'', and ``<code>&amp;amp;</code>'' in our example), or
you wrap the program code in a <code>CDATA</code>, like, for example,</p>

<pre>
    &lt;programlisting&gt;
        &lt;![CDATA[
            cout &lt;&lt; "value = &lt;" &lt;&lt; &amp;p &lt;&lt; "&gt;\n";
        ]]&gt;
    &lt;/programlisting&gt;
</pre>

<p>or, if the program is stored in file&nbsp;<EM>my-program.pl</EM>, pull in
the whole file with</p>

<pre>
    &lt;programlisting&gt;
        &lt;inlinemediaobject&gt;
            &lt;imageobject&gt;
                &lt;imagedata format = "linespecific"
                           fileref = "my-program.pl"&gt;&lt;/imagedata&gt;
            &lt;/imageobject&gt;
        &lt;/inlinemediaobject&gt;
    &lt;/programlisting&gt;
</pre>
</dd>
</dl>

<h4><a name="list making tags">List-Making Tags</a></h4>

<p>Generate the three typical types of lists.</p>

<p>The <em>item</em>s or <em>definition</em>s are typically formed by one or
more paragraphs, but they are allowed to contain program listings, too. The
<em>term</em>s usually are one or more words, not paragraphs.</p>

<ul>
<li>Itemized List 

<p>&lt;itemizedlist&gt;</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&lt;listitem&gt;</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<em>first item</em></p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&lt;/listitem&gt;</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&lt;listitem&gt;</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<em>second item</em></p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&lt;/listitem&gt;</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;...</p>

<p>&lt;/itemizedlist&gt;</p>
</li>

<li>Enumerated List 

<p>&lt;enumeratedlist&gt;</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&lt;listitem&gt;</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<em>first item</em></p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&lt;/listitem&gt;</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&lt;listitem&gt;</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<em>second item</em></p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&lt;/listitem&gt;</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;...</p>

<p>&lt;/enumeratedlist&gt;</p>
</li>

<li>Description List 

<p>&lt;variablelist&gt;</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&lt;varlistentry&gt;</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;term&gt;<em>first
term</em>&lt;/term&gt;</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;listitem&gt;</p>

<p>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<em>
first definition</em></p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/listitem&gt;</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&lt;/varlistentry&gt;</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&lt;varlistentry&gt;</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;term&gt;<em>second
term</em>&lt;/term&gt;</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;listitem&gt;</p>

<p>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<em>
second definition</em></p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/listitem&gt;</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&lt;/varlistentry&gt;</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;...</p>

<p>&lt;/variablelist&gt;</p>
</li>
</ul>

<h4><a name="inline markup tags">Inline Markup Tags</a></h4>

<dl>
<dt><strong><a name="item_emphasis"><code>emphasis</code></a></strong><br>
</dt>

<dd>&lt;emphasis&gt;<em>text to be emphasized</em>&lt;/emphasis&gt; 

<p>Highlight a short part of the document; usually a single word.</p>
</dd>

<dt><strong><a name="item_filename"><code>filename</code></a></strong><br>
</dt>

<dd>&lt;filename&gt;<em>filename or directory name</em>&lt;/filename&gt; 

<p>Mark word as filename.</p>
</dd>

<dt><strong><a name="item_literal"><code>literal</code></a></strong><br>
</dt>

<dd>&lt;literal&gt;<em>literal something</em>&lt;/literal&gt; 

<p>&lt;literal role = "<em>classification</em>"&gt;<em>literal
something</em>&lt;/literal&gt;</p>

<p>Mark a word as being a literal expression. Use this tag only as last
possibility, if no other more specific tag matches. To calm one's bad
conscience, <a href="#item_literal"><code>literal</code></a> often gets
decorated with a <code>role</code> attribute, which describes more precisely
the kind of literal.</p>
</dd>

<dt><strong><a name="item_replaceable"><code>
replaceable</code></a></strong><br>
</dt>

<dd>&lt;replaceable&gt;<em>placeholder name</em>&lt;/replaceable&gt; 

<p>Mark a meta-variable.</p>
</dd>

<dt><strong><a name="item_title"><code>title</code></a></strong><br>
</dt>

<dd>&lt;title&gt;<em>title</em>&lt;/title&gt; 

<p>Give a name to a section or a formal element, like a table.</p>
</dd>
</dl>

<h4><a name="cross references">Cross References</a></h4>

<p>Cross references refer to other parts of the same DocBook document or to
other documents on the World Wide Web. Targets of the former are all elements
that carry an <code>id</code> attribute, targets of the latter are selected
with universal resource locators (URLs).</p>

<dl>
<dt><strong><a name="item_link"><code>link</code></a></strong><br>
</dt>

<dd>&lt;link linkend = "<em>target</em>"&gt;<em>item</em>&lt;/link&gt; 

<p>Install a (hyper-)link to the spot identified via <em>target</em> within
the current document.</p>
</dd>

<dt><strong><a name="item_ulink"><code>ulink</code></a></strong><br>
</dt>

<dd>&lt;ulink url = "<em>complete URL</em>"&gt;<em>item</em>&lt;/ulink&gt; 

<p>Install a hyper-link to a WWW-accessible document identified by a <em>
complete URL</em>. A complete URL includes the protocol, for example, <code>
http://</code>.</p>
</dd>

<dt><strong><a name="item_xref"><code>xref</code></a></strong><br>
</dt>

<dd>&lt;xref linkend = "<em>target</em>"&gt;&lt;/xref&gt; 

<p>Install a (hyper-)link to the spot identified via <em>target</em> within
the current document. A translator will add text around an <a href=
"#item_xref"><code>xref</code></a> element. For example, a <a href=
"#item_xref"><code>xref</code></a> to a section might be decorated with the
text ``<code>see section</code>''.</p>
</dd>
</dl>

<h3><a name="what i have left out">What I Have Left Out</a></h3>

<p>Ugh, I left out tons of stuff, but only to give you a smooth, 
non-frightening introduction. Some great things DocBook handles that I have not
discussed are</p>

<ul>
<li>Tables,</li>

<li>Graphics (with automatic selection of the ``appropriate'' format),
and</li>

<li>Automated index generation.</li>
</ul>

<p>Also left out is everything related to changing the DTD or changing the
style sheets.</p>

<h3><a name="pros and cons">Pros and Cons</a></h3>

<dl>
<dt><strong><a name="item_Pros">Pros</a></strong><br>
</dt>

<dd>
<ul>
<li>DocBook is an official W3C standard</li>

<li>Access to text via (user-defined) programs</li>

<li>Texts carry a rich marked up</li>
</ul>
</dd>

<dt><strong><a name="item_Cons">Cons</a></strong><br>
</dt>

<dd>
<ul>
<li>Slow transformation</li>

<li>The DocBook format is very verbose. Unless the writer uses a special
editor, a lot of typing is required.</li>
</ul>
</dd>
</dl>

<h3><a name="further reading">Further Reading</a></h3>

<ul>
<li>
Norman Walsh and Leonard Muellner, <em>DocBook: The Definitive Guide</em>,
O'Reilly&nbsp;&amp;&nbsp;Associates, first edition, ISBN:&nbsp;156592-580-7 at
<a href= 
"http://www.amazon.com/exec/obidos/ASIN/1565925807/qid%3D1010861150/ref%3Dsr%5F11%5F0%5F1/104-6293324-1789547">
Amazon</a>. It is also available <a href="http://www.docbook.org/tdg/en/">
online</a> (as second edition)
</li>

<li>
<a href="http://www.docbook.org">DocBook website</a>
</li>

<li>
Norman Walsh's (chairman of the DocBook steering committee) <a href= 
"http://nwalsh.com/">website</a>
</li>

<li>
<a href="http://www.oasis-open.org/committees/docbook/">DocBook Steering
Committee</a>
</li>
</ul>

<p>Next month: Texinfo</p>





<!-- *** BEGIN bio *** -->
<SPACER TYPE="vertical" SIZE="30">
<P> 
<H4><IMG ALIGN=BOTTOM ALT="" SRC="../gx/note.gif">Christoph Spiel</H4>
<EM>Chris runs an Open Source Software consulting company in Upper Bavaria, Germany.
Despite being trained as a physicist -- he holds a PhD in physics from Munich
University of Technology -- his main interests revolve around numerics,
heterogenous programming environments, and software engineering.  He can be
reached at 
<A HREF="mailto:cspiel@hammersmith-consulting.com">cspiel@hammersmith-consulting.com</A>.</EM>

<!-- *** END bio *** -->

<!-- *** BEGIN copyright *** -->
<P> <hr> <!-- P --> 
<H5 ALIGN=center>

Copyright &copy; 2002, Christoph Spiel.<BR>
Copying license <A HREF="../copying.html">http://www.linuxgazette.com/copying.html</A><BR> 
Published in Issue 75 of <i>Linux Gazette</i>, February 2002</H5>
<!-- *** END copyright *** -->

<!--startcut ==========================================================-->
<HR><P>
<CENTER>
<!-- *** BEGIN navbar *** -->
<IMG ALT="" SRC="../gx/navbar/left.jpg" WIDTH="14" HEIGHT="45" BORDER="0" ALIGN="bottom"><A HREF="piszcz.html"><IMG ALT="[ Prev ]" SRC="../gx/navbar/prev.jpg" WIDTH="16" HEIGHT="45" BORDER="0" ALIGN="bottom"></A><A HREF="index.html"><IMG ALT="[ Table of Contents ]" SRC="../gx/navbar/toc.jpg" WIDTH="220" HEIGHT="45" BORDER="0" ALIGN="bottom" ></A><A HREF="../index.html"><IMG ALT="[ Front Page ]" SRC="../gx/navbar/frontpage.jpg" WIDTH="137" HEIGHT="45" BORDER="0" ALIGN="bottom"></A><A HREF="http://www.linuxgazette.com/cgi-bin/talkback/all.py?site=LG&article=http://www.linuxgazette.com/issue75/spiel.html"><IMG ALT="[ Talkback ]" SRC="../gx/navbar/talkback.jpg" WIDTH="121" HEIGHT="45" BORDER="0" ALIGN="bottom"  ></A><A HREF="../faq/index.html"><IMG ALT="[ FAQ ]" SRC="./../gx/navbar/faq.jpg"WIDTH="62" HEIGHT="45" BORDER="0" ALIGN="bottom"></A><A HREF="williamson.html"><IMG ALT="[ Next ]" SRC="../gx/navbar/next.jpg" WIDTH="15" HEIGHT="45" BORDER="0" ALIGN="bottom"  ></A><IMG ALT="" SRC="../gx/navbar/right.jpg" WIDTH="15" HEIGHT="45" ALIGN="bottom">
<!-- *** END navbar *** -->
</CENTER>
</BODY></HTML>
<!--endcut ============================================================-->