Firebird Documentation IndexScrivere documenti per Firebird → DocBook XML – una introduzione
Firebird Home Firebird Home Indietro: Prepararsi a scrivere: farsi uno schema!Firebird Documentation IndexRisali: Scrivere documenti per FirebirdAvanti: Strumenti per scrivere in DocBook XML

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.

Indietro: Prepararsi a scrivere: farsi uno schema!Firebird Documentation IndexRisali: Scrivere documenti per FirebirdAvanti: Strumenti per scrivere in DocBook XML
Firebird Documentation IndexScrivere documenti per Firebird → DocBook XML – una introduzione