Provided by: po4a_0.55-1_all bug

NOME

       Local::Po4a::TeX - converter documentos TeX e derivados de/para ficheiros PO

DESCRIÇÃO

       O objetivo do projeto po4a (PO para tudo) é facilitar traduções (e mais interessante, a
       manutenção das traduções) usando ferramentas gettext em áreas onde eles não eram esperados
       como documentação.

       Locale::Po4a::TeX é um módulo para ajudar na tradução de documentos TeX em outra língua
       [humana]. Também pode ser usado como uma base para a construção de módulos de TeX
       documentos baseados.

       Users should probably use the LaTeX module, which inherits from the TeX module and
       contains the definitions of common LaTeX commands.

TRADUÇÃO COM PO4A::TEX

       Este módulo pode ser usado diretamente para lidar com documentos genéricos TeX. Isto irá
       dividir o seu documento em blocos menores (parágrafos, blocos textuais, ou mesmo menores,
       como títulos ou índices).

       Existem algumas opções (descrito na próxima secção), que podem personalizar este
       comportamento. Se isto não se encaixa no seu formato de documento que está encorajado a
       escrever o seu próprio módulo derivado deste, para descrever os detalhes do seu formato.
       Consulte a secção WRITING DERIVATE MODULES abaixo, para descrição do processo.

       Este módulo também pode ser personalizado por linhas que começam com "% po4a:" no ficheiro
       TeX. Estas personalizações são descritas na secção INLINE CUSTOMIZATION.

OPÇÕES ACEITES POR ESTE MÓDULO

       Estas são as opções particulares deste módulo:

       debug
           Ativar a depuração para alguns mecanismos internos deste módulo. Use a fonte para ver
           que partes podem ser depuradas.

       no_wrap
           Lista de ambientes separada por vírgula que não deve ser re-envolvidos.

           Note que há uma diferença entre os ambientes textuais e no_wrap. Não existe um comando
           e análise de comentários em blocos textuais.

           Se este ambiente não foi já registado, po4a irá considerar que este ambiente não leva
           nenhum parâmetro.

       exclude_include
           Lista de ficheiros separada por dois pontos que não devem ser incluídos por \input e
           \include.

       definitions
           O nome dum ficheiro que contém as definições para po4a, como definido na secção INLINE
           CUSTOMIZATION. Você pode usar esta opção se não épossível colocar as definições no
           documento a ser traduzido.

       verbatim
           Lista de ambientes separada por vírgula que devem ser tomados como textuais.

           Se este ambiente não foi já registado, po4a irá considerar que este ambiente não leva
           nenhum parâmetro.

       O uso destas opções permite substituir o comportamento dos comandos definidos nas listas
       padrão.

