Documenti
Firebird → Agli
scrittori per Firebird → Scrivere
documenti per Firebird → DocBook XML – una introduzione

DocBook XML – una introduzione

Un'introduzione
generale a XML

Un'introduzione
a DocBook XML

Il formato scelto per la documentazione che è nel modulo del manuale di
Firebird è DocBook XML. Per coloro che non hanno molto
sentito parlare di XML e/o di DocBook, seguirà una breve introduzione a XML in
generale e a DocBook XML in particolare. Si avverte che queste introduzioni sono
giusto per dare un'immagine molto semplificata. Ovviamente sarà idonea a
sufficienza: non è necessario essere un esperto in DocBook XML per poter
scrivere documentazione per Firebird. È necessario avere solo un po' di
conoscienze basilari - che si possono apprendre in mezz'oretta dai paragrafi
successivi - ed un po' di esperienza nell'applicare gli elementi di DocBook XML
al vostro testo (cosa che si otterrà molto presto appena si inizia a scrivere).

Salta
l'introduzione a XML Se conosci già tutto sugli elementi, le etichette e gli
attributi di XML, sul rendering ( cioè restituzione grafica) ed il multichannel
publishing (editoria e pubblicazione multicanale).

Salta
entrambe le introduzioni Se si è anche un esperto autore con DocBook.

Nota

Nonostante si richieda che almeno si provi a sviluppare il proprio lavoro con il
formato DocBook, si è altresì coscienti che non tutti hanno il tempo per
apprenderlo (o per convertire la propria documentazione esistente in DocBook).
Nel caso, se ne parli sulla lista firebird-docs (possibilmente in inglese).
Certamente non si rifiuta della documentazione utile solo perchè non è nel
giusto formato.

Un'introduzione generale
a XML

XML sta' per Extensible Markup Language, che è
semplice testo piano con delle etichette di demarcazione. Un tipico frammento di
testo XML potrebbe comparire come il seguente:

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

Marcatori ed
attributi

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:

Tabella 1. Formato dei marcatori XML

Tipo del marcatore

Comincia con

Finisce con

Marcatore iniziale

<

>

Marcatore finale

</

>

Marcatore di elemento vuoto

<

/>

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.

Caratteri speciali ed Entità

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:

