The top-level element of a book body must be <chapter>; it may contain one or more <sect1>, each of them may contain <sect2> and so on up to <sect5>. The top-level element of an article body is always <sect1>. Regardless of which elements you use, give each structural element an unique id, so that you can link to it. For usage example, see the template.

Please try to avoid using deeply nested sections; for most situations, <sect1> and <sect2> should be sufficient. If not, you probably should split your <sect1> into several smaller ones.

Use the tag <para> for paragraphs, even if there is only one paragraph in a section—see template for examples.

For notes, tips, warnings, and important information, which should be set apart from the main text (usually as a paragraph with some warning sign on the margin), use tags <note>, <tip>, <warning>, <important> respectively. For example:

<tip>
 <title>Optimization Tip</title>
 <para>
  To speed up program compilation, use <application>gcc</application>
  compiler with Pentium optimization.
 </para>
</tip> 

	Optimization Tip
	To speed up program compilation, use gcc compiler with Pentium optimization.

Note that the <tip> tag should not be inside a <para> tag but between paragraphs.

To include screenshots and other figures, use the following tags:

<figure id="shot1">
 <title>Screenshot</title>
 <screenshot>
  <mediaobject>
   <imageobject>
    <imagedata fileref="figures/example_screenshot" format="PNG"/>
   </imageobject>
   <textobject>
     <phrase>Shows the application screenshot with several buttons.</phrase>
   </textobject>
   <caption>
    <para>Screenshot of a program</para>
   </caption>
  </mediaobject>
 </screenshot>
</figure>
          

Figure 1. Screenshot

Screenshot of a program

	Note
	Notice in this example that the screenshot file name does not include the file type extension — to find out why, please read Screenshots in DocBook.

To show a file fragment—for example, program listing—use <programlisting> tag:

<programlisting>
[Desktop Entry] 
Name=Gnumeric spreadsheet
Exec=gnumeric 
Icon=gnome-gnumeric.png 
Terminal=0
Type=Application
</programlisting>
          

[Desktop Entry] 
Name=Gnumeric spreadsheet 
Exec=gnumeric
Icon=gnome-gnumeric.png 
Terminal=0 
Type=Application
          

To show a record of terminal session—i.e., sequence of commands entered at the command line—use <screen> tag:

<screen>
<prompt>bash$</prompt><userinput>make love</userinput> 
make: *** No rule to make target `love'. Stop.
</screen>
          

bash$make love  
make: *** No rule to make target `love'.  Stop.
          

	Note
	Note that both <programlisting> and <screen> preserve linebreaks, but interpret XML tags (unlike LaTeX verbatim environment). Take a look at the source of this document to see how you can have XML tags literally shown but not interpreted,

The most common list types in DocBook are <itemizedlist>, <orderedlist>, and <variablelist>.

Lists can be nested; in this case, the stylesheets are smart enough to change the numeration (for <orderedlist>) or marks of each entry (in <itemizedlist>) for sub-lists

If you need to refer to a sequence of menu choices, such as Main Menu->Utilities->GNOME terminal there is a special construction for this, too:

<menuchoice>
 <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
 <guimenuitem>GNOME terminal</guimenuitem> </menuchoice>
          

To refer to another place in the same document, you can use tags <xref> and <link>. The first of them automatically inserts the full name of the element you refer to (section, figure, etc.), while the second just creates a link (in HTML output). Here is an example:

An example of a <link linkend="extip">tip</link> was given in
<xref linkend="notes" />.  
          

Here notes is the id attribute of Notes, Warnings, and Tips and extip is the id attribute of the section about tips.

To produce a link to an external source, such as a Web page or a local file, use the <ulink> tag, for example:

 To find more about GNOME, please visit the <ulink type="http"
url="http://www.gnome.org">GNOME Web Site</ulink> 
          

Here are some tags used to describe operating system-related things:

To mark up text input by the user, use <userinput>.

To mark keystrokes such as shortcuts and other commands, use <keycap>. This is used for marking up what is printed on the top of the physical key on the keyboard. There are a couple of other tags for keys, too: <keysym> and <keycode>. However you are unlikely to need these for most documentation. For reference, <keysym> is for the “symbolic name” of a key. <keycode> is for the “scan code” of a key. These are not terms commonly required in GNOME documentation, although <keysym> is useful for marking up control codes.

To mark up a combination of keystrokes, use the <keycombo> wrapper:

<keycombo>
 <keycap>Ctrl</keycap>
 <keycap>Alt</keycap>
 <keycap>F1</keycap>
</keycombo>
          

Finally, if you want to show a shortcut for some menu command, here are the appropriate tags (rather long):

<menuchoice>
 <shortcut>
  <keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo>
 </shortcut> 
 <guimenuitem> Quit</guimenuitem> 
</menuchoice>
          

To mark up e-mail address, use <email>:

 The easiest way to get in touch with me is by e-mail
(<email>me@mydomain.com</email>)
          

DocBook also provides special means for entering typographic symbols which can not be entered directly form the keyboard (such as copyright sign). This is done using character entities, which ii the XML analogue of macros, or commands, of LaTeX. They generally have the form &entityname;. Note that the semicolon is required.

here is partial list of most commonly used enitites:

Note that the actual look of the resulting symbols depends on the fonts used by your browser; for example, it might happen that long dash (&mdash;) looks exactly like the usual dash (-). However, in the PostScript (and thus, in print) the output will look markedly better if you use appropriate tags.