Creando Documentación Técnica con DocBook

Prefacio

Hola 😀

Desde hace un tiempo (2000 – actualidad) el estándar XML me ha atraído mucho mis primeras implementaciones fueron con VBScritps, ASP, luego JSP y desde que estoy en el movimiento del “Conocimiento Libre” [0] he apreciado que XML se usa en muchas cosas no solo la Web.

Mi primera ves con DocBook fue en una revista española llamada “Linux Free Magazine” en su edición “N°1” [1] donde existe una sección llamada “Docbook-ayuda” con los siguientes temas: Documenta el software libre, Curso de docbook. Luego formalmente desde hace unos años estoy trabajando para unos proyectos de Software Libre en Fundacite Mérida [2] y allí se ha requerido documentar muchos procesos de sistemas para manuales de usuarios, de instalación, FAQ, entre otros. Gracias a esa experiencia obtenida en mi día es que les voy a contar como es DocBook y como se puede usar 😉

Introducción

Según Beltran Monasterios [4], la documentación técnica en el mundo de las computación es muy importante ya documenta procesos tales como:

• Manuales de usuario.

• Libros, Tutoriales.

• Ensayos y artículos técnicos.

• Documentación de un API.

• Preguntas Comunes.

• Diapositivas, Sitios Web, entre otras.

¿Por qué usar DocBook?

Según El proyecto GNOME [5], Para la creación de artículos, libros, tutoriales, entre otros se hace necesario utilizar un medio de documentación estándar de manera que la modificación de los documentos fuentes sea mas sencilla al igual que la generación de estos en diferentes formatos sea un paso trivial.

La documentación estructurada se construye sobre elementos estructurados: capítulos, secciones, párrafos, entre otros. donde los elementos se etiquetan claramente para que son: referencias, salida de programas, entre otros. No se da ninguna información explícita sobre como el documento debe ser escrito, solamente sobre su estructura y contenido.

Esto permite el proceso automático de los documentos, animando a los autores a que se concentren en el contenido de los documentos y no en el como generarlos. Además ofrece facilidad de mantenimiento, de reaprovechamiento de recursos y generación off-line.

¿Qué es DocBook?

Según Wikipedia [6],[7], DocBook es un aplicación del estándar SGML/XML e incluye una DTD propia y que se utiliza de manera más destacada en el área de la documentación técnica, especialmente para documentar todo tipo de material y programas informáticos. Existe un Comité Técnico de DocBook en OASIS (originalmente SGML Open) que mantiene y actualiza este estándar. Además tiene casi 15 años, inicialmente comenzó como una DTD de SGML (SGML/DSSSL/DTD), pero a partir de la versión 4 existe un equivalente para XML (XML/XSL).

Algunos ejemplos

A continuación un ejemplo simple de la estructura del documento basado en DocBook XML para un articulo:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN""http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article lang="es">
<title>Creando Documentación Técnica con DocBook</title>
<articleinfo>
<author>
<firstname>Leonardo</firstname>
<surname>Caballero</surname>
</author>
</articleinfo>
<section id="art-intro">
<title>Introducción</title>
<para>
DocBook es un aplicación del estándar SGML/XML e
incluye una DTD propia y que se utiliza de manera
más destacada en el área de la documentación técnica,
especialmente para documentar todo tipo de material
y programas informáticos, para mayor información consultar aquí <ulink
url="http://www.oasis-open.org/docbook/"/>.
</para>
</section>
</article>

Otro ejemplo simple de la estructura del documento basado en DocBook XML para un libro:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN""http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<book lang="es" id="simple_libro">
<title>Un libro muy simple</title>
<chapter id="capitulo_1">
<title>Capitulo 1</title>
<para>Hola mundo!</para>
<para>¡Yo espero que tu día esta bien!</para>
</chapter>
<chapter id="capitulo _2">
<title>Capitulo 2</title>
<para>Hola otra ves, mundo!</para>
</chapter>
</book>

¿Cómo funciona DocBook?

En la siguiente gráfica se ilustra el flujo de procesos por la que un autor de documentación genere desde DocBook SGML, formatos como HTML, RTF, PDF, PS y otros más. Dicha ilustración fue realizada por Ismael Olea para su conferencia “SGML/XML para autores de documentación”.

Figura 1. Entorno Docbook SGML en Linux

En la siguiente gráfica se ilustra el flujo de procesos por la que un autor de documentación genere desde DocBook XML, formatos como HTML, PDF, PS y otros más. Dicha ilustración fue realizada por Hardy Beltran Monasterios para su conferencia “Creando Documentación Técnica con DocBook”.

Figura 2. Entorno Docbook XML

