Provided by: po4a_0.73-2ubuntu1_all 
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 de texto 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. Esse processo
é descrito 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 de texto 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 como literais.
Se esse ambiente ainda não foi registrado, po4a vai considerar que ele não leva parâmetros.
Use essas opções para sobrescrever o comportamento padrão dos comandos definidos.
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 descreve 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 mantém 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 define os parâmetros aceitos pelo ambiente ambiente e especifica quais serão traduzidos. Essa
informação é posteriormente usada para verificar o número de argumentos do comando \begin. 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 exemplos:
% 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
add_comment
Adiciona uma string 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
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
parse
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 pode ser usado para 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 v2.0 ou
posterior (veja o arquivo COPYING).
perl v5.38.2 2024-08-28 LOCALE::PO4A::TEX.3PM(1)