lf152, Applications: Crear documentos PDF con DocBook

Este documento está disponible en los siguientes idiomas: English Castellano Deutsch Francais Nederlands Russian Turkce

por Egon Willighagen

Sobre el autor:

En 1999 se unió al grupo alemán de LF y a principios de este año se transformó en su segundo editor. Es estudiante de química analítica de la Universidad de Nijmegen. Juega al basket y disfruta haciendo excursiones.

Contenidos:

¿Qué es DocBook?
Escribir un artículo
Añadir texto e información adicional
Convertir el documento a PDF
Observaciones finales
Referencias
Formulario de "talkback" para este artículo

Crear documentos PDF con DocBook

Resumen:

El presente artículo explica cómo usar DocBook para crear documentos PDF. Abarca tanto las herramientas de edición como las que se necesitan para la conversión al formato PDF. Puesto que sólo se citan los programas y no se dan detalles sobre su instalación está dirigido principalmente a usuarios avanzados de Linux.

La primera parte se centrará en el formato de los documentos DocBook. Tras una breve introducción, se explicaran las herramientas necesarias para convertirlos en documentos PDF y así poder verlos con el Acrobat Reader.

¿Qué es DocBook?

DocBook [1] es una aplicación SGML desarrollada para el marcado de documentos. A diferencia del HTML, DocBook no ofrece ninguna información sobre el formato del documento y es por esta razón que se necesita de una conversión previa para poder visualizarlo. La conversión se realiza con herramientas que aplican una determinada hoja de estilo al documento DocBook.

Figura 1: Conversión de DocBook a PDF con una hoja de estilo

Posteriormente se explicará el tipo de hoja de estilo que debe usarse para la conversión y la herramienta necesaria para ello.

Escribir un artículo

DocBook es capaz de trabajar con dos tipos de documentos: artículos y libros. Puesto que en esencia son idénticos, emplearé como ejemplo el marcado de un artículo. Previamente daré una descripción básica de DocBook.

DocBook es en principio una aplicación SGML al igual que el HTML. Pero también existe una versión XML que si bien es más limitada, es más fácil de leer y , por lo tanto, más fácil de aprender. Puesto que el XML es en sí mismo una aplicación SGML, se pueden seguir usando las herramientas del SGML. La principal diferencia entre ambas variantes son las siguientes (y ésto es válido para cada aplicación XML):

las etiquetas XML deben estar siempre enmarcadas.
las etiquetas XML deben anidarse de manera adecuada.

Lo primero significa que no se puede usar <BR> como en el HTML, sino <BR></BR>. El segundo requisito significa que no se puede escribir <B><A HREF="alguna_url">hacer click aquí</B></A> sino anidar las etiquetas correctamente: <B><A HREF="alguna_url"> hacer click aquí</A></B>.

Teniendo en cuenta estas importantes formalidades, podemos empezar a escribir artículos con DocBook.

<?xml version="1.0"?>
    <article>
      <title>Escribir artículos DocBook</title>
      <artheader>
        <abstract>
          El presente artículo explica como usar DocBook para crear documentos PDF
          y cubre las herramientas necesarias para editar documentos DocBook
          y transformarlos al formato PDF.
        </abstract>
        <author>
          <firstname>Egon</firstname>
          <surname>Willighagen</surname>
        </author>
        <date></date>
      </artheader>
    </article>

Se diría que no es muy difícil. Hemos comenzado con un artículo con su título, un breve resumen, la fecha en que fue escrito y el nombre de su autor.

El siguiente paso consiste en añadir secciones al artículo haciendo uso de etiquetas de sección (<section>, </section>):

<?xml version="1.0"?>
    <article>
      <title>Escribir artículos DocBook</title>
      <artheader>
        ... Encabezado del artículo ...
      </artheader>

      <section>
        <title>Introducción</title>
      </section>

      ... otras secciones ...

    </article>

Al artículo se le ha agregado una sección Introducción. Se pueden añadir más secciones para obtener Resultados, Conclusión, etc.

Añadir texto e información adicional

Todo el texto está contenido entre etiquetas de párrafo (<para>, </para>), comparables a los elementos <P></P> del 'HTML':

<section>
      <title>Introducción</title>
      <para>
        DocBook es una aplicación SGML desarrollada para el marcado de texto,
        al igual que el HTML lo es para el marcado de documentos web.
      </para>
</section>

Pero además de las etiquetas de párrafo están disponibles una gran cantidad de otras etiquetas. En lo que resta de esta sección se explicará como insertar en el artículo ejemplos, listas, gráficos, etc.

