Proyecto de Documentación de FreeBSD: SGML
El proyecto de Documentación usa SGML como método estándar de representar la documentación.
El nombre SGML viene de Standard Generalised Markup Language, que podría traducirse como "lenguaje de etiquetado estándar de propósito general".
Brevemente (y disculpas para los puristas de SGML que puedan sentirse ofendidos) SGML es un lenguaje para escribir otros lenguajes.
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 no está escribiendo SGML pero sí que está usando un lenguaje definido por SGML.
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 <tag contenido>). FreeBSD lo adoptó y definidó nuevos elementos para hacerlo más preciso.
Por ejemplo, así se escribiría un breve párrafo en HTML (no se preocupe del contenido, solo fíjese en las etiquetas):
<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>
El mismo párrafo en DocBook sería:
<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>
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.
Esta mayor expresividad tiene grandes ventajas:
-
No es ambiguo o inconsistente.
No se pierde tiempo pensando "?Hmm, necesito mostrar un nombre de fichero, ?debería usar "tt", o "b", o "em"?
En lugar de eso, use la etiqueta correcta para lo que quiera hacer.
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.
-
Dejar de pensar en cómo representar la documentación y concentrarse solamente en el contenido.
-
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.
-
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.
.
Si está familiarizado con ellos es como las galerías de estilo de Microsoft Word, sólo que infinitamente más potente.
Por supuesto, esta potencia tiene un precio:
Al existir un mayor número de etiquetas el aprendizaje es más largo y cuesta más trabajo aprender a usarlas.
La mejor manera de aprender es leer los fuentes de otros documentos para ver cómo representaron información similar otros autores.
El proceso de conversión no es tan simple.
?Qué pasa si no sabe DocBook? ?Todavía puedo ayudar?
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.
Envíe 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.
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.
? Necesita má información sobre SGML y DocBook?
Lo primero que deberí leer es el Documentation Project Primer. 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 un sola página.
- http://www.oasis-open.org/cover/sgml-xml.html
La web de SGML/XML. Incluye más recursos sobre SGML.
- http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html
El "Gentle Introduction to SGML". De recomendada lectura para cualquiera que desee tener conocimientos avanzados de SGML.
- http://www.oasis-open.org/docbook/
OASIS mantiene el DTD DocBook. Estas páginas están pensadas para usuarios con bastante experiencia con SGML y quieren aprender DocBook.