Una lista itemizedlist viene usata per elencare una serie di cose il cui ordine non è importantissimo:

<itemizedlist spacing="compact">
  <listitem><para>Le arance sono succose</para></listitem>
  <listitem><para>Le mele si dice facciano bene</para></listitem>
  <listitem><para>Molti ritengono i limoni troppo aspri</para>
    </listitem>
</itemizedlist>

Gli oggetti in lista sono generalmente evidenziati con un pallino nel documento finale:

Senza mettere l'attributo spacing, viene ritenuto normal, che significa che viene inserito uno spazio verticale (usualmente di una linea) tra ogni oggetto in lista.

Si usa una orderedlist quando si desidera evidenziare l'ordine degli elementi:

<orderedlist spacing="compact" numeration="loweralpha">
  <listitem><para>Sumeri 3300 aC – 1900 aC</para></listitem>
  <listitem><para>Impero Assiro 1350 aC – 612 aC</para></listitem>
  <listitem><para>Impero Persiano 600 aC – 330 aC</para>
  </listitem>
</orderedlist>

Per default, vengono messi numeri arabi (1, 2, 3, ...) per elencare gli oggetti, ma si può cambiare attraverso l'attributo numeration. Risultato:

Una procedure ha spesso lo stesso aspetto di una orderedlist, ma il significato è diverso: una procedura elenca una serie di passi da eseguire in un preciso ordine:

<procedure>
  <step><para>Apri la serratura</para></step>
  <step><para>Svaligia la casa</para></step>
  <step><para>Fatti arrestare</para></step>
</orderedlist>

Ecco come diventa l'esempio:

Dentro uno step si possono includere elementi substeps, che a loro volta possono avere più step.

Una variablelist è fatta di varlistentrys, ognuno dei quali contiene un term seguito da un listitem:

<variablelist>
  <varlistentry>
    <term>Marcatore</term>
    <listitem>
      <para>Un testo incluso fra parentesi angolari</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>Elemento</term>
    <listitem>
      <para>Un marcatore iniziale, un corrispondente marcatore finale,
        e tutto quel che c'è dentro</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>Contenuto di un elemento</term>
    <listitem>
      <para>Tutto quel che c'è tra due marcatori corrispondenti</para>
    </listitem>
  </varlistentry>
</variablelist>

Risultato:

Notare che questa lista, che elenca i vari tipi di liste, è anch'essa una variablelist con i nomi degli elementi (itemizedlist, orderedlist, etc.) come termini. La prossima sezione ( i Links ) consisterà di una frase iniziale seguita da una variablelist.

link è l'elemento generico per indirizzare ad un altro punto del documento o del set. L'attributo linkend deve essere sempre presente ed il suo valore deve essere l'id dell'elemento a cui ci si vuole collegare (il link target).

Cliccare <link linkend="docwritehowto-introduction-it">qui</link> per
tornare all'introduzione.

Nel documento finale, la parola «qui» sarà il punto caldo (hot text), cioè: il link cliccabile che porta alla destinazione, in questo esempio all'introduzione:

Si usa un ulink per puntare ad una risorsa Internet. L'attributo url è obbligatorio:

Cliccare <ulink url="http://docbook.org/tdg/en/">questo link</ulink>
per leggere The Definitive Guide on DocBook (in inglese).

Le parole «questo link» genereranno un hyperlink a http://docbook.org/tdg/en/, come questo:

Si può fare un link ad una posta elettronica con ulink, ma è più facile usare l'elemento email con cui l'indirizzo di email viene visualizzato come un link cliccabile. Questo frammento XML:

Inviare una mail a
<email>[email protected]</email> per 
iscriversi.

genera il seguente risultato:

Desiderando evidenziare un testo diverso da quello della email di destinazione stessa, si può usare ulink e l'attributo url col protocollo mailto://

Un anchor è un elemento vuoto che etichetta un punto esatto nel documento. Essendo completamente invisibile, non viene visto dai lettori, ma può essere utilizzato come destinazione di un link. È utile quando si vuol andare direttamente a metà o alla fine di lungo paragrafo:

<para id="naufrago">
  Bla bla bla bla...
  ed ancora bla bla bla...
  e poi bla bla bla, ma forse non vi ho detto bla bla bla...
  Ed ora un punto interessante del paragrafo a cui voglio arrivare 
  direttamente:
  <anchor id="salvataggio"/>Eccoci qui!
  Ed altri paragrafi continuano interessanti 
  ( come un convegno di tromboni... )
  e dai, e dai, e dai...
  e non finiscono più...
</para>

Avendo messa l'ancora (anchor), si può creare il link ad essa:

<link linkend="salvataggio">Vai al punto interessante</link> nel
mezzo di quel lunghissimo paragrafo.

