Provided by: po4a_0.55-1_all bug

NOME

       Locale::Po4a::TeX - converte documentos TeX e derivados de/para arquivos PO

DESCRIÇÃO

       O objetivo do projeto po4a (PO for anything, ou PO para qualquer coisa) é facilitar
       traduções (e o mais interessante, a manutenção das traduções) usando as ferramentas do
       gettext em áreas em que não se esperava, como documentação.

       Locale::Po4a::TeX é um módulo para ajudar a tradução de documentos TeX para outros
       idiomas. Ele também pode ser usado como uma base para construir módulos para documentos
       baseados em TeX.

       Usuários provavelmente deveriam usar o módulo LaTeX, o qual herdou do módulo TeX e contém
       as definições dos comandos comuns do LaTeX.

TRADUZINDO COM PO4A::TEX

       Esse módulo pode ser usado diretamente para lidar com documentos TeX genéricos. Ele vai
       dividir seu documento em blocos menores (parágrafos, blocos literais ou até mesmo menores,
       como títulos e índices).

       Há algumas opções (descritas na próxima seção) que podem personalizar este comportamento.
       Se isso não se adequar ao formato do seu documento, encorajamos você a escrever seu
       próprio módulo derivado deste, para descrever os detalhes do seu formato. Veja a seção
       abaixo ESCREVENDO MÓDULOS DERIVADOS, para a descrição do processo.

       Esse módulo também pode ser personalizado por linhas iniciais com "% po4a:" no arquivo
       TeX. Essas personalizações são descritas na seção PERSONALIZAÇÃO INTEGRADA.

OPÇÕES ACEITAS POR ESTE MÓDULO

       Estas são as opções específicas deste módulo:

       debug
           Ativa depuração em alguns mecanismos internos deste módulo. Use a fonte para saber
           quais partes podem ser depuradas.

       no_wrap
           Lista separada por vírgula dos ambientes que não deveriam ser redimensionado.

           Note que há uma diferença entre ambientes literais e no_wrap. Não há análise de
           comentários e comandos nos blocos literais.

           Se esse ambiente ainda não foi registrado, po4a vai considerar que ele não leva
           parâmetros.

       exclude_include
           Lista separada por dois-pontos (:) dos arquivos que não deveria ser incluídos por
           \input e \include.

       definitions
           O nome de um arquivo contendo definições para o po4a, como definido na seção
           PERSONALIZAÇÃO INTEGRADA. Você pode usar esta opção se não for possível colocar as
           definições no documento que está sendo traduzido.

       verbatim
           Lista separada por vírgula dos ambientes que deveriam ser considerados com literais.

           Se esse ambiente ainda não foi registrado, po4a vai considerar que ele não leva
           parâmetros.

       Usar essas opções permite sobrescrever o comportamento dos comandos definidos nas listas
       padrões.

