Escribir documentación para aplicaciones GNOME
En todo proyecto la documentación es un elemento muy importante y que lamentablemente no siempre se le da la atención que requiere. Tanto desde el punto de vista de quien recibe la documentación como de quien la genera, es vital contar con herramientas que hagan mucho mas fácil esta labor.
Así existe Yelp para poder leer la documentación. Para generar documentación existe DocBook, que permite a través de un fuente generar documentos en diferentes formatos.
Visor de ayuda Yelp
El navegador de ayuda de GNOME incluye documentación detallada de la mayoría de las aplicaciones, utilidades u otros componentes como el panel o el administrador de archivos Nautilus.
Yelp puede mostrar algunos archivos HTML y XML al ser pasados como parámetro en la línea de comandos. Este programa acepta todos las opciones estándares de GNOME y GTK+ que siga la sintáxis habitual de la línea de comandos GNU. Para obtener mas información sobre estas opciones utilize Yelp con el argumento --help.
DockBook
Con docbook se pueden generar documentos en diferentes formatos: html, latex, txt, pdf, postscript. Permite la creación de documentos tales como libros, articulos, manuales, etc. Se ha convertido junto a Open eBook en un estandar internacional para el procesamiento de este tipo de documentos.
Programas necesarios
Para Debian lenny/sid instale los siguientes paquetes para el uso de docbook:
- sgml-base: Infraestructura SGML.
- sgml-data: Datos comunes para SGML y XML.
- docbook: Sistema estandar SGML para la representación de documentos ténicos
- docbook-utils: Convertidor de archivos docbook a otros formatos.
- docbook-xsl: Estilos para el procesamiento de archivos docbook XML.
Para utilizar Vim, instale los paquetes:
- vim-common: Datos comunes.
- vim: Editor VI mejorado.
Si quiere activar el soporte para syntax highlighting (resaltar la sintaxis), debe editar el archivo /etc/vim/vimrc y habilitar la línea syntax on.
Donde escribir los documentos
Cualquier editor sirve para escribir nuestro documento, Vim con la opción syntax on activada para el resalte de etiquetas con colores es una buena idea. También puede usar Emacs con el módulo SGML mode, el que permite escribir con mas facilidad estos documentos.
Estructura de un archivo XML
Generación de 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.