Locale::Po4a::Sgml - converte documenti SGML da/a file PO
Lo scopo del progetto po4a (PO for anything - PO per tutto)
è di facilitare la traduzione e, cosa ancor più interessante,
la manutenzione delle traduzioni usando gettext e i relativi strumenti in
campi in cui il loro uso non era programmato, come la documentazione.
Locale::Po4a::Sgml è un modulo che aiuta la traduzione in
altre lingue della documentazione in formato SGML.
This module uses onsgmls(1) to parse the SGML files. Make
sure it is installed. Also make sure that the DTD of the SGML files are
installed in the system.
- debug
- Elenco di parole chiave, separate da spazi, indicanti le parti di cui fare
il debug. I valori ammessi sono: «tag»,
«generic», «entities» e
«refs».
- verbose
- Mostra più informazioni su quello che sta accadendo.
- translate
- Space separated list of extra tags (beside the DTD provided ones) whose
content should form an extra msgid.
- section
- Space separated list of extra tags (beside the DTD provided ones)
containing other tags, some of them being of category
translate.
- indent
- Space separated list of tags which increase the indentation level.
- verbatim
- Il layout all'interno di questi tag non deve essere modificato: i
paragrafi non verranno mandati a capo, non verrà aumentata
l'indentazione né verranno aggiunte nuove linee per ragioni
estetiche.
- empty
- Tag che non è necessario chiudere.
- ignore
- Tag ignorati e considerati come testo semplice da po4a, vale a dire che
possono far parte di un msgid. Ad esempio, <b> è un buon
candidato per questa categoria: metterlo nella sezione traducibile darebbe
luogo a dei msgid che non contengono frasi complete, condizione non
ideale.
- attributes
- A space separated list of attributes that need to be translated. You can
specify the attributes by their name (for example, "lang"), but
you can also prefix it with a tag hierarchy, to specify that this
attribute will only be translated when it is into the specified tag. For
example: <bbb><aaa>lang specifies that the lang attribute will
only be translated if it is in an <aaa> tag, which is in a
<bbb> tag. The tag names are actually regular expressions so you can
also write things like <aaa|bbbb>lang to only translate lang
attributes that are in an <aaa> or a <bbb> tag.
- qualify
- A space separated list of attributes for which the translation must be
qualified by the attribute name. Note that this setting automatically adds
the given attribute into the 'attributes' list too.
- force
- Procede anche se il DTD è sconosciuto o se onsgmls trova errori nel
file in ingresso.
- include-all
- I msgid che contengono solo un'entità (come
«&version;») vengono saltati per comodità del
traduttore. Attivare questa opzione impedisce questa ottimizzazione.
Può essere utile se il documento contiene una costruzione del tipo
«<title>È</title>», anche se è
difficile possa succedere...
- ignore-inclusion
- Elenco separato da spazi di entità che non saranno accodate. Usare
quest'opzione con cautela: può provocare in onsgmls (usato
internamente) l'aggiunta di tag ed invalidare così il documento in
uscita.
Il risultato è perfetto, ossia i documenti generati sono
identici. Rimane però ancora qualche problema:
- Gli errori scritti in uscita da onsgmls vengono rediretti in maniera
predefinita su /dev/null, il che è chiaramente sbagliato, ma non so
come fare per evitarlo.
Il problema è che devo "proteggere"
l'inclusione condizionale (cioè i vari
"<! [ %blabla [" e
"]]>") da onsgmls. Altrimenti
onsgmls se li mangia e non so come fare per farli ricomparire nel
documento finale. Per impedirlo, li riscrivo come
"{PO4A-beg-foo}" e
"{PO4A-end}".
Il problema con questo approccio è che i vari
"{PO4A-end}" che aggiungo non sono
validi nel documento (non in un tag <p> o simili).
If you want to view the onsgmls output, just add the following
to your command line (or po4a configuration line):
-o debug=onsgmls
- Funziona solo con i DTD DebianDoc e DocBook. Aggiungere supporto per un
nuovo dtd dovrebbe essere molto facile. Il meccanismo è lo stesso
per ogni DTD, basta soltanto fornire l'elenco dei tag esistenti e alcune
delle loro caratteristiche.
Sono d'accordo, avrebbe bisogno di maggiore documentazione, ma
è ancora considerato in fase di beta, e detesto documentare
qualcosa che potrebbe venir modificato in seguito.
- Attenzione, il supporto per i DTD è piuttosto sperimentale. Non ho
letto nessun manuale di riferimento per trovare le definizioni di tutti i
tag. Ho aggiunto definizioni dei tag al modulo finché non ha
funzionato per qualche documento che ho trovato in rete. Non
funzionerà se il documento fornito usa più tag del mio. Ma,
come ho appena detto, sistemarlo dovrebbe essere davvero facile.
Ho testato DocBook soltanto con SAG (acronimo di System
Administrator Guide, la famosa Guida degli amministratori di sistema di
Linux), ma si tratta di un documento piuttosto grosso, e dovrebbe usare
gran parte delle caratteristiche di DocBook.
Per quanto riguarda DebianDoc, ho testato qualche manuale del
DDP, ma non ancora tutti.
- Nel caso in cui si includano file, i riferimenti ai messaggi nei file po
(cioè le righe del tipo "#:
en/titletoc.sgml:9460") risulteranno sbagliati.
Questo perché prima il file viene pre-elaborato per
proteggere l'inclusione condizionale (cioè i vari
"<! [ %blabla [" e
"]]>") e qualche entità
(come &version;) da onsgmls perché le voglio così come
sono nel documento generato. Per questo motivo, faccio una copia
temporanea del file di input e applico alla copia tutte le modifiche che
voglio prima di sottoporlo all'analisi di onsgmls.
Per far sì che funzioni, sostituisco le entità
che richiedono l'inclusione di un file con il contenuto del file dato
(così posso proteggere anche ciò che si deve trovare anche
nei sotto-file). Ma nulla viene fatto fin'ora per correggere i
riferimenti (cioè i nomi dei file e i numeri di riga)
successivamente. Non sono sicuro di quale sia la cosa migliore da
fare.
Questo modulo è un adattamento di sgmlspl, (un
postprocessore SGML per il parser ONSGMLS) che era:
Copyright © 1995 by David Megginson <dmeggins@aix1.uottawa.ca>
Adattato per po4a da:
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)
Danilo Piazzalunga <danilopiazza@libero.it>
Marco Ciampa <ciampix@libero.it>
Copyright © 1995 by David Megginson <dmeggins@aix1.uottawa.ca>
Copyright © 2002-2005 by SPI, inc.
Questo programma è software libero; è lecito
ridistribuirlo o modificarlo secondo i termini della licenza GPL (vedere il
file COPYING).