Notes on docBook

Table of Contents
Introduction
Hello World
Important Tags
Examples

Introduction

DocBook is an XML text markup language similar to html or LaTeX, but which is much more rigorous about only marking up content types, never formating or style. The Linux kernel documentation, the Linux Documentation Project (see the LDP Author Guide), the online GNOME documentation (see the GNOME Handbook of Writing Software Documentation) and KDE documentation (see the KDE Documentation Primer ) are all written in docBook.

Several tutorials are available; most are listed on the DocBook wiki tutorials page.

Tools exist to convert docBook to many formats, including html, pdf, UNIX man pages, LaTeX, RTF, Microsoft Help pages, KDE help pages, and Gnome help pages. In addition to conversion to a very plain html page (the default), one can also convert to a web site with navigation panel and similar conveniences.

Note also that sometimes programming API documentation can be generated automatically, for example from javadocs using dbdoclet.

There are two good books on docBook, and the full text of both are available on line. One is Walsh and Muellner's DocBook: The Definitive Guide, which covers how to write docBook and the details of all the tags. The other is Stayton's DocBook XSL: The Complete Guide, which covers how to do stuff with docBook (like turn it in to web pages, etc.)

There are many tags, most of which you probably don't need, although they don't hurt any. If one of the supported help systems or program documentation systems formats a type of content in a specific way, there is usually a tag for it. If you don't need your document to format that type of content differently, you probably don't need the tag.

There are many tags that you will want to use, though. Lists and tables are similar to their html counterparts. Rugge, Galassi, and Bischoff's Writing Documentation Using DocBook: A Crash Course does a good job of covering important tags. A number of tags exist to support creation of UNIX man pages, which we will want to use when that is one of the formats we want to generate.

Hello World

This is what an extremely basic docBook document looks like:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                         "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<article>

<section><title>A Simple Example</title>

<para>Hello world.</para>
<para>Hello alternate world, too.</para>

</section>

</article>

You can turn it into html like this:

bash$ xsltproc --xinclude \
> /usr/share/sgml/docbook/xsl-stylesheets/xhtml/docbook.xsl \
> helloWorld.xml > helloWorld.html

You can turn it into pdf by first converting it into an fo, and then do a pdf, like this:

bash$ xsltproc --xinclude \
> /usr/share/sgml/docbook/xsl-stylesheets/fo/docbook.xsl \
> helloWorld.xml > helloWorld.fo
bash$ pdfxmltex helloWorld.fo
bash$ acroread helloWorld.pdf

There are several tools for converting fo files to pdf files, all of which have some problems. If you can't get pdfxmltex to do what you want, you might want to try fop.

A Makefile can be nice if you have lots of files, or want to process them to different sorts of targets:

XHTMLSTYLE=/usr/share/sgml/docbook/xsl-stylesheets/xhtml/docbook.xsl

helloWorld.html: helloWorld.xml 
	xsltproc --xinclude ${XHTMLSTYLE} helloWorld.xml > helloWorld.html

There is an older, DSSSL based set of tools for processing docbook as well. It formats to more output formats, and is sometimes faster and producese nicer output, particularly on paper. It isn't maintained any more, though. You can use it like this:

bash$ xmllint --xinclude helloWorld.xml > helloWorld-full.xml
bash$ sed -i 's/xml:base=".*"//g' helloWorld-full.xml
bash$ docbook2pdf helloWorld-full.xml
Using catalogs: /etc/sgml/xml-docbook-4.1.2-1.0-17.2.cat
Using stylesheet: /usr/share/sgml/docbook/utils-0.6.13/docbook-utils.dsl#print
Working on: /home/neilsen/linuxAdminDocs/docbook-tutorial/example/helloWorld-full.xml
Done.
bash$ xpdf helloWorld-full.pdf

Note that the DSSSL tools cannot handle xml includes, so you need to use xmllint to generate a file with all the includes incorportated.

Important Tags

You often want to include text verbatim. There are two tags that do this: "programlisting" and "screen". For most styles, the output is the same. Use "programlisting" if you are showing the content of a file, and "screen" if a screen capture of a terminal:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                         "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<article>

<para>
<screen>
bash$ echo boo
boo
</screen>
</para>

</section>

</article>

Sometimes, your screen capture or program listing will include characters that the docbook processor will mistake for XML tags. There are two ways to deal with this. One is with CDATA blocks:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                         "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<article>

<para>
<programlisting><![CDATA[
if (foo < bar) {
  printf("Foo too big!\n");
}
]]></programlisting>
</para>

</article>

You can also include the program from an external text file:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                         "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<article>

