1. Introducción

Esta es una guía de usuario para el sistema de procesado de documentación linuxdoc-SGML, concebido para producir información relativa a LiNUX. Consiste en una Definición de Tipo de Documento SGML (DTD), junto con un juego de ``archivos de reemplazo'' que convierten el SGML a fuentes inteligibles por groff, LaTeX, HTML, GNU info, LyX, y RTF.

linuxdoc-sgml Está fuertemente basado en el paquete QWERTZ DTD de Thomas Gordon thomas.gordon@gmd.de. Lo único que he hecho han sido revisiones a sus definiciones de tipo de documento, y los archivos sustitutorios para su empleo específico con d ocumentación relativa a LiNUX.

linuxdoc-sgml no pretende ser un sistema genérico de procesado de documentación. A pesar de que puede emplearse para documentos de varias clases, lo he limitado para el uso de los escritores de LiNUX para producir HOWTOs, FAQs, y (posteriormente) para los manuales del Linux Documentation Project (LDP). No pretende ser un sistema de pr ocesado de documentación genérico; He manipulado sus posibilidades con este propósito.

Si se percibe una falta de generalidad en el sistema, se debe a esta razón. No hay nada que limite linuxdoc-SGML a la producción de documentación sobre LiNUX, pero todo lo producido con este sistem a tendrá un aspecto característico. Si se desea que la apariencia sea distinta, sugiero que se emplee un sistema más generalizado como el QWERTZ DTD, en combinación con las herramientas Linuxdoc-SGML.

Uno de los objetivos de este sistema es hacer fácil la producción de documentos en distintos formatos. Hasta ahora, la mayoría de la documentación LiNUX había sido producida a través de edición manual. Un sistema como groff puede ocuparse del formate o para una versión ASCII, pero sigue sin poder proporcionar HTML (para su uso en World Wide Web), LaTeX (para documentos impresos con calidad), o GNU info. Por este motivo, si faltan prestaciones en este sistema de las que se quisiese disfrutar, házmelo saber, por favor! La idea es que no hagan falta demasiadas triquiñuelas para producir documentos agradables en múltiples formatos.

El autor debe de tener que hacer lo mínimo posible.

1.1 Acerca de este documento.

Este documento fue escrito usando el DTD linuxdoc-sgml. Contiene más o menos todo lo que se necesita saber para escribir documentos SGML con este DTD (definición de tipo de documento). Véase Linuxdoc-Ejemplo.sgml para ver un ejemplo de documento que se puede tener como modelo a la hora de escribir los propios.

1.2 ¿Por qué SGML?

Elegí SGML para este sistema porque está concebido específicamente para su posterior transformación a otros formatos. SGML, abreviatura de Standard Generalized Markup Language, permite especificar la estructura del documento---esto es, qué tipo de cosas dan forma al documento. La estructura del documento se especifica con un DTD. linuxdoc-sgml es un DTD que especifica la estructura para los HOWTOs y otros documentos de LiNUX. QWERTZ es otro DTD; el SGML estándar proporciona DTDs para libros , artículos, y otras clases de documentación genérica.

El DTD especifica los nombres de los ``elementos'' que forman parte de un documento. Un elemento es simplemente una parte de la estructura---como una sección, subsección, un párrafo, o simplemente algo menor como texto remarcado. A diferencia del LaT eX, no obstante, estos elementos no son en modo alguno intrínsecos al SGML en sí mismo. La definición de documento linuxdoc-sgml viene a definir elementos muy similares a su equivalentes en LaTeX ---tiene secciones, subsecciones, ``entornos'' de texto y d emás---. No obstante, empleando SGML se pueden definir cualquier tipo de estructuras de documento que se quieran. En cierto modo, es similar al TeX de bajo nivel, mientras que el DTD linuxdoc-sgml se parece más al LaTeX.

No dejarse confundir por esta analogía. SGML no es un sistema de formateo de documentación. No existe un ``formateador SGML'' en sí mismo. El fuente SGML es sólo convertido a otros formatos para su procesado. Además, el SGML por sí mismo lo únic o que hace es especificar la estructura del documento. No existen dispositivos o ``macros'' intrínsecos al SGML en sí mismo. Todos estos aspectos son definidos en el DTD. No se puede hacer uso del SGML sin el DTD ---el DTD define lo que hace el SGML---

1.3 Cómo funciona.

