<!-- 0,2 -->
<!-- Linuxdoc-sgml -->
<!-- Greg,Hankins,greg.hankins@cc.gatech.edu -->
<!-- Matt,Welsh,mdw@sunsite.unc.edu -->
<!-- 1.5,1996-03-08 -->
<!-- Linuxdoc-sgml -->
<!-- Francisco J.,Montilla,pacopepe@insflug.org -->
<!-- 1.0,1997-02-04 -->
<!-- linuxdoc-sgml,sgml,COMO,formato -->
<!-- Software,Aplicaciones,Texto -->

<!doctype linuxdoc system>

<article>

<title>Guía de usuario de Linuxdoc-SGML

<author>Por Matt Welsh. Puesta al día por Greg Hankins, <tt><htmlurl
url="mailto:greg.hankins@cc.gatech.edu"
name="greg.hankins@cc.gatech.edu"></tt>&nl Traducido por Francisco José
Montilla, <tt><htmlurl url="mailto:pacopepe@insflug.org"
name="pacopepe@insflug.org"></tt>

<date>v1.5, 8 Marzo 1996     

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

<toc> 

<sect>Introducción
<p>

Esta es una guía de usuario para el sistema de procesado de documentación
<tt/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 <tt/groff/, LaTeX, HTML, GNU info, LyX, y RTF. 


<tt/linuxdoc-sgml/ Está fuertemente basado en el paquete QWERTZ DTD de
Thomas Gordon <tt><htmlurl url="mailto:thomas.gordon@gmd.de" 
name="thomas.gordon@gmd.de"></tt>. 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. 


<tt/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 <tt/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 <tt/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 <tt/info/. Por
este motivo, si faltan prestaciones en este sistema de las que se quisiese
disfrutar, <em/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.

<sect1>Acerca de este documento.
<p>

Este documento fue escrito usando el DTD <tt/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 <tt/Linuxdoc-Ejemplo.sgml/ 
para
ver un ejemplo de documento que se puede tener como modelo a la hora de
escribir los propios. 

<sect1>¿Por qué SGML?
<p>

Elegí SGML para este sistema porque está concebido específicamente para su
posterior transformación a otros formatos. SGML, abreviatura de
<em/Standard Generalized Markup Language/, permite especificar la
<em/estructura/ del documento---esto es, qué tipo de cosas dan forma al
documento. La estructura del documento se especifica con un DTD.
<tt/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
<em/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
<tt/linuxdoc-sgml/ se parece más al LaTeX. 

No dejarse confundir por esta analogía. SGML <em/no/ es un sistema de
formateo de documentación. No existe un ``formateador SGML'' en sí mismo.
El fuente SGML es <em/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---

<sect1>Cómo funciona.
<p>

