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

Herramientas de po4a                               2020-04-15                            Locale::Po4a::Sgml(3pm)