<para>
<programlisting>
<xi:include 
  xmlns:xi="http://www.w3.org/2001/XInclude" 
  parse="text" href="hello.c" />
</programlisting>
</para>

</article>

By setting the "parse" attribute to text, you prevent the xml processor from processing it.

If you do not use the "parse" attribute, you can use includes to split you documentation into many files:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                         "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<article>

<xi:include 
   xmlns:xi="http://www.w3.org/2001/XInclude"
   href="firstSection.xml" />.
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
   href="secondSection.xml" />.
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
   href="thirdSection.xml" />.

</article>

Another thing you will probably want to do is show images. This example shows how:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                         "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<section><title>Here is how to show an image</title>

<para>The simple way is just to use the graphic tag:
<graphic fileref="figure.jpeg"/>
Sometimes, this won't work. The graphic tag is depricated,
and the standard says the graphic tag needs to be inside
a figure.
</para>

<para>To be more correct, use a figure:
<figure><title>This is my figure</title>
<mediaobject><imageobject>
<imagedata fileref="figure.jpeg"/>
</imageobject></mediaobject>
</figure></para>
</section>

Examples

Adding a procedure

The most common (and perhaps most useful) type of content that I write is the procedures, which is a task of moderate complexity in docBook.

I begin by doing whatever it is I want to document, recording all of the interaction in the terminal or with script. If I were documenting something where graphics were important, I would perform some screen captures as well:

bash$ script sampleCapturedScreen.txt
Script started, file is sampleCapturedScreen.txt
bash$ xclock &
[1] 20242
bash$  xwd | xwdtopnm | pnmtojpeg > xclockImage.jpeg
xwdtopnm: writing PPM file
bash$ exit
Script done, file is sampleCapturedScreen.txt
bash$

I then start with the basic outline of procedure file:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE procedure PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                         "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<procedure><title id=""></title>

<para></para>

<step><para>
<screen><![CDATA[
]]></screen>
</para></step>

</procedure>

and fill in a title, id, and introduction:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE procedure PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                         "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<procedure><title id="xclock">Capturing a Clock</title>

<para>Here is how to screen capture xclock</para>

<step><para>
<screen><![CDATA[
]]></screen>
</para></step>

</procedure>

I then make as many copies of the step tag as necessary, and cut and paste important bits of the screen output into tho screen sections and add commentary:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE procedure PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                         "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<procedure><title id="startXclock">Starting xclock</title>

<para>Here is how to start xclock.</para>

<step><para>Start xclock and put it in the background:
<screen><![CDATA[
bash$ xclock &
[1] 20595
bash$
]]></screen>
</para></step>

<step><para>Capture the clock and put it in a eps file:
<screen><![CDATA[
bash$ xwd | xwdtopnm | pnmtops > xclockImage.eps
xwdtopnm: writing PPM file
pnmtops: writing color PostScript...
bash$
]]></screen>
</para></step>

</procedure>

Now you can process it and look at it:

bash$ docbook2pdf xclock.xml
Using catalogs: /etc/sgml/xml-docbook-4.1.2-1.0-17.2.cat
Using stylesheet: /usr/share/sgml/docbook/utils-0.6.13/docbook-utils.dsl#print
Working on: /home/neilsen/linuxAdminDocs/docbook-tutorial/example/xclock.xml
Done.
bash$ acroread xclock.pdf

You probably also want to use xinclude to incorporate it in to the larger documentation.

Sadly, of docbook2pdf cannot process the xincludes itself, so you may need to do this:

bash$ xmllint --xinclude fileWithIncludes.xml > fileWithoutIncludes.xml
bash$ docbook2pdf fileWithoutIncludes.xml

Here, xmllint generates a file with all the included text pulled in.

Creating a FAQ

Another common type is the FAQ.

Again I start with a basic template:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE qandaset PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                         "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<qandaset defaultlabel="qanda">
<title>Sample FAQ</title>

<qandaentry>
<question>
<para>What is this?</para>
</question>
<answer>
<para>This is the FAQ.</para>
</answer>
</qandaentry>

</qandaset>

I then add the content. Again, you can use xincludes to incorporate other docbook files:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE qandaset PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                         "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<qandaset defaultlabel="qanda">
<title>Sample FAQ</title>

<qandaentry>
<question>
<para>How do I start xclock?</para>
</question>

<answer>
<xi:include
  xmlns:xi="http://www.w3.org/2001/XInclude"
  href="procedureFilledTemplate.xml" />
</answer>
</qandaentry>

</qandaset>

Creating a man page for a command