Se la destinazione del link è un elemento breve, o l'inizio di un elemento, è più comodo dare all'elemento stesso un id e riferirlo nell'attributo linkend del link.

Per includere frammenti di codice sorgente nel documento, li si mette in un elemento programlisting. Quanto verrà scritto in un programlisting verrà reso identico, inclusi a capo, spazi, ecc.. Inoltre il documento sarà stampato con fonti a passo fisso. Il termine «listato sorgente», o «program listing», deve essere inteso in senso lasco: si può usare sia per frammenti di SQL come per esempi di DocBook XML. Questa guida, e specialmente la sezione sugli elementi che si sta' leggendo, è piena di programlisting, così è facile rendersi conto di come appaiono:

La resa di un programlisting è come in questa linea.

Si usa un elemento screen per mostrare ciò che un utente vede o potrebbe vedere sullo schermo di un computer in modalità testo, o in una finestra terminale. Anche in questo caso lo schema viene conservato e si usa una font a passo fisso, ma la semantica è diversa. La resa potrebbe essere del tutto diversa (oppure per niente) da un programlisting. Questo è un breve esempio, giusto per mostrare che succede cercando di ricostruire un modulo inesistente dell'albero del modulo del manuale (notare: il primo è un programlisting, il successivo è effettivamente uno screen):

<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>

E questo è quel che ne risulta:

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, al pari di screen e programlisting, lascia intatto il formato ma normalmente non cambia la font, a meno di impostare l'attributo class a monospaced. È ancora più generico dei precedenti nel senso che al contenuto non viene attribuito nessun significato particolare: si può pertanto mettere qualsiasi testo di cui si voglia conservare lo schema.

Esempio:

<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>

Risultato:

Un example è un esempio formale con un titolo. Di solito gli si da' un id per potergli fare riferimento da altre parti del documento. L'indice degli esempi viene generato automaticamente nella stampa del documento. Spesso si possono trovare anche dei programlisting in un example, oppure screen, para, liste varie, ecc.

Ecco un esempio di example:

<example id="docwritehowto-sql-example">
  <title>Un esempio di SQL</title>
  <para>Con questo comando si possono listare tutti i record della
  tabella COUNTRY:</para>
  <programlisting>SELECT * FROM COUNTRY;</programlisting>
</example>

Il risultato sarà più o mano così:

Volendo fare un example senza il titolo obbligatorio, si usa un informalexample. Gli esempi informali non sono compresi nell'indice degli esempi.

Un bridgehead è un titolo flottante tra paragrafi, non associato all'inizio di un capitolo o sezione. L'attributo renderas determina come sarà l'aspetto finale.

<para>Il biliardo all'italiana si gioca oggi sul biliardo 
internazionale, che è un tavolo privo di buche di 2,84 m x 1,42 m;
si usano tre biglie e cinque piccoli birilli. Le biglie
destinate ai giocatori sono di colore bianco o giallo, 
il pallino di colore rosso. I birilli, alti circa 2,5 cm, 
sono di colore bianco ad eccezione di quello centrale, che è
di colore rosso.</para>

<bridgehead renderas="sect5">Ma come si gioca?</bridgehead>

<para>I birilli devono essere disposti prima di ogni tiro in posizioni 
ben precise, al centro del tavolo, a formare quello che si suole 
definire castello. Bisogna colpire con la propria biglia quella 
dell'avversario cercando possibilmente di indirizzare quest'ultima 
sui birilli, alla cui caduta è attribuito un punteggio.</para>

Il sorgente qui sopra ha questo aspetto:

Si è liberi nella scelta del livello di renderas, ma la scelta più logica sarebbe normalmente quella del corrente livello di sezione più (almeno) uno.

Un formalpara è un paragrafo con un titolo. L'aspetto dipende dal foglio di stile, nel nostro caso trasforma il titolo indentando tutto.

<formalpara>
  <title>Amor materno:</title>
  <para>Questo è l'amore che ha tua madre per te, da non confondere 
    con l'amor paterno, fraterno o altrui.</para>
</formalpara>

Il risultato viene visualizzato come segue:

Viene aggiunto un punto alla fine del titolo, a meno che non termini già con un carattere di interpunzione.

Si usa il marcatore filename per evidenziare nomi di file nel senso più generico possibile. Gli attributi possono opzionalmente indicare se il file è una libreria, un link, una directory, ecc.

Mettere il documento nella directrory <filename
class="directory">src/docs/firebirddocs</filename>.

che si leggerà:

command e application si usano entrambi per programmi eseguibili. command si usa per piccoli programmi e comandi interni; il suo contenuto dovrebbe essere il comando esatto così come dato in una linea di comando; application è usato di solito per grandi programmi e non necessariamente deve essere il nome dell'eseguibile. Entrambi possono riferire lo stesso programma:

