Gentoo Logo

Guía Gentoo de GuideXML

Contenido:

1.  Fundamentos de GuideXML

Metas de GuideXML

La sintaxis de GuideXML es sencilla pero expresiva, por eso es fácil de aprender y al mismo tiempo proporciona todas las características 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 transformación de la guía a otros formatos, tales como DocBook XML/SGML y páginas web (HTML).

El objetivo es facilitar la creación y transformación de documentos guía, como este, en XML.

Otros recursos

Si planea contribuir a la documentación de Gentoo, o quiere probar la GuideXML, por favor lea nuestra guía de Trucos y Consejos, que contiene trucos y consejos para el desarrollo de documentación.

Tal le interese mirar las fuentes XML de este documento mientras lo lee.

2.  GuideXML

Estructura básica

Vamos a comenzar con el aprendizaje de la sintaxis de GuideXML. Comenzaremos con las etiquetas iniciales usadas en un documento de guía en XML:

Listado de Código 2.1: El comienzo de un documento de GuideXML

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header$ -->

<guide lang="es">
<title>Guía Gentoo de Documentación</title>

<author title="Autor">
  <mail link="nombre@gentoo.org">Su Nombre</mail>
</author>

<abstract>
Esta guía enseña cómo estructurar documentación para la web usando la
nueva sintaxis liviana GuideXML de Gentoo. Esta sintaxis constituye el
formato oficial para la documentación de Gentoo, este mismo documento
fue creado usando GuideXML. Esta guía asume un conocimiento básico de
XML y HTML.
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/3.0 -->
<license version="3.0"/>

<version>1</version>
<date>2011-11-29</date>

En las primeras líneas, encontramos la etiqueta necesaria que identifica este documento como un documento XML y especifica su DTD. La línea <!-- $Header$ --> será modificada automáticamente por el servidor CVS y sirve para llevar la cuenta de las revisiones. Le sigue una etiqueta <guide> -- el documento guía está encerrado completamente entre etiquetas <guide> y </guide>.
El atributo lang debe ser usado para especificar el código de idioma del documento. Sirve para definir el formato de la fecha y para traducir cadenas de caracteres como "Note", "Content", etc. al lenguaje especificado. La opción por defecto es inglés.

Después, hay una etiqueta <title>, usada para colocar 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 nombres de los autores están encerrados en otra etiqueta -- una etiqueta <mail>, usada para especificar una dirección email para esta persona en particular. La etiqueta <mail> es opcional y puede ser omitida, requiriéndose al menos 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 actual, y la fecha de la versión (en formato AAAA-MM-DD) respectivamente. Fechas que no sean válidas o que no estén en formato AAAA-MM-DD aparecerán textualmente en el nuevo documento.

Esto es todo en cuanto a las etiquetas que deben aparecer al comienzo del documento. 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.

Finalmente encontramos la etiqueta <license version="3.0"/>, usada para publicar el documento bajo la licencia Creative Commons - Attribution / Share Alike como se requiere en la Política de documentación. Anteriormente, se utilizaba la etiqueta <license />, la cual indicaba la utilización de la versión 2.5 de la licencia. Esta versión todavía se permite y admite.

Capítulos y secciones

Una vez que las etiquetas iniciales han sido especificadas, estamos listos 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 puede tener una o más secciones. Cada capítulo y cada sección tiene su título. Aquí hay un capítulo de ejemplo con una sola sección, consistente en un párrafo. Si agrega este XML al XML del ejemplo anterior y añade </guide> al final del fichero, tendrá un documento de guía válido (aunque mínimo):

Listado de Código 2.2: Ejemplo de guía mínima

<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, ajustamos el título del capítulo añadiendo un elemento hijo <title> al elemento <chapter>. Luego, creamos 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 dentro de poco qué etiquetas se permiten dentro de un elemento <body>.

