Anterior Siguiente Indice

3. Redacción de Documentos con Linuxdoc-SGML

Para la mayoría, redactar documentación empleando la Definición de Tipo de Documento es muy simple, y similar en ciertas cosas al LaTeX. No obstante, hay algunas advertencias a tener en cuenta. En esta sección, expondré en una introducción la redacción de documentación con SGML.

Ver el archivo Linuxdoc-Ejemplo.sgml para tener un ejemplo (y tutorial) de documento SGML que pueda usarse como modelo a seguir a la hora de redactar tus propios documentos. Sólo discutiré algunas de las prestaciones del SGML aquí, pero el fuente no es muy le gible como ejemplo. Mejor imprimir el fuente (así como la salida ya formateada) de Linuxdoc-Ejemplo.sgml para así tener una referencia real a la que acudir.

3.1 Conceptos Básicos

Examinando los fuentes del documento ejemplo, te percatarás de que hay una serie de ``etiquetas'' enmarcadas con paréntesis en ángulo N. del T.
Válgame la traducción ;-) creo que es más intuible y corto que poner ``símbolos de mayor/menor q ue'' (< y >). Una etiqueta especifica simplemente el comienzo y final de un elemento, siendo un elemento algo como una sección, párrafo, una frase con texto en tipografía cursiva (itálica), un ``item'' de un listado , y demás. El uso de una etiqueta es similar a los comandos de LaTeX como \item o \section{...}.

Por poner un ejemplo sencillo, para producir este texto en negrita, escribí:

Por poner un ejemplo sencillo, para producir <bf>este texto en negrita</bf>, ...

en el fuente. <bf> da comienzo a la región de texto en negrita, y </bf> la finaliza. Como alternativa, se puede emplear la forma abreviada

Por poner un ejemplo sencillo, para producir <bf/este texto en negrita/, ...

que encierra el texto en negrita entre barras. (Si el texto contenido entre las barras contiene barras también, deberás usar el método ``largo'', como es el caso de los nombres de archivo en Unix).

Hay otros aspectos que tener en cuenta respecto a caracteres especiales (esa es la razón por la que verás todas esas absurdas expresiones con simbolos de ``&'' si observas los fuentes; las describiré pronto).

En algunos casos, la etiqueta de fin para un elemento en particular es opcional. Por ejemplo, para comenzar una sección, empleas la etiqueta de <sect>; de todos modos, la etiqueta de finalización de la sección (que podría aparecer al final del cuerpo de la sección propiamente, ¡no justo tras el título de la sección!) es opcional e implícito cuando se da comienzo a otra sección de la misma ``profundidad''. En general, no debemos preocuparnos de esos detalles; basta con seguir el modelo empleado en el tutorial (Linuxdoc-Ejemplo.sgml).

3.2 Caracteres Especiales

Para obtener una lista detallada de caracteres especiales, echar un vistazo a alguno de los ficheros de reemplazamiento. Normalmente el LaTeX se quejará de la mayoría de caracteres especiales, por lo que paginando $LINUXDOCLIB/rep/latex/general sería un buen sitio donde comenzar. $LINUXDOCLIB está definido al comienzo de los scripts de conversión.

Obviamente, los paréntesis en ángulo son por sí mismos caracteres especiales en los fuentes SGML. Hay otros a los que prestar atención. Por ejemplo, digamos que quisieras teclear una expresión que contenga paréntesis en ángulo, como esta: <foo>. Para obtener el paréntesis en ángulo izquierdo (o de apertura)tendrás que emplear el elemento &lt; que es una macro que se expandirá al carácter de paréntesis en ángulo actual. Por tanto, en el fuente tecleé: 

... que contenga parentesis en angulo, como esta: <tt><foo></tt>.

Generalmente, lo que comience con un símbolo de ``&'' N. del T.
A partir de aquí me referiré a el por su denominación anglosajona, ``ampersand'' es una macro especial. Por ejemplo, existe &percnt; para obtener un %, &verbar; para |, y así. Para todos los caracteres especiales existen estas entidades precedidas por ``ampersands'' para representarlos.

Normalmente, no necesitamos emplear la macro con ampersand para obtener un carácter especial, no obstante, en algunos casos es necesario. Los más utilizados son:

3.3 Entornos Code y Verbatim

Mientras tratábamos el asunto de los caracteres especiales, debí mencionar también el ``entorno'' verbatim empleado para incluir texto literal en la salida (preservando los espacios, sangrías, y demás). El elemento verb se emplea para esto; tiene el siguiente aspecto: 

<verb>
Un poco de texto literal a incluir como ejemplo en la salida.
</verb>

El entorno verb no te permite emplear todo en su interior literalmente. Específicamente, deberás hacer lo siguiente en el interior de los entornos verb.

