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 á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.

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 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>&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 onsgmls (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» 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.

AUTORES

       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)

TRADUCCION

        Jordi Vilalta <jvprat@gmail.com>
        Omar Campagne <ocampagne@gmail.com>

DERECHO DE COPIA Y LICENCIA

        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).