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

OPÇÕES ACEITES POR ESTE MÓDULO

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>&Aacute;</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.

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

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 feito 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 é software livre, pode redistribuí-lo e/ou modificá-lo sob os termos da GPL (consulte o ficheiro CÓPIA).