5. Más allá de Hola Mundo

Hasta aquí hemos visto las características básicas de la edición estructurada usando Emacs. Sin embargo, hay mucho, pero mucho más que ver. He aquí algunos bonitos trucos y sugerencias que van a hacer nuestra vida como autores de documentación mucho más fácil.

5.1. Dividir nuestros documentos en diferentes archivos.

Una de las principales ventajas del Formateo de Textos sobre la Edición de Textos, es la habilidad de trabajar en archivos separados y la flexibilidad a la hora de organizar estos archivos de manera personal. Más aún, con la técnica de Formatear Textos se puede ser tan flexible con nuestra documentación, como lo somos a la hora de organizar nuestros archivos fuentes cuando programamos.

Las Entidades deben ser declaradas en la declaración DOCTYPE al principio del documento. Una declaración típica es como la siguiente:

<!DOCTYPE book PUBLIC "-//OASIS//DTD Docbook V4.1//EN" [
<!ENTITY presDeLaCompania SYSTEM "presDeLaCompania.sgml"> ]>

Como se puede deducir del ejemplo anterior, las entidades son declaradas dentro de los paréntesis rectos []. Además, puede verse que existe un identificador de sistema para la entidad, de manera que el analizador sintáctico pueda encontrar el archivo cuando procese el documento principal. El nombre de la entidad, además de identificarla dentro del documento, puede tener cualquier nombre que deseemos. Personalmente, en el ejemplo, traté de mantener el mismo nombre entre el de la entidad y el identificador del sistema, pero esto no es un requisito.

Para usar nuestra entidad, sólo deberemos usar el signo & y su nombre, por ejemplo:

 &presDeLaCompania;

Importante

Cuando trabajamos con entidades, no se puede incluir una declaración DOCTYPE en la misma. Esto hace que a Emacs le sea imposible saber cómo validar el documento. He encontrado una alternativa para superar esto y es explicada abajo.

5.2. Validar nuestros documentos

Como se verá al correr de esta sección, Emacs/PSGML no sólo nos ayudará a editar documentos SGML, sino que también nos ayudará a validar documentos en cualquier momento que nos encontremos editándolos. Esta es una característica estándar pura de Emacs (no de PSGML), gracias a la cual aprenderemos a valorar la edición estructurada en dicho editor de textos.

5.2.1. Validar un documento simple

En cualquier punto del documento, simplemente presionando C-c C-v se podrá ver la orden nsgmls en el mini-búfer. Presionando enter, podremos validar nuestro documento actual. Tanto si ocurre un error en la validación, como si salió todo bien, seremos notificados en una división de la pantalla, por debajo del mini-búfer.

Algo útil con respecto a esto es saber que, si hacemos click en uno de los errores y luego enter, nos veremos desplazados justo a la línea donde se encontró el error. Es más, si el error está en otros archivo que el actual, Emacs lo abrirá automáticamente y ¡nos hará saltar a donde supuestamente se encuentra el error! Ésta es una funcionalidad estándar de Emacs en integración con algunas otras herramientas de nuestro sistema. Es el mismo caso que gdb, make o un compilador java. Así de simple.

5.2.2. Validar partes (entidades) de un documento

El principal problema con la división del documento en partes separadas en archivos, o entidades que es como se las denomina en SGML, es que no podemos tener una declaración DOCTYPE en cualquiera de estas partes. Si lo hiciéramos así, Emacs no tendría forma de saber dónde buscar la DTD. He aquí lo que yo hago para solucionar este problema:

  1. Ir al documento principal, (aquel que tiene la declaración DOCTYPE) e ir al menú DTD -> Save Parsed DTD. Dar aquí un nombre simple como docbook.ced o main.ced. Sería bueno almacenar este archivo en el mismo directorio en el que almacenamos nuestro documento principal.

  2. Al abrir la parte del documento, obtendremos el error External entity XXXXXX not found, donde XXXXXX es el nombre de la primera etiqueta que se encontró. Ignórese esto y presiónese C-x 1 para maximizar el cuadro en el que trabajaremos. Selecciónese el menú DTD->Load Parsed DTD y sustitúyase filename.ced por main.ced (o por el nombre que le hallamos dado al archivo en 1).

Y ¡eso es todo! Ahora podremos trabajar con dicha parte del documento en Emacs de igual forma que como lo veníamos haciendo con nuestro documento principal.

