[successivo] [precedente] [inizio] [fine] [indice generale] [indice ridotto] [indice analitico] [volume] [parte]


Capitolo 459.   Introduzione a DocBook

DocBook è un formato per la composizione di documenti tecnici che ha l'intento di essere onnicomprensivo. Dal lato pratico, DocBook è essenzialmente un DTD, che originariamente è stato realizzato per l'SGML, successivamente adattato e ridotto a XML. Naturalmente, l'importanza di un DTD è minima se poi mancano degli strumenti di composizione adeguati. DocBook è molto complesso e gli strumenti realizzati attorno a lui sono diversi e in continua evoluzione.

In questo capitolo viene mostrato solo un utilizzo superficiale di strumenti per la composizione abbinati a DocBook, soprattutto in considerazione della dinamicità con cui queste cose si evolvono. Può essere molto utile la lettura di DocBook demystification HOWTO, di Eric S. Raymond, per avere una visione di insieme sulle strade che si possono scegliere per arrivare al risultato di proprio interesse.

459.1   Edizioni e varianti del DTD

L'importanza di DocBook è paragonabile a HTML; da questo fatto si può comprendere la presenza di diverse versioni e varianti di questo formato di composizione. Tra queste varianti possono essere interessanti anche quelle che cercano di ridurre il tutto a una struttura più semplice, pur rimanendo compatibile con quella generale complessiva, quasi come avviene con un formato HTML «stretto» (strict).