Digitare <command>netscape&amp;</command> in una finestra terminale
per lanciare il <application>Netscape Navigator</application>.

Questo apparirà così:

envar invece serve per indicare una variabile d'ambiente.

È immediato intuire cosa fanno:

Dopo la scoperta della formula e = mc<superscript>2</superscript>,
avevo proprio voglia di un bicchiere di H<subscript>2</subscript>O !

Output: Dopo la scoperta della formula e = mc², avevo proprio voglia di un bicchiere di H₂O !

L'uso di varname (nome di variabile) e constant (costante) dovrebbero essere ovvii. Il marcatore <database> non è stato previsto solo per i database, ma anche per gli oggetti di database:

La tabella <database class="table">COUNTRY</database> ha due campi:
<database class="field">COUNTRY</database> e
<database class="field">CURRENCY</database>.

Risultato: La tabella COUNTRY ha due campi: COUNTRY e CURRENCY.

Anche questi sono autoesplicativi, credo.

La funzione <function>log</function> ha due parametri
<parameter>a</parameter> e <parameter>b</parameter>.

Risultato: La funzione log ha due parametri a e b.

Si usa prompt per una stringa che chiede all'utente di inserire del testo; userinput si riferisce al testo inserito dall'utente (non necessariamente ad un prompt!); computeroutput è il testo mostrato dal computer:

Digitare <userinput>guest</userinput> al prompt
<prompt>login:</prompt> ed il server risponderà con
<computeroutput>Benvenuto, utente guest</computeroutput>.

Risultato: Digitare guest al prompt login: ed il server risponderà con Benvenuto,utente guest.

Il testo scritto su di un tasto della tastiera, oppure il suo nome comune:

Digitare il tasto <keycap>Del</keycap> per cancellare il messaggio, 
oppure <keycap>SPACE</keycap> per confermarlo.

Risultato: Digitare il tasto Del per cancellare il messaggio, oppure SPACE per confermarlo.

Questo elemento è stato usato moltissimo in questa guida: evidenzia marcatori SGML e XML, elementi, attributi, entità, ecc.:

Se riguarda una directory, impostate l'attributo 
<sgmltag class="attribute">class</sgmltag> dell'elemento
<sgmltag class="element">filename</sgmltag> a
<sgmltag class="attvalue">directory</sgmltag>.

Risultato: Se riguarda una directory, impostate l'attributo class dell'elemento filename a directory.

Altri possibili valori per sgmltag.class sono: starttag, endtag, emptytag, e genentity (per una entità).

Si usa emphasis per evidenziare genericamente delle parole, citetitle per titoli di libri ecc., e firstterm introducendo un nuovo termine o concetto ai lettori:

Si usa <firstterm>DocBook XML</firstterm> per la nostra
documentazione Firebird. Segue una breve introduzione;
<emphasis>per favore</emphasis>, leggetela attentamente!
Per avere ulteriori informazioni al riguardo, comprare il
libro <citetitle>DocBook – The Definitive Guide</citetitle>.

Risultato: Si usa DocBook XML per la nostra documentazione Firebird. Segue una breve introduzione; per favore, leggetela attentamente! Per avere ulteriori informazioni al riguardo, comprare il libro DocBook – The Definitive Guide.

Usare quote per virgolettare in linea (a differenza di blockquote). Le virgolette vengono messe automaticamente. Usando quote invece di digitare le virgolette (che sarebbe comun que perfettamente legale) ha il vantaggiono che si possono cambiare il tipo di virgolettatura globalmente nel foglio di stile volendolo. Inoltre si diversificano per lingua:

<para>Queste sono <quote lang="en">virgolette inglesi</quote> 
e queste sono <quote lang="fr">virgolette francesi</quote>. 
Invece sono così <quote lang="it">quelle italiane</quote>.</para>

Risultato: Queste sono “virgolette inglesi” e queste sono « virgolette francesi ». Invece sono così «quelle italiane».

Non si dovrebbe usare l'attributo lang nell'elemento quote nei propri documenti. L'attributo lang dell'elemento radice assicura che vengano usate le virgolette giuste. Nella traduzione del vostro documento, e quindi nella modifica alla radice dell'attributo lang, verranno così automaticamente usate le virgolette del linguaggio della traduzione. Ho usato l'attributo in questo caso per mostrare la differenza, e per assicurarmi che le differenti virgolette rimarranno indipendentemente dalla traduzione.

Un literal è una parola o un frammento di testo da prendere alla lettera. È un elemento generico, spesso usato per evidenziare tipograficamente certe parole:

L'ultima parola del vocabolario italiano è 
<literal>zuzzurellone</literal>, credo.

Risultato: L'ultima parola del vocabolario italiano è zuzzurellone, credo.