Provided by: po4a_0.66-1_all 
NOME
Locale::Po4a::TeX - convert TeX documents and derivatives from/to PO files
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::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.
Utilizadores 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.
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).
There are some options (described in the next section) that can customize this behavior.
If this doesn't fit to your document format you're encouraged to write your own derivative
module from this, to describe your format's details. See the section WRITING DERIVATIVE
MODULES below, for the process description.
This module can also be customized by lines starting with "% po4a:" in the TeX file. This
process is described in the INLINE CUSTOMIZATION section.
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 de um ficheiro que contém as definições para po4a, como definido na secção
INLINE CUSTOMIZATION. Pode usar esta opção se não é possível pôr 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
predefinidas.
INLINE CUSTOMAZITION
O módulo TeX pode ser personalizado com linhas a começar 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 comando 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 a quantidade de argumentos e os tipos deles.
Pode preceder o comando command1 por
um asterisco (*)
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, não tem que especificar quais os parâmetros que são traduzíveis,
mas po4a deve saber o tipo e a quantidade 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 cadeia 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 pôr 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 quer especificar que o comando
'href' tem dois parâmetros obrigatórios, que não quer traduzir o 'URL' (primeiro
parâmetro) e que 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 a indicar que argumentos devem ser traduzidos só é usada se
um parágrafo é composto apenas por este comando href.
% po4a: ambiente env parameters
Isso permite definir os parâmetros aceitos pelo ambiente ambiente. Essa informação é
posteriormente usada para verificar a quantidade 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
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 '&').
The notion of environment is expanded to the type displayed in the PO file. This can
be used to split on "\\\\" in the first mandatory argument of the title command. In
this case, the environment is title{#1}.
B <% po4a: ambiente textual> env
Indica que env é um ambiente textual. Comentários e comandos 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
add_comment
Adiciona uma cadeia como um comentário a ser adicionado em torno do próximo elemento
traduzido. Isso é principalmente útil para o módulo texinfo, já que os comentários
são tratados automaticamente no TeX.
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 a primeira cadeia
traduzida deste parágrafo.
get_leading_command($buffer)
Esta função retorna:
Um nome de comando
Se nenhum comando é encontrado no início do 'buffer' dado, esta cadeia 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 cadeia 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 os argumentos dele.
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' a separar 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
Sobrepõe o read() do Transtractor.
read_file
Recursivamente ler um ficheiro, a anexar ficheiros incluídos que não estão listadas na
matriz @exclude_include. Ficheiros incluídos são pesquisados a utilizar 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
parse
docheader
FUNÇÕES INTERNAS usadas para escrever analisadores derivados
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 os argumentos dele 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 os argumentos dele.
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 à pilha do ambiente e
generic_command irá acrescentar o nome do comando seguido por um identificador do
parâmetro (como {#7} ou [#2]).
ESTADO 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 a
quantidade de argumentos, o tipo deles 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 cadeia.
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, pode redistribuí-lo e/ou modificá-lo sob os termos da GPL
(consulte o ficheiro CÓPIA).