Nota: Un elemento <guide> puede contener múltiples capítulos (elementos <chapter>), y un elemento <chapter> puede contener múltiples secciones (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>:

Listado de Código 2.3: Ejemplo de un elemento body

<p>
Esto es un párrafo. <path>/etc/passwd</path> es un fichero.
<uri>http://forums.gentoo.org</uri> es mi sitio web favorito. Escriba <c>ls</c> si lo desea. Yo <e>de veras</e> quiero irme a dormir ahora.
</p>

<pre caption="Ejemplo de código">
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>

<comment>(Así se inserta una nota dentro de un bloque de código)</comment>
</pre>

<note>
Esto es una nota.
</note>

<warn>
Esta es una advertencia.
</warn>

<impo>
Esto es importante.
</impo>

Ahora, aquí se ve cómo se queda el elemento <body> antes descrito:

Esto es un párrafo. /etc/passwd es un fichero. http://forums.gentoo.org es mi sitio web favorito. Escriba ls si lo quiere así. Yo de veras quiero irme a dormir ahora.

Listado de Código 2.4: Código de ejemplo

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í se inserta una nota dentro de un bloque de
código)

Nota: Esto es una nota.

Aviso: Esta es una advertencia.

Importante: Esto es importante.

Las etiquetas <body>

Hemos visto un montón de nuevas etiquetas en la sección anterior -- aquí está lo que necesita saber de ellas. Las etiquetas <p> (párrafo), <pre> (bloque de código), <note> (nota), <warn> (advertencia) y <impo> (importante) todas pueden contener una o más lineas de texto. Además, junto a los elementos <table> (los cuales veremos después), son las únicas etiquetas que deben aparecer inmediatamente dentro de un elemento <body>. Otra cosa -- estas etiquetas no deben ser apiladas -- en otras palabras, no deben apilarse, o sea, no ponga un elemento <note> dentro de un elemento <p>. Como puede imaginar, el elemento <pre> conserva los espacios en blanco exactamente igual, haciéndolo adecuado para ejemplos de código. Es obligatorio nombrar la etiqueta <pre> con un atributo caption:

Listado de Código 2.5: Poniendo un nombre a <pre>

<pre caption="Salida de uptime">
# <i>uptime</i>
16:50:47 up 164 days,  2:06,  5 users,  load average: 0.23, 0.20, 0.25
</pre>

Epígrafes

Delegados de los 13 estados originales formaron el Congreso Contento. Thomas Jefferson, un virgen y Benjamín Franklin fueron dos de los cantantes de la Declaración de la Independencia. Franklin descubrió la corriente eléctrica frotando dos gatos hacia atrás y declaró "Un caballo dividido entre sí mismo no puede mantenerse de pie." Franklin murió en 1790 y todavía lo está.

—Estudiante anónimo

Los epígrafes son utilizados a veces al comienzo de algunos párrafos para ilustrar lo que viene. Es solo un párrafo con un atributo by que contiene la firma.

Listado de Código 2.6: Estudiante anónimo

<p by="Estudiante anónimo">
Delegados de los 13 estados originales formaron el ...
</p>

<path>, <c>, <b>, <e>, <sub> and <sup>

Los elementos <path>, <c>, <b>, <e>, <sub> y <sup> pueden ser usados dentro de cualquier hijo de <body>, excepto dentro del elemento <pre>.

Los elementos <path> se usan para marcar texto que hace referencia a ficheros en disco -- tanto si es una ruta absoluta o relativa, o si es simplemente un nombre de fichero. 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 una orden o entrada del usuario. Piense en <c> como un medio de avisar al lector que pueden escribir algo o que realizarán en algún tipo de acción. Por ejemplo, todos las etiquetas XML 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 las órdenes que necesitan escribir. También porque los elementos <c> se diferencian del texto normal, casi no hará falta rodear la entrada del usuario con dobles comillas. Por ejemplo, no se refiera al elemento "<c>" como aparece en esta frase. Evitar el uso innecesario de dobles comillas hace que el documento sea más legible -- ¡y adorable!

Tal como probablemente ha podido adivinar, la <b> se utiliza para enfatizar con negritas.

<e> se usa para aplicar énfasis a una palabra o frase; por ejemplo: Yo realmente debería 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 darle más impacto a su prosa.

Los elementos <sub> y <sup> se utilizan para especificar subíndice y superíndices.

Ejemplos de código y codificación con colores

