
        *****************************************************
        *           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 documentos SGML de/para ficheiros PO

=head1 DESCRIÇÃO

O objetivo do projeto po4a (PO for anything: PO para qualquer coisa) é
facilitar traduções (e o mais interessante, a manutenção das traduções) a
usar as ferramentas do gettext em áreas em que não se esperava, como na
documentação.

Locale::Po4a::Sgml é um módulo para ajudar a tradução da documentação no
formato SGML em outros idiomas [humanos].

Este módulo usa B<onsgmls>(1) para analisar os ficheiros SGML. Certifique-se
de que é instalado. Certifique-se também de que o DTD dos ficheiros SGML
está instalado no sistema.

=head1 OPÇÕES ACEITES POR ESTE MÓDULO

=over 4

=item B<debug>

Lista de palavras-chave separadas por espaços que indicam qual categoria de
mensagens de depuração extras deve ser mostrada. Os valores possíveis são:
C<entities>, C<generic>, C<onsgml>, C<refs> e C<tag>.

=item B<verbose>

Dá mais informações sobre o que está a acontecer.

=item B<translate>

Lista separada por espaços das marcações extras (além daquelas fornecidas
por DTD) cujo conteúdo deveria formar um msgid extra, isto é, deveria ser
traduzido.

=item B<section>

Lista separada por espaços das marcações extras (além daquelas fornecidas
por DTD) contendo outras marcações, algumas delas sendo da categoria
B<translate>.

=item B<indent>

Lista separada por espaços de marcações que aumentam o nível de
indentação. Isso afetará a indentação no documento resultante.

=item B<verbatim>

A apresentação dentro dessas marcas não deve ser alterada. Este parágrafo
não vai ficar envolvido e não há espaço de recuo adicional ou nova linha
será adicionada para finalidade estética.

=item B<empty>

Etiquetas que não precisam ser fechadas.

=item B<ignore>

Etiquetas ignoradas e consideradas como simples dados de caracteres pelo
po4a. Isso quer dizer que elas podem ser parte de um identificador de
mensagem. Por exemplo, E<lt>bE<gt> é um bom candidato para esta categoria
pois pô-lo na secção B<translate> criaria identificadores de mensagens com
apenas o seu conteúdo, (e geralmente não são frases inteiras), o que é mau.

=item B<attributes>

Uma lista separada por espaços de atributos que precisam ser
traduzidos. Pode especificar os atributos pelos seus nomes (por exemplo,
C<lang>), mas também pode prefixá-la com uma hierarquia de etiquetas, para
especificar que este atributo só será traduzido quando estiver na etiqueta
especificada. Por exemplo: C<< <bbb><aaa>lang >> especifica que o atributo
lang só será traduzido se ele estiver numa etiqueta C<< <aaa> >>, que está
numa etiqueta C<< <bbb> >>. Os nomes de etiquetas são, na verdade,
expressões regulares, de forma que também pode escrever coisas como C<<
<aaa|bbb>lang >> para traduzir apenas atributos C<lang> que estão numa
etiqueta C<< <aaa> >> ou uma etiqueta C<< <bbb> >>.

=item B<qualify>

Uma lista separada por espaços de atributos para os quais a tradução deve
ser qualificada pelo nome do atributo, isto é, o texto extraído para a
tradução incluirá o nome e o valor do atributo. Por exemplo, para uma
etiqueta como C<< <aaa lang_en="foo"> >> os tradutores receberão a cadeia
C<lang_en="foo">. Observe que isto também adiciona automaticamente o
atributo fornecido à lista B<attributes>.

=item B<force>

Continua mesmo na eventualidade do DTD ser desconhecido ou se B<onsgmls>
encontrar erros no ficheiro de entrada.

=item B<include-all>

Por predefinição, msgids que contenham apenas uma entidade (como
C<&version;>) são ignorados para o conforto dos tradutores. Ao ativar esta
opção previne-se esta otimização. Ela pode ser útil se a documentação conter
uma construção como C<< <title>&Aacute;</title> >>, mesmo duvidando que este
tipo de coisa venha a acontecer...

