Anatomía de una receta

Jaime E. Villate

22 de noviembre de 2000

Una receta debe comenzar con las líneas:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE receta PUBLIC "-//laespiral.org//DTD LE-receta 1.0//ES"
"LE-receta.dtd">

El elemento principal es "receta" que tiene un preámbulo seguido de un elemento "contenido" donde está el texto de la receta que puede estar seguido por una o varias referencias (elemento "referencia").

Preámbulo

El preámbulo comienza con tres elementos obligatorios titulo, autor y fecha; la fecha puede ser escrita en la forma "9 de noviembre de 2000" o en cualquiera de los formatos aceptados por Postgresql. A continuación pueden venir algunos de los siguientes elementos opcionales:

version:

Para mantener la historia de revisiones de una receta.

nivel:

A que tipo de usuarios se destina: basico, medio o avanzado (sin acentos).

sistema:

Sistema operativo; por ahora linux o hurd.

arquitectura:

alpha, arm, i386, m68k, mips, powerpc, sparc, sparc-64, beowulf o todas.

distribucion:

slink, hamm, potato o woody.

seccion:

La misma clasificación usada en Debian para los paquetes, pero con nombres traducidos: administracion, base, comunicaciones, desarrollo, documentacion, editores, electronica, juegos, graficos, radioaficionados, interpretes, librerias, correo, matematica, miscelanea, red, noticias, antiguedades, otros-sistemas, ciencia, shells, sonido, tex, texto, utilitarios, web, x11.

funcion:

En qué etapa es útil la receta: instalacion, configuracion, uso.

Contenido

El contenido se compone de una combinación de los siguientes elementos:

para:

Un párrafo.

items:

Una lista con items ("item").

secuencia:

Una lista en que cada "item" será numerado.

glosario:

Una lista en que cada entrada tiene un "termino" seguido de su "definición".

lista:

Es realmente una tabla, pero en este momento solo acepta una columna! cada "elemento" ocupará un renglón.

listado:

Un listado de un programa o un o varios comandos.

figura:

Como su nombre lo indica. Puede tener una "leyenda" y una "grafica".

grafica:

Una imagen que puede aparecer en un línea de un párrafo, o centrada dentro de una figura.

secc1...secc5:

secciones de nivel 1 hasta 5. Cada sección debe tener un "titulo" seguido de una o mas secciones de un nivel inferior o cualquier otro de los elemento mencionados en esta sección.

Texto

El texto de la receta será escrito dentro de párrafos (elemento "para"); los párrafos aparecen dentro del contenido de la receta, dentro de un ítem en una lista o dentro de la definición en un glosario. Dentro de un párrafo se pueden usar los siguientes elementos para enfatizar alguna parte o definir el tipo de texto:

fichero:

Cuando se hable de un fichero que sea estándar en un sistema Linux (o Hurd), se debe indicar usando este elemento. Así en un futuro será fácil descubrir que recetas tratan sobre un fichero que queremos modificar.

enfasis:

Su nombre lo dice todo.

comando:

Comandos estándar de Unix.

directorio:

Semejante a fichero.

paquete:

Siempre que se haga referencia a un paquete de Debian, se deberá usar este elemento para permitir en un futuro buscar que recetas nos dan información sobre un determinado paquete.

literal:

Algo que debe aparecer tal como está escrito.

comillas:

Debe evitarse usar "texto entre comillas", que está reservado para los atributos, y mejor usar <comillas>texto entre comillas</comillas>.

nota:

Nota de pie de página.

clave:

Palabras claves; como por ejemplo en un libro las que aparecen en el índice al final.

enlace:

Un enlace a una página Web, definida por el atributo url.

Recomendaciones finales

Cuando se escribe una receta se debe tener en cuenta lo siguiente:

  1. No usar <, >, " ni & en el texto (ni siquiera dentro de un literal o un listado), pues son caracteres especiales de XML. En su lugar se deben usar &lt;, &gt;, &quot; y &amp;.

  2. Toda receta deberá tener por lo menos una "clave". Conviene después de escribir la receta leerla con atención y poner algunos elementos <clave> con sus respectivos </clave>.

  3. Usar siempre ispell para verificar la ortografía, y quien use Emacs con el modo psgml, deberá usar C-c C-v para verificar la sintaxis.

El DTD usado para las recetas, las páginas de estilo para producir diferentes formatos y alguna documentación vienen dentro del paquete ledoc-xml que puede ser obtenido en http://laespiral.org/software. Este paquete trae el programa le2html que permite convertir una receta en código HTML por medio del comando:

le2html -s LE-receta.xsl receta.xml  > receta.html

El fichero HTML obtenido se puede transformar en un fichero de texto ASCII, usando lynx:

lynx -dump receta.html > receta.txt



Página creada en: 2004-11-04 11:40:55 +0000
© Copyright 2001, 2002, 2003, 2004, La Espiral, debian-laespiral@lists.debian.org
Permitida la copia y distribución textual, integral, siempre y cuando se mantenga este aviso.