\*(R". For the sake of simplicity, we assume that the document is well formatted, i.e. that '
' tags are the only tags present, and that this tag is at the very beginning of each paragraph. .PP .Vb 2 \& sub parse { \& my $self = shift; \& \& PARAGRAF: while (1) { \& $my ($paragraf,$pararef)=("","","",""); \& $my $primera=1; \& my ($linia,$lref)=$self\->shiftline(); \& while (defined($linia)) { \& if ($linia =~ m/
/ && !$primera\-\-; ) { \& # No és la primera vegada que veiem
. \& # Tornem a posar la línia actual a l\*(Aqentrada, \& # i posem el paràgraf construït a la sortida \& $document\->unshiftline($linia,$lref); \& \& # Ara que el document està construït, el traduïm: \& # \- Eliminem el tag del principi \& $paragraf =~ s/^
//s; \& \& # \- push to output the leading tag (untranslated) and the \& # rest of the paragraph (translated) \& $self\->pushline( "
"
\& . $self\->translate($paragraph,$pararef)
\& );
\&
\& next PARAGRAF;
\& } else {
\& # L\*(Aqafegim al paràgraf
\& $paragraf .= $linia;
\& $pararef = $lref unless(length($pararef));
\& }
\&
\& # Reinit the loop
\& ($line,$lref)=$self\->shiftline();
\& }
\& # Did not get a defined line? End of input file.
\& return;
\& }
\& }
.Ve
.PP
Un cop hagueu implementat la vostra funció parse, ja podeu utilitzar la
vostra classe de documents, a través de la interfície pública presentada a
la següent secció.
.SH "INTERFÍCIE PÚBLICA per guions que utilitzin el vostre analitzador"
.IX Header "INTERFÍCIE PÚBLICA per guions que utilitzin el vostre analitzador"
.SS "Constructor"
.IX Subsection "Constructor"
.IP "process(%)" 4
.IX Item "process(%)"
Aquesta funció pot fer tot el que necessiteu fer amb un document po4a en una
única invocació. Els seus paràmetres han d'estar empaquetats com a un
hash. \s-1ACCIONS:\s0
.RS 4
.IP "a." 3
.IX Item "a."
Llegeix tots els fitxers \s-1PO\s0 especificats a po_in_name
.IP "b." 3
.IX Item "b."
Llegeix tots els documents originals especificats a file_in_name
.IP "c." 3
.IX Item "c."
Analitza el document
.IP "d." 3
.IX Item "d."
Llegeix i aplica els annexes especificats
.IP "e." 3
.IX Item "e."
Escriu el document traduït a file_out_name (si es dóna)
.IP "f." 3
.IX Item "f."
Escriu el fitxer \s-1PO\s0 extret a po_out_name (si es dóna)
.RE
.RS 4
.Sp
PARÀMETRES, a part dels acceptats per \fBnew()\fR (amb el tipus esperat):
.IP "file_in_name (@)" 4
.IX Item "file_in_name (@)"
Llista dels noms dels fitxers dels que s'ha de llegir el document d'entrada.
.IP "file_in_charset ($)" 4
.IX Item "file_in_charset ($)"
Joc de caràcters utilitzat en el document d'entrada (si no s'especifica,
s'intentarà detectar del document d'entrada).
.IP "file_out_name ($)" 4
.IX Item "file_out_name ($)"
Nom del fitxer on s'ha d'escriure el document de sortida.
.IP "file_out_charset ($)" 4
.IX Item "file_out_charset ($)"
Joc de caràcters utilitzat en el document de sortida (si no s'especifica,
s'utilitzarà el joc de caràcters del fitxer \s-1PO\s0).
.IP "po_in_name (@)" 4
.IX Item "po_in_name (@)"
Llistat dels noms dels fitxers dels que llegirem els \s-1PO\s0 d'entrada, que
contindran la traducció que s'utilitzarà per traduir el document.
.IP "po_out_name ($)" 4
.IX Item "po_out_name ($)"
Nom del fitxer on s'escriurà el fitxer \s-1PO\s0 de sortida, que contindrà les
cadenes extretes del document d'entrada.
.IP "addendum (@)" 4
.IX Item "addendum (@)"
List of filenames where we should read the addenda from.
.IP "addendum_charset ($)" 4
.IX Item "addendum_charset ($)"
Joc de caràcters dels annexes.
.RE
.RS 4
.RE
.IP "new(%)" 4
.IX Item "new(%)"
Crea un nou document de po4a. Accepta les següents opcions (empaquetades en
un hash):
.RS 4
.IP "verbose ($)" 4
.IX Item "verbose ($)"
Ajusta el nivell d'informació extra.
.IP "debug ($)" 4
.IX Item "debug ($)"
Activa la depuració.
.RE
.RS 4
.RE
.SS "Manipulant fitxers de documentació"
.IX Subsection "Manipulant fitxers de documentació"
.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. The argument is the filename to read. If a second
argument is provided, it is the filename to use in the references.
.Sp
This array \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR holds this input document data as an
array of strings with alternating meanings.
* The string \f(CW$textline\fR holding each line of the input text data.
* The string \f(CW\*(C`$filename:$linenum\*(C'\fR holding its location and called as
\*(L"reference\*(R" (\f(CW\*(C`linenum\*(C'\fR starts with 1).
.Sp
Tingueu en compte que això no analitza res. Haureu de cridar la funció
\&\fBparse()\fR quan hagueu acabat d'empaquetar els fitxers d'entrada en el
document.
.IP "write($)" 4
.IX Item "write($)"
Escriu el document traduït al fitxer amb el nom donat.
.Sp
This translated document data are provided by:
* \f(CW\*(C`$self\->docheader()\*(C'\fR holding the header text for the plugin, and
* \f(CW\*(C`@{$self\->{TT}{doc_out}}\*(C'\fR holding each line of the main translated text in the array.
.SS "Manupulant fitxers \s-1PO\s0"
.IX Subsection "Manupulant fitxers PO"
.IP "readpo($)" 4
.IX Item "readpo($)"
Afegeix el contingut d'un fitxer (el nom del qual s'ha de passar com a
paràmetre) al \s-1PO\s0 d'entrada actual. No es descarta el contingut anterior.
.IP "writepo($)" 4
.IX Item "writepo($)"
Escriu el fitxer \s-1PO\s0 extret al fitxer amb el nom donat.
.IP "\fBstats()\fR" 4
.IX Item "stats()"
Retorna algunes estadístiques de la traducció feta fins al moment. Tingueu
en compte que no són les mateixes estadístiques que mostra msgfmt
\&\-\-statistic. Aquestes són estadístiques sobre l'ús recent del fitxer \s-1PO,\s0
mentre que msgfmt mostra l'estat del fitxer. Simplement crida la funció
Locale::Po4a::Po::stats_get sobre el fitxer \s-1PO\s0 d'entrada. Exemple d'ús:
.Sp
.Vb 1
\& [ús normal del document po4a...]
\&
\& ($percentatge,$encerts,$peticions) = $document\->stats();
\& print "S\*(Aqhan trobat traduccions per al $percentatge\e% ($encerts de $peticions) de cadenes.\en";
.Ve
.IP "\fBis_po_uptodate()\fR" 4
.IX Item "is_po_uptodate()"
Returns ($uptodate, \f(CW$diagnostic\fR) where \f(CW$uptodate\fR is whether the input po and
the output po match (if not, it means that the input po should be updated)
and \f(CW$diagnostic\fR is a string explaining why the po file is not uptodate, when
this happens.
.SS "Manipulant annexes"
.IX Subsection "Manipulant annexes"
.IP "addendum($)" 4
.IX Item "addendum($)"
Consulteu \fBpo4a\fR\|(7) per més informació sobre què són els annexes, i
com els han d'escriure els traductors. Per tal d'aplicar un annex al
document traduït, simplement passeu el nom del fitxer a aquesta funció i ja
està ;)
.Sp
Aquesta funció retorna un enter no nul en cas d'error.
.SH "INTERNAL FUNCTIONS used to write derivative parsers"
.IX Header "INTERNAL FUNCTIONS used to write derivative parsers"
.SS "Obtenint entrada, proporcionant sortida"
.IX Subsection "Obtenint entrada, proporcionant sortida"
Four functions are provided to get input and return output. They are very
similar to shift/unshift and push/pop of Perl.
.PP
.Vb 4
\& * Perl shift returns the first array item and drop it from the array.
\& * Perl unshift prepends an item to the array as the first array item.
\& * Perl pop returns the last array item and drop it from the array.
\& * Perl push appends an item to the array as the last array item.
.Ve
.PP
The first pair is about input, while the second is about output. Mnemonic:
in input, you are interested in the first line, what shift gives, and in
output you want to add your result at the end, like push does.
.IP "\fBshiftline()\fR" 4
.IX Item "shiftline()"
This function returns the first line to be parsed and its corresponding
reference (packed as an array) from the array \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR
and drop these first 2 array items. Here, the reference is provided by a
string \f(CW\*(C`$filename:$linenum\*(C'\fR.
.IP "unshiftline($$)" 4
.IX Item "unshiftline($$)"
Unshifts the last shifted line of the input document and its corresponding
reference back to the head of \f(CW\*(C`{$self\->{TT}{doc_in}}\*(C'\fR.
.IP "pushline($)" 4
.IX Item "pushline($)"
Push a new line to the end of \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR.
.IP "\fBpopline()\fR" 4
.IX Item "popline()"
Pop the last pushed line from the end of \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR.
.SS "Marcant cadenes com a traduïbles"
.IX Subsection "Marcant cadenes com a traduïbles"
Es proporciona una funció per tractar el text que s'ha de traduir.
.IP "translate($$$)" 4
.IX Item "translate($$$)"
Paràmetres obligatoris:
.RS 4
.IP "\-" 2
La cadena a traduir
.IP "\-" 2
La cadena de referència (és a dir, la posició al fitxer d'entrada)
.IP "\-" 2
El tipus de la cadena (és a dir, la descripció textual del seu significat
estructural; s'utilitza a \fBLocale::Po4a::Po::gettextization()\fR; consulteu
també la secció \fIGettextització: com funciona?\fR de \fBpo4a\fR\|(7))
.RE
.RS 4
.Sp
Aquesta funció també pot rebre alguns paràmetres extra. Aquests han d'estar
agrupats en un hash. Per exemple:
.Sp
.Vb 2
\& $self\->translate("cadena","ref","tipus",
\& \*(Aqwrap\*(Aq => 1);
.Ve
.IP "\fBwrap\fR" 4
.IX Item "wrap"
booleà que indica si podem considerar que els espais de la cadena no són
importants. Si té valor cert, la funció canonitzarà la cadena abans de
buscar-ne la traducció o d'extreure-la, i en justificarà la traducció.
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
La columna a la que s'ha de justificar (per defecte: 76).
.IP "\fBcomment\fR" 4
.IX Item "comment"
Un comentari extra per afegir a l'entrada.
.RE
.RS 4
.Sp
Accions:
.IP "\-" 2
Insereix la cadena, la referència i el tipus a po_out.
.IP "\-" 2
Retorna la traducció de la cadena (trobada a po_in) per tal que
l'analitzador pugui construir el doc_out.
.IP "\-" 2
Tracta els jocs de caràcters per recodificar les cadenes abans d'enviar-les
a po_out i abans de retornar les traduccions.
.RE
.RS 4
.RE
.SS "Funcions diverses"
.IX Subsection "Funcions diverses"
.IP "\fBverbose()\fR" 4
.IX Item "verbose()"
Retorna el nivell d'informació extra que es va passar durant la creació del
TransTractor.
.IP "\fBdebug()\fR" 4
.IX Item "debug()"
Retorna si s'ha passat l'opció de depuració durant la creació del
TransTractor.
.IP "detected_charset($)" 4
.IX Item "detected_charset($)"
Això informa al TransTractor que s'ha detectat un nou joc de caracters (el
primer paràmetre) del document d'entrada. Habitualment es pot trobar a la
capçalera dels documents. Tan sols es mantindrà el primer joc de caracters
trobat, ja sigui un paràmetre de \fBprocess()\fR o bé sigui detectat del document.
.IP "\fBget_out_charset()\fR" 4
.IX Item "get_out_charset()"
Aquesta funció retorna el joc de caràcters que s'ha d'utilitzar en el
document de sortida (habitualment és útil per substituir el joc de caràcters
del document d'entrada en el lloc on s'ha trobat).
.Sp
Utilitzarà el joc de caràcters especificat a la línia de comandes. Si no
s'ha especificat, utilitzarà el joc de caràcters del \s-1PO\s0 d'entrada, i si el
\&\s-1PO\s0 d'entrada conté el valor per defecte \*(L"\s-1CHARSET\*(R",\s0 retornarà el joc de
caràcters del document d'entrada, de forma que no es realitzi recodificació.
.IP "recode_skipped_text($)" 4
.IX Item "recode_skipped_text($)"
Aquesta funció retorna el text passat com a paràmetre recodificat, des del
joc de caràcters del document d'entrada cap al del document de sortida. Això
no és necessari quan es tradueix una cadena (la funció \fBtranslate()\fR ja
recodifica les traduccions), però és important quan se salta una cadena del
document d'entrada i es vol conservar la consistència en la codificació
global del document de sortida.
.SH "DIRECCIONS FUTURES"
.IX Header "DIRECCIONS FUTURES"
Una deficiència del TransTractor actual és que no pot tractar documents
traduïts que continguin tots els idiomes, com ara les plantilles de debconf,
o els fitxers .desktop.
.PP
Per resoldre aquest problema, els únics canvis necessaris a la interfície
són:
.IP "\-" 2
take a hash as po_in_name (a list per language)
.IP "\-" 2
afegir un paràmetre a translate per indicar l'idioma destí
.IP "\-" 2
make a pushline_all function, which would make pushline of its content for
all languages, using a map-like syntax:
.Sp
.Vb 3
\& $self\->pushline_all({ "Description[".$codiidioma."]=".
\& $self\->translate($linia,$ref,$codiidioma)
\& });
.Ve
.PP
Ja veurem si és suficient ;)
.SH "AUTORS"
.IX Header "AUTORS"
.Vb 3
\& Denis Barbier