Diferencia entre revisiones de «Documentación en Software libre»

En el mundo del software libre, apenas se usan procesadores de texto WYSIWYG y otras herramientas ofimáticas que tanto éxito tienen en otros entornos, a pesar de haber ya herramientas libres, como OpenOffice. Ello es debido a varios factores importantes:

• Es conveniente mantener la documentación bajo control de fuentes, y los sistemas de control de fuentes, como CVS, aunque admiten formatos binarios, prefieren formatos textuales transparentes, editables con un editor de texto normal y procesables con herramientas desarrolladas para programas, que nos permitan ver fácilmente las diferencias entre versiones, generar y aplicar parches basados en esas diferencias, y realizar operaciones de mezcla.

Nota: En Unix las herramientas que hacen estas operaciones más comunes son diff, diff3, patch y merge.

• Ciertas licencias de documentación libre, especialmente la GFDL (“Licencia de documentación libre de GNU”), exigen formatos transparentes, sobretodo por facilitar el trabajo a los que realicen documentos derivados.

• Las herramientas WYSIWYG (what you see is what you get) generalmente no contienen más información que la estricta de visualización, haciendo muy difícil, si no imposible, el procesamiento automático, como identificar autores o título, y la conversión a otros formatos. Incluso aunque permitan conversión de formatos, ésta suele hacerse de forma interactiva, siendo muchas veces imposible automatizarla (con make, por ejemplo).

• Generalmente las herramientas ofimáticas generan unos formatos de ficheros muy voluminosos, asunto muy desagradable para los desarrolladores o los repositorios.

Por todo ello el programador libre, acostumbrado también a programar y compilar, prefiere formatos de documentación transparentes, en muchos casos simple texto puro, en muchos otros formatos de documentación procesables.

Los formatos procesables utilizados no son muchos. Tradicionalmente en el mundo Unix los programas se han documentado en los formatos esperados por la familia de procesadores roff, con versión libre[groff] de Norman Walsh. No obstante esta práctica se ha ido abandonando, excepto para las páginas de manual tradicionales, ya que es casi obligado preparar páginas de manual para las herramientas más básicas del sistema. Debido a que muchas páginas de manual han crecido excesivamente, de modo que difícilmente se les puede llamar páginas, fue necesario elaborar un formato alternativo hiper-textual, que permitiera seguir documentos estructurados con índices y referencias cruzadas. El proyecto GNU diseñó el formato texinfo[texinfo] y lo convirtió en su estándar. Este formato permite obtener documentos navegables con la herramienta info o dentro del editor emacs, y a su vez obtener documentos impresos de calidad con ayuda del procesador de textos TeX, de Donald Knuth[knuth:tex].

El formato texinfo puede traducirse a HTML multipágina si se desea, y mucha gente prefiere ver la información con un navegador Web, pero se pierde la capacidad de búsqueda de palabras en un documento. Esta es una de las consecuencias indeseables de la popularidad de HTML, ya que los navegadores no implementan el concepto de documento multipágina, a pesar de que existen elementos link que permiten enlazar las partes.

Existe una imperiosa demanda de que los documentos complejos se puedan ver como páginas Web multipágina fácilmente navegables. Hay gente que escribe documentación en LaTeX[lamport:latex], también aplicación de TeX, muy popular entre los científicos, más expresivo que Texinfo, y convertible a HTML multipágina con ciertas herramientas[goosens:texweb], siempre que se guarde cierta disciplina. En efecto, las aplicaciones de TeX son conjuntos de macros que combinan operadores tipográficos de muy bajo nivel para convertirlos en lenguajes abstractos que trabajan con conceptos de alto nivel (autor, título, resumen, capítulo, apartado, etc.). Si sólo se utilizan las macros básicas, la conversión es sencilla. Pero como nadie impide usar operadores de bajo nivel y, además, existen cantidades enormes de paquetes de macros fuera de la capacidad de mantenimiento de los mantenedores de los conversores, es difícil conseguir que las conversiones salgan bien.