El entorno code es mayormente como el entorno verb, a excepción de las líneas horizontales que son añadidas al texto que enmarca, como aquí: 

He aqui un entorno code de muestra.

Deberás usar el entorno tscreen antes de cualquier entorno verb, como aquí: 

<tscreen><verb>
He aqui un poco de texto de ejemplo
</verb></tscreen>

tscreen es un entorno que únicamente sangra el texto y selecciona como fuente tipográfica por defecto tt. Esto hace que los ejemplos tengan mejor aspecto, tanto en las versiones LaTeX como ASCII. Se puede usar tscreen sin verb de todos modos, pero si se incluye algún carácter especial en el ejemplo, será necesario emplear ambos. tscreen no procesa los caracteres especiales. Ver ejemplo.sgml para los ejemplos.

El entorno quote es similar a tscreen, con la excepción de que no se selecciona como fuente tipográfica por defecto tt. Por tanto, puedes emplear quote para menciones que no requieren interacción de la computadora, como en: 

<quote>
He aqui una muestra de texto a sangrar, como en una cita.
</quote>

que generará:

He aqui una muestra de texto a sangrar, como en una cita.

3.4 Estructura Global del Documento.

Antes de meternos en profundidad con los detalles, describiré la estructura global de un documento definido por el DTD linuxdoc. Echar un vistazo a Linuxdoc-Ejemplo.sgml para ver un buen ejemplo de cómo definir un documento.

El Preámbulo

En el ``preámbulo'' del documento, se definen aspectos como la información del título, y el estilo del documento. Para un documento de tipo Howto N. del T.
COMO tendría este aspecto:

<!doctype linuxdoc system>

<article>

<title>Linux Foo-HOWTO

<author>Norbert Ebersol, <tt/norb@baz.com/

<date>v1.0, 9 March 1994

<abstract>
Este documento describe como usar las herramientas foo para frobnicar
librerias menganitas, empleando el relincador xyzzy... 
</abstract>

<toc>

Los elementos deberán ir más o menos en ese orden. La primera línea comunica al analizador SGML que emplee el DTD Linuxdoc-SGML. La etiqueta <article> fuerza al documento a seguir el estilo ``article''. El DTD QWERTZ original define ``report'' N. del T.
Informe y ``book'' N. del T.
Libro. también; no he retocado éstos para su uso con Linuxdoc-SGML.

Las etiquetas title, author, y date N. del T.
Título, Autor y Fecha, respectivamente. deberían resultar obvias. La etiqueta date incluye el número de versión y la última fecha de modificación del documento.

La etiqueta abstract define el texto que será impreso en el encabezamiento del documento, antes de la tabla de contenidos. Si no se va a incluir una tabla de contenidos (la etiqueta toc), probablemente no sea necesario un elemento abstract. Sugiero que todos los Linux HOWTOs sigan este mismo formato para el preámb ulo, para que el título, resumen, y tabla de contenidos estén todos ahí y tengan una apariencia similar.

Párrafos y Secciones

Tras el preámbulo, estamos listos para sumergirnos en el documento. Disponemos de los siguientes comandos de seccionamiento:

Éstas son a grosso modo equivalentes a sus respectivas en LaTeX section, subsection, y demás.

Tras la etiqueta sect (o sect1, sect2, etc.) vendrá el nombre de la sección. Por ejemplo, al comienzo de este documento, tras el preámbulo, viene la etiqueta: 

<sect>Introduccion

Y al comienzo de esta sección (Párrafos y Secciones), está la etiqueta:

<sect2>Parrafos y Secciones.

Tras la etiqueta de sección, se comienza el cuerpo de la sección. En cualquier caso, se debe empezar el cuerpo con una etiqueta <p>, como sigue: 

<sect>Introduccion
<p>

Esta es una guia de usuario del sistema de procesado de documentacion
linuxdoc-sgml ...

Esto es así para comunicar al analizador que se ha terminado con el título de la sección, y que estás listo para comenzar con el cuerpo. A partir de ahí, los párrafos siguientes se comienzan con una línea en blanco (tal y como se haría en TeX). Por ejemplo,

He aqui el final del primer parrafo.

Y aqui comenzamos este nuevo.

No hay razón para usar etiquetas <p> al comienzo de cada párrafo; únicamente al comienzo del primer párrafo tras un comando de seccionamiento.

Finalizando el documento

Al final del documento, se debe emplear la etiqueta:

</article>

Para comunicar al analizador que hemos finalizado con el elemento article (que engloba al documento completo en conjunto)

3.5 Referencias Cruzadas

Ahora iremos con otras prestaciones del sistema. Las referencias cruzadas son fáciles. Por ejemplo, si queremos definir una referencia cruzada a cierta sección, necesitarás etiquetar esa sección con un nombre, como sigue: 

