NOME

       Locale::Po4a::Sgml - converte documenti SGML da/a file PO

DESCRIZIONE

       L'obiettivo del progetto po4a (PO per tutto) è di facilitare le traduzioni (e cosa più
       interessante, la manutenzione delle traduzioni) usando gli strumenti associati a gettext
       in aree inaspettate come la documentazione.

       Locale::Po4a::Sgml è un modulo che aiuta la traduzione in altre lingue della
       documentazione in formato SGML.

       Questo modulo usa onsgmls(1) per analizzare i file SGML. Assicurati che sia installato.
       Assicurati anche che i DTD dei file SGML siano installati nel sistema.

OPZIONI ACCETTATE DA QUESTO MODULO

       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
           Elenco separato da spazi di tag extra (oltre a quelli forniti da DTD) il cui contenuto
           dovrebbe formare un msgstr in più.

       section
           Elenco separato da spazi di tag extra (oltre a quelli forniti dalla DTD) contenenti
           altri tag, alcuni dei quali sono di categoria translate.

       indent
           Elenco separato da spazi di tag che aumentano il livello di indentazione.

       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
           Un elenco di attributi separati da spazi che devono essere tradotti. È possibile
           specificare gli attributi in base al loro nome (ad esempio, "lang"), ma è anche
           possibile anteporre una gerarchia di tag, per specificare che questo attributo verrà
           tradotto solo quando si trova nel tag specificato. Ad esempio: <bbb><aaa>lang
           specifica che l'attributo lang verrà tradotto solo se si trova in un tag <aaa>, che è
           in un tag <bbb>. I nomi dei tag sono in realtà espressioni regolari, quindi si possono
           anche scrivere cose come <aaa|bbbb>lang per tradurre solo attributi lang che sono in
           nei tag <aaa> o <bbb>.

       qualify
           Un elenco di attributi separati da spazi per i quali la traduzione deve essere
           qualificata dal nome dell'attributo. Si noti che questa impostazione aggiunge
           automaticamente l'attributo dato anche nell'elenco 'attributes'.

       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>&Egrave;</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.

STATO DI QUESTO MODULO

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

         Se si vuole visualizzare l'uscita di onsgmls, aggiungere quanto segue alla riga di
         comando (o alla riga di configurazione di po4a):

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

AUTORI

       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)

TRADUZIONE

        Danilo Piazzalunga <danilopiazza@libero.it>
        Marco Ciampa <ciampix@posteo.net>

COPYRIGHT E LICENZA

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