5.3. Manteniendo nuestros documentos bonitos

En esta sección se hablará sobre el correcto sangrado y justificación de nuestros Docbook. Para esto usaremos algunos modos principales de Emacs y el propio modo principal PSGML.

5.3.1. La Tecla Tab

A diferencia de cualquier otro editor que yo haya visto antes, la tecla Tab se comporta de un modo sorprendentemente inteligente en Emacs. Por ejemplo, si nos encontramos en un modo principal distinto al modo de texto puro, al presionar la tecla Tab en cualquier parte del documento, esto hará que la línea en la cual estamos posicionados sangre correctamente, mientras que en cualquier otro editor de textos lo anterior quebrará la línea en dos.

5.3.2. Sangrar una región

Como modo de ejemplo, supóngase que en Ejemplo 1 hemos decidido que nuestra Sect2 sea ahora una Sect1 y queremos hacerla sangrar apropiadamente. He aquí como hacer tal cosa:

  1. Selecciónese la región (C-space activa el bloque de la selección) y reemplácense las etiquetas. Si estamos sangrando para afuera una región deberíamos empezar a buscar y reemplazar empezando por las etiquetas exteriores. Si, por el contrario, estamos sangrando hacia adentro, deberíamos hacer lo contrario.

  2. Una vez que las etiquetas tengan los nombres correctos, Emacs debería ser capaz de realizar el sangrado de la región automáticamente. Para ello, simplemente selecciónese la región nuevamente y presiónese M-x indent-region y Voilà!

5.3.3. Otros detalles sobre el sangrado

En esta sección se discutirán aspectos que involucran cuestiones de estilo y claridad en el código. Personalmente, en algunos casos prefiero que las líneas de CDATA (los caracteres de datos) estén entre las líneas que ocupan las etiquetas, y no que estas últimas estén al principio y al final de CDATA, en las mismas líneas. Los párrafos son ejemplos perfectos de esto:

<para>
  En esta sección se discutirán aspectos que involucran
  cuestiones de estilo y claridad en el código. Personalmente,
  en algunos casos prefiero que las líneas de
  CDATA (los caracteres de datos) estén
  entre las líneas que ocupan las etiquetas, y no que estas
  últimas estén al principio y al final de CDATA, en las
  mismas líneas. Los párrafos son ejemplos perfectos de esto:
</para>	

versus

<para>En esta sección se discutirán aspectos que involucran
cuestiones de estilo y claridad en el código. Personalmente,
en algunos casos prefiero que las líneas de
CDATA (los caracteres de datos) estén
entre las líneas que ocupan las etiquetas, y no que estas
últimas estén al principio y al final de CDATA, en las
mismas líneas. Los párrafos son ejemplos perfectos de
esto. </para>

Téngase presente que para el sangrado de una región, Emacs seguirá el sangrado de la primera línea y a partir de este, alineará todas las demás. Luego, deberemos tener correctamente hecho el sangrado de las líneas superiores para que en las líneas inferiores sea correcto.

5.4. Ortografía

Dado que Emacs se integra pacíficamente con el sistema operativo y sus herramientas, también lo hace con Ispell y spell. Esta integración puede ser ad-hoc activando el modo principal Ispell o puede ser ejecutado en un modo secundario. Esta última manera de funcionar es análoga al subrayado rojo que se presenta en las faltas ortográficas de los documentos en Ms Word. He aquí algunas pistas:

5.5. Formatos y Gráficos

Si bien los documentos SGML pueden ser limpiamente convertidos a otros muchos formatos, hay un par de consideraciones que hacer si vamos a convertir documentos SGML que involucren algún otro tipo de dato que no sea texto. Para explicar esto, supongamos que estamos manteniendo un documento SGML el cual será distribuido en dos formatos básicos: PostScript y HTML. Si el documento no tiene gráficos no habrá problemas serios al realizar las conversiones. Sin embargo, si los tiene hay que tener en cuenta dos características de los mismos: su tamaño y su formato. En primer lugar tomemos como ejemplo una captura de pantalla de 800x600: la misma podrá mostrarse sin problemas en un archivo HTML, pero no entrará en una hoja A4 en un archivo PS o PDF. El problema con los formatos es un poco más complicado. Por ejemplo, debemos tener en cuenta que en un archivo HTML no podremos mostrar un imagen EPS directamente, así como también, en un archivo PostScript no podremos mostrar una imagen PNG.

