1. General Tips and Tricks

1. General Tips and Tricks
Prev	Appendix D. DocBook: Sample Markup	Next

For a general overview of what markup is all about, please read Chapter 5, Markup

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 lower case, using double quotes in all attributes, and not omitting end tags. Most tools that automatically insert elements (like psgml+emacs) follow these rules automatically or with some fine tuning.
Each type of document created has a specific structure. This document is in “book” format. Most authors, however, will want to use the shorter “article” format instead. Templates are available from Appendix A, Templates.

1.1. Useful markup

Table D.1, “Useful markup” shows some markup that is useful for generating generic documents. Remember that some elements are valid only on some contexts.

Check several formats

Sometimes the appearance of a particular tag changes from one conversion 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. You are advised to look at how your document is presented in HTML, PDF and PostScript, since these formats will be made available by TLDP once you publish your document.

Better too much than not enough

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 D.1. Useful markup

Description Sample markup 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

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, “Encoding Indexes”.

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.

Itemized (unnumbered) 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 5, “Inserting Pictures”

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)

^[a]Text can be emphasized 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 style sheet used.