Gu�a de usuario de Linuxdoc-SGML

Gu�a de usuario de Linuxdoc-SGML
Por Matt Welsh. Puesta al d�a por Greg Hankins, greg.hank�
[email protected]
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 for�
matos 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)

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.

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 [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 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, [email protected],
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.

2. Instalaci�n.

Hacerse con linuxdoc-sgml-1.5.tar.gz de alguno de los siguientes
servidores ftp:

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

� ftp://tsx-11.mit.edu/pub/linux/docs/linuxdoc-sgml-1.5.tar.gz

� ftp://ftp.cc.gatech.edu/pub/people/gregh/linuxdoc-sgml/linuxdoc-
sgml-1.5.tar.gz

Parches actualizados para la versi�n 1.5 pueden encontrarse en:

ftp://ftp.cc.gatech.edu/pub/people/gregh/linuxdoc-sgml.

Puede obtener informaci�n actualizada en:

Linuxdoc-SGML WWW Page.

El archivo linuxdoc-sgml-1.5.tar.gz contiene todo lo necesario para
escribir documentos SGML y convertirlos a groff, LaTeX, HTML, GNU
info, LyX, y RTF. Adem�s de este paquete, se necesitar�n las
siguientes herramientas -- no son requeridas por el sistema SGML en
s�, pero sugiero hacerse con ellas para poder as� formatear tus
documentos y verificar que todo aparece como debe antes de
distribuirlas.

1. groff. Necesitas la versi�n 1.08 � 1.09. Aparentemente, parte del
tratamiento de los m�rgenes en groff se encuentra en estado de
perfeccionamiento de versi�n en versi�n; ambos funcionar�n, pero se
obtendr�n resultados ligeramente dist intos. (Particularmente, en
la 1.09 el margen izquierdo no es sangrado dos caracteres como lo
era en la 1.08.
Es soportable en la 1.09, pero en la 1.08, tiene un aspecto
terrible) Las versiones precedentes a la 1.08 no funcionar�n.
Puedes obtener esto de ftp://prep.ai.mit.edu/pub/gnu.

Hay una versi�n binaria para LiNUX en
ftp://sunsite.unc.edu/pub/Linux/utils/text Tambi�n. Necesitar�s
groff para producir texto ASCII simple a partir tus documentos
SGML. (TeX/LaTeX se emplear�n para obtener bonitas copias impresas
en PostScript y dvi).

2. TeX y LaTeX. Estos est�n disponibles m�s o menos, en todos lados;
no deber�a de haber problema en conseguirlo e instalarlo. (Hay una
distribuci�n de binarios en sunsite.unc.edu). Por supuesto, s�lo lo
necesitaremos si pretendemos formatear nues tros documentos SGML
con LaTeX/TeX, por lo que esto es opcional.

3. Si quieres visualizar el HTML generado, recomiendo conseguir el
NCSA Mosaic 2.6 o posterior, disponible en
ftp://sunsite.unc.edu/pub/Linux/system/Network/info-systems.

4. gawk y las herramientas GNU info, para formatear y visualizar los
ficheros info. Est�n disponibles tambi�n en

ftp://prep.ai.mit.edu/pub/gnu, o en
ftp://sunsite.unc.edu/pub/Linux/utils/text (para gawk) y

ftp://sunsite.unc.edu/pub/Linux/system/Manual-pagers (para las
herramientas GNU info.)

5. LyX (un interface quasi-WYSIWYG para el LaTeX, con esquemas SGML),
est� disponible en ftp://ftp.via.ecp.fr.

2.1. Instalaci�n del software

Los pasos necesarios para la instalaci�n y configuraci�n de linuxdoc-
sgml son los siguientes:

1. Primero, desempaquetar el archivo tar linuxdoc-sgml-1.5.tar.gz
donde sea. Esto crear� el directorio linuxdoc-sgml-1.5, donde
residir�n todos los archivos SGML. No importa donde descomprimas
este archivo; simplemente, no muevas nada del dir ectorio linuxdoc-
sgml-1.5.

2. Leer el fichero INSTALL. Contiene instrucciones detalladas de
instalaci�n.

