Cómo escribir documentación para eldemonio.org

El proyecto eldemonio.org pretende, entre otras cosas, crear documentación variada en castellano sobre los sistemas operativos BSD. Este texto pretende explicar cómo crear dichos documentos para este proyecto, de manera que posean un aspecto homogéneo y una estructura similar.

Para ello usaremos el estándar XHTML 1.0 para escribir nuestros documentos y los enlazaremos a una hoja de estilo CSS que les dará el aspecto propio de eldemonio.org

Características fundamentales de XHTML

XHTML es un lenguaje mucho más estricto que HTML. La idea inicial de HTML fue definir la estructura de un documento, sin importar su apariéncia, pero actualmente esta aproximación ya no es aplicable. Gran cantidad de creadores de páginas usan HTML incorrectamente para dotarlas de un aspecto visual espectacular.

Website templates are pre-designed websites all you need to do is add your own personal content and you're ready to jump start your own website. Website templates by Vooweb

XHTML se ha diseñado para solventar estos problemas, permitiendo solo definir la estructura del documento, dejano el aspecto a cargo de la hoja de estilo. Las páginas escritas en XHTML pueden verse en gran variedad de navegadores, desde Links hasta Mozilla, pasando por terminales WAP, siendo las páginas perfectamente legibles en todos ellos. Esto es debido a que cada navegador interpretará las características del CSS que sea capaz, dejando a las otras sin alterar.

Ya que XHTML es estricto, debemos seguir unas normas mas formales que en HTML para la creación de documentos. Todo documento XHTML tiene que empezar con el siguiente código:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" lang="es" xml:lang="es">

El atributo lang es opcional, pero lo usaremos en eldemonio.org para indicar el castellano.

Aparte de esto hay que destacar dos cosas mas: los tags y los atributos en HTML tienen que ir siempre en minúsculas; por otro lado, los valores de los atributos tienen que ir siempre entre comillas dobles.

Como podéis ver en la definición de DOCTYPE usamos XHTML Transitional. Bien, esto es debido a que si usásemos Strict la creación de determinados documentos se volveria muy compleja y necesitariamos hojas de estilo inmensas. Así pues, será aceptable definir atributos de aspecto dentro de las tablas, por ejemplo, cosa que es muy dificil de controlar en CSS.

Otra característica de XHTML es que todo elemento debe tener su cierre correspondiente. Si un elemento, por ejemplo hr, no requería cierre en HTML, en XHTML debe ponerse. Pueden usarse cualquiera de las dos sintáxis siguientes (aunque la primera es preferible):

<hr />
<hr></hr>

Los párrafos, que en HTML se escribian de cualquier modo, en XHTML tienen que ir encerrados en el tag p obligatoriamente, así:

<p>Esto es un párrafo</p>

<p align="center">Y esto es otro con alineación al centro</p>

Como última característica importante sobre XHTML decir que no podemos incluir caracteres especiales directamente, como acentos, eñes, signos de exclamación, etc. Para ello debemos de usar las secuéncias de éscape própias de XHTML. Ejemplos: í, ñ, etc.

Estructura del documento

Todo documento posee una estructura lógica que lo divide en secciones y subapartados. Para determinar cada nivel dentro de la estructura se usan los tags de encabezamiento. Los titulos no deben realizarse con el tag font, ya que éste solo determina el aspecto de las letras. En cambio, los encabezamientos determinan el orden lógico del documento, definiendo su aspecto en el CSS.

Así pues, todo documento para eldemonio.org empezará con un encabezado de nivel 1, que indicará su titulo:

<body>
<h1>Título del documento</h1>

Solo puede aparecer un h1, pero es usual incluir varios h2, h3, h4, h5 o h6. Cabe destacar que estos encabezados deben aparecer en orden de modo que un h1 no puede incluir un h3 directamente sin pasar por un h2.

Un detalle específico de eldemonio.org es que no debemos definir ninguna sección como Introdución. La introducción en sí será el conjunto de párrafos que vayan antes del primer h2.

Plantilla del documento

La siguiente plantilla contiene la estructura mínima que deberá contener cualquier documento para eldemonio.org. Es recomendable que la uséis como base para vuestros documentos.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" lang="es" xml:lang="es">
<head>
<title>Título del documento</title>
<link rel="stylesheet" type="text/css" href="estilo.css" />
</head>

<body>
<h1>Título del documento</h1>

<p class="header">
<Autor: <a href="mailto:email@delautor">Nombre del autor</a>
<br />
Fecha: fecha
</p>

<hr />

<p>Cuerpo del documento</p>

<hr />

</body>
</html>

La línea del link rel será ajustada por eldemonio.org para coincidir con su estructura de directorios.

De esta plantilla solo deberéis modificar los campos que aparecen en negrita (los títulos, el email del autor, su nombre (o nick), la fecha y el cuerpo del documento). Todo lo otro debe quedar intacto.

Indentación

La indentación en HTML o XHTML no es algo muy cuidado. De todos modos, deberíais seguir unas pequeñas normas para hacer documentos más legibles en editores en modo texto y resoluciones de pantalla estándares (80x25 en modo texto).

Para el head y el body no es necesária ninguna indentación, ya que son bloques muy generales y no tiene sentido indentar su contenido. Así pues, todo el texto del documento empezará en la columna 0.

