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 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.

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.

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

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.

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" ).

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.

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.

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: &gt;, &lt;, &amp; y &quot;. 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.

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.

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.

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" .

22 de noviembre de 2000

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