SISTEMA DE CREACION DE DOCUMENTACION - DOCBOOK

La documentación en el ámbito de software juega un papel importantísimo como complemento indispensable de los programas informáticos.

Un sistema o software pobremente documentado carece de valor aunque haya funcionado bien en alguna ocasión. En el caso de programas pequeños y poco importantes que sólo se utilizan durante un corto periodo de tiempo, unos cuantos comentarios en el código podrían ser suficientes. No obstante, la mayoría de los programas cuya única documentación es el código no tienen aceptación y es imposible mantenerlos. Dedicar un poco de esfuerzo a la documentación, incluso dentro de los límites de un pequeño proyecto, constituye una muy buena práctica.
Aprender a documentar software es una tarea complicada y exige un criterio de ingeniería maduro. Documentar escuetamente es un erigual de perjudicial: si escribe documentaciones extensas, éstas atosigarán al lector y constituirán
una carga a la hora de mantenerlas. Es esencial documentar sólo los asuntos correctos. La documentación no sirve de ayuda para nadie si su extensión desanima a la gente a la hora de leerla.

El problema de documentar software libre

Si la documentación debe evolucionar junto al software, cuando hablamos de software libre nos encontramos ante el problema de que estamos documentando un software potencialmente realizado por muchas personas, que puede ser libremente modificado y mejorado.
Es obvio, entonces, que la documentación del software libre debe poder ser libremente codificada y mejorada para acompañar la evolución del software libre. De hecho, se considera que software libre sin documentación libre no es un software libre, ya que el desarrollo libre del software se puede ver perjudicado por la falta de un acceso libre a su documentación.

Documentación en formato Docbook

DocBook es un dialecto de SGML (como lo es HTML) especialmente orientado a la escritura de documentación técnica. En particular es una aplicación del estándar SGML/XML, que 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. DocBook inicialmente comenzó como una DTD de SGML, pero a partir de la versión 4 existe un equivalente para XML. DocBook es muy utilizado en algunos contextos, entre los que destacan Linux Documentation Project (Proyecto de documentación Linux), las referencias de las API de GNOME y GTK+, así como la documentación del núcleo Linux. Las páginas man del entorno operativo Solaris se generan también a partir de documentos que utilizan las DTD de DocBook.

Norman Walsh y el equipo de desarrollo del DocBook Open Repository mantienen un conjunto de hojas de estilo DSSSL y XSL para generar versiones PDF y HTML de documentos DocBook (así como para desarrollar otros formatos, incluyendo páginas de referencia man y de ayuda en HTML). Walsh es también el principal autor del libro DocBook: The Definitive Guide, la documentación oficial de DocBook. Este libro se puede obtener bajo licencia GFDL o en su versión impresa está editada por O’Reilly & Associates.”

Instalación y consideraciones preliminares

Para poder utilizar DocBook y poder sacar un mejor provecho de la escritura, se recomienda tener instalados las siguientes utilidades:

• DocBook y utilidades: estos paquetes son requeridos para que todo funcione debidamente; generalmente las distribuciones de GNU/Linux ya traen paquetes prontos para instalar.

• emacs: si bien los documentos pueden ser editados con cualquier editor de textos, Emacs es el único editor orientado al contexto (funcionalidad muy útil a la hora de editar DocBook).

Instalación de programas

Para Debian instale los siguientes paquetes:

• sgml-base: Utilidades para mantención de catalogos SGML.
• sgml-data: SGML comn, XML DTDs y entidades.
• docbook: Sistema estandar SGML para la representación de documentos técnicos
• docbook-utils: Convertidor de archivos docbook a otros formatos.
• docbook-xsl: Estilos para el procesamiento de archivos DocBook XML.

Para instalar estos paquetes utilizamos el comando: apt-get install nombre_paquete. Si no encuentra estos nombres de paquetes busque con el comando: apt-get search sgml y apt-get search docbook los que correspondan.

Ejemplo de archivo sgml:
Paso a otros formatos

Para pasar el documento fuente a otros formatos tenemos los siguientes comandos:

• db2dvi: genera un documento en formato dvi.
• db2html: genera un directorio con el nombre del archivo y el su interior archivos html.
• db2pdf: genera un documento en formato pdf.
• db2ps: genera un documento en formato postscript.
• db2rtf: genera un documento en formato rtf.

La instrucción para generar los distintos formatos es:

db2dvi fuente.sgml

db2html fuente.sgml

db2ps fuente.sgml

db2pdf fuente.sgml

db2rtf fuente.sgml


Si mientras el proceso de generación no arroja error entonces el nuevo documento ha sido creado correctamente.

Ejemplo en formato HTML:



http://www.calcifer.org/documentos/librognome/docbook-dtd.html