NOME

       Locale::Po4a::Sgml - converte documentações SGML de/para arquivos PO

DESCRIÇÃO

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

       Locale::Po4a::Sgml é um módulo para ajudar a tradução de documentação no formato SGML para
       outros idiomas.

       Esse módulo usa onsgmls(1) para analisar os arquivos SGML. Certifique-se de que ele está
       instalado. Certifique-se, também, de que o DTD dos arquivos SGML estão instalados no
       sistema.

OPÇÕES ACEITAS POR ESTE MÓDULO

       debug
           Lista separada por espaço das palavras-chave indicando qual parte você gostaria de
           depurar. Valores possível são: tag, generic, entities e refs.

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

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

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

       indent
           Lista separada por espaço das marcações que incrementam o nível de recuo.

       verbatim
           O layout dentro daquelas marcações que não deveriam ser alteradas. O parágrafo não
           será dimensionado e nenhuma nova linha ou espaço de recuo extra serão adicionados por
           motivos cosméticos.

       empty
           Marcações que não precisam ser fechadas.

       ignore
           Marcações ignoradas e consideradas como dados de caracteres planos pelo po4a. Isso é o
           mesmo que dizer que elas podem ser parte de um msgid. Por exemplo, <b> é um ótimo
           candidato para esta categoria, considerando que colocar ela em uma seção de tradução
           resultaria na criação de msgids não sendo sentenças completas, o que é ruim.

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

       qualify
           Uma lista separada por espaço de atributos para os quais a tradução deve ser
           qualificada pelo nome. Note que essa configuração adiciona automaticamente o atributo
           fornecido à lista de "atributes" também.

       force
           Continua ainda na eventualidade do DTD ser desconhecido ou se onsgmls encontrar erros
           no arquivo de entrada.

       include-all
           Por padrão, msgids que contenham apenas uma entidade (como "&version;") são ignorados
           para o conforto do tradutor. Ao ativar essa opção, está se prevenindo esta otimização.
           Ela pode ser útil se a documentação contém uma construção como
           "<title>&Aacute;</title>", mesmo eu duvidando que esse tipo de coisa venha a
           acontecer...

       ignore-inclusion
           Lista separada por espaço de entidades que não serão acrescentadas embutidas. Use esta
           opção com cuidado: ela pode levar o onsgmls (usado internamente) a adicionar marcações
           e tornar inválido o documento resultante.

ESTADO 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 que "proteger" as inclusões condicionais (i.e. as "<! [ %foo
         [" e "]]>") do onsgmls. Do contrário, onsgmls devora-as e eu não sei como restaurá-las
         no documento final. Para evitar isso, eu as reescrevo para "{PO4A-beg-foo}" e
         "{PO4A-end}".

         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 bem apenas com o Docbook DTD e DebianDoc. Adicionar suporte a um novo DTD
         deve ser muito fácil. O mecanismo é o mesmo para todo DTD, você só deveria passar uma
         lista de marcações existentes e algumas de suas características.

         Eu concordo, isso precisa de mais documentação, mas ele ainda é considerado como beta e
         eu odeio documentar coisas que podem/vão alterar.

       • Aviso, o suporte para DTDs é bem experimental. Eu não li nenhum manual de referência
         para encontrar a definição para todas marcações. Eu adicionar definição de marcações ao
         módulo até que funcionou para algumas documentações encontradas na internet. Se seu
         documento usa mais marcações que o meu, ele não vai funcionar. Mas como eu falei acima,
         corrigir isso deve ser bem fácil.

         Eu testei DocBook apenas com o SAG (System Administrator Guide), mas este documento é
         bem grande e deveria usar a maioria das especificidades do DocBook.

         Para DebianDoc, Eu testei alguns dos manuais do DDP, mais não todos ainda.

       • No caso de inclusão de arquivo, a referência de strings nos arquivos PO (i.e. linhas
         como "#: en/titletoc.sgml:9460") estarão erradas.

         Isso porque eu preprocesso o arquivo para proteger a inclusão condicional (i.e. aqueles
         "<! [ %foo [" e "]]>") e algumas entidades (como &version;) do onsgmls porque eu quero
         eles verbatim no documento gerado. Para isso, eu faço uma cópia temporária do arquivo de
         entrada e faço todas as alterações que eu quero nele antes de passá-lo para o onsgmls
         para análise.

         Para que isso funcione, eu substituo as entidades requisitando uma inclusão de arquivo
         pelo conteúdo do arquivo dado (de forma que eu possa proteger o precisa ser um
         subarquivo também). Mas nada é feito até o momento para corrigir as referências (i.e.
         nome de arquivo e número da linha) posteriormente. Eu não tenho certeza qual é a melhor
         coisa a se fazer.

AUTORES

       Esse módulo é uma versão adaptado do sgmlspl (pós-processador SGML para o analisador
       ONSGMLS) que era:

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

       A adaptação para o po4a foi feita para:

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

COPYRIGHT E LICENÇA

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

       Esse programa é um software livre; você pode redistribuí-lo e/ou modificá-lo sob os termos
       da GPL (veja o arquivo COPYING).