". Em nome da simplicidade, nós presumimos que o documento está bem formatado, ou seja, que as marcações "
" são as únicas marcações apresentadas e que essa marcação está exatamente no começo de cada parágrafo. .PP .Vb 2 \& sub parse { \& my $self = shift; \& \& PARAGRAPH: while (1) { \& my ($paragraph,$pararef)=("",""); \& my $first=1; \& my ($line,$lref)=$self\->shiftline(); \& while (defined($line)) { \& if ($line =~ m/
/ && !$first\-\-; ) { \& # Não é a primeira vez que vemos
. \& # Colocar novamnete a linha atual na entrada, \& # e colocar o parágrafo compilado na saída \& $self\->unshiftline($line,$lref); \& \& # Agora que o documento está formado, traduza\-o: \& # \- Remove a marcação no começo \& $paragraph =~ s/^
//s; \& \& # \- envia para a saída a marcação no começo (não \& # traduzida) e o resto do parágrafo (traduzido) \& $self\->pushline( "
"
\& . $self\->translate($paragraph,$pararef)
\& );
\&
\& next PARAGRAPH;
\& } else {
\& # Anexa ao parágrafo
\& $paragraph .= $line;
\& $pararef = $lref unless(length($pararef));
\& }
\&
\& # Reinicia o loop
\& ($line,$lref)=$self\->shiftline();
\& }
\& # Não conseguiu uma linha definida? Termina com o
\& # arquivo de entrada.
\& return;
\& }
\& }
.Ve
.PP
Uma vez que você tenha implementada a função de análise, você pode usar sua classe de documento, usando a interface pública apresentada na seção seguinte.
.SH "INTERFACE PÚBLICA para scripts usando seu analisador"
.IX Header "INTERFACE PÚBLICA para scripts usando seu analisador"
.SS Construtor
.IX Subsection "Construtor"
.IP process(%) 4
.IX Item "process(%)"
Essa função pode fazer tudo que você precisa fazer com um documento po4a em uma chamada. Seus argumentos devem ser empacotados como um hash. AÇÕES:
.RS 4
.IP a. 3
.IX Item "a."
Lê todos os arquivos PO especificados em po_in_name
.IP b. 3
.IX Item "b."
Lê todos os documentos originais especificados em file_in_name
.IP c. 3
.IX Item "c."
Analisa o documento
.IP d. 3
.IX Item "d."
Lê e aplica todos os adendos especificados
.IP e. 3
.IX Item "e."
Escreve o documento traduzido para file_out_name (se fornecido)
.IP f. 3
.IX Item "f."
Escreve o arquivo PO extraído para po_out_name (se fornecido)
.RE
.RS 4
.Sp
ARGUMENTOS, além dos aceitos por \fBnew()\fR (com o tipo esperado):
.IP "file_in_name (@)" 4
.IX Item "file_in_name (@)"
Lista de nomes de arquivos nos quais nós deveríamos ler o documento de entrada.
.IP "file_in_charset ($)" 4
.IX Item "file_in_charset ($)"
Conjunto de caracteres usado no documento de entrada (se esse não for especificado, usa UTF\-8).
.IP "file_out_name ($)" 4
.IX Item "file_out_name ($)"
Nome de arquivo no qual nós deveríamos escrever o documento de saída.
.IP "file_out_charset ($)" 4
.IX Item "file_out_charset ($)"
Conjunto de caracteres usado no documento de saída (se esse não for especificado, usa UTF\-8).
.IP "po_in_name (@)" 4
.IX Item "po_in_name (@)"
Lista de nomes de arquivos dos quais nós deveríamos ler os arquivos PO de entrada, contendo a tradução que será usada para traduzir o documento.
.IP "po_out_name ($)" 4
.IX Item "po_out_name ($)"
Nome de arquivo no qual nós deveríamos escrever o arquivo PO de saída, contendo as strings extraídas do documento de entrada.
.IP "addendum (@)" 4
.IX Item "addendum (@)"
Lista de nomes de arquivos nos quais nós deveríamos ler os adendos.
.IP "addendum_charset ($)" 4
.IX Item "addendum_charset ($)"
Conjunto de caracteres para o adendos.
.RE
.RS 4
.RE
.IP new(%) 4
.IX Item "new(%)"
Cria um novo documento de po4a. Opções aceitas são (no hash passado como parâmetro):
.RS 4
.IP "verbose ($)" 4
.IX Item "verbose ($)"
Define o detalhamento.
.IP "debug ($)" 4
.IX Item "debug ($)"
Define a depuração.
.IP "wrapcol ($)" 4
.IX Item "wrapcol ($)"
The column at which we should wrap text in output document (default: 76).
.Sp
The negative value means not to wrap lines at all.
.RE
.RS 4
.Sp
Also it accepts next options for underlying Po-files: \fBporefs\fR, \fBcopyright-holder\fR, \fBmsgid-bugs-address\fR, \fBpackage-name\fR, \fBpackage-version\fR, \fBwrap-po\fR.
.RE
.SS "Manipulação de arquivos de documento"
.IX Subsection "Manipulação de arquivos de documento"
.IP read($$$) 4
.IX Item "read($$$)"
Add another input document data at the end of the existing array \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR.
.Sp
This function takes two mandatory arguments and an optional one.
* The filename to read on disk;
* The name to use as filename when building the reference in the PO file;
* The charset to use to read that file (UTF\-8 by default)
.Sp
Esse vetor \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR detém os dados desse documento de
entrada como um vetor e strings com significados alternativos.
* A string \f(CW$textline\fR detendo cada linha de dados de texto de entrada.
* A string \f(CW\*(C`$filename:$linenum\*(C'\fR detendo sua localização e chamada
como "referência" (\f(CW\*(C`linenum\*(C'\fR inicia com 1).
.Sp
Por favor note que ele analisa nada. Você deveria usa a função \fBparse()\fR quando você acabar de empacotar os arquivos de entrada no documento.
.IP write($) 4
.IX Item "write($)"
Escreve o documento traduzido no nome de arquivo fornecido.
.Sp
Os dados desse documento traduzido são fornecidos por:
* \f(CW\*(C`$self\->docheader()\*(C'\fR detendo o texto de cabeçalho para o plugin, e
* \f(CW\*(C`@{$self\->{TT}{doc_out}}\*(C'\fR detendo cada linha do principal texto traduzido no vetor.
.SS "Manipulação de arquivos PO"
.IX Subsection "Manipulação de arquivos PO"
.IP readpo($) 4
.IX Item "readpo($)"
Adiciona o conteúdo de um arquivo, cujo nome é passado como argumento, ao PO de entrada existente. O conteúdo antigo é descartado.
.IP writepo($) 4
.IX Item "writepo($)"
Escrever o arquivo PO extraído para o nome de arquivo fornecido.
.IP \fBstats()\fR 4
.IX Item "stats()"
Retorna algumas estatísticas sobre a tradução realizada até o mesmo. Por favor, note que não são as mesmas estatísticas mostradas pelo "msgfmt \-\-statistic". Aqui, são as estatísticas sobre uso recente do arquivo PO, enquanto o msgfmt relata o status do arquivo. Ele é um wrapper da função Locale::Po4a::Po::stats_get aplicada ao arquivo PO de entrada. Exemplo de uso:
.Sp
.Vb 1
\& [uso normal de um documento po4a...]
\&
\& ($percent,$hit,$queries) = $document\->stats();
\& print "Nós encontramos de $percent\e% ($hit de $queries) das strings.\en";
.Ve
.SS "Manipulando adendos"
.IX Subsection "Manipulando adendos"
.IP addendum($) 4
.IX Item "addendum($)"
Por favor veja o \fBpo4a\fR\|(7) para mais informações sobre o que são adendos e como tradutores deveriam escrevê\-los. Para aplicar um adendo ao documento traduzido, simplesmente passe seu nome de arquivo para essa função e pronto ;)
.Sp
Essa função retorna um inteiro não nulo quando há um erro.
.SH "FUNÇÕES INTERNAS usadas para escrever analisadores derivados"
.IX Header "FUNÇÕES INTERNAS usadas para escrever analisadores derivados"
.SS "Obtendo a entrada, fornecendo a saída"
.IX Subsection "Obtendo a entrada, fornecendo a saída"
Quatro funções são fornecidas para obter entrada e retornar a saída. Elas são muito parecidas com shift/unshift e push/pop de Perl.
.PP
.Vb 4
\& * Perl shift retorna o primeiro item do vetor e solta\-o do vetor.
\&* Perl unshift preenche um item no vetor como o primeiro item do vetor.
\&* Perl pop retorna o último item do vetor e solta\-o do vetor.
\&* Perl push acrescenta um item ao vetor como o último item do vetor.
.Ve
.PP
O primeiro par é sobre entrada, enquanto ao segundo é sobre saída. Mnemônico: na entrada, você está interessada na primeira linha, que é o que o shift fornece, e na saída você quer adicionar seu resultado ao final, como o push faz.
.IP \fBshiftline()\fR 4
.IX Item "shiftline()"
Esta função retorna a primeira linha a ser analisada e a sua referência correspondente (empacotada como um vetor) do vetor \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR e descarta estes 2 primeiros itens do vetor. Aqui, a referência é fornecida por uma string \f(CW\*(C`$filename:$linenum\*(C'\fR.
.IP unshiftline($$) 4
.IX Item "unshiftline($$)"
Executa unshift a última linha "shiftada" do documento de entrada e sua referência correspondente de volta para o cabeçalho de \f(CW\*(C`{$self\->{TT}{doc_in}}\*(C'\fR.
.IP pushline($) 4
.IX Item "pushline($)"
Envia uma nova linha para o fim de \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR.
.IP \fBpopline()\fR 4
.IX Item "popline()"
Volta, do fim de \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR, a linha anteriormente enviada.
.SS "Marcando strings como traduzíveis"
.IX Subsection "Marcando strings como traduzíveis"
Uma função é fornecida para manipular o texto que deveria ser traduzido.
.IP translate($$$) 4
.IX Item "translate($$$)"
Argumentos obrigatórios:
.RS 4
.IP \- 2
Uma string para traduzir
.IP \- 2
A referência dessa string (i.e. posição no arquivo de entrada)
.IP \- 2
O tipo dessa string (i.e. a descrição textual de seu papel estrutural; usado em \fBLocale::Po4a::Po::gettextization()\fR; veja também \fBpo4a\fR\|(7), seção \fBGettextização: como ela funciona?\fR)
.RE
.RS 4
.Sp
Essa função também pode levar alguns argumentos extras. Eles devem ser organizados como um hash. Por exemplo:
.Sp
.Vb 2
\& $self\->translate("string","ref","type",
\& \*(Aqwrap\*(Aq => 1);
.Ve
.IP \fBwrap\fR 4
.IX Item "wrap"
booleano indicando se nós podemos considerar que espaços em brancos nas strings não são importantes. Se sim, a função canoniza a string antes de procurar por uma tradução ou de extrair, e dimensiona a tradução.
.IP \fBwrapcol\fR 4
.IX Item "wrapcol"
the column at which we should wrap (default: the value of \fBwrapcol\fR specified during creation of the TransTractor or 76).
.Sp
The negative value will be substracted from the default.
.IP \fBcomment\fR 4
.IX Item "comment"
um comentário extra para adicionar ao registro.
.RE
.RS 4
.Sp
Ações:
.IP \- 2
Envia a string, referência e tipo para po_out.
.IP \- 2
Retorna a tradução da string (como encontrado em po_in) de forma que o analisador pode compilar o doc_out.
.IP \- 2
Manipula os conjuntos de caracteres para re-codificar as strings antes de enviá\-las para po_out e antes de retornar as traduções.
.RE
.RS 4
.RE
.SS "Funções miscelânea"
.IX Subsection "Funções miscelânea"
.IP \fBverbose()\fR 4
.IX Item "verbose()"
Retorna se a opção de detalhamento foi passada durante a criação do TransTractor.
.IP \fBdebug()\fR 4
.IX Item "debug()"
Retorna se a opção de depuração foi passada durante a criação do TransTractor.
.IP \fBget_in_charset()\fR 4
.IX Item "get_in_charset()"
Esta função retorna o charset que foi fornecido como o charset mestre
.IP \fBget_out_charset()\fR 4
.IX Item "get_out_charset()"
Essa função vai retornar o conjunto de caracteres que deveria ser usado no documento do entrada (normalmente útil para substituir o conjunto de caracteres detectado no documento de entrada, onde ele foi encontrado).
.Sp
Ele vai usar o conjunto de caracteres de saída especificado na linha de comando. Se não tiver sido especificado, ele vai usar o conjunto de caracteres do PO de entrada, e se o PO de entrada possuir o "CHARSET" padrão, ele vai retornar o conjunto de caracteres do documento de entrada, de forma que nenhuma codificação é realizada.
.SH "DIREÇÕES FUTURAS"
.IX Header "DIREÇÕES FUTURAS"
Um problema do atual TransTractor é que ele não consegue manipular documento traduzido contendo todos idiomas, como modelos de debconf, ou arquivos .desktop.
.PP
Para resolver esse problema, as únicas alterações necessárias na interface são:
.IP \- 2
pegar um hash como po_in_name (uma lista por idioma)
.IP \- 2
adicionar um argumento para traduzir para indicar o idioma alvo
.IP \- 2
fazer uma função pushline_all, que deveria fazer pushline de seu conteúdo para todos idiomas, usando uma sintaxe tipo mapa:
.Sp
.Vb 3
\& $self\->pushline_all({ "Description[".$langcode."]=".
\& $self\->translate($line,$ref,$langcode)
\& });
.Ve
.PP
Veremos se isso é o suficiente ;)
.SH AUTORES
.IX Header "AUTORES"
.Vb 3
\& Denis Barbier