DocBook

Summary

DocBook es una aplicación del estándar SGML/XML e incluye una DTD propia y que se utiliza de manera más destacada en el área de la documentación técnica, especialmente para documentar todo tipo de material y programas informáticos. Existe un Comité Técnico de DocBook en OASIS (originalmente SGML Open) que mantiene y actualiza este estándar. DocBook inicialmente comenzó como una DTD de SGML, pero a partir de la versión 4 existe un equivalente para XML.

Como lenguaje semántico que es, DocBook nos permite crear documentos en un formato neutro, independiente de la presentación. En este formato neutro se recogen tanto el contenido como la estructura lógica del mismo, permitiendo así que pueda ser publicado (presentado) automáticamente en multitud de formatos: HTML, XHTML, EPUB, PDF, man pages , HTML Help, etc., simplemente aplicando "plantillas" de presentación, sin que sea necesario ningún cambio sobre el documento original.

Introducción

editar

DocBook es un lenguaje XML. En su versión actual (5.0), está formalmente definido por un esquema RELAX NG con reglas Schematron integradas. (Existen también un XML Schema+Schematron y un DTD, pero actualmente se consideran no estándares.)

Los documentos DocBook no describen ni la apariencia ni la presentación de sus contenidos, sino únicamente el sentido de dichos contenidos. Por ejemplo, en lugar de indicar exactamente cómo ha de visualizarse una determinada frase que es el título de un capítulo, DocBook simplemente indica que dicha frase es un título de capítulo. Posteriormente, el decidir dónde y cómo se ha de mostrar dicho título dentro de la página será tarea de una herramienta procesadora externa o de la aplicación visualizadora que estemos manejando.

DocBook dispone de un gran número de etiquetas para describir elementos semánticos, englobándose estas en tres grandes categorías: estructurales, de bloque y de línea.

Las etiquetas estructurales especifican características generales de sus contenidos. Por ejemplo, el elemento book especifica que sus elementos hijo serán partes de un libro: títulos, capítulos, glosarios, apéndices, etc. Algunas etiquetas estructurales son:

  • set:
  • book:
  • part:
  • article:
  • chapter:
  • appendix:
  • dedication:

Los elementos estructurales pueden contener a otros elementos estructurales, pero han de ser siempre elementos de primer nivel dentro de un documento DocBook.

Las etiquetas de bloque representan elementos tales como párrafos, listas, etc., y no todos ellos han de contener necesariamente texto en su interior. Estos elementos de bloque suelen ir distribuidos secuencialmente, y serán visualizados uno "debajo" de otro. (Aunque "debajo" puede variar dependiendo del entorno cultural: en la mayoría de lenguajes occidentales "debajo" significará un sentido descendente en la página; pero en algunos lenguajes orientales, "debajo" significará un sentido en columnas de derecha a izquierda. La especificación DocBook es completamente neutral a ese tipo de conceptos intrínsecos de cada cultura.)

Las etiquetas de línea representan elementos tales como letras enfatizadas, hyper-enlaces, etc, y se suelen aplicar a porciones de texto en el interior de un elemento de bloque, provocando habitualmente que la herramienta procesadora de presentación aplique algún tipo de tratamiento tipográfico especial a dichas porciones. (La especificación de DocBook indica que se espera un tratamiento tipográfico especial, pero no indica exactamente qué tratamiento específico se debe aplicar. Por ejemplo, "letras enfatizadas" no implica necesariamente "letras en cursiva"; la herramienta de presentación puede optar por aumentarles el tamaño de letra o por cambiarles el color de fondo.)

Ejemplos

editar

Artículo en DocBook SGML/XML

editar
<?xml version="1.0" standalone="no"?>
     <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
       "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

     <article lang="es">
      <title>Creando Documentación Técnica con
      DocBook</title>

      <articleinfo>
       <author>
        <firstname>Leonardo</firstname>
        <surname>Caballero</surname>
       </author>
      </articleinfo>

      <section id="art-intro">

       <title>Introducción</title>

       <para>DocBook es un aplicación del estándar
       SGML/XML e incluye una DTD propia y que se utiliza de manera
       más destacada el área de la documentación
       técnica, especialmente para documentar todo tipo de
       material y programas informáticos, para mayor
       información consultar aquí <ulink
       url="http://www.oasis-open.org/docbook/"/>.</para>

      </section>

     </article>

Desde un punto de vista semántico, este documento es un "artículo" (article), con su respectivo "título" (title). Se identifica claramente al "autor" (author), y se podría haber incluido también otro tipo de "información" adicional (articleinfo). Este artículo de ejemplo consta de una sola "sección", también con su respectivo "título"; y con "párrafos" (paragraph) de texto.

Libro en DocBook SGML/XML

editar
     <?xml version="1.0" standalone="no"?>
     <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
       "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
     <book lang="es" id="simple_libro">
      <title>Un libro muy simple</title>

       <chapter id="capitulo_1">
        <title>Capitulo 1</title>
        <para>Hola mundo!</para>
        <para>¡Yo espero que tu día sea bueno!</para>
       </chapter>

       <chapter id="capitulo_2">
        <title>Capitulo 2</title>
        <para>Hola otra vez, mundo!</para>
       </chapter>
    </book>

