Scroll to navigation

LOCALE::PO4A::SGML.3PM(1) User Contributed Perl Documentation LOCALE::PO4A::SGML.3PM(1)

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

Space-separated list of keywords indicating which category of extra debug messages should be shown. Possible values are: "entities", "generic", "onsgml", "refs" and "tag".
Fornece mais informações sobre o que está acontecendo.
Lista separada por espaço das marcações extras (além daquelas fornecidas por DTD) cujo conteúdo deveria formar um msgid extra, isto é, deveria ser traduzido.
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.
Lista separada por espaço das marcações que incrementam o nível de recuo. Isso vai afetar o recuo no documento resultante.
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.
Marcações que não precisam ser fechadas.
Marcações ignoradas e consideradas como dados de caracteres simples 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 translate resultaria na criação de um msgid com apenas o seu conteúdo (é geralmente não uma sentença completa), o que é ruim.
A space-separated list of attributes that need to be translated. You can specify the attributes by their name (for example, "lang"), but you can also prefix it with a tag hierarchy, to specify that this attribute will only be translated when it is into the specified tag. For example: "<bbb><aaa>lang" specifies that the lang attribute will only be translated if it is in an "<aaa>" tag, which is in a "<bbb>" tag. The tag names are actually regular expressions so you can also write things like "<aaa|bbb>lang" to only translate "lang" attributes that are in an "<aaa>" or a "<bbb>" tag.
Uma lista separada por espaço 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 tag como "<aaa lang_en="foo">" os tradutores receberão a string "lang_en="foo"". Observe que isso também adiciona automaticamente o atributo fornecido à lista attributes também.
Continua mesmo na eventualidade do DTD ser desconhecido ou se onsgmls encontrar erros no arquivo de entrada.
Por padrão, msgids que contenham apenas uma entidade (como "&version;") são ignorados para o conforto dos tradutores. 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...
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 tags e tornar inválido o documento resultante.

ESTADO DESTE MÓDULO

O resultado é perfeito, ou seja, os documentos gerados são exatamente os mesmos que os originais. 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 pré-processo 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 v2.0 ou posterior (veja o arquivo COPYING).

2024-08-06 perl v5.38.2