Provided by: po4a_0.41-1ubuntu1_all bug

NOMBRE

       Locale::Po4a::Sgml - Convierte documentos SGML desde/a ficheros PO

DESCRIPCIÓN

       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 áreas donde no eran
       de esperar, 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 nsgmls 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.

OPCIONES ACEPTADAS POR ESTE MODULO

       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 nsgmls 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>&Aacute;</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
           nsgmls (usado internamente) añada etiquetas, y por ello dejar sin
           valor el documento de salida.

ESTADO DE ESTE MODULO

       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», lo cual es
         definitivamente malo. No sé como evitarlo.

         El problema es que debo «proteger» la inclusión condicional (p. ej.,
         las cosas como "<! [ %blah [" y "]]>") de nsgmls, porque si no,
         nsgmls 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 son
         válidos en el documento (pero no en una etiqueta <p> o similar).

         Con la salida de nsgmls redirigida de esta manera todo funciona bien,
         pero esto nos impide detectar si el documento está mal formateado.

       · 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 nsgmls 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 nsgmls 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.

AUTORES

       Este módulo es una versión adaptada de sgmlspl (postprocesador SGML
       para los analizadores SGMLS y NSGMLS) que hizo:

        Copyright (c) 1995 by David Megginson <dmeggins@aix1.uottawa.ca>

       La adaptación a po4a la realizó:

        Denis Barbier <barbier@linuxfr.org>
        Martin Quinson (mquinson#debian.org)

DERECHO DE COPIA Y LICENCIA

        Copyright (c) 1995 por David Megginson <dmeggins@aix1.uottawa.ca>
        Copyright 2002, 2003, 2004, 2005 por SPI, inc.

       Esto es software libre; puede redistribuirlo y/o modificarlo bajo las
       condiciones de la licencia GPL (consulte el fichero COPYING).