Si todo va bien, estar�s listo para empezar a utilizar el sistema.

2.2. Formateando documentos

Digamos que tienes el documento SGML pepito.sgml que queremos
formatear. He aqu� una revisi�n gen�rica de c�mo formatear el
documento a lo s distintos formatos. Para ver una lista completa de
opciones, consultar las p�ginas man

2.2.1. Obteniendo texto plano como salida.

Si se quiere obtener texto plano como resultado, emplear el comando:

% sgml2txt foo.sgml

N�tese que he limitado la conversi�n de groff para la salida de texto
simple. Es decir, he quitado los encabezamientos de p�gina, cambiado
los m�rgenes, y dem�s. Con un poco de trabajo, puedes producir
PostScript y DVI de la salida de groff, pero sugiero que se emplee
LaTeX para ello.

Puedes producir fuentes groff para p�ginas man, que pueden ser
formateadas con groff -man. Para hacer esto:

% sgml2txt -man
foo.sgml

2.2.2. Produciendo LaTeX, DVI o PostScript

Para producir documentos LaTeX a partir del fuente SGML, ejecutar:

% sgml2latex foo.sgml

Si quieres producir salida PostScript (v�a dvips) emplea la opci�n -p:

% sgml2latex -p foo.sgml

O puedes producir un fichero DVI usando el par�metro -d, como aqu�:

% sgml2latex -d foo.sgml

2.2.3. Produciendo salida HTML

Si quieres obtener HTML como salida, haz lo siguiente:

% sgml2html -img foo.sgml

Esto producir� tanto foo.html, como foo-1.html, foo-2.html, y dem�s
---un archivo por cada secci�n del documento. Ejecuta tu navegador
WWW en foo.html, que es el archivo cabecera. Asegurarse de que todos
los ficheros HTML correspondientes al documento est�n en un
directorio, ya que se referencian unos a otros con URLs locales. Los
iconos referenciados en la salida HTML est�n localizados en
$LINUXDOCLIB/icons. Estos deber�n ser copiados tambi�n a la
localizaci�n final de los documentos HTML. $LINUXDOCLIB est� definida
al comienzo de los scripts de con versi�n SGML.

Si empleas sgml2html sin el par�metro -img, los documentos HTML
tendr�n las etiquetas ``previous'', ``next'', y ``table of contents''
para la navegaci�n. Puedes saltarte esa configuraci�n por defecto
creando un archivo en $LINUXDOCLIB /rep/html/<nombre_archivo>,
sustituyendo con tus palabras, las apropiadas para los distintos
lenguajes. El archivo posee el siguiente formato:

PrevPage: nuevovalor
NextPage: nuevovalor
TOC: nuevovalor

Ver el ejemplo deutsch.

2.2.4. Creando salida GNU Info

Si quieres formatear tu archivo para el visualizador GNU info, lo
�nico que has de ejecutar es:

% sgml2info foo.sgml

2.2.5. Creando salida LyX

Para obtener salida LyX, emplear el comando:

% sgml2lyx foo.sgml

2.2.6. Creando salida RTF

Si quieres obtener salida RTF, usa el comando:

% sgml2rtf foo.sgml

Esto producir� como salida foo.rtf, as� como foo-1.rtf, foo-2.rtf, y
as�; un fichero por cada secci�n del documento.

2.2.7. Comprobando la sintaxis del SGML

Si lo �nico que quieres es comprobar si habr�a errores en la
conversi�n del SGML emplea el script sgmlcheck. Por ejemplo:

% sgmlcheck foo.sgml

2.3. Tabla de C�digos ISO 8859-1

La tabla de caracteres ISO 8859-1 puede ser usada con caracteres
internacionales en transformaciones a texto ASCII plano, LaTeX y HTML
(-- nota para los textos en Castellano:

Esta es la tabla que se ha de emplear si se emplean tildes, e�es, etc;
basta con escribirlos como tales en los fuentes, y emplear el
par�metro sgml2html)--) Para hacer u so de esta propiedad, pasar al
script el par�metro -l, por ejemplo:

% sgml2txt -l foo.sgml

Puedes emplear los caracteres ISO 8859-1 en los fuentes, ser�n
transformados en los c�digos de escape apropiados de cada tipo de
formato.

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.
``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 <
que es una macro que se expandir� al car�cter de par�ntesis en �ngulo
actual. Por tanto, en el fuente tecle�:

Generalmente, lo que comience con un s�mbolo de ``&'' (-- N. del T.
``ampersand''--) es una macro especial. Por ejemplo, existe &percnt;
para obtener un %, | 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:

� Usar & con el ``ampersand'' (&),

� Usar < para el s�mbolo menor que (<),

� Usar > para el s�mbolo mayor que (>),

� Usar &etago; para el el s�mbolo menor que con una barra inversa
(</)

� Usar &dollar; con el s�mbolo de d�lar ($),

� Usar &num; con la almohadilla (#),

� Usar &percnt; con el s�mbolo de tanto por ciento (%),

� Usar &tilde; con una tilde (~),

� Usar `` y '' con las comillas, o emplear &dquot con ".

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.

� Usar &ero; para obtener un ampersand,

� Usar &etago; para obtener </,

� No usar \end{verbatim} dentro de un entorno verb ya que es as� como
lo emplea LaTeX para finalizar el entorno verbatim (En el futuro,
podr�a ser posible ocultar el formateador de texto subyacente
enteramente, pero el analizador no soporta esta caracter�stica
todav�a.)

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.

3.4.1. 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.
tendr�a este aspecto:

<!doctype linuxdoc system>

<article>

<title>Linux Foo-HOWTO

<author>Norbert Ebersol, <tt/[email protected]/

<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. y ``book''
(-- N. del T.

tambi�n; no he retocado �stos para su uso con Linuxdoc-SGML.

Las etiquetas title, author, y date (-- N. del T. 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.

3.4.2. P�rrafos y Secciones

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

� sect: Para secciones de nivel principal (como 1, 2, y as� en
adelante)

� sect1: Para secciones secundarias (como 1.1, 2.1, y dem�s)

� sect2: Para secciones de tercer nivel

� sect3: Para secciones de cuarto nivel

� sect4: Para secciones de quinto nivel

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

3.4.3. 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:[email protected]"
name="[email protected]"></tt>

y obtener ``[email protected]'' en la salida a texto mejor que el
repetitivo ``[email protected] <mailto:[email protected]>''
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.

deber�an ser todas las necesarias.

3.7. Listados

Existen varios tipos de listados soportados. Son:

� itemize para listados marcados con puntos como este

� enum para listados numerados

� descrip para obtener listados ``descriptivos''

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:

� He aqui un item

� He aqui un segundo item

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.

� The QWERTZ User's Guide est� disponible en:
ftp://ftp.cs.cornell.edu/pub/mdw/SGML.

QWERTZ (y por tanto, Linuxdoc-SGML) tiene bastantes prestaciones
como f�rmulas matem�ticas, tablas, figuras, y dem�s. No recomiendo
emplear la mayor�a de estas prestaciones en los HOWTOs sobre LiNUX
debido a que no saldr�an bien en las versiones de texto ASCII.

Si deseases escribir documentaci�n gen�rica en SGML, sugiero
emplear el DTD QWERTZ original, en lugar del ``retocado'' Linuxdoc-
SGML, que he modificado para el uso en particular con los HOWTOs de
LiNUX y documentaci�n similar.

� Las herramientas originales QWERTZ de Tom Gordon pueden obtenerse
en:

� M�s informaci�n acerca de SGML puede encontrarse en las siguientes
p�ginas WWW:

1. SGML en la web

2. P�gina Web del SGML

� El analizador de James Clark's sgmls, su sucesor, nsgmls y otras
herramientas pueden encontrarse en: ftp://ftp.jclark.com y en
James Clark's WWW Page <http://www.jclark.com>.

� Puedes unirte a la lista de correo de Linuxdoc-SGML enviando correo
a:

[email protected] con subscribe linuxdoc-sgml en el cuerpo del
mensaje. La direcci�n de correo es: [email protected].

� Se puede obtener m�s informaci�n sobre LyX en:

LyX WWW Page. LyX es un procesador de texto de alto nivel,
interface al LaTeX, quasi-WYSIWYG (-- N.del T.
``What You See Is What You Get'', algo as� como ``lo que ves es lo
que vas a obtener''--) , que genera muchos estilos y dise�os casi
autom�ticamente. Acelera el aprendizaje del LaTeX y hace que
dise�os complicados sean f�ciles e intuitivos.

4. Anexo a la Traducci�n al Castellano.

4.1. Aspectos Importantes del SGML-LaTeX en Castellano

4.1.1. Tildes, E�es, Etc.

Para que aparezcan las tildes, e�es y dem�s caracteres tipogr�ficos
t�picos del castellano que no sean ``caracteres especiales'' basta
como escribirlos como tales en el fuente (para ello, deber�s cargar el
mapa de teclado espa�ol, es.map, cosa q ue se suele configurar con el
programa de instalaci�n de LiNUX), que el editor los soporte (para vi
no hacen falta m�s configuraciones) y pasarle el par�metro `-l' al
script de conversi�n utilizado; (actualmente, s�lo soportan esta
opci�n sgml2la tex, sgml2html, y sgml2txt).

4.1.2. Tama�o del Papel.

Este no es un aspecto crucial, pero no est� de m�s saberlo. Para que
los documentos a LaTeX se formateen en un tama�o de papel A4, t�pico
en nuestro pa�s, basta con que al script de conversi�n se le pase el
par�metro `-a'. Tambi�n se puede especificar est o a dvips con la
opci�n `-a4'.

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

Este era un aspecto bastante molesto del LaTeX, el que se generasen
autom�ticamente los t�tulos de las macros toc, lof, lot, biblio,
etc... con los t�tulos en ingl�s; esto est� solucionado empleando el
paquete babel que suele veni r incluido con LaTeX, y que en lo que a
nosotros ata�e, da soporte a castellano, catal�n y gallego.

Para hacer uso del mismo basta con ejecutar texconfig, y configurar
las ``hyphenation tables'', generalmente editando desde el shell de
configuraci�n de texconfig el archivo languaje.dat, en el que se ha de
descomentar el patr�n perten eciente al espa�ol; al salir de texconfig
tendr�is el LaTeX configurado para funcionar en castellano.
Personalmente, dejo solamente el patr�n perteneciente al espa�ol, y no
tengo problemas, no s� si dar� problemas dejando varios.

Despu�s es necesario editar el fichero &LINUXDOCLIB/rep/latex/mapping
y a�adir en las definiciones de cada DTD (article, etc), ``spanish'',
de modo que quedar�a as�:

______________________________________________________________________
<qwertz> +
</qwertz> +

<article> + "\\documentstyle\[linuxdoc-sgml,isolatin,spanish,qwertz,[OPTS]\]{article}\n" ^ ^ ^
"\\input{epsf.tex}\n" +

</article> + "\\end{document}" +

[...]
______________________________________________________________________

5. Anexo: El INSFLUG

El INSFLUG forma parte del grupo internacional Linux Documentation
Project, encarg�ndose de las traducciones al castellano de los Howtos
(Comos), as� como la producci�n de documentos originales en aquellos
casos en los que no existe an�logo en ingl�s.

En el INSFLUG se orienta preferentemente a la traducci�n de documentos
breves, como los COMOs y PUFs (Preguntas de Uso Frecuente, las FAQs.
:) ), etc.

Dir�jase a la sede del INSFLUG para m�s informaci�n al respecto.

En la sede del INSFLUG encontrar� siempre las �ltimas versiones de las
traducciones: www.insflug.org. Aseg�rese de comprobar cu�l es la
�ltima versi�n disponible en el Insflug antes de bajar un documento de
un servidor r�plica.

Se proporciona tambi�n una lista de los servidores r�plica (mirror)
del Insflug m�s cercanos a Vd., e informaci�n relativa a otros
recursos en castellano.

Francisco Jos� Montilla, [email protected].