An itemizedlist is used to enumerate items whose order is not (very) important:

<itemizedlist spacing="compact">
  <listitem><para>Oranges are juicy</para></listitem>
  <listitem><para>Apples are supposed to be healthy</para></listitem>
  <listitem><para>Most people find lemons way too sour</para>
    </listitem>
</itemizedlist>

The items in the list are generally marked with a bullet in the rendered output docs:

If you leave out the spacing attribute, it will default to normal, which means that vertical whitespace (usually one line's height) will be inserted between the listitems.

Use an orderedlist when you want to stress the order of the entries:

<orderedlist spacing="compact" numeration="loweralpha">
  <listitem><para>Sumerians 3300 BC – 1900 BC</para></listitem>
  <listitem><para>Assyrian Empire 1350 BC – 612 BC</para></listitem>
  <listitem><para>Persian Empire 6th century BC – 330 BC</para>
  </listitem>
</orderedlist>

By default, arabic numerals (1, 2, 3, ...) will be placed before the items, but you can change this with the numeration attribute. Output:

A procedure is often rendered like an orderedlist, but the semantics are different: a procedure denotes a sequence of steps to be performed in a given order:

<procedure>
  <step><para>Pick the lock</para></step>
  <step><para>Rob the house</para></step>
  <step><para>Get arrested</para></step>
</orderedlist>

Here's how the above example is rendered:

Within a step you can include a substeps element, which in turn contains more steps.

A variablelist is made up of varlistentrys, each of which contains a term followed by a listitem:

<variablelist>
  <varlistentry>
    <term>Tag</term>
    <listitem>
      <para>A piece of text enclosed in angle brackets</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>Element</term>
    <listitem>
      <para>A start tag, a matching end tag, and everything in 
        between</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>Content of an element</term>
    <listitem>
      <para>Everything between the matching tags</para>
    </listitem>
  </varlistentry>
</variablelist>

The list you are reading right now, enumerating the different types of lists, is a variablelist with the element names (itemizedlist, orderedlist, etc.) as terms. The next section – Links – also consists of one introductory sentence followed by a variablelist.

link is the generic element to point to another location in the document or set. The linkend attribute must always be present; its value should be the id of the element you link to (the link target).

Click <link linkend="docwritehowto-introduction">here</link> to jump
to the introduction.

In the rendered document, the word “here” will be hot text, that is: a clickable link pointing to the introduction:

Use a ulink to link to an Internet resource. The url attribute is mandatory:

Click <ulink url="http://docbook.org/tdg/en/">this link</ulink> to
read The Definitive Guide on DocBook.

The words “this link” will rendered as a hyperlink to http://docbook.org/tdg/en/, like this:

You can make an email link with a ulink, but it's easier to use the email element. This will show the email address as a clickable link in the output. This piece of XML:

Send mail to 
<email>[email protected]</email> to 
subscribe.

results in the following output:

If you want the hot text to be different from the email address itself, use a ulink with a mailto: URL.

An anchor is an empty element marking an exact spot in the document. It doesn't show up in the text that your readers see, but it can be used as a link target. This is useful if you want to link to a place somewhere in the middle of a long paragraph:

<para id="lost-at-sea">
  Blah blah blah...
  and some more...
  and then some...
  Now here's an interesting place in the paragraph I want to be able
  to link to:
  <anchor id="captain-haddock"/>There it is!
  Paragraph drones on...
  and on...
  and on...
</para>

Having placed the anchor, you can create a link to it:

<link linkend="captain-haddock">Go to the interesting spot</link> in
that long, long paragraph.

If your link targets a short element, or the beginning of an element, it's easier to give the target element an id and use that as linkend.

If you include code fragments in your doc, put them in a programlisting element. Everything you type within a programlisting will be rendered verbatim, including line breaks, spaces etc. Also, a fixed-width font will be used in the rendered documents. The term “program listing” is to be interpreted loosely here: you should also use this element for SQL fragments and DocBook XML examples. This guide – and especially the section about elements, which you are reading now – is littered with programlistings, so you already know what they look like:

Programlistings are rendered like this.

Use a screen element to show what a user sees or might see on a computer screen in text mode, or in a terminal window. Here too, your layout will be preserved and a fixed-width font used, but the semantics are different. It may or may not look different from a programlisting in the output. Here's a short example, showing what happens if you try to build a non-existing target in the manual tree:

<screen>
D:\Firebird\manual_incl_howto\src\build>build ugh
java version "1.4.2_01"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_01-b06)
Java HotSpot(TM) Client VM (build 1.4.2_01-b06, mixed mode)

Buildfile: build.xml

BUILD FAILED
Target `ugh' does not exist in this project.
</screen>

And this is how it's rendered:

D:\Firebird\manual_incl_howto\src\build>build ugh
java version "1.4.2_01"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_01-b06)
Java HotSpot(TM) Client VM (build 1.4.2_01-b06, mixed mode)

Buildfile: build.xml

BUILD FAILED
Target `ugh' does not exist in this project.

literallayout, like screen and programlisting, keeps your layout intact, but it usually doesn't change the font – unless you set the class attribute to monospaced. It's also more general than the previous two in the sense that there's no meaning attached to its content: you can put any kind of text here of which you want to preserve the layout.

Example source:

<literallayout>
The Sick Rose

Oh Rose, thou art sick!
The invisible worm
That flies in the night,
In the howling storm,

Has found out thy bed
Of crimson joy,
And his dark secret love
Doth thy life destroy.

  — William Blake
</literallayout>

Output:

An example is a formal example with a title. It is usually given an id so it can be referred to from other places in the document. An index of examples is built automatically when the document is rendered. You'll often find programlisting's in an example, but it may also contain screen's, para's, lists, etc.

Here's an example of an example:

<example id="docwritehowto-sql-example">
  <title>An SQL example</title>
  <para>With this command you can list all the records in the COUNTRY 
    table:</para>
  <programlisting>SELECT * FROM COUNTRY;</programlisting>
</example>

In the output this will look like:

If you want an example without a mandatory title, use an informalexample. Informal examples are also left out of the examples index.

A bridgehead is a free-floating title between paragraphs, not associated with the start of a chapter or section. The renderas attribute determines how it will be rendered.

<para>You may remember that Mr. Hardy started with this firm as
  elevator boy and with grim determination worked his way up to
  the top. And after the wedding today he becomes General Manager
  of this vast organisation.</para>

<bridgehead renderas="sect5">Mr. Laurel's comments</bridgehead>

<para>We also spoke to his lifetime friend and companion Mr. Laurel.
  Mr. Laurel says that after viewing the situation from all sides,
  he is thoroughly reconciled to the fact that the moving picture
  industry is still in its infancy. Mr. Laurel also states that
  technology, whilst it may appear to be the center of all—</para>

The above source is rendered as:

You are free in your choice of renderas level, but the logical choice would normally be the current section level plus (at least) one.

A formalpara is a paragraph with a title. Our stylesheets render the title as a run-in head.

<formalpara>
  <title>Motherly love:</title>
  <para>This is the love your mother has for you, not to be
    confused with brotherly or otherly love.</para>
</formalpara>

In the output this looks like:

A period will be appended to the title, unless it already ends with a punctuation character.

Use the filename tag to mark file names in the broadest sense. Attributes can optionally indicate that the file is a header file, a directory, etc.

Place your doc in the <filename
class="directory">src/docs/firebirddocs</filename> subdirectory.

The output reads:

command and application are both used for executable programs. command is usually chosen for smaller programs and internal commands; its content should be the exact command as given on a command line; application is generally used for bigger programs and need not be the name of the executable file. Both can refer to the same program:

Type <command>netscape&amp;</command> in a terminal window to start 
<application>Netscape Navigator</application>.

This is rendered as:

envar denotes an environment variable.

These two do the expected thing:

After inventing the formula e = mc<superscript>2</superscript>, I 
really felt like a glass of liquid H<subscript>2</subscript>O !

Output: After inventing the formula e = mc², I really felt like a glass of liquid H₂O !

The use of varname and constant should be obvious. The <database> tag is not only meant for databases, but also for database objects:

The <database class="table">COUNTRY</database> table has two fields:
<database class="field">COUNTRY</database> and
<database class="field">CURRENCY</database>.

Output: The COUNTRY table has two fields: COUNTRY and CURRENCY.

These three speak for themselves, I trust.

The <function>log</function> function takes parameters
<parameter>a</parameter> and <parameter>b</parameter>.

Output: The log function takes parameters a and b.

prompt is used for a string inciting the user to enter some text; userinput refers to text entered by the user (not necessarily at a prompt!); computeroutput is text displayed by the computer:

Type <userinput>guest</userinput> at the <prompt>login:</prompt>
prompt and the server will greet you with a <computeroutput>Welcome,
guest user</computeroutput>.

Output: Type guest at the login: prompt and the server will greet you with a Welcome, guest user.

The text on a keyboard key, or its common name:

Hit the <keycap>Del</keycap> key to erase the message, or
<keycap>SPACE</keycap> to move on.

Output: Hit the Del key to erase the message, or SPACE to move on.

This element is used extensively throughout this guide: it marks SGML and XML tags, elements, attributes, entities etc.:

If it concerns a directory, set the 
<sgmltag class="attribute">class</sgmltag> attribute of the 
<sgmltag class="element">filename</sgmltag> element to
<sgmltag class="attvalue">directory</sgmltag>.

Output: If it concerns a directory, set the class attribute of the filename element to directory.

Other possible values for sgmltag.class are: starttag, endtag, emptytag, and genentity (for an entity).

Use emphasis to stress words in general, citetitle for book titles etc., and firstterm if you introduce a new word or concept to your readers:

We use <firstterm>DocBook XML</firstterm> for our Firebird 
documentation. A short introduction follows;
<emphasis>please</emphasis> read it carefully! If you want to know
more about the subject, buy <citetitle>DocBook – The Definitive 
Guide</citetitle>.

Output: We use DocBook XML for our Firebird documentation. A short introduction follows; please read it carefully! If you want to know more about the subject, buy DocBook – The Definitive Guide.

Use quote for an inline quotation (as opposed to a blockquote). Quotation marks will be inserted automatically. Using quote instead of typing the quote characters yourself (which is also perfectly legal) has the advantage that we can alter the type of quotation marks through stylesheets if we want to. Also, quotes differ per language:

<para>An <quote lang="en">English quote</quote>
  and a <quote lang="fr">French quote</quote>.</para>

Output: An “English quote” and a « French quote ».

Please note that you shouldn't use the lang attribute on quotes in your own docs. Your root element's lang attribute will ensure that the right type of quotes are used. If someone translates your document – and changes the root lang attrib – it will be rendered with the quotation marks for the target language. Of course I had to use the attribute here to show the difference, and to make sure that the different quotation marks survived any translation.

A literal is a word or text fragment to be taken literally. It is a rather general element, often used to make certain words stand out typographically:

At all costs avoid using the word <literal>humongous</literal> in
your documentation.

Output: At all costs avoid using the word humongous in your documentation.