Scroll to navigation

PO4A-BUILD.CONF(5) Strumenti Po4a PO4A-BUILD.CONF(5)

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:

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".

Il foglio di stile predefinito usato per preparare l'HTML finale può essere scavalcato usando l'impostazione "HTMLXSL" nel file di configurazione "po4a-build".
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.

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"
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"
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"
Necessario.

Cartella di base per la scrittura dei contenuti tradotti.

 # cartella di base per i file generati, cioè i doc.ti
 BASEDIR="_build"
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"
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=
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"
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=""
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/"
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"
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=""
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"
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"
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"
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"
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"
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"
Sottocartella di BASEDIR da usare per inserire i risultati HTML tradotti e non tradotti. 

 # Risultati HTML (sottocartella di BASEDIR)
 HTMLDIR=""
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=""
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@codehelp.co.uk>

TRADUZIONE

 Danilo Piazzalunga <danilopiazza@libero.it>
 Marco Ciampa <ciampix@libero.it>
2018-05-27 Strumenti Po4a