The easiest way to create a man page is to start with a template:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                         "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<!-- See http://www.docbook.org/tdg/en/html/refentry.html for more documentation -->

<refentry id="commands.sampleCommand">

<refmeta>
<refentrytitle>Sample Command</refentrytitle>
<manvolnum>1</manvolnum> <!-- 1 for commands -->
</refmeta>

<refnamediv>
<refname>doSomething</refname>
<refpurpose>Do something useful</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>/usr/bin/doSomething</command>
<arg choice="opt">
<option>ab</option>
</arg>
<arg choice="opt" rep="repeat">someFile</arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1><title>Description</title>
<para>Describe what the command does.</para>
</refsect1>

<refsect1><title>Options</title>

<variablelist>

<varlistentry>
  <term><option>-a</option></term>
  <listitem>
    <para>does thing a</para>
  </listitem>
</varlistentry>

<varlistentry>
  <term><option>-b</option></term>
  <listitem>
    <para>does thing b</para>
  </listitem>
</varlistentry>

</variablelist>

</refsect1>

<refsect1><title>Files</title>
<para>Describe the files needed, and reference the data model.</para>

<variablelist>

<varlistentry>
  <term><filename>sample.dat</filename></term>
  <listitem>
    <para>sample data is used; see <xref linkend="datamodel.sampleFormat"/>.</para>
  </listitem>
</varlistentry>

</variablelist>

</refsect1>

<refsect1><title>Environment</title>
<para>Describe environmanet variables that do stuff.</para>

<variablelist>

<varlistentry>
  <term>THING_DIR</term>
  <listitem>
    <para>sets where to look for thing</para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>OUT_DIR</term>
  <listitem>
    <para>sets where to put output</para>
  </listitem>
</varlistentry>

</variablelist>

</refsect1>

<refsect1><title>Diagnostics</title>
<para>Instructions on how to solve problems.</para>
</refsect1>

<refsect1><title>Bugs</title>
<para>Describe known bugs.</para>
</refsect1>

<refsect1><title>See also</title>
<para><simplelist type="inline">
<member><xref linkend="datamodel.sampleFormat"/></member>
<member><ulink url="http://www.docbook.org/tdg/en/html/refentry.html">DocBook Manual</ulink></member>
</simplelist></para>
</refsect1>


</refentry>

You can process this file and look at the result thus:

sdsslnx33$ xsltproc --xinclude /usr/share/sgml/docbook/xsl-stylesheets/manpages/docbook.xsl sampleCommand.xml
xref to nonexistent id datamodel.sampleFormat
xref to nonexistent id datamodel.sampleFormat
Writing doSomething.1 for refentry(commands.sampleCommand)
sdsslnx33$ groff -Tascii -man doSomething.1
SAMPLE COMMAND(1)                                            SAMPLE COMMAND(1)



NAME
       doSomething - Do something useful

SYNOPSIS
       /usr/bin/doSomething [ab] [someFile...]


DESCRIPTION
       Describe what the command does.


OPTIONS
       -a     does thing a


       -b     does thing b


FILES
       Describe the files needed, and reference the data model.


       sample.dat
              sample data is used; see .


ENVIRONMENT
       Describe environmanet variables that do stuff.


       THING_DIR
              sets where to look for thing


       OUT_DIR
              sets where to put output


DIAGNOSTICS
       Instructions on how to solve problems.


BUGS
       Describe known bugs.


SEE ALSO
       , DocBook Manual: http://www.docbook.org/tdg/en/html/refentry.html,




                                                             SAMPLE COMMAND(1)

Creating a man page for a file format

Creating a man page for a file format is much like making one for a command. Start with a template:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                         "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<!-- See http://www.docbook.org/tdg/en/html/refentry.html for more documentation -->

<refentry id="datamodel.sampleFormat">

<refmeta>
<refentrytitle>Sample Format</refentrytitle>
<manvolnum>5</manvolnum> <!-- 5 for file formats -->
</refmeta>

<refnamediv>
<refname>some data</refname>
<refpurpose>Store some information</refpurpose>
</refnamediv>

<refsynopsisdiv>
<para><filename>sample.dat</filename></para>
</refsynopsisdiv>

<refsect1><title>Description</title>
<para>This command does not exist, only the documentation.</para>
</refsect1>

<refsect1><title>Examples</title>
<para>
<screen>
#This is what a file looks like
a     b
1     1
2     3
</screen>
</para>
</refsect1>

<refsect1><title>See also</title>
<para><simplelist type="inline">
<member><xref linkend="commands.sampleCommand"/></member>
</simplelist></para>
</refsect1>

</refentry>

Processing is the same as for a command.