Trucos y consejos para DocBook

Inclusión de imágenes

Mientras que LinuxDoc no permitía la inclusión de imágenes en los CÓMOs, Docbook ofrece esta posibilidad. A continuación se muestra una manera sencilla de hacerlo:

 
<figure> 
<title>LyX screen shot</title> 
<mediaobject> 
<imageobject><imagedata fileref="lyx_screenshot.eps" format="eps"></imageobject>
<imageobject><imagedata fileref="lyx_screenshot.jpg" format="jpg"></imageobject>
<textobject><phrase>Screen shot of the LyX document processing program</phrase></textobject>
</mediaobject> 
</figure> 

Este procedimiento es mejor que <graphic> por dos motivos. En primer lugar, en DocBook 5.0 se sustituye la etiqueta <graphic> por la etiqueta <mediaobject> . Por esto, quizá sea mejor comenzar bien desde un principio. En segundo lugar, <mediaobject> permite diferentes tipos de formato en función de la salida. En el ejemplo, la primera etiqueta <imageobject> es un fichero .eps usado con formatos derivados de TeX como DVI, PS, y PDF. La segunda <imageobject>es una imagen JPEG para mostrarse en pantalla, sobre todo para formato HTML. La etiqueta <textobject> se incluye por si la salida no soporta imágenes (TXT). Considérela una etiqueta <alt> .

Designación de ficheros HTML

Por defecto, cuando se crea un conjunto de ficheros HTML , el procesador de SGML asigna nombres arbitrarios a los ficheros resultantes. Esto puede confundir a los lectores que deseen marcar una página para realizar modificaciones o para saber qué contiene cada uno de los ficheros. Sean cuales fueren sus razones, aquí tiene un modo de designarlos a su voluntad:

En la primera etiqueta <article> (que debería ser la única) incluya un parámetro id y llámelo índice. La etiqueta debería, pues, tener la siguiente forma:

<article id="index">

No modifique la primera etiqueta <sect1> pues suele ser una introducción que deseará figure en la primera página. Incluya un parámetro id en el resto de las etiquetas <sect> , y dele un nombre. Los nombres deberían constar únicamente de caracteres alfanuméricos y ser representativos de su contenido.

<sect1 id="tips">

Uso de ldp.dsl

El LDP utiliza su propio fichero DSSSL, que permite, por ejemplo, añadir un fondo blanco y generar automáticamente la tabla de contenidos que puede ver al comienzo de los CÓMOs. Puede encontrar la última versión de este fichero en http://metalab.unc.edu/gferg/ldp/ldp.dsl.

Una vez tenga el fichero, puede que deba realizar alguna labor de edición de las primeras líneas, en relación con la ubicación de sus ficheros DSSSL de DocBook. En el ejemplo, se utiliza el conjunto de utilidades Cygnus.

Almacene el fichero ldp.dsl en /usr/lib/sgml/stylesheets y ábralo con su editor de texto favorito. Debería ver algo así:

 
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY % html "IGNORE"> 
<![%html;[ <!ENTITY % print "IGNORE"> 
<!ENTITY docbook.dsl SYSTEM "docbook.dsl" CDATA dsssl> 
]]> 
<!ENTITY % print "INCLUDE"> 
<![%print;[
<!ENTITY docbook.dsl SYSTEM "docbook.dsl" CDATA dsssl> 
]]> 
]> 

Si utiliza otro DSSSL, especifique para estos ficheros la ubicación de los ficheros HTML y print en ese DSSSL. Normalmente se encuentran en directorios llamados "html" y "print".

Cuando termine, podrá generar ficheros HTML:

 
bash$ mkdir HOWTO-HOWTO ; cd HOWTO-HOWTO 
bash$ jade -t sgml -ihtml -d /usr/lib/sgml/stylesheets/ldp.dsl\#html
../HOWTO-HOWTO.sgml

La primera orden crea un directorio en el que almacenar los ficheros. La segunda orden (la orden jade) genera ficheros HTML individuales para cada sección de su documento. Si va a utilizar algo como RTF, puede hacer lo siguiente:

 
bash$ jade -t rtf -d /usr/lib/sgml/stylesheets/ldp.dsl ../HOWTO-HOWTO.sgml