INLINE CUSTOMAZITION

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

       % po4a: command command1 alias command2
           Indica que os argumentos do commando command1 devem ser tratado como os argumentos do
           comando command2.

       % po4a: command command1 parameters
           Isso permite descrever em detalhes os parâmetros do comando command1. Esta informação
           será utilizada para verificar o número de argumentos eseus tipos.

           Você pode preceder o comando command1 por

           an asterisk (*)
               po4a irá extrair este comando a partir de parágrafos (se ele está localizado no
               começo ou o fim de um parágrafo). Os tradutores terão então de traduzir os
               parâmetros que são marcados como traduzível.

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

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

           um menos (-)
               Neste caso, o comando não será extraído a partir de qualquer bloco. Mas se aparece
               sozinho num bloco, então, apenas os parâmetros marcados como traduzíveis serão
               apresentados ao tradutor. Isto é útil para os comandos de fonte. Estes comandos
               geralmente não devem ser separados dos seus parágrafos (para manter o contexto),
               mas não há motivo para chatear o tradutor com eles, se uma sequência inteira é
               incluída em tal comando.

           O argumento parameters é um conjunto de [] (para indicar um argumento opcional)
            ou {} (para indicar um argumento obrigatório).  Pode colocar um traço baixo (_) entre
           estas chavetas para indicar isso O parâmetro deve ser traduzido. Por exemplo:
            % po4a: command *chapter [_]{_}

           Isto indica que o comando capítulo tem dois parâmetros: um opcional (título curto) e
           um obrigatório, que devem ser ambos traduzidos.  Se você quer especificar que o
           comando 'href' tem dois parâmetros obrigatórios, que você não quer traduzir o 'URL'
           (primeiro parâmetro), e que você não quer que esse comando seja separado do seu
           parágrafo (que permitem ao tradutor mover a ligação (link) na frase), pode usar:
            %po4a: comando -href {} {_}

           Neste caso, a informação indicando que argumentos devem ser traduzidos só é usada se
           um parágrafo é composto apenas por este comando href.

       % po4a: ambiente env parameters
           This permits to define the parameters accepted by the env environment.  This
           information is later used to check the number of arguments of the \begin command, and
           permit to specify which one must be translated.  The syntax of the parameters argument
           is the same as described for the others commands.  The first parameter of the \begin
           command is the name of the environment.  This parameter must not be specified in the
           list of parameters. Here are some examples:
            % po4a: environment multicols {}
            % po4a: environment equation

           Como para os comandos, env pode ser precedido por um sinal de mais (+) para indicar
           que o comando \begin deve ser traduzido com todos os seus argumentos.

       % po4a: separator env "regex"
           Indica que um ambiente deve ser dividido de acordo com a expressão regular dada.

           A expressão regular é delimitada por aspas. Não deve criar qualquer referência de
           volta. Deve usar (?:) se precisa de um grupo. Também pode precisar alguns 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 por células
           por '&').

           A noção de ambiente é dependida com o tipo exibido no ficheiro PO.Isto pode ser usado
           para dividir no "\\\\" primeiro argumento obrigatório do comando do título. Neste
           caso, o meio ambiente é title{# 1}.

       B <% po4a: ambiente textual> env
           Indica que env é um ambiente textual. Comentários e comandos serão serão ignorados
           neste ambiente.

           Se este ambiente não foi já registado, po4a irá considerar que este ambiente não leva
           nenhum parâmetro.

ESCREVENDO MÓDULOS DERIVADOS

       pre_trans
       post_trans
       translate
           Envolvido em torno 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 PO para o primeiro
           sequência traduzida deste parágrafo.

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

           Um nome de comando
               Se nenhum comando é encontrado no inicio do 'buffer' dado, esta sequência estará
               vazia. Apenas os comandos que podem ser separados são considerados. O
               %separated_command contém a lista desses comandos.

           Uma variante
               Isto indica se uma variante é usada. Por exemplo, um asterisco (*) pode ser
               adicionado no final das secções de comando para especificar que não devem ser
               numerada. Neste caso, o campo irá conter "*". Se não houver uma variante, o campo
               é uma sequência vazia.

           Uma matriz de tuplos (tipo de argumento, argumento)
               O tipo de argumento pode ser '{' (para argumentos obrigatórios) ou '[' (para
               argumentos opcionais).

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

       get_trailing_command($buffer)
           O mesmo que get_leading_command, mas para comandos no fim do 'buffer'.

       translate_buffer
           Recursivamente traduzir um 'buffer' separando comandos à esquerda e à direita (aqueles
           que devem ser convertidos em separado) a partir do 'buffer'.

           Se uma função é definida em %translate_buffer_env para o atual ambiente, esta função
           irá ser usada para converter o 'buffer' em vez de translate_buffer ().

       read
           Overloads Transtractor's read().

       read_file
           Recursivamente ler um ficheiro, anexando ficheiros incluídos que não estão listadas na
           matriz @exclude_include. Ficheiros incluídos são pesquisados ​​utilizando o comando
           kpsewhich comando a partir da biblioteca kpathsea.

           Com exceção de parte a inclusão do ficheiros, é um corte e cole a partir da leitura
           Transtractor.

       parse_definition_file
           Sub-rotina para analisar um ficheiro com as directivas po4a (definições de
           novoscomandos).

       parse_definition_line
           Analisar uma linha de definição da forma "% po4a:".

           Ver a secção INLINE CUSTOMIZATION para mais detalhes.

       is_closed
       docheader

FUNÇÕES INTERNAS usadas para escrever analises derivadas

       Funções de comando e ambiente que precisam dos seguintes argumentos (em adição do objeto
       $self):

       Um nome de comando
       Uma variante
       Uma matriz de tuplos (tipo, argumneto)
       O ambiente corrente

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

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

       Funções do ambiente são chamadas quando um comando \begin é encontrado. Eles são chamados
       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 as informações especificadas por register_generic_command ou pela
       adição de definição para o ficheiro TeX:
        %po4a: comando command1 parameters

       generic_environment usa as informações especificadas por register_generic_environment ou
       pela adição de definição para o ficheiro TeX: %po4a: ambiente env parameters

       Ambas as funções só traduzem os parâmetros que foram especificados como traduzível (com um
       '_'). generic_environment irá acrescentar o nome do ambiente para a pilha do ambiente e
       generic_command irá acrescentar o nome do comando seguido por um identificador do
       parâmetro (como {#7} ou [#2]).

STATUS DESTE MÓDULO

       Este módulo precisa de mais testes.

       Ele foi testado num livro e com a documentação de Python.

LISTA PARAFAZER

       Detecção automática de novos comandos
           O módulo TeX pode analisar os argumentos do novo comando e tentar adivinhar o número
           de argumentos, seu tipo e se eles devem ou não ser traduzidos.

       Tradução do separador de ambiente
           Quando \item é utilizado como um separador de ambiente, o argumento item é ligado à
           seguinte sequência.

       Alguns comandos devem ser adicionados à pilha de ambiente
           Esses comandos devem ser especificados por pares. Isto poderia permitir especificar
           comandos de abertura ou fecho num ambiente textual.

       Outros
           Vários outros pontos são marcados A FAZER na fonte.

ERROS CONHECIDOS

       Vários pontos são marcados CORREÇÃO na fonte.

VER TAMBÉM

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

AUTORES

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

DIREITOS DE AUTOR E LICENÇA

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

       Este programa é software livre, você pode redistribuí-lo e/ou modificá-lo sob os termos da
       GPL (consulte o ficheiro CÓPIA).