Locale::Po4a::Sgml - converte documentos SGML de/para ficheiros
PO
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
outras 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.
- debug
- Lista separada por espaços de palavras-chave que indicam que parte
deseja depurar. Valores de depuração possíveis
são: tag, generic, entities e refs.
- verbose
- Dê mais informações sobre o que está a
acontecer.
- translate
- Lista separada por espaços de etiquetas extra (ao lado dos DTD
fornecidos), cujo conteúdo devem formar um identificador de
mensagem extra.
- section
- Lista separada por espaços de etiquetas extra (ao lado dos DTD
fornecidos), a conter outras etiquetas, a ser algumas de categoria
translate.
- indent
- Lista separada por espaço de etiquetas que aumentam o nível
de recuo.
- 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 carateres por
po4a. Isso quer dizer que elas podem ser parte de um identificador de
mensagem. Por exemplo, <b> é um bom candidato para esta
categoria desde que o ponha na secção de traduzir criaria
identificadores de mensagens não a ser 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 pode também prefixá-lo com uma
hierarquia de etiquetas, para especificar que este atributo será
apenas traduzido quando está na etiqueta especificada, por exemplo:
<bbb><aaa>lang especifica que o atributo 'lang' só
será traduzido se estiver numa etiqueta <aaa>, que é
uma etiqueta <bbb> Os nomes de etiquetas são realmente
expressões regulares, então também podem escrever
coisas como <aaa|bbbb>lang para apenas traduzir os atributos 'lang'
que estão num <aaa> ou uma etiqueta <bbb>.
- qualify
- Uma lista separada por espaços de atributos para que a
tradução deve ser qualificada pelo nome do atributo. Note
que esta definição adiciona automaticamente o atributo dado
também na lista dos 'atributos'.
- force
- Proceder mesmo se o DTD é desconhecido ou se onsgmls encontra erros
no ficheiro de entrada.
- include-all
- Por predefinição, o 'msgids' contém apenas uma
entidade (como '&version;') são ignorados para o conforto do
tradutor. Ativando esta opção impede que ista
otimização. Pode ser útil se o documento
contém uma construção como
"<title>Á</title>" , mesmo que duvide que
tais coisas sempre acontecem ...
- ignore-inclusion
- Lista separada por espaço de entidades que não será
indexadas. Use esta opção com cuidado: ela pode causar
onsgmls (usado internamente) para adicionar etiquetas e render o documento
de saída inválida.
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 predefinição, o que obviamente é ruim. Não
sei como evitar isso.
O problema é que tenho a "proteger" as
inclusões condicionais (ou seja, o material
"<! [%foo [" e
"]]>") de 'onsgmls'. Caso
contrário 'onsgmls' come-os e, não sei como
restaurá-los no documento final. Para evitar isso, reescrevi-os
para "{po4a-beg-foo}" e
"{po4a-final}".
O problema com isso é que o
"{PO4A-end}" e outros que acrescento,
são inválidos no documento (não numa
marcação <p> ou similar).
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 suascaracterí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 etiqueta do que a minha, 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.
Isso é porque pre-processei o ficheiro para proteger a
inclusão condicional (ou seja, o material
"<! [%foo [" e
"]]E <gt">) e algumas entidades
(como &version;) de 'onsgmls' porque quero-os textualmente no
documento gerado. Para isso, fiz uma cópia temporária do
ficheiro de entrada e faço todos as mudanças que quero
para este antes de o passar para '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.
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 feito por:
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)
Copyright © 1995 David Megginson <dmeggins@aix1.uottawa.ca>.
Copyright © 2002-2005 SPI, Inc.
Este programa é software livre, pode redistribuí-lo
e/ou modificá-lo sob os termos da GPL (consulte o ficheiro
CÓPIA).