Documentación con DocBook

Tabla de contenidos

Por qué usar SGML?
El DTD DocBook
Elementos

Por qué usar SGML?

Para la creación de articulos/libros/tutoriales/etc se hace necesario utilizar un medio de documentación estandar de manera que la modificación de los documentos fuentes sea mas sencilla al igual que la generación de estos en diferentes formatos sea un paso trivial.

SGML

La documentación estructurada se construye sobre elementos estructurados: capítulos, secciones, párrafos, etc. donde los elementos se etiquetan claramente para que son: referencias, salida de programas, etc. No se da ningúna información explícita sobre como el documento debe ser escrito, solamente sobre su estructura y contenido.

Esto permite el proceso automático de los documentos, animando a los autores a que se concentren en el contenido de los documentos y no en el como generarlos.

Asi, el preguntarse "como colocar una palabra en negrilla con SGML?" tiene poca importancia, lo que uno se pregunta es como poner mas énfasis en un cierto texto.

El SGML (Standard Generalized Markup Languaje) es un lenguaje estandarizado previsto para facilitar la escritura de documentación estructurada. Mas especificamente es un metalenguaje. Realmente no se escribe el documento en SGML, El SGML se utiliza para describir un lenguaje estructurado especifico para un tipo de documento, llamado DTD (Document Type Definition), que especifica como los documentos pueden ser escritos.

Por lo tanto decir que un documento está escrito en formato SGML es técnicamente correcto, pero engañoso. Podra decir que un documento está escrito con el formato DocBook u otro formato definido en SGML.

SGML es un lenguaje de marcas. Todos los documentos incluyen texto mezclados con etiquetas que delimita los elementos. En el Ejemplo 1, “Uso de Etiquetas” se muestra el uso de las etiquetas.

Ejemplo 1. Uso de Etiquetas

        <article>
        <title>Proyecto GNOME Chile</title>
        <para>Vamos que se puede!</para>
      

Se parace a HTML, pues HTML es teóricamente un DTD de SGML. Los elementos tienen un contenido, por ejemplo el contenido del elemento "para" tiene "Vamos que se puede!".

Los elementos pueden tener cualidades, para indicar mas información, por ejemplo:

      <example id="ejemplo1">
      .....
      </example>
      

Un elemento es especial, el elemento de la "raiz" que es el elemento global, que contiene a todo el documento. En XML, la linea DOCTYPE indica que elemento es la raiz. En el Ejemplo 2, “Elemento raiz de un documento” se muestra una linea de este tipo.

Ejemplo 2. Elemento raiz de un documento

	<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
	

Archivos XML

Como no es el propsito de este documento el hablar explcitamente sobre XML, sólo diremos que los archivos XML comienzan primero con una "instrucción de proceso", que comienzan con <?, y en este caso indica que es un archivo XML, además de cierta meta-información. Esto lo vemos en el Ejemplo 3, “Encabezado de un archivo XML”.

Ejemplo 3. Encabezado de un archivo XML

	  <xml version="1.0" encoding="utf-8"?>
	  

Los archivos XML deben ser "bien formateados", es decir, las etiquetas de comienzo deben siempre tener una etiqueta de término. También puede tener "elementos vacios" donde la etiqueta de inicio con la de término se convinan en una sola etiqueta escrita:

	<etiqueta/>
	

Qué es un DTD?

Un DTD (Document Type Definicion) es la descripción (en SGML) de un lenguaje específico. Puede escribir su propio DTD o puede usar un DTD ya existente, con la ventaja de poder intercambiar documentos con otras personas. Existe varios DTDs, tipicamente para propósitos de un grupo de gente dado (astrónomos, químicos,etc).

El DTD enumera los elementos y sus relaciones permitidas, por ejemplo, un "capitulo" debe tener por lo menos una "sección". Algunos DTDs que puede encontrar útiles son:

  • DocBook: Utilizado para la documentación técnica especialmente sobre software.

  • LinuxDoc: Utilizado por el proyecto de documentación de Linux, por ejemplo para el Linux-COMO.

  • DebianDoc: Utilizado en parte por el proyecto de documentación de Debian.

  • HTML: en teoría es un DTD pero muy poca páginas actuales respetan su definición.