Firebird Documentation IndexScrivere documenti per Firebird → Impostare il vostro documento DocBook
Firebird Home Firebird Home Indietro: Strumenti per scrivere in DocBook XMLFirebird Documentation IndexRisali: Scrivere documenti per FirebirdAvanti: Gli elementi che si usano più di frequente

Impostare il vostro documento DocBook

Creare il documento
Scrivere il testo

Bene, ci siete? So che abbiamo passato un po' di tempo spiegando XML e DocBook, ma sono realmente convinto che fosse necessario perchè sono concetti nuovi per molta gente. Dando solo dei link e dicendo di trovarsi da soli come fare, ci avrebbe fatto perdere degli scrittori di documentazione altrimenti validi.

Comunque, siamo arrivati e siamo pronti a scrivere il documento. Questa sezione spiega come impostare il documento DocBook; la successiva spiega come applicare i marcatori giusti al posto giusto.

Creare il documento

Ogni documento nel nostro manuale è parte di un <set>. Questo è l'elemento in cima nella gerarchia di DocBook. Un set (lett. insieme) contiene un certo numero di <book>s (cioè libro/i), che a loro volta contengono <chapter>s (cioè capitolo/i), e così via.

Un vantaggio di mettere i libri in un insieme è che si possono fare riferimenti l'un l'altro, cioè si possono porre link in un documento che puntano esattamente ad una precisa posizione in un altro libro. Questo vantaggio è limitato dal fatto che non funzionano tra file PDF diversi (un limite che non esiste nei file HTML). Un altro vantaggio è la creazione automatica dell'indice, detta anche tabella dei contenuti o ToC (acronimo di Table of Contents).

Fortunatamente, mettere i libri in un unico set non implica necessariamente che debbano generare un solo grande file. DocBook permette di impostare un documento principale, come mostrato sotto. Al momento non si consideri la sezione che inizia con "<!DOCTYPE" fino a tutto il segno "]>": non si avrà mai il bisogno di scrivere da soli una cosa così orribile. Alla peggio si copia una riga e la si edita, oppure, se si deve tradurre un set esistente in un nuovo linguaggio, si copia con altro nome e si modifica l'intero documento principale da una versione esistente; ad esempio per la versione italiana, ho copiato e modificato l'originale versione inglese.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  "docbookx/docbookx.dtd" [
    <!ENTITY preface SYSTEM "firebirddocs/preface.xml">
    <!ENTITY fb-intro SYSTEM "firebirddocs/firebirdintro.xml">
    <!ENTITY ...>
    <!ENTITY ...>
]>

<set id="firebird-books">
  &preface;
  &fb-intro;
  ...
  ...
</set>

Con il documento principale impostato come sopra, i vari libri possono essere in file distinti: preface.xml, firebirdintro.xml, ecc., il che permette di editarli indipendentemente. Il libro, ad esempio quello che si sta' scrivendo, è pressapoco strutturato così:

<?xml version="1.0" encoding="UTF-8"?>

<book id="fbintro">
  <chapter id="fbintro-preface">
    ...
    ...
  </chapter>
  <chapter id="fbintro-installing-firebird">
    ...
    ...
  </chapter>
  ...
  ...
</book>

Naturalmente, scrivendo un nuovo documento, questo deve essere fatto riconoscere all'insieme principale, ma di questo se ne parlerà quando si sarà pronti a scrivere. Al momento non si può dare una regola generale, in quanto dipende da quello che si intende scrivere: un libro, un articolo, un capitolo, un paio di capitoli... e da come il lavoro si incastra con il resto già esistente.

Ogni documento DocBook deve iniziare con questa linea:

<?xml version="1.0" encoding="UTF-8"?>

(Notare che per alcune lingue, UTF-16 dovrebbe essere la scelta migliore.)

Se si scrive il documento in un editor di testi, cioè testo XML «nudo e crudo», bisogna scriversi quella linea così com'è. Usando un editor specifico per XML, viene inserita automaticamente creando un nuovo documento.

Posizioni degli insiemi in funzione del linguaggio

I files del set di documentazione per l'inglese deve essere posto nell'albero di directory manual/src/docs/firebirddocs. I documenti in altre lingue vanno nell'albero della directory della lingua: ad esempio, per il francese manual/src/docs/firebirddocs-fr, per lo spagnolo manual/src/docs/firebirddocs-es, per l'italiano in manual/src/docs/firebirddocs-it, ecc.

A partire dal gennaio 2006 c'è la possibilità di creare set di base aggiuntivi, il primo dei quali è stato rlsnotes, l'insieme delle Release Notes (note di versione). Anche in questo caso si utilizza la stessa logica: le Release Notes in inglese vanno in manual/src/docs/rlsnotes, in francese in manual/src/docs/rlsnotes-fr, e così via.

Ognuno di questi alberi di directory (firebirddocs, firebirddocs-es, firebirddocs-nl, rlsnotes, rlsnotes-it, ecc.) contiene un diverso <set>, con un documento principale (master document) ed un certo numero di file da includere (include files).

Scrivere il testo

Scrivendo DocBook XML con un text editor come il Blocco Note di Windows, emacs oppure ConText, si può andare a capo, usare l'indentazione, e spaziare il testo a piacere. Ogni «spazio bianco» (whitespace), cioè una sequenza di uno o più caratteri spazio, tabulazione, a capo, salto pagina (space, tab, linefeed, formfeed), viene convertito in un singolo carattere di spazio in uscita. Così:

<section><title>Firebird Architectures</title><para>Now let's have a
look at Firebird's different architectures.</para><itemizedlist>
<listitem><para>First, there's the so-called <firstterm>Classic Server
</firstterm>.</para></listitem><listitem><para>Then there is <firstterm>
Superserver</firstterm> architecture.</para></listitem><listitem><para>
And finally, with the release of Firebird 1.5 we also have the 
<firstterm>embedded server</firstterm>.</para></listitem></itemizedlist>
</section>

avrà lo stesso aspetto di questo:

<section>
  <title>Firebird Architectures</title>
  <para>Now let's have a look at Firebird's different
    architectures.</para>
  <itemizedlist>
    <listitem>
      <para>First, there's the so-called 
        <firstterm>Classic Server</firstterm>.</para>
    </listitem>
    <listitem>
      <para>Then there is <firstterm>Superserver</firstterm> 
        architecture.</para>
    </listitem>
    <listitem>
      <para>And finally, with the release of Firebird 1.5 we also
        have the <firstterm>embedded server</firstterm>.</para>
    </listitem>
  </itemizedlist>
</section>

Inutile a dirsi, questa seconda forma è molto più facile da leggere e capire da parte di una persona. Così, scrivendo il testo XML in chiaro, è meglio formattare il testo in modo che la struttura sia la più chiara possibile.

Usando un editor XML dedicato, bisogna rendersi conto che il tasto Invio chiude automaticamente il <para>grafo corrente e ne apre uno nuovo. Quindi bisogna essere coscienti di come il proprio editor si comporta sotto questo aspetto e comportarsi di conseguenza. Inoltre bisogna verificare cosa succede quando si premono spazi successivi, poichè alcuni editor XML possono usare trucchi speciali per conservali.

Indietro: Strumenti per scrivere in DocBook XMLFirebird Documentation IndexRisali: Scrivere documenti per FirebirdAvanti: Gli elementi che si usano più di frequente
Firebird Documentation IndexScrivere documenti per Firebird → Impostare il vostro documento DocBook