LOCALE::PO4A::SGML.3PM(1) | User Contributed Perl Documentation | LOCALE::PO4A::SGML.3PM(1) |
NOME¶
Locale::Po4a::Sgml - converte documentos SGML de/para ficheiros PO
DESCRIÇÃO¶
O objetivo do projeto po4a (PO for anything: PO para qualquer coisa) é facilitar traduções (e o mais interessante, a manutenção das traduções) a usar as ferramentas do gettext em áreas em que não se esperava, como na documentação.
Locale::Po4a::Sgml é um módulo para ajudar a tradução da documentação no formato SGML em outros 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 de palavras-chave separadas por espaços que indicam qual categoria de mensagens de depuração extras deve ser mostrada. Os valores possíveis são: "entities", "generic", "onsgml", "refs" e "tag".
- verbose
- Dá mais informações sobre o que está a acontecer.
- translate
- Lista separada por espaços das marcações extras (além daquelas fornecidas por DTD) cujo conteúdo deveria formar um msgid extra, isto é, deveria ser traduzido.
- section
- Lista separada por espaços 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ços de marcações que aumentam o nível de indentação. Isso afetará a indentação no documento resultante.
- verbatim
- A apresentação dentro dessas marcas não deve ser alterada. Este parágrafo não vai ficar envolvido e não há espaço de recuo adicional ou nova linha será adicionada para finalidade estética.
- empty
- Etiquetas que não precisam ser fechadas.
- ignore
- Etiquetas ignoradas e consideradas como simples dados de caracteres pelo po4a. Isso quer dizer que elas podem ser parte de um identificador de mensagem. Por exemplo, <b> é um bom candidato para esta categoria pois pô-lo na secção translate criaria identificadores de mensagens com apenas o seu conteúdo, (e geralmente não são frases inteiras), o que é mau.
- attributes
- Uma lista separada por espaços de atributos que precisam ser traduzidos. Pode especificar os atributos pelos seus nomes (por exemplo, "lang"), mas também pode prefixá-la com uma hierarquia de etiquetas, para especificar que este atributo só será traduzido quando estiver na etiqueta especificada. Por exemplo: "<bbb><aaa>lang" especifica que o atributo lang só será traduzido se ele estiver numa etiqueta "<aaa>", que está numa etiqueta "<bbb>". Os nomes de etiquetas são, na verdade, expressões regulares, de forma que também pode escrever coisas como "<aaa|bbb>lang" para traduzir apenas atributos "lang" que estão numa etiqueta "<aaa>" ou uma etiqueta "<bbb>".
- qualify
- Uma lista separada por espaços 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 etiqueta como "<aaa lang_en="foo">" os tradutores receberão a cadeia "lang_en="foo"". Observe que isto também adiciona automaticamente o atributo fornecido à lista attributes.
- force
- Continua mesmo na eventualidade do DTD ser desconhecido ou se onsgmls encontrar erros no ficheiro de entrada.
- include-all
- Por predefinição, msgids que contenham apenas uma entidade (como "&version;") são ignorados para o conforto dos tradutores. Ao ativar esta opção previne-se esta otimização. Ela pode ser útil se a documentação conter uma construção como "<title>Á</title>", mesmo duvidando que este tipo de coisa venha a acontecer...
- ignore-inclusion
- Lista separada por espaços de entidades que não serão embutidas. Use esta opção com cuidado: ela pode levar o onsgmls (usado internamente) a adicionar etiquetas e invalidar o documento resultante.
ESTADO DESTE MÓDULO¶
O resultado é perfeito. Isto é, 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 predefinição, o que obviamente é ruim.
Não sei como evitar isso.
O problema é que tenho que "proteger" as inclusões condicionais (i.e. as "<! [ %foo [" e "]]>") do onsgmls. Caso contrário, onsgmls devora-as e não sei como restaurá-las no documento final. Para evitar isso, reescrevo-as para "{PO4A-beg-foo}" e "{PO4A-end}".
O problema com isso é que o "{PO4A-end}" e outros que acrescento, são inválidos no documento (não numa etiqueta <p> ou semelhante).
Se 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 suas características.
Concordo. apenas necessita mais documentação, no entanto pode ser considerado como beta e detesto conteúdos de documentos que podem ainda ser sujeitos a alterações.
- Aviso, o suporte para DTDs é bastante experimental. 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 etiquetas do que as minhas, não vai funcionar.
Mas como eu disse acima, reparar isto deve ser muito fácil.
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, testei alguns dos manuais da DDP, mas não todos ainda.
- Em caso de inclusão de ficheiros, a cadeia de referência de
mensagens em ficheiros PO (ou seja, linhas como "#:
en/titletoc.sgml:9460") vai estar errada.
Isto porque eu pré-processei o ficheiro para proteger a inclusão condicional (i.e. aqueles "<! [ %foo [" e "]]>") e algumas entidades (como "&version;") do onsgmls porque quero eles verbatim no documento gerado. Para isto, faço uma cópia temporária do ficheiro de entrada e faço todas as alterações que quero nele antes de passá-lo para o onsgmls para análise.
Assim ele funciona, substituí as entidades que pedem a inclusão de ficheiros pelo conteúdo do ficheiro de dados (para que 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. 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 feita por:
Denis Barbier <barbier@linuxfr.org> Martin Quinson (mquinson#debian.org)
DIREITOS DE AUTOR E LICENÇA¶
Copyright © 1995 David Megginson <dmeggins@aix1.uottawa.ca>. Copyright © 2002-2005 SPI, Inc.
Este programa é um software livre; pode redistribuí-lo e/ou modificá-lo sob os termos da GPL v2.0 ou posterior (veja o ficheiro COPYING).
2025-09-14 | perl v5.40.1 |