Se i vari DTD DocBook sono stati installati correttamente (dipende probabilmente dall'organizzazione della propria distribuzione GNU), dovrebbe essere sufficiente indicare l'intestazione corretta nel proprio sorgente per fare riferimento al DTD che si preferisce.

459.2   Esperimenti con il DTD e convalida

Per cominciare a fare qualche esperimento con il DTD DocBook, occorre almeno uno strumento di convalida, di solito il pacchetto SP di James Clark. Nella propria distribuzione GNU/Linux, questo pacchetto potrebbe essere disponibile da solo (come avviene nella distribuzione Debian), oppure assieme a Jade (come avviene nella distribuzione Red Hat). Quello che conta è, per iniziare, che sia disponibile l'eseguibile nsgmls.

Senza entrare nel dettaglio dell'SGML di DocBook, si può prendere l'esempio seguente come base per gli esperimenti.

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<book id="book" lang="it">
<bookinfo>
  <title>Il mio primo libro con DocBook</title>
  <authorgroup>
    <author>
      <surname>Pallino</surname>
      <firstname>Pinco</firstname>
    </author>
  </authorgroup>
  <editor>
    <surname>Cai</surname>
    <firstname>Caio</firstname>
  </editor>
  <legalnotice>
    <para>Copyright &copy; 1999 Pinco Pallino</para>

    <para>This work is free; you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.</para>
  </legalnotice>
</bookinfo>

<chapter>
<title>Primo capitolo</title>

<para>Contenuto del primo capitolo, bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla.</para>

<para>bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla.</para>

<sect1>
<title>Prima sezione del primo capitolo</title>

<para>Contenuto della prima sezione, bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla.</para>

<para>bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla.</para>

</sect1>
</chapter>
<appendix>
<title>Prima appendice</title>

<para>Contenuto della prima appendice, bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla.</para>

<para>bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla.</para>

</appendix>

</book>

La verifica si fa nel modo già visto tante altre volte. Supponendo di voler fare riferimento al catalogo contenuto nel file /usr/share/sgml/catalog e supponendo di avere chiamato il sorgente SGML libro.sgml:

nsgmls -s -c /usr/share/sgml/catalog libro.sgml[Invio]

Eventualmente, se il pacchetto di programmi che contiene SP è stato compilato in modo coerente con l'impostazione SGML della propria distribuzione, potrebbe non essere necessario indicare espressamente il file del catalogo:

nsgmls -s libro.sgml[Invio]

A questo punto, disponendo di un analizzatore SGML che funziona correttamente con questo DTD, si potrebbero realizzare i propri strumenti per la trasformazione in un risultato adatto alla consultazione: cartacea o elettronica.

Purtroppo può capitare di disporre di DTD DocBook che non sono stati realizzati in modo accurato. In questi casi si possono osservare una serie di segnalazioni di errori che dipendono da file estranei al proprio. Dal momento che nsgmls ha un limite massimo di errori predefinito, dopo il quale non ne mostra altri, potrebbe essere necessario utilizzare l'opzione -E per estenderlo, andando poi a cercare gli errori riferiti direttamente al file di proprio interesse:

nsgmls -E1000 -s libro.sgml[Invio]

459.3   Strumenti per la composizione

All'inizio del capitolo si è accennato al fatto che gli strumenti di composizione che si avvalgono di DocBook sono diversi, ma forse nessuno può dirsi abbastanza maturo per poter essere scelto senza alcun dubbio. In condizioni normali, senza entrare nel dettaglio di questi strumenti, potrebbero essere disponibili degli script che facilitano la produzione di un certo formato finale prescelto. Potrebbe trattarsi di nomi come quelli seguenti:

db2ps file_sgml_docbook | docbook2ps file_sgml_docbook
db2pdf file_sgml_docbook | docbook2pdf file_sgml_docbook
db2rtf file_sgml_docbook | docbook2rtf file_sgml_docbook
db2html file_sgml_docbook | docbook2html file_sgml_docbook

In generale, quindi, uno script del tipo db2nome o docbook2nome sta a indicare una conversione da DocBook al formato indicato dal nome. In pratica, lo script va letto mnemonicamente come: from docbook to x.

459.4   Struttura generale

Un documento DocBook si può articolare in modi differenti. Per prima cosa si distingue il tipo di documento; i casi principali si possono ridurre a: raccolta, libro o articolo. Lo schema della struttura di un libro si può semplificare nel modo seguente:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<book>
<bookinfo>
    ...
</bookinfo>
{<part>}
    <chapter>
        {<sect1>
            {<sect2>
                {<sect3>
                    {<sect4>
                        {<sect5>
                            ...
                        </sect5>}
                        ...
                    </sect4>}
                    ...
                </sect3>}
                ...
            </sect2>}
            ...
        </sect1>}
        ...
    </chapter>
{<part>}
...
{<appendix>
    {<sect1>
        ...
    </sect1>}
</appendix>}
{<glossary>
    ...
</glossary>}
</book>

La struttura che appare è incompleta e serve solo per avere un'idea dell'articolazione di un libro secondo DocBook. Si può osservare che a differenza di HTML, le sezioni di un documento (parti, capitoli e sezioni di livello inferiore) sono ben delimitate attraverso un elemento appropriato.

Una raccolta, ovvero un documento molto grande diviso in volumi, può essere strutturato nel modo seguente, dove naturalmente ogni elemento book si può articolare come già visto a proposito della struttura a volume singolo:

<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<set>
<setinfo>
    ...
</setinfo>
<book>
    ...
<book>
...
</set>

Un articolo, ovvero un documento di piccole dimensioni, può essere strutturato nel modo seguente:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article>
<articleinfo>
    ...
</articleinfo>
{<sect1>
    {<sect2>
        {<sect3>
            {<sect4>
                {<sect5>
                    ...
                </sect5>}
                ...
            </sect4>}
            ...
        </sect3>}
        ...
    </sect2>}
    ...
</sect1>}
...
</article>

Gli attributi più importanti che si possono usare con gli elementi che delimitano porzioni di testo, specie se si tratta di quelli che lo dividono in sezioni (parti, capitoli, ecc.), sono id e lang. Il primo serve a indicare una stringa di identificazione, che in seguito può essere usata per fare un riferimento incrociato; il secondo stabilisce il linguaggio, attraverso una sigla espressa secondo lo standard ISO 639 (appendice 104), cosa che può riflettersi in vario modo in fase di composizione.

Nei modelli mostrati, riferiti rispettivamente al libro, alla raccolta e all'articolo, appare inizialmente un elemento destinato all'inserimento di informazioni particolari: bookinfo, setinfo e articolinfo. Questi due elementi sono paragonabili all'intestazione di un file HTML, dove va collocato il titolo, i dati dell'autore o degli autori, assieme a tutte le altre informazioni generali riferite all'opera. Il modello seguente semplifica questa struttura:

<bookinfo>|<setinfo>|<articleinfo>
    <title>titolo</title>
    <authorgroup>
        <author>
            <firstname>nome_autore</firstname>
            <familyname>cognome_autore</familyname>
        </author>
        ...
    </authorgroup>
    <keywordset>
        <keyword>parola_chiave</keyword>
        ...
    </keywordset>
    <abstract>
        descrizione_del_documento
    </abstract>
    <legalnotice>
        note_legali_sul_documento
    </legalnotice>
    <edition>dati_dell'edizione</edition>
</bookinfo>|</setinfo>|</articleinfo>

459.5   Corpo del documento

L'elemento più comune che appare nel corpo del documento e anche in altri contesti che lo richiedono è il paragrafo:

<para>testo</para>

Così come avviene nella maggior parte dei sistemi SGML (o XML), il paragrafo rappresenta un blocco di testo elementare, che contiene può contenere altri elementi che però non costituiscono un altro blocco separato.

Nelle sezioni seguenti vengono descritti altri elementi comuni del corpo del documento, senza però entrare nel dettaglio delle caratteristiche e delle possibilità di questi.

459.5.1   Elenchi

DocBook dispone di una discreta quantità di elenchi differenti. L'elenco più semplice è definito dall'elemento simplelist, allo scopo di annotare una serie di voci, senza un'estetica o uno scopo particolare:

<simplelist>
<member>prima_voce_dell'elenco</member>
<member>seconda_voce_dell'elenco</member>
...
<member>ultima_voce_dell'elenco</member>
</simplelist>

L'elenco puntato classico si ottiene con l'elemento itemizedlist:

<itemizedlist>
<listitem>blocchi_della_prima_voce</listitem>
<listitem>blocchi_della_seconda_voce</listitem>
...
<listitem>blocchi_dell'ultima_voce</listitem>
</itemizedlist>

Si osservi che la differenza più importante tra i due tipi di elenchi appena descritti sta nel fatto che le voci contenute negli elementi listitem sono costituite da uno o più blocchi di testo (per esempio i paragrafi), mentre l'elemento member contiene un testo lineare che l'elemento stesso traduce in un blocco unico.

L'elenco numerato si ottiene con l'elemento orderedlist:

<orderedlist>
<listitem>blocchi_della_prima_voce</listitem>
<listitem>blocchi_della_seconda_voce</listitem>
...
<listitem>blocchi_dell'ultima_voce</listitem>
</orderedlist>

Come si vede, orderedlist si utilizza nello stesso modo dell'elenco puntato normale, con la differenza che le voci sono numerate.

Gli elenchi descrittivi si ottengono con l'elemento variablelist che appare un po' complesso rispetto a quelli già presentati:

<variablelist>
<varlistentry>
    <term>voce_descrittiva</term>
    ...
    <listitem>blocchi_della_voce</listitem>
</varlistentry>
...
</variablelist>

Lo schema mostra l'elemento variablelist che può contenere uno o più elementi varlistentry, all'interno dei quali, ogni voce contiene una o più descrizioni all'interno di elementi term, seguiti da un solo elemento listitem che ha le caratteristiche già viste a proposito degli elenchi puntati e numerati.

Quelli descritti sono elenchi classici che di solito si trovano nella maggior parte dei sistemi di composizione; tuttavia DocBook dispone anche di altri elenchi speciali, che qui non vengono descritti.

459.5.2   Tabelle

DocBook offre tabelle molto complesse, la cui realizzazione pratica dipende però dagli strumenti di composizione utilizzati effettivamente. In generale si distinguono due involucri alternativi: l'elemento table e l'elemento informaltable. Nel primo caso si ha una tabella che richiede l'inserimento di un titolo (ovvero di una didascalia); nel secondo questo viene a mancare:

<table>
    <title>titolo</title>
    <tgroup cols="n_colonne">
        corpo_della_tabella
    </tgroup>
</table>
<informaltable>
    <tgroup cols="n_colonne">
        corpo_della_tabella
    </tgroup>
</informaltable>

Il contenuto dell'elemento tgroup è il corpo della tabella, con o senza intestazioni:

<tgroup cols="n_colonne">
    [<thead>
        righe
    </thead>]
    [<tfoot>
        righe
    </tfoot>]
    <tbody>
        righe
    </tbody>
</tgroup>

Il contenuto di un'intestazione o del corpo sono le righe, normalmente descritte semplicemente con l'elemento row:

<row>
    <entry>
        contenuto_della_cella
    </entry>
    ...
</row>

Si osservi che il contenuto di una cella può essere un testo lineare oppure uno o più blocchi.

459.5.3   Immagini

L'inserzione di immagini può avvenire in contesti differenti, utilizzando elementi appropriati che attribuiscono un senso al tipo di immagine che si va a includere. Il modo più generalizzato per inserire un'immagine è attraverso l'uso dell'elemento mediaobject o di inlinemediaobject: il primo per le immagini che costituiscono un blocco a parte, mentre il secondo consente l'inserzione all'interno di un testo lineare. Inoltre, quando si inserisce un'immagine che costituisce un blocco autonomo, questa la si può inserire nell'elemento figure o nell'elemento informalfigure; entrambi consentono di controllarne la fluttuazione per motivi tipografici, mentre solo il primo permette di aggiungere un titolo alla figura.

<informalfigure [float="0"|"0"]>
    figura
    ...
</informalfigure>
<figure [float="0"|"0"]>
    [<title>titolo</title>]
    figura
    ...
</figure>

I due modelli sintattici riepilogano in modo molto semplificato l'uso degli involucri costituiti dagli elementi informalfigure e figure. Come si può intuire, assegnando il valore uno all'attributo float si rende fluttuante la figura contenuta.

Anche gli elementi mediaobject o di inlinemediaobject sono contenitori di altri più specifici per poter fare riferimento a un file esterno contenente un'immagine. Come accennato, il primo si presta all'uso in un blocco a sé stante, mentre il secondo per l'inserimento in un testo lineare. Nel caso si utilizzi un involucro del tipo figure o informalfigure, si deve utilizzare mediaobject.

<inlinemediaobject>|<mediaobject>
    <imageobject>
        <imagedata fileref="file_esterno" format="nome_formato">
    </imageobject>
    ...
    [<textobject>
        blocchi_di_testo
    </textobject>]
</inlinemediaobject>|</mediaobject>

Il modello sintattico descrive in modo molto semplificato l'uso degli elementi inlinemediaobject e mediaobject, tralasciando la possibilità per il secondo di inserire una didascalia nell'elemento caption.(1)

Come si può vedere dal modello, si possono inserire più elementi imageobject, ognuno per indicare il riferimento a un'immagine in forma diversa, da usare in alternativa alle altre, secondo le caratteristiche del tipo di composizione attuato. In questa ottica va visto anche l'elemento textobject che serve a contenere dei blocchi di testo normali, per descrivere l'oggetto quando questo non può essere visualizzato in alcun modo. L'esempio seguente mostra l'inserimento di un'immagine, senza l'involucro figure, in cui appare il riferimento a due formati differenti, ognuno adatto a un sistema di composizione particolare, assieme a un'annotazione alternativa:

<mediaobject>
    <imageobject>
        <imagedata fileref="prova.jpg" format="jpg"
    </imageobject>
    <imageobject>
        <imagedata fileref="prova.eps" format="eps"
    </imageobject>
    <textobject>
        <para>una figura qualunque</para>
    </textobject>
    <caption>
        <para>Questa &egrave; una prova</para>
    </caption>
</mediaobject>

459.5.4   Riferimenti interni ed esterni

I riferimenti interni al documento si fanno inserendo delle ancore per mezzo dell'attributo id disponibile nella maggior parte degli elementi:

<nome_elemento id="stringa_di_identificazione">...</nome_elemento>

Eventualmente è disponibile anche un elemento aggiuntivo il cui solo scopo è quello di consentire l'inserimento di un'ancora in quel punto particolare; si tratta dell'elemento anchor che è vuoto:

<anchor id="stringa_di_identificazione"/>

Per fare riferimento alle ancore inserite nel documento stesso, si possono usare due modi, attraverso gli elementi link e xref. Nel primo caso si ottiene un riferimento ipertestuale attraverso il testo delimitato dall'elemento link, valido quindi solo in una composizione che consenta questo tipo di utilizzo, mentre l'elemento xref è vuoto e fa apparire il numero della sezione o un altro riferimento visivo:

<link linkend="stringa_di_identificazione">...</link>
<xref linkend="stringa_di_identificazione"/>

I riferimenti esterni si fanno normalmente attraverso degli indirizzi URI; per questi è a disposizione l'elemento ulink che si usa con l'attributo url:

<ulink url="indirizzo_uri">testo_del_riferimento</ulink>

A seconda della composizione finale, l'indirizzo URI a cui si fa riferimento potrebbe apparire oppure no.

459.6   Conclusione

DocBook è un sistema SGML/XML molto complesso e ancora lontano dall'avere trovato una struttura definitiva. Data la disponibilità di una quantità così grande di elementi, che spesso si equivalgono, oltre alla grande libertà con cui questi possono essere usati, fa sì che l'uso effettivo di DocBook dipenda principalmente da due fattori: le capacità reali del sistema di composizione e dalla guida di stile stabilita per il progetto editoriale a cui si vuole partecipare con DocBook.

In altri termini, la struttura di DocBook non dà implicitamente dei limiti e difficilmente un autore può conoscere perfettamente il contesto corretto per ogni elemento; pertanto, diventa indispensabile la definizione di una guida di stile per l'uso di DocBook; guida che può essere molto diversa da un progetto editoriale a un altro.

459.7   Riferimenti

Appunti di informatica libera 2007.02 --- Copyright © 2000-2007 Daniele Giacomini -- <daniele (ad) swlibero·org>


1) Si osservi che in questo caso si tratterebbe di una didascalia vera e propria e non di un titolo come si fa nell'elemento figure.


Dovrebbe essere possibile fare riferimento a questa pagina anche con il nome introduzione_a_docbook.htm

[successivo] [precedente] [inizio] [fine] [indice generale] [indice ridotto] [indice analitico]

Valid ISO-HTML!

CSS validator!