Para incrementar la legibilidad de ejemplos de código, se permite el uso de las siguientes etiquetas dentro de bloques <pre>:

<i>
Distingue la entrada del usuario del texto desplegado
<comment>
Comentarios relevantes a las acciones después del comentario
<Palabra-clave>
Denota una palabra-clave en el lenguaje utilizado en el ejemplo
<ident>
Usado para un identificador
<const>
Usado para una constante
<stmt>
Usado para un enunciado
<var>
Usado para una variable

Nota: Recuerde que todos los espacios en blanco, antes y después y todos los cortes de línea en bloques <pre> aparecerán tal cual en la página html.

Ejemplo de un bloque <pre> codificado con colores:

Listado de Código 2.7: My first ebuild

# Copyright 1999-2009 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $

DESCRIPTION="Exuberant ctags generates tags files for quick source navigation"
HOMEPAGE="http://ctags.sourceforge.net"
SRC_URI="mirror://sourceforge/ctags/${P}.tar.gz"

LICENSE="GPL-2"
SLOT="0"
KEYWORDS="~mips ~sparc ~x86"
IUSE=""

src_compile() {
    econf --with-posix-regex
    emake || die "emake failed"
}

src_install() {
    make DESTDIR="${D}" install || die "install failed"

    dodoc FAQ NEWS README
    dohtml EXTENDING.html ctags.html
}

<mail> and <uri>

Anteriormente echamos un vistazo a la etiqueta <mail> ; se usa para enlazar un texto con una dirección de corre electrónico, y tiene la forma <mail link="foo.bar@example.com">Mr. Foo Bar</mail>. Si desea mostrar la dirección de email, puede usar <mail>foo.bar@example.com</mail>, lo cual se vería como foo.bar@example.com.

Las formas abreviadas facilitan el uso de nombres y direcciones de correo de desarrolladores Gentoo. Ambas formas <mail>neysx</mail> y <mail link="neysx"/> aparecerán como Xavier Neys. Si desea usar un correo de un desarrollador Gentoo con un contenido distinto a su nombre completo, use la segunda forma con algún contenido. Por ejemplo, usar el primer nombre del desarrollador: <mail link="neysx">Xavier</mail> aparece como Xavier.
Esto es particularmente útil cuando quiere referirse a un desarrollador cuyo nombre contiene caracteres "extraños" que no puede escribir.

La etiqueta <uri> se usa para apuntar a ficheros/localizaciones en Internet. Tiene dos formas -- la primera puede usarse cuando se quiere tener la URI mostrada en el cuerpo del texto, como en este enlace a http://forums.gentoo.org. Para crear este enlace, escribí <uri>http://forums.gentoo.org</uri>. La forma alternativa es cuando se quiere asociar una URI con otro texto -- por ejemplo, Foros de Gentoo. Para crear este enlace, escribí <uri link="http://forums.gentoo.org"> Foros de Gentoo</uri>. No necesita escribir http://www.gentoo.org/ para enlazar otras partes del sitio Web de Gentoo. Por ejemplo, para enlazar al índice principal de la documentación simplemente sería <uri link="/doc/es/index.xml">índice principal de la documentación</uri>. Hasta puede omitir index.xml cuando apunte directamente al índice de un directorio, ejemplo: <uri link="/doc/es/">índice principal de la documentación</uri>. El dejar la barra final ahorra una petición HTTP adicional.

No debe usar una etiqueta <uri> con un atributo link que comience con mailto:. En este caso, haga uso de la etiqueta <mail>.

Por favor evite el síndrome de haga clic aquí tal como nos recomienda el W3C.

Ilustraciones

Así se inserta una imagen en un documento -- <figure link="mygfx.png" short="mi imagen" caption="mi imagen 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 una leyenda. No es demasiado difícil :) También soportamos el estilo estándar de HTML con la etiqueta <img src="foo.gif"/> para añadir imágenes sin leyendas, bordes, etc.

Tablas