<sect1>Introduccion<label id="sec-intro">

Ahora ya se podrá referir a esa sección en cualquier lugar del texto empleando la expresión: 

Ver seccion <ref id="sec-intro" name="Introduccion"> para una introduccion.

Esto sustituirá la etiqueta ref con el número de sección etiquetado como sec-intro. El argumento name para ref es necesario para transformaciones a groff y HTML. La definición de macro de groff que emplea Linuxdoc-SGML no soporta referencias cruzadas, y algunas veces es preferible referirse a ella por su nombre en lugar de por su número.

Por ejemplo, esta sección es la Cross-references.

Existe también un elemento url para los ``Universal Resource Locators'', o URLs, empleados en los World Wide Web. Este elemento deberá ser empleado para referirse a otros documentos, ficheros disponibles para FTP, y demás. Por ejemplo,

Puedes obtener los documentos HOWTO en
<tt><htmlurl url="http://sunsite.unc.edu/mdw/HOWTO/" 
name="The Linux HOWTO INDEX"></tt>.

El argumento url especifica el URL actual en sí mismo. Un enlace al URL en cuestión será añadido actualmente al documento HTML.

El argumento opcional name especifica el texto que será anclado al URL (para la conversión HTML) o que dará nombre como descripción del URL (para LaTeX y groff). Si no se incluye ningún parámetro name, se empleará el propio del URL.

Por ejemplo, puede obtener el paquete Linuxdoc-SGML de

ftp://sunsite.unc.edu/pub/Linux/utils/text/linuxdoc-sgml-1.5.tar.gz.

Una variante muy útil de este htmlurl, que suprime la creación de la parte correspondiente al URL excepto en HTML. Lo cual es muy útil para cosas como las direcciones e-mail personales; se puede escribir: 

<tt><htmlurl url="mailto:esr@snark.thyrsus.com"
name="esr@snark.thyrsus.com"></tt>

y obtener ``esr@snark.thyrsus.com'' en la salida a texto mejor que el repetitivo ``esr@snark.thyrsus.com <mailto:esr@snark.thyrsus.com>'' manteniendo la validez en los documentos URL y HTML.

3.6 Fuentes (Tipográficas)

En esencia, las mismas fuentes soportadas por LaTeX lo son por Linuxdoc-SGML. Nótese de todos modos, que en la conversión a texto ASCII (vía groff) se prescinde de la información relativa a fuentes. Por tanto, podrán emplearse las fuentes todo lo que se quiera, con el beneficio correspondiente en la conversión a LaTeX. Pero no basarse en las fuentes para hacer comprender algo concreto en la versión ASCII.

Particularmente, la etiqueta tt descrita anteriormente puede ser empleada para obtener una fuente de tipo ``máquina de escribir'' de anchura constante, que deberá emplearse en todas las direcciones e-mail, nombres de máquina, de fichero, etc.

Por ejemplo:

He aqui una muestra de <tt>texto tipo maquina de escribir </tt> para
ser incluida en el documento.

El equivalente:

He aqui una muestra de <tt/texto tipo maquina de escribir/ para ser
incluido en el documento.

Recuérdese que sólo se puede hacer uso de este método abreviado si el texto englobado no contiene barras.

Se pueden conseguir otras fuentes; bf para obtener negrita y em para obtener cursiva. Bastantes más tipos de fuentes son soportados también, pero no las recomiendo, porque al convertir esos documentos a otros formatos como el HTML podr ían no ser soportados. La negrita, tipo máquina de escribir, y cursiva N. del T.
Boldface, typewriter e italics en Inglés. deberían ser todas las necesarias.

3.7 Listados

Existen varios tipos de listados soportados. Son:

Cada elemento o ítem de un listado itemize o enum deberá ser marcado con una etiqueta item. Los ítems en descrip son marcados con tag.

Por ejemplo:

<itemize>
<item>He aqui un item.
<item>He aqui un segundo item.
</itemize>

Que tendrá este aspecto:

O, para un enum,

<enum>
<item>He aqui el primer item.
<item>He aqui el segundo item.
</enum>

Ya se coge la idea. Los listados pueden contener niveles también; ver el documento de ejemplo para más detalles.

Un listado descrip es ligeramente diferente, y también ligeramente más feo, pero podrías querer emplearlo en ciertas ocasiones: 

<descrip>
<tag/Gnats./ bugs raros que vuelan por el ventilador de tu disipador.
<tag/Gnus./ bugs raros que corren por tu CPU.
</descrip>

que acaban teniendo este aspecto:

Gnats.

bugs raros que vuelan por el ventilador de tu disipador.

Gnus.

bugs raros que corren por tu CPU.

3.8 Más Información.

Anterior Siguiente Indice