Tips and Tricks with DocBook

Including Images

If you plan on including images in your HOWTOs, you can now do this, as LinuxDoc didn't support images. Here's a sample way of including an image in your HOWTOS:

<figure>
<title>LyX screen shot</title>
<mediaobject>
<imageobject><imagedata fileref="lyx_screenshot.eps" format="eps"></imageobject>
<imageobject><imagedata fileref="lyx_screenshot.jpg" format="jpg"></imageobject>
<textobject><phrase>Screen shot of the LyX document processing program</phrase></textobject>
</mediaobject>
</figure>

This is a better way than using <graphic> for two reasons. First, <graphic> will be removed in DocBook 5.0 in favor of the <mediaobject> tag. So you may as well get started with the right way now. Second, <mediaobject> allows for different kinds of media based on what the output is. In this example, the first <imageobject> is an encapsulated PostScript(eps) file for use with formats derived from TeX such as DVI, PS, and PDF. The second <imageobject> is a JPEG image for visual display, mostly for HTML output. The <textobject> is presented if the output doesn't support graphics (TXT). Think of it as an <alt> tag.

Naming separate HTML files

By default, when separate HTML files are made, the SGML processor will assign arbitrary names to the resulting files. This can be confusing to readers who may bookmark a page only to have it change, or so you know what files are what. Whatever your reasoning, here's how to make separate files named the way you want:

In your first <article> tag (which should be the only one) include an id parameter and call it index. This will make your tag look like this:

<article id="index">

On the first <sect1> tag, do not modify it, as it's usually an introduction and you want that on the first page. For each other <sect> tag, include the id parameter and name it. Names should include only alphanumeric characters, and it should be short enough to understand what it is.

<sect1 id="tips">

Using ldp.dsl

The LDP uses its own DSSSL file, which adds things like a white background and automatic generation of the table of contents you see at the beginning of HOWTOs. You can find the latest copy of the file at http://metalab.unc.edu/gferg/ldp/ldp.dsl.

Once you have the file, you may need to do some editing of the first few lines based on the location of your DocBook DSSSL files. My example uses the Cygnus tool set.

Place the ldp.dsl file in /usr/lib/sgml/stylesheets and bring it up under your favorite text editor.You should see something like this:

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY % html "IGNORE">
<![%html;[
<!ENTITY % print "IGNORE">
<!ENTITY docbook.dsl SYSTEM "docbook.dsl" CDATA dsssl>
]]>
<!ENTITY % print "INCLUDE">
<![%print;[
<!ENTITY docbook.dsl SYSTEM "docbook.dsl" CDATA dsssl>
]]>
]>

If you're using another DSSSL, point those two files to the location of the HTML and print DSSSL files. They're usually in directories called html and print.

With that complete, you can now generate HTML files:

bash$ mkdir HOWTO-HOWTO ; cd HOWTO-HOWTO
bash$ jade -t sgml -ihtml -d /usr/lib/sgml/stylesheets/ldp.dsl\#html ../HOWTO-HOWTO.sgml

The first command creates a new directory to put your files into. The second command (the jade one) generates individual HTML files for each section of your document. If you are going to something like RTF, you can do this:

bash$ jade -t rtf -d /usr/lib/sgml/stylesheets/ldp.dsl ../HOWTO-HOWTO.sgml