He aquí cómo procesar un documento con SGML y cómo funciona el DTD
<tt/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 <tt/linuxdoc-sgml/
para nuestros propósitos.  El DTD únicamente configura la estructura del
documento. Una pequeña porción del mismo tiene este aspecto: 

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

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 (<tt/titlepag/), un encabezamiento opcional,
(<tt/header/); una tabla de contenidos opcional también, (<tt/toc/),
listado de figuras y de tablas opcionales (<tt/lof/ y <tt/lot/), cualquier
número de párrafos (<tt/p/), y secciones principales (<tt/sect/) apéndices
opcionales (<tt/appendix/), bibliografía (<tt/biblio/) y notas al pie
(<tt/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 <tt/titlepag/, <tt/header/, 
<tt/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 <em/necesita/ estar familiarizado con la <em/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 <tt/linuxdoc-sgml/ más tarde. 

El siguiente paso es escribir el documento empleando la estructura
definida por el DTD. Nuevamente, el DTD <tt/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
<em/analizado/ junto con el DTD por (lo adivinaste) el <em/analizador/
SGML. 

Estoy empleando el analizador <tt/sgmls/ de James Clark,
<tt><htmlurl url="mailto:jjc@jclark.com" name="jjc@jclark.com"></tt>, 
quien precisamente resulta ser el creador de
<tt/groff/. Estamos en buenas manos.  El analizador (<tt/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 <tt/sgmlasp/, la siguiente fase del proceso. 

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

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

<tscreen><verb>
<itemize>       +       "\\begin&lcub;itemize&rcub;      +
&etago;itemize>      +       "\\end&lcub;itemize&rcub;        +
</verb></tscreen>

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

<tscreen><verb>
\begin&lcub;itemize&rcub;
</verb></tscreen>

en el fuente LaTeX. (Como dije, los elementos del <tt/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 <tt/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.

<sect>Instalación.
<p>

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

<itemize> 

<item><tt><htmlurl
url="ftp://sunsite.unc.edu/pub/Linux/utils/text/linuxdoc-sgml-1.5.tar.gz" 
name="ftp://sunsite.unc.edu/pub/Linux/utils/text/linuxdoc-sgml-1.5.tar.gz"></tt>

<item><tt><htmlurl
url="ftp://tsx-11.mit.edu/pub/linux/docs/linuxdoc-sgml-1.5.tar.gz"
name="ftp://tsx-11.mit.edu/pub/linux/docs/linuxdoc-sgml-1.5.tar.gz"></tt>

<item><tt><htmlurl
url="ftp://ftp.cc.gatech.edu/pub/people/gregh/linuxdoc-sgml/linuxdoc-sgml-1.5.tar.gz" 
name="ftp://ftp.cc.gatech.edu/pub/people/gregh/linuxdoc-sgml/linuxdoc-sgml-1.5.tar.gz"></tt>

</itemize>

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

<tt><htmlurl url="ftp://ftp.cc.gatech.edu/pub/people/gregh/linuxdoc-sgml" 
name="ftp://ftp.cc.gatech.edu/pub/people/gregh/linuxdoc-sgml"></tt>. 

Puede obtener información actualizada en:

<tt><htmlurl 
url="http://www.informatik.tu-muenchen.de/&tilde;schwarz/linuxdoc-sgml/"
name="Linuxdoc-SGML WWW Page"></tt>. 

El archivo <tt/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. 

<enum>

<item><tt/groff/. <em/Necesitas/ la versión 1.08 ó 1.09. Aparentemente,
parte del tratamiento de los márgenes en <tt/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.
&nl Es soportable en la 1.09, pero en la 1.08, tiene un aspecto terrible) 
Las versiones precedentes a la 1.08 <em/no funcionarán/. Puedes obtener
esto de <tt><htmlurl url="ftp://prep.ai.mit.edu/pub/gnu" 
name="ftp://prep.ai.mit.edu/pub/gnu"></tt>.

Hay una versión binaria para LiNUX en <tt><htmlurl
url="ftp://sunsite.unc.edu/pub/Linux/utils/text" 
name="ftp://sunsite.unc.edu/pub/Linux/utils/text"></tt> También. 
Necesitarás <tt/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).

<item>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 <tt/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. 

<item>Si quieres visualizar el HTML generado, recomiendo conseguir el NCSA
Mosaic 2.6 o posterior, disponible en <tt><htmlurl
url="ftp://sunsite.unc.edu/pub/Linux/system/Network/info-systems" 
name="ftp://sunsite.unc.edu/pub/Linux/system/Network/info-systems"></tt>. 

<item><tt/gawk/ y las herramientas GNU info, para formatear y visualizar
los ficheros info. Están disponibles también en

<tt><htmlurl url="ftp://prep.ai.mit.edu/pub/gnu" 
name="ftp://prep.ai.mit.edu/pub/gnu"></tt>, o en <tt><htmlurl
url="ftp://sunsite.unc.edu/pub/Linux/utils/text" 
name="ftp://sunsite.unc.edu/pub/Linux/utils/text"></tt> (para <tt/gawk/) y

<tt><htmlurl url="ftp://sunsite.unc.edu/pub/Linux/system/Manual-pagers" 
name="ftp://sunsite.unc.edu/pub/Linux/system/Manual-pagers"></tt> (para
las herramientas GNU info.)  <item>LyX (un interface quasi-WYSIWYG para el
LaTeX, con esquemas SGML), está disponible en <tt><htmlurl
url="ftp://ftp.via.ecp.fr"  name="ftp://ftp.via.ecp.fr"></tt>. 

</enum>

<sect1>Instalación del software
<p>

Los pasos necesarios para la instalación y configuración de
<tt/linuxdoc-sgml/ son los siguientes: 

<enum>

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

<item>Leer el fichero <tt/INSTALL/. Contiene instrucciones detalladas de
instalación. 

Si todo va bien, estarás listo para empezar a utilizar el sistema.
</enum>

<sect1>Formateando documentos
<p>

Digamos que tienes el documento SGML <tt/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 <tt/man/

<sect2>Obteniendo texto plano como salida.
<p>

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

<tscreen><verb>
% sgml2txt foo.sgml
</verb></tscreen>

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 <tt/groff -man/. Para hacer esto:  <tscreen><verb> % sgml2txt -man
foo.sgml </verb></tscreen>

<sect2>Produciendo LaTeX, DVI o PostScript 
<p>

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

<tscreen><verb>
% sgml2latex foo.sgml
</verb></tscreen>

Si quieres producir salida PostScript (vía <tt/dvips/) emplea la opción
<tt/-p/: 

<tscreen><verb>
% sgml2latex -p foo.sgml
</verb></tscreen>

O puedes producir un fichero DVI usando el parámetro <tt>-d</tt>, como aquí:

<tscreen><verb>
% sgml2latex -d foo.sgml
</verb></tscreen>

<sect2>Produciendo salida HTML
<p>

Si quieres obtener HTML como salida, haz lo siguiente: 

<tscreen><verb>
% sgml2html -img foo.sgml
</verb></tscreen>

Esto producirá tanto <tt>foo.html</tt>, como <tt>foo-1.html</tt>,
<tt/foo-2.html/, y demás ---un archivo por cada sección del documento. 
Ejecuta tu navegador WWW en <tt>foo.html</tt>, 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
<tt>&dollar;LINUXDOCLIB/icons</tt>. Estos deberán ser copiados también a
la localización final de los documentos HTML. <tt/&dollar;LINUXDOCLIB/
está definida al comienzo de los scripts de con versión SGML. 

Si empleas <tt/sgml2html/ sin el parámetro <tt/-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 <tt>&dollar;LINUXDOCLIB /rep/html/&lt;nombre_archivo&gt;</tt>,
sustituyendo con tus palabras, las apropiadas para los distintos
lenguajes. El archivo posee el siguiente formato: 

<tscreen><verb>
PrevPage:    nuevovalor
NextPage:    nuevovalor
TOC:         nuevovalor
</verb></tscreen>

Ver el ejemplo <tt/deutsch/.

<sect2>Creando salida GNU Info 
<p>

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

<tscreen><verb>
% sgml2info foo.sgml
</verb></tscreen>

<sect2>Creando salida LyX
<p>

Para obtener salida LyX, emplear el comando:

<tscreen><verb>
% sgml2lyx foo.sgml
</verb></tscreen>

<sect2>Creando salida RTF
<p>

Si quieres obtener salida RTF, usa el comando:

<tscreen><verb>
% sgml2rtf foo.sgml
</verb></tscreen>

Esto producirá como salida <tt>foo.rtf</tt>, así como <tt>foo-1.rtf</tt>,
<tt/foo-2.rtf/, y así; un fichero por cada sección del documento. 

<sect2>Comprobando la sintaxis del SGML
<p>

Si lo único que quieres es comprobar si habría errores en la conversión
del SGML emplea el script <tt/sgmlcheck/. Por ejemplo: 

<tscreen><verb>
% sgmlcheck foo.sgml
</verb></tscreen>

<sect1>Tabla de Códigos ISO 8859-1 
<p>

La tabla de caracteres ISO 8859-1 puede ser usada con caracteres
internacionales en transformaciones a texto ASCII plano, LaTeX y
HTML<footnote> 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
'-l' en los scripts de conversión que se empleen (sgml2latex, sgml2text o
sgml2html)</footnote> Para hacer u so de esta propiedad, pasar al script
el parámetro <tt/-l/, por ejemplo: 

<tscreen><verb>
% sgml2txt -l foo.sgml 
</verb></tscreen>

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. 

<sect>Redacción de Documentos con Linuxdoc-SGML
<p>

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 <tt/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 <tt/Linuxdoc-Ejemplo.sgml/ 
para así
tener una referencia real a la que acudir. 

<sect1>Conceptos Básicos
<p>

Examinando los fuentes del documento ejemplo, te percatarás de que hay una
serie de ``etiquetas'' enmarcadas con paréntesis en ángulo<footnote>N. del
T.&nl Válgame la traducción ;-) creo que es más intuible y corto que poner
``símbolos de mayor/menor q ue''</footnote> (<tt>&lt;</tt> y
<tt/&gt;</tt>). 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/itálica/), un ``item'' de un listado
, y demás. El uso de una etiqueta es similar a los comandos de LaTeX como
<tt>&bsol;item</tt> o <tt>&bsol;section{...}</tt>. 

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

