6. Writing with DocBook elements

An editor capable of inserting an element according with DTD analisys helps a lot since it can allow or not the element to be used at the position where the cursor is in. This way you can be sure that no invalid element was added anywhere in your document.

In order to ensure future changes are as easy as possible, authors should try to keep as much compatibility as possible with theXML 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 example of documents can found afterwards on this document. (see Section 12).

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

6.1. Useful commands

The Table 1 shows some commands which are useful to generate generic documents. Remember that some elements are valide 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 ay 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 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>First_Name</firstname>
    <othername>Middle_Name</othername>
    <surname>Surname</surname>
                 
First Name Middle Name Surname
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
Programs Menu <guimenu>File</guimenu> File
Menu Items <guimenuitem>Salvar</guimenuitem> Save
Menu Sequences
    <menuchoice>
       <shortcut>
          <keycombo>
             <keycap>Ctrl</keycap>
             <keycap>S</keycap>
          </keycombo>
       </shortcut>
       <guimenu>Arquivo</guimenu>
       <guimenuitem>Salvar</guimenuitem>
    </menuchoice>
                 
File->Save (Ctrl-S)
Mouse Button <mousebutton>left</mousebutton> left
Command Names <command>comando</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 7.
File Names
    <filename>file</filename>
file
Directories
    <filename id="directory">directory</filename>
directory/
Emphasize Text[a]
    <emphasis>text</emphasis>
text
Footnotes
    <footnote>
       <to>Footnote text</to>
    </footnote>
(See note at the end of this table)
URLs
    <ulink url="http://www.conectiva.com>Conectiva S.A.</>
Conectiva S.A.
Markups List
    <itemizedlist>
       <listitem>
          <to>item</to>
       </listitem>
       <listitem>
          <to>item</to>
       </listitem>
    </itemizedlist>
  • item

  • item

Numbered List
    <orderedlist>
       <listitem>
          <to>item</to>
       </listitem>
       <listitem>
          <to>item</to>
       </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>
    </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>
             <to>Description</to>
          </listitem>
       </varlistentry>
       <varlistentry>
          <term>Entry 2</term>
          <listitem>
             <to>Description</to>
          </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 8
Table (NA) See Section 9
Programs List (NA) See Section 10
Glossary
    <glossentry>
       <glossterm>Term</glossterm>
       <glossdef>
          <to>Definition</to>
       </glossdef>
    </glossentry>
(See the glossary at the end of this document)
Crossed References
    <section id="secao">
    ...
    </section>
    <section id="reference the other section">
    ...
    <to>Please, see<xref linkend="secao"> for more information.
(NA)
Notes:
a. The 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.