GuideXML soporta una sintaxis simplificada para tablas, similar al de HTML. Para comenzar una tabla, use la etiqueta <table>. Comience una hilera con una etiqueta <tr>. Sin embargo, para los datos propios de la tabla, no soportamos el uso de la etiqueta <td> de HTML; en cambio, use <th> para la cabecera y <ti> si va a insertar un bloque de información normal. Puede usar <th> en cualquier lugar donde se pueda usar <ti> -- no hay obligación que los elementos <th> aparezcan solo en la primera hilera.

Los encabezados de tabla (<th>) y los ítems de tabla (<ti>) aceptan los atributos colspan y rowspan para que su contenido abarque columnas, hileras o ambas

Además los ítems de tabla (<ti>) pueden alinearse a la derecha, a la izquierda o centrados con el atributo align.

Este titular abarca 4 columnas
Este título abarca 6 hileras Item A1 Item A2 Item A3
Item B1 Título en bloque 2x2
Item C1
Item D1..D3
Item E1..F1 Item E2..E3
Item F2..F3

Listas

Para crear listas, ordenadas o no, simplemente use las etiquetas <ol>, <ul> y <li> al estilo XHTML. Las listas solo deben aparecer dentro de las etiquetas <body> y <li> lo cual significa que pueden hacerse listas dentro de listas. No se olvide que está escribiendo XML y que debe colocar las etiquetas de cierre, incluyendo ítems en listas, a diferencia de HTML.

También soportamos listas de definiciones (<dl>). Por favor note que ni la etiqueta de definición de término (<dt>) ni la de definición de datos (<dd>) aceptan etiquetas de otro nivel, como de párrafo o advertencia. Una lista de definición se parece a esta:

<dl>
A Definición Etiqueta de lista, contiene
<dt>
Pares de Definición Etiquetas de Términos
<dd>
y Etiquetas de Definición de Datos

La siguiente lista, copiada de w3.org muestra que una lista de definición puede contener listas ordenadas y sin orden, sin embargo, no puede contener otra lista de definición.

The ingredients:
  • 100 g flour
  • 10 g sugar
  • 1 cup water
  • 2 eggs
  • salt, pepper
The procedure:
  1. Mix dry ingredients thoroughly
  2. Pour in wet ingredients
  3. Mix for 10 minutes
  4. Bake for one hour at 300 degrees
Notes:
The recipe may be improved by adding raisins

Referencias Internas en el Documento

GuideXML hace que sea realmente sencillo referenciar a otras partes del documento con hiperenlaces. Se puede crear un enlace que apunte 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>.

Sin embargo, algunas guías cambian a menudo y al emplear este 'conteo' pueden producirse enlaces rotos. Para hacer frente a esto, se puede definir un nombre para el <capítulo>, <sección> o <tr> con el atributo id y después apuntarlo así:

Listado de Código 2.8: Utilizando el atributo id

<chapter id="foo">
<title>Esto es foo.</title>
...
<p>
Más información puede encontrarse en el <uri link="#foo">capítulo foo</uri>
</p>

Renuncias de responsabilidad y documentos obsoletos

El atributo disclaimer puede ser aplicado a guías y manuales para desplegar un aviso predefinido de renuncia de responsabilidad al comienzo del documento. Los textos de renuncia de responsabilidad disponibles son:

  • articles se utiliza para los artículos que se han vuelto a publicar
  • draft se utiliza para indicar que un documento está en fase de redacción y que no debe considerarse oficial
  • oldbook se utiliza con manuales viejos para indicar que están en desuso y que ya no son mantenidos
  • obsolete es utilizado para marcar un documento como obsoleto.

Al marcar un documento como obsoleto, tal vez desee agregar un enlace a una versión nueva. El atributo redirect hace justamente eso. El usuario puede ser redirigido automáticamente a la página nueva, pero no debe depender de este comportamiento.

Listado de Código 2.9: Ejemplo de renuncia de responsabilidad

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header$ -->

<guide disclaimer="obsolete" redirect="/doc/en/handbook/handbook-x86.xml">
<title>Gentoo x86 Installation Guide</title>

<author title="Author">
...

FAQs