Probablemente haya una manera de corregir esta clase de limitaciones en los documentos SGML que involucren algún tipo de programa preprocesador, o algo parecido. Sin embargo no estoy enterado de la existencia de algo parecido. Cuando encuentre la herramienta apropiada, probablemente actualice esta sección del documento. Así y todo, he encontrado un procedimiento simple que simplifica la solución de este problema de formatos:

5.6. Referencias Cruzadas, Enlaces y URLs

Cada elemento SGML puede tener un ID[2] definido por el usuario. Este ID nos permite hacer referencia al elemento con diferentes propósitos y obtener una salida más coqueta en algunos tipos de archivo que soporten ciertas características. Un ejemplo de esto último puede ser el siguiente. Si estamos publicando nuestros documentos en archivos HTML u otro tipo de archivos que soporten hiperenlaces, puede ser últil publicar enlaces dentro del documento que apunten a otras partes del mismo. Estos enlaces pueden ser declarados de diferentes maneras en los documentos Docbook y en esta sección se darán algunas características que he encontrado dignas de relatar.

5.6.1. XRef

He encontrado a XRef muy versátil dado que trabaja de igual forma en publicaciones para la impresión (PostScript) como en publicaciones HTML. La única diferencia es que en este último formato agrega el hipervínculo.

Para usar XRef se debe, primero que nada, identificar el nodo objetivo del vínculo (o sea, aquella cosa a la cual vamos a apuntar). Para esto, simplemente deberemos ir a la etiqueta de apertura del elemento que queremos identificar, teclear C-c + y seleccionar ID. Luego deberemos introducir el nombre:

<sect1 id="lfpt">
   <title>La Fantasía de los Procesadores de Texto</title>

A partir de ahora, en cualquier lugar podremos hacer referencia a la sección del ejemplo anterior, utilizando su ID de la forma:

los cuales fueron listados en <xref linkend="lfpt">

5.6.2. URL

Para declarar una URL el procedimiento es bastante trivial. Simplemente debe usarse el elemento ULink de modo análogo a como se hace en el siguiente ejemplo:

<para>
   <ulink url="http://xml.coverpages.org/general.html#faq">
      http://xml.coverpages.org/general.html#faq
  </ulink>
</para>

5.7. Otros trucos bonitos

Aquí cubriré otras características bonitas que he descubierto gracias al uso de Emacs y el módulo PSGML. Esta sección crecerá con el tiempo, por lo que el lector debería mantenerse en línea....

5.7.1. Etiquetado no planeado

No he podido encontrar un mejor título para esta sección por lo que los lectores tendrán que soportar éste. Supóngase que se está realizando la corrección de un documento ya terminado y se decide enfatizar palabras que no lo están. Si se usa C-c C-e se terminará con una etiqueta de apertura seguida de una etiqueta de fin pero con nada en el medio. Sin lugar a dudas, esto no es lo que queremos. En este caso se podrá usar C-< lo cual nos dejará elegir una etiqueta, pero sólo insertará la de apertura. Cuando se quiera cerrar dicho elemento, se podrá presionar C-/ ¡lo cual insertará automáticamente en ese lugar la etiqueta de fin!

5.7.2. Parámetros de las Etiquetas

Cuando escribimos en Docbook o en HTML, podemos ver que las etiquetas aceptan gran variedad de parámetros diferentes, los cuales pueden ser muy difíciles de recordar de memoria, o hasta pueden tener valores por defecto. En estos casos, lo que puede hacerse es, ubicando el cursor en cualquier parte de una etiqueta de abertura, presionar C-c +. Esto hará que se abra una lista de parámetros válidos en dicha etiqueta y hasta se podrán ver los valores permitidos para cada uno de estos parámetros, si es que han sido definidos. Encuentro esta característica sorprendente y esencial para cualquier edición que involucre etiquetas. Lo que quiero decir, es que ya no necesitaremos tener al lado alguna referencia al lenguaje HTML o Docbook al editar documentos en tales formatos, ya que la mayoría de la información de los parámetros de una etiqueta la podremos obtener con la órden anterior y el autocompletado. De todos modos, esto no es excusa para no aprender el lenguaje estándar de etiquetas con el cual se trabaje, pero sí sirve para no tener que acordarnos de memoria de estas características de menor importancia.

Notas

[1]

XCF - Formato Nativo de Gimp.

[2]

que vendría a ser como un acrónimo de IDentificador.