Documentación técnica usando <acronym>DocBook</acronym> 13 de Junio 2002 Jaime Irving Dávila El presente documento se cede al dominio público
Introducción Historia DocBook nace en 1991 bajo la iniciativa de un grupo informal que incluía representantes de O'Reilly, Hal Computer Systems y representantes de los mayores vendedores de UNIX los cuales buscaban explorar formatos electrónicos que permitieran intercambiar los manuales de mejor forma. En 1994, este grupo informal se organiza bajo el nombre del grupo Davenport y continua su desarrollo hasta 1998. Dicho grupo se fusiona con OASIS hacia 1998. OASIS es un consorcio de XML/SGML que busca la estandarización. Hoy en día DocBook es utilizado por multitud de empresas como lo son SUN, HP y O'Reilly y por proyectos de Software Libre/Fuente Abierta como lo son GNOME, Free BSD, KDE, PHP y LDP. ¿Qué es <acronym>DocBook</acronym>? Es un formato de escritura estructurada basado en tecnología SGML/XML que permite escribir documentación técnica. Documentación estructurada ... ¿es decir? Se dice que un formato es estructurado si da énfasis a la estructura del documento, en contraste con la forma en que el documento es presentado Por ejemplo HTML usado de cierta forma puede ser un formato estructurado, como en el siguiente ejemplo: Mi primera página

Título

Un párrafo

]]> O puede no serlo ... Mi primera página Título

Un párrafo ]]> ... ¿Y qué es <acronym>SGML</acronym>? ¿y <acronym>XML</acronym>? SGML significa Standard Generalized Mark-up Language y es la especificación de un conjunto de lenguajes basados en marquillas. El ejemplo más famoso de dialecto SGML es HTML. XML es una simplificación de SGML con propósitos de orientación a la web. No incluye características de SGML como lo son la minimización de marquillas. ¿Y qué es documentación técnica? Algunos ejemplos de documentación técnica: Manuales de usuario. Libros técnicos, de enseñanza de un lenguaje. Documentación de un API Una sección de preguntas frecuentes (FAQ). Algunos ejemplos de documentación no técnica: Una carta. Una hoja de vida. Un libro de recetas.
Un primer ejemplo en <acronym>DocBook</acronym> Archivo <filename>hola.sgml</filename> Hola Esta es la introducción Sección Única Y hasta dice algo. Primera subsección 1 < 2 Segunda subsección Nada que decir ]]> Descripción de las partes de <filename>hola.sgml</filename> Encabezado Es donde se describe que tipo de documento SGML, puede hacer referencia a un archivo físico o a un identificador que después se resuelve en un catálogo. En este caso el encabezado es ]]> Elementos Es cualquiera de las marquillas que describen la estructura, en este caso solo presentamos marquillas de organización del documento, las cuales son book, sect1, title. Entidades Usualmente representan caracteres que no pueden ser presentados textualmente. En este caso, la entidad que utilizamos era &lt; en vez de < que tiene significado adicional dentro de SGML. Comentarios Usualmente no son procesados, brindan aclaraciones en el documento. Es <!-- Un primer comentario --> Edición de <acronym>SGML/XML</acronym> Puesto que los archivos SGML son archivos de texto, la edición se puede realizar a través de editores de texto. Sin embargo dependiendo del editor se tienen más facilidades para la escritura (escribir un documento DocBook en Notepad NO es recomendado) Los más populares editores que tienen facilidades para DocBook son: Emacs: Tiene el modo PSGML el cual muestra cuales son las marquillas disponibles en un momento determinado, hace autocompletación ... Vim: Existe una manera de configurarlo, para no escribir las marquillas completas. Jedit: Es un editor hecho en Java, con muchas características gráficas, y que muestra por ejemplo el árbol de la estructura de un documento. Formatos de salida A partir de hola.sgml se pueden generar diversas salidas en diversos formatos como: HTML PS RTF PDF Esto se realiza a través de algunos scripts como db2html, db2ps, db2rtf, db2pdf. Algunos conceptos en <acronym>SGML/XML</acronym> DTD Es un archivo en el cual se describe la sintaxis de un documento SGML/XML, en el se definen cuales son las marquillas válidas, que tipo de entidades se van a utilizar. Hojas de estilo: DSSSL y XSLT Definen cual va a ser la presentación que va a tener documento en formato HTML o en salida impresa. DSSSL es un lenguaje con una sintaxis similar a LISP y que es propia de SGML. XSLT cumple con el mismo propósito usando un lenguaje con sintaxis XML, simplificando algunas características de DSSSL Las hojas de estilo son bastante configurables, a través de multitud de parámetros y de las facilidades que brinde cada lenguaje de hojas de estilo. Algunos conceptos en <acronym>SGML/XML</acronym> (2) Procesador DSSSL o XSL Son programas que toma un archivo XML y una hoja de estilo y generan una determinada salida. Algunos de los más populares y utilizados son openjade/jade Es un procesador DSSSL bastante maduro, que permite generar salida en HTML, TEX y RTF xsltproc Es el procesador XSL del proyecto Gnome. Bastante rápido y genera salida en HTML, XML y FOP. saxon Es un procesador XSL escrito en Java, bastante popular.
Algunas posibilidades Un pequeño artículo
Jose Fernando Pérez Una aproximación analítica a <phrase>Hola Mundo</phrase> 13 de Junio de 2002 2002 Jose Pérez 1.0 15 de Mayo de 2002 Versión inicial 1.1 13 de Junio de 2002 Inclusión de capítulo Hello World
Hola Mundo
]]> Un párrafo en un tutorial En emacs C-x significa que presione al mismo tiempo Control y X Puede conseguir información adicional de emacs en este enlace, o una copia del archivo hola.txt. En caso de dudas o comentarios puede enviar un email a jadavila@uniandes.edu.co. hola.txt emacs información ]]> Descripción de un <acronym>API</acronym> HelloWriter HelloWriter String greeting print ]]> Preguntas Frecuentes ¿Qué es DocBook? Es un lenguaje de marcado útil para escribir documentación técnica. ]]>
Recursos adicionales Bibliografía Docbook: The Definitive Guide Introducing Docbook Presentación de Docbook Tutorial de Docbook: Un enfoque integrado y a través de ejemplos Para resolver dudas existen: Lista docbook-ayuda Lista docbook y docbook-apps Preguntas frecuentes (FAQ)