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;
 | 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:
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.
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:
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.
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:
Para revisar ortográficamente un documento, presiónese M-x ispell.
Para cambiar el diccionario presiónese M-x ispell-change-dictionary. (Pueden verse los diccionarios disponibles de Ispell en /usr/lib/ispell.
Para activar el modo secundario de Ispell, simplemente presiónese M-x flyspell-mode.
Si se tiene activado el modo secundario Ispell y se escucha un beep, esto significa que se ha cometido un error ortográfico en alguna palabra. Para corregirlo, deténgase la edición inmediatamente y presiónese M-$. De esta forma se verán algunas opciones en la parte superior de la pantalla, igual que en el modo principal de Ispell!
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:
Créese un subdirectorio llamado graphic en el cual guardaremos todas nuestras imágenes. En dicho subdirectorio, créense otros subdirectorios uno para cada tipo de formato. Por ejemplo, en mi caso, trabajo con Gimp y publico mis trabajos tanto en PostScript como en HTML por lo que tengo tres de estos subdirectorios: XCF [1], EPS y PNG.
Cuando creemos un gráfico, guardémoslo en los diferentes formatos en cada subdirectorio. Para los formatos XCF y EPS guardemos los archivos con extensión, pero guardemos los archivos PNG sin extensión.
Si en nuestro documento no especificamos el tipo de archivo, cada rutina de conversión esperará una extensión diferente para las imágenes; excepto por la conversión a HTML la cual tomará el nombre del archivo literalmente. Es por esto que en el punto anterior pedí que se guardaran los archivos PNG sin extensión. De todos modos, el explorador de páginas HTML a usar debería ser capaz de determinar el tipo de archivo. He aquí un ejemplo para insertar una captura de pantalla:
<screenshot> <screeninfo>Emacs 21 Graphical Menus in X</screeninfo> <graphic fileref="graphic/emacs-21-menu-grafico"></graphic> </screenshot>Antes de ejecutar la herramienta para la conversión de SGML a otro formato, nos debemos asegurar de tener los archivos de tipo correcto en el directorio graphic. Por ejemplo, la conversión a formato PostScript esperará que en dicho directorio halla archivos EPS. Así, no tendremos que modificar la declaración de cada etiqueta graphic para cada conversión.
Dado que nuestros archivos PNG no tienen extensión, el parámetro IMG en el archivo HTML tendrá la misma ruta y nombre de archivo que su ancestro SGML.
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.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.