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”.

Entorno Docbook SGML en Linux

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”.

Entorno Docbook XML

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

10 thoughts on “Creando Documentación Técnica con DocBook

  1. Pingback: El Blog de Jose » Blog Archive » DocBook en cápsulas: herramientas básicas

  2. Me alegra que el trabajo que realizo puede ser aprovechado o usado de referencia por otros, gracias por la cita, casi tengo listo mi próximo post sobre “Editores de Docbook”, pero como tu dices “Podríamos pasar horas citando editores de texto, pero no tiene sentido” y es verdad solo tratare el tema desde un enfoque de las funcionalidades, tipos de editores existentes y luego estaré en próximas entregas explicando cada uno de los editores más recomendables.

    Bueno estamos en contacto😉

    P.D.: Como le dije a Ailé me alegra no ser el único usuario “conocido públicamente” que esta usando esta tecnología en Venezuela.

  3. Que tal Leonardo, estoy usando DocBook y me va bien, sin embargo, tengo una duda, ¿Será que existe alguna manera de justificar la alineación del texto de un párrafo? Cualquier cosa gracias…

    Saludos…

  4. Hola Félix

    Yo trabajo con Docbook SGML y los estilos con “The Linux Documentation Project’s DSSSL” el paquete se llama en Debian “ldp-docbook-dsssl” y en la hoja de estilo se define o descomenta el siguiente parámetro

    (define %default-quadding%
    ;; Full justification.
    ‘justify)

    Claro esto solo me ha funcionado para los formatos PDF, para HTML no lo he puesto a funcionar así que si lo haces me avisas como te fue por favor😉

    Éxitos

    P.D.: La lista de Ayuda de Docbook es muy buena quizás te respondan a tu pregunta de forma más efectiva que yo

    https://listas.hispalinux.es/mailman/listinfo/docbook-ayuda

  5. Gracias por tu información, voy a probar lo que me recomiendas, en cuanto a HTML, pues hice solamente un CSS para eso y funciona bien pues lo probé.

    Voy a visitar la lista de ayuda de DocBook que recomiendas.

    Saludos gracias…

  6. Leonardo, conseguí una manera para que justifique los párrafos para HTML automáticamente, inicialmente cuando habilité el parámetro %default-quadding% en mi archivo docbook-utils.dsl, me generaba un mensaje de openjade al momento de transportar los archivos a HTML, para PDF, no me decía nada, entonces edité el archivo dbhtml.dsl que está en la ruta /usr/share/sgml/docbook/stylesheet/dsssl/modular/, dentro de dicho archivo donde se declaran los atributos para párrafos en HTML, hice un cambio por defecto (list (list “ALIGN” %default-quadding%)) y cambié %default-quadding% por “JUSTIFY” con todo y comillas, quedando (list (list “ALIGN” “JUSTIFY”)).

    Saludos…

  7. Otra cosa, aún no hallo entrar a la lista de DocBook, si tienen un canal en irc sería de gran utilidad, esta solución la hice leyendo los mensajes de errores y leyendo todos los archivos ahí dentro, por otro lado publiqué un poco la solución en mi blog.

    Saludos…

  8. Hola!

    Encontré bastante información sobre DocBook/XML, también sobre herramientas de traducción con memoria, pero aún no logro encontrar herramientas para traducir colaborativamente (es decir, una aplicación web individual o extensión de un CMS) un documento. Lo más parecido que encontré es BEYTrans pero su homepage está caída. ¿Algo que decir al respecto….?

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