Añadir ejemplos

Los ejemplos se pueden agregar mediante el uso de etiquetas de ejemplo (<example>, </example>), como se muestra a continuación:

<example>
  <title>Programa en Perl que convierte un documento XML en una página HTML.</title>
  <programlisting>
    #!/usr/bin/perl -w
    use diagnostics;
    use strict;
    use XML::XSLT;

    my $XSLTparser = XML::XSLT->new();
    $XSLTparser->open_project ("file.xml", "stylesheet.xsl", "FILE", "FILE");
    $XSLTparser->process_project;
    $XSLTparser->print_result();
  </programlisting>
</example>

Cabe destacar que el ejemplo puede a su vez contener texto, gráficos u otra información.

Añadir listas

Al igual que en el HTML, DocBook también puede contener listas. Las listas se definen mediante la etiqueta de listas no ordenadas (<itemizedlist>, </itemizedlist>) que contiene una o más etiquetas de items (<listitem>, </listitem>):

<itemizedlist>
  <listitem>
    <para>an item</para>
  </listitem>
  <listitem>
    <para>another item</para>
  </listitem>
  <listitem>
    <para>and again an item</para>
  </listitem>
  </itemizedlist>

Observesé que aquí también el texto está contenido en una etiqueta de párrafo. ¡El texto debe siempre estar contenido dentro de esta etiqueta!

Asimismo las listas pueden ordenarse. En este caso se puede usar la etiqueta de listas ordenadas (<orderedlist>, </orderedlist>) en vez de la etiqueta de listas no ordenadas. Agregando un parámetro numérico (ej.<orderedlist numeration="Arabic">) se puede obtener una lista numerada.

Añadir gráficos

Se pueden poner imágenes en el artículo:

<mediaobject>
<imageobject>
<imagedata fileref="alguna_imagen.gif" format="gif"/>
</imageobject>
<textobject>
  <para>
    Si no se está usando <productname>Lynx</productname>
    se puede ver un gráfico.
  </para>
</textobject>
</mediaobject>

Como puede verse junto al texto aparece la imagen elegida. De hecho pudiera haber agregado una película.

Nótese también que la palabra Lynx está resaltada. Éste es un rasgo característico de los lenguajes de marcado en donde el formato está separado de la información. El artículo establece que Lynx es un producto. Posteriormente la hoja de estilo establecerá que el nombre del producto debe mostrarse en un formato específico, por ejemplo, en cursiva. En la siguiente sección veremos algunos métodos de marcado de palabras.

Marcado de palabras

Como hemos visto en el ejemplo de arriba, se pueden resaltar palabras. En la siguiente tabla se muestran algunas etiquetas de marcado aplicadas a palabras:

Etiqueta	Descripción
abbrev	Una abreviatura, en particular una terminada en punto. Ejemplo: <para><abbrev>ej.</abbrev> significa por ejemplo.</para>
acronym	Un acrónimo Ejemplo: <para><acronym>DSM</acronym> (compañía química) significa "De StaatsMijnen" (Minas del Estado en alemán). </para>
email	La dirección electrónica de una persona Ejemplo: <para>Mi email es <email>egon.w@linuxfocus.org</email></para>
keyword	Palabras claves del artículo Ejemplo: <para>En mi humilde opinión <keyword>la química</keyword> es muy importante.</para>

Y una gran cantidad de otras etiquetas que están listadas en una completa hoja de referencia [2].

Tras esta breve introducción a las etiquetas de DocBook, estamos en condiciones de crear los documentos PDF.

Convertir el documento a PDF

Una vez obtenido el documento DocBook, podemos convertilo a distintos formatos. Además del PDF, se puede convertir en documento PostScript, en archivo fuente Tex o en documento RTF (Formato de texto enriquecido) que puede leerse con WordPerfect, Word, StarWriter y otros procesadores de texto. Sin embargo, en el presente artículo haremos únicamente hincapié en la conversión a documento PDF.

Los documentos DocBook se pueden escribir con cualquier editor tales como Vi y Enedit. Mejor aún con Emacs: Norman Walsh ha escrito un modo mayor de Emacs para DocBook [3] que agrega ciertas funcionalidades útiles como el poder completar el nombre de las etiquetas o insertar plantillas. Antes de crear tu propio artículo de prueba, puedes bajarte docbook_article.xml mi versión que contiene los ejemplos dados en este artículo.