<tscreen><verb>
Por poner un ejemplo sencillo, para producir <bf>este texto en negrita&etago;bf>, ...
</verb></tscreen>

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

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

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 ``&amp;'' 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
<tt>&lt;sect></tt>; 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 (<tt/Linuxdoc-Ejemplo.sgml/).

<sect1>Caracteres Especiales
<p>

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
<tt>&dollar;LINUXDOCLIB/rep/latex/general </tt> sería un buen sitio donde
comenzar. <tt/&dollar;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: <tt>&lt;foo></tt >. Para obtener el
paréntesis en ángulo izquierdo (o de apertura)tendrás que emplear el
elemento <tt>&amp;lt;</tt> que es una macro que se expandirá al carácter
de paréntesis en ángulo actual. Por tanto, en el fuente tecleé: 

<tscreen><verb>
... que contenga parentesis en angulo, como esta: <tt>&ero;lt;foo>&etago;tt>.
</verb></tscreen>

Generalmente, lo que comience con un símbolo de ``&amp;''<footnote>N. del
T.&nl A partir de aquí me referiré a el por su denominación anglosajona,
``ampersand''</footnote> es una macro especial. Por ejemplo, existe
<tt/&amp;percnt;/ para obtener un &percnt;, <tt/&amp;verbar;/ para
&verbar;, 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: 

