Notas para usar DocBook

Hace un tiempo, en la comunidad PingüinoVE, hemos dedicado un tiempo evaluando qué herramienta usar para documentar la información del proyecto, entre manuales, libros, artículos, otros; una de las alternativas mas destacadas es DocBook.

Para esto nos dimos un tiempo para transmitir algunas notas de dicha herramienta y cómo comenzar a usarla sin mayores tropiezos.

Voy a listar los paquetes que se deben tener instalados para usar la suite sencilla en Debian como usuario root:

# aptitude -yr install docbook docbook-dsssl docbook-utils docbook-xml docbook-xsl openjade jadetex

En Fedora, como usuario root:

# yum install docbook docbook-style-dsssl docbook-utils docbook-dtds docbook-utils-pdf openjade jadetex

Luego de instalar los complementos, se debe elegir un editor de texto para comenzar a editar los archivos fuentes, cabe destacar que DocBook trabaja con código fuente SGML o XML, de estos archivos fuentes parte toda la documentación que posteriormente podrá ser exportado a formatos como: HTML, PDF, MAN, …, Postscript. Cualquier editor podría funcionar, entre los mas destacados se pueden usar:

  • Bluefish
  • Emacs
  • Gedit
  • Kate
  • Geany
  • Anjuta
  • vi / vim
  • nano

En fin, cualquier editor de texto viene bien. Teniendo las herramientas necesarias se procede a crear los documentos, particularmente para llevar un orden, ya como usuario normal, genero un directorio donde guardaré todos mis archivos fuentes:

$ mkdir documento

Inicialmente crearé un capítulo independiente al documento completo:

$ touch capitulo1.xml

Dentro del archivo capitulo1.xml guardaré el siguiente contenido:



Mi primer capítulo


Aprendiendo hacer documentos con DocBook
DocBook usa un lenguaje de marcación, entre los que podemos usar SGML o XML.





Como lenguaje semántico que es, DocBook nos permite crear documentos en un formato
neutro, independiente de la presentación.



Se debe tomar en cuenta la cabecera “!DOCTYPE chapter PUBLIC” donde se ve claramente que el documento será de tipo capítulo. Y para transportarlo a HTML o PDF, se puede realizar de la siguiente forma respectivamente:

$ db2html capitulo1.xml
$ db2pdf capitulo1.xml

En el caso del PDF siempre quedará en un archivo .pdf, en el caso del HTML siempre se crearán un directorio con múltiples archivos .html.

Bien, básicamente es esto, por otro lado podemos hacer múltiples capítulos y crear con todos un solo documento o libro, sin embargo, para crear el libro completo se debe tener el archivo principal que guardará la información del libro, para lo que sería necesario editar un archivo documento.xml como el siguiente:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.0//EN" [

]>


Manual de Referencia DocBook


Satélite
Guayana


2010
sateliteguayana.com.ve



&cap1;


Una observación, es clara que la cabecera queda de manera diferente al capítulo, “!DOCTYPE book PUBLIC”, igualmente se incluye el capítulo ya realizado, pero previamente se debe comentar la cabecera del archivo capitulo1.xml, debe quedar:

<!--  -->

Para transportar el libro completo es cuestión de ejecutar:

$ db2html documento.xml
$ db2pdf documento.xml

Finalmente con el formato HTML genera un directorio con varias páginas .html y en cuanto al PDF solo genera un archivo .pdf.

Pienso que son dos ejemplos sencillos por lo menos para dar inicio al uso de DocBook como herramienta para documentar temas técnicos, existen otras herramientas como LaTeX usando LyX, entre otras.

Advertisements
This entry was posted in DocBook. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s