PDF de programación - Guía de usuario de Linuxdoc-SGML

Guía de usuario de Linuxdoc-SGML

Por Matt Welsh. Puesta al día por Greg Hankins, [email protected]
Traducido por Francisco José Montilla, [email protected]

v1.5, 8 Marzo 1996

Este documento es una guía de usuario del sistema Linuxdoc-SGML, un formateador basado en SGML
que permite obtener varios tipos de formatos de salida. Se pueden producir archivos de texto plano (ASCII
e ISO-8859-1), DVI, PostScript, HTML, GNU info, LyX, y RTF a partir de un sólo fuente SGML. Esta guía
documenta el paquete Linuxdoc-SGML en su versión 1.5.

Índice General

1 Introducción

1.1 Acerca de este documento.

. . . . .

1.2

¿Por qué SGML? . . . .

. . . .

. .

1.3 Cómo funciona.

. . . . .

. .

. . . .

.

.

.

. .

.

.

.

. .

. .

.

. .

. .

. .

. .

. .

. .

.

.

. . .

. . .

.

.

.

.

.

.

. . .

. . .

. . .

.

.

.

.

.

.

. . .

. . .

. . .

.

.

.

. . .

.

. .

. .

.

. .

. .

.

. . .

.

. .

. .

.

.

.

.

. . .

. .

. .

.

.

.

.

.

.

.

.

.

.

. . .

. . .

. .

. .

. . .

. . .

.

.

.

.

. . .

. . .

.

.

.

.

.

.

.

.

.

.

.

.

. .

. .

.

.

.

.

. . .

. . .

. . .

. . .

2 Instalación.

2.1

Instalación del software .

. . . . . .

. .

. .

2.2 Formateando documentos . . . . . .

.

. .

.

.

.

2.2.1 Obteniendo texto plano como salida. .

. .

. .

.

2.2.2

Produciendo LaTeX, DVI o PostScript

.

. .

. .

2.2.3

Produciendo salida HTML .

. .

. .

2.2.4 Creando salida GNU Info .

. .

. .

2.2.5 Creando salida LyX . . . . .

2.2.6 Creando salida RTF . . . . .

.

.

. .

. .

.

.

.

.

.

.

.

.

.

.

. .

. .

. .

. .

. .

. .

. .

. .

2.2.7 Comprobando la sintaxis del SGML .

. .

. .

.

2.3 Tabla de Códigos ISO 8859-1

. . .

. .

.

. .

.

. .

. .

.

.

.

.

.

.

3 Redacción de Documentos con Linuxdoc-SGML

3.1 Conceptos Básicos

. . .

. . . . .

.

. .

. .

.

.

.

. . .

.

3.2 Caracteres Especiales . .

. . . . . .

3.3 Entornos Code y Verbatim . . . . .

.

.

. .

.

. .

. .

. .

.

. . .

3.4 Estructura Global del Documento.

3.4.1 El Preámbulo . .

. . . . .

.

.

. .

. .

. .

. .

. .

. .

.

. . .

.

. .

. .

.

. .

. .

.

. . .

.

.

. . .

.

.

. . .

.

.

. . .

.

.

. . .

.

.

.

.

.

.

. . .

.

.

.

.

. . .

. . .

. . .

.

.

.

.

. . .

.

.

.

. . .

. . .

. . .

.

.

.

.

.

. . .

.

.

.

. . .

. . .

. . .

.

.

.

.

.

.

.

.

.

.

.

.

. .

. . .

.

.

. .

. .

. .

. .

.

.

.

.

.

. . .

.

. .

. .

.

. .

. .

.

. . .

3.4.2

Párrafos y Secciones . . . .

. .

.

. .

.

. .

. .

.

.

.

. . .

.

.

. . .

3.4.3

Finalizando el documento .

3.5 Referencias Cruzadas . .

. . . . . .

.

.

. .

.

.

. .

. .

. .

. .

.

. .

. .

. . .

. .

. .

. .

.

. . .

.

.

. . .

.

.

. . .

.

.

.

3.6 Fuentes (Tipográficas)

.

. . . . . .

. .

. .

.

. . .

.

. .

. .

.

. .

. .

.

. . .

.

.

.

.

.

.

. . .

. . .

. . .

. . .

.

.

.

.

. . .

.

.

.

.

.

.

.

. . .

. . .

.

.

.

.

.

.

.

.

.

.

.

.

. . .

. .

.

.

.

.

.

.

.

.

. . .

. . .

. . .

. . .

. . .

. . .

.

.

.

.

.

. . .

. . .

.

.

.

.

.

.

.

.

.

.

.

.

.

. .

.

.

.

.

.

.

.

.

.

.

.

.

.

. . .

. . .

. . .

. . .

.

.

. .

. .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

. .

. .

. .

. .

. .

. .

.

.

.

.

2

2

3

3

4

5

5

6

6

6

7

7

7

7

7

7

8

8

9

10

10

11

11

12

12

.

.

.

.

.

.

.

.

.

.

.

.

. .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

. .

.

.

.

.

.

.

.

.

.

.

1. Introducción

3.7 Listados . . . .

. . .

. .

.

. .

. .

.

. . .

.

3.8 Más Información.

. . . .

. . .

. . .

. .

. .

.

.

. . .

. . .

.

.

. .

. .

. .

. .

.

.

. .

. .

. .

. .

.

.

.

.

.

. . .

4 Anexo a la Traducción al Castellano.

4.1 Aspectos Importantes del SGML-LaTeX en Castellano .

. .

. .

.

.

. .

. .

.

4.1.1 Tildes, Eñes, Etc.

. . . . . .

. .

. .

4.1.2 Tamaño del Papel.

. . . . .

. .

. .

.

.

. .

. .

. .

. .

. .

. .

. .

. .

.

.

. .

. .

. .

. .

.

.

. . .

. . .

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

.

. . .

. . .

. . .

.

.

.

.

.

.

.

.

.

.

.

. . .

.

.

.

.

2

13

14

15

15

15

15

15

15

.

.

.

.

.

.

.

.

.

.

.

.

.

.

. .

.

.

.

.

. .

. .

.

.

.

4.1.3 Los títulos de las Tablas de Contenidos, Bibliografía, etc. .

. .

. .

.

.

. .

. .

.

. . .

5 Anexo: El INSFLUG

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 tho-
[email protected]. 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 necesi-
ta 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. Introducción

1.2 ¿Por qué SGML?

3

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 remarca-
do. 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 princi-
pios 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 con-
tenidos 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 (foot-
note ).

Como