192 lines
8.3 KiB
Text
192 lines
8.3 KiB
Text
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [
|
|
<!ENTITY base CDATA "..">
|
|
<!ENTITY date "$FreeBSD: www/es/docproj/sgml.sgml,v 1.7 2000/07/05 09:38:19 wosch Exp $">
|
|
<!ENTITY title "Proyecto de Documentación de FreeBSD: SGML">
|
|
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
|
|
]>
|
|
<!-- $FreeBSD: www/es/docproj/sgml.sgml,v 1.7 2000/07/05 09:38:19 wosch Exp $ -->
|
|
|
|
<html>
|
|
&header;
|
|
|
|
<p>El proyecto de Documentación intenta usar SGML como
|
|
método estandar de representar la documentación.</p>
|
|
|
|
<p>SGML es el lenguaje <b>S</b>tandard <b>G</b>eneralised <b>M</b>arkup
|
|
<b>L</b>.</p>
|
|
|
|
<p>Brevemente (y disculpas para los puristas de SGML que puedan sentirse
|
|
ofendidos), SGML es un lenguaje para escribir otros lenguajes.</p>
|
|
|
|
<p>Probablemente ya has usado SGML sin saberlo. HTML, el leguaje en el
|
|
que se escriben las páginas web, tiene una descripción
|
|
formal. Esa descripción está escrita en SGML. Cuando
|
|
escribes en HTML <b>no</b> estás escribiendo SGML, pero sí
|
|
estás usando un lenguaje definido por SGML.</p>
|
|
|
|
<p>Existen muchos, muchos lenguajes "markup" que están definidos
|
|
usando SGML. HTML es uno de ellos. Otro es el llamado "LinuxDoc". Como
|
|
puedes adivinar, fue creado por los grupos de usuarios de Linux para
|
|
escribir su documentación, y el Proyecto de Documentación
|
|
de FreeBSD lo adoptó.</p>
|
|
|
|
<p>Otro lenguaje "markup" definido usando SGML es el llamado "DocBook".
|
|
Este es un lenguaje diseñado específicamente para escribir
|
|
documentación técnica.</p>
|
|
|
|
<p>Por ejemplo, así estaría escrito un breve párrafo
|
|
en HTML (no te preocupes del contenido, solo fíjate en los
|
|
tags):</p>
|
|
|
|
<pre><![ CDATA [
|
|
<p>The system's passwords are stored in <tt>/etc/passwd</tt>. To edit
|
|
this file you should use <b><tt>vipw</tt></b>. However, if you just
|
|
want to add a new user you can use <b><tt>adduser</tt></b>.</p>
|
|
]]></pre>
|
|
|
|
<p>El mismo párrafo usando DocBook sería:</p>
|
|
|
|
<pre><![ CDATA [
|
|
<para>The system's passwords are stored in
|
|
<filename>/etc/passwd</filename>. To edit this file you should use
|
|
<command>vipw</command>. However, if you just want to add a new user
|
|
you can use <command>adduser</command>.</para>
|
|
]]></pre>
|
|
|
|
<p>Como puedes ver, DocBook es mucho más expresivo que HTML. En el
|
|
ejemplo HTML el nombre del fichero se muestra con una fuente de tipo
|
|
"typewriter". En el ejemplo de DocBook, el nombre de fichero está
|
|
marcado como que es un "filename", la representación de un
|
|
nombre de fichero no está descrita.</p>
|
|
|
|
<p>Hay grande ventajas en esta manera más expresiva de lenguaje:</p>
|
|
|
|
<ul>
|
|
<li><p>No es ambiguo o inconsistente.</p> <p>No pierdes tiempo
|
|
pensando "Hmm, necesito mostrar un nombre de fichero, debería
|
|
usar "tt", o "b", o "em"</p> <p>En lugar de eso, usas el tag
|
|
correcto para el trabajo correcto.</p>
|
|
|
|
<p>El proceso de conversión de DocBook a otros formatos como
|
|
HTML o Postscript asegura que todos serán vistos de la
|
|
misma manera.</p>
|
|
</li>
|
|
|
|
<li><p>Dejar de pensar en como representar la documentación,
|
|
y solo te concentras en el contenido.</p>
|
|
|
|
<li><p>Como la documentación no está pensada para un
|
|
determinado formato de salida, la misma documentación puede
|
|
crearse en diferentes formatos - texto, HTML, Postscript, RTF,
|
|
PDF, etc.</p></li>
|
|
|
|
<li><p>La documentación es más "inteligente", lo que
|
|
permite hacer cosas más inteligentes con ella. Por ejemplo,
|
|
es posible crear un índice automático que liste cada
|
|
comando mostrado en la documentación.</p>.</li>
|
|
</ul>
|
|
|
|
<p>Si estás familiarizado con ellos, es como las galerías
|
|
de estilo de Microsoft Word, solo que infinitamente más
|
|
potente.</p>
|
|
|
|
<p>Por supuesto, esta potencia tiene un precio;</p>
|
|
|
|
<ul>
|
|
<li><p>Al existir un mayor número de tags, hace que tardes
|
|
más en aprenderlos y como usarlos efectivamente.</p>
|
|
|
|
<p>La mejor manera de aprender es leer los fuentes de muchos
|
|
documentos de ejemplo, viendo como otros autores han escrito
|
|
información similar.</p></li>
|
|
|
|
<li><p>El proceso de conversión no es tan simple.</p></li>
|
|
</ul>
|
|
|
|
<p>Actualmente, el Proyecto está usando LinuxDoc para el
|
|
Handbook y las FAQ. Esto está cambiando, ya que se está
|
|
haciendo una migración de la documentación a DocBook.</p>
|
|
|
|
<h2>Qué pasa si no se LinuxDoc/DocBook? Todavía puedo
|
|
contribuir?</h2>
|
|
|
|
<p>Sí, por supuesto. Cualquier documentación es mejor
|
|
que no tener nada. Si tienes documentación con la que
|
|
contribuir y no está en formato LinuxDoc o DocBook, no
|
|
te preocupes.</p>
|
|
|
|
<p><a href="submitting.html">Envía</a> la documentación
|
|
de la manera habitual. Alguien del proyecto recogerá los
|
|
documentos enviados y los convertirá por tí. Con un
|
|
poco de suerte, te será devuelta ya marcada en DocBook. Así
|
|
puedes comparar el documento original con el que has recibido y
|
|
aprender a hacerlo tú mismo.</p>
|
|
|
|
<p>Obviamente, esto retrasa el que la documentación esté
|
|
online, pero no te preocupes.</p>
|
|
|
|
<h2>Má información sobre SGML y DocBook?</h2>
|
|
|
|
<p>Primero deberís leer el <a
|
|
href="&base;/../tutorials/docproj-primer/"><b>Documentation Project
|
|
Primer</b></a>. Es una extensa explicación de todo lo que
|
|
necesitas saber para poder trabajar con la documentación de
|
|
FreeBSD.</p>
|
|
|
|
<p>Es un documento largo, dividido en múltiples ficheros
|
|
diferentes de pequeño tamaño. También puedes
|
|
verlo en formato de <a
|
|
href="&base;/../tutorials/docproj-primer/book.html"><b>un sólo
|
|
fichero</b></a>.</p>
|
|
|
|
<dl>
|
|
<dt><a
|
|
href="http://www.oasis-open.org/cover/sgml-xml.html"><b>http://www.oasis-open.org/cover/sgml-xml.html</b></a></dt>
|
|
|
|
<dd><p>El web de SGML/XML. Incluye más recursos sobre SGML.</p></dd>
|
|
|
|
<dt><a
|
|
href="http://www-tei.uic.edu/orgs/tei/sgml/teip3sg/index.html"><b>http://www-tei.uic.edu/orgs/tei/sgml/teip3sg/index.html</b></a></dt>
|
|
|
|
<dd><p>The "Gentle Introduction to SGML". De recomendada lectura para
|
|
cualquiera que desee tener conocimientos avanzados de SGML.</p></dd>
|
|
|
|
<dt><a
|
|
href="http://www.ora.com/davenport/"><b>http://www.ora.com/davenport/</b></a></dt>
|
|
<dd><p>El DTD DocBook es mantenido por OASIS.
|
|
Estas páginas están pensadas para usuarios que
|
|
se sienten de manera confortable con SGML y quieren aprender
|
|
DocBook.</p>
|
|
</dd>
|
|
|
|
<dt><a
|
|
href="http://fallout.campusview.indiana.edu/~jfieber/docbook/"><b>http://fallout.campusview.indiana.edu/~jfieber/docbook/</b></a></dt>
|
|
|
|
<dd><p>La página de John Fieber contiene links a otros recursos
|
|
de DocBook y documentos de ejemplo. Tambié incluye una
|
|
guía de marcas para FreeBSD.</dd>
|
|
|
|
<dt><a
|
|
href="http://www.nothing-going-on.demon.co.uk/FreeBSD/"><b>http://www.nothing-going-on.demon.co.uk/FreeBSD/</b></a></dt>
|
|
|
|
<dd><p>La página de Nik Clayton contiene links a
|
|
documentación escrita y después convertida a HTML.
|
|
Los ficheros DocBook originales están disponibles, dando
|
|
una idea muy razonable de como usar los diferentes elementos
|
|
de DocBook.</p></dd>
|
|
|
|
<dt><a
|
|
href="http://wolfram.schneider.org/papers/webbuild.html"><b>
|
|
http://wolfram.schneider.org/papers/webbuild.html</b></a></dt>
|
|
|
|
<dd><p>
|
|
Este documento describe como crear y actualizar las páginas Web
|
|
de FreeBSD a mano desde el CVS.
|
|
</p></dd>
|
|
</dl>
|
|
|
|
|
|
<p></p><a href="docproj.html">FreeBSD Documentation Project Home</a>
|
|
&footer;
|
|
</body>
|
|
</html>
|