Los documentos FAQ (preguntas de uso frecuente) necesitan comenzar con una lista de preguntas enlazadas a sus respuestas. Se pierde mucho tiempo creando este tipo de lista y se pueden cometer errores. Este tipo de lista puede ser creada automáticamente si usa el elemento faqindex como el primer capítulo del documento. Este elemento tiene la misma estructura que un chapter y permite un texto introductorio. Se espera que la estructura del documento se divida en capítulos (al menos uno), que contenga secciones, cada sección con una pregunta especificada en su elemento title y con la respuesta en su body. El índice aparecerá como una sección por capítulo y un enlace por pregunta.

Una mirada rápida a FAQ y sus fuentes nos proporcionará todas las explicaciones necesarias.

3.  Formato del Manual

Guide vs Book

Para documentación de alto volumen, como las Instrucciones de Instalación se necesitaba un formato más amplio. Diseñamos unas mejoras compatibles con GuideXML que nos permiten escribir documentación modular y multi-página.

Archivo principal

El primer cambio responde a la necesidad de un documento "maestro". Este documento realmente no comprende verdadero contenido, sino enlaces a los módulos individuales del documento. La sintaxis no difiere mucho de GuideXML:

Listado de Código 3.1: Ejemplo del uso de book

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE book SYSTEM "/dtd/book.dtd">
<!-- $Header$ -->

<book>
<title>Example Book Usage</title>

<author...>
  ...
</author>

<abstract>
  ...
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/3.0 -->
<license version="3.0"/>

<version>...</version>
<date>...</date>

Por los momentos no se ven diferencias sustanciales (excepto por la etiqueta <book> en vez de <guide>). En vez de comenzar con los <chapter>s (capítulos) individuales, definimos un <part>, el cual equivale a una parte separada de un libro:

Listado de Código 3.2: Definiendo una parte

<part>
<title>Part One</title>
<abstract>
  ...
</abstract>

(Definiendo varios capítulos)
</part>

Cada "part" se acompaña de un <title> y un resumen (<abstract>) que proporciona una introducción resumida a la parte.

Dentro de cada parte, definimos los capítulos individuales (<chapter>s). Cada capítulo debe ser un documento separado. Como resultado, no es de sorprenderse que podamos agregar una etiqueta especial (<include>) para permitir la inclusión del documento separado.

Listado de Código 3.3: Definiendo un capítulo

<chapter>
<title>Chapter One</title>

  <include href="path/to/chapter-one.xml"/>

</chapter>

Diseñando los capítulos individuales

El contenido de un capítulo individual se estructura de la siguiente manera:

Listado de Código 3.4: Sintaxis de un capítulo

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
<!-- $Header$ -->

<!--  The content of this document is licensed under the CC-BY-SA license -->
<!--  See http://creativecommons.org/licenses/by-sa/3.0 -->

<sections>

<abstract>
  This is a small explanation on chapter one.
</abstract>

<version>...</version>
<date>...</date>

(Defina varias <section>s <subsection>s)

</sections>

En cada capítulo se pueden definir secciones (<section>s) que equivale a un capítulo (<chapter>) en una Guía y subsecciones (<subsection>s), que equivalen a una sección (<section>) en una Guía.

Cada capítulo individual debe tener sus propios elementos para fecha y versión. La última fecha de todos los capítulos y documento maestro será desplegada cuando un usuario consult las distintas partes del libro.

4.  Características avanzadas del manual

Valores globales

A veces se repiten los mismos valores una y otra vez a través del manual. Una operación global de búsqueda y reemplazo podría pasar algo por alto o introducir cambios no deseados. Además, puede ser útil definir diferentes valores a ser usados en capítulos compartidos, dependiendo de cual manual incluya el capítulo.

Los valores globales pueden ser definidos en el archivos maestro del manual y usados en todos los capítulos incluidos.

Para definir valores globales, agregue el elemento <values> al archivo maestro del manual. Cada valor es definido con un elemento <key> cuyo atributo id identifica el valor, o sea, el nombre de la variable. El contenido de <key> corresponde a su valor.

El siguiente ejemplo define tres valores en un archivo maestro de un manual:

Listado de Código 4.1: Definir valores en un manual

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE book SYSTEM "/dtd/book.dtd">
<!-- $Header$ -->

<book>
<title>Example Book Usage</title>