&lt;

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 &gt; (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 &lt; e
&auml; (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:

&amp;

Così questa linea di XML:

Kernigan &amp; Ritchie hanno scelto '&lt;' 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 &lt; e &amp; nel XML quando lo salva su disco. Più
oltre in questa guida ci saranno riferimenti ad alcuni editor XML/DocBook.

Elementi

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.

Nota

In effetti, gli elementi sono un concetto più basilare dei marcatori: i
marcatori sono di fatto gli identificatori degli elementi. Pertanto sarebbe
stato meglio dire che i marcatori prendono il nome dai loro elementi. Ma poichè
i marcatori sono più facili da riconoscere di un intero elemento, si è pensato
di spiegarli prima.

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

Importante

Non si confonda il contenuto con gli attributi. Il contenuto sta' tra due marcatori, gli attributi sono nei marcatori. Il marcatore di elemento vuoto
dell'esempio precedente ha un attributo, ma non ha contenuto.

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.

XML: Conclusione

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.

Un'introduzione
a DocBook XML

DocBook è stato progettato per semplificare la scrittura di documenti
strutturati usando SGML o XML (non ci si deve preoccupare di SGML – noi usiamo
solo XML). È particolarmente adatto a scrivere libri ed articoli tecnici,
specialmente su argomenti relativi ai computer. DocBook XML è definito nel suo
Document Type Definition o DTD: un insieme di definizioni e di regole che descrivono
esattamente come deve essere strutturato un un documento DocBook valido. DocBook
sta' diventando rapidamente uno standard di fatto per documentazione tecnica, e
viene supportato da un crescente numero di strumenti ed applicazioni.

Caratteristiche di DocBook XML

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

Il DTD di DocBook definisce un numero limitato e preciso di marcatori, e
da' regole esatte su come vanno usati: quali attributi sono possibili per un
dato marcatore, quali elementi possono stare all'interno un dato elemento, e
così via. Il documento che non usa marcatori definiti, o che non segue le
regole, non sarà più un documento DocBook (e gli strumenti di supporto
potrebbero non funzionare più).

I marcatori di DocBook determinano sempre e solo struttura logica e
semantica (significato), ma mai
l'estetica. In DocBook, si troveranno marcatori strutturali come <book>, <part>, <chapter>, <section>, <para>, <table>; inoltre vi sono marcatori
semantici come <filename>, <warning,> <emphasis>, <postcode>; ma mai nulla come <font>, <bold>, <center>, <indent>, <backgroundcolor> – nulla cioè che abbia a
che fare con l'aspetto estetico finale del documento.

A causa di ciò, era necessario prendere una decisione su come i marcatori
in qualche modo dovessero essere tradotti nell'aspetto estetico finale. Questa
decisione (o meglio, le regole di restituzione) avrebbero potuto essere
fissate negli strumenti software, ma questo avrebbe reso le cose poco
flessibili. Questo è il motivo per cui le regole sono in gran parte definite
in fogli di stile o stylesheets. Un foglio di stile è un documento che
informa gli strumenti su cose come:

«Stampa i titoli di capitolo in una font a 24 punti
nera; inizia ogni capitolo a pagina nuova; usa il corsivo per l'enfasi;
visualizza gli avvisi in una font rossa 12 punti in grassetto; usa il
maiuscoletto per gli acronimi; ecc. ecc.»

Questo metodo permette all'utente di modificare gli stylesheets se non gli
piace il risultato del documento finale. Sarebbe molto più difficile, sebbene
non impossibile, modificare gli strumenti software stessi.

Nota

I fogli di stile che sono usati per convertire i testi DocBook XML in altri
formati, sono chiamati transformation stylesheets.
Questi sono scritti in un altro tipo di XML, chiamato XSLT (eXtensible Stylesheet Language for
Transformations).

Benefici del
DocBook XML

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

Un documento DocBook XML consiste di puro, pulitissimo, contenuto. Non bisogna per nulla preoccuparsi
dell'aspetto presentazionale mentre si scrive il documento; ci si può
concentrare sulla struttura e sul contenuto. Questo potrebbe sembrare un po'
strano a chi è abituato a scrivere in Word, ad esempio, ma ve lo promettiamo:
presto comincierete ad apprezzarlo.

Poichè DocBook è solo struttura e significato, verrà facilissimo
trasformare lo schema preparato in uno scheletro DocBook.

Molti preparano documenti per il modulo del manuale. Se ognuno di essi
usasse formati diversi, ma anche un solo formato come Word o HTML, ognuno di
loro renderà con aspetto molto diverso il proprio lavoro perchè prenderà le
proprie decisioni in modo autonomo sull'estetica. Ovviamente si potrebbero
sviluppare tutta una serie di convenzioni, ma ugualmente ogni scrittore
dovrebbe esserne a conoscenza e preoccuparsi di applicarle sempre e comunque.
No... meglio mettere le regole in un punto centralizzato: i fogli di stile, e
fare in modo che gli scrittori si preoccupino del contenuto e non dell'aspetto
estetico. I fogli di stile assicureranno che tutta la nostra documentazione
avrà esattamente lo stesso aspetto.

Se non piace l'aspetto estetico della trasformazione, si può facilmente
modificare, fintantochè le regole sono in un foglio di stile. Non deve essere
modificato nulla nel documento sorgente DocBook; tutto quello che c'è da fare,
dopo aver modificato i fogli di stile, è rigenerare i documenti finali. I
documenti appena rifatti, automaticamente avranno il nuovo aspetto. Provate a
farlo se le istruzioni di formattazione sono sparpagliate fra tutti i
documenti in posti diversi in modi diversi...!

Un altro vantaggio è che DocBook è uno standard «aperto» , cioè non proprietario di una qualsiasi
applicazione commerciale o di un particolare sistema operativo. Scaricando il
modulo del manuale di Firebird , si possono ricostruire i documenti HTML e PDF
a partire dal sorgente DocBook sia sotto Linux che sotto Windows, e si
potrebbero supportare altri sistemi operativi se necessario.

Un documento DocBook è puro testo, che è ideale per essere utilizzato con
CVS. Naturalmente, una struttura CVS può contenere anche file binari, ma molte
delle utilità offerte da CVS (mostrare la differenza fra due versioni di un
file, ad esempio) funzionano solo con i file di testo.

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.

La documentazione su
DocBook in Internet

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

http://opensource.bureau-cornavin.com/crash-course/

Writing Documentation Using DocBook – A Crash
Course di David Rugge, Mark Galassi e Eric Bischoff. Una introduzione ben
fatta, anche se molti degli strumenti trattati non sono gli stessi nostri.

http://docbook.org/tdg/en/

DocBook – The Definitive Guide, di Norman Walsh e
Leonard Muellner. Una guida che non è per inesperti. Difatti la prima parte è
praticamente incomprensibile se si è principianti di DocBook. La ragione per
menzionarla qui, è perchè è un riferimento importantissimo online, che viene
spesso consultato dagli esperti mentre scrivono.

http://www.tldp.org/HOWTO/DocBook-Demystification-HOWTO/

Questo DocBook Demystification Howto è
interessante se si desidera sapere un po' di più di quanto si è detto qui
riguardo a XML e DocBook. C'è anche molto materiale su SGML e su strumenti che
non vengono usati per il sottoprogetto documentazione di Firebird.

http://sourceforge.net/projects/docbook

È il sito del progetto open source di DocBook a SourceForge.

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

Documenti
Firebird → Agli
scrittori per Firebird → Scrivere
documenti per Firebird → DocBook XML – una introduzione