"El Velocity Docbook Framework de Apache es una buena alternativa para poder comenzar a desarrollar documentación en Docbook con una curva de aprendizaje más corta."
En este mini tutorial descubriremos como crear documentos en DocBook utilizando el framework Velocity Docbook Framework de Apache. La característica principal de este marco de desarrollo es proveer al los escritores técnicos de todas las herramientas necesarias para la creación de documentación en el formato Docbook, sin la necesidad de estar descargando las aplicaciones, para producir estos documentos, de diferentes fuentes en Internet.
¿Qué es el Velocity Docbook Framework?
¿Qué es el Velocity Docbook Framework?
La definición proporcionada por el projecto Velocity sobre el Docbook Framework es la siguiente: "El Docbook Framework esta pensado para ayudarte a crear documentación de alta calidad disponible para formatos online y de impresión". El proyecto comenzo originalmente como un marco para desarrollar la documentación del proyecto Velocity en formato Docbook, pero terminó convirtiendose en una herramienta genérica que permite a los desarrolladores generar documentación en este formato de manera más facil.
El framework fue desarrollado con los siguientes conceptos en mente:
- Transformar múltiples documentos en diferentes formatos con un estilo uniforme sin tener que crear un gran número de hojas de estilo o imágenes.
- Separar la capa de traducción o de render de la documentación en sí. El framework se instala una vez y se direcciona a el las veces que se necesite.
- Usar el estandar Docbook XML y XSL zip disponibles para descarga.
- Usar los archivos de referencia actuales de Docbook, las librerías y las herramientas
- Usar el framework sin necesidad de estar conectado a Internet
- Independiente de la plataforma y 100% escrito en Java
- Que sea basado en Apache ant y que sea facilmente incluido en grandes desarrollos.
Instalando el ambiente
El ejemplo que describiré a continuación ha sido desarrollado usando el IDE Eclipse. Con Java 7 instalado y Apache ant 1.6 o superior descargar las librerías JAI de SUN según se explica en la documentación del proyecto (en inglés of course) la descarga del framework. Todo montado sobre una máquina laptop con Ubuntu 12.04. En el ejemplo que he creado he actualizado la versión de Docbook de la 4 a la 5. Por lo que en mas adelante explicare que otros componentes se necesitan descargar.
Manos a la obra. Escribiendo documentos docbook con el Docbook Framework.
Tutorial
A continuación una pequeña guía de como crear un documento con este framework:
A continuación una pequeña guía de como crear un documento con este framework:
- Abrimos Eclipse, accedemos al menú File -> New -> Project...
- Seleccionamos un wizard General y un Project
- Colocamos el nombre del proyecto "testdocbook" y damos click en finish.
- El framework nos sugiere una estructura de directorios la cual vamos a crear dentro del proyecto que acabamos de crear. En el menú File -> New -> Folder y creamos la siguiente estructura de directorios. Se debe ser muy cuidadose en crear todos y cada uno de los directorios para evitar futuros errores al momento de compilar el documento.
- Como se puede ver de manera muy intuitiva las carpetas css, images y style nos ayudaran a definir el estilo de nuestro documento en los formatos PDF y HTML de salida. En la carpeta docbook se colocara la carpeta con los diferentes documentos XML que escribimos utilizando las etiquetas Docbook estandar.
- Ahora vamos a crear dos archivos necesarios para el framwork "project.properties" y "build.xml" al nivel del origen del proyecto esto es no hay que crear estos archivos en ninguna carpeta sino en la carpeta raíz del projecto. Se debe tomar encuenta que debemos tener el pluggin o web tools de eclipse para poder escribir estos archivos en xml de manera que el IDE pueda interpretarlos correctamente. Existen muchos tutoriales sobre el tema de manera que no ahondare más, queda como tarea al lector revisar estos aprendizajes si es que no los poseé.
- El código del archivo "build.xml" se muestra acontinuación:
Hay dos propiedades importantes a considerar "docbook.dir" y "docbook.file" en ellas colocaremos el directorio y el o los archivos que deseamos compilar para obtener nuestro PDF o el HTML correspondiente. En el ejemplo el framework buscará por un directorio llamado "manuales" y un archivo "ejemplo.xml".
- El archivo "project.properties" debe de incluir una sola linea:
dbf.basedir=/ruta donde se instaló el /DocBook-Framework-1.0/
la variable dbf.basedir hace referencia al directorio donde se extrajo e instaló el framework.
- Ahora ya es momento de escribir nuestro archivo docbook propiamente dicho: "ejemplo.xml", aquí el código:
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V5.0//EN"
"http://www.docbook.org/xml/5.0/dtd/docbook.dtd">
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="es">
<info>
<title>Ejemplo del Docbook Framework</title>
<author>
<personname><firstname>Luis Ubaldo</firstname><surname>Godínez Flores</surname></personname>
</author>
<copyright><year>2013</year><holder>CINVESTAV</holder></copyright>
<productname>DocumentandoSistemas</productname>
</info>
<preface><title>Introducción</title>
<section><title>Este es un nuevo tutorial</title>
<para>llksajks lkalkskd kalskd ñlalkskd lkaksd lask ñaks djkalkj dksjldkasda
asdasd alorkhajs kakjjheuens jkakjsakjs kkjakjskjd jkkjakjskjdkj jkakjsjkjjh qwejh ak jsh de
jajkskdjheukam k lskjd lñaks jaks lsñloeoap klsk dñaie dkals d</para>
<para>hajqopegwh hrte jau jhdta jueka jskajs kl ñql mkansge trqew zmxna hdtal sjslakjd asjskjda
jakjskjaskjdjkaskjdhsjdkajd</para>
</section>
<section><title>Requisitos</title>
<para>Para la operación de este manual se deben de tener los siguientes requisitos mínimos: </para>
<simplelist>
<member>Navegador web: IExplorer 7 o superior, Chrome or Firefox</member>
<member>Conexión a Internet</member>
<member>Dirección o URL de accesos al sistema</member>
<member>Contar con una cuenta de correo electrónico</member>
</simplelist>
</section>
</preface>
<chapter>
<title>Capítulo 1. Ejemplo</title>
<section>
<title>Este es un título</title>
<para>Aqui va tu información muchas veces puede ser Aqui va tu información muchas veces puede ser
Aqui va tu información muchas veces puede ser
Aqui va tu información muchas veces puede serAqui va tu información muchas veces puede ser
Aqui va tu información muchas veces puede ser</para>
<simplelist>
<member>Aqui va tu información muchas veces puede ser</member>
<member>Aqui va tu información muchas veces puede ser</member>
<member>Aqui va tu información muchas veces puede ser</member>
<member>Aqui va tu información muchas veces puede ser</member>
</simplelist>
</section>
<section><title>Aqui va tu información muchas veces puede ser</title>
<para>Aqui va tu información muchas veces puede ser</para>
<figure xml:id="img1"><title>Esta es una imagen</title>
<mediaobject>
<imageobject>
<imagedata width="6in" format="JPEG" fileref="images/img1.jpg" align="center"/>
</imageobject>
</mediaobject>
</figure>
</section>
</chapter>
</book>
Se debe poner atención en la cabecera del archivo ya que, originalmente el framework trabaja para la versión 4.4 de Docbook, sin embargo yo he actualizado a la versión 5 por lo que deberán descargar los archivos "docbook-xml-5.0.zip" y "docbook-xsl-1.76.1.zip" del sitio de Docbook y colocarlos en la carpeta "DocBook-Framework-1.0/src/zip" del framework.
También se debe editar el archivo "docbook.properties" que se encuentra en la carpeta del framework:
#Ubicar las siguientes dos lineas
#dbf.xml.version = 4.4
#dbf.xsl.version = 1.70.0
#y reemplazarlas por
dbf.xml.version = 5.0
dbf.xsl.version = 1.76.1
No es necesario ejecutar los pasos anteriores, ya que estos solo deben ser ejecutados si se desea pasar a la versión 5 de Docbook lo cual es muy recomendable pero no mandatorio.
- El framework contiene las plantillas de ejemplo para los estilos. En primer lugar debemos copiar los archivos "custom.xsl" y "titlepage.xml" de la siguiente ruta: "/DocBook-Framework-1.0/docs/src/styles/html" y "/DocBook-Framework-1.0/docs/src/styles/pdf" respectivamente y colocarlos en nuestro proyecto.
- Con esto los pasos estaran completos ahora damos click sobre el archivo "build.xml" y seleccionamos la opción "Run as" -> "Ant Build".
- Obtendremos en la consola una salida como la siguiente:
- y el siguiente mensaje de éxito:
El archivo obtenido se puede encontrar en la carpeta target del proyecto dentro del workspace de eclipse. A continuación el ejemplo del PDF obtenido:
Consideraciones y retos
El anterior ejemplo tiene como intención servir para motivar a los documentadores técnicos y desarrolladores en general a involucrarse en esta tecnología. Esperemos que pronto salga una nueva versión del Framework y que la comunidad Velocity le siga dando mantenimiento a esta útil herramienta.
Para consultar la documentación del proyecto y descargar el framework, diríjete al siguiente sitio web:
Excelente documentacion, es entendible y el resumen es muy adecuado, justo para los que vamos empezando en este mundo de la documentación! Gracias
ResponderEliminar