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

Ferramentas Po4a                                   2023-01-03                            Locale::Po4a::Sgml(3pm)