| Firebird Documentation Index → Come fare il manuale di Firebird → Ricostruire la documentazione di Firebird |
|
|
|
Si utilizzano alcuni strumenti JAVA per produrre la documentazione in formato HTML e PDF a partire dal formato XML DocBook. Pertanto è necessaria una versione recente di Java 2 installata nel sistema.
Nelle prossime sezioni si spiega:
Da dove prelevare Java 2
Da dove recuperare gli strumenti
Come impostare l'ambiente operativo per il processo di ricostruzione dei documenti
Come costruire i documenti sia HTML che PDF
Se si ha già una versione di Java 2 installata, si può saltare il primo passo.
Scaricate ed installate solo uno dei seguenti:
Java 2 Runtime Environment, Standard Edition – spesso abbreviato con J2RE SE.
Vai a http://www.java.com/ e segui i link per le pagine di download. Scarica la versione idonea al tuo sistema operativo. Cliccando su un link del tipo "Download" oppure "Get it now" può comparire una scheda che chiede l'accordo affinché Sun Microsystems installi il tutto sul computer. Confermando, praticamente il tutto si installa automaticamente. Se non sembra chiaro, si può anche scaricare il programma di installazione e lanciarlo dal proprio computer.
Java 2 Software Development Kit, Standard Edition – spesso abbreviato con J2SDK SE.
Questo è un pacchetto molto più grande, e contiene già il precedente J2RE SE. Se si desidera installare questo SDK, si trova a http://java.sun.com/j2se/ dove c'è l'ultima versione stabile. Dovendo scegliere tra JRE e SDK, prendete il secondo (SDK). Certamente, si può ottenere J2RE dal SDK, ma è più facile e rapido dalla prima opzione. Ad ogni modo, si scarica il programma di installazione e lo si lancia.
Se non è chiara la differenza fra i due, prendi il primo: J2RE. Non è necessario l'SDK per costruire i documenti.
Gli strumenti necessari per ricostruire i documenti HTML e PDF
sono distribuiti in file Java JAR e archivi ZIP, e di solito li teniamo nel deposito
CVS in modo che siano scaricati automaticamente nella giusta posizione
quando si fa il checkout del modulo sorgente del manuale. Tuttavia non è
buona cosa lasciare grandi oggetti binari nel CVS, specialmente se i
relativi sorgenti sono gestiti anche altrove (sono tutti strumenti
open-source). Pertanto attualmente non mettiamo più le nuove versioni
degli strumenti nel CVS, ma sono mantenute nel sito web di Firebird per
poterli scaricare.
Dopo il checkout del modulo del manuale, controllare nella
directory manual/lib. Contiene il
file _readme_libs.txt con le istruzioni esatte per
scaricare ed installare le librerie mancanti. Similmente,
_readme_tools.txt in manual/tools informa da dove scaricare
alcuni strumenti utili richiesti.
Le procedure di ricostruzione hanno bisogno della variabile di
ambiente JAVA_HOME che punta all'installazione di Java
2.
In Windows versione italiana, questo è di solito in
C:\Programmi\Java\j2re1.4.2_01. Per esserne
sicuri, controllare se c'è un direttorio di nome
bin all'interno di esso e se il sottodirettorio
bin contiene un programma di nome
java.exe
In Linux, di solito è in
/usr/lib/java/jre oppure
/usr/java/j2sdk, oppure... be', potrebbe essere
in un bel po' di posti diversi. Ad ogni modo si deve controllare se
c'è un sottodirettorio bin che contiene un file
eseguibile java (senza l'estensione
.exe in questo caso).
Nel caso sfortunato in cui la variabile d'ambiente
JAVA_HOME non sia già presente e corretta, va impostata
correttamente e in Windows (versione italiana) con il comando
set JAVA_HOME=C:\Programmi\Java\j2re1.4.2_01 o sotto
Linux/bash con export JAVA_HOME=/usr/lib/java/jre.
(Nota bene: questi sono solo esempi, i comandi corretti potrebbero non
essere quelli indicati per versioni diverse di Java e di sistema
operativo.)
Suggerimento: rendete la variabile JAVA_HOME
permanente in modo da non doverla impostare ogni volta. Dipende dal
sistema operativo il modo in cui farlo. Consultate la documentazione se
necessario.
Se siete arrivati fin qui, adesso siete pronti per costruire i manuali di Firebird. Ecco cosa c'è da fare:
Se non è già stato fatto, è il momento di leggere il documento
ReadMe che è nel direttorio
manual. Può contenere informazioni importanti
che non sono (ancora) incluse in questo testo.
Se sei in ambiente grafico, apri una finestra a linea di comando.
A meno che il ReadMe dia istruzioni
diverse, andate al direttorio manual/src/build
e date il comando
build (in Windows), oppure
./build.sh (in Linux)
Se tutto è stato impostato correttamente, si ottiene un certo
numero di linee stampate che terminano con BUILD
SUCCESSFUL, e che parlano di certi build
targets (cose che si possono costruire).
Ora, si può costruire qualcosa di più concreto, cioè:
build html oppure
build pdf oppure
build docs
Qualsiasi cosa venga fatta starà nell'albero dei direttori
sotto manual/dist
Costruendo il file PDF si ricevono moltissimi messaggi di
errore. Si possono tranquillamente ignorare, l'importante è che
nelle ultime linee si legga BUILD
SUCCESSFUL.
A causa di alcune limiti nel software di ricostruzione, alcuni file PDF possono necessitare di essere rifiniti a mano, per renderli presentabili. Per uso personale vanno benissimo, nel senso che «c'è dentro tutto». Nel caso si desiderasse migliorarli, si legga la sezione verso la fine di questa guida riguardo il perfezionamento dei documenti PDF.
Se la copia locale del modulo del manuale è in un percorso che
contiene nel nome degli spazi o altri caratteri speciali non
alfanumerici, la ricostruzione del PDF può non funzionare perché un
file intermedio viene posto in un percorso creato ex-novo con lo
stesso nome, tranne per il fatto che tutti i caratteri
«dannosi» vengono sostituiti con la loro controparte
codificata URL: gli spazi diventano %20,
ecc.
Anche la costruzione del file monohtml (sarebbe come html, ma è costituito da una sola lunghissima pagina web) va a finire dentro il percorso codificato come URL. Invece le immagini che dovrebbero andarci insieme sono salvate nel percorso originale. Tutto questo ambaradàn è causato da una classe Java che ha alcuni compiti durante la costruzione ma purtroppo anche converte in URL i nomi dei percorsi durante il processo.
Il miglior modo per evitare questi problemi è mettere il modulo del manuale in un percorso che contenga solo lettere non accentate, numeri e i caratteri '-' e '_'. La seconda scelta è rendere il percorso codificato come URL un link simbolico al reale percorso originale. Dopo aver fatto il link simbolico, tutte le costruzioni future andranno a meraviglia. Tuttavia questo potrebbe non essere fattibile in Windows.
Per costruire la documentazione in lingua non inglese (man mano
che si rende disponibile) si usa il parametro
-Dsfx assegnandogli il codice della lingua,
cioè:
build pdf -Dsfx=es
build html -Dsfx=fr
build monohtml -Dsfx=it
I documenti in lingua vengono distribuiti nei rispettivi
direttori: manual/dist/pdf/it,
manual/dist/pdf/ru,
manual/dist/html/fr, etc.
Senza specificare il parametro -Dsfx,
viene costruito il manuale inglese.
Non tutte le lingue hanno la stessa quantità di documenti. Questo dipende dall'attività degli scrittori e dei traduttori. Di solito la parte in inglese è la più aggiornata e la più completa.
Gli esempi fatti finora producono l'intero insieme (per una
lingua). Di solito però non è questo che si vuole ottenere. Per
generare uno specifico documento (esempio un libro o un articolo
particolare) si usa il parametro -Did.
Con l'argomento -Did si deve specificare
l'ID dell'elemento da costruire, ad esempio:
build pdf -Did=fbutils
build pdf -Dsfx=fr -Did=qsg15-fr
Come conoscere l'ID? Si trova nei sorgenti XML DocBook. Si deve
cercare l'attributo id negli
elementi quali book (libro),
article (articolo), and chapter (capitolo). Per saperne di più su
questo argomento, consultare il manuale per Scrivere
Documenti per Firebird.
Come si vede nell'ultimo esempio, gli argomenti possono essere insieme.
A partire dal gennaio del 2006, le Note di Rilascio (Release
Notes) sono state integrate col modulo del manuale, ma costituiscono
un insieme da sole, parallelo all'insieme dei documenti
«firebirddocs». Questo ha generato un
altro parametro, -Dbase, il cui valore deve
essere «rlsnotes» per costruire le
Release Notes:
build pdf -Dbase=rlsnotes
build pdf -Dbase=rlsnotes -Did=rlsnotes210 -Dsfx=it
build pdf -Dbase=rlsnotes -Dsfx=fr
Nel frattempo sono stati aggiunti altri due insiemi,
papers e refdocs, non ancora
tradotti in italiano.
Il risultato di vari insiemi è scritto nei soliti direttori,
tranne in un caso: il multi-file documento finale di tipo
html è messo in
manual/dist/html-<base>, per evitare
ambiguità con altri insiemi e pertanto i vari file
index.html non si sovrascrivono l'un l'altro. Gli
insiemi non in inglese vanno in
manual/dist/html-<base>/<sfx>. Per
esempio le note di rilascio in inglese sono scritte in
manual/dist/html-rlsnotes, quelle in francese
invece in manual/dist/html-rlsnotes/fr.
La trasformazione in monohtml e
pdf andando nel solito sottodirettorio non
causa problemi, in quanto questa termina in un file singolo con un
solo nome.
Ci si ritrova spesso a ricostruire sempre il solito insieme,
sempre nella stessa lingua e sempre quel documento? Allora è il caso
di impostare i corrispondenti valori dei parametri nel file di
controllo della ricostruzione, cioè build.xml, in
modo da non doverli digitare ogni volta sulla linea di comando. Le
istruzioni si trovano circa in cima al file
build.xml, vicino alla parola
init.
Ovviamente, facendo uso di questa caratteristica, si possono
ancora costruire le altre cose specificando le proprie intenzioni
sulla linea di comando. Per esempio, nel caso in cui si sia impostato
base a rlsnotes nel file di
impostazione dei default, si può costruire l'insieme completo standard
con:
build html -Dbase=firebirddocs
Ecco fatto – adesso si è un perfetto ricostruttore patentato di documenti per Firebird. Congratulazioni!
Per scrivere o tradurre altri documenti per il Progetto Firebird leggi anche Scrivere documenti per Firebird.
|
| Firebird Documentation Index → Come fare il manuale di Firebird → Ricostruire la documentazione di Firebird |