En otras ocasiones la indentación es recomendable, sobretodo cuando escribimos listas o tablas. En estos casos es necesario el sangrado para poder saber luego dónde estamos. Por cada nivel de indentación que uséis, usar 2 espacios. Aunque parezca poco, es suficiente para ver el nivel de sangrado actual. Además, si usamos más espacios, nos quedaremos sin columnas para escribir gran cantidad de texto, o bien, necesitaremos muchas lineas.

Por último, procura que el texto no sobrepase las 70 columnas. Esto dejará un márgen en editores en modo texto y el documento XHTML podrá ser impreso sin problemas. Si activáis el modo auto-fill-mode en Emacs, él realizará el cambio de línea automáticamente.

La hoja de estilo de eldemonio.org

Esta hoja de estilo CSS ha sido diseñada específicamente para escribir documentos técnicos. Puede ser que veáis que faltan clases para destacar tipos que necesitéis, así que si nos enviáis un email los incluiremos en cuanto podamos.

Antes de continuar, es necesario definir que son las clases. Una clase es un tipo específico de un mismo tag, que determina cómo será mostrado. Así pues podemos tener varias clases de font para mostrar rutas de archivo, controladores, elementos de menú, etc. Una clase se usa del siguiente modo:

<p>El archivo <font class="file">/etc/motd</font>
contiene información general del sistema.</p>

A continuación describiré las diferentes clases que disponen los elementos de nuestra hoja de estilo:

Clases para los párrafos

Éstas clases son válidas para los tags p.

Sin clase: Incluye todos los párrafos del texto.
header: Engloba los elementos de la cabecera, como son el autor y la fecha. Sólo debe usarse una vez.
note: Marca una anotación. Normalmente se escribirá en un párrafo independiente, después de los párrafos a los que la nota se refiere.

Clases para los tipos de letra

Éstas clases son válidas para los tags font, que deben usarse sólo dentro de los párrafos para marcar determinadas palabras.

Sin clase: Tipo de letra normal, no es necesario usarlo, ni debe usarse, nunca.
command: Marca los comandos que són ejecutables desde el shell o desde dentro de un programa. Si el comando es el nombre de un programa en sí, dependerá del contexto del texto si usamos esta clase o la clase program.
device: Marca el nombre de un controlador, del kernel generalmente.
file: Determina cualquier ruta a un archivo, o el nombre del archivo sin ruta.
filecontent: Engloba una línea de texto que puede incluirse dentro de un archivo.
flag: Determina un modificador o parámetro para un comando.
key: Marca una tecla que puede pulsarse. Normalmente la englobaremos dentro de corchetes además de aplicarle esta clase.
man: Indica una página del manual. Puede indicarse con una de las siguientes formas: man ls o ls(1). Es preferible la segunda ya que es consistente con las demás páginas de manual.
menu: Determina el nombre de un menú, uno de sus elementos o una secuéncia de elementos que debemos ir seleccionando a través de ellos para llegar a una opción determinada.
misc: Cualquier tipo que no se puede clasificar en ninguna de las otras clases. Puedes contactar con nosotros para que creemos otra clase nueva si lo crees necesario.
program: El nombre de un programa. Si en el contexto de la frase se indica como debe ejecutarse, entonces usaremos la clase command.
protocol: Marca el nombre de un protocolo, de red principalmente.
value: Marca el valor que puede tomar una variable.
var: Determina el nombre de una variable.

Clases para fragmentos "pegados"

Éstas clases son válidas para los tags pre, que deben usarse fuera de los párrafos.

No debemos usar indentación alguna al empezar a escribir texto dentro de un pre, ya que la hoja de estilo se encargará de ello.

filecontent: Indica el contenido de un archivo.
shell: Marca una série de ordenes que ejecutamos en la shell, y opcionalmente, las respuestas que obtenemos. Es conveniente indicar al inicio de cada comando el prompt del shell, sea un simple % o #.

Ejemplos

Ahora ya sabéis cómo está estructurada nuestra hoja de estilo. Sin embargo puede resultar complicado entenderla sin ver algun que otro ejemplo. Lo que incluyo a continuación es el cuerpo de un pequeño documento ilustrativo, al que falta la cabecera para ahorrar espacio (¡pero que debéis incluir!).

<h1>Documento de ejemplo</h1>

<p>Un p&aacute;rrafo de introducci&oacute;n.</p>

<h2>Primera secci&oacute;n</h2>

<p>Usar el siguiente comando para iniciar el sistema <font
class="program">X-Window</font>:</p>

<pre class="shell">
# startx
</pre>

<p>[...]</p>

<p>Proceder ahora a incluir las siguientes l&iacute;neas
en el archivo <font class="file">/etc/fstab</font>:</p>

<pre class="filecontent">
/dev/ad0s8 /usr ufs ro 2 2
/dev/ad0s9 /home ufs rw 2 2
</pre>

<h2>Notas</h2>

<p class="nota">Un p&aacute;rrafo que contendr&aacute;
una nota.</p>

Para terminar

Espero que uséis estas normas para la escritura de documentos, ya que facilitan mucho las tareas de mantenimiento más adelante y la integración en nuestro website.

Además, los estándares XHTML y CSS están soportados plenamente por el W3C. ;-)

Si queréis ver ejemplos sobre XHTML y nuestro CSS, hechad un vistazo al código de los documentos que ya tenemos, o a éste mismo.

Para cualquier duda, comentario o sugeréncia, contactar con el autor.

eldemonio.org El site BSD en Castellano Articles catalogue

Website templates are pre-designed websites all you need to do is add your own personal content and you're ready to jump start your own website. Website templates by Vooweb

eldemonio.org v 4_2