<values>
 <key id="arch">x86</key>
 <key id="min-cd-name">install-x86-minimal-2007.0-r1.iso</key>
 <key id="min-cd-size">57</key>
</values>

<author...>
  ...
</author>

...

Los valores definidos pueden entonces ser usados a través del manual con el elemento <keyval id="key_id"/>. Especifique el nombre de la clave (key) en su atributo id, por lo que <keyval id="min-cd-name"/> sería reemplazado por "install-x86-minimal-2007.0-r1.iso" en el ejemplo.

Listado de Código 4.2: Usando valores definidos

<p>
The Minimal Installation CD is called <c><keyval id="min-cd-name"/></c>
and takes up only <keyval id="min-cd-size"/> MB of diskspace. You can use this
Installation CD to install Gentoo, but <e>only</e> with a working Internet
connection.
</p>

Para facilitarle la vida a nuestros traductores, use solo valores que no requieran traducción. Por ejemplo, definimos el valor de min-cd-size como 57 y no 57 MB.

Elementos condicionales

Los capítulos compartidos por varios manuales, tales como nuestro Manuales de Instalación frecuentemente tienen pequeñas diferencias, dependiendo de cuál manual los incluy. En vez de agregar contenido que sea irrelevante a algunos manuales, los autores pueden agregar una condición a los siguientes elementos: <section>, <subsection>, <body>, <note>, <impo>, <warn>, <pre>, <p>, <table>, <tr>, <ul>, <ol> y <li>.

La condición debe ser una expresión Xpath que será evaluada al transformar el XML. Si evalúa a true, este elemento es procesado, si no, es ignorado. La condición es especificada en un atributo test.

El siguiente ejemplo usa el valor arch, el cual es definido en cada archivo maestro de manual para condicionar el contenido:

Listado de Código 4.3: Usando elementos condicionales

<body test="contains('AMD64 x86',func:keyval('arch'))">

<p>
Este párrafo aplica a ambas plataformas, x86 y AMD64.
</p>

<p test="func:keyval('arch')='x86'">
Este párrafo aplica solo a la plataforma x86.
</p>

<p test="func:keyval('arch')='AMD64'">
Este párrafo aplica solo a la plataforma AMD64.
</p>

<p test="func:keyval('arch')='PPC'">
¡Este párrafo no será visto nunca!
Se ignora el cuerpo completamente debido a la primera condición.
</p>

</body>

<body test="contains('AMD64 PPC64',func:keyval('arch'))">

<p>
Este párrafo aplica a las plataformas AMD64, PPC64 y PPC porque la cadena 'AMD64 PPC64' contiene 'PPC'.
</p>

<note test="func:keyval('arch')='AMD64' or func:keyval('arch')='PPC64'">
Esta nota solo aplica a las plataformas AMD64 y PPC64.
</note>

</body>

5.  Estilo de codificación

Introducción

Puesto que toda la documentación de Gentoo es esfuerzo conjunto y probablemente varias personas cambiarán la documentación existente, es necesario un estilo de codificación. Un estilo de codificación abarca dos secciones. La primera es relativa a la codificación interna - como se sitúan las etiquetas XML. La segunda trata sobre el contenido - como no confundir al lector.

Ambas secciones se describen a continuación.

Estilo de codificación interno

Los fines de línea deben ponerse inmediatamente después de cada etiqueta GuideXML (tanto de apertura como de cierre) exceptuando: <version>, <date>, <title>, <th>, <ti>, <li>, <i>, <e>, <uri>, <path>, <b>, <c>, <comment>, <mail>.

Deben situarse líneas en blanco inmediatamente después de cada <body> (solo de apertura) y antes de cada <chapter>, <p>, <table>, <author> (conjunto), <pre>, <ul>, <ol>, <warn>, <note> e <impo> (solamente de apertura).

Los ajustes de líneas (word wrap) deben ser aplicados a los 80 caracteres, excepto dentro de <pre>. Solamente se puede desviar de esta regla cuando no hay otra opción (por ejemplo cuando una URL excede el máximo de caracteres). El editor debe entonces ajustar la línea en cuanto exista el primer espacio en blanco. Debe intentar mantenerse el contenido desplegado de los elementos <pre> dentro de 80 columnas para ayudar a los usuarios de consola.

