General

DocBook en cápsulas: herramientas básicas

Desde hace ya algún tiempo estoy trabajando con Ailé en la documentación de proyectos con DocBook. Hasta hace un tiempo solíamos utilizar LaTeX para todo, incluyendo artículos, manuales, presentaciones y reportes.DocBook parece muy superior en el área de documentación, específicamente para hacer manuales. No dejaría de hacer reportes y presentaciones con LaTeX aun, pero la importancia semántica del diseño original de DocBook es invaluable. Es por ello, por su propia condición de estar orientado al contenido y no a la presentación, que puede resultar un poco fastidioso al principio — pero es increíblemente útil, y lo considero esencial en el toolset de un analista responsable. Además es más fácil para empezar que LaTeX.La idea de esta serie de posts es ofrecer una referencia rápida para trabajar con DocBook en Linux, particularmente en Debian, Ubuntu y distribuciones derivadas. No planeo extenderme con la introducción de DocBook: me remito a enlazar este excelente artículo en el blog de Leonardo Caballero que explica con detalle qué es DocBook y como empezar a utilizarlo.Herramientas básicasPara empezar a trabajar con DocBook de forma productiva se necesita:

  • Un editor de texto. Cualquiera sirve, pero hay tres cosas que particularmente considero deseables en un editor de texto: resaltado de sintaxis, plegado de bloques y bindings con aplicaciones exteas. Un ejemplo de un cliente que maneja esas tres cosas es Kate. Yo utilizo Bluefish, pero GEdit también es una opción. Podríamos pasar horas citando editores de texto, pero no tiene sentido. También podríamos discutir usar CUIs o GUIs, pero no hay tiempo. Queremos documentar, y rápido.
  • El DTD de DocBook. En Debian y Ubuntu, basta con instalar el paquete docbook-xml. Estamos en el año 2007, así que durante todos estos posts hablaré de la representación en XML de DocBook. Existe una representación en SGML de DocBook, y el paquete se llama docbook — pero queremos evitar utilizar tecnologías en declive. Además en varias partes de la Documentación de DocBook hay referencias al antiguo docbook-sgml, para los nostálgicos.
  • Un conjunto de hojas de estilo XSL para procesar el documento XML y vomitarlo en otros formatos de salida. Nuevamente, en las distribuciones serias basta con instalar docbook-xsl. El DTD suele quedar por /usr/share/xml/docbook/schema/dtd.
  • Herramientas para aplicar las hojas de estilo sobre el documento DocBook en XML. Yo utilizo xsltproc, fop y xmlto. Todas tienen paquetes homónimos en Debian y Ubuntu. Estas aplicaciones ayudan a convertir el documento XML a los formatos realmente útiles, y son el caballo de batalla para trabajar en DocBook.

Probando las herramientasVamos a crear un documento DocBook para probar nuestro dominio sobre las herramientas. Podemos utilizar el ejemplo del blog de Leonardo, o hacemos un nuevo documento, llamado 1.xml. Este documento representa un libro sencillo, que define título, autor y un capítulo con su título y un párrafo de contenido. Todo está codificado en castellano y en UTF-8 — el toolset indicado en las versiones actuales de Debian y Ubuntu masajea toda la data haciéndole caso a la codificación.En los próximos posts revisaremos las partes esenciales de esta porción de código XML. Por ahora, solo lo utilizaremos para introducir las herramientas básicas.

<?xml version="1.0" encoding="UTF-8" ?><!DOCTYPE book PUBLIC "-//OASIS//DTD Docbook XML V4.5//EN"  "/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd"><book lang="es"><bookinfo>            <title>Mi primer manual de DocBook</title>            <author>                        <firstname>Tío Rico</firstname>                        <suame>McPato</suame>            </author></bookinfo><chapter>            <title>Prefacio</title>            <para>                        Bienvenido a mi primer manual de DocBook.            </para></chapter></book>

La forma más sencilla de obtener una representación útil de este documento es usar xmlto para aplicar una hoja XSL que transforme el documento en XHTML 1.0:

xmlto xhtml 1.xml

Este comando generará archivos .html por cada sección del documento, la tabla de contenidos y todos los enlaces de forma adecuada. Si quisiéramos tener todo en un solo archivo XHTML, podríamos usar xmlto xhtml-nochunks 1.xml, pero cuando trabajamos con documentación estructurada que puede crecer muy rápido no queremos tener todo en un XHTML para que la gente no scrollee por siempre.Suponiendo que queremos ver la salida del documento en PDF, podemos usar xmlto para transformar el documento al formato FO y luego podemos usar FOP de Apache para pasar a PDF.

xmlto fo 1.xmlfop -fo 1.fo -pdf 1.pdf

FO es un dialecto de XML que trabaja en la capa de presentación. Una descripción más amplia de FO y sus herramientas se puede encontrar en DocBook Demystificacion Howto (Raymond, 2004)Siguientes pasosEn el próximo post revisaremos el ejemplo y empezaremos a trabajar con los elementos estructurales de DocBook, además de un par de cosas más sobre conversión y algunas aplicaciones realmente útiles de documentar con DocBook. Utilizar un estándar para documentar resulta beneficioso no solo para el proyecto que se está documentando, sino para comprender la importancia de trabajar con estándares en formatos abiertos.Algo que nunca podrás hacer con OOXML, BTW.

Standard

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s