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