Creación de artículos y páginas web usando XML en Linux

22 de noviembre de 2000

Versión 0.1, 16/8/2000

Versión 0.2, 12/9/2000

Versión 0.3, 15/9/2000

Versión 0.4, 1/10/2000

Versión 1.1, 22/11/2000

Este documento es libre. Puedes copiarlo, distribuirlo y/o modificarlo bajo los términos de la Licencia GNU Para documentación Libre, versión 1.1 o cualquier versión posterior publicada por la Free Software Foundation.

Este artículo ha sido producido por La Espiral y su versión más reciente se puede encontrar en http://www.laespiral.org/

Resumen

Este artículo explica como escribir documentos y páginas para publicar en la web, usando LE-document (versión 1.1), un tipo de documento basado en la versión XML de DocBook. Usando una versión simplificada de DocBook se facilita el proceso de creación de documentos y el editor de texto puede dar mayor ayuda en la construcción de la estructura del documento. Para transformar los ficheros fuente XML para otros formatos, se muestran algunos ejemplos de páginas de estilo XSL. Los ejemplos que se dan han sido creados en un sistema Debian, pero como no se usa ningún programa específico de Debian, deberá funcionar igual en cualquier distribución de Linux, una vez sean instalados los programas necesarios.

Introducción

El sistema de creación de páginas web y manuales que se describe en este artículo ha sido creado para el proyecto La Espiral (http://laespiral.org/). Este proyecto busca impulsar el uso del software libre, y en particular de Debian GNU/Linux, por parte de usuarios de habla hispana sin conexión permanente a la Internet; este tipo de usuarios tiene como principal fuente de instalación de Linux los discos compactos que se distribuyen con revistas. Para facilitar la distribución de Debian en revistas en español, pensamos crear selecciones de software basadas en Debian y acompañadas de documentación que pueda ser distribuida libremente

Para cumplir nuestro objetivo, los documentos distribuidos por el proyecto deberán estar disponibles en versiones para imprimir con buena calidad, pero al mismo tiempo deberán existir versiones destinadas a consulta rápida en la web o en una consola. Otro requisito importante es mantener un estilo uniforme, ya que el proyecto se basa en contribuciones de muchos voluntarios.

La solución que proponemos aquí, bautizada como LE-document, emplea XML para los ficheros fuente y unas páginas de estilo XSL para producir los diferentes formatos. Esta solución presenta varias ventajas:

permite definir el documento de una forma estructurada;
facilita la producción de varios formatos diferentes (html, latex, pdf, postscript, texto en ascii);
hace posible la extracción de partes de un documento para introducirlas automáticamente en una base de datos;
permite definir un estilo uniforme para todos los artículos del proyecto, el cual puede ser modificado en cualquier momento, sin tener que modificar ninguno de los artículos (el contenido está separado del estilo);
permite la construcción de todas las páginas web del proyecto usando la misma herramienta usada para los artículos.

Un documento escrito en XML puede parecer complicado por la cantidad de etiquetas y atributos que es necesario introducir, pero con un editor de texto adecuado y un DTD (fichero que define la estructura del documento) bien diseñado, las etiquetas podrán ser introducidas fácilmente y el propio editor podrá sugerir la secuencia lógica que deben seguir las etiquetas. Antes de dar un ejemplo de como escribir un artículo, vamos a sugerir los programas que deben ser instalados para facilitar el proceso.

El DTD que usaremos es una versión simplificada de DocBook, que es el sistema preferido por muchos proyectos de documentación libre. La ventaja de usar una versión simplificada, en vez del original, reside en que el proceso de creación de un documento se facilita mucho mas, al igual que la elaboración de páginas xsl para transformar el código xml en otros formatos. Cualquier documento creado usando el sistema que se describe en este artículo puede ser usado igualmente en DocBook, bastando substituir la definición del DTD al comienzo del fichero.

Requisitos

Para facilitar la redacción de artículos usando LE-document en Debian, es aconsejable instalar los siguientes paquetes:

emacs

Combinado con un modo para edición de ficheros XML, facilita el trabajo de escribir un artículo en XML.

psgml

Modo para editar ficheros sgml/html en emacs. Las versiones mas recientes (1.2.1-8 o superior) manejan mejor el código XML.

Incluye el programa nsgmls que permite examinar la sintaxis de un fichero XML.

sablotron

Procesador de páginas XSL (lenguaje de descripción de estilo), útil para transformar la fuente xml de un artículo en html o latex, usando páginas de descripción de estilo. Se recomienda usar la versión 0.43 o superior; en versiones anteriores el resultado sale en código UFT8, siendo necesario usar um programa, por ejemplo recode, para transformarlo a código iso-latin-1. Los paquetes de sablotron y libsablot0 en woody pueden ser instalados sobre potato, y los puedes copiar de http://laespiral.org/software/.

tetex

Para producir las versiones PostScript y pdf, usaremos un fichero LaTeX generado a partir del fichero xml. En Debian será necesario instalar los paquetes tetex-base y tetex-extra. Usaremos también el paquete hyperref, que es parte de tetex-extra; sin embargo, las versiones actuales de este paquete en Debian no fucionan en español, ya que no reconocen la ñ (aparece un mensaje de error: Command texttilde unavailable in encoding OT1). Este problema solo fue corregido muy recientemente; para actualizar a la versión de hyperref que funciona en español, basta copiar los ficheros que se encuentran dentro del archivo http://laespiral.org/software/hyperref_6.70f.tgz; esto no creará ningún conflicto con el paquete tetex-extra original de Debian que ya ha sido instalado.

lynx

Para producir la versión en texto ascii de un fichero originalmente en xml, usaremos el programa lynx que leerá la versión html y la convertirá en texto.

ledoc-xml

Este es un paquete no-oficial de Debian, que puedes encontrar en http://laespiral.org/software/ (si trabajas con otra distribución diferente de Debian, deberás copiar el archivo ledoc-xml-1.1.tar.gz y seguir las instrucciones para su instalación). Este paquete contiene el fichero de definición del tipo de documento (DTD) que vamos a crear, asi como las páginas de estilo y programas para producir las versiones html y latex a partir de la fuente xml.

Primeros pasos

Para comenzar a escribir un artículo, el primer paso es crear un fichero con extensión xml y con el siguiente contenido en las dos primeras líneas:

<?xml version="1.0" encoding="ISO-8859-1" ?> <!DOCTYPE article PUBLIC "-//laespiral.org//DTD LE-document 1.1//EN" "LE-document.dtd">

La primera línea indica que lo que viene a continuación es un fichero en código xml, versión 1.0, y con caracteres del código ISO-8859-1. La segunda línea define el DTD (en este caso LE-document.dtd) y dá alguna información sobre la institución que lo ha producido, el nombre oficial que se le ha dado y el idioma en que fué escrito. Un DTD define un árbol jerarquico de elementos; dentro de la línea donde se identifica el DTD que será usado, debe identificarse también cual será el elemento principal, dentro de esa jerarquía, que será usado en el presente documento; en este caso hemos escrito article, pues iremos a escribir un artículo completo. Si fueramos a escribir únicamente una sección de un artículo, escribiríamos por ejemplo sect1, o si fueramos a crear una página para la web escribiríamos webpage.

Si se abre con emacs un fichero con extensión xml que tenga las dos líneas anteriores, el resultado será como el de la figura 1.

Fig. 1: Comienzo de un artículo usando LE-document.dtd.

La extensión xml del nombre del fichero ha hecho que emacs ejecute el modo XML de psgml, como se puede ver en el centro de la línea de estado (la línea negra en la parte inferior) y por la aparición de varios menús adicionales para trabajar con xml. El modo xml se ha encargado también de leer la línea que define el tipo de documento y ha cargado el fichero LE-document.dtd que se encuentra en el directorio de trabajo (si está en otro directorio, la línea de definición del documento debe ser modificada dando el camino completo del fichero dtd).

En la línea de estado en la figura 1 se puede ver que el fichero dtd ya ha sido leído y analizado, pues ya ha sido identificado el elemento principal del documento: "article" ; también puede ver alguna información sobre el DTD y los elementos que define, en le menú DTD que presenta psgml en emacs. Si en tu sesión de emacs no aparece esa información, por ejemplo si comenzaste a escribir las dos primeras líneas en un fichero vacío, tendrás primero que asegurarte de que estás usando modo XML, con el comando “M-x xml-mode'', y después podrás seleccionar la opción “Parse DTD'' en el menú DTD (o si prefieres puedes usar el teclado: "C-c C-p" ).

Creación de artículos con LE-document

Después de estar en modo XML y de haber seleccionado un DTD, puedes usar una opción de menú muy útil y que será la que nos permitirá escribir el documento rápidamente; se trata de la opción Insert Element, en el menú "Markup" . Esta opción nos dá una lista de los elementos que son permitidos en el punto donde se encuentra el cursor; escogiendo un elemento en la lista, son introducidas las etiquetas exigidas por ese elemento y si existe alguna información adicional obligatoria, será pedida en el mini-búfer (la última línea en la pantalla).

Otra forma rápida de introducir elementos, equivalente a la opción Insert Element, consiste en oprimir simultáneamente la tecla "Shift" y el botón derecho del ratón. Al hacer eso, aparece un cuadro con la lista de elementos válidos; por ejemplo en la figura 1 se acabó de pulsar "Shift+botón derecho" y ha aparecido una lista con un único elemento, article, que es el único elemento que se puede seleccionar inicialmente. Seleccionando este elemento, aparece toda la información que se muestra en la figura 2.

Fig. 2: La estructura mínima de un artículo en LE-document.dtd.

El contenido del fichero en la figura 2 constituye la estructura mínima que debe tener un artículo en el sistema LE-document. El cursor ha sido desplazado al primer lugar donde tendremos que comenzar a introducir texto: el título del artículo. Después de escribir el título del artículo, podemos usar la opción Next data field, en el menú Move (o con el teclado: "C-c C-d" ), para desplazarnos al próximo campo que debe ser rellenado.

Repitiendo el comando Next data field, verás que inicialmente los únicos campos que tienes para rellenar son el título del artículo, el nombre(s) y apellido(s) del autor ( "firstname" y "surname" ) y el título de la primera sección. El resto del artículo es considerado opcional en el DTD que se está usando. Para introducir otra información opcional, conviene revisar qué otros elementos y atributos opcionales existen en cada sección. Por ejemplo después del final del elemento "author" y antes de terminar "artheader" , vemos que existen otras tres posibilidades "abstract" (resumen), "date" (fecha del artículo) y "revhistory" (historia de revisiones). Y si miramos dentro de <article>, veremos que este elemento tiene dos atributos opcionales: "xreflabel" y "lang" ; conviene seleccionar el atributo "lang" , y escoger su valor "es" si el artículo va a ser escrito en español.

Algo muy importante que se debe tener en cuenta es lo siguiente: para escribir el contenido de la primera sección lo mas natural era pensar que deberíamos comenzar a escribir después de su título, pero cuando usamos "Next data field" en el título, somos desplazados hasta el final del artículo. Lo que pasa es que antes de comenzar a escribir el contenido de la sección nos falta escoger otro elemento después del título; podemos ver que la lista de posibles elementos en ese punto es la siguiente:

para

Indica un párrafo con texto. Cada párrafo en un artículo debe estar siempre entre las etiquetas <para> y </para>.

sect2

Una sección de segundo nivel, o subsección. Debemos notar que los números después de "sect" no se refieren al número que identifica la sección, sino a su nivel. Existen 5 niveles de secciones.

itemizedlist

Una lista con ítems.

orderedlist

Una lista enumerada.

variablelist

Una lista con descripciones, como la que estoy usando en este preciso momento en este artículo!

simplelist

Una tabla con una columna (en el futuro permitirá usar mas de una columna); cada columna se pone dentro de un elemento "member" . Se puede usar por ejemplo cuando necesitamos escribir varias líneas separadas sin comenzar nuevos párrafos.

figure

Una figura.

programlisting

Un listado de un programa o unos pocos comandos, como el que se usó al comienzo de esta sección.

Dentro de un párrafo y en general en cualquier punto donde se pueda escribir texto, existen otros elementos útiles, como por ejemplo <ulink> para introducir enlaces a localizadores url, <filename> para indicar el nombre de un fichero, y <command> para el nombre de un comando. Si el autor usa estos elementos, después será fácil que un programa busque el nombre de los comandos o ficheros referidos en su artículo con ventajas obvias para búsquedas de información y creación de bases de datos.

Caracteres especiales en XML

Existen 4 caracteres que bajo ninguna circunstancia se deben usar en el texto de un documento XML, pues están reservados a los comandos XML. Estos cuatro caracteres son los siguientes: >, <, & y ". Cuando sea necesario usar uno de estos caracteres, deberán ser escritos en la siguiente forma: >, <, & y ". Cuando sea necesario usar comillas, es mas aconsejable usar el elemento <quote>, ya que este será traducido correctamente a cada código que se use (html, latex, texto, etc) y podrá usar caracteres diferentes en diferentes idiomas.

Transformación de xml a otros formatos

Antes de transformar un fichero xml, conviene asegurarnos de que no tenga ningún error de sintaxis. Dentro de emacs, se usa el comando “Validate'' en el menú “SGML'' (o simplemente “C-c C-v'') y se pulsa "enter" .

El paquete ledoc-xml viene con unas páginas de estilo (XSL) que se usan por defecto para producir html o latex. Para obtener código html a partir de un fichero xml que use LE-document.dtd, se usa el comando le2html:

le2html fichero.xml > fichero.html

Si quieres usar tus propias páginas de estilo, deberás dar la opción -s al comando. Por ejemplo, el paquete ledoc-xml también trae las páginas de estilo que usamos en el proyecto La Espiral. Para producir un fichero html usando este estilo se debe dar el comando:

le2html -s laespiral.xsl fichero.xml > fichero.html

En Debian las páginas han sido instaladas en /usr/lib/sgml/stylesheet/ laespiral donde podrás copiarlas para modificarlas y crear tu propio estilo. Para producir latex, el proceso es semejante:

le2latex fichero.xml > fichero.tex

o usando el estilo de propio de La Espiral,

le2latex -s laespiral-latex.xsl fichero.xml > fichero.tex

Los ficheros LaTeX generados por este método han sido hechos de forma a que sean aceptados tanto por latex, para producir un fichero dvi usando el comando "latex fichero.tex" , o por pdflatex para producir un fichero pdf (usando el comando "pdflatex fichero.tex" ). Para pasar de dvi a formato PostScript, se usa: "dvips -o fichero.ps fichero.dvi" . Si nunca has usado LaTeX, te recomiendo que para obtener versiones ps y pdf uses el comando le2all que viene con ledoc-xml.

El comando le2all produce las versiones html, latex, ps, pdf y texto ascii; basta escribir en la línea de comandos:

le2all fichero.xml

y le2all se encargará de los detalles. Se puede usar también un estilo diferente, por ejemplo:

le2all -s laespiral.xsl fichero.xml

Pero en este caso hay que tener cuidado, pues si defines tu propio estilo, el nombre que dés con la opción s, por ejemplo "estilo.xsl" deberá ser una página para transformar en html, y deberá existir otra página para convertir en LaTeX, con nombre "estilo-latex.xsl" . Para ver un resumen del uso de estos comandos, consulta las páginas de manual de le2html, le2latex y le2all.

Creación de páginas web

El mismo método se puede usar para producir páginas web. en vez de comenzar con el elemento article, se debe comenzar en este caso con el elemento webpage (en la línea DOCTYPE al comienzo se deberá substituir article por webpage). El elemento webpage tiene casi todos los mismos sub-elementos de article, mas dos elementos adicionales: news y webmenu.

"News" se usa para producir una lista de noticias en una página web. Cada noticia va dentro de una etiqueta <newsentry>, la cual está formada por una fecha, <date>, seguida de un párrafo, <para>, con el texto de la noticia.

"Webmenu" se usa para colocar un índice al lado de varias páginas, que permita navegar mas fácilmente por entre las páginas. El paquete ledoc-xml viene acompañado por un programa LE-webmenu, que permite crear automáticamente el menú para un grupo de páginas. Consulta la página de manual de LE-webmenu.

Compatibilidad con DocBook

El elemento article de LE-document es un subconjunto de DocBook y por tanto cualquierr documento creado con ese elemento será totalmente compatible con DocBook; basta substituir la definición del DTD por la correspondiente de DocBook. La razón para crear una versión simplificada en vez de usar el DTD completo de DocBook, es que con un DTD mas simple se facilita la creación de documentos; si en cada punto del documento las posibles etiquetas que son aceptadas por el DTD son pocas, será mas fácil recordar la estructura que debe tener el documento.

El elemento webpage de LE-document es una extensión que no está presente en DocBook, y por tanto no será totalmente compatible con DocBook, debido a los dos elementos adicionales "news" y "webmenu" .

Bibliografia

Walsh, N. y L. Muellner. DocBook: The Definitive Guide, 1a edic., O'Reilly & Associates, Inc. octubre de 1999, ISBN: 156592-580-7. (disponible en http://www.docbook.org/)
http://www.xml.com/ . Allí se encuentra mucha información sobre XML y XSL.
http://www.nwalsh.com/ . Otra fuente muy buena de información.

Jaime E. Villate.

22 de noviembre de 2000

Permitida la copia y distribución textual, integral, siempre y cuando se mantenga este aviso.