
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 NOME

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

=head1 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 B<onsgmls>(1) per analizzare i file SGML. Assicurati che
sia installato. Assicurati anche che i DTD dei file SGML siano installati
nel sistema.

=head1 OPZIONI ACCETTATE DA QUESTO MODULO

=over 4

=item B<debug>

Elenco di parole chiave, separate da spazi, indicanti le categorie di
messaggi extra da mostrare a scopo diagnostico. I valori ammessi sono:
C<entities>, C<generic>, C<onsgml>, C<refs> e C<tag>.

=item B<verbose>

Mostra più informazioni su quello che sta accadendo.

=item B<translate>

Elenco separato da spazi di tag extra (oltre a quelli forniti dalla DTD) il
cui contenuto dovrebbe formare un msgstr in più, cioè che dovrebbe essere
tradotto.

=item B<section>

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

=item B<indent>

Elenco separato da spazi di marcatori che aumentano il livello di
indentazione. Ciò influenzerà l'indentazione nel documento risultante.

=item B<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.

=item B<empty>

Tag che non è necessario chiudere.

=item B<ignore>

Marcatori ignorati e considerati come testo semplice da po4a, vale a dire
che possono far parte di un msgid. Ad esempio, E<lt>bE<gt> è un buon
candidato per questa categoria dato che metterlo nella sezione B<translate>
darebbe luogo a dei msgid contenenti solo il suo contenuto (e normalmente
non sono frasi complete), condizione non ideale.

=item B<attributes>

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

=item B<qualify>

Un elenco di attributi separati da spazi per i quali la traduzione deve
essere qualificata dal nome dell'attributo, ovvero il testo estratto per la
traduzione includerà sia il nome dell'attributo che il suo valore, ad
es. per un marcatore come C<< <aaa lang_en="foo"> >> ai traduttori verrà
presentata la stringa C<lang_en="foo">. Si noti che questa impostazione
aggiunge automaticamente l'attributo dato anche nell'elenco B<attributes>.

=item B<force>

Procede anche se il DTD è sconosciuto o se B<onsgmls> trova errori nel file
in ingresso.

=item B<include-all>

I msgid che contengono solo un'entità (come C<&version;>) vengono saltati
per comodità del traduttore. Attivare questa opzione impedisce questa
ottimizzazione. Può essere utile se il documento contiene una costruzione
del tipo C<< <title>&Aacute;</title> >>, anche se è difficile possa
succedere...

=item B<ignore-inclusion>

Elenco separato da spazi di entità che non saranno accodate.  Usare
quest'opzione con cautela: può provocare in B<onsgmls> (usato internamente)
l'aggiunta di tag ed invalidare così il documento in uscita.

=back

=head1 STATO DI QUESTO MODULO

Il risultato è perfetto, ossia i documenti generati sono identici. Rimane
però ancora qualche problema:

=over 2

=item *

Gli errori scritti in uscita da B<onsgmls> vengono rediretti in maniera
predefinita su /dev/null, il che è chiaramente sbagliato, ma non si sa come
fare per evitarlo.

Il problema è che bisogna "proteggere" l'inclusione condizionale (cioè i
vari C<E<lt>! [ %foo [> e C<]]E<gt>>) da B<onsgmls>. Altrimenti B<onsgmls>
se li mangia e non si sa come fare per farli ricomparire nel documento
finale. Per impedirlo, li si riscrivono come C<{PO4A-beg-foo}> e
C<{PO4A-end}>.

Il problema con questo approccio è che i vari C<{PO4A-end}> che aggiungo non
sono validi nel documento (non in un tag E<lt>pE<gt> o simili).

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

  -o debug=onsgmls

=item *

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.

=item *

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.

=item *

Nel caso in cui si includano file, i riferimenti ai messaggi nei file po
(cioè le righe del tipo C<#: en/titletoc.sgml:9460>) risulteranno sbagliati.

Questo perché prima il file viene pre-elaborato per proteggere l'inclusione
condizionale (cioè i vari C<E<lt>! [ %foo [> e C<]]E<gt>>) e qualche entità
(come C<&version;>) da B<onsgmls> perché le si vuole così come sono nel
documento generato. Per questo motivo, faccio una copia temporanea del file
di ingresso e applico alla copia tutte le modifiche che voglio prima di
sottoporlo all'analisi di B<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.

=back

=head1 AUTORI

Questo modulo è un adattamento di sgmlspl, (un postprocessore SGML per il
parser ONSGMLS) che era:

 Copyright © 1995 David Megginson <dmeggins@aix1.uottawa.ca>

Adattato per po4a da:

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)


=head1 TRADUZIONE

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

=head1 COPYRIGHT E LICENZA

 Copyright © 1995 David Megginson <dmeggins@aix1.uottawa.ca>.
 Copyright © 2002-2005 SPI, Inc.

Questo programma è software libero; è lecito ridistribuirlo o modificarlo
secondo i termini della licenza GPL v2.0 o successive (vedere il file
COPYING).
