2.2. Haciendo un documento pequeño

Para comenzar a escribir un documento necesitará abrir una sesión de emacs, para ello desde la línea de comandos del shell, ejecute emacs hola.sgml&, en mi computador esto luce de la siguiente forma:

[irving@abadon e1]$ emacs hola.sgml &

Una vez hecho esto obtendrá una pantalla como la siguiente, observe que aparecen algunos menus como SGML, DTD, Markup y otros. En caso de no ser así, revise la instalación de su sistema.

Una vez en el editor, debe comenzar escribiendo la línea que describe que el documento SGML que usted escribirá es de tipo DocBook, para ello solo escriba las líneas <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">[1], una manera más automática de hacer esto, aprovechando la configuración del archivo .emacs es mediante los menus DTD->Insert DTD->DocBook 4.1.

En emacs es usual que cualquier conjunto de comandos que usted pueda realizar mediante menus los pueda realizar también usando un conjunto de comandos desde el teclado, esto permite que cuando un comando es usado muy frecuentemente se pueda realizar de forma más rápida usando un atajo (shortcut) apropiado. En este caso el atajo correspondiente será C-c-C-u-C-d

Importante

Cuando escribamos por ejemplo C-c queremos decir que presione Control y al mismo tiempo C. Cuando escribamos por ejemplo M-x, queremos decir que presione la tecla Alt y al mismo tiempo la tecla x. En algunas ocasiones escribiremos M-C-x, lo cual quiere decir presionar al tiempo las teclas Control,Alt y X.

Después de esta secuencia de teclas es necesario que escriba DocBook 4.1 y luego ENTER. Cuando nos encontremos en situaciones como éstas, en las que una misma acción se puede realizar mediante una escogencia en el menú y un atajo en el teclado lo escribiremos usando una abreviación como la siguiente DTD->Insert DTD (C-c-C-u-C-d)

Sugerencia

Para evitar equivocarse escribiendo las palabras Docbook 4.1 usted puede usar una característica muy útil de emacs que es la autocompletación. Esta consiste en que haciendo uso de la tecla TAB se pueden ir presentando las opciones válidas hasta el momento. Es así como si en el anterior caso hubiera digitado TAB después de haber hecho C-c-C-u-C-d se le hubieran presentado las opciones posibles que eran HTML 4 y DocBook 4.1 escribiendo D TAB la única opción posible será entonces DocBook 4.1, restando solo escribir Enter

A continuación es necesario cargar la sintaxis de DocBook, para que el editor muestre en diferente fuente aquellas partes del documento que son marquillas (o tags). Esto lo puede hacer mediante DTD->Parse DTD (C-c C-p), una vez hecho esto emacs comenzará a cargar la información de sintaxis de DocBook y posteriormente se obtendrá un color distinto (usualmente púrpura) en el encabezado que usted acabó de imprimir como lo muestra la siguiente pantalla

Sugerencia

En caso de que emacs presente un error significa que la versión 4.1 no se encuentra correctamente instalada, use un número de versión más baja (3.1 por ejemplo) o instale la última versión.

En una línea aparte es necesario colocar la primer marquilla del documento que es la que corresponde a libro (book), la primer forma consiste en escribir <book>, usando el teclado. Una forma mucho más eficiente de introducir marquillas es usando C-c-C-e , a continuación aparecerá un mensaje en el buffer de emacs con el mensaje Element: book, indicando que la única marquilla disponible es ésta, posteriormente pulse Enter, creándose las marquillas de inicio y cerrado de un libro (book y /book respectivamente)

Una forma alternativa de elegir que marquilla insertar se puede hacer mediante Markup->Insert Element (Shift+Botón Derecho), y luego señalar la marquilla a utilizar, que en este caso es book

Como nuestro primer ejemplo estará escrito en castellano, es necesario indicar el idioma a que vamos a usar, para ello necesitamos editar uno de los atributos de la marquilla <book>; através de menúes esto se puede hacer con Markup->Insert Attribute (Botón Derecho). A continuación se presentarán los diferentes atributos de dicha marquilla, es necesario entonces seleccionar LANG->Set Attribute, a continuación en el buffer aparecerá Value for LANG(CDATA): , por lo que habrá que escribir es. Tendremos entonces que nuestro editor lucirá de la siguiente forma

