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

Ferramentas do Po4a                                2020-04-15                            Locale::Po4a::Sgml(3pm)