PERSONALIZAÇÃO INTEGRADA

       O módulo TeX pode ser personalizado com linhas começando com % po4a:. Essas linhas são
       interpretadas como comandos para o analisador. Os seguintes comandos são reconhecidos:

       % po4a: command comando1 alias comando2
           Indica que os argumentos do comando1 deveriam ser tratados como os argumentos do
           comando comando2.

       % po4a: command comando1 parâmetros
           Isso permite descrever em detalhes os parâmetros do comando comando1. Essa informação
           será usada para verificar o número de argumentos e seus tipos.

           Você pode preceder o comando comando1 por

           um asterisco (*)
               po4a vai extrair esse comando dos parágrafos (se ele estiver alocado no começo ou
               no fim de um parágrafo). Os tradutores vão, então, ter que traduzir os parâmetros
               que estão marcados como traduzíveis.

           um mais (+)
               Assim como o asterisco, o comando será extraído se ele aparecer em uma extremidade
               de um bloco, mas os parâmetros não serão traduzidos separadamente. O tradutor terá
               que traduzir o comando concatenado a todos os seus parâmetros. Isso permite manter
               mais o contexto e é útil para comandos com palavras pequenas em parâmetro, o qual
               pode ter múltiplos significados (e traduções).

               Nota: neste caso, você não terá que especificar quais parâmetros são traduzíveis,
               mas po4a deve saber o tipo e número de parâmetros.

           um menos (-)
               Nesse caso, o comando não será extraído de qualquer bloco. Mas se ele aparece
               sozinho em um bloco, então apenas os parâmetros marcados como traduzíveis serão
               apresentados para o tradutor. Isso é útil para comandos de fonte. Esses comandos
               geralmente deveriam não ser separados de seu parágrafo (para manter o contexto),
               mas não há motivo para incomodar o tradutor com eles, se um conjunto de strings
               está incluso neste comando.

           O argumento parâmetros é um conjunto de [] (para indicar um argumento opcional) ou {}
           (para indicar um argumento obrigatório).  Você pode colocar um sublinhado (_) entre
           esses colchetes para indicar que o parâmetro deve ser traduzido. Por exemplo:
            % po4a: command *chapter [_]{_}

           Isso indica que o comando de capítulo possui dois parâmetros: um opcional (título
           curto) e um obrigatório, os quais devem ser traduzidos.  Se você deseja especificar
           que o comando href tenha dois parâmetros obrigatórios, que você não deseja traduzir a
           URL (primeiro parâmetro), e que você não deseja que esse comando seja separado de seu
           parágrafo (o que permite que o tradutor mova o link na sentença), você pode usar:
            % po4a: command -href {}{_}

           Neste caso, a informação indicando quais argumentos devem ser traduzidos é apenas
           usado se um parágrafo é composto apenas deste comando href.

       % po4a: environment ambiente parâmetros
           Isso permite definir os parâmetros aceitos pelo ambiente ambiente.  Essa informação é
           posteriormente usada para verificar o número de argumentos do comando \begin e permite
           especificar quais deles devem ser traduzidos.  A sintaxe do argumento parâmetros é a
           mesma da descrita para outros comandos.  O primeiro parâmetro do comando \begin é o
           nome do ambiente.  Este parâmetro não deve ser especificado na lista de parâmetros.
           Veja alguns parâmetros:
            % po4a: environment multicols {}
            % po4a: environment equation

           Quanto aos comandos, ambiente pode ser precedido por um mais (+) para indicar que o
           comando \begin deve ser traduzido com todos os seus argumentos.

       % po4a: separator ambiente "expressão_regular"
           Indica que um ambiente deveria ser dividido de acordo com a expressão regular
           fornecida.

           A expressão regular é delimitada por aspas. Ela não deveria criar qualquer referência
           própria. Você deveria usar (?:) se você precisa de um grupo. Também pode ser
           necessário alguns caracteres de escapes.

           Por exemplo, o módulo LaTeX usa a expressão regular "(?:&|\\\\)" para traduzir
           separadamente cada célula de uma tabela (linhas são separadas por "\\" e células por
           "&").

           A noção de ambiente é expandida ao tipo exibido no arquivo PO. Isso pode ser usado
           para dividir em "\\\\" no primeiro argumento obrigatório no comando title. neste caso,
           o ambiente é title{#1}.

       % po4a: verbatim environment ambiente
           Indica que ambiente é o ambiente literal (verbatim). Comentários e comandos serão
           ignorados neste ambiente.

           Se esse ambiente ainda não foi registrado, po4a vai considerar que ele não leva
           parâmetros.

ESCREVENDO MÓDULOS DERIVADOS

       pre_trans
       post_trans
       translate
           Wrapper da tradução do Transtractor, com filtros pré e pós-processamento.

           Comentários de um parágrafo são inseridos como um comentário no PO para a primeira
           string traduzida neste parágrafo.

       get_leading_command($buffer)
           Essa função retorna:

           Um nome de comando
               Se nenhuma comando for encontrado no começo do buffer fornecido, esta string
               estará vazia. Apenas comandos que podem ser separados são considerados. O hash
               %separated_command contém a lista destes comandos.

           Uma variante
               Isso indica se uma variante é usada. Por exemplo, um asterisco (*) pode ser
               adicionado ao final de comando de seções para especificar que eles deveriam não
               ser numerados. Nesse caso, este campo deveria conter "*". Se não houver variante,
               o campo é uma string vazia.

           Um vetor com tuplos (tipo de argumento, argumento)
               O tipo de argumento pode ser tanto "{" (para argumentos obrigatórios) ou "[" (para
               argumentos opcionais).

           O buffer restante
               O resto do buffer após a remoção deste comando e seus argumentos. Se nenhum
               comando for encontrado, o buffer original não é afetado e é retornado neste campo.

       get_trailing_command($buffer)
           O mesmo que get_leading_command, mas para comandos ao final de um buffer.

       translate_buffer
           Traduz recursivamente um buffer separando comandos no início e no final (aqueles que
           devem ser traduzidos separadamente) do buffer.

           Se uma função é definida em %translate_buffer_env como o ambiente atual, essa função
           será usada para traduzir o buffer ao invés de translate_buffer().

       read
           Sobrepõe o read() do Transtractor.

       read_file
           Lê recursivamente um arquivo, anexando arquivos incluídos que não estão listados no
           vetor @exclude_include. Arquivos incluídos são pesquisados usando o comando kpsewhich
           da biblioteca Kpathsea.

           Exceto pela parte de inclusão de arquivos, é uma cópia idêntica da leitura do
           Transtractor.

       parse_definition_file
           Subrotina para analisar um arquivo com diretivas do po4a (definições de novos
           comandos).

       parse_definition_line
           Analisa uma linha de definição na forma de "% po4a: ".

           Veja a seção PERSONALIZAÇÃO INTEGRADA para mais detalhes.

       is_closed
       docheader

FUNÇÕES INTERNAS usadas para escrever analisadores derivados

       Funções de ambiente e comandos levam os seguintes argumentos (em adição ao objeto $self):

       Um nome de comando
       Uma variante
       Um vetor de tuplos (tipo, argumento)
       O ambiente atual

       Os primeiros três argumentos são extraídos por get_leading_command ou
       get_trailing_command.

       Funções de ambiente ou comandos retornam a tradução do comando com seus argumentos e um
       novo ambiente.

       Funções de ambiente são chamadas quando um comando \begin for encontrado. Elas são
       chamadas com o comando \begin e seus argumentos.

       O módulo TeX propõe apenas uma função de comando e uma função de ambiente: generic_command
       e generic_environment.

       generic_command usa a informação especificada por register_generic_command ou adicionando
       definição ao arquivo TeX:
        % po4a: command comando1 parâmetros

       generic_environment usa a informação especificada por register_generic_environment ou
       adicionando definição ao arquivo TeX:
        % po4a: environment ambiente parâmetros

       Ambas funções vai traduzir apenas os parâmetros que foram especificadas como traduzíveis
       (com uma "_"). generic_environment vai anexar o nome do ambiente à pilha de ambientes e
       generic_command vai anexar o nome do comando seguido por um identificador do parâmetro
       (como {#7} ou [#2]).

ESTADO DESTE MÓDULO

       Esse módulo precisa de mais testes.

       Ele foi testado em um livro e com a documentação Python.

LISTA DE TAREFAS

       Detecção automática de novos comandos
           O módulo TeX poderia analisar os argumentos de novos comandos e tentar adivinhar o
           número de argumentos, seus tipos e se eles deveriam ser traduzidos.

       Tradução do separador de ambiente
           Quando o \item é usado como um separador de ambiente, o argumento item é anexado a
           string seguinte.

       Alguns comandos devem ser adicionados à pilha de ambiente
           Esses comandos deveriam ser especificados em duplas. Isso poderia permitir especificar
           comandos iniciando ou terminando um ambiente literal.

       Outros
           Vários outros pontos são marcados como TODO no código.

ERROS CONHECIDOS

       Vários pontos são marcados como FIXME no código.

VEJA TAMBÉM

       Locale::Po4a::LaTeX(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)

AUTORES

        Nicolas François <nicolas.francois@centraliens.net>

COPYRIGHT E LICENÇA

       Copyright © 2004, 2005 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.

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