Tutorial de DocBook: Un enfoque integrado y a través de ejemplos
Anterior	Retroceder	Capítulo 4. Usando opciones más avanzadas	Avanzar	Siguiente

4.4. Facilitando la búsquedas al usuario

Una vez un documento adquiere un cierto tamaño, es útil dotarlo de estructuras que permitan a los usuarios consultar información sobre un tema específico o consultar la definición de una palabra que se utiliza constantemente. En esta sección trataremos el tema de la creación de índices y glosarios, que son justo la solución a dicho problema

4.4.1. Glosarios

Un glosario es una parte del documento en la cuál se dá la definición de algunos de los conceptos usados en él. Usualmente los glosarios se ubican al final del documento, por ello la marquilla glossary va usualmente después del último capítulo. A continuación presentamos un ejemplo de un glosario.

<glossary>
<glossentry id="doc">
<glossterm><acronym>DocBook</acronym></glossterm>
<glossdef>
<para>Lenguaje de marcado definido en
<acronym>SGML</acronym>que permite escribir documentación
técnica</para>
/glossdef>
/glossentry>
<glossentry id="em">
<glossterm>emacs</glossterm>
<glossdef>
<para>Editor de amplio uso en <acronym>unix</acronym>. Su
nombre proviene de Editor MACroS (Macros de Edición). </para>
</glossdef>
</glossentry>
</glossary>

Aquí básicamente declaramos declaramos un glosario usando la marquilla glossary y cada una de las entradas de dicho glosario se declara usando glossentry. Tales entradas consisten en esencia de un término (glossterm) y una definición (glossdef). Notemos que cada una de las entradas de este ejemplo tienen un identificador, esto es útil en caso de que uno quiera remitir al glosario para la definición de algún término.

Es usual denotar cuando una palabra está en un glosario o cuando es la primera ocurrencia de un término en una obra, para ello son útiles las marquillas firstterm y glossterm respectivamente. Dichas marquillas pueden contener o no un enlace a su respectiva definición, utilizándose para ello el atributo linkend. En este caso dicho atributo se hace igual al identificador correspondiente a la definición del término en el glosario. A continuación presentamos dos ejemplos de dicha situación, el primero con enlace y el segundo sin él.

<para><firstterm linkend="doc"><acronym>DocBook</acronym></firstterm>
 es un lenguaje de marcado, que permite escribir documentación
 técnica, nacido en 1991.</para>

<para>Para invocar a <glossterm><acronym>emacs</acronym></glossterm>,
  basta hacer lo siguiente desde una línea de comandos</para>

4.4.2. Definiendo las palabras claves de un índice

Un índice contiene un conjunto de referencias a las ocurrencias de palabras claves dentro de un documento, por ende el paso básico en la creación de un índice corresponde en señalar los sitios donde se encuentran dichas palabras a través de la marquilla indexterm, como lo muestra el siguiente ejemplo

<para>A continuación mostramos una tabla con algunas de las
   marquillas más usadas.</para>
<indexterm>
   <primary>marquillas</primary>
</indexterm>

Es de notar el uso de primary que indica que la primer palabra clave del índice es en este caso marquillas. Uno puede usar secondary en caso de querer refinar mejor la clasificación del índice como a continuación

...
</table>
<indexterm>
  <primary>marquilla</primary>
  <secondary>book</secondary>
</indexterm>
<indexterm>
   <primary>marquilla</primary>
   <secondary>chapter</secondary>
</indexterm>

Para generar una entrada de índice a partir de una palabra, se puede usar usar C-c x mientras se selecciona una palabra (para hacer esto último desde teclado, basta presionar C-SPC y luego M-C-e para ir al final de la marquilla)

4.4.3. Generando índices

La generación de dichos índices se describe con detalles en la página Automatic Indexing with the DocBook DSSSL Stylesheets. A continuación presentamos los pasos descritos en ella

Asegúrese de tener a collateindex.pl

Es necesario que verifique que tenga dicho archivo dentro de la ruta de su sistema, para ello digite lo siguiente desde la interfaz de comandos:

[jdavila@abadon herramientas]$ perl -S collateindex.pl

Si obtiene una descripción de la sintaxis de collateindex.pl podrá proseguir, en caso contrario es necesario colocar dicho archivo dentro de la ruta (en este caso haremos un enlace simbólico a /usr/local/bin). Para ello después de registrarse como superusuario (usando el comando su desde la interfaz de comandos) es necesario realizar los siguientes pasos

[root@abadon herramientas]$ cd /usr/share/sgml/docbook/dsssl/nwalsh-modular/bin
[root@abadon bin]$ chmod +x collateindex.pl
[root@abadon bin]$ ln -s collateindex.pl /usr/local/bin/collateindex.pl
[root@abadon bin]$ exit
[jdavila@abadon herramientas]$

En mi caso las hojas de estilo DSSSL están ubicadas en /usr/share/sgml/docbook/dsssl/nwalsh-modular/, sin embargo dependiendo de su distribución pueden estar en otro lugar. Averigue en que sitio se encuentran en su distribución usando un comando como find / -name docbook.dsl

Cree una referencia hacia el índice

Dentro del documento original es necesario que cree una entidad que haga referencia al archivo de índice que se va a generar. Para ello es necesario que modifique su documento que lucía de la siguiente forma

<!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<book lang="es">
<!-- Aquí viene el contenido del documento -->
...
<!-- Aquí termina el contenido del documento -->
<book>

por algo de la siguiente forma

<!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.1//EN"[
<!ENTITITY genindex.sgml SYSTEM "genindex.sgml">]>
<book lang="es">
<!-- Aquí viene el contenido del documento -->
...
<!-- Aquí termina el contenido del documento -->
&genindex.sgml
<book>

Cree un índice vacío
Es necesario que cree un archivo genindex.sgml vacío mediante el siguiente comando
[jdavila@abadon herramientas]$ perl -S collateindex.pl -N -o genindex.sgml
Genere un archivo HTML.index
El archivo HTML.index contiene información útil para la generación de índices, esto se puede hacer a través del siguiente comado
[jdavila@abadon herramientas]$ openjade -t sgml -d /usr/share/sgml/docbook/dsssl/nwalsh-modular/html/docbook.dsl -V html-index herramientas.sgml
Genere el archivo genindex.sgml
Para generar el archivo de índice basta usar un comando como el siguiente
[jdavila@abadon herramientas]$ perl -S collateindex.pl -o genindex.sgml HTML.index
Genere la salida deseada
Ahora puede generar la salida deseada (por ejemplo HTML o ps) cómo es descrito en la Sección 2.3.2

Anterior	Inicio	Siguiente
Capturando la atención del lector	Subir	Dando información adicional