Si uno sólo quiere utilizar el teclado para introducir dicho atributo puede usar C-c +, con lo que el editor le responderá Attribute name (que en este caso es lang) y luego le preguntará Value for LANG in BOOK (CDATA) (que en este caso es es). Recuerde que cuando se le solicita el nombre del atributo, usted puede usar autocompletación, esto hará que su labor sea más efectiva y menos susceptible de errores

Ahora introduciremos un capítulo, usando C-c C-e seguido de Chapter, una vez hecho esto se escribirá el título del capítulo que será Hola, tenemos entonces que el editor luce de la siguiente forma:

Los comentarios en DocBook se comienzan y terminan usando los símbolos <!-- y -->, es de notar entonces que lo que aparece en letra roja es un comentario insertado automáticamente por el modo PSGML que indica cuáles marquillas están disponibles a continuación. Una manera alternativa de conocer cuáles son las marquillas disponibles es usar C-c C-t. Si desea borrar los comentarios recién insertados, muévase al inicio de la línea donde está ubicado el comentario (Aquí puede ser útil C-a, que mueve al inicio de una línea) y luego pulse C-k (que se encarga de borrar la línea)

Sugerencia

En caso de que desee desactivar la característica de inserción automática de comentarios con marquillas disponibles , esto se puede hacer con SGML+User Options->Insert Missing Element o incluyendo la siguiente línea en el archivo .emacs, (setq sgml-insert-missing-element-comment nil).

Lo que haremos a continuación es escribir un párrafo con la introducción del capítulo. Una aclaración importante es que todo párrafo en DocBook debe ubicarse dentro de las marquillas para y /para. Dicha marquilla puede introducirse en emacs cómo lo hemos mostrado en el caso de la marquilla book o chapter , pero debido a que es de tan frecuente uso, la introdujimos en nuestro archivo .emacs y solo basta usar C-c p. Una vez hecho esto introduciremos el párrafo Esto es la introducción

Nuestra idea es crear un pequeño libro con dos capítulos y varias secciones, subsecciones, párrafos entre ellos; para introducir una sección dentro de un capítulo la marquilla de utilidad será sect1, en caso de querer hacer una subsección dentro de ésta basta usar sect2 y así sucesivamente.

Para introducir comentarios, la configuración local nos permite hacerlo a través de C-c o. Con esto en mente vemos que és facil escribir el siguiente código final de nuestro primer ejemplo

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<book lang="es">
  <chapter>
    <title>Hola</title>
    <para>Esta es la introducción</para>
    <!-- Un primer comentario -->
    <sect1>
      <title>Sección Única</title>
      <para>Y hasta dice algo</para>
      <sect2>
	<title>Primera subsección</title>
	<para>Nada de que hablar</para>
      </sect2>
      <sect2>
	<title>Segunda subsección</title>
	<para>Nada que decir</para>
      </sect2>
    </sect1>
  </chapter>
  <chapter>
    <title>Mundo</title>
    <para>Esta es otra introducción</para>
    <sect1>
      <!-- Un comentario en la primera sección, del segundo capítulo -->
      <title>Primer título</title>
      <para>Algo que decir</para>
    </sect1>
    <sect1>
      <title>Segundo título</title>
      <para>Más que decir</para>
    </sect1>
  </chapter>
</book>

o gráficamente,

De vez en cuando es útil saber dentro de que marquilla se encuentra el cursor ubicado, para ello basta usar SGML->List Valid Tags (C-c C-t). Por último en caso de que necesite saber los diversos comandos que usted puede usar en el modo PSGML de emacs basta que use C-c C-h, o visite una Guía de Referencia Rápida de EMACS PSGML

Notas

[1]

En la fecha en que este documento escrito, la versión estable de DocBook era la 4.1, por ende esta será nuestra referencia