Antiguo BlogDocumentaciónRevisadas

Proyecto Paraíso: hacia un mejor sistema de documentación

Revisando formatos de documentación, y como no las ya míticas manpages, he seguido el rastro de doclifter, una herramienta que al parecer convierte el formato Troff, Groff o como se llame a Docbook XML, la cual conozco a raíz de las publicaciones de Ismael Olea en su página personal y en diversas listas de distribución..

Aunque ya había hecho varias indagaciones al respecto, hoy me he encontrado con una página cuyo título “Project Paradise: Towards a Better Documentation System” me ha llamado la atención (¿me estaré soltando ‘algo’ con el Ingles?).

Aunque no lo he leído a fondo, parece ser un proyecto que puso en marcha por Eryc Raymond, a quien tengo pendiente llamar cuando hable Inglés :p, para convertir las páginas man (manpages) a Docbook XML con el objetivo de facilitar su mantenimiento. Para ello se pensaba utilizar una herramienta desarrollada por el mismo llamada doclifter, mayormente la misma que he comentado antes.

The doclifter program translates documents written in troff macros to DocBook. Lifting documents from presentation level to semantic level is difficult, and a really good job requires human polishing, but this tool does about 95% of the work. It aims to do everything that can be mechanized, and to preserve in XML comments any troff-level information that might have structural implications. Also includes manlifter, a driver script that can be used to convert entire manual-page hierarchies.

Desconozco en que quedó el proyecto, pero parece ser que estaba prácticamente conseguido o al menos eso quiero entender el artículo publicado.

On a stock Fedora Core 2 system, doclifter successfully converts over 96% of 10,897 manual pages to validated XML-DocBook . I have about 270 trivial patches for broken markup that push the clean-conversion rate to over 99%, leaving only about 80 pages that cannot be converted. Of these patches, about 40 have been accepted by upstream maintainers.

En fin, habrá que intentar retomarlo… ¿no?

[catb.org]~$ Project Paradise: Towards a Better Documentation System