734 lines
25 KiB
HTML
734 lines
25 KiB
HTML
<!--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><tag></code> with <code></tag></code>. Another
|
|
variant allows for abbreviating the closing tag to <code></></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><tag> ... </tag></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;</code>''</li>
|
|
|
|
<li>Less-Than Sign, ``<code>&lt;</code>'' and</li>
|
|
|
|
<li>Greater-Than Sign, ``<code>&gt;</code>''.</li>
|
|
</ul>
|
|
|
|
<p>Comments are bracketed between ``<code><!--</code>'' and
|
|
``<code>--</code>>''.</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>
|
|
<!DOCTYPE (1)
|
|
book (2)
|
|
PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN" (3)
|
|
"/usr/share/sgml/db41xml/docbookx.dtd" (4)
|
|
[ ] (5)
|
|
>
|
|
</pre>
|
|
|
|
<p>where I have broken the expression (from ``<'' to ``>'') into several
|
|
lines for easier analysis, and added numbers in parentheses for reference.</p>
|
|
|
|
<p>Part (1) tells the system that we are about to choose our DTD.
|
|
Part (2) defines element <a href="#item_book"><code>book</code></a> to be
|
|
the root element of our document. part (3), the public identifier selects
|
|
the DTD to use. The public identifier is the string in quotes. The system
|
|
identifier, part (4) tells the translation tools where to find the DTD on
|
|
the local computer system. Within the square brackets, part (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 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>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
|
|
"/usr/share/sgml/db41xml/docbookx.dtd" []>
|
|
</pre>
|
|
|
|
<pre>
|
|
<book>
|
|
<bookinfo>
|
|
<title>XYZ (version 0.8.15) User's Manual</title>
|
|
</bookinfo>
|
|
</pre>
|
|
|
|
<pre>
|
|
<chapter id = "chapter-introduction">
|
|
<title>Introduction</title>
|
|
</pre>
|
|
|
|
<pre>
|
|
<para>
|
|
This chapter provides a quick introduction to XYZ.
|
|
</para>
|
|
</pre>
|
|
|
|
<pre>
|
|
<sect1 id = "section-syntax">
|
|
<title>Syntax</title>
|
|
</pre>
|
|
|
|
<pre>
|
|
<para>
|
|
In this section we present an outline of the
|
|
syntax of the XYZ language.
|
|
</para>
|
|
</sect1>
|
|
</pre>
|
|
|
|
<pre>
|
|
<sect1 id = "section-core-library">
|
|
<title>Core Library</title>
|
|
</pre>
|
|
|
|
<pre>
|
|
<para>
|
|
Even if no additional libraries are loaded to a
|
|
XYZ program, it has access to some core library
|
|
functions.
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|
|
</pre>
|
|
|
|
<pre>
|
|
<chapter id = "chapter-commands">
|
|
<title>Commands</title>
|
|
</pre>
|
|
|
|
<pre>
|
|
<sect1 id = "section-interactive-commands">
|
|
<title>Interactive Commands</title>
|
|
</pre>
|
|
|
|
<pre>
|
|
<para>
|
|
...
|
|
</para>
|
|
</pre>
|
|
|
|
<pre>
|
|
<sect2 id = "section-interactive-commands-argumentless">
|
|
<title>Argumentless Commands</title>
|
|
</pre>
|
|
|
|
<pre>
|
|
<para>
|
|
...
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
</pre>
|
|
|
|
<pre>
|
|
<sect1 id = "section-non-interactive-commands">
|
|
<title>Non-Interactive Commands</title>
|
|
</pre>
|
|
|
|
<pre>
|
|
<para>
|
|
...
|
|
</para>
|
|
</pre>
|
|
|
|
<pre>
|
|
<sect2 id = "section-non-interactive-commands-argumentless">
|
|
<title>Argumentless Commands</title>
|
|
</pre>
|
|
|
|
<pre>
|
|
<para>
|
|
...
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
</book>
|
|
</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><book>
|
|
|
|
<pre>
|
|
I<paragraphs or chapters>
|
|
</pre>
|
|
|
|
<p></book></p>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_article"><code>article</code></a></strong><br>
|
|
</dt>
|
|
|
|
<dd><article>
|
|
|
|
<pre>
|
|
I<paragraphs or level 1 sections>
|
|
</pre>
|
|
|
|
<p></article></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><chapter id = "<em>label</em>">
|
|
|
|
<p><em>title</em></p>
|
|
|
|
<p>followed by</p>
|
|
|
|
<p><em>paragraphs or level N+1 sections</em></p>
|
|
|
|
<p></chapter></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, <xref linkend = "label"></xref>.</p>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_para"><code>para</code></a></strong><br>
|
|
</dt>
|
|
|
|
<dd><para>
|
|
|
|
<p><em>paragraph text</em></p>
|
|
|
|
<p></para></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><programlisting role = "<em>language</em>">
|
|
|
|
<p><em>program text</em></p>
|
|
|
|
<p></programlisting></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><</code>'', ``<code>></code>'', and ``<code>&</code>'' inside
|
|
of it. The several workarounds for this problem. Either you replace all
|
|
control characters with their mnemonic equivalents (``<code>&lt;</code>'',
|
|
``<code>&gt;</code>'', and ``<code>&amp;</code>'' in our example), or
|
|
you wrap the program code in a <code>CDATA</code>, like, for example,</p>
|
|
|
|
<pre>
|
|
<programlisting>
|
|
<![CDATA[
|
|
cout << "value = <" << &p << ">\n";
|
|
]]>
|
|
</programlisting>
|
|
</pre>
|
|
|
|
<p>or, if the program is stored in file <EM>my-program.pl</EM>, pull in
|
|
the whole file with</p>
|
|
|
|
<pre>
|
|
<programlisting>
|
|
<inlinemediaobject>
|
|
<imageobject>
|
|
<imagedata format = "linespecific"
|
|
fileref = "my-program.pl"></imagedata>
|
|
</imageobject>
|
|
</inlinemediaobject>
|
|
</programlisting>
|
|
</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><itemizedlist></p>
|
|
|
|
<p> <listitem></p>
|
|
|
|
<p> <em>first item</em></p>
|
|
|
|
<p> </listitem></p>
|
|
|
|
<p> <listitem></p>
|
|
|
|
<p> <em>second item</em></p>
|
|
|
|
<p> </listitem></p>
|
|
|
|
<p> ...</p>
|
|
|
|
<p></itemizedlist></p>
|
|
</li>
|
|
|
|
<li>Enumerated List
|
|
|
|
<p><enumeratedlist></p>
|
|
|
|
<p> <listitem></p>
|
|
|
|
<p> <em>first item</em></p>
|
|
|
|
<p> </listitem></p>
|
|
|
|
<p> <listitem></p>
|
|
|
|
<p> <em>second item</em></p>
|
|
|
|
<p> </listitem></p>
|
|
|
|
<p> ...</p>
|
|
|
|
<p></enumeratedlist></p>
|
|
</li>
|
|
|
|
<li>Description List
|
|
|
|
<p><variablelist></p>
|
|
|
|
<p> <varlistentry></p>
|
|
|
|
<p> <term><em>first
|
|
term</em></term></p>
|
|
|
|
<p> <listitem></p>
|
|
|
|
<p>
|
|
<em>
|
|
first definition</em></p>
|
|
|
|
<p> </listitem></p>
|
|
|
|
<p> </varlistentry></p>
|
|
|
|
<p> <varlistentry></p>
|
|
|
|
<p> <term><em>second
|
|
term</em></term></p>
|
|
|
|
<p> <listitem></p>
|
|
|
|
<p>
|
|
<em>
|
|
second definition</em></p>
|
|
|
|
<p> </listitem></p>
|
|
|
|
<p> </varlistentry></p>
|
|
|
|
<p> ...</p>
|
|
|
|
<p></variablelist></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><emphasis><em>text to be emphasized</em></emphasis>
|
|
|
|
<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><filename><em>filename or directory name</em></filename>
|
|
|
|
<p>Mark word as filename.</p>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_literal"><code>literal</code></a></strong><br>
|
|
</dt>
|
|
|
|
<dd><literal><em>literal something</em></literal>
|
|
|
|
<p><literal role = "<em>classification</em>"><em>literal
|
|
something</em></literal></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><replaceable><em>placeholder name</em></replaceable>
|
|
|
|
<p>Mark a meta-variable.</p>
|
|
</dd>
|
|
|
|
<dt><strong><a name="item_title"><code>title</code></a></strong><br>
|
|
</dt>
|
|
|
|
<dd><title><em>title</em></title>
|
|
|
|
<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><link linkend = "<em>target</em>"><em>item</em></link>
|
|
|
|
<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><ulink url = "<em>complete URL</em>"><em>item</em></ulink>
|
|
|
|
<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><xref linkend = "<em>target</em>"></xref>
|
|
|
|
<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 & Associates, first edition, ISBN: 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 © 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 ============================================================-->
|