LDP Author Guide
Prev	Chapter 4. Using DocBook Tags	Next

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.

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.

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> <address@domain>

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>

item
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.

Prev	Home	Next
Creating and modifying catalogues	Up	Encoding Indexes