<itemize>
<item>Usar <tt>&amp;amp;</tt> con el ``ampersand'' (&amp;), 
<item>Usar <tt>&amp;lt;</tt> para el símbolo <it/menor que/ (&lt;),
<item>Usar <tt>&amp;gt;</tt> para el símbolo <it/mayor que/ (&gt),

<item>Usar <tt>&amp;etago;</tt> para el el símbolo <it/menor que/
con una barra inversa (<tt>&etago;</tt>) 

<item>Usar <tt>&amp;dollar;</tt> con el símbolo de dólar (&dollar;),
<item>Usar <tt>&amp;num;</tt> con la almohadilla (&num;),
<item>Usar <tt>&amp;percnt;</tt> con el símbolo de tanto por ciento (&percnt;),
<item>Usar <tt>&amp;tilde;</tt> con una tilde (&tilde;),

<item>Usar <tt>``</tt> y <tt>''</tt> con las comillas, o emplear
<tt>&amp;dquot</tt> con &dquot;. 

</itemize>

<sect1>Entornos Code y Verbatim
<p>

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

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

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

<itemize>
<item>Usar <tt>&amp;ero;</tt> para obtener un ampersand, 
<item>Usar <tt>&amp;etago;</tt> para obtener <tt>&etago;</tt>,

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

</itemize>

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

<code>
He aqui un entorno code de muestra.
</code>

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

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

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

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

<tscreen><verb>
<quote>
He aqui una muestra de texto a sangrar, como en una cita.
&etago;quote>
</verb></tscreen>

que generará:

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

<sect1>Estructura Global del Documento.
<p>

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

<sect2>El Preámbulo
<p>

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<footnote>N. del T.&nl COMO</footnote> tendría este aspecto:

<tscreen><verb>
<!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... 
&etago;abstract>

<toc>
</verb></tscreen>

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
<tt>&lt;article></tt> fuerza al documento a seguir el estilo ``article''.
El DTD QWERTZ original define ``report'' <footnote>N. del T.&nl
Informe</footnote> y ``book''<footnote>N. del T.&nl Libro.</footnote>
también; no he retocado éstos para su uso con Linuxdoc-SGML.

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

La etiqueta <tt/abstract/ define el texto que será impreso en el
encabezamiento del documento, <em/antes/ de la tabla de contenidos. Si no
se va a incluir una tabla de contenidos (la etiqueta <tt/toc/),
probablemente no sea necesario un elemento <tt/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. 

<sect2>Párrafos y Secciones
<p>

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

<itemize>

