Appendix D. DocBook: Sample Markup

Table of Contents
General Tips and Tricks
<section> and <sectN>: what's the difference?
Command Prompts
Encoding Indexes
Inserting Pictures
Markup for Metadata
Bibliographies
Entities (shortcuts, text macros and re-usable text)
Customizing your HTML files

General Tips and Tricks

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

Useful markup

Table D-1 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>
              
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 the Section called 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 the Section called 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)
Notes:
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.