DebianDOCU ~NTOS X 1Jaime E. ViliateUniversidad de Oportt.

Este artículo explica cómo escribir documentos y páginas para publicar en la web, usandoLE-document, un tipo de documento basado en la versión XIVIL de DocBook.

U sando una versión simplifica

da de DocBook se facilita eiproceso de creación de documentos, y ei editor de texto

puede dar mayor ayuda en ia construcción de la estructura dei documento. Para transformar los ficherosfuente XML para otros formatos, semuestran algunos ejemplos de páginas de estilo XSL. Los ejemplos que sedan han sido creados en un sistemaDebian, pero como no se usa ningúnprograma especifico 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áginasweb y manuales que se describe en este artículo ha sido creado para ei proyecto La Espiral (httl,://laesiiral.org).

Este proyecto busca impulsar ei usodei software libre, y en particular deDebian GNU/Linux, por parte deusuarios de habla hispana sin conexión permanente a Internet. Este tipode usuarios tiene como principal fuente de instaiación de Linux los discoscompactos que se distribuyen con revistas. Para facilitar su distribución,La Espiral va a crear selecciones desoftware basadas en Debian y acompafiadas de documentación que puedaser distribuida libremente.

Para cumplir este objetivo, los documentos distribuidos por ei proyecto deberán estar disponibles en versiones para imprimir con buenacalidad, pero ai mismo tiempo deberán existir versiones destinadas aconsulta rápida en la web. Otro re

El mismo métodusado para los

artículos sepuede usar para

producir paginas web

quisito importante es mantener unestilo uniforme, ya que ei proyectose basa en contribuciones de muchos voluntarios.

La solución que proponemos aquí,bautizada como LE-document, empleaXML para los ficheros fuente y unaspáginas de estilo XSL para producirlos diferentes formatos. Esta soluciónpresenta varias ventajas:• Permite definir ei documento de

una forma estructurada.• Facilita la producción de varios for

matos 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 uniformepara todos los artículos dei proyecto, ei cual puede ser modificado encualquier momento, sin tener quemodificar ninguno de los artículos.

• Permite ia construcción de todas iaspáginas web dei proyecto usando iamisma herramienta usada para losartículos.

~rcs~2spu..n’~: u’ ~

Buffers Files Tools Edit Search Nodif~i Nove Warkup Vise 010

Iversi encodi 1?><1 erticlo “— /Iaasplrai /010 LE-dacoaent LOIIFJr

•I.E tdtd”>

L1\ I’t~ht1.:~ ji’t~ 1)— 1——fli 1——

Comienzo de au articulo usando LE.Docunient,dtd.

~ocumiiHs X~[

El modo xml seencarga de leer

la línea que defineei tipo de

documento~

Un documento escrito en XML puede parecer complicado por ia cantidadde etiquetas y atributos que es necesano introducir, pero con un editor detexto adecuado y un DTD (fichero quedefine ia estructura dei documento)bien disefíado, las etiquetas podránser introducidas fácilmente y el propioeditor podrá sugerir la secuencia lógica que deben seguir ias etiquetas. Antes de dar un ejempio de cómo escribirun articulo, vamos a sugerir ios programas que deben ser instalados parafacilitar el proceso.

El DTD que usaremos es una versión simplificada de DocBook, que esei sistema preferido por muchos proyectos de documentación libre. Laventaja de usar una versión simplificada, en vez del original, reside en queel proceso de creación de un documento se facilita mucho más, ai igualque la eiaboración de páginas xsl paratransformar el código xml en otrosformatos. Cuaiquier documento creado usando ei sistema que se describeen este artícuio puede ser usadoigualmente en DocBook, bastandosustituir la definición del DTD al comienzo del fichero.

REQUISITOSP ara facilitar la redacción de artículos usando LE-document en Debian, es aconsejabie instaiar los siguientes paquetes:

Emacs. Combinado con un modopara edición de ficheros XML, facilita eitrabajo de escribir un artículo en XML.

Psgml. Modo para editar ficherossgml/html en emacs. Las versionesmás recientes (1.2.1-8 o superior) admiten mejor ei código XML.

Sp. Inciuye el programa nsgmlsque permite examinar ia sintaxis deun fichero XML.

Sablotron. Procesador de páginasXSL (lenguaje de descripción de estilo), útii para transformar ia fuente xmlde un artículo en html o latex, usandopáginas de descripción de estio. Se recomienda usar la versión 0.43 o superior. En versiones anteriores ei resuitado saie en código U1~T8, siendonecesario usar un programa, por ejempio Recode, para transformarlo a códigoiso-latin-1. Los paquetes de sablotron ylibsablotO en Woody pueden ser instaiados sobre Potato, y ios puede copiar dehttn://iaespirai.or~/software/.

Tetes. Para producir las versionesPostScript y pdf usaremos un ficheroLaTeX generado a partir dei ficheroxml. En Debian será necesario instaiarios paquetes tetex-base y tetex-extra.Usaremos también ei paquete hyperref que es parte de tetex-extra; sin embargo, ias versiones actuales de estepaquete en Debian no funcionan en espafiol, ya que no reconocen ia ~i (aparece un mensaje de error: Command\texttilde unavailable in encodingOTJ). Este probiema sóio fue corregido muy recientemente; para actualizarse a la versión de hyperref que funciona en espaflol, basta copiar iosficheros que se encuentran dentro deiarchivo httt,://laesiiral. or2/software/hvlerref 6. 7oftgz; esto no creará ningún conflicto con ei paquete tetex-extraoriginai de Debian que ya ha sidoinstaiado.

le-docxml. Este es un paquete nooficial de Debian, que podemos encontrar en httb://laestiral. or~/ software/

(si trabaja con otra distribución diferente de Debian, deberá copiar el archivo le-docxml-1. 0. targz y seguir iasinstrucciones para su instalación). Este paquete contiene el fichero de definición dei tipo de documento que vamos a crear, así como las páginas deestilo y programas para producir iasversiones html y latex a partir de iafuente xml.

PRI EROS PASOSP ara comenzar a escribir un artícuio, ei primer paso es crear un fichero con extensión xml con el siguientecontenido en ias dos primeras líneas:

<?xml version=”l.O” encoding=”ISO-8859-1”?><!DOCTYPE article PUBLIC ~‘-/J1aespira1.org/IDTD

LE-document 1.0//EN”

La primera linea indica que io queviene a continuación es un fichero encódigo xml, versión 1.0, y con caracteres dei código ISO-8859-1. La segundalinea define ei DTD (en este caso LEdocument.dtd) y da aiguna información sobre ia institución que io ha producido, ei nombre oficial que se ie hadado, y ei idioma en que fue escrito.Un DTD define un árboi jerárquico deelementos; dentro de ia línea donde seidentifica ei DTD que será usado, debeidentificarse también cuai será ei elemento principai, dentro de esa jerarquía, que será usado en ei presente documento. En este caso hemos escrito

xVice PTD Help

1

><

“LE-document.dtd”>

acs~sp~ ~‘ ‘t.

Buffers Files Toole Edit Search SGItL Hodifg flove I(arkup

<?xei versi 1. encedi ~“i :.~ 1 ?><1 articie ~—/,I..~.irai. /DTOLE

~LE .dtd><articie>

<artheader><titie)Wtitie><authar>

(li rstnaee></f 1 rstnaee><surnase></surnate>

</author></artheader><secti>

<ti t le></t 1 ti e></sectl>

</art 1 cl e>

artiulos—CFJHEI.x ~jrt;rte/Ii~Ie

1.0/

1) --1 6--fl II

O Esiructura nhínima de ou artículo eu LE-Duumeni.did.

Debian

article, pues vamos a escribir un artículo completo. Si fuéramos a escribirúnicamente una sección de un artículo, escribiríamos, por ejempio, secti, osi fuéramos a crear una página para laweb, escribiríamos webpage.

Si se abre con emacs un fichero conextensión xmi que tenga ias dos lineasanteriores, el resultado será como elde ia Figura 1.

La extensión xml del nombre del fichero ha hecho que emacs ejecute elmodo XML de psgmi, como se puedever en el centro de la línea de estado(la linea negra en la parte inferior) ypor la aparición de varios menús adicionales para trabajar con xmi. El modo xml se ha encargado también deleer la linea que define ei tipo de documento y ha cargado el fichero LEdocument.dtd que se encuentra en eldirectorio de trabajo (si está en otro directorio, la linea de definición del documento debe ser modificada dando elcamino completo del fichero dtd).

En la línea de estado en la Figura 1se puede ver que el fichero dtd ya hasido leído y analizado, pues ya ha sidoidentificado el elemento principal deldocumento: article. También puedever alguna información sobre el DTDy los elementos que define, en ei menúDTD que presenta psgml en emacs. Sien su sesión de emacs no aparece esainformación, por ejempio si comenzó aescribir las dos primeras lineas en unfichero vacío, tendrá primero que asegurarse que está en modo XML, con elcomando M-x xml-mode, y después p0-drá seleccionar ia opción Parse DTDen ei menú DTD (o si prefiere usar elteclado: C-c C-p).

ESCRIBIENDOCON LE-DOCUMENT

D espués de estar en modo XML y dehaber seleccionado un DTD, puedeusar una opción de menú muy útii, queserá la que nos permitirá escribir ei documento rápidamente; se trata de la opción Insert Element, en ei menú Markup. Esta opción nos da una lista de loselementos que son permitidos en elpunto donde se encuentra el cursor.Escogiendo un elemento en la lista, sonintroducidas ias etiquetas requeridaspor ese elemento, y si existe alguna in

formación adicional obligatoria, será pedida en ei mini-buffer (la úitimalinea en la pantalia).

Otra forma rápida de introducirelementos, equivalente a ia opciónInsert Element,consiste en oprimir simuitáneamente la teclaSh~ft y el botón derecho del ratón. Aihacer eso, apareceun cuadro con lalista de eiementosválidos; por ejemploen ia Figura 1 se acabó de pulsarShift+botón derecho y ha aparecido unalista con un único eiemento, article,que es ei único elemento que se puedeseleccionar inicialmente. Seleccionando este elemento, aparece toda la información que se muestra en la Figura2.

Ei contenido del fichero en la Figura 2 constituye la estructura mínimaque debe tener un artículo en ei sistema LE-article. 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 ei título del artículo, podemos usarla opción Next data field, en ei menúMove (o con ei teclado: C-c C-d), paradesplazarnos ai próximo campo quedebe ser rellenado.

Repitiendo ei comando Next datafield, verá que iniciaimente los únicoscampos que tiene para reilenar son eitítulo del artículo, el nombre y apeilidos dei autor (flrstname y surname) y eltítulo de la primera sección. El resto delartículo es considerado opcional en elDTD que se está usando. Para introducir otra información opcional, convienerevisar qué otros elementos y atributosopcionales existen en cada sección. Porejemplo después dei final dei elementoauthor y antes de terminar artheader,vemos que existen otras tres posibilidades abstract (resumen), date (fechadel artículo) y revhistory (historia derevisiones). Y si miramos dentro de<article>, veremos que este elementotiene dos atributos opcionaies: xreflabei

Es ir~1Debon. la d~otu coo la que puedes quentes nieda.

Uldeiaectua0zación 15-11-2000

y lang~ conviene seleccionar ei atributolang, y escoger su valor es si ei artículova a ser escrito en espafiol.

Algo muy importante que se debetener en cuenta es lo siguiente: paraescribir ei contenido de ia primera sección lo más natural era pensar que deberíamos comenzar a escribir despuésde su título, pero cuando usamos Nextdata field en ei título, somos despiazados hasta ei final del artículo. Lo quepasa, es que antes de comenzar a escribir el contenido de la sección nosfalta escoger otro elemento despuésdei título; podemos ver que ia lista deposibles elementos en ese punto es lasiguiente:

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 hacer notar que los nú

meros después de sect no se refieren ainúmero que identifica ia sección, sino asu nivel. Existen 5 niveles de secciones:

Objetivos

Coo eon &i. elProyecto LaEsprcl ,bsde eltasbajo eu laue lOseas de accsda

Genecacides de docimientaçeln aclare Debaesyproyectos o so5wece

Cualqutera que desce puede cctnpes~ mi ccno~e1oe coo la conurgdad.adio hene que variou pneus a megiar pesa contaibsu cones aselculo aLa£~r~~

Toda la doct~taeu6ngenueda actuei dtapeeible pesa au descarga esformatos adecuado, que pemabue au reedeado (eegdo los lésounoa de labçencma Idee ~keda es ei eseicelo) o espraiada

Co~ccadn de es CD a&torol coo softwnca no mdmd~ eis la antado establede DebaesIGNU Limiar

Página dela Espiral.

PigiuaPcindpal

Eoopo LaEspcul

CD dt La Escavi

Como CorgelOne

Serntdtr ÇVS

Contacto

Lista de Cnteto

Con un DTD biendiseíiado, las etiquetas

podrán serintroducidas

p.facilmente

hcuml~fos X~1

• itemizedlist Una lista con ítems.• Orderedlist Una lista enumerada.• Variablelist. Una lista con descrip

ciones, Icomo la que estoy usandoen este preciso momento en este artículo!

• Figure. Una figura.• Programlisting. Un listado de un

programa o unos pocos comandos,como el que se usó al comienzo deesta sección.Dentro de un párrafo, y en gene

ral, 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 uncomando. Si el autor usa estos elementos, después será fácil que unprograma busque el nombre de loscomandos o ficheros referidos en suartículo con ventajas obvias para búsquedas de información y creación debases de datos.

TRANSFORMANDOX L EN OTROS

Validate en el menú SGML (o simplemente C-c C-v) y se pulsa enter.

El paquete le-docxml viene con unaspáginas de estilo (KSL) que se usanpor defecto para producir html o latex.Para obtener código html a partir de unfichero xml que use LE-document. dtd,se usa el comando le2html:

le2html fichero.xml > fichem.html

Si quiere usar sus propias páginasde estilo, deberá dar la opción -s al comando. Por ejemplo, el paquete ledocxml también trae las páginas de estilo que usamos en el proyecto LaEspiral. Para producir un fichero htmlusando este estilo se debe dar el comando:

ie2htmi -s Iaespiral.xsi fichero.xml > fichero.html

En Debian, las páginas han sido instaladas en usr/lib/sgml/stylesheet laespiral, desde donde podrá copiarlaspara modificarlas y crear su propio estilo. Para producir latex, el proceso essemejante:

le2latex fichero.xml > fichero.tex

A ntes de transformar un ficheroxml, conviene asegurarnos de queno tenga ningún error de sintaxis.Dentro de emacs, se usa el comando

o usando el estilo de propio de LaEspiral.

le2latex -s Iaespiral-iatex.xsl fichero.xml > fichero.tex

I’~giIi~ principdl

Paquetes

@debian1 ~ ~ Sopoili Di~,drrolIJdor I~Li~tftdj

tOjo! Esta traducción está muy decactualizada, por favor, consulte el documento original.

calos a tes co Ia distribuctón estableEsta es la liberaciiSn oficial más reciente de la dsstibución Debian GNtJ!Linux~ también llamada “i&ms” (principa~Todos los paquctes en dIa son libres co ei sentido detallado en la Guia dc Debtan sobre aué es software libre, lo queasegura la libertad de uso y redistnbución, y la disponlblhdad de todo su código fluente.

Tambi~n hay alginos afladidos a la disisibución maus que sufren alguna resticcién que no les permite ser parte de unadistibuctón 100% libre con Debian GNUlLanu~ Pero aún asi. Debian los incluye como ias servicio a nuesfros usisanosEntre elios están

Co,stmáLos paquetes de este área son libres, pero dependen de pro~amas o hardware que no es libre

No?s-Frea (no libre)Los paquetcs de este área no cuestan necesariamente dinero, pero ~enen condiciones que restnngende alguna forma eu uso o redistsibución.

2~arn-US’Estos paquetes no pueden ser exportados de EEUU. y coo sobre todo paquetes que sncluyensofiware de difrado, o soflware que está afèctado por asisntos relacionados con patentes. La mayorparte de eflos son soflware libre, pero algunos no.

Informoclón sobre poquetes Debion.