Muy Bueno

DDDELUCHI — Thu, 08 Sep 2005 13:33:21 -0700

Si es muy buen sistema.
Slds
Diego de http://www.dddeluchi.com.ar

ECAL: Dox, un buen sistema para manejar documentación

clbustos — Wed, 11 May 2005 14:27:35 -0700

Una de las cosas agradables de programar PHP en Windows era el manual de PHP en formato .chm. El sistema de índices y de ayuda hacía la búsqueda de información muy rápida, especialmente considerando lo arbitrario del uso de parámetros en las funciones de string

Al pasar a Linux, una de las cosas que extrañé era, precisamente, mi ayuda de php. Primero, intenté usar xchm; claro, se veía, pero no tenía para nada la facilidad de uso del original.

Dando vueltas por Linux Links, encontré la referencia a un programita llamado Dox. Justo lo que me recetó el doctor

¿Qué gracias tiene?

Ocupa el clásico esquema de tres pestañas, siendo la primera el íncide de manuales, la segunda el listado de índices y el tercero la búsqueda.
Puede leer todos los man e info y viene con la documentación de la librería estandar de C y la STL
Es fácilmente extensible, a través de la incorporación de páginas en HTML, con un sencillo formato xml para los índices y las tablas de contenido

Me interesa destacar el punto de la extensibilidad. Si alguien trató de hacer alguna vez un manual en chm, se debe haber dado cuenta que es endemoniadamente enredado, como todo lo que viene de Windows. En Dox, la cosa es super simple:

Lo primero es ver donde (/·$&· está guardada la información. En mi Gentoo está en /usr/share/dox y si se instala manualmente debería quedar en /usr/local/share/dox.
El directorio de dox contiene 5 subdirectorios. Los que nos interesan se llaman html, indices y tocs
Si se quiere agregar un manual, se debe copiar o hacer un symlink de los html dentro de html. El nombre de este directorio debe ser igual al del archivo con indices y la tabla de contenidos.
En tocs deben incorporar un archivo con el nombre del directorio + ".toc". Un ejemplo de código sería:
1. <!DOCTYPE doxtoc0>
2. <doxtoc0>
3. <title>Mi manual</title>
4. <base href='/home/mi_cuenta/mi_manual/html'/>
5. <tocsect1 name='1.- Intro' url='intro.html'>
6. <tocsect2 name='1.1.- Primera parte Intro' url="intro_1.html" />
7. </tocsect1>
8. <tocsect1 name='Foreword' url='foreword.html' />
9. </doxtoc0>
La tabla de indices va en el subdir "indices" y debe llevar el nombre del directorio +".index". Por ejemplo:
1. <!DOCTYPE doxindex0>
2. <doxindex0>
3. <title>Mi manual</title>
4. <base href='/home/mi_cuenta/mi_manual/html'/>
5. <item primary="perno" topic="perno" url="perno.html" />
6. <item primary="perno" topic="perno, tuerca" url="perno.html#tuerca" />
7. <item primary="perno" topic="perno, metal" url="perno.html#metal" />
8. <item primary="rodamiento" topic="rodamiento" url="rodamiento.html" />
9. </doxindex0>
Este código nos crearía dos entradas nuevas en el índice. En la primera, se incluirían tres subtemas, el primero llamado "perno", el segundo "tuerca" y el tercero "metal". Siempre al lado de cada término se incluye el nombre del manual, para evitar confusiones

Eso sería por ahora. Es una herramienta que realmente recomiendo, por su versatilidad, rapidez y facilidad para extender. Aparte que no se me ha caído todavía :)

Php y otras yerbas - ECAL: Dox, un buen sistema para manejar documentación - Comentarios

Muy Bueno

ECAL: Dox, un buen sistema para manejar documentación