
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 NOME

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

=head1 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
outras línguas [humanas]. Também pode ser usado como uma base para a
construção de módulos para documentos baseados em TeX.

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.

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

Há algumas opções (descritas na próxima secção) que podem personalizar este
comportamento.   Se isso não se adequar ao formato do seu documento,
encorajamos-o a escrever o seu próprio módulo derivado deste, para descrever
os detalhes do seu formato.   Veja a secção abaixo B<WRITING DERIVATE
MODULES>, para a descrição do processo.

Esse módulo também pode ser personalizado por linhas iniciais com "% po4a:"
no ficheiro TeX. Esse processo é descrito na secção B<INLINE CUSTOMIZATION>.

=head1 OPÇÕES ACEITES POR ESTE MÓDULO

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

=over 4

=item B<debug>

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

=item B<no_wrap>

Lista de ambientes separados por vírgulas que não devem ser re-envolvidos.

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

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

=item B<exclude_include>

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

=item B<definitions>

O nome de um ficheiro que contém as definições para po4a, como definido na
secção B<INLINE CUSTOMIZATION>. Pode usar esta opção se não é possível pôr
as definições no documento a ser traduzido.

=item B<verbatim>

Lista de ambientes separados por vírgulas que devem ser tomados como
literais.

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

=back

Use essas opções para sobrepor o comportamento predefinido dos comandos
definidos.

=head1 PERSONALIZAÇÃO EM LINHA

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

=over 4

=item B<% po4a: command> I<command1> B<alias> I<command2>

Indica que os argumentos do comando I<command1> devem ser tratado como os
argumentos do comando I<command2>.

=item B<% po4a: command> I<command1> I<parameters>

Isso descreve em detalhe os parâmetros do comando I<comando1>.   Essa
informação será usada para verificar a quantidade de argumentos e os seus
tipos.

Pode preceder o comando I<command1> por

=over 4

=item um asterisco (B<*>)

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.

=item um sinal mais (B<+>)

Assim como o asterisco, o comando será extraído se ele aparecer numa
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, 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.

=item um sinal menos (B<->)

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.

=back

O argumento I<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 que indica quais argumentos devem ser traduzidos só
é usada se um parágrafo é composto apenas por este comando href.

=item B<% po4a: environment> I<env> I<parameters>

Isso define os parâmetros aceites pelo ambiente I<ambiente> e especifica quais serão traduzidos.
Essa informação é posteriormente usada para verificar a quantidade de argumentos
do comando \begin.
A sintaxe do argumento I<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

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

=item B<% po4a: separator> I<env> B<">I<regex>B<">

Indica que um ambiente deve ser dividido de acordo com a expressão regular
dada.

A expressão regular é delimitada por aspas. Ela não deveria criar qualquer
referência própria.  Deveria usar (?:) se precisa de um grupo.   Também pode
ser necessário 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 é expandida ao tipo exibido no ficheiro PO. Isso pode
ser usado para dividir em "\\\\" no primeiro argumento obrigatório no
comando title. neste caso, o ambiente é title{#1}.

=item B<% po4a: verbatim environment> I<env>

Indica que I<env> é um ambiente literal.   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.

=back

=head1 ESCREVENDO MÓDULOS de DERIVA

=over 4

=item B<pre_trans>

=item B<post_trans>

=item B<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.

=item B<translate>

Envólucro 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.

=item B<get_leading_command>($buffer)

Esta função retorna:

=over 4

=item 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. A
cinza %separated_command contém a lista desses comandos.

=item 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 numeradas. Neste caso, o campo irá conter "*".  Se não houver uma
variante, o campo é uma cadeia vazia.

=item Uma matriz de tuplos (tipo de argumento, argumento)

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

=item O 'buffer' restante

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

=back

=item B<get_trailing_command>($buffer)

O mesmo que B<get_leading_command>, mas para comandos no fim dum 'buffer'.

=item B<translate_buffer>

Recursivamente traduz um 'buffer' ao separar comandos à esquerda e à direita
(aqueles que devem ser traduzidos em separado) a partir do 'buffer'.

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

=item B<read>

Sobrecarrega o read() do Transtractor.

=item B<read_file>

Recursivamente lê um ficheiro, anexando ficheiros incluídos que não estão
listados na matriz @exclude_include. Ficheiros incluídos são pesquisados
utilizando o comando B<kpsewhich> a partir da biblioteca kpathsea.

Com excepção da parte da inclusão do ficheiro, é um corte e cole a partir da
leitura do Transtractor.

=back

=over 4

=item B<parse_definition_file>

Sub-rotina para analisar um ficheiro com as diretivas po4a (definições de
novos comandos).

=item B<parse_definition_line>

Analisa uma linha de definição do formato "% po4a:".

Veja a secção B<INLINE CUSTOMIZATION> para mais detalhes.

=item B<is_closed>

=item B<parse>

=item B<docheader>

=back

=head1 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):

=over

=item Um nome de comando

=item Uma variante

=item Uma matriz de tuplos (tipo, argumento)

=item O ambiente atual

=back

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 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 os 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 I<command1> I<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 I<env> I<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]).

=head1 ESTADO DESTE MÓDULO

Este módulo precisa de mais testes.

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

=head1 LISTA de A FAZER

=over 4

=item 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.

=item Tradução do separador de ambiente

Quando \item é utilizado como um separador de ambiente, o argumento item é
ligado à seguinte cadeia.

=item Alguns comandos devem ser adicionados à pilha de ambiente

Estes comandos deveriam ser especificados por pares.  Isto pode ser usado
para especificar comandos iniciando ou terminando um ambiente literal.

=item Outros

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

=back

=head1 BUGS CONHECIDOS

Vários pontos são marcados CORRIGIR na fonte.

=head1 VEJA TAMBÉM

L<Locale::Po4a::LaTeX(3pm)|Locale::Po4a::LaTeX>,
L<Locale::Po4a::TransTractor(3pm)|Locale::Po4a::TransTractor>,
L<po4a(7)|po4a.7>

=head1 AUTORES

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

=head1 DIREITOS DE AUTOR E LICENÇA

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

Este programa é um software livre; pode redistribuí-lo e/ou modificá-lo sob
os termos da GPL v2.0 ou posterior (veja o ficheiro COPYING).
