4.4. Writing with DocBook elements

An editor capable of inserting elements according to the DTD will help a lot since it will enforce the DTD. This way you can be sure that no invalid elements were added anywhere in your document.

In order to ensure that future changes are as easy as possible, authors should try to keep compatibility with the XML version of the DocBook DTD. This means keeping element names in upper case, using double quotes in all attributes, not using "markup minimizations" (explained below), and not omitting end tags. Most tools that automatically insert elements (like psgml+emacs) follow these rules automatically or with some fine tuning.

There are several forms of markup minimization. These include empty tags. One example of tag minimization is that instead of typing the end tag you simply type </>. Another example, as said before, is ommiting tags. You can see both examples below:


<para>I'm using <emphasis>here</>, normal text here, 
and <>here</> I emphasized the text again, with empty tags.</para>

Each type of document created has a specific structure, and examples of documents can found later in this document. (see Section 4.11).

Considering the explanation above we can proceed to instructions on how to write a document using DocBook.

4.4.1. Useful commands

Table 4-1 shows some commands that are useful for generating generic documents. Remember that some elements are valid only on some contexts.

Tip

Sometimes the appearance of a particular tag changes from one format to another. As a beginner in DocBook writing, you may wish to see how your document looks in several formats before you publish them.

Note

Since the formatting depends on the output style chosen, it's recommended to use as much markup as possible. Even if the appearance of the output doesn't seem to change with the standard output style, there may be specific output formats that will make these tags stand out.

Table 4-1. Useful commands

Description Command Result
E-mail address <email>address@domain</email>
About the author <author>...</author> (see example below)
Author's name

<firstname>Mary</firstname>
<othername>Margaret</othername>
<surname>O'Hara</surname>
              
Mary Margaret O'Hara
Keys' name (printings on the keyboard) <keycap>F1</keycap> F1
Symbol represented by the keys <keysym>KEY_F1</keysym> KEY_F1
Key's code <keycode>0x3B</keycode> 0x3B
Combinations or sequences of keys

<keycombo>
   <keycap>Ctrl</keycap>
   <keycap>S</keycap>
</keycombo>
              
Ctrl-S
Program Menus <guimenu>File</guimenu> File
Menu Items <guimenuitem>Save</guimenuitem> Save
Menu Sequences

<menuchoice>
   <shortcut>
      <keycombo>
         <keycap>Ctrl</keycap>
         <keycap>S</keycap>
      </keycombo>
   </shortcut>
   <guimenu>File</guimenu>
   <guimenuitem>Save</guimenuitem>
</menuchoice>
              
File->Save (Ctrl-S)
Mouse Button <mousebutton>left</mousebutton> left
Command Names <command>command</command> command
Application Names <application>application</application> application
Text Bibliographical Reference <citation>reference</citation> [reference]
Quote

<blockquote>
   <attribution>Text Author</attribution>
   <para>Quote Text.</para>
</blockquote>
              

 

Quote Text.

 
--Text Author  

Index (NA) See Section 4.5.
File Names

<filename>file</filename>
file
Directories

<filename id="directory">directory</filename>
directory/
Emphasize Text[a]

<emphasis>text</emphasis>
text
Footnotes

<footnote>
   <para>Footnote text</para>
</footnote>
(See note at the end of this table for an example)
URLs

<ulink url="http://www.conectiva.com>Conectiva S.A.</>
Conectiva S.A.
Itemizeda (unnumberd) List

<itemizedlist>
   <listitem>
      <para>item</para>
   </listitem>
   <listitem>
      <para>item</para>
   </listitem>
</itemizedlist>

  • item

  • item

Ordered (numbered) List

<orderedlist>
   <listitem>
      <para>item</para>
   </listitem>
   <listitem>
      <para>item</para>
   </listitem>
</orderedlist>

  1. item

  2. item

Segmented List

<segmentedlist>
   <title>Binary to decimal conversion</title>
   <segtitle>Binary</segtitle>
   <segtitle>Decimal</segtitle>
   </seglistitem><seg>00</seg><seg>0</seg>
   </seglistitem>
   <seglistitem><seg>01</seg><seg>1</seg>
   </seglistitem>
   <seglistitem><seg>10</seg><seg>2</seg>
   </seglistitem>
</segmentedlist>

Binary to Decimal Conversion

Binary: 00

Decimal: 0

Binary: 01

Decimal: 1

Binary: 10

Decimal: 2

Variable List

<variablelist>
   <varlistentry>
      <term>Entry 1</term>
      <listitem>
         <para>Description</para>
      </listitem>
   </varlistentry>
   <varlistentry>
      <term>Entry 2</term>
      <listitem>
         <para>Description</para>
      </listitem>
   </varlistentry>
</variablelist>

Entry 1

Description

Entry 2

Description

Simple Lists

<simplelist type="horiz" columns="3">
   <member>1</member>
   <member>2</member>
   <member>3</member>
   <member>4</member>
   <member>5</member>
   <member>6</member>
</simplelist>
<simplelist type="inline">
   <member>A</member>
   <member>B</member>
   <member>C</member>
   <member>D</member>
   <member>E</member>
   <member>F</member>
</simplelist>

1 2 3
4 5 6

A, B, C, D, E, F
Pictures (NA) See Section 4.6
Table (NA) See Section 4.7
Programs List (NA) See Section 4.8
Glossary

<glossentry>
   <glossterm>Term</glossterm>
   <glossdef>
      <para>Definition</para>
   </glossdef>
</glossentry>
(See the glossary at the end of this document)
Crossed References

<section id="secao">
...
</section>
<section id="reference the other section">
...
<para>Please, see<xref linkend="secao"> for more information.
(NA)
Notes:
a. Text can be enphasized in a few ways. The most common ways are italics and bold. DocBook, however, supports only italics. The use of bold requires additional settings on the stylesheet used.