=item B<ignore-inclusion>

Lista separada por espaços de entidades que não serão embutidas. Use esta
opção com cuidado: ela pode levar o B<onsgmls> (usado internamente) a
adicionar etiquetas e invalidar o documento resultante.

=back

=head1 ESTADO DESTE MÓDULO

O resultado é perfeito. Isto é, os documentos gerados são exatamente os
mesmos que os originais. Mas ainda há alguns problemas:

=over 2

=item *

A saída de erro do B<onsgmls> é redirecionada para /dev/null por
predefinição, o que obviamente é ruim. Não sei como evitar isso.

O problema é que tenho que "proteger" as inclusões condicionais (i.e. as
C<E<lt>! [ %foo [> e C<]]E<gt>>) do B<onsgmls>. Caso contrário, B<onsgmls>
devora-as e não sei como restaurá-las no documento final. Para evitar isso,
reescrevo-as para C<{PO4A-beg-foo}> e C<{PO4A-end}>.

O problema com isso é que o C<{PO4A-end}> e outros que acrescento, são
inválidos no documento (não numa etiqueta E<lt>pE<gt> ou semelhante).

Se quiser ver a saída do B<onsgmls>, adicione o seguinte à sua linha de
comandos (ou linha de configuração po4a):

  -o debug=onsgmls

=item *

Ele funciona apenas com o DebianDoc e DocBook DTD. Adicionar suporte para um
novo DTD deve ser muito fácil. O mecanismo é o mesmo para cada DTD, só tem
que dar uma lista das etiquetas existentes e algumas das suas
características.

Concordo. apenas necessita mais documentação, no entanto pode ser
considerado como beta e detesto conteúdos de documentos que podem ainda ser
sujeitos a alterações.

=item *

Aviso, o suporte para DTDs é bastante experimental. Não li nenhum manual de
referência para encontrar a definição de cada etiqueta. Adicionei a
definição de etiqueta para o módulo, até que funciona para alguns documentos
que eu encontrei na Internet. Se o documento usar mais etiquetas do que as
minhas, não vai funcionar. Mas como eu disse acima, reparar isto deve ser
muito fácil.

Testei DocBook contra o SAG (Guia do Administrador do Sistema), mas também
este documento é muito grande e deve usar mais especificidades do DocBook.

Para DebianDoc, testei alguns dos manuais da DDP, mas não todos ainda.

=item *

Em caso de inclusão de ficheiros, a cadeia de referência de mensagens em
ficheiros PO (ou seja, linhas como C<#: en/titletoc.sgml:9460>) vai estar
errada.

Isto porque eu pré-processei o ficheiro para proteger a inclusão condicional
(i.e. aqueles C<E<lt>! [ %foo [> e C<]]E<gt>>) e algumas entidades (como
C<&version;>) do B<onsgmls> porque quero eles verbatim no documento
gerado. Para isto, faço uma cópia temporária do ficheiro de entrada e faço
todas as alterações que quero nele antes de passá-lo para o B<onsgmls> para
análise.

Assim ele funciona, substituí as entidades que pedem a inclusão de ficheiros
pelo conteúdo do ficheiro de dados (para que possa proteger também o que
precisa de estar num sub-ficheiro também). Mas nada se fez até agora para
corrigir as referências (ou seja o nome do ficheiro e o número da linha)
mais tarde. Não tenho certeza qual é a melhor coisa a fazer.

=back

=head1 AUTORES

Este módulo é uma versão adaptada do 'sgmlspl' (pós-processador SGML para os
analisadores SGMLS e ONSGMLS) que foi:

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

A adaptação para po4a foi feita por:

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

=head1 DIREITOS DE AUTOR E LICENÇA

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

Este programa é um software livre; pode redistribuí-lo e/ou modificá-lo sob
os termos da GPL v2.0 ou posterior (veja o ficheiro COPYING).
