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.

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.

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:

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

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):

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

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

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)

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:

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

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

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.

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

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

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

Ejemplo de un bloque <pre> codificado con colores:

# 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
}

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

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.

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.

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

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í:

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

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.

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

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.

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.

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:

<?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:

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

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

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

</chapter>

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

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

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:

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

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

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:

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

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.

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:

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

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

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.

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

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

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!