NOME

       Locale::Po4a::Sgml - converte documentos SGML de/para ficheiros PO

DESCRIÇÃO

       O objetivo do projeto po4a (PO para tudo) é facilitar traduções (e mais interessante, a
       manutenção das traduções) usando ferramentas gettext em áreas onde eles não eram esperados
       como documentação.

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

       Este módulo usa 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.

OPÇÕES ACEITES POR ESTE MÓDULO

       debug
           Lista separada por espaço de palavras-chave que indicam que parte você deseja. Valores
           de depuração possíveis são: tag, generic, entities e refs.

       verbose
           Dê mais informações sobre o que está acontecendo.

       translate
           Lista separada por espaços de etiquetas extra (ao lado dos DTD fornecidos), cujo
           conteúdo devem formar um identificador de mensagem extra.

       section
           Lista separada por espaços de etiquetas extra (ao lado dos DTD fornecidos), contendo
           outras etiquetas, sendo algumas de categoria translate.

       indent
           Lista separada por espaço de etiquetas que aumentam o nível de recuo.

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

       empty
           Etiquetas não precisam ser fechados

       ignore
           Etiquetas ignoradas e consideradas como simples dados de carateres por po4a. Isso quer
           dizer que elas podem ser parte de um identificador de mensagem. Por exemplo, <b> é um
           bom candidato para esta categoria desde que o coloque na secção de traduzir criaria
           identificadores de mensagens não sendo frases inteiras, o que é mau.

       attributes
           Uma lista separada por espaços de atributos que precisam ser traduzidos. Você pode
           especificar os atributos pelos seus nomes (por exemplo, "lang"), mas você pode também
           prefixá-lo com uma hierarquia de etiquetas, para especificar que este atributo será
           apenas traduzido quando está na etiqueta especificada, por exemplo: <bbb><aaa>lang
           especifica que o atributo 'lang' só será traduzido se estiver numa etiqueta <aaa>, que
           é uma etiqueta <bbb> Os nomes de etiqueta são realmente expressões regulares, então
           você também pode escrever coisas como <aaa|bbbb>lang para apenas traduzir os atributos
           'lang' que estão num <aaa> ou uma etiqueta <bbb>.

       qualify
           Uma lista separada por espaços de atributos para que a tradução deve ser qualificada
           pelo nome do atributo. Note que esta definição adiciona automaticamente o atributo
           dado também na lista dos 'atributos'.

       force
           Proceder mesmo se o DTD é desconhecido ou se onsgmls encontra erros no ficheiro de
           entrada.

       include-all
           Por padrão, o 'msgids' contém apenas uma entidade (como '&version;') são ignorados
           para o conforto tradutor. Ativando esta opção impede que ista otimização. Pode ser
           útil se o documento contém uma construção como "<title>&Aacute;</title>" , mesmo que
           eu duvide que tais coisas sempre acontecem ...

       ignore-inclusion
           Lista separada por espaço de entidades que não será indexadas. Use esta opção com
           cuidado: ela pode causar onsgmls (usado internamente) para adicionar etiquetas e
           render o documento de saída inválida.

STATUS DESTE MÓDULO

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

       • A saída de erro do onsgmls é redirecionada para /dev/null por padrão, o que obviamente é
         ruim. Eu não sei como evitar isso.

         O problema é que eu tenho para "proteger" as inclusões condicionais (ou seja, o material
         "<! [%foo [" e "]]>") de 'onsgmls'. Caso contrário 'onsgmls' come-os e, eu não sei como
         restaurá-los no documento final. Para evitar isso, eu reescrevi-os para "{po4a-beg-foo}"
         e "{po4a-final}".

         O problema com isso é que o "{PO4A-end}", e outros que eu acrescento, são inválidos no
         documento (não em uma marcação <p> ou similar).

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

           -o debug=onsgmls

       • 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 suascaracterísticas.

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

       • Aviso, o suporte para DTDs é bastante experimental. Eu 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 etiqueta do que a minha, não vai funcionar. Mas como
         eu disse acima, reparar isto deve ser muito fácil.

         Eu 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, eu testei alguns dos manuais da DDP, mas não todos ainda.

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

         Isso é porque eu pre-processei o ficheiro para proteger a inclusão condicional (ou seja,
         o material "<! [%foo [" e "]]E <gt">) e algumas entidades (como &version;) de 'onsgmls'
         porque eu quero-os textualmente no documento gerado. Para isso, fiz uma cópia temporária
         do ficheiro de entrada e faço todos as mudanças que quero para este antes de o passar
         para 'onsgmls' para análise.

         Assim ele funciona, eu substituí as entidades que pedem a inclusão de ficheiros pelo
         conteúdo do ficheiro de dados (para que eu 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. Eu não tenho certeza qual é a
         melhor coisa a fazer.

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 feito 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 é software livre, você pode redistribuí-lo e/ou modificá-lo sob os termos da
       GPL (consulte o ficheiro CÓPIA).