He aquí cómo procesar un documento con SGML y cómo funciona el DTD linuxdoc-sgml. Primero, se necesita una definición de tipo de documento (DTD). Yo estoy empleando el DTD QWERTZ, que fue realizado en sus principios por un grupo de personas que neces itaban un DTD estilo LaTeX. He modificado el DTD QWERTZ obteniendo el DTD linuxdoc-sgml para nuestros propósitos. El DTD únicamente configura la estructura del documento. Una pequeña porción del mismo tiene este aspecto:

<!element article - -
        (titlepag, header?, 
         toc?, lof?, lot?, p*, sect*, 
         (appendix, sect+)?, biblio?) +(footnote)>

Esta parte configura la estructura global para un ``article'', que viene a ser un ``estilo de documento'' en LaTeX. El artículo consiste en una página de portada (titlepag), un encabezamiento opcional, (header); una tabla de contenidos opcional también, (toc), listado de figuras y de tablas opcionales (lof y lot), cualquier número de párrafos (p), y secciones principales (sect) apéndices opcionales (appendix), bibliografía (biblio) y notas al pie (footnote ).

Como puede observarse, el DTD no menciona nada acerca de cómo debería de formatearse el documento, o sobre el aspecto que debería tener. Simplemente define qué partes conforman el documento. En alguna parte del DTD, son definidas las estructuras de titlepag, header, sect, así como otros elementos.

No se precisa saber nada acerca de la sintaxis del DTD para escribir documentación. Simplemente lo presento para que así se sepa su aspecto, y lo que hace. Se necesita estar familiarizado con la estructura que defina el DTD. De no ser así, podrí a violarse la estructura a la hora de tratar de escribir un documento, y quedarse muy confundido con los mensajes de error resultantes. Describiremos en detalle la estructura de los documentos linuxdoc-sgml más tarde.

El siguiente paso es escribir el documento empleando la estructura definida por el DTD. Nuevamente, el DTD linuxdoc-sgml hace que la apariencia de los documentos sea muy similar al LaTeX ---muy simple de seguir---. En la jerga SGML, un documento esc rito empleando un DTD específico, se conoce como una instancia de ese documento.

A fin de traducir el fuente SGML a otro formato (como LaTeX o groff) para su procesado, el fuente SGML (el documento que escribiste) es analizado junto con el DTD por (lo adivinaste) el analizador SGML.

Estoy empleando el analizador sgmls de James Clark, jjc@jclark.com, quien precisamente resulta ser el creador de groff. Estamos en buenas manos. El analizador (sgmls) únicamente toma tu documento y verifica que sigue la estructura definida anteriormente en el DTD. También devuelve un formato más esplícito de tu documento, con todos las ``macros'' y demás elementos expandidos, lo cual es inteligible para sgmlasp, la siguiente fase del proceso.

sgmlsasp es el responsable de la conversión de la salida de sgmls a otro formato (como LaTeX). Lleva a cabo esta tarea usando archivos sustitutivos, que describen cómo convertir elementos del SGML original al fuente correspondiente en el formato ``destino'' (como LaTeX o groff).

Por ejemplo, parte del archivo de reemplazamiento para LaTeX tendría este aspecto:

<itemize>       +       "\\begin{itemize}      +
</itemize>      +       "\\end{itemize}        +

El cual dice que siempre que se comience un elemento itemize en el fuente SGML, deberá ser reemplazado por

\begin{itemize}

en el fuente LaTeX. (Como dije, los elementos del linuxdoc-sgml DTD son muy similares a sus equivalentes en LaTeX).

Asi que para convertir el SGML a otro formato, todo lo que se ha de hacer es escribir un archivo de reemplazamiento nuevo para ese formato que proporcione las analogías apropiadas para los elementos SGML en el nuevo formato. En la práctica, no es tan simp le ---por ejemplo, si se está intentando convertir a un formato que no está estructurado enteramente como tu DTD, van a haber problemas---. En cualquier caso, es más fácil de hacer que escribir analizadores individuales y traductores para varios tipos de formatos de salida; SGML proporciona un sistema genérico de conversión de fuentes a varios formatos.

Una vez sgmlsasp ha concluido su trabajo, se obtiene el fuente LaTeX que corresponde al documento SGML original, el cual puede ser formateado empleando LaTeX como se haría normalmente. Posteriormente daré en este documento ejemplos y mostraré los com andos empleados para llevar a cabo la traducción y formateo. Todo puede ser llevado a cabo desde la línea de comandos.

Pero primero, debo describir cómo instalar y configurar el software.

Hosting by: hurra.com
Generated: 2007-01-26 18:00:33