Primeros pasos con DocBook


Para realizar presentaciones o documentos de texto, en lugar de utilizar aplicaciones ofimáticas, llevo muchos años utilizando LaTeX. LaTeX es muy potente y el resultado final es impresionante, es el formato estándar para publicar documentación científica y era el formato utilizado para crear de forma colaborativa documentación en proyectos de software libre, sin embargo hace años surgió el formato Docbook, que ha sustituido a LaTeX en determinados ámbitos, en particular en este último. No tengo todavía una opinión formada sobre las ventajas de uno sobre otro, creo que voy a empezar a utilizar DocBook para determinadas cosas e iré aprendiendo de la experiencia.

En esta entrada se explica una manera de empezar a trabajar con DocBook (versión 5), utilizando Emacs como editor y Debian GNU/Linux (squeeze) como sistema operativo.

Instalación

Instalamos los siguientes paquetes:

# aptitude install xsltproc fop docbook-xsl-ns docbook5-xml

Que incluye los esquemas de Docbook 5 en DTD, xsd, rng y rnc, las hojas de estilo y aplicaciones para realizar transformaciones a HTML o PDF.

Configuración del entorno de trabajo – Emacs

Ya que Docbook es un dialecto XML del que disponemos de los esquemas, lo más lógico es utilizar algún editor de textos que soporte la inclusión de esquemas, de manera que el documento se autovalide al vuelo. Yo voy a utilizar Emacs con nxml-mode (véase Emacs como editor XML de este mismo blog), los pasos a seguir son los siguientes:

Añadimos la siguiente línea a nuestro fichero de configuración de Emacs (~/.emacs por ejemplo):

