El proyecto de Documentación intenta usar SGML como método estándar de representar la documentación.
SGML es el lenguaje Standard Generalised Markup L.
Brevemente (y disculpas para los puristas de SGML que puedan sentirse ofendidos), SGML es un lenguaje para escribir otros lenguajes.
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 no estás escribiendo SGML, pero sí estás 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 "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ó.
Otro lenguaje "markup" definido usando SGML es el llamado "DocBook". Este es un lenguaje diseñado específicamente para escribir documentación técnica.
Por ejemplo, así estaría escrito un breve párrafo en HTML (no te preocupes del contenido, solo fíjate en los tags):
The system's passwords are stored in /etc/passwd. To edit
this file you should use vipw. However, if you just
want to add a new user you can use adduser.
]]>
El mismo párrafo usando DocBook sería:
The system's passwords are stored in
/etc/passwd . To edit this file you should use
vipw . However, if you just want to add a new user
you can use adduser .
]]>
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.
Hay grande ventajas en esta manera más expresiva de lenguaje:
No es ambiguo o inconsistente.
No pierdes tiempo pensando "Hmm, necesito mostrar un nombre de fichero, debería usar "tt", o "b", o "em"
En lugar de eso, usas el tag correcto para el trabajo correcto.
El proceso de conversión de DocBook a otros formatos como HTML o Postscript asegura que todos serán vistos de la misma manera.
Dejar de pensar en como representar la documentación, y solo te concentras 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ás familiarizado con ellos, es como las galerías de estilo de Microsoft Word, solo que infinitamente más potente.
Por supuesto, esta potencia tiene un precio;
Al existir un mayor número de tags, hace que tardes más en aprenderlos y como usarlos efectivamente.
La mejor manera de aprender es leer los fuentes de muchos documentos de ejemplo, viendo como otros autores han escrito información similar.
El proceso de conversión no es tan simple.
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.
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.
Enví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.
Obviamente, esto retrasa el que la documentación esté online, pero no te preocupes.
Primero deberís leer el Documentation Project Primer. Es una extensa explicación de todo lo que necesitas saber para poder trabajar con la documentación de FreeBSD.
Es un documento largo, dividido en múltiples ficheros diferentes de pequeño tamaño. También puedes verlo en formato de un sólo fichero.
El web de SGML/XML. Incluye más recursos sobre SGML.
The "Gentle Introduction to SGML". De recomendada lectura para cualquiera que desee tener conocimientos avanzados de SGML.
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.
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.
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.
Este documento describe como crear y actualizar las páginas Web de FreeBSD a mano desde el CVS.