Desde un punto de vista semántico, este documento es un "libro" (book), con un "título" (title); consta de dos "capítulos" (chapter), cada uno de ellos con su propio "título", y estos "capítulos" tienen "párrafos" (paragraph) de texto. Todo ello expresado en un formato fácilmente comprensible por humanos.

Esquemas y validación

editar

Tanto los distintos elementos que forman un DocBook, como las reglas para combinarlos (por ejemplo, que todo elemento "libro" ha de contener un elemento "título", previo a cualquier otro elemento estructural tal como "capítulo"), se definen formalmente en un esquema (schema), de tal forma que los programas informáticos pueden validar el documento contra dicho esquema, y determinar así, en todo momento, si el documento está bien formado.

Escritura

editar

Como documentos XML que son, los documentos DocBook pueden ser escritos con cualquier editor de texto, aunque siempre será más sencillo escribirlos con un editor XML, o, mejor aún, con un editor XML que lleve integrados los esquemas específicos de DocBook. Por ejemplo Emacs, trabajando en modo nXML, o XML Copy Editor.

También existen editores más "visuales" (WYSIWYG), tales como XMLmind Editor ("XXE"), Oxygen XML Editor, capaz de representar los documentos DocBook formateándolos con CSS; o Syntext Serna, que realiza transformaciones XSL en tiempo real.

Postproceso

editar

Asimismo, como documentos XML que son, los documentos DocBook pueden ser validados y procesados automáticamente por cualquier herramienta o lenguaje de programación que soporte XML.

Estas herramientas se suelen utilizar para crear documentos de salida en un amplio abanico de formatos, habitualmente haciendo uso de "hojas de estilo" DocBook XLS, un tipo de hojas XSLT que nos permiten transformar documentos DocBook a otros formatos tales como HTML, PDF, etc., permitiendo conversiones tan sofisticadas como para que contemplen la generación automática de tablas de contenido, de glosarios y/o de índices, o que permitan incluso filtrados previos de contenidos, extractando solo ciertas partes del DocBook original.

Usos

editar

DocBook es muy utilizado en algunos contextos, entre los que destacan Linux Documentation Project (Proyecto de documentación Linux), las referencias de las APIs de GNOME y GTK+, así como la documentación del núcleo Linux. Las páginas man del Entorno Operativo Solaris se generan también a partir de documentos que utilizan las DTDs o los esquemas de DocBook.

Historia

editar

DocBook nació en 1991, de un proyecto conjunto de HAL Computer Systems y O'Reilly & Associates, evolucionando posteriormente hasta tener su propia organización (el Grupo Davenport), para acabar, en 1998, siendo gestionado por el consorcio SGML Open, que más tarde se convertiría en la organización OASIS, en cuyo seno existe actualmente el DocBook Technical Committee, encargado del mantenimiento del estándar DocBook.

La especificación DocBook está disponible tanto en el formato SGML como en el formato XML, estando definida tanto por un documento DTD, como por un esquema RELAX NG - W3C XML Schema. A partir de la versión 5, el esquema RELAX NG es el "normativo", siendo el resto de formatos meras adaptaciones del mismo.

DocBook nació como una aplicación de SGML, pero actualmente su adaptación XML la ha sustituido en la mayoría de usos. (A partir de la versión 4 del DTD SGML, la versión DTD XML ha tomado su propio camino y su propio esquema de numeración.)

En un principio, el uso del formato DocBook estaba prácticamente reducido al grupo de compañías participantes en su diseño, pero en estos momentos ha sido ampliamente adoptado por toda la comunidad de software libre y por un amplio espectro de compañías, existiendo en el mercado multitud de herramientas que hacen uso de él.

Norman Walsh y el equipo de desarrollo del DocBook Open Repository mantienen un conjunto de hojas de estilo DSSSL y XSL para generar versiones PDF y HTML de documentos DocBook (así como para desarrollar otros formatos, incluyendo páginas de referencia man y de ayuda en HTML). Walsh es también el principal autor del libro DocBook: The Definitive Guide (DocBook: La Guía Definitiva), la documentación oficial de DocBook. Este libro se puede obtener bajo licencia GFDL o en su versión impresa (ISBN 1565925807), editada por O'Reilly & Associates."

Referencias

editar

Enlaces externos

editar
  • DocBook wiki
  • DocBook en OASIS (Organization for the Advancement of Structured Information Standards)
  • DocBook Open Repository Project en SourceForge
  • DocBook Validator + Transformer en SourceForge
  • DocBook's Live-DTD
  • DocBook: The Definitive Guide
  • DocBook Filters - Read and write DocBook xml using OpenOffice.org
  • Getting Started With DocBook on OpenOffice, para aquellos que deseen editar DocBook con el OpenOffice.org.
  • <oXygen/> DocBook Editor (commercial)
  • Writing and producing documentation (HTML Help) with DocBook
  •   Datos: Q796483