<item><tt/sect/:  Para secciones de nivel principal (como 1, 2, y así en
adelante)

<item><tt/sect1/: Para secciones secundarias (como 1.1, 2.1, y demás)
<item><tt/sect2/: Para secciones de tercer nivel
<item><tt/sect3/: Para secciones de cuarto nivel
<item><tt/sect4/: Para secciones de quinto nivel
</itemize>

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

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

<tscreen><verb>
<sect>Introduccion
</verb></tscreen>

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

<tscreen><verb>
<sect2>Parrafos y Secciones.
</verb></tscreen>

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
<tt>&lt;p></tt>, como sigue: 

<tscreen><verb>
<sect>Introduccion
<p>

Esta es una guia de usuario del sistema de procesado de documentacion
linuxdoc-sgml ... 
</verb></tscreen>

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,

<tscreen><verb>
He aqui el final del primer parrafo.

Y aqui comenzamos este nuevo. 
</verb></tscreen>

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

<sect2>Finalizando el documento
<p>

Al final del documento, se debe emplear la etiqueta:

<tscreen><verb>
&etago;article>
</verb></tscreen>

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

<sect1>Referencias Cruzadas<label id="cross-ref">
<p>

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: 

<tscreen><verb>
<sect1>Introduccion<label id="sec-intro">
</verb></tscreen>

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

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

Esto sustituirá la etiqueta <tt/ref/ con el número de sección etiquetado
como <tt/sec-intro/. El argumento <tt/name/ para <tt/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 <ref id="cross-ref"
name="Cross-references">. 

Existe también un elemento <tt/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,

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

El argumento <tt/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 <tt/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 <tt/name/, se
empleará el propio del URL. 

Por ejemplo, puede obtener el paquete Linuxdoc-SGML de 

<tt><htmlurl
url="ftp://sunsite.unc.edu/pub/Linux/utils/text/linuxdoc-sgml-1.5.tar.gz" 
name="ftp://sunsite.unc.edu/pub/Linux/utils/text/linuxdoc-sgml-1.5.tar.gz"></tt>. 

Una variante muy útil de este <tt/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: 

<tscreen><verb>
<tt><htmlurl url="mailto:esr@snark.thyrsus.com"
name="esr@snark.thyrsus.com">&etago;tt>
</verb></tscreen>

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

<sect1>Fuentes (Tipográficas)
<p>

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/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:

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

El equivalente:

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

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; <tt/bf/ para obtener <bf/negrita/ y
<tt/em/ para obtener <em/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<footnote>N. del T.&nl
<bf/Boldface/, <tt/typewriter/ e <em/italics/ en Inglés.</footnote>
deberían ser todas las necesarias.

<sect1>Listados
<p>

Existen varios tipos de listados soportados. Son:

<itemize>
<item><tt/itemize/ para listados marcados con puntos como este
<item><tt/enum/ para listados numerados
<item><tt/descrip/ para obtener listados ``descriptivos''
</itemize>

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

Por ejemplo:

<tscreen><verb>
<itemize>
<item>He aqui un item.
<item>He aqui un segundo item.
&etago;itemize>
</verb></tscreen>

Que tendrá este aspecto:

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

O, para un <tt/enum/,

<tscreen><verb>
<enum>
<item>He aqui el primer item.
<item>He aqui el segundo item.
&etago;enum>
</verb></tscreen>

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

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

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

que acaban teniendo este aspecto:

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

<sect1>Más Información.
<p>

<itemize> 
<item>The QWERTZ User's Guide está disponible en: <tt><htmlurl
url="ftp://ftp.cs.cornell.edu/pub/mdw/SGML"
name="ftp://ftp.cs.cornell.edu/pub/mdw/SGML"></tt>.

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. 

<item>Las herramientas originales QWERTZ de Tom Gordon pueden obtenerse
en:&nl <tt><htmlurl url="ftp://ftp.gmd.de/GMD/sgml" 
name="ftp://ftp.gmd.de/GMD/sgml"></tt>. 

<item>Más información acerca de SGML puede encontrarse en las siguientes
páginas WWW: 

<enum> 

<item><tt><htmlurl url="http://www.w3.org/hypertext/WWW/MarkUp/SGML/" 
name="SGML en la web"></tt> 

