| Documenti Firebird → Agli scrittori per Firebird → 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 dei Java JARs file, 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 si dovrebbero lasciare librerie compilate nel CVS, specialmente se i relativi sorgenti sono gestiti 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.
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 controllate se c'è un sottodirettorio bin che contiene un file eseguibile java (senza .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 limitazioni del software di costruzione, alcuni file PDF possono necessitare di qualche - noiosa - rifinitura da farsi 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 al perfezionamento dei documenti PDF.
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). Per costruire un manuale con solo una parte (esempio un libro o un articolo particolare) si usa il parametro -Drootid. Questo è utile quando si costruiscono i file PDF, perchè l'intero set diventa un solo grosso file di dimensioni enormi.
Con l'argomento -Drootid si deve specificare l'ID dell'elemento da costruire, ad esempio:
build pdf -Drootid=fbutils
build pdf -Dsfx=fr -Drootid=qsg15-fr
Come conoscere l'ID? Si trova nei sorgenti XML DocBook. Ma questo è parte del manuale per Scrivere Documenti per Firebird. L'uso del parametro -Drootid è tipicamente riservato a chi scrive/traduce i manuali, non a chi li ricostruisce solamente.
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, -Dbasename, il cui valore deve essere “rlsnotes” per costruire le Release Notes:
build pdf -Dbasename=rlsnotes
build pdf -Dbasename=rlsnotes -Drootid=rlsnotes20
build pdf -Dbasename=rlsnotes -Dsfx=fr
In futuro potrebbero essere aggiunti altri insiemi.
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-<basename>, 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-<basename>/<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 basename a rlsnotes nel file di impostazione dei default, si può costruire l'insieme completo standard con:
build html -Dbasename=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 Firebird Docwriting Guide (in inglese).
|
| Documenti Firebird → Agli scrittori per Firebird → Come fare il manuale di Firebird → Ricostruire la documentazione di Firebird |