1. General Tips and Tricks

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

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

DescriptionSample markupResult
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>
              
FileSave (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>
  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>
123
456
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.