<item><tt><htmlurl
url="http://www.sil.org/sgml/sgml.html"  name="Página Web del SGML"></tt>
</enum>
       
<item>El analizador de James Clark's <tt/sgmls/, su sucesor, <tt/nsgmls/ y
otras herramientas pueden encontrarse en:  <tt><htmlurl
url="ftp://ftp.jclark.com" name="ftp://ftp.jclark.com"> </tt> y en
<tt><url url="http://www.jclark.com"  name="James Clark's WWW Page"></tt>. 

<item>Puedes unirte a la lista de correo de Linuxdoc-SGML enviando correo
a:

<tt><htmlurl url="mailto:majordomo@via.ecp.fr" 
name="majordomo@via.ecp.fr"></tt> con <tt/subscribe linuxdoc-sgml/ en el
cuerpo del mensaje. La dirección de correo es:  <tt><htmlurl
url="mailto:linuxdoc-sgml@via.ecp.fr" 
name="linuxdoc-sgml@via.ecp.fr"></tt>. 

<item>Se puede obtener más información sobre <tt/LyX/ en:

<tt><htmlurl
url="http://wsiserv.informatik.uni-tuebingen.de/&tilde;ettrich/" 
 name="LyX WWW Page"></tt>.  <tt/LyX/ es un procesador de texto de alto
nivel, interface al LaTeX, quasi-WYSIWYG<footnote>N.del T.&nl WYSIWYG :
``What You See Is What You Get'', algo así como ``lo que ves es lo que vas
a obtener''</footnote>, 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. 

</itemize>

<sect>Anexo a la Traducción al Castellano.
<p>

<sect1>Aspectos Importantes del SGML-LaTeX en Castellano
<p>

<sect2>Tildes, Eñes, Etc.
<p>

Para que aparezcan las tildes, eñes y demás caracteres tipográficos
típicos del castellano que <em/no/ sean ``caracteres especiales'' basta
como escribirlos como tales en el fuente (para ello, deberás cargar el
mapa de teclado español, <tt/es.map/, cosa q ue se suele configurar con el
programa de instalación de LiNUX), que el editor los soporte (para <tt/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
<tt/sgml2la tex/, <tt/sgml2html/, y <tt/sgml2txt/). 

<sect2>Tamaño del Papel.
<p>

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 <tt/dvips/ con la
opción `-a4'. 

<sect2>Los títulos de las Tablas de Contenidos, Bibliografía, etc.
<p>

Este era un aspecto bastante molesto del LaTeX, el que se generasen
automáticamente los títulos de las macros <tt/toc/, <tt/lof/, <tt/lot/,
<tt/biblio/, etc... con los títulos en inglés; esto está solucionado
empleando el paquete <em/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 <tt/texconfig/, y configurar
las ``<em/hyphenation tables/'', generalmente editando desde el shell de
configuración de <tt/texconfig/ el archivo <tt/languaje.dat/, en el que se
ha de descomentar el patrón perten eciente al español; al salir de
<tt/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 <tt>
&amp;LINUXDOCLIB/rep/latex/mapping</tt> y añadir en las definiciones de
cada DTD (article, etc), ``spanish'', de modo que quedaría así: 

<tscreen><code>
<qwertz>        +
&etago;qwertz>       +

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

&etago;article>      +       "\\end{document}"       +

[...]
</code></tscreen>

<sect>Anexo: El INSFLUG <label id="Grupos">
<p>

El <em/INSFLUG/ forma parte del grupo internacional <it/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 <bf/INSFLUG/ se orienta preferentemente a la traducción de
documentos breves, como los <em/COMOs/ y <em/PUFs/ (<bf/P/reguntas de
<bf/U/so <bf/F/recuente, las <it/FAQs/. <tt/:)/ ), etc. 

Diríjase a la sede del INSFLUG para más información al respecto.

En la sede del INSFLUG encontrará siempre las <bf/últimas/ versiones de
las traducciones:  <tt><htmlurl url="http://www.insflug.org" 
name="www.insflug.org"></tt>. 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 (<it/mirror/)
del Insflug más cercanos a Vd., e información relativa a otros recursos en
castellano. 

Francisco José Montilla, <tt><htmlurl url="mailto:pacopepe@insflug.org" 
name="pacopepe@insflug.org"></tt>. 

</article>
