  Gua de usuario de Linuxdoc-SGML
  Por Matt Welsh. Puesta al da por Greg Hankins, greg.hank
  ins@cc.gatech.edu
  Montilla, pacopepe@insflug.org
  v1.5, 8 Marzo 1996

  Este documento es una gua 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 slo fuente SGML. Esta gua documenta el paquete Linuxdoc-SGML en
  su versin 1.5.
  ______________________________________________________________________

  ndice General:

  1.      Introduccin

  1.1.    Acerca de este documento.

  1.2.    Por qu SGML?

  1.3.    Cmo funciona.

  2.      Instalacin.

  2.1.    Instalacin 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 Cdigos ISO 8859-1

  3.      Redaccin de Documentos con Linuxdoc-SGML

  3.1.    Conceptos Bsicos

  3.2.    Caracteres Especiales

  3.3.    Entornos Code y Verbatim

  3.4.    Estructura Global del Documento.

  3.4.1.  El Prembulo

  3.4.2.  Prrafos y Secciones

  3.4.3.  Finalizando el documento

  3.5.    Referencias Cruzadas

  3.6.    Fuentes (Tipogrficas)

  3.7.    Listados

  3.8.    Ms Informacin.

  4.      Anexo a la Traduccin al Castellano.

  4.1.    Aspectos Importantes del SGML-LaTeX en Castellano

  4.1.1.  Tildes, Ees, Etc.

  4.1.2.  Tamao del Papel.

  4.1.3.  Los ttulos de las Tablas de Contenidos, Bibliografa, etc.

  5.      Anexo: El INSFLUG
  ______________________________________________________________________

  1.  Introduccin

  Esta es una gua de usuario para el sistema de procesado de
  documentacin linuxdoc-SGML, concebido para producir informacin
  relativa a LiNUX.  Consiste en una Definicin 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 especfico con d ocumentacin relativa a
  LiNUX.

  linuxdoc-sgml no pretende ser un sistema genrico de procesado de
  documentacin.  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 documentacin genrico; He manipulado sus posibilidades con
  este propsito.

  Si se percibe una falta de generalidad en el sistema, se debe a esta
  razn. No hay nada que limite linuxdoc-SGML a la produccin de
  documentacin sobre LiNUX, pero todo lo producido con este sistem a
  tendr un aspecto caracterstico. Si se desea que la apariencia sea
  distinta, sugiero que se emplee un sistema ms generalizado como el
  QWERTZ DTD, en combinacin con las herramientas Linuxdoc-SGML.

  Uno de los objetivos de este sistema es hacer fcil la produccin de
  documentos en distintos formatos. Hasta ahora, la mayora de la
  documentacin LiNUX haba sido producida a travs de edicin manual.
  Un sistema como groff puede ocuparse del formate o para una versin
  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, hzmelo saber, por favor! La idea es que no hagan
  falta demasiadas triquiuelas para producir documentos agradables en
  mltiples formatos.

  El autor debe de tener que hacer lo mnimo posible.

  1.1.  Acerca de este documento.

  Este documento fue escrito usando el DTD linuxdoc-sgml. Contiene ms o
  menos todo lo que se necesita saber para escribir documentos SGML con
  este DTD (definicin de tipo de documento). Vase 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 especficamente
  para su posterior transformacin 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 estndar
  proporciona DTDs para libros , artculos, y otras clases de
  documentacin genrica.

  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 seccin, subseccin, un prrafo, o simplemente
  algo menor como texto remarcado. A diferencia del LaT eX, no obstante,
  estos elementos no son en modo alguno intrnsecos al SGML en s mismo.
  La definicin de documento linuxdoc-sgml viene a definir elementos muy
  similares a su equivalentes en LaTeX ---tiene secciones, subsecciones,
  ``entornos'' de texto y d ems---. 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 ms al LaTeX.

  No dejarse confundir por esta analoga. SGML no es un sistema de
  formateo de documentacin. No existe un ``formateador SGML'' en s
  mismo.  El fuente SGML es slo convertido a otros formatos para su
  procesado.  Adems, el SGML por s mismo lo nic o que hace es
  especificar la estructura del documento. No existen dispositivos o
  ``macros'' intrnsecos 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.  Cmo funciona.

  He aqu cmo procesar un documento con SGML y cmo funciona el DTD
  linuxdoc-sgml. Primero, se necesita una definicin 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 propsitos.  El DTD nicamente configura la
  estructura del documento. Una pequea porcin 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 artculo consiste
  en una pgina de portada (titlepag), un encabezamiento opcional,
  (header); una tabla de contenidos opcional tambin, (toc), listado de
  figuras y de tablas opcionales (lof y lot), cualquier nmero de
  prrafos (p), y secciones principales (sect) apndices opcionales
  (appendix), bibliografa (biblio) y notas al pie (footnote ).

  Como puede observarse, el DTD no menciona nada acerca de cmo debera
  de formatearse el documento, o sobre el aspecto que debera 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
  documentacin. 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 ms 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
  especfico, 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. Tambin
  devuelve un formato ms esplcito de tu documento, con todos las
  ``macros'' y dems elementos expandidos, lo cual es inteligible para
  sgmlasp, la siguiente fase del proceso.

  sgmlsasp es el responsable de la conversin de la salida de sgmls a
  otro formato (como LaTeX). Lleva a cabo esta tarea usando archivos
  sustitutivos, que describen cmo 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 tendra
  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 analogas apropiadas para los elementos SGML en el
  nuevo formato. En la prctica, 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 ms fcil de hacer que escribir analizadores individuales y
  traductores para varios tipos de formatos de salida; SGML proporciona
  un sistema genrico de conversin 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 hara normalmente. Posteriormente
  dar en este documento ejemplos y mostrar los com andos empleados
  para llevar a cabo la traduccin y formateo. Todo puede ser llevado a
  cabo desde la lnea de comandos.

  Pero primero, debo describir cmo instalar y configurar el software.

  2.  Instalacin.

  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 versin 1.5 pueden encontrarse en:

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

  Puede obtener informacin 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. Adems de este paquete, se necesitarn 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 versin 1.08  1.09. Aparentemente, parte del
     tratamiento de los mrgenes en groff se encuentra en estado de
     perfeccionamiento de versin en versin; ambos funcionarn, pero se
     obtendrn 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 funcionarn.
     Puedes obtener esto de ftp://prep.ai.mit.edu/pub/gnu.

     Hay una versin binaria para LiNUX en
     ftp://sunsite.unc.edu/pub/Linux/utils/text Tambin.  Necesitars
     groff para producir texto ASCII simple a partir tus documentos
     SGML.  (TeX/LaTeX se emplearn para obtener bonitas copias impresas
     en PostScript y dvi).

  2. TeX y LaTeX. Estos estn disponibles ms o menos, en todos lados;
     no debera de haber problema en conseguirlo e instalarlo. (Hay una
     distribucin de binarios en sunsite.unc.edu). Por supuesto, slo 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. Estn disponibles tambin 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.  Instalacin del software

  Los pasos necesarios para la instalacin y configuracin 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
     residirn 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
     instalacin.

     Si todo va bien, estars 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 revisin genrica de cmo formatear el
  documento a lo s distintos formatos.  Para ver una lista completa de
  opciones, consultar las pginas man

  2.2.1.  Obteniendo texto plano como salida.

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

       % sgml2txt foo.sgml

  Ntese que he limitado la conversin de groff para la salida de texto
  simple.  Es decir, he quitado los encabezamientos de pgina, cambiado
  los mrgenes, y dems. 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 pginas 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 (va dvips) emplea la opcin -p:

       % sgml2latex -p foo.sgml

  O puedes producir un fichero DVI usando el parmetro -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 dems
  ---un archivo por cada seccin del documento.  Ejecuta tu navegador
  WWW en foo.html, que es el archivo cabecera.  Asegurarse de que todos
  los ficheros HTML correspondientes al documento estn en un
  directorio, ya que se referencian unos a otros con URLs locales.  Los
  iconos referenciados en la salida HTML estn localizados en
  $LINUXDOCLIB/icons. Estos debern ser copiados tambin a la
  localizacin final de los documentos HTML. $LINUXDOCLIB est definida
  al comienzo de los scripts de con versin SGML.

  Si empleas sgml2html sin el parmetro -img, los documentos HTML
  tendrn las etiquetas ``previous'', ``next'', y ``table of contents''
  para la navegacin. Puedes saltarte esa configuracin 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 seccin del documento.

  2.2.7.  Comprobando la sintaxis del SGML

  Si lo nico que quieres es comprobar si habra errores en la
  conversin del SGML emplea el script sgmlcheck. Por ejemplo:

       % sgmlcheck foo.sgml

  2.3.  Tabla de Cdigos 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, ees, etc;
  basta con escribirlos como tales en los fuentes, y emplear el
  parmetro sgml2html)--) Para hacer u so de esta propiedad, pasar al
  script el parmetro -l, por ejemplo:

       % sgml2txt -l foo.sgml

  Puedes emplear los caracteres ISO 8859-1 en los fuentes, sern
  transformados en los cdigos de escape apropiados de cada tipo de
  formato.

  3.  Redaccin de Documentos con Linuxdoc-SGML

  Para la mayora, redactar documentacin empleando la Definicin 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
  seccin, expondr en una introduccin la redaccin de documentacin
  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. Slo 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 Bsicos

  Examinando los fuentes del documento ejemplo, te percatars de que hay
  una serie de ``etiquetas'' enmarcadas con parntesis en ngulo (-- N.
  del T.
  ``smbolos de mayor/menor q ue''--) (< y >). Una etiqueta especifica
  simplemente el comienzo y final de un elemento, siendo un elemento
  algo como una seccin, prrafo, una frase con texto en tipografa
  cursiva (itlica), un ``item'' de un listado , y dems. 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 regin 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 tambin, debers usar el mtodo
  ``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 razn por la que vers 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 seccin, empleas la etiqueta
  de <sect>; de todos modos, la etiqueta de finalizacin de la seccin
  (que podra aparecer al final del cuerpo de la seccin propiamente,
  no justo tras el ttulo de la seccin!) es opcional e implcito
  cuando se da comienzo a otra seccin 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 mayora de caracteres especiales, por lo que
  paginando $LINUXDOCLIB/rep/latex/general  sera un buen sitio donde
  comenzar. $LINUXDOCLIB est definido al comienzo de los scripts de
  conversin.

  Obviamente, los parntesis en ngulo son por s mismos caracteres
  especiales en los fuentes SGML. Hay otros a los que prestar atencin.
  Por ejemplo, digamos que quisieras teclear una expresin que contenga
  parntesis en ngulo, como esta: <foo>. Para obtener el parntesis en
  ngulo izquierdo (o de apertura)tendrs que emplear el elemento &lt;
  que es una macro que se expandir al carcter de parntesis en ngulo
  actual. Por tanto, en el fuente tecle:

  Generalmente, lo que comience con un smbolo de ``&'' (-- N. del T.
  ``ampersand''--) es una macro especial. Por ejemplo, existe &percnt;
  para obtener un %, &verbar; 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 carcter especial, no obstante, en algunos casos es
  necesario. Los ms utilizados son:

    Usar &amp; con el ``ampersand'' (&),

    Usar &lt; para el smbolo menor que (<),

    Usar &gt; para el smbolo mayor que (>),

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

    Usar &dollar; con el smbolo de dlar ($),

    Usar &num; con la almohadilla (#),

    Usar &percnt; con el smbolo 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 tratbamos el asunto de los caracteres especiales, deb
  mencionar tambin el ``entorno'' verbatim empleado para incluir texto
  literal en la salida (preservando los espacios, sangras, y dems). 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. Especficamente, debers 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,
     podra ser posible ocultar el formateador de texto subyacente
     enteramente, pero el analizador no soporta esta caracterstica
     todava.)

  El entorno code es mayormente como el entorno verb, a excepcin de las
  lneas horizontales que son aadidas al texto que enmarca, como aqu:

  ______________________________________________________________________
  He aqui un entorno code de muestra.
  ______________________________________________________________________

  Debers 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 tipogrfica 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 algn carcter
  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 excepcin de que no se
  selecciona como fuente tipogrfica por defecto tt. Por tanto, puedes
  emplear quote para menciones que no requieren interaccin 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 cmo
  definir un documento.

  3.4.1.  El Prembulo

  En el ``prembulo'' del documento, se definen aspectos como la
  informacin del ttulo, y el estilo del documento. Para un documento
  de tipo Howto (-- N. del T.
  tendra este aspecto:

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

  <toc>

  Los elementos debern ir ms o menos en ese orden. La primera lnea
  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.

  tambin; no he retocado stos para su uso con Linuxdoc-SGML.

  Las etiquetas title, author, y date (-- N. del T.  deberan resultar
  obvias.  La etiqueta date incluye el nmero de versin y la ltima
  fecha de modificacin 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 premb ulo, para que
  el ttulo, resumen, y tabla de contenidos estn todos ah y tengan una
  apariencia similar.

  3.4.2.  Prrafos y Secciones

  Tras el prembulo, 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 dems)

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

  Tras la etiqueta sect (o sect1, sect2, etc.) vendr el nombre de la
  seccin. Por ejemplo, al comienzo de este documento, tras el
  prembulo, viene la etiqueta:

       <sect>Introduccion

  Y al comienzo de esta seccin (Prrafos y Secciones), est la
  etiqueta:

       <sect2>Parrafos y Secciones.

  Tras la etiqueta de seccin, se comienza el cuerpo de la seccin. 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
  ttulo de la seccin, y que ests listo para comenzar con el cuerpo. A
  partir de ah, los prrafos siguientes se comienzan con una lnea en
  blanco (tal y como se hara en TeX). Por ejemplo,

       He aqui el final del primer parrafo.

       Y aqui comenzamos este nuevo.

  No hay razn para usar etiquetas <p> al comienzo de cada prrafo;
  nicamente al comienzo del primer prrafo 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 fciles. Por ejemplo, si queremos definir una referencia
  cruzada a cierta seccin, necesitars etiquetar esa seccin con un
  nombre, como sigue:

       <sect1>Introduccion<label id="sec-intro">

  Ahora ya se podr referir a esa seccin en cualquier lugar del texto
  empleando la expresin:

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

  Esto sustituir la etiqueta ref con el nmero de seccin etiquetado
  como sec-intro. El argumento name para ref es necesario para
  transformaciones a groff y HTML. La definicin 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
  nmero.

  Por ejemplo, esta seccin es la ``Cross-references''.

  Existe tambin 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 dems. 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 cuestin ser aadido actualmente al documento HTML.

  El argumento opcional name especifica el texto que ser anclado al URL
  (para la conversin HTML) o que dar nombre como descripcin del URL
  (para LaTeX y groff). Si no se incluye ningn parmetro 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 creacin 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:esr@snark.thyrsus.com"
  name="esr@snark.thyrsus.com"></tt>

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

  3.6.  Fuentes (Tipogrficas)

  En esencia, las mismas fuentes soportadas por LaTeX lo son por
  Linuxdoc-SGML.  Ntese de todos modos, que en la conversin a texto
  ASCII (va groff) se prescinde de la informacin relativa a fuentes.
  Por tanto, podrn emplearse las fuentes todo lo que se quiera, con el
  beneficio correspondiente en la conversin a LaTeX. Pero no basarse en
  las fuentes para hacer comprender algo concreto en la versin ASCII.

  Particularmente, la etiqueta tt descrita anteriormente puede ser
  empleada para obtener una fuente de tipo ``mquina de escribir'' de
  anchura constante, que deber emplearse en todas las direcciones e-
  mail, nombres de mquina, 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.

  Recurdese que slo se puede hacer uso de este mtodo abreviado si el
  texto englobado no contiene barras.

  Se pueden conseguir otras fuentes; bf para obtener negrita y em para
  obtener cursiva. Bastantes ms tipos de fuentes son soportados
  tambin, pero no las recomiendo, porque al convertir esos documentos a
  otros formatos como el HTML podr an no ser soportados. La negrita,
  tipo mquina de escribir, y cursiva (-- N. del T.

  deberan 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 tambin; ver
  el documento de ejemplo para ms detalles.

  Un listado descrip es ligeramente diferente, y tambin ligeramente ms
  feo, pero podras 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.  Ms Informacin.

    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 frmulas matemticas, tablas, figuras, y dems. No recomiendo
     emplear la mayora de estas prestaciones en los HOWTOs sobre LiNUX
     debido a que no saldran bien en las versiones de texto ASCII.

     Si deseases escribir documentacin genrica 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 documentacin similar.

    Las herramientas originales QWERTZ de Tom Gordon pueden obtenerse
     en:

    Ms informacin acerca de SGML puede encontrarse en las siguientes
     pginas WWW:

     1. SGML en la web

     2. Pgina 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:

     majordomo@via.ecp.fr con subscribe linuxdoc-sgml en el cuerpo del
     mensaje. La direccin de correo es:  linuxdoc-sgml@via.ecp.fr.

    Se puede obtener ms informacin 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 diseos casi
     automticamente. Acelera el aprendizaje del LaTeX y hace que
     diseos complicados sean fciles e intuitivos.

  4.  Anexo a la Traduccin al Castellano.

  4.1.  Aspectos Importantes del SGML-LaTeX en Castellano

  4.1.1.  Tildes, Ees, Etc.

  Para que aparezcan las tildes, ees y dems caracteres tipogrficos
  tpicos del castellano que no sean ``caracteres especiales'' basta
  como escribirlos como tales en el fuente (para ello, debers cargar el
  mapa de teclado espaol, es.map, cosa q ue se suele configurar con el
  programa de instalacin de LiNUX), que el editor los soporte (para vi
  no hacen falta ms configuraciones) y pasarle el parmetro `-l' al
  script de conversin utilizado; (actualmente, slo soportan esta
  opcin sgml2la tex, sgml2html, y sgml2txt).

  4.1.2.  Tamao del Papel.

  Este no es un aspecto crucial, pero no est de ms saberlo. Para que
  los documentos a LaTeX se formateen en un tamao de papel A4, tpico
  en nuestro pas, basta con que al script de conversin se le pase el
  parmetro `-a'. Tambin se puede especificar est o a dvips con la
  opcin `-a4'.

  4.1.3.  Los ttulos de las Tablas de Contenidos, Bibliografa, etc.

  Este era un aspecto bastante molesto del LaTeX, el que se generasen
  automticamente los ttulos de las macros toc, lof, lot, biblio,
  etc... con los ttulos en ingls; esto est solucionado empleando el
  paquete babel que suele veni r incluido con LaTeX, y que en lo que a
  nosotros atae, da soporte a castellano, cataln y gallego.

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

  Despus es necesario editar el fichero &LINUXDOCLIB/rep/latex/mapping
  y aadir en las definiciones de cada DTD (article, etc), ``spanish'',
  de modo que quedara 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, encargndose de las traducciones al castellano de los Howtos
  (Comos), as como la produccin de documentos originales en aquellos
  casos en los que no existe anlogo en ingls.

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

  Dirjase a la sede del INSFLUG para ms informacin al respecto.

  En la sede del INSFLUG encontrar siempre las ltimas versiones de las
  traducciones:  www.insflug.org. Asegrese de comprobar cul es la
  ltima versin disponible en el Insflug antes de bajar un documento de
  un servidor rplica.

  Se proporciona tambin una lista de los servidores rplica (mirror)
  del Insflug ms cercanos a Vd., e informacin relativa a otros
  recursos en castellano.

  Francisco Jos Montilla, pacopepe@insflug.org.