¿Quienes usan DocBook?

Existen muchos usuarios de DocBook alrededor del mundo; a continuación cito algunos proyectos internacionales: Consultores y autores de documentación libre, Empresas del sector IT tales como: IBM, Sun; También muchas distribuciones de GNU/Linux, como: Debian, Red Hat, Fedora, Suse, Gentoo, FreeBSD, LFS, entre otros; proyectos de documentación de Software Libre/Abierto tales como: GNOME, KDE, PHP, Linux Documentation Proyect, PHP, O’Reilly, entre otros. y en Venezuela conozco de buena fuente el caso de Fundacite Mérida [2] con proyectos como SAID [3].

Este caso fue la primera vez que se uso este sistema de documentación en Fundacite Mérida para el diseño de los manuales de usuario y instalación de cada modulo del SAID usando DocBook con SGML/DSSSL/DTD se generaron los manuales en diferentes formatos como PDF, HTML, PS, entre otros. También han logrado programar tareas con “Makefile” para agilizar la labor de generación de los mismos.

Ventajas

Existen varias ventajas que a continuación describiré:

• Se puede generar varios formatos desde una sola fuente.
• Los documentos estructurados abren la posibilidad de crear sistemas avanzados de búsqueda de información.
• La presentación separada del contenido (y del procedimiento), no esta ligado a una implementación concreta (CMS).
• Se puede generar offline de las páginas (incluso en otro ordenador).
• Permite todo tipo de transformaciones del contenido por Ejemplo: ofuscar direcciones de correo electrónico, entre otras.

Desventajas

Existen varias desventajas que a continuación describiré:

• Demasiadas marcas XML/SGML.
• Inicialmente su aprendizaje es lento para quienes nunca usaron «lenguajes de marcas».
• Algunas herramientas libres no son suficiente maduras para ciertos usos (Ej. Editor XML, Convertir XML FO a PDF).
• Varias herramientas maduras son solo para Windows y no son libres.

Requerimientos Básicos

Para la edición y generación desde DocBook SGML necesita como mínimo instalado los requerimientos:

• Un editor de texto o editor SGML/XML.
• DocBook instalado en su sistema.
  • El DTD de DocBook SGML.
  • Hojas de estilo DSSSL DocBook.
• Un procesador DSSSL.
  • Por ejemplo OpenJade.
• Un procesador de formato imprimible (si quiere PDF).
  • Por ejemplo JadeTeX.

Para la edición y generación desde DocBook XML necesita como mínimo instalado los requerimientos:

• Un editor de texto o editor XML.
• DocBook instalado en su sistema.
  • El DTD de DocBook XML.
  • Hojas de estilo XSLT DocBook.
• Un procesador XSLT.
  • Por ejemplo xsltproc.
• Un procesador FO (si quiere PDF).
  • Por ejemplo Apache FOP.

¿Más documentación o soporte?

Existen documentación oficial, el manual de referencia se llama “DocBook: The Definitive Guide” [8]. Además existen manuales en español en la siguiente dirección electrónica [9]. Un buen sitio para hacer preguntas “Lista de correo en español para ayuda y asistencia al uso de la DTD de composición de documentos técnicos DocBook” [11] dispuesta a colaborar entre si con un espíritu altruista incluso aclarando dudas técnicas.

Conclusiones

DocBook llama la atención por dos cualidades importantes: Se puede generar varios formatos desde una sola fuente y los documentos estructurados abren la posibilidad de crear sistemas avanzados de búsqueda de información. Cada día las herramientas en GNU/Linux maduran más y su adopción se extiende cada día más.
Esto es una introducción general de DocBook, les invito a que conozcan más y pongan en practicas estos “tips”, usen los manuales de referencia [8] y los tutoriales en español [9].

Y en la próxima …

En la próxima entrega explicaré sobre “Editores de DocBook”, y así lograr una productividad en el procedo de documentación con DocBook.

Referencias

[0] http://es.wikipedia.org/wiki/Conocimiento_Libre
[1] http://www.kernelproduktion.com/newfile29.htm
[2] http://www.fundacite-merida.gob.ve/
[3] http://said.fundacite-merida.gob.ve/
[4] http://www.hardy.com.bo/files/seminarios/docBook-tutorial-congreso.pdf
[5] http://libros.es.gnome.org/librognome/librognome/librognome/c9682.html
[6] http://es.wikipedia.org/wiki/DocBook
[7] http://en.wikipedia.org/wiki/DocBook
[8] http://www.docbook.org/tdg/index.html
[9] http://wiki.docbook.org/topic/DocBookTutorials
[10] https://listas.hispalinux.es/mailman/listinfo/docbook-ayuda