646ddd7e13
english sub directories: cgi, commercial, gallery, gifs which are redundant and will never be translated and the spanish sub directories: doc-es, docs-es Submitted by: "Jesus Rodriguez" <jesusr@ncsa.es> Fix Makefiles errors. `Make all install' runs fine. Currently, many the links to the sub directories cgi, commercial, gallery, gifs are broken. The links should point to the English orginal files.
173 lines
7.6 KiB
Text
173 lines
7.6 KiB
Text
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [
|
|
<!ENTITY base CDATA "..">
|
|
<!ENTITY date "$Date: 1999-02-08 19:26:11 $">
|
|
<!ENTITY title "Proyecto de Documentación de FreeBSD: SGML">
|
|
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
|
|
]>
|
|
<!-- $Id: sgml.sgml,v 1.1.1.1 1999-02-08 19:26:11 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>
|
|
|
|
<dl>
|
|
<dt><a
|
|
href="http://www.sil.org/sgml/sgml.html"><b>http://www.sil.org/sgml/sgml.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 Grupo Davenport diseñó y mantiene el DTD
|
|
DocBook. Estas páginas están pensadas para usuarios que
|
|
se sienten de manera confortable con SGML y quieren aprender
|
|
DocBook.</p>
|
|
<p>La Documentación DocBook está disponible en formato PDF
|
|
en <a href="http://www.freebsd.org/~wosch/docbook/">http://www.freebsd.org/~wosch/docbook/</a></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>
|
|
</dl>
|
|
|
|
|
|
<p></p><a href="docproj.html">FreeBSD Documentation Project Home</a>
|
|
&footer
|
|
</body>
|
|
</html>
|