». Para simplificar, suponemos que el documento está correctamente formateado, es decir, que sólo hay presentes etiquetas '
', y que esta etiqueta está justo al principio de cada párrafo. .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\-\-; ) { \& # No es la primera vez que vemos
. \& # Devuelve la línea actual a la entrada, \& # y pon el párrafo construido en la salida. \& $self\->unshiftline($line,$lref); \& \& # Ahora que tenemos el documento creado, lo traducimos: \& # \- Eliminamos la etiqueta inicial \& $paragraph =~ s/^
//s; \& \& # \- Ponemos en la salida la etiqueta inicial (sin traducir) y el \& # resto del párrafo (traducido) \& $self>pushline( "
"
\& . $document\->translate($paragraph,$parraref)
\& );
\&
\& next PARAGRAPH;
\& } else {
\& # Añadir al párrafo.
\& $paragraph .= $line;
\& $pararef = $lref unless(length($pararef));
\& }
\&
\& # Reiniciar el bucle
\& ($line,$lref)=$self\->shiftline();
\& }
\&¿ # ¿No se obtuvo una línea definida? Fin del fichero de entrada.
\& return;
\& }
\& }
.Ve
.PP
Una vez haya implementado la función de análisis, ya puede usar su clase de
documento usando la interfaz pública presentada en la siguiente sección.
.SH "INTERFAZ PÚBLICA para scripts que usen su analizador"
.IX Header "INTERFAZ PÚBLICA para scripts que usen su analizador"
.SS "Constructor"
.IX Subsection "Constructor"
.IP "process(%)" 4
.IX Item "process(%)"
Esta función puede hacer todo lo que quiera hacer con un documento po4a en
una invocación:. Sus argumentos deben estar empaquetados como una tabla de
elementos asociativos («hash»). \s-1ACCIONES:\s0
.RS 4
.IP "a." 3
.IX Item "a."
Lee todos los ficheros \s-1PO\s0 especificados en «po_in_name»
.IP "b." 3
.IX Item "b."
Lee todos los documentos originales especificado en «file_in_name»
.IP "c." 3
.IX Item "c."
Analiza el documento
.IP "d." 3
.IX Item "d."
Lee y aplica todos los apéndices especificados
.IP "e." 3
.IX Item "e."
Escribe el documento traducido en «file_out_name» (si se da)
.IP "f." 3
.IX Item "f."
Escribe el fichero \s-1PO\s0 extraído en «po_out_name» (si se da)
.RE
.RS 4
.Sp
\&\s-1ARGUMENTOS,\s0 aparte de los aceptados por «\fBnew()\fR» (con el tipo esperado):
.IP "file_in_name (@)" 4
.IX Item "file_in_name (@)"
Lista de los nombres de ficheros de los que se debe leer el documento de
entrada.
.IP "file_in_charset ($)" 4
.IX Item "file_in_charset ($)"
El juego de caracteres usado en el documento de entrada (si no se
especifica, se intentará detectar del documento de entrada)
.IP "file_out_name ($)" 4
.IX Item "file_out_name ($)"
Nombre del fichero donde se debe escribir el documento de salida.
.IP "file_out_charset ($)" 4
.IX Item "file_out_charset ($)"
El juego de caracteres usado en el documento de salida (si no se especifica,
se usará el juego de caracteres del fichero \s-1PO\s0).
.IP "po_in_name (@)" 4
.IX Item "po_in_name (@)"
Lista de los nombres de ficheros de los que se deben leer los ficheros \s-1PO\s0 de
entrada, y que contienen la traducción que se usará para traducir el
documento.
.IP "po_out_name ($)" 4
.IX Item "po_out_name ($)"
Nombre de fichero en el que se debe escribir el fichero \s-1PO\s0 de salida, el
cual contendrá las cadenas extraídas del documento de entrada.
.IP "addendum (@)" 4
.IX Item "addendum (@)"
Lista de los nombres de los ficheros de los que se deben leer los apéndices.
.IP "addendum_charset ($)" 4
.IX Item "addendum_charset ($)"
El juego de caracteres para los apéndices.
.RE
.RS 4
.RE
.IP "new(%)" 4
.IX Item "new(%)"
Crea un nuevo documento po4a. Las opciones aceptadas (que deben estar en una
tabla «hash»):
.RS 4
.IP "verbose ($)" 4
.IX Item "verbose ($)"
Configura el nivel de verbosidad.
.IP "debug ($)" 4
.IX Item "debug ($)"
Configura la depuración.
.RE
.RS 4
.RE
.SS "Manipulación de ficheros de documentos"
.IX Subsection "Manipulación de ficheros de documentos"
.IP "read($)" 4
.IX Item "read($)"
Añade otro documento de datos de entrada al final de la matriz ya existente
\&\f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR. El argumento es el nombre del fichero que
leer.
.Sp
La matriz \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR contiene estos datos de documentos de entrada
como una matriz de cadenas con significados alternos.
* La cadena \f(CW$textline\fR que contiene cada línea de los datos de texto de entrada.
* La cadena \f(CW\*(C`$filename:$linenum\*(C'\fR que contiene su ubicación, y se denomina
\*(L"referencia\*(R".
.Sp
Cabe destacar que esto no analiza nada. Debe usar la función «\fBparse()\fR»
cuando haya terminado de cargar los ficheros de entrada en el documento.
.Sp
Tenga en cuenta que \f(CW$linenum\fR comienza con 1.
.IP "write($)" 4
.IX Item "write($)"
Escribe el documento traducido al fichero dado.
.Sp
Estos datos de documentos traducidos se proporcionan por:
* \f(CW\*(C`$self\->docheader()\*(C'\fR que contiene el texto de cabecera de la extensión, y
* \f(CW\*(C`@{$self\->{TT}{doc_out}}\*(C'\fR que contiene cada línea del texto traducido principal de la matriz.
.SS "Manipula ficheros \s-1PO\s0"
.IX Subsection "Manipula ficheros PO"
.IP "readpo($)" 4
.IX Item "readpo($)"
Añade el contenido de un fichero (cuyo nombre se introduce como argumento)
al \s-1PO\s0 de entrada existente. El contenido anterior no se desecha.
.IP "writepo($)" 4
.IX Item "writepo($)"
Escribe el fichero \s-1PO\s0 extraído al nombre de fichero dado.
.IP "\fBstats()\fR" 4
.IX Item "stats()"
Devuelve algunas estadísticas sobre el punto actual de la traducción en
curso. Estas no son las mismas estadísticas que las que muestra «msgfmt
\&\-\-statistic». Aquí las estadísticas son sobre el uso reciente del fichero
\&\s-1PO,\s0 mientras que msgfmt informa del estado del fichero. Esto es un «wrapper»
(patrón de diseño) de la función Locale::Po4a::Po::stats_get aplicada al
fichero \s-1PO\s0 de entrada. Ejemplo de uso:
.Sp
.Vb 1
\& [uso normal del documento po4a...]
\&
\& ($porcentaje,$aciertos,$solicitudes) = $documento\->stats();
\& print "Se han encontrado traducciones para el $porcentaje\e% ($aciertos de $solicitudes) de cadenas.\en";
.Ve
.IP "\fBis_po_uptodate()\fR" 4
.IX Item "is_po_uptodate()"
Devuelve ($uptodate, \f(CW$diagnostic\fR) donde \f(CW$uptodate\fR representa su el po de
entrada y el po de salida coinciden (en caso contrario, significa que el se
debería actualizar el po de entrada) y \f(CW$diagnostic\fR es una cadena que detalla
porqué el fichero po no está actualizado, de ser así.
.SS "Manipulación de apéndices"
.IX Subsection "Manipulación de apéndices"
.IP "addendum($)" 4
.IX Item "addendum($)"
Consulte \fBpo4a\fR\|(7) para más información acerca de los apéndices, y
cómo los traductores deben escribirlos. Para aplicar un apéndice a un
documento traducido, simplemente introduzca su nombre de fichero en ésta
función y ya está ;)
.Sp
Esta función devuelve un entero no nulo en caso de error.
.SH "FUNCIONES INTERNAS utilizadas para escribir analizadores derivados"
.IX Header "FUNCIONES INTERNAS utilizadas para escribir analizadores derivados"
.SS "Obtener entrada, proporcionar salida."
.IX Subsection "Obtener entrada, proporcionar salida."
Se proporcionan cuatro funciones para obtener la entrada y salida de
vuelta. Son muy similares a shift/unshift y push/pop de Perl.
.PP
.Vb 4
\& * Perl shift devuelve el primer elemento de matriz y lo elimina de la matriz.
\& * Perl unshift añade un elemento al matriz como el primer elemento del a matriz.
\& * Perl pop devuelve el último elemento de la matriz y lo elimina de la matriz.
\& * Perl push añade un elemento a la matriz como el último elemento de la matriz.
.Ve
.PP
El primer par trata la entrada, mientras que el segundo trata la
salida. Truco mnemoténico: en la entrada, está interesado en la primera
línea, lo que ofrece shift, y en la salida desea insertar el resultado al
final, como hace push.
.IP "\fBshiftline()\fR" 4
.IX Item "shiftline()"
Esta función devuelve la primera línea para su análisis y la referencia
correspondiente (en forma de matriz), de la matriz \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR, y elimina estos dos primeros elementos de
matriz. Aquí, la referencia es proporcionada por la cadena \f(CW\*(C`$filename:$linenum\*(C'\fR.
.IP "unshiftline($$)" 4
.IX Item "unshiftline($$)"
Devuelve la modificación «shift» de la última línea «shifted» del documento
de entrada y su referencia a la cabecera de \f(CW\*(C`{$self\->{TT}{doc_in}}\*(C'\fR.
.IP "pushline($)" 4
.IX Item "pushline($)"
Inserta una línea nueva al final de \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR.
.IP "\fBpopline()\fR" 4
.IX Item "popline()"
Extrae la últma línea insertada al final de \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR.
.SS "Marcar cadenas como traducibles"
.IX Subsection "Marcar cadenas como traducibles"
Se proporciona una función para tratar el texto que se debe traducir.
.IP "translate($$$)" 4
.IX Item "translate($$$)"
Argumentos obligatorios:
.RS 4
.IP "\-" 2
Una cadena a traducir
.IP "\-" 2
La referencia a esa cadena (por ejemplo, la posición en el fichero de
entrada).
.IP "\-" 2
El tipo de esta cadena (p. ej., la descripción textual de la estructura;
utilizada en \fBLocale::Po4a::Po::gettextization()\fR; consulte también la sección
\&\fIGettextización: ¿cómo funciona?\fR en \fBpo4a\fR\|(7)).
.RE
.RS 4
.Sp
Esta función también puede tomar algunos argumentos adicionales. Estos deben
estar en una tabla de elementos asociativos («hash»). Por ejemplo:
.Sp
.Vb 2
\& $self\->translate("string","ref","type",
\& \*(Aqwrap\*(Aq => 1);
.Ve
.IP "\fBwrap\fR" 4
.IX Item "wrap"
Booleano que indica si podemos considerar que los espacios en blanco de la
cadena carecen de importancia. En ese caso, la función canoniza la cadena
antes de buscar su traducción o extraerla, y justifica la traducción.
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
La columna en la que se debe hacer el salto de línea (por omisión: 76).
.IP "\fBcomment\fR" 4
.IX Item "comment"
Un comentario adicional para añadir a la entrada.
.RE
.RS 4
.Sp
Acciones:
.IP "\-" 2
Inserta la cadena, referencia y escribe en «po_out».
.IP "\-" 2
Devuelve la traducción de la cadena (como aparece en «po_in») de forma que
el analizador pueda construir el fichero «doc_out».
.IP "\-" 2
Trata los juegos de caracteres para recodificar las cadenas antes de
enviarlas a «po_out» y antes de devolver las traducciones.
.RE
.RS 4
.RE
.SS "Funciones varias"
.IX Subsection "Funciones varias"
.IP "\fBverbose()\fR" 4
.IX Item "verbose()"
Devuelve si se pasó la opción de verbosidad durante la creación del
TransTractor.
.IP "\fBdebug()\fR" 4
.IX Item "debug()"
Devuelve si se pasó la opción de depuración de fallos durante la creación
del TransTractor.
.IP "detected_charset($)" 4
.IX Item "detected_charset($)"
Esto informa al TransTractor que se ha detectado un nuevo juego de
caracteres (el primer argumento) en el documento de entrada. Habitualmente
se puede encontrar en la cabecera del documento. Solo permanecerá el primer
juego de caracteres, ya venga de los argumentos de «\fBprocess()\fR» o si se
detectó en el documento.
.IP "\fBget_out_charset()\fR" 4
.IX Item "get_out_charset()"
Esta función devuelve el juego de caracteres que se debe usar en el
documento de salida (normalmente es útil para sustituir el juego de
caracteres detectado en el documento de entrada donde se encontró).
.Sp
Utilizará el juego de caracteres especificado en la linea de órdenes. Si no
se ha especificado, utilizará el juego de caracteres del \s-1PO\s0 de entrada, y si
el \s-1PO\s0 de entrada aún tiene el «CHARSET» predefinido, devolverá el juego de
caracteres del documento de entrada, para que no se realice ninguna
codificación.
.IP "recode_skipped_text($)" 4
.IX Item "recode_skipped_text($)"
Esta función devuelve el texto recodificado introducido como argumento,
desde el juego de caracteres del documento de entrada al del documento de
salida. No es necesario cuando se traduzca una cadena (\fBtranslate()\fR ya lo
recodifica por su cuenta), pero sí lo es cuando se salta alguna cadena del
documento de entrada y quiere mantener la consistencia del documento de
salida con la codificación global.
.SH "DIRECCIONES FUTURAS"
.IX Header "DIRECCIONES FUTURAS"
Una deficiencia del TransTractor actual es que no puede tratar documentos
traducidos que contengan todos los idiomas, como las plantillas de debconf,
o en los ficheros «.desktop».
.PP
Para tratar este problema, los únicos cambios necesarios en la interfaz son:
.IP "\-" 2
tomar una tabla «hash» como «po_in_name» (una lista por idioma)
.IP "\-" 2
añadir un argumento a «translate» para indicar el idioma de destino
.IP "\-" 2
hacer una función «pushline_all», que haría un «pushline» de su contenido
para todos los idiomas, usando una sintaxis parecida a «map»:
.Sp
.Vb 3
\& $self\->pushline_all({ "Description[".$langcode."]=".
\& $self\->translate($line,$ref,$langcode)
\& });
.Ve
.PP
Ya veremos si es suficiente ;)
.SH "AUTORES"
.IX Header "AUTORES"
.Vb 3
\& Denis Barbier