52f6d56540
- Replace /XML/{doc,www}/ with /XML/ in SysId.
- Remove empty stylesheets in share/xsl and point share/xml/empty.xsl via
XML catalog instead.
- Change the L10N layer in freebsd-*.xsl not to use localized XSLT
stylesheets directly.
- Move share/xsl/* to share/xml and remove share/xsl.
- Remove obsolete share/web2c/pdftex.def.
177 lines
6.7 KiB
XML
177 lines
6.7 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
|
|
"http://www.FreeBSD.org/XML/share/xml/xhtml10-freebsd.dtd" [
|
|
<!ENTITY title "Proyecto de Documentación de FreeBSD: SGML">
|
|
]>
|
|
|
|
<!-- The FreeBSD Spanish Documentation Project
|
|
Original Revision: r1.28 -->
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>&title;</title>
|
|
|
|
<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
|
|
</head>
|
|
|
|
<body class="navinclude.docs">
|
|
|
|
<p>El proyecto de Documentación usa SGML como
|
|
método estándar de representar la documentación.</p>
|
|
|
|
<p>El nombre SGML viene de <b>S</b>tandard <b>G</b>eneralised
|
|
<b>M</b>arkup <b>L</b>anguage, que podría traducirse
|
|
como "lenguaje de etiquetado estándar de
|
|
propósito general".</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 haya usado SGML sin saberlo. HTML, el lenguaje en el
|
|
que se escriben las páginas web, tiene una descripción
|
|
formal. Esta descripción se escribió en SGML. Cuando
|
|
escribe en HTML <b>no</b> está escribiendo SGML pero sí
|
|
que está 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 "DocBook".
|
|
Éste es un lenguaje diseñado específicamente para
|
|
escribir documentación técnica y tiene muchas etiquetas
|
|
o "tags", (por ejemplo <tt><tag contenido></tt>).
|
|
FreeBSD lo adoptó y definidó
|
|
nuevos elementos para hacerlo más preciso.</p>
|
|
|
|
<p>Por ejemplo, así se escribiría un breve párrafo
|
|
en HTML (no se preocupe del contenido, solo fíjese en las
|
|
etiquetas):</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 en 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 puede ver DocBook es mucho más expresivo que HTML. En el
|
|
ejemplo HTML el nombre del fichero se muestra con un tipo de letra
|
|
de máquina de escribir. En el ejemplo de DocBook, el nombre
|
|
de fichero lleva la etiqueta "filename" (nombre de fichero); la
|
|
representación de un nombre de fichero no está
|
|
descrita.</p>
|
|
|
|
<p>Esta mayor expresividad tiene grandes ventajas:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>No es ambiguo o inconsistente.</p> <p>No se pierde tiempo
|
|
pensando "?Hmm, necesito mostrar un nombre de fichero,
|
|
?debería usar "tt", o "b", o "em"?</p>
|
|
|
|
<p>En lugar de eso, use la etiqueta correcta para lo que quiera
|
|
hacer.</p>
|
|
|
|
<p>El proceso de conversión de DocBook a otros formatos como
|
|
HTML o Postscript garantiza que la presentación de todos
|
|
ellos será la misma.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Dejar de pensar en cómo representar la documentación
|
|
y concentrarse solamente en el contenido.</p></li>
|
|
|
|
<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á familiarizado con ellos es como las galerías
|
|
de estilo de Microsoft Word, sólo 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 etiquetas el aprendizaje
|
|
es más largo y cuesta más trabajo aprender a
|
|
usarlas.</p>
|
|
|
|
<p>La mejor manera de aprender es leer los fuentes de otros
|
|
documentos para ver cómo representaron información
|
|
similar otros autores.</p></li>
|
|
|
|
<li><p>El proceso de conversión no es tan simple.</p></li>
|
|
</ul>
|
|
|
|
<h2>?Qué pasa si no sabe DocBook? ?Todavía
|
|
puedo ayudar?</h2>
|
|
|
|
<p>Sí, por supuesto. Un poco de documentación es mejor
|
|
que no tener nada. Si tiene documentación con la que
|
|
contribuir y no está en formato DocBook no se preocupe.</p>
|
|
|
|
<p><a href="submitting.html">Envíe</a> la documentación
|
|
de la manera habitual. Algún miembro del proyecto
|
|
recogerá los documentos que envíe y trabajará
|
|
en ellos. Con un poco de suerte le enviarán una copia
|
|
ya etiquetada en DocBook. Así podrá comparar el
|
|
documento original con el que reciba y podrá ir aprendiendo
|
|
a hacerlo usted mismo.</p>
|
|
|
|
<p>Obviamente esto retrasa el que la documentación esté
|
|
online porque su documento requiere un trabajo adicional. Esto
|
|
puede suponer unas horas o unos días pero de cualquier modo
|
|
llegará a su destino.</p>
|
|
|
|
<h2>? Necesita má información sobre SGML y
|
|
DocBook?</h2>
|
|
|
|
<p>Lo primero que deberí leer es el <a
|
|
href="&base;/../doc/en_US.ISO8859-1/books/fdp-primer/index.html">
|
|
<b>Documentation Project Primer</b></a>. Es una extensa
|
|
explicación de todo lo que necesita saber para poder trabajar
|
|
con la documentación de FreeBSD. Es un documento largo,
|
|
dividido en múltiples páginas diferentes de pequeño
|
|
tamaño. También puede verlo en formato de <a
|
|
href="&base;/../doc/en_US.ISO8859-1/books/fdp-primer/book.html"><b>un sola página</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>La web de SGML/XML. Incluye más recursos sobre SGML.</p></dd>
|
|
|
|
<dt><a
|
|
href="http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html"><b>http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html</b></a></dt>
|
|
|
|
<dd><p>El "Gentle Introduction to SGML". De recomendada lectura para
|
|
cualquiera que desee tener conocimientos avanzados de SGML.</p></dd>
|
|
|
|
<dt><a
|
|
href="http://www.oasis-open.org/docbook/"><b>http://www.oasis-open.org/docbook/</b></a></dt>
|
|
|
|
<dd><p>OASIS mantiene el DTD DocBook. Estas páginas
|
|
están pensadas para usuarios con bastante experiencia
|
|
con SGML y quieren aprender DocBook.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p></p><a href="docproj.html">Inicio del Proyecto de Documentación de FreeBSD</a>
|
|
|
|
</body>
|
|
</html>
|