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