DocBook (II): XInclude

8 12 2008

DocBook me está gustando porque simplifica la tarea de la generación y mantenimiento de la documentación. En esta entrada voy a comentar cómo utilizar XInclude para insertar ficheros externos en la documentación, ahorrando la tarea de editarlos, escapar caráctares e insertar. Porque si eso lo vamos a hacer con todos los fragmentos de código, ficheros XML, etc y es programable, pues que lo haga el ordenador.

Concretamente se ilustra el caso con la inserción de un fichero XML, que de otra forma deberíamos editar para escapar los carácteres XML. Con XInclude e indicando text en el atributo parse, tendremos lo mismo pero sin hacer ese trabajo.

Tenemos en un nuestro directorio de trabajo dos ficheros XML: el primero (articulo.xml) es la fuente DocBook, mientras que el segundo (pom.xml) contiene el fichero XML que deseamos insertar en docbook.

<?xml version=”1.0″ encoding=”utf-8″?>
<article xmlns=”http://docbook.org/ns/docbook&#8221;
xmlns:xi=”http://www.w3.org/2001/XInclude&#8221;
xml:lang=”es”>

<section xml:id=”pom”>
<title>Fichero POM</title>

<para>Aquí va el fichero pom.xml</para>

<programlisting><xi:include href=”pom.xml” parse=”text” /></programlisting>
</section>

</article>

Finalmente basta añadir la opción –xinclude en la llamada a xsltproc:

xsltproc --xinclude --o articulo.xhtml /sw/share/xml/xsl/docbook-xsl/xhtml/docbook.xsl articulo.xml

Si lo que se desea es insertar un fragmento de XML se puede realizar con el xinclude, por ejemplo si se quiere añadir el noveno elemento del elemento raíz mostrando un mensaje de error en caso de fallo, de esta forma se procesa el documento.

<programlisting>
<xi:include href=”pom.xml” xpointer=”element(/1/9)”>
<xi:fallback>no cargado pom.xml</xi:fallback>
</xi:include>
</programlisting>

Anuncios




DocBook en OS X Leopard

15 10 2008

Aunque soy un usuario convencido de LaTeX2e, quería probar DocBook por varias razones:

  • Curiosidad técnica
  • XML como mejor formato para gestionar documentos

Como además soy usuario de un MacBook y he encontrado poca información actualizada al respecto me he decidido a añadir una nueva entrada a mi blog.

Primero instalé fink (y su version GUI finkcommander) para realizar la instalación de DocBook mediante este gestor de paquetes. Los paquetes a instalar son:

  • docbook-bundle
  • docbook-xsl

A continuación creo las siguientes variables de entorno (i.e. /etc/profile)


# DocBook
JADE_HOME=/usr/local/openjade-1.3
SGML_SHARE=/sw/share/sgml


# DSSSL stylesheets
# Norman Walsh's Modular DocBook Stylesheets
SGML_CATALOG_FILES=$SGML_SHARE/dsssl/docbook/catalog
# OpenJade stylesheets
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$JADE_HOME/dsssl/catalog
# sgmltools-lite's stylesheets
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/stylesheets/sgmltools/sgmltools.cat


# DocBook DTD
# From OASIS-Open.org
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/3.1/catalog
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/4.1/catalog
# These old ones were installed with doctools-1.2 from XFree86.org
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/2.4.1/catalog
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/3.0/catalog

# sgmltools-lite catalogs for LinuxDoc
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/dtd/sgmltools/catalog

# XSL files home directory
XSL=/sw/share/xml/xsl


export JADE_HOME SGML_SHARE SGML_CATALOG_FILES XSL

Realmente creo que las necesarias para DocBook 5 es $XSL, y el resto son para retrocompatibilidad o si se van a procesar ficheros SGML.

También he instalado FOP (para generar salida en pdf), copiando las librerías Java necesarias a /Library/Java/Extensions y estén disponibles para todos los usuarios.

  • avalon-framework-4.2.0.jar
  • batik-all-1.7.jar
  • commons-io-1.3.1.jar
  • commons-logging-1.0.4.jar
  • fop-hyph.jar (no incluida en FOP por asunto de licencias)
  • fop.jar
  • serializer-2.7.0.jar
  • xalan-2.7.0.jar
  • xercesImpl-2.7.1.jar
  • xml-apis-1.3.04.jar
  • xml-apis-ext-1.3.04.jar
  • xmlgraphics-commons-1.3.1.jar

Y para generar un documento en pdf sólo son necesarios dos comandos:
xsltproc --output articulo.fo /sw/share/xml/xsl/docbook-xsl/fo/docbook.xsl articulo.xml
java org.apache.fop.cli.Main -fo articulo.fo -pdf articulo.pdf

Siendo el fichero original articulo.xml:

<xml version="1.0" encoding="utf-8">
<article>
<title>Mi titulo</title>
<section><title>Seccion primera</title>
<para>Parrafada de la primera seccion.
</para>
</section>
</article>

Finalmente recomiendo los siguientes enlaces que han sido de muchísima ayuda:
Working With DocBook XML On Mac OS X
Con respecto a este enlace he realizado una serie de modificaciones: el modo nXML lo instalo para todos los usuarios (/usr/local/share/emac/site-lisp), en el fichero .emacs indico la ruta absoluta a rng-auto.el para que sea cargado.
DocBook XSL: The Complete Guide
DocBook Install mini-HOWTO