Ubuntu Manpages

Locale::Po4a::Sgml

converte documentações SGML de/para arquivos PO

A missão do projeto po4a (em inglês, PO for anything) é facilitar as traduções (e o mais interessante, a manutenção de traduções) usando ferramentas de gettext em áreas onde elas não eram esperadas, como documentação.

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

This module uses onsgmls(1) to parse the SGML files. Make sure it is installed. Also make sure that the DTD of the SGML files are installed in the system.

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.
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.
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.
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 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.
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>.
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.
Proceed even if the DTD is unknown or if onsgmls finds errors in the input file.
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...
Space separated list of entities that won't be inlined. Use this option with caution: it may cause onsgmls (used internally) to add tags and render the output document invalid.

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

  • The error output of onsgmls is redirected to /dev/null, which is clearly bad. I don't know how to avoid that.

    The problem is that I have to "protect" the conditional inclusions (i.e. the "<! [ %foo [" and "]]>" stuff) from onsgmls. Otherwise onsgmls eats them, and I don't know how to restore them in the final document. To prevent that, I rewrite them to "{PO4A-beg-foo}" and "{PO4A-end}".

    The problem with this is that the "{PO4A-end}" and such I add are invalid in the document (not in a <p> tag or so).

    Everything works well with onsgmls's output redirected that way, but it will prevent us from detecting that the document is badly formatted.

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

    This is because I preprocess the file to protect the conditional inclusion (i.e. the "<! [ %foo [" and "]]>" stuff) and some entities (like &version;) from onsgmls because I want them verbatim to the generated document. For that, I make a temp copy of the input file and do all the changes I want to this before passing it to onsgmls for parsing.

    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.

This module is an adapted version of sgmlspl (SGML postprocessor for the ONSGMLS parser) which was:

 Copyright (c) 1995 por 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 (c) 1995 por David Megginson <dmeggins@aix1.uottawa.ca>
 Copyright 2002, 2003, 2004, 2005 por SPI, inc.

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