<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><title>Presentando documentos DocBook con AxKit</title><link rel="stylesheet" href="BrunoV_html_docbook.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.50.0" /><meta name="keywords" content="axkit, XML, Perl, DocBook, XSLT" /></head><body><div class="article"><div class="titlepage"><div><h1 class="title"><a id="id2669363"></a>Presentando documentos DocBook con AxKit</h1></div><div><div class="authorgroup"><div class="author"><h3 class="author">Carlos Escribano</h3></div></div></div><div><div class="legalnotice"><p class="legalnotice-title"><b>DC.Rights</b></p><p><a href="http://opencontent.org/openpub/" target="_top">OpenPublication</a></p></div></div><div><div class="abstract"><p class="title"><b>Abstract</b></p><p>Como servidor de aplicaciones XML, AxKit ofrece múltiples piezas entre las que podemos elegir las que deseemos para componer el puzzle de nuestra web, también desde contenidos dinámicos.</p><p>En esta ocasión mostraremos cómo utilizar AxKit para ofrecer directamente desde el servidor Apache documentos DocBook estáticos, ya creados, sin realizar ninguna conversión previa.</p><p>Esta es la forma más sencilla (y estándard) de utilizar AxKit, con textos XML modificados tan sólo por hojas de estilo XSLT y CSS.</p></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt>1. <a href="#id2675444">Instalando las hojas de estilo</a></dt><dt>2. <a href="#id2669343">Mostrar un documento DocBook</a></dt><dt>3. <a href="#id2675698">Aplicación de CSS y personalización de la hoja de estilos</a></dt><dt>4. <a href="#id2676023">Mostrar este documento en formato XHTML o PDF</a></dt><dt>5. <a href="#id2676294">Mostrarlo con diferentes hojas de estilo según el cliente</a></dt><dt>6. <a href="#id2676429">Mostrar el código fuente</a></dt></dl></div><div class="section"><div class="titlepage"><div><h2 class="title" style="clear: both"><a id="id2675444"></a>1. Instalando las hojas de estilo</h2></div></div><p>La ventaja de estos formatos emergentes, como éste <a href="http://www.docbook.org/" target="_top">DocBook</a> o el del <a href="http://www.tei-c.org/" target="_top">TEI</a>, que se están convirtiendo en estándares de facto, es que disponemos de hojas de estilo XSLT elaboradas por los autores, que podemos usarlas directamente, e incluso personalizarlas fácilmente.</p><p>Las últimas hojas de estilo de DocBook se encuentran en <a href="http://sourceforge.net/project/showfiles.php?group_id=21935" target="_top">sourceforge</a>, aunque las distribuciones mayoritarias las incluyen entre sus paquetes. En Debian el paquete es <a href="http://packages.debian.org/unstable/text/docbook-xsl.html" target="_top">docbook-xsl</a>, y los estilos se instalan en usr/share/sgml/docbook/stylesheet/xsl/nwalsh/. Si no es el caso del lector, se deberán corregir las rutas de los ficheros que a continuación proponemos.</p><p>Después de instalado, hemos de permitir a Apache acceder a esta ruta. Lo haremos con la directiva Alias, que asignará la dirección real a una dirección del directorio virtual del servidor http. En nuestro directorio de configuración de Apache (en Debian es /etc/apache/httpd.conf) añadimos:</p><pre class="programlisting">Alias /stylesheet /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/</pre><p>Hay en la web hojas de estilo alternativas a la <span class="emphasis"><em>oficial</em></span>, como las de <a href="http://www.openbsd.org.mx/~santana/docbook2html.es.html" target="_top">Gerardo Santana</a>, que utilizaremos también en alguno de estos ejemplos.</p><p>Usaremos también una hoja de estilo CSS para modificar la presentación del texto HTML conseguido. Hay varias disponibles en la web, como la de <a href="http://bruno.vernay.free.fr/docbook.css" target="_top">Bruno Vernay</a>, o la de <a href="http://www.freebsd.org/cgi/cvsweb.cgi/~checkout~/doc/share/misc/docbook.css?rev=1.6&content-type=text/plain" target="_top">FreeBSD</a>.</p></div><div class="section"><div class="titlepage"><div><h2 class="title" style="clear: both"><a id="id2669343"></a>2. Mostrar un documento DocBook</h2></div></div><p>Para este ejemplo necesitamos un documentos válido DocBook. Elejimos uno de los muchos que se encuentran en la web, por ejemplo éste de Pocket-Linux-Guide, <a href="http://cvsview.tldp.org/index.cgi/*checkout*/LDP/guide/docbook/Pocket-Linux-Guide/phase1.xml?rev=HEAD&content-type=text/xml" target="_top">phase1.xml</a>. Lo colocamos en este caso en nuestro directorio real /var/www/Pocket-Linux-Guide/, que es accesible para Apache (en nuestro caso correspondería al directorio virtual /Pocket-Linux-Guide/, puesto que la directiva DocumentRoot apunta a /var/www), y lo renombraremos como phase1.dbk, para preservar la extensión xml con otros propósitos, como veremos más abajo. La mínima configuración de Apache para este contenido estático será:</p><pre class="programlisting"> PerlModule AxKit
<Directory /var/www/Pocket-Linux-Guide >
<Files *.dbk>
AddHandler axkit .dbk
AxAddStyleMap text/xsl Apache::AxKit::Language::LibXSLT
AxAddProcessor text/xsl /stylesheet/xhtml/docbook.xsl
</Files>
</Directory></pre><p>Es una configuración realmente sencilla, como vemos. La directiva de mod_perl PerlModule permite registrar AxKit como módulo de mod_perl; la directiva de mod_mime AddHandler indica a Apache que los documentos .dbk los gestionará AxKit. AxAddStyleMap señala quién es el módulo responsable del procesado para el tipo MIME text/xsl, en este caso Apache::AxKit::Language::LibXSLT. Por fin la directiva AxAddProcessor indica qué hoja de estilos se aplica para los documentos del tipo text/xsl; aquí elejimos la hoja de estilo para xhtml dentro de las originales de DocBook. Hemos de reiniciar Apache y pedirle la URI correspondiente:</p><pre class="programlisting">http://localhost/Pocket-Linux-Guide/phase1.dbk</pre></div><div class="section"><div class="titlepage"><div><h2 class="title" style="clear: both"><a id="id2675698"></a>3. Aplicación de CSS y personalización de la hoja de estilos</h2></div></div><p>En este ejemplo mostraremos cómo utilizar hojas CSS que entregaremos al navegador, o personalizar las hojas de estilo de DocBook.</p><p>Estas modificaciones se efectúan enviando parámetros al procesador XSLT. AxKit le pasará cualquier parámetro que le enviemos vía GET o POST (salvo que explícitamente lo tengamos prohibido en la configuración).</p><p>El único cambio necesario a la configuración anterior es registrar el módulo Apache::AxKit::Plugin::QueryStringCache. Por defecto, AxKit sólo guarda en la cache la URI base, sin parámetros, y necesitamos que nos entregue un texto diferente si cambiamos algún parámetro.</p><p>Para obtener el resultado deseado, tan sólo tenemos que añadir a la URI los parámetros adecuados. El procesado de la hoja de estilos CSS se lleva a cabo en el cliente, y éste lo realiza al encontrar en la cabecera del documento que recibe un campo content-type que lo indica, en este caso text/css. AxKit por defecto nos entregará un tipo MIME text/xml, por lo que debemos modificar esta conducta mediante el parámetro <a href="http://docbook.sourceforge.net/release/xsl/current/doc/html/html.stylesheet.type.html" target="_top">html.stylesheet.type</a>. El archivo que contiene la hoja de estilos a aplicar debe indicarse mediante el parámetero <a href="http://docbook.sourceforge.net/release/xsl/current/doc/html/html.stylesheet.html" target="_top">html.stylesheet</a>.</p><p>Si colocamos la hoja CSS en el mismo directorio que el archivo DocBook, la URI a solicitar será:</p><pre class="programlisting">http://localhost/Pocket-Linux-Guide/phase1.dbk?html.stylesheet=docbook.css&html.stylesheet.type=text/css</pre><p>La gran ventaja de las hojas de estilo XSLT <span class="emphasis"><em>oficiales</em></span> de DocBook es que son altamente personalizables. La <a href="http://docbook.sourceforge.net/release/xsl/current/doc/html/" target="_top">lista</a> de posibles modificaciones es muy grande. En nuestro caso seguiremos utilizando la vía del envío de parámetros vía GET para conseguir cambiar el comportamiento del documento. Por ejemplo, para conseguir que todas las secciones aparezcan numeradas en el texto final añadimos el parámetro <a href="http://docbook.sourceforge.net/release/xsl/current/doc/html/section.autolabel.html" target="_top">section.autolabel=1</a>.</p><p>Vistas desde el exterior, las URIs deberían reflejar sólo la base. El hecho de que un determinado documento deba ser presentado de una cierta manera no debería condicionarlas: Si cambiamos por ejemplo el nombre del estilo, o ahora decidimos que las secciones no estén numeradas, la URI no debe cambiar, o de lo contrario los enlaces que guardaban nuestros usuarios no funcionarán. En un texto DocBook hemos conseguido aislar el contenido de la presentación, y esta forma de alterar el comportamiento del procesador XSLT rompe los beneficios obtenidos.</p><p>Por ello resulta más lógico encargar la gestión de los parámetros al módulo mod_rewrite de Apache, desde archivos .htaccess a colocar en los directorios donde se encuentran los archivos. Con ello nos encontramos con una forma más natural de invocar nuestro documento:</p><pre class="programlisting">http://localhost/Pocket-Linux-Guide/phase1.html</pre><p>El uso de archivos .htaccess nos permite de paso personalizar la hoja de estilos XSLT a aplicar. Podemos por ejemplo indicar una hoja de estilos XSLT en nuestro archivo de configuración de Apache y otras en los directorios correspondientes mediante archivos .htacces. Éstos tienen preferencia sobre las directivas generales, por lo que si en un directorio indicamos un estilo de esta manera, será utilizado, mientras que en los directorios donde no haya indicación expresa se utilizará la hoja de estilos genérica.</p><p>En primer lugar nos aseguramos que tenemos habilitado el módulo mod_rewrite en nuestro archivo de configuración de Apache. En Debian está habilitado por defecto:</p><pre class="programlisting"># cat /etc/apache/httpd.conf | grep rewrite
LoadModule rewrite_module /usr/lib/apache/1.3/mod_rewrite.so</pre><p>Es importante que en la sección que describa el comportamiento de Apache con nuestros archivos tengamos habilitada y abierta la directiva AllowOverride. De lo contrario Apache no leerá los archivos .htaccess. AllowOverride All será la opción más sencilla, aunque se pueden utilizar configuraciones algo más estrictas. Las directivas quedan así:</p><pre class="programlisting"> PerlModule AxKit
AxAddPlugin Apache::AxKit::Plugin::QueryStringCache
<Directory /var/www/Pocket-Linux-Guide >
AllowOverride All
<Files *.dbk>
AddHandler axkit .dbk
AxAddStyleMap text/xsl Apache::AxKit::Language::LibXSLT
AxAddProcessor text/xsl /stylesheet/xhtml/docbook.xsl
</Files>
</Directory></pre><p>Después crearemos un archivo .htaccess en el directorio donde se encuentra nuestro documento (recordemos que en nuestro caso era /var/www/Pocket-Linux-Guide/), con el siguiente contenido:</p><pre class="programlisting">RewriteEngine on
RewriteRule ^(.*)(\.html)$ $1.dbk?html.stylesheet=docbook.css&html.stylesheet.type=text/css&section.autolabel=1
AxAddProcessor text/xsl a_docbook.xsl</pre><p>Hemos colocado dos directivas para mod_rewrite y otra para AxKit.</p><p>Mod_rewrite nos permite cambiar una URI por otra. La directiva RewriteRule va acompañada de dos expresiones regulares, una que describe el patrón buscado y otra el patrón sustituido. En nuestra primera expresión, el patrón</p><pre class="programlisting">^(.*)(\.html)$</pre><p>indica que buscamos cualquier cadena (un . significa cualquier carácter, y el * que le sigue indica que repetido muchas veces) al principio (^) que termine ($) con la subcadena .xml . El paréntesis hace que lo obtenido por el primer patrón, en nuestro caso toda la URI, salvo la extensión, se almacene en el escalar $1, que aprovecharemos en la siguiente expresión regular.</p><p>La segunda expresión regular, la que corresponde a lo que en realidad servirá Apache, simplemente añade a la URI entrante (nuestro escalar $1 que hemos capturado) la extensión y un texto con los parámetros a pasar al procesador XSLT a enviar mediante el método GET. Aquí hemos dicho que envíe al cliente una hoja de estilos llamada docbook.css y que numere las secciones, como hicimos arriba.</p><p>AxKit en este caso recibe otra directiva, AxAddProcessor que hará que entregue una hoja de estilos que no es la estandard, por ejemplo la alternativa que hemos mencionado de Gerardo Santana, que hemos copiado en este mismo directorio.</p></div><div class="section"><div class="titlepage"><div><h2 class="title" style="clear: both"><a id="id2676023"></a>4. Mostrar este documento en formato XHTML o PDF</h2></div></div><p>La implementación de este aspecto descansa sobre <a href="http://www.tei-c.org.uk/Software/passivetex/" target="_top">PassiveTex</a>, por lo que debemos instalarlo. En Debian se deben instalar los paquetes tetex-bin, xmltex y passivetex, y si no es el caso del lector, se deberá acudir a la documentación de la distribución correspondiente para instalar el software necesario.</p><p>Podemos hacer una prueba para comprobar que esta parte de la instalación, ajena a AxKit, es correcta:</p><pre class="programlisting"> xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/fo/docbook.xsl /var/www/Pocket-Linux-Guide/phase1.dbk > phase1.fo
pdfxmltex phase1.fo</pre><p>Esto nos creará el documento phase1.pdf como esperábamos.</p><p>Puesto que la presentación en PDF sí que es vista por el usuario como un documento <span class="emphasis"><em>diferente</em></span>, en este caso sí que prepararemos una URI específica para ella. En concreto cambiaremos la extensión .pdf en la URI, por lo que solicitaremos el documento así:</p><pre class="programlisting">http://localhost/Pocket-Linux-Guide/phase1.pdf</pre><p>El permitir que AxKit entregue un documento en varios formatos alternativos nos obliga a definir unos perfiles para estos formatos, o <span class="emphasis"><em>estilos</em></span>. Aún así, la configuración de AxKit es bastante similar al ejemplo anterior:</p><pre class="programlisting"> PerlModule AxKit
AxAddPlugin Apache::AxKit::Plugin::QueryStringCache
AxAddPlugin Apache::AxKit::StyleChooser::QueryString
<Directory /var/www/Pocket-Linux-Guide >
AllowOverride All
<Files *.dbk>
AddHandler axkit .dbk
AxAddStyleMap text/xsl Apache::AxKit::Language::LibXSLT
AxAddStyleMap text/xslfo Apache::AxKit::Language::PassiveTeX
<AxStyleName "#default">
AxAddProcessor text/xsl /stylesheet/xhtml/docbook.xsl
</AxStyleName>
<AxStyleName "pdf">
AxAddProcessor text/xsl /stylesheet/fo/docbook.xsl
AxAddProcessor text/xslfo NULL
</AxStyleName>
</Files>
</Directory></pre><p>En primer lugar necesitamos un método para hacer llegar a AxKit nuestra preferencia por un estilo determinado. El más natural es mediante el método GET, añadiéndolo a la URI como hemos hecho arriba. Este es el camino que hemos elegido, y por ello registramos un nuevo Plugin,Apache::AxKit::StyleChooser::QueryString. Esto nos permitirá añadir a la URI una expresión style=pdf para pedir un documento con el estilo pdf.</p><p>Mediante la directiva AxAddStyleMapp registramos dos procesadores de estilos, para gestionar respectivamente los tipos MIME text/xsl y text/xslfo.</p><p>Dentro de la sección Files creamos varias secciones dedicadas a <span class="emphasis"><em>estilos</em></span>, denominadas <span class="emphasis"><em>AxStyleName</em></span>. En este ejemplo tan sólo creamos dos, #default y pdf. El <span class="emphasis"><em>nombre</em></span> del estilo coincidirá con el valor que pasaremos a AxKit mediante el parámetro GET <span class="emphasis"><em>style</em></span>, tal y como hemos visto.</p><p>Hemos colocado también un estilo adicional, <span class="emphasis"><em>#default</em></span>, encargado de gestionar cualquier otra petición que no encaje con el resto de estilos predefinidos. El contenido de esta sección mantendrá el mismo comportamiento que en el ejemplo anterior, mostrando la hoja por defecto para XHTML de la distribución XSLT de DocBook.</p><p>Aquí vemos en funcionamiento la tubería de AxKit. El estilo <span class="emphasis"><em>pdf</em></span> ha de tener un tratamiento a través de dos procesadores. El primero sí utilza una hoja XSLT, en este caso la creada para el formato FO en la distribución XSLT de DocBook.</p><p>El segundo procesador vuelve a ser llamado con la directiva <span class="emphasis"><em>AxAddProcessor</em></span>, a la que indicaremos el tipo MIME a tratar, <span class="emphasis"><em>text/xslfo</em></span>, pero sin ninguna hoja a aplicar, por lo que especificamos NULL como último parámetro. Puesto que hemos indicado que el procesador para este tipo MIME es el módulo Apache::AxKit::Language::PassiveTeX, éste gestionará la salida del procesador anterior, y generará el PDF en sí.</p><p>Nuestro archivo .htaccess queda así:</p><pre class="programlisting"> RewriteEngine on
RewriteCond $2 .html$
RewriteRule ^(.*)(\.html)$ $1.dbk?html.stylesheet=BrunoV_html_docbook.css&html.stylesheet.type=text/css&section.autolabel=1 [L]
RewriteCond $2 .pdf$
RewriteRule ^(.*)(\.pdf)$ $1.dbk?style=pdf [L]</pre><p>En esta ocasión introducimos otra directiva de mod_rewrite, RewriteCond, encargada de verificar una condición, y, si se cumple, aplicar la regla RewriteRule que le sigue. La sintaxis de RewriteCond evalúa si coinciden las cadenas expresadas como parámetros. $2 en este caso indica la cadena obtenida al aplicar una parte del patrón de la directiva siguiente RewriteRule, el segundo paréntesis. Como hemos explicado arriba, este segundo patrón indica simplemente si la cadena acaba en .html. La otra cadena a comparar es exactamente la misma, por lo que si coinciden se aplicará la conversión que vimos arriba.</p><p>Lo mismo podemos decir de la segunda regla. Si la URI solicitada acaba en .pdf se aplica la regla, que es muy similar a la primera, difiriendo tan sólo en los parámetros GET enviados.</p><p>Obsérvese el flag L añadido al final de las reglas que indica a mod_rewrite que termine la conversión, y no siga aplicando de nuevo las reglas a las nuevas cadenas obtenidas.</p></div><div class="section"><div class="titlepage"><div><h2 class="title" style="clear: both"><a id="id2676294"></a>5. Mostrarlo con diferentes hojas de estilo según el cliente</h2></div></div><p>En este caso seleccionaremos un <span class="emphasis"><em>estilo</em></span> en función del User Agent, el identificador del cliente. Siempre hay otas maneras de hacerlo, y mod_rewrite también podría controlarlo, pero a título de ejemplo lo haremos desde AxKit, y el lector elegirá la opción más adecuada. En nuestro caso ello cada estilo de Axkit nos permitirá servir una hoja XSLT, la de de HTML para los clientes antiguos y otra XHTML para el resto. Llamaremos al primer estilo <span class="emphasis"><em>antiguos</em></span>.</p><p>Añadiremos un nuevo módulo, Apache::AxKit::StyleChooser::UserAgent, a registrar mediante la directiva AxAddPlugin. Y con la directiva de mod_perl PerlSetVar, que este módulo utiliza para recibir parámeteros, crearemos un arreglo AxUAStyleMap, que indicará a AxKit qué estilo corresponde a cada cliente. La sintaxis a emplear es:</p><pre class="programlisting">AxAddPlugin Apache::AxKit::StyleChooser::UserAgent
PerlSetVar AxUAStyleMap "antiguos => Netscape 2.0,\
antiguos => Netscape 3.0"</pre><p>La configuración queda como sigue:</p><pre class="programlisting"> PerlModule AxKit
AxAddPlugin Apache::AxKit::StyleChooser::UserAgent
AxAddPlugin Apache::AxKit::StyleChooser::QueryString
AxAddPlugin Apache::AxKit::Plugin::QueryStringCache
<Directory /var/www/Pocket-Linux-Guide >
AllowOverride All
<Files *.dbk>
AddHandler axkit .dbk
AxAddStyleMap text/xsl Apache::AxKit::Language::LibXSLT
PerlSetVar AxUAStyleMap "antiguos => Netscape 2.0,\
antiguos => Netscape 3.0"
<AxStyleName "#default">
AxAddProcessor text/xsl /stylesheet/xhtml/docbook.xsl
</AxStyleName>
<AxStyleName "antiguos">
AxAddProcessor text/xsl /stylesheet/html/docbook.xsl
</AxStyleName>
<AxStyleName "pdf">
AxAddProcessor text/xsl /stylesheet/fo/docbook.xsl
AxAddProcessor text/xslfo NULL
</AxStyleName>
</AxMediaType>
</Files>
</Directory></pre><p>Como vemos, los módulos AxAddPlugin Apache::AxKit::StyleChooser::UserAgent y AxAddPlugin Apache::AxKit::StyleChooser::QueryString (aún hay otras alternativas, como AxAddPlugin Apache::AxKit::StyleChooser::PathInfo) nos ofrecen en realidad dos caminos para llegar al mismo estilo. Si el <span class="emphasis"><em>User Agent</em></span> es Netscape 2.0, la URI:</p><pre class="programlisting"> http://localhost/Pocket-Linux-Guide/phase1.html</pre><p>servirá lo procesado por el estilo antiguos, pero desde cualquier navegador, esta URI:</p><pre class="programlisting"> http://localhost/Pocket-Linux-Guide/phase1.dbk?style=antiguos</pre><p>contendrá exactamente lo mismo, lo que nos abriría el camino a tratarlo con mod_rewrite como vimos arriba. De todos modos, puesto que hemos habilitado la elección de estilo en función del navegador desde dentro de AxKit, no haremos ninguna modificación de nuestro archivo .htaccess.</p></div><div class="section"><div class="titlepage"><div><h2 class="title" style="clear: both"><a id="id2676429"></a>6. Mostrar el código fuente</h2></div></div><p>En esta ocasión mostraremos el código fuente como si fuera otra URI, con la extensión .xml. Un nuevo Plugin de AxKit, AxAddPlugin Apache::AxKit::Plugin::Passthru, nos permitirá acceder al código origonal DocBook añadiendo tan sólo otro parámetro GET, passthru=1.</p><p>El procedimiento de conversión de la URL mediante mod_rewrite es similar a los vistos más arriba, pues tan sólo se trata de añadir una nueva condición:</p><pre class="programlisting">RewriteCond $2 .xml$
RewriteRule ^(.*)(\.xml)$ $1.dbk?passthru=1 [L]</pre></div></div></body></html>