No debemos usar sangrías, excepto con las estructuras XML cuyas etiquetas padres sean <tr> (procedente de <table>), <ul>, <ol> <dl> y <author>. Si se usan sangrados, estos obligatoriamente debe ser de dos espacios por cada paso de sangrado. Esto significa que nada de tabs ni de más (de dos) espacios. Dicho sea de paso, que las tabulaciones no están permitidas en los documentos GuideXML.

En caso de tener que ajustar las líneas con construcciones de tipo <ti>, <th>, <li> o <dd>, debe usarse el sangrado para el contenido.

Un ejemplo de sangrado sería:

Listado de Código 5.1: Ejemplo de sangrado

<table>
<tr>
  <th>Foo</th>
  <th>Bar</th>
</tr>
<tr>
  <ti>Esto es un ejemplo de sangrado.</ti>
  <ti>
    En caso de que el texto no pueda ser mostrado en los 80 caracteres de
    ancho de línea, deberá usar el sangrado si la etiqueta padre lo permite.
  </ti>
</tr>
</table>

<ul>
  <li>Primera opción</li>
  <li>Segunda opción</li>
</ul>

Los atributos no deben tener espacios entre sí, el signo "=" y el valor del atributo. Como en el ejemplo:

Listado de Código 5.2: Atributos

Incorrecto :     <pre caption = "Atributos">
Correcto:     <pre caption="Atributos">

Estilo de codificación externa

Dentro de las tablas (<table>) y los listados (<ul>, <ol>) y <dl>, no deben usarse puntos finales (".") a menos que se usen varias oraciones. En ese caso, cada oración debería acabar en un punto (u otras marcas de puntuación).

Cada oración, incluyendo aquellas dentro de tablas y listados, debe empezar por una letra mayúscula.

Listado de Código 5.3: Puntos y letras mayúsculas

<ul>
  <li>Sin punto</li>
  <li>Con punto. Varias oraciones, recuerda?</li>
</ul>

Los listados de código deben tener siempre una leyenda

Intente utilizar <uri> con el atributo link tanto como sea posible. En otras palabras, los Foros de Gentoo se prefiere en vez de http://forums.gentoo.org.

Cuando comente algo dentro de una construcción <pre>, utilice <comment> y ponga entre paréntesis el comentario o la marca de comentario para el lenguaje que se utiliza (# si es para guiones bash y muchas otras cosas, // si es código C, etc.) Además sitúe el comentario antes del tema del comentario.

Listado de Código 5.4: Ejemplo de comentario

(Sustituye "john" por tu nombre de usuario)
# id john

6.  Recursos

Comience a escribir

Esta guía ha sido diseñada especialmente para ser "clara y directa" para que los desarrolladores puedan pasar más tiempo escribiendo documentación y menos tiempo aprendiendo la sintaxis XML. Esperamos que esto permitirá a los desarrolladores que no son muy conocedores de la documentación, comenzar a escribir documentación Gentoo de gran calidad. Quizá esté interesado en nuestra página de Trucos y consejos sobre Documentación de Desarrollo. Si quiere ayudar (o tiene alguna duda sobre la guía), por favor mande un mensaje a la lista de correo gentoo-doc comentando lo que le gustaría saborear. ¡Diviértase!



Imprimir

Página actualizada 7 de octubre, 2012

Sumario: Esta guía enseña cómo estructurar documentación para la web usando la nueva sintaxis liviana Gentoo GuideXML. Esta sintaxis constituye el formato oficial para la documentación del Gentoo, este mismo documento fue creado usando GuideXML. Esta guía asume un conocimiento básico de XML y HTML.

Xavier Neys
Autor

Daniel Robbins
Autor

John P. Davis
Autor

Jorge Paulo
Editor

Sven Vermeulen
Editor

Joshua Saddler
Editor

John Christian Stoddart
Traductor

José Luis Rivero
Traductor

José María Alonso
Traductor

Donate to support our development efforts.

Copyright 2001-2014 Gentoo Foundation, Inc. Questions, Comments? Contact us.