Como he explicado al principio se necesita tanto una hoja de estilo como una herramienta que haga uso de ella para convertir el artículo DocBook en formato PDF. De hecho la hoja de estilo no hace la conversión de manera automática sino que requiere de un paso intermedio con TeX. Las hojas de estilo que usaremos son las Hojas de Estilo Modulares de DocBook de Norman Walsh [4] escritas en DSSSL.

Para emplear en el proceso de conversión las hojas de estilo en DSSSL, se necesita un procesador DSSSL. El procesador que utilicé se denomina Jade [5] que fue desarrollado por James Clark (actualmente ha dejado de brindar soporte a esta herramienta). Fue reemplazado por OpenJade [6], una utilidad que aún no he tenido posibilidad de probar.

Nótese que los paquetes de Hojas de Estilo Modular, Jade y JadeTex (ver arriba) están disponibles en todas las distribuciones que usan paquetes (tales como RedHat, Suse, Corel y Debian). ¡Por lo tanto verifiquen primero el disco de instalación o la página web de su distribución!

En mi sistema Debian las Hojas de Estilo Modular de Walsh para conversiones a PDF se encuentran instaladas en /usr/lib/sgml/stylesheets/dsssl/docbook/nwalsh/print/ y son accesibles desde Jade mediante el parámetro "-d". Por otra parte, la opción "-t" indica a Jade que use a TeX para obtener el documento final:

egonw@localhost> ls -al
total 3
-rw-r--r--    1 egonw    egonw        2887 Apr  8 22:06 docbook_article.xml
egonw@localhost> jade -t tex -d /usr/lib/sgml/stylesheets/dsssl/docbook/nwalsh/print/docbook.dsl docbook_article.xml
egonw@localhost> ls -al
total 21
-rw-r--r--    1 egonw    egonw        2887 Apr  8 22:06 docbook_article.xml
-rw-r--r--    1 egonw    egonw       17701 Apr  8 22:29 docbook_article.tex

Como pueden ver, Jade genera un archivo TeX que se puede convertir a PDF con la herramienta pdfjadetex que acompaña al paquete JadeTeX [7]:

egonw@localhost> ls -al
total 21
-rw-r--r--    1 egonw    egonw        2887 Apr  8 22:06 docbook_article.xml
-rw-r--r--    1 egonw    egonw       17701 Apr  8 22:29 docbook_article.tex
egonw@localhost> pdfjadetex docbook_article.tex

Esto crea un agradable docbook_article.pdf. Notemos que se han agregado un montón de detalles tales como el título al comienzo de cada página y el uso de diferentes fuentes para el listado del programa. Cuando empezé a trabajar con DocBook la mayoría del tiempo la dediqué en comprender todas las combinaciones posibles. Este artículo muestra solamente una de ellas.

Observaciones finales

El lenguaje DocBook XML es muy amplio y los métodos para convertir los documentos en otros formatos son diversos. Este artículo sólo proporciona una pequeñísima introducción. Las preguntas pueden formularse en la página de consulta de este artículo. Más información se puede encontrar en las referencias [8] y [9]. ¡Fíjense que esta última referencia ha sido completamente escrita en DocBook!

Los tópicos avanzados que no han sido cubiertos por el presente artículo pero que están disponibles con DocBook son:

manejo de información bibliográfica
creación de enlaces a otras secciones

Estos temas quizás sean tratados en un futuro artículo.

Referencias

http://www.docbook.org/ La página web de DocBook.
http://nwalsh.com/docbook/defguide/qr/quickref.htm Referencia Rápida: las Etiquetas de DocBook.
http://nwalsh.com/emacs/docbookide/index.html Modo mayor de Emacs para DocBook
http://nwalsh.com/docbook/dsssl/index.html Las Hojas de Estilo Modular de DocBook.
http://www.jclark.com/jade/ Jade.
http://openjade.sourceforge.net/ OpenJade.
http://www.tug.org/applications/jadetex/ JadeTeX.
http://nwalsh.com/docbook/ Página web de Norman Walsh sobre DocBook.
http://www.oreilly.com/catalog/docbook/chapter/book/docbook.html DocBook: La Guía Definitiva sobre la variante del SGML.

Formulario de "talkback" para este artículo

Cada artículo tiene su propia página de "talkback". A través de esa página puedes enviar un comentario o consultar los comentarios de otros lectores

Ir a la página de "talkback"

Contactar con el equipo de LinuFocus
© Egon Willighagen, FDL
LinuxFocus.org
Pinchar aquí para informar de algún problema o enviar comentarios a LinuxFocus

Información sobre la traducción:

en	->	--	Egon Willighagen
en	->	es	Walter Echarri

2001-03-30, generated by lfparser version 2.9