(eval-after-load 'rng-loc '(add-to-list 'rng-schema-locating-files "~/.schemas/schemas.xml"))

Para que se busquen los esquemas de los diferentes dialectos en el directorio ~/.schemas, de acuerdo a lo especificado en el fichero schemas.xml, por lo que el siguiente paso es crear el directorio ~/.schemas y ubicar allí el fichero schemas.xml con el siguiente contenido:

<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
  <namespace ns="http://docbook.org/ns/docbook" uri="/usr/share/xml/docbook/schema/rng/5.0/docbookxi.rnc"/>
</locatingRules>

Documento base

Vamos a utilizar el siguiente documento como base para crear un documento extenso (book):

<?xml version="1.0" encoding="utf-8"?>
<book xmlns="http://docbook.org/ns/docbook"
      xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:lang="es">
</book>

Emacs reconocerá el espacio de nombres y automáticamente validará el formato y nos ayudará con el autocompletado, con ello podemos crear nuestro primer documento sin tener mucha idea de DocBook, aunque como es lógico es necesario tener a mano un buen manual, como por ejemplo DocBook 5: The Definitive Guide, publicado por O’Reilly pero disponible a su vez vía web.

Con todo ello podríamos crear nuestro primer documento:

<?xml version="1.0" encoding="utf-8"?>
<book xmlns="http://docbook.org/ns/docbook"
      xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:lang="es">
<info>
  <title>Primeros pasos con DocBook</title>
  <author>
    <personname>
      <firstname>Alberto</firstname>
      <surname>Molina Coballes</surname>
    </personname>
  </author>
</info>
<chapter xml:id="intro">
  <title>Introducción</title>
  <para>Para realizar presentaciones o documentos de texto, en lugar de utilizar aplicaciones ofimáticas, llevo muchos años utilizando LaTeX. LaTeX es muy potente y el resultado final es impresionante, es el formato estándar para publicar documentación científica y era el formato utilizado para crear de forma colaborativa documentación en proyectos de software libre, sin embargo hace años surgió el formato Docbook, que ha sustituido a LaTeX en determinados ámbitos, en particular en este último. No tengo todavía una opinión formada sobre las ventajas de uno sobre otro, creo que voy a empezar a utilizar DocBook para determinadas cosas e iré aprendiendo de la experiencia.</para>
  <para>En esta entrada se explica una manera de empezar a trabajar con DocBook (versión 5), utilizando Emacs como editor y Debian GNU/Linux (squeeze) como sistema operativo.</para>
  <section>
    <title>Instalación</title>
    <para>Instalamos los siguientes paquetes:</para>
    <screen>
      <prompt># </prompt><userinput>aptitude install xsltproc fop docbook-xsl-ns docbook5-xml</userinput>
    </screen>
    <para>Que incluye los esquemas de Docbook 5 en DTD, xsd, rng y rnc, las hojas de estilo y aplicaciones para realizar transformaciones a HTML o PDF.</para>
  </section>
  <section>
    <title>Configuración del entorno de trabajo – Emacs</title>
    <para>Ya que Docbook es un dialecto XML del que disponemos de los esquemas, lo más lógico es utilizar algún editor de textos que soporte la inclusión de esquemas, de manera que el documento se autovalide al vuelo. Yo voy a utilizar Emacs con nxml-mode (véase Emacs como editor XML de este mismo blog), los pasos a seguir son los siguientes:</para>
    <programlisting language="lisp">
    <![CDATA[
    (eval-after-load 'rng-loc '(add-to-list 'rng-schema-locating-files 
    "~/.schemas/schemas.xml"))
    ]]>
    </programlisting>
    <para>Para que se busquen los esquemas de los diferentes dialectos en el directorio ~/.schemas, de acuerdo a lo especificado en el fichero schemas.xml, por lo que el siguiente paso es crear el directorio ~/.schemas y ubicar allí el fichero schemas.xml con el siguiente contenido:</para>
    <programlisting language="xml">
      <![CDATA[
      <locatingRules
        xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
        <namespace ns="http://docbook.org/ns/docbook" 
        uri="/usr/share/xml/docbook/schema/rng/5.0/docbookxi.rnc"/>
      </locatingRules>
      ]]>
    </programlisting>
  </section>
  <section>
    <title>Documento base</title>
    <para>Vamos a utilizar el siguiente documento como base para crear un documento extenso (book):</para>
    <programlisting language="xml">
      <![CDATA[
      <?xml version="1.0" encoding="utf-8"?>
      <book xmlns="http://docbook.org/ns/docbook"
            xmlns:xi="http://www.w3.org/2001/XInclude"
            version="5.0" xml:lang="es">
      </book>
      ]]>
    </programlisting>
    <para>Emacs reconocerá el espacio de nombres y automáticamente validará el formato y nos ayudará con el autocompletado, con ello podemos crear nuestro primer documento sin tener mucha idea de DocBook, aunque como es lógico es necesario tener a mano un buen manual, como por ejemplo DocBook 5: The Definitive Guide, publicado por O’Reilly pero disponible a su vez vía web.</para>
  </section>
</chapter>
</book>

Transformar un documento en Docbook a XHTML y PDF

Partiendo del documento anterior (al que llamaremos docbook.xml) podemos generar una versión en formato XHTML con la siguiente instrucción:

$ xsltproc -o docbook.html /usr/share/xml/docbook/stylesheet/docbook-xsl-ns/xhtml-1_1/docbook.xsl docbook.xml

Que produce el fichero docbook.html, a su vez podemos generar el mismo documento en formato PDF con las siguientes instrucciones:

$ xsltproc -o docbook.fo /usr/share/xml/docbook/stylesheet/docbook-xsl-ns/fo/docbook.xsldocbook.xml
$ fop docbook.fo -pdf docbook.pdf

Que produce a su vez el fichero docbook.pdf, con el mismo contenido.

Referencias:

, ,

  1. #1 por joconsultor el 26-06-13 - 10:58 pm

    Hola compi,
    muchas gracias por este genial post. Me sirvió mogollón hace unos meses y, desde entonces, sólo uso DocBook para documentar mis tutoriales y manuales.
    MUCHAS GRACIAS. Y sigue así ;-)

    joan

    Me gusta

    • #2 por albertomolina el 27-06-13 - 6:41 pm

      Gracias Joan,

      Si tienes tiempo, échale un vistazo a apache maven, es un poco complicado al principio pero es mucho más completo que xsltproc. Nosotros lo utilizamos para la documentación de un proyecto utilizando como base las plantillas que había hecho la gente de OpenStack [1]

      En cualquier caso, creo que todavía me siento más cómodo con LaTeX ;)

      [1] https://github.com/pi-fp-cloud/doc/tree/master/admin-openstack

      Me gusta

      • #3 por joconsultor el 27-06-13 - 7:45 pm

        Gracias por la info. La verdad es que no conozco Maven y, cuando leo el artículo de la Wikipedia sobre Maven no entiendo muy bién de qué se trata :-)

        Voy a leer un poco sobre LaTeX, a ver si me ofrece algo que DocBook no hace para mis tutoriales.
        De todas formas gracias y ánimos con este blog ;-)

        joan

        Me gusta

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s

A %d blogueros les gusta esto: