Provided by: po4a_0.41-1ubuntu1_all bug

NOMBRE

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

DESCRIPCI'ON

       El objetivo del proyecto po4a (<<PO for anything>>, PO para todo) es
       facilitar la traduccion (y mas interesante, el mantenimiento de las
       traducciones) usando las herramientas de gettext en areas donde no eran
       de esperar, como la documentacion.

       Locale::Po4a::Sgml es un modulo que asiste en la traduccion de
       documentacion en formato SGML a otros lenguajes (humanos).

       Este modulo usa nsgmls para analizar los ficheros SGML. Asegurese de
       que esta instalado. Asegurese tambien de que el DTD de los ficheros
       SGML estan instalados en el sistema.

OPCIONES ACEPTADAS POR ESTE MODULO

       debug
           Es una lista de palabras clave separadas por espacios que indican
           que partes se quieren depurar. Los valores posibles son: <<tag>>,
           <<generic>>, <<entities>> y <<refs>>.

       verbose
           Muestra mas informacion sobre que esta 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 categoria translate.

       indent
           Lista de todas las etiquetas que aumentan el nivel de sangrado,
           separadas por espacios.

       verbatim
           La organizacion del contenido de estas etiquetas no se debe
           cambiar. El parrafo no se justificara ni se anadiran espacios de
           sangrado ni saltos de linea por motivos esteticos.

       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 categoria ya
           que anadirlo en la seccion <<translate>> crearia unos msgid que no
           serian 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 anadirle como prefijo una jerarquia de
           etiquetas para especificar que esta etiqueta solo se debe traducir
           cuando este dentro de la etiqueta especificada. Por ejemplo:
           <bbb><aaa>lang indica que el atributo <<lang>> solo se traducira
           cuando este dentro de la etiqueta <aaa>, y este este dentro de una
           etiqueta <bbb>. Los nombres de las etiquetas son, generalmente,
           expresiones regulares que le permiten escribir cosas tales como
           <aaa|bbbb>lang solo para traducir atributos de <<lang>> que estan
           dentro de una etiqueta <aaa> o <bbb>.

       qualify
           Lista de elementos separados por espacios de los atributos, para
           los que la traduccion se debe calificar por el nombre de atributo.
           Observe que definir esto automaticamente tambien anade 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 omision, los msgid que contienen solamente una entidad (por
           ejemplo '&version;') se obvian, para comodidad de los traductores.
           Evitara esta optimizacion si activa esta opcion. Puede ser util si
           el documento contiene una construccion como
           <<<title>&Aacute;</title>>>, aunque dudo que nunca pase algo asi...

       ignore-inclusion
           Lista de entidades separadas por espacios que no se trataran como
           elementos en linea. Use esta opcion con cuidado: puede causar que
           nsgmls (usado internamente) anada 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
       identicos. A pesar de todo aun hay algunos problemas:

       o La salida de error de nsgmls se redirige a <</dev/null>>, lo cual es
         definitivamente malo. No se como evitarlo.

         El problema es que debo <<proteger>> la inclusion condicional (p.
         ej., las cosas como "<! [ %blah [" y "]]>") de nsgmls, porque si no,
         nsgmls se lo come, y no se 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 anado son
         validos 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 esta mal formateado.

       o Esto solo funciona con DebianDoc y  DocBook DTD. Anadir
         compatibilidad para un nuevo DTD deberia ser muy facil. El mecanismo
         es comun para todos los DTD, solo tiene que dar una lista de las
         etiquetas existentes y algunas de sus caracteristicas.

         Estoy de acuerdo, esto necesita un poco mas de documentacion, pero
         aun se considera beta, y odio documentar cosas que probablemente
         cambiaran.

       o Advertencia: la compatibilidad con DTD es aun experimental. No lei
         ningun manual de referencia para mirar la definicion de cada
         etiqueta. Fui anadiendo definiciones de etiquetas al modulo hasta que
         funcionaba para varios documentos que encontre en la red. Si su
         documento utiliza mas etiquetas que el mio, no funcionara. Pero tal y
         como he dicho, arreglar esto debe ser muy facil.

         Solo probe DocBook con SAG (System Administrator Guide, Guia del
         administrador de sistemas), pero este documento es muy grande, y debe
         usar la mayoria de las caracteristicas especificas de DocBook.

         Para DebianDoc, he probado algunos de los manuales de DDP, pero no
         todos aun.

       o En el caso de inclusion de ficheros, la cadena de referencia del
         mensaje del fichero PO (p.e., lineas como "#: en/titletoc.sgml:9460")
         seran incorrectas.

         Esto es debido a que proceso el fichero para proteger la inclusion
         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 este antes de pasarlo
         por nsgmls para su analisis.

         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 tambien). Pero por ahora no
         se hace nada para corregir las referencias despues (p. ej., nombre de
         fichero y numero de linea). No estoy seguro de cual es la mejor
         solucion.

AUTORES

       Este modulo es una version adaptada de sgmlspl (postprocesador SGML
       para los analizadores SGMLS y NSGMLS) que hizo:

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

       La adaptacion a po4a la realizo:

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