Guías básicas
Metas del diseno de guías XML
La sintaxis de las guías XML es sencilla pero expresiva, por eso es fácil
de aprender y al mismo tiempo proporciona todas las caracterísicas necesarias para la
creación de documentación Web. El número de etiquetas es muy pequeño -- solamente
las necesarias. Esto hace muy fácil la transformacion de la guía a otros formatos,
tales como DocBook XML/SGML y páginas web (HTML).
El fin es conseguir facilitar la creación y transformación de
documentos guía en XML.
Como transformar guías XML en HTML
Antes de echar un vistazo a la sintaxis de la guía en sí, sería de gran ayuda
conocer como la guía en XML se transforma en código HTML listo para las páginas web.
Para hacer esto, usaremos un fichero especial llamado guide-main.xsl,
y a través de una herramienta de procesado XSLT por línea de comandos
(también llamado "motor"). El fichero guide-main.xsl, describe
exactamente como se transforman los contenidos del documento original de la guía desde
XML al destino en un fichero HTML. Dos de los procesadores XSLT más populares son
sabcmd (incluido en el paquete app-text/sablottron) y
xsltproc (que se encuentra en el paquete gnome-libs/libxslt).
Por experiencia, aconsejamos xsltproc pues es un procesador XSL de calidad
superior y tiene un mayor número características.
Una vez que tenga instalado xsltproc o samcmd, estará preparado
para convertir guías de XML a HTML listas para web. Así es como funciona. Primero
se descarga la última version desde nuestro sitio Web en http://www.gentoo.org/projects/xml.html,
encontrándose el fichero
xml-guide-latest.tar.gz. Se extrae el fichero del tarball. Dentro, encontrará
un directorio gentoo-src, además de otro directorio gentoo-src/xml,
etc. Ahora, encuentre el fichero gentoo-src/xml/install.xml. (La guía
de instalación para nuevos usuarios). Este será nuestro documento fuente de la guía
XML. El modo fácil de realizar las transformaciones es cambiar el directorio actual
al directorio donde reside el fichero guide-main.xsl. Entonces,
se ejecuta xsltproc de la siguiene forma:
# cd gentoo-web/xsl
# xsltproc guide-main.xsl ../xml/install.xml > /tmp/install.html
Si todo fue bien, debería tener una version de install.xml
preparada para la web en /tmp/install.html. Para que este documento
se muestre correctamente en un navegador, debería tener una copia de algunos
ficheros de gentoo-web en /tmp, tales como
css/main-new.css y ( para asegurarse ) el directorio completo
images.
Guía de XML
Estructura básica
Ahora que sabe como transformar las guías XML, está listo para empezar a
aprender la sintaxis XML de las guías. Comenzaremos con las etiquetas iniciales
usadas en un documento de guía en XML:
<?xml version='1.0'?>
<guide>
<title>Guía de documentación de Gentoo Linux</title>
<author title="Chief Architect"><mail link="drobbins@g.o">
Daniel Robbins</mail>
</author>
<author title="Editor"><mail link="thomasfl@g.o">
Thomas Flavel</mail>
</author>
<abstract>Esta guía muestra como crear documentación web usando la nueva sintaxis XML
de las guías de Gentoo. Esta sintaxis es el formato oficial de la documentación de
Gentoo Linux, la cual ha sido creada usando la guía de XML. Esta guía asume
un conocimiento básico de trabajo sobre XML y HTML. </abstract>
<version>1.0</version>
<date>29 Mar 2001</date>
En la primera línea, se encuentra la etiqueta necesaria que identifica esto como un
documento XML. A continuación, hay una etiqueta de <guide> -- todo el documento
de la guía esta encerrado entre una pareja de etiquetas <guide> y </guide>.
Después, hay una etiqueta de <title>, usada para ajustar el título
del documento de la guía.
Luego, vienen las etiquetas <author>, que contienen información
sobre los autores del documento. Cada etiqueta <author>
permite un atributo opcional title=, usado para especificar la relación
del autor con el documento ( autor, co-autor, editor, etc.). En este ejemplo
en particular, los nombrres de los autores están encerrados en otra etiqueta --
una etiqueta <mail>, usada para especificar la dirección email
para esa persona en particular. La etiqueta <mail> es opcional
y puede ser omitida, y solamente se requiere un elemento <author>
por cada documento de guía.
Lo siguiente, llegamos a las etiquetas <abstract>,
<version> y <date>, usadas para especificar un resumen
del documento, la versión acual, y la fecha de la versión (en el formato DD MMM
YYYY) respectivamente. Esto es todo en cuanto a las etiquetas que deben
aparecer al comienzo del documento. Todas estas etiquetas, salvo <title>
y <mail>, no deberían aparecer en ningún otro lugar
que no sea inmediatamente dentro de la etiqueta <guide>, y por
consistencia, se recomienda (aunque no es obligatorio) que esas etiquetas, aparezcan
antes que el contenido del documento.
Capítulos y secciones
Una vez que las etiquetas iniciales han sido especificadas, se está listo
para empezar a añadir los elementos estructurales del documento. Los documentos
de guía están divididos en capítulos, y cada capítulo tiene una o más secciones.
Cada capítulo y cada sección tiene un título. Aquí hay un ejemplo de un capítulo
con una única sección, consistente en un párrafo. Si agrega este XML al XML
de ejemplo anterior y añade </guide>
al final del fichero, tendrá un documento de guía (mínimo):
<chapter>
<title>Este es mi capítulo</title>
<section>
<title>Esta es una sección en uno de mis capítulos</title>
<body>
<p>Esto es texto contenido en mi sección.</p>
</body>
</section>
</chapter>
Arriba, he ajustado el título del capítulo añadiendo un elemento hijo
<title> al elemento <chapter>. Luego, se crea una
sección añadiendo un elemento <section>. Si observa en el interior
del elemento <section>, verá que contiene dos elementos hijos --
un elemento <title> y otro <body>. Mientras que
el elemento <title> no es nada nuevo, el elemento <body>
sí lo es -- es el contenido de texto de esta sección. Veamos que etiquetas
están permitidas dentro de un elemento <body>.
Un elemento <guide> puede contener múltiples capítulos (elementos
<chapter>), y un elemento <chapter> puede
contener múltiples elementos <section>. Sin embargo, un elemento
<section> solo puede contener un único elemento <body>.
Un ejemplo de <body>
Ahora, es el momento de aprender a maquetar los contenidos. Aquí está el código XML
de un ejemplo de un elemento <body>:
<p>
Esto es un párrafo. <path>/etc/passwd</path> es un fichero.
<uri>http://www.gentoo.org</uri> es mi sitio web favorito.
Escriba <c>ls</c> si lo quiere así. Yo quiero <e>de veras</e>
irme a dormir ahora.
</p>
<pre>
Este es el texto de salida o código.
# <i>esto es lo que escribe el usuario</i>
Haz que el HTML/XML sea más fácil de leer usando énfasis selectivo:
<foo><i>bar</i></foo>
<codenote>Así es como se inserta una nota dentro de un bloque de código</codenote>
</pre>
<note>Esto es una nota.</note>
<warn>Esto es una advertencia.</warn>
<impo>Esto es importante.</impo>
Ahora, aquí esta como se muestra este elemento <body>:
Esto es un párrafo. /etc/passwd es un fichero.
http://www.gentoo.org es mi sitio web favorito.
Escriba ls si lo quiere asi. Yo quiero de veras irme a dormir ahora.
Este es el texto de salida o código.
# esto es lo que escribe el usuario
Haz que el HTML/XML sea más fácil de leer usando énfasis selectivo:
<foo>bar</foo>
Así es como se inserta una nota dentro de un bloque de código
Esto es una nota.
Esto es una advertencia.
Esto es importante.
Las etiquetas <body>
Hemos visto un montón de nuevas etiquetas en la sección anterior -- aquí
esta lo que necesita saber de ellas. Las etiquetas <p> (párrafo),
<pre> (bloque de código), <note> (nota),
<warn> (advertencia) y <impo> (importante) pueden
contener una o más lineas de texto. Además, y junto a los elementos
<table> (los cuales veremos posteriormente), son los únicas etiquetas
que deberían aparecer inmediatamente dentro de un elemento <body>.
Otra cosa -- estas etiquetas no deben ser apiladas -- en otras palabras,
no ponga un elemento <note> dentro de un elemento <p>.
Como puede imaginar, el elemento <pre> conserva los espacios en
blanco exactamente, haciéndolo adecuado para ejemplos de código.
<path>, <c> y <e>
Los elementos <path>, <c> y <e>
pueden ser usados dentro de cualquier hijo de <body>, excepto dentro
de los elementos <pre>.
Los elementos <path> se usan para marcar texto que se refieren
a ficheros en disco -- tanto si es una ruta absoluta o relativa, o
si es un nombre de fichero simplemente.
Este elemento generalmente se muestra con una fuente monoespaciada para diferenciarlo
del tipo estándar del párrafo.
El elemento <c> se usa para marcar un comando o entrada
del usuario. Piense en <c> como un medio de avisar al lector para
que haga algo que ellos pueden escribir o que realizarán en algún tipo de acción. Por
ejemplo, todos las etiquetas XML aquí mostradas en este documento están encerradas
entre etiquetas <c> porque representan algo que el usuario podría
escribir en algo que no es una línea de comandos. Usando elementos <c>,
ayudará a sus lectores a que identifiquen rápidamente los comandos que necesitan escribir.
También, porque los elementos <c> se diferencian del texto normal,
se usa a menudo para rodear la entrada del usuario con dobles comillas. Por
ejemplo, no se refiera al elemento "<c>" como yo lo he hecho en esta
frase. Evitar el uso innecesario de dobles comillas hace el documento más legible
-- ¡y adorable!
<e> se usa para aplicar énfasis a una palabra o frase; por ejemplo:
Yo debería de veras usar puntos y comas más a menudo. Como puede ver, este
texto se distingue del párrafo normal con el énfasis. Esto ayuda a hacer sus textos
más impactanes
<mail> y <uri>
Anteriormente echamos un vistazo a la etiqueta <mail> ; se usa
como enlace a un texto con una dirección de email, y tiene la forma
<mail link="foo@...">Mr. Foo Bar</mail>.
La etiqueta <uri> se usa para apuntar ficheros/localizaciones en
internet. Tiene dos formas -- la primera puede usarse cuando se quiere tener
la URI mostrada en el cuerpo del texto, como este enlace a
http://www.gentoo.org. Para crear este enlace, escribí
<uri>http://www.gentoo.org</uri>. La forma alternativa es
cuando se quiere asociar una URI con un texto -- por ejemplo,
el sitio web de Gentoo Linux.
Para crear este enlace, escribí <uri link="http://www.gentoo.org">el
siio web de Gentoo Linux</uri>.
Figuras
Así es como se inserta una figura en un documento -- <figure
link="mygfx.png" short="mi figura" caption="mi figura favorita de todos los tiempos"
/>. El atributo link= apunta a la imagen, el atributo short=
especifica una descripción corta ( actualmente usada para el atributo alt=
de HTML), y un título. No es demasiado difícil :) También se da soporte al
estilo estándar de HTML con la etiqueta <img src="foo.gif"/> para añadir
imagenes sin títulos, bordes, etc.
Tablas and listas
Las guías soportan tablas simplificadas similares a como se hace en HTML.
Para comenzar una tabla, se usa la etiqueta <table>. Se comienzan
las filas con una etiqueta <tr>. Sin embargo, para insertar datos
en la tabla, no se usa la etiqueta HTML <td> ; en vez de eso, se usa
<th> si se va a insertar una cabecera, y <ti> si se va
a insertar un bloque normal de información. Se puede usar <th> en
cualquier lugar donde se pueda usar <ti> -- no hay ninguna obligación
de que los elementos <th> aparezcan solamente en la primera columna.
Actualmente, estas etiquetas no soportan atributos, pero serán añadidos ( tales como
caption= para <table>) pronto.
Para crear listas ordenadas o no, simplemente se usa al estilo HTML las
etiquetas <ol>, <ul> y <li>. Las etiquetas
de lista deberían aparecer solamente dentro de las etiquetas <p>,
<ti>, <note>, <warn> o <impo>.
Referencias Internas del Documento
Es realmente sencillo hacer referencias a otras partes del documento
mediante el uso de los hiperenlaces. Se puede crear un enlace apuntando al
Capítulo Uno escribiendo
<uri link="#doc_chap1">Capítulo Uno</uri>. Para apuntar a
la sección dos del Capítulo Uno,
se escribe <uri link="#doc_chap1_sect2">la sección dos del
Capítulo Uno</uri>. Para hacer una referencia a la figura 3, se escribe
<uri link="doc_fig3">figura 3</uri>. O para referirse al
listado de código 2,
se escribe <uri link="doc_pre2">listado de código 2</uri>.
Se añadirán otras capacidades de auto-enlace (tales como enlaces a tablas) pronto.