<paragraph>
<loud>'No!'</loud> she screamed. <scary>But the bloody hand
<italics>kept on creeping</italics> towards her.</scary>
<picture file="bloody_hand.png"/>
</paragraph>

Nell'esempio precedente, le parole e le frasi racchiuse fra parentesi angolari sono i marcatori. <italics> è un marcatore iniziale (start tag), mentre </italics> è un marcatore finale (end tag), e <picture file="bloody_hand.png"/> è un marcatore autonomo, detto comunemente marcatore di elemento vuoto (empty-element tag). I marcatori XML hanno sempre uno di questi tre formati:

Ancora riferendosi al nostro esempio, le parole paragraph, loud, scary, italics e picture sono i nomi dei marcatori (tag names). Nel marcatore <picture.../>, la parte file="bloody_hand.png" viene detta un attributo (attribute), dove file è il nome dell'attibuto (attribute name) ed invece bloody_hand.png è il valore dell'attributo (attribute value). I valori degli attributi devono essere sempre tra apici, e sono permessi sia i singoli che i doppi apici.

XML permette di definire i marcatori a piacere, purchè siano costruiti correttamente. Così <questotag>, <altrotag>, and <io_non_sono_un_tag/> sono tutti marcatori XML corretti. (Un testo XML che segue lo standard viene detto well-formed (ben costruito o corretto); Il termine valido (valid) è utilizzato solo per implementazioni specifiche, ad esempio DocBook XML)

Ovviamente i marcatori in quanto tali non sono stati pensati per apparire nel documento finale (cioè il documento come verrà presentato ai lettori). Contengono, invece, istruzioni che influenzeranno il suo aspetto. XML, quando usato per scrivere documenti, è un tipico formato sorgente (source format), con lo scopo di essere processato da altro software per produrre documenti ben formattati. Questo procedimento viene usualmente chiamato restituzione (rendering).

Alcuni marcatori sono senza tema d'errore indicazioni di formattazione:

<italics>kept on creeping</italics>

significa ovviamente che le parole words kept on creeping devono essere visualizzate o stampate in corsivo (italics in inglese). Tuttavia,

<loud>'No!'</loud>

è un po' meno ovvio. La parola No! deve apparire in grassetto? Oppure sottolineata? O ancora in corsivo? O vuol dire che questo testo debba essere letto ad alta voce da un sintetizzatore vocale, e il marcatore <loud> lo informa di alzare la voce? Tutte questi casi sono possibili, e c'è di più: spesso un sorgente XML può essere convertito in vari formati - ad esempio, un documento PDF, una pagina web in HTML, un file audio. Questa è chiamata editoria multicanale (multichannel publishing). Con l'editoria multicanale, <loud> potrebbe essere trasformato in grassetto nel documento PDF; in un carattere grassetto rosso nella pagina web; e un aumento del 50% del volume per il sintetizzatore vocale.

Osservando gli altri marcatori, <picture.../> (cioè immagine) è ovviamente l'istruzione per inserire l'immagine bloody_hand.png (mano_insanguinata) nel documento, e <scary>, be'... questo è ancora meno chiaro di <loud>. Potrebbe essere che la frase tra i marcatori <scary> debba essere insanguinata. Può essere che ci sia da mettere in sottofondo musica dell'orrore. Tutto dipende da chi definisce i marcatori, e dal programma che viene utilizzato per la restituzione.

Il marcatore <paragraph>, infine, è di tipo strutturale. Informa sulla posizione che queste linee devono assumere nella struttura gerarchica interna al documento. Nel risultato finale, i paragrafi potrebbero o meno essere separati da linee vuote. Ancora, ciò dipende dal software di restituzione e pure da opzioni configurabili dall'utente. Altri marcatori di struttura che si potrebbero considerare sono ad esempio <chapter>, <section>, e <subdocument> che significano, nell'ordine, capitolo, sezione e sottodocumento.

Poichè il carattere «<» ha un significato particolare in quanto inizio di marcatore, non si può includere direttamente come valore, invece affinchè i lettori possano vedere una parentesi angolare aperta, bisogna scrivere questo:

Che è una «e commerciale» (in inglese ampersand), seguita dalle lettere «l» e «t» (che stanno per «minore di» cioè less than), seguite da un punto e virgola. Si può usare anche > (greater than cioè «maggiore di») per il carattere di parentesi angolare chiusa «>», ma non è necessario.

XML ha molti codici come questi, e sono chiamati entità (entities). Alcune rappresentano caratteri, come < e ä (a minuscola con umlaut) ed altri con scopi totalmente diversi. Ad ogni modo, tutti cominciano con una e commerciale e finiscono con un punto e virgola.

Ma, un momento... se una e commerciale serve è l'inizio di una entità, come includere quel carattere nel proprio testo? Be', c'è un'entità anche per questo:

Così questa linea di XML:

Kernigan & Ritchie hanno scelto '<' come operatore minore-di per
il linguaggio C.

si trasformerà nel documento finale così:

Kernigan & Ritchie hanno scelto '<' come operatore minore-di per il linguaggio C.

E ci sono pure le buone notizie: usando un editor specifico per l'XML per scrivere il vostro documento, probabilmente si potrà digitare direttamente «<» e «&» dovunque si desideri. L'editor si farà carico della trasformazione direttamente in < e & nel XML quando lo salva su disco. Più oltre in questa guida ci saranno riferimenti ad alcuni editor XML/DocBook.

C'è un altro importante concetto di XML da sapere: gli elementi. Un elemento è la combinazione di un marcatore di inizio, un corrispondente marcatore di fine, e tutto ciò che c'è in mezzo. «Tutto ciò che c'è in mezzo» viene definito il contenuto dell'elemento, e può includere altri elementi. Gli elementi prendono il nome dal loro marcatore, pertanto si parla di elementi di paragrafo, elementi in corsivo, ecc.

Questo è un elemento:

<loud>'No!'</loud>

Anche questo è un elemento:

<paragraph>Questo è un elemento che contiene <bold>un altro</bold> 
  elemento!</paragraph>

I marcatori di un elemento vuoto sono un caso un po' particolare: l'elemento che marcano non ha contenuto, e l'elemento non ha una coppia di marcatori, iniziale e finale.

<picture file="bloody_hand.png"/>

Si sta' insistendo sul concetto di elemento perchè molta documentazione tende a parlare di «chapter elements», «title elements» (elementi capitolo, elementi titolo) ecc. invece che di «chapter tags» e «title tags» (marcatori di capitolo, marcatori di titolo). I termini sono usati spesso in modo intercambiabile, ma vi sono casi in cui è importante sapere la differenza.

Bene, questo è tutto quello che c'è da sapere su XML. Per il momento si dovrebbe avere un'idea generale su come deve apparire un testo XML, che cosa sono i marcatori e gli elementi e a cosa servono. Come già detto, si è data giusto un'idea molto semplificata, ma è già abbastanza per i nostri scopi.

Dovrebbe essere anche chiaro che scrivere con un XML inventato e sui generis è inutile, a meno di non avere un software che riesce a comprendere i propri marcatori. Come, se no, riuscire a trasformare il proprio sorgente XML in un documento ben composto e presentabile?

Fortunamente non si ha la necessità di sviluppare le proprie definizioni degli elementi ed i software di conversione. Ci sono un buon numero di tipi formalizzati di XML disponibili, ognuno che definisce un insieme di marcatori e, cosa altrettanto importante, un insieme di regole sul come usarli. DocBook XML è uno di questi tipi.

Le maggiori caratteristiche di DocBook – al contrario del «generico» XML – sono:

DocBook ha molti vantaggi per tutti coloro che scrivono documentazione tecnica. Queste sono secondo noi le più importanti:

Certamente, nessuno di questi benefici è unico solo per DocBook. Ma DocBook li ha tutti, ed è supportato ampiamente. Questo lo rende la scelta ideale per la documentazione di Firebird.

Seguono alcuni link (in inglese) nel caso si desiderasse saperne di più su DocBook:

Nel caso si conoscessero altre buone risorse online riguardo a DocBook, siete pregati di mettere un messaggio sulla lista di firebird-docs.