General

DocBook en cápsulas: secciones y capítulos

Este es el segundo post sobre DocBook, un lenguaje de marcación basado en XML orientado hacia la elaboración semántica de documentación. El primer artículo está disponible en mi blog, y trata sobre las herramientas esenciales para trabajar con este estándar.Una de las características más atractivas de DocBook es la organización lógica que permite realizar sobre un documento y las divisiones por bloques En OpenOffice.org Writer, por ejemplo, resultan útiles los estilos predefinidos de encabezados para estructurar un documento, y cuando se utiliza correctamente la herramienta los resultados al exportar a otros formatos, como XHTML y PDF, resultan mucho más atractivos.Sin embargo, la mayor parte de la gente subutiliza sus herramientas de ofimática y tiende a desconocer que los estilos predefinidos pueden cambiar en forma sin alterar la organización del documento. Es allí donde la ordenación lógica que DocBook le permite realizar al autor proporciona herramientas útiles para generar documentación de forma rápida y precisa.Supongamos que estamos realizando un manual o un libro, bajo el tipo de documento <book> de DocBook. El elemento raíz de organización es el capítulo, identificado por la etiqueta <chapter>. Resulta una buena práctica definir el atributo id de cada elemento de división lógica (secciones y capítulos), tomando en cuenta que luego son útiles para hacer referencias inteas. Por ejemplo, una definición de capítulo se puede ver así:

<chapter id="introduccion">...</chapter>

Dentro de una etiqueta <chapter> pueden ocurrir la mayor parte de las etiquetas de DocBook, pero usualmente querremos empezar con una etiqueta <title> para indicar el título del capítulo, al estilo de <title>Introducción</title>. Adicionalmente, el elemento de bloque más utilizado es <para>, del inglés paragraph o párrafo.

<chapter id="introduccion"><title>Introducción</title><para>Bienvenido a mi primer documento en DocBook</para></chapter>

Debajo de un <chapter> pueden haber uno o más <section>, un indicador de sección. Y, sorpresivamente, ¡<section> también contiene <title> y <para>!Entendiendo la referenciaEstos ejemplos, en conjunto con la información del primer artículo, le permitirán empezar a trabajar con DocBook de forma básica. Quizás sea lo suficientemente curioso como para desear consultar la referencia de DocBook, el documento que indica qué etiquetas pueden aparecer, dónde lo hacen, en qué condiciones y qué significan.Una de las situaciones más frustrantes que se experimenta al usar DocBook por primera vez es cuando por violaciones del esquema no es posible convertir el archivo fuente XML en otros formatos. En estos casos, leer el modelo de contenido de la etiqueta deseada en la referencia resulta muy útil, por ejemplo, en la referencia de la etiqueta chapter (se han omitido líneas para reducir la longitud del ejemplo):

chapter ::=
La etiqueta que queremos
(beginpage?,chapterinfo?,
Opcionalmente, etiquetas beginpage o chapterinfo
(title,subtitle?,titleabbrev?),
Obligatoriamente un title, y opcionalmente subtitle o titleabbrev.
(toc|lot|index|glossary|bibliography)*,
Una y solo una de toc, lot, index, glossary o bibliography, que puede aparecer cero o más veces
destructorsynopsis|methodsynopsis|formalpara|para|simpara|
Una y solo una de estas, y aquí vemos a nuestro amigo para.
indexterm|beginpage)+,
Todo lo que está en el paréntesis debe aparecer al menos una vez, y se puede repetir.
Standard

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