NOME
po4a−build.conf − file di configurazione per la creazione dei contenuti tradotti
Introduzione
po4a−build.conf descrive come "po4a−build" dovrebbe creare la documentazione tradotta e non tradotta da un insieme di documenti sorgenti non tradotti e dai loro file PO corrispondenti.
Tutti i formati supportati, in tutte le combinazioni supportate, possono essere gestiti in un singolo file di configurazione po4a−build.conf ed in una singola chiamata a "po4a−build". Comunque, è anche possibile scegliere di separare le cartelle po/ ed avere un file di configurazione per ogni esecuzione (eseguendo "po4a−build −f FILE" per ognuna).
Si noti che malgrado po4a−build includa il supporto a gettext per la traduzione di messaggi di uscita di script, po4a−build.conf in sè non ha alcuna attinenza con tali traduzioni. po4a−build.conf si occupa solo della traduzione di contenuto statico come le pagine man.
Per il supporto di po4a−build alla traduzione di messaggi a runtime, vedere po4a−runtime(7).
Formati supportati
Attualmente,
"po4a−build" supporta le seguenti
combinazioni:
DocBook XML per le sezioni 1 e 3
Tipicamente usato per le pagine man, per script di shell o per altri interpreti che non possiedono un proprio formato di documentazione come il POD. L ’idoneo XML può essere generato direttamente da una pagina man esistente usando "doclifter"(1) e "po4a−build" genererà un file POT senza ulteriore lavoro. Il file POT può poi essere distribuito per la traduzione e i file PO essere aggiunti alla rispettiva cartella po/. "po4a−build" poi preparerà non solo la pagina man non tradotta dal "doclifter" XML ma anche userà "po4a" per preparare gli XML tradotti dai file PO e poi creerà le pagine man tradotte dall’ XML.
Le pagine man vengono generate usando il supporto predefinito nel docbook-xsl − il foglio di stile usato può essere scavalcato usando l’impostazione "XSLFILE" nel file di configurazione "po4a−build".
DocBook XML per HTML
Il foglio di stile predefinito usato per preparare l’ HTML finale può essere scavalcato usando l’impostazione "HTMLXSL" nel file di configurazione "po4a−build".
POD per le sezioni 1, 3, 5 e 7
pod2man viene usato per convertire contenuto POD per ognuna delle sezioni supportate.
Usare "PODFILE" per la sezione 1, "PODMODULES" per la sezione 3, "POD5FILES" per la sezione 5 e "POD7FILES" per la sezione 7.
Per il contenuto nelle sezioni 5 o 7 (che tendono ad aver bisogno di un nomefile che viene usato anche per il contenuto della sezione 1), se il nomefile include 5 o 7 come parte del nomefile, questo (e qualsiasi estensione del nomefile) verrà automaticamente rimosso.
cioè per preparare /usr/share/man/man7/po4a.7.gz:
# File POD per la sezione 7 POD7FILES="doc/po4a.7.pod"
Contenuti del file
I valori di configurazione possono apparire in qualsiasi ordine nel file di configurazione.
Qualunque contenuto dopo un "#" viene ignorato.
Qualsiasi valore che sarebbe sempre vuoto può essere eliminato dal file.
Alcuni campi di
configurazione sono richiesti −
po4a−build può finire col non generare
nulla se i campi indispensabili sono lasciati vuoti.
CONFIG
Necessario.
Nome e posizione del file di configurazione (temporaneo) "po4a" che "po4a−build" genererà e manterrà. Questo file non serve che viva nel sistema di controllo versione e può essere tranquillamente cancellato durante la creazione del pacchetto.
# nome e posizione del file di configurazione CONFIG="_build/po4a.config"
PODIR
Necessario.
La cartella contenente i file PO per TUTTE le traduzioni gestite da questo file di configurazione. Tutte le stringhe verranno fuse in un file POT in questa cartella e tutti i file PO fusi con quel file POT. Qualunque soglia di mantenimento ( KEEP, vedere sotto) verrà applicata a tutte le stringhe da tutti i file in ingressospecificati in questo file e tutti i file PO in questa cartella. La cartella non è necessario che venga chiamata "po". Si noti, comunque, che qualche software di statistica si aspetta che questa si chiami "po", perciò si raccomanda di mantenere questo nome.
# cartella po per le pagine man/documenti PODIR="po/pod"
POTFILE
Necessario.
Percorso al file POT (relativo alla posizione di questo file di configurazione) che verrà generato, mantenuto ed aggiornato da "po4a−build" per queste traduzioni.
# Percorso file POT POTFILE="po/pod/po4a−pod.pot"
BASEDIR
Necessario.
Cartella di base per la scrittura dei contenuti tradotti.
# cartella di base per i file generati, cioè i doc.ti BASEDIR="_build"
BINARIES
Necessario.
Anche se viene creato solo un pacchetto, qui è richiesto almeno un valore.
La stringa in sè è arbitraria ma tipicamente consiste nel nome del pacchetto. Il contenuto generato apparirà allora in sottocartelle di BASEDIR/BINARIES :
_build/po4a/man/man1/foo.1
Se il pacchetto crea più di un pacchetto binario (cioè un pacchetto sorgente e più file .deb o .rpm), questo campo può aiutare ad isolare il contenuto inteso per ogni obiettivo, facilitanto l’automatismo del processo di compilazione.
Separa le stringhe con uno spazio.
# pacchetti binari che conterranno le pagine man generate BINARIES="po4a"
KEEP
Valore da passare direttamente a "po4a −k" per specificare la soglia per il contenuto tradotto correttamente prima che una particolare traduzione venga omessa dalla compilazione. Lasciare vuoto o rimuovere per usare il valore predefinito (80%) o specificare zero per forzare l’inclusione di tutti i contenuti, anche se completamente non tradotti.
Per avere il controllo totale su tale comportamento è necessario valutare accuratamente quali file sono assegnati a quali file di configurazione po4a−build.conf.
Si noti che avere molti file in un file POT può essere conveniente per i traduttori, specialmente se i file hanno stringhe in comune. Per contro, i file POT con migliaia di stringhe lunghe sono impegnativi per i traduttori, e tendono a portare a periodi di string freeze molto lunghi.
# soglia minima della percentuale di traduzione per poterla mantenere KEEP=
XMLMAN1
I file XML DocBook per generare le pagine man in sezione 1. Separare i nomi dei file con spazi. Tutti i file devono essere nella cartella XMLDIR.
È pratica comune usare più file XML in un libro, in modo da gestire un indice, ecc. Se il libro contiene file specificati anche in XMLMAN3, specificare qui solo i file XML per la sezione 1, non nel libro. Se il libro contiene solo contenuti per questa sezione, specificare solo il file del libro.
# file XML DocBook per la sezione 1 XMLMAN1="po4a−build.xml po4aman−display−po.xml po4apod−display−po.xml"
XMLMAN3
File XML DocBook per generare le pagine man in sezione 3. Nomi file separati da spazi. Tutti i file devono essere nella cartella XMLDIR.
È pratica comune mettere più file XML in un libro, in modo da fornire un indice, ecc. Se il libro contiene file specificati anche in XMLMAN1, specificare qui solo i file XML per la sezione 3, non il libro. Se il libro contiene solo materiale per questa sezione, specificare solo il file del libro.
# File XML DocBook per la sezione 3 XMLMAN3=""
XMLDIR
Posizione di tutti i file XML DocBook. Attualmente, "po4a−build" si aspetta di essere in grado di trovare tutti i file elencati in XMLMAN1 e XMLMAN3 cercando file *.xml in questa cartella.
Deve essere specificato se vengono usati XMLMAN1 o XMLMAN3. I percorsi sono relativi alla posizione del file di configurazione.
# posizione dei file XML XMLDIR="share/doc/"
XMLPACKAGES
Quali pacchetti, dall’elenco in BINARIES, usano contenuto sorgente XML.
Se viene specificato un qualunque valore in XMLMAN1 o XMLMAN3, deve essere dato anche qui un valore.
# pacchetti binari che usano XML DocBook & xsltproc XMLPACKAGES="po4a"
DOCBOOKDIR
Simile a XMLDIR ma usata solo per preparare i file DocBook tradotti. Se il pacchetto vuole usare file .sgml, sarà meglio discutere come questi devono essere creati sulla mailing list po4a−devel.
# modello per trovare i file .docbook DOCBOOKDIR=""
XSLFILE
Foglio di stile XSL usato per preparare i contenuti tradotti e non tradotti dai file XML DocBook.
# file XSL da usare per l'XML DocBook XSLFILE="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"
PODFILE
File POD per la generazione del contenuto delle pagine man nella sezione 1. Separare i file POD con degli spazi. I percorsi, se usati, devono essere relativi alla posizione del file di configurazione specificato.
# file POD per la sezione 1 PODFILE="po4a po4a−gettextize po4a−normalize scripts/msguntypot"
PODMODULES
Supporto specializzato per il moduli Perl contenenti contenuti POD − il nome del modulo verrà ricostruito dal percorso (così questo dovrebbe essere la disposizione tipica Perl) e le pagine man vengono automaticamente messe nella sezione 3.
# File POD per la sezione 3 − nomi dei moduli rigenerati dal percorso PODMODULES="lib/Locale/Po4a/*.pm"
POD5FILES
Contenuti POD arbitrari usati per la generazione delle pagine man per la sezione 5. I percorsi, se usati, devono essere relativi alla posizione del file di configurazione specificato.
Per il contenuto nelle sezioni 5 o 7 (che tendono ad aver bisogno di un nomefile che viene usato anche per il contenuto della sezione 1), se il nomefile include 5 o 7 come parte del nomefile, questo (e qualsiasi estensione del nomefile) verrà automaticamente rimosso.
# File POD per la sezione 5 POD5FILES="doc/po4a−build.conf.5.pod"
POD7FILES
Contenuti POD arbitrari usati per la generazione delle pagine man per la sezione 7. I Percorsi, se usati, devono essere relativi alla posizione del file di configurazione specificato.
Per il contenuto nelle sezioni 5 o 7 (che tendono ad aver bisogno di un nomefile che viene usato anche per il contenuto della sezione 1), se il nomefile include 5 o 7 come parte del nomefile, questo (e qualsiasi estensione del nomefile) verrà automaticamente rimosso.
# File POD per la sezione 7 POD7FILES="doc/po4a.7.pod"
PODPACKAGES
Simile a XMLPACKAGES − ogni pacchetto che si aspetta contenuti creati da file POD deve inserire un valore in PODPACKAGES. Richiesto se viene specificato un valore qualsiasi per PODFILE, PODMODULES, POD5FILES o POD7FILES.
# pacchetti binari che usano POD PODPACKAGES="po4a"
HTMLDIR
Sottocartella di BASEDIR da usare per inserire i risultati HTML tradotti e non tradotti.
# Risultati HTML (sottocartella di BASEDIR) HTMLDIR=""
HTMLFILE
File DocBook da convertire in HTML (può essere lo stesso di uno dei file in XMLMAN1 o XMLMAN3 ). Le sezioni non sono rilevanti per il risultato HTML, perciò qui si è liberi di usare il file book singolo in modo che l’ HTML abbia un indice ecc.
# File DocBook HTML HTMLFILE=""
HTMLXSL
L’impostazione predefinita usa un foglio di stile XSL a spezzoni. Attualmente non è supportato l’uso di più di un foglio di stile per esecuzione HTML.
# file XSL da usare per l'HTML HTMLXSL="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"
AUTORI
Neil Williams <linux [AT] codehelp.uk>
TRADUZIONE
Danilo Piazzalunga <danilopiazza [AT] libero.it> Marco Ciampa <ciampix [AT] libero.it>