- Requisitos
- Primeros
pasos - Creación de
artículos con LE-document - Caracteres especiales en
XML - Transformación de
xml a otros formatos - Creación de
páginas web - Compatibilidad con
DocBook - Bibliografía
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.
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.
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.
sp
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.
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.
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.
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" .
- 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
© Copyright 2001, 2002, 2003, 2004, La
Espiral,
Permitida la copia y distribución textual,
integral, siempre y cuando se mantenga este aviso.