Locale::Po4a::Sgml - Convierte documentos SGML desde/a ficheros
PO
El objetivo del proyecto po4a («PO for anything», PO
para todo) es facilitar la traducción (y más interesante, el
mantenimiento de las traducciones) usando las herramientas de gettext en
ámbitos dónde no previstos, como la documentación.
Locale::Po4a::Sgml es un módulo que asiste en la
traducción de documentación en formato SGML a otros lenguajes
(humanos).
Este módulo usa onsgmls(1) para analizar los
ficheros SGML. Asegúrese de que está instalado.
Asegúrese también de que el DTD de los ficheros SGML
están instalados en el sistema.
- debug
- Es una lista de palabras clave separadas por espacios que indican
qué partes se quieren depurar. Los valores posibles son:
«tag», «generic», «entities» y
«refs».
- verbose
- Muestra más información sobre qué está
pasando.
- translate
- Lista de etiquetas («tags») adicionales separados por
espacios (aparte de los proporcionados por DTD) cuyo contenido debe
generar un msgid adicional.
- section
- Lista separada por espacios de las etiquetas adicionales (aparte de los
proporcionados por el DTD) que pueden contener otras etiquetas, algunos de
los cuales pueden ser de la categoría translate.
- indent
- Lista de todas las etiquetas que aumentan el nivel de sangrado, separadas
por espacios.
- verbatim
- La organización del contenido de estas etiquetas no se debe
cambiar. El párrafo no se justificará ni se
añadirán espacios de sangrado ni saltos de línea por
motivos estéticos.
- empty
- Etiquetas que no necesitan cierre.
- ignore
- Las etiquetas ignoradas y consideradas por po4a como datos de caracteres
sencillos. Esto significa que pueden ser parte de un msgid. Por ejemplo,
<b> es un buen candidato para esta categoría ya que
añadirlo en la sección «translate»
crearía unos msgid que no serían la frase completa, lo cual
no es recomendable.
- attributes
- Lista separada por espacios de los atributos que necesita traducir. Puede
especificar los atributos por su nombre (por ejemplo,
«lang»), pero puede añadirle como prefijo una
jerarquía de etiquetas para especificar que esta etiqueta
sólo se debe traducir cuando esté dentro de la etiqueta
especificada. Por ejemplo: <bbb><aaa>lang indica que el
atributo «lang» sólo se traducirá cuando
esté dentro de la etiqueta <aaa>, y éste esté
dentro de una etiqueta <bbb>. Los nombres de las etiquetas son,
generalmente, expresiones regulares que le permiten escribir cosas tales
como <aaa|bbbb>lang sólo para traducir atributos de
«lang» que están dentro de una etiqueta <aaa> o
<bbb>.
- qualify
- Lista de elementos separados por espacios de los atributos, para los que
la traducción se debe calificar por el nombre de atributo. Observe
que definir esto automáticamente también añade el
atributo en la lista de 'attributes'.
- force
- Procede aunque se desconozca el DTD o si onsgmls encuentra errores en el
fichero de entrada.
- include-all
- Por omisión, los msgid que contienen solamente una entidad (por
ejemplo '&version;') se obvian, para comodidad de los traductores.
Evitará esta optimización si activa ésta
opción. Puede ser útil si el documento contiene una
construcción como
«<title>Á</title>», aunque dudo que
nunca pase algo así...
- ignore-inclusion
- Lista de entidades separadas por espacios que no se tratarán como
elementos en línea. Use esta opción con cuidado: puede
causar que onsgmls (usado internamente) añada etiquetas, y por ello
dejar sin valor el documento de salida.
El resultado es perfecto. Es decir, los documentos generados son
idénticos. A pesar de todo aún hay algunos problemas:
- La salida de error de nsgmls se redirige a «/dev/null» de
forma predefinida, lo cual es claramente negativo. No sé como
evitarlo.
El problema es que debo «proteger» la
inclusión condicional (p. ej., las cosas como
"<! [ %blah [" y
"]]>") de onsgmls, porque si no,
onsgmls se lo come, y no sé como restaurarlo en el documento
final. Para evitarlo, lo reescribo como
"{PO4A-beg-blah}" y
"{PO4A-end}".
El problema con esto es que
"{PO4A-end}" y otros que añado
no son válidos en el documento (pero no en una etiqueta <p>
o similar).
Si desea observar la salidad de onsgmls, simplemente
añada lo siguiente a la línea de órdenes (o fichero
de configuración de po4a):
-o debug=onsgmls
- Esto sólo funciona con DebianDoc y DocBook DTD. Añadir
compatibilidad para un nuevo DTD debería ser muy fácil. El
mecanismo es común para todos los DTD, sólo tiene que dar
una lista de las etiquetas existentes y algunas de sus
características.
Estoy de acuerdo, esto necesita un poco más de
documentación, pero aún se considera beta, y odio
documentar cosas que probablemente cambiarán.
- Advertencia: la compatibilidad con DTD es aún experimental. No
leí ningún manual de referencia para mirar la
definición de cada etiqueta. Fui añadiendo definiciones de
etiquetas al módulo hasta que funcionaba para varios documentos que
encontré en la red. Si su documento utiliza más etiquetas
que el mío, no funcionará. Pero tal y como he dicho,
arreglar esto debe ser muy fácil.
Sólo probé DocBook con SAG (System Administrator
Guide, Guia del administrador de sistemas), pero este documento es muy
grande, y debe usar la mayoría de las características
específicas de DocBook.
Para DebianDoc, he probado algunos de los manuales de DDP,
pero no todos aún.
- En el caso de inclusión de ficheros, la cadena de referencia del
mensaje del fichero PO (p.e., líneas como "#:
en/titletoc.sgml:9460") serán incorrectas.
Esto es debido a que proceso el fichero para proteger la
inclusión condicional (p. ej., las cosas como
"<! [ %blah [" y
"]]>") y algunas entidades (como
&version;) de onsgmls porque lo quiero igual en el documento
generado. Por eso hago una copia temporal del fichero de entrada y hago
todos los cambios que quiero en éste antes de pasarlo por onsgmls
para su análisis.
Para que esto funcione, reemplazo las entidades que incluyen
un fichero con el contenido del fichero dado (de forma que puedo
proteger lo que convenga del subfichero también). Pero por ahora
no se hace nada para corregir las referencias después (p. ej.,
nombre de fichero y número de línea). No estoy seguro de
cuál es la mejor solución.
Este módulo es una versión adaptada de sgmlspl
(postprocesador SGML para los analizadores SGMLS y ONSGMLS) que hizo:
Copyright © 1995 David Megginson <dmeggins@aix1.uottawa.ca>
La adaptación a po4a la realizó:
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)
Jordi Vilalta <jvprat@gmail.com>
Omar Campagne <ocampagne@gmail.com>
Copyright © 1995 David Megginson <dmeggins@aix1.uottawa.ca>.
Copyright © 2002-2005 SPI, Inc.
Esto es software libre; puede redistribuirlo y/o modificarlo bajo
las condiciones de la licencia GPL (consulte el fichero COPYING).