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

Strumenti Po4a                                     2023-01-03                            Locale::Po4a::Sgml(3pm)