Tabla de Contenidos

Literate programming

<note>Borrador</note>

A comienzos de junio de 2009 dediqué unos días a explorar el concepto de “literate programming”. Si bien me había encontrado con él en varias oportunidades (principalmente a raíz de mi interés en la obra de D. Knuth), en esta ocasión finalmente leí varios artículos “importantes”, instalé herramientas, y hasta hice un experimento de conversión a LP de un script existente.

Algunos links: http://delicious.com/fgomez/literate_programming

En castellano he visto “literate” traducido como “literaria”, y también como “ilustrada” o “letrada”.

Sería interesante averiguar entre los estadísticos si conocen o usan R con Sweave; ver p.ej. http://cran.r-project.org/doc/contrib/Rivera-Tutorial_Sweave.pdf

El grupo comp.programming.literate parece muy inactivo desde hace unos años; sin embargo las discusiones interesantes sucedieron hace bastante tiempo, p.ej. ésta sobre noweb language independence de 1998.

Documentos

Algunos archivos (ps, pdf) están en mi notebook.

http://www.linuxjournal.com/article/2618 (Letters to the Editor, sobre el artículo de noweb)

Ver un mail mío sobre “Elucidative programming”.

N. Ramsey dice (en una discusión en comp.programming.literate): “This question suggests that maybe you don't “get” the literate-programming paradigm. I suggest you read some of Don Knuth's papers, and also the Don Lindsay LP column from CACM, with special attention to reviewer Harold Thimbleby's comments.” Busquemos eso de CACM!

Herramientas

Noweb

* Select (ejemplo sencillo)

Me gustaría poder contar con algunas herramientas adicionales en los editores (gedit, bluefish, otro?):

Con respecto al output HTML, me gustaría poder mejorar su aspecto con CSS. (Ya hice algo con nw-styles.html.)

También es necesario un mecanismo para partir un documento HTML grande en documentos más chicos linkeados (e.g. uno por sección). htmldoc genera cosas como este ejemplo. Leer estos posts; incluye fix para el problema con Unicode en htmldoc anterior a la v.1.8. OJO: htmldoc no arregla los links internos generados con reST! (ver bien)

Otra opción para dividir un HTML: Splity? (perl)

Integración con DokuWiki? (ver el ejemplo de integración con MediaWiki)

Discusiones interesantes en comp.programming.literate. (Creo que algunas ya fueron “rescatadas” en softpanorama o un sitio similar)

Probar noweb -t para generar todos los archivos en una pasada, como dice NR (1994): 

If you set up the names of the root chunks to correspond to the file
names, 'noweb -t' will generate all of the output files in one pass.
(Tip of the hat to Preston Briggs.)  It will also avoid updating
output files that have not changed, so
        'noweb -t; make'
will do what you want.

Ejemplos de makefiles para extracción automática de archivos: http://boris.reitman.name/notes.html#noweb

LyX

Integración con noweb: http://nuclear.gla.ac.uk/computing/LyX_doc/Extended.html#tth_sEc6.5

IMPORTANTE: incluye un ejemplo de cómo incluir un build-script dentro del mismo documento .nw. De esa manera no necesitamos un Makefile por cada proyecto, pues basta con invocar un script genérico que simplemente aplique notangle para extraer el chunk build-script y pasarlo al shell para que se ocupe del resto. Ver esa página y ejemplos en: 

$ find /usr/share/lyx/|xargs grep -l "build-script"
/usr/share/lyx/doc/Extended.lyx
/usr/share/lyx/examples/listerrors.lyx
/usr/share/lyx/examples/Literate.lyx
/usr/share/lyx/examples/noweb2lyx.lyx

Molestia: requiere “ctrl+return” para cada salto de línea dentro de un code chunk.

Ventaja: tiene Outline.

Editores

Varias veces quise aprender a usar uno de estos editores poderosos (como también quise aprender a tipear correctamente!). Creo que es una buena oportunidad para aprender vim. Bajé algunos ebooks sobre vim.

Gedit

Para poder tener un resaltado de sintaxis en Gedit (versión 2.22.3 en Ubuntu 8.04), usando reStructuredText como lenguaje de documentación, hice lo siguiente:

Queda por resolver una pequeña molestia: cómo hacer que Gedit asocie automáticamente un archivo con extensión nw con el resaltado de sintaxis para noweb. Quizás probando algo de esto: http://ubuntuforums.org/showthread.php?t=463344, http://ubuntuforums.org/showthread.php?t=368353 (no lo hice aún).

Lenguaje de documentación

La alternativa más “natural” para noweb es LaTeX. Sin embargo, me gustaría más usar un lenguaje como reST (reStructuredText), que es el usado para la documentación de Python y Django.

Una idea para probar: escribir .nw usando reST, convertir a LaTeX usando rst2latex, procesar con noweave as usual. Pero perderíamos la riqueza del HTML que genera rst2html.

reStructuredText

No encuentro páginas que hablen del uso combinado de noweb con rst. Busqué incluso +noweb “docutils-users” en Google.

Encontré esto pero no el código al que hace referencia: «I implemented a “literate programming system” called LitRE (“Literate REstructuredText”) that can extract and test examples.»

Hice unos experimentos en la notebook (~/dev/noweb/rst) y parece que va bien; desde luego quedan detalles para pulir. (Movido a ~/unison/noweb)

Experimentos iniciales

Aplicación a OpacMarc

LP me parece un método atractivo para aplicar a la documentación de OpacMarc. Un primer problema es el de decidir cómo organizar el texto. La tentación inicial es mirar cómo está organizado el código, y usar eso como guía para armar la estructura del documento. Pero quizás más interesante sería pensar en la descripción del sistema a un nivel un poco más alto, es decir, no tan atado a esta implementación concreta, sino a ciertos conceptos generales de lo que “debería” ser un OPAC, siguiendo p.ej. el libro de Yee y Shatford Layne. De esta manera, el documento resultaría ser una descripción de un “OPAC ideal” (en el sentido del libro mencionado), acompañada por la descripción de una implementación imperfecta, aproximada, de ese OPAC. Con este enfoque, ciertas cuestiones propias de la implementación, como p.ej. los trucos usados para generar los índices a partir de la base bibliográfica, quedarían posiblemente relegados a un apéndice de “detalles técnicos”.

El texto debería indicar cuál es el público al que está dirigido, especificar “design goals”, etc.

LP y Python

Durante mi primer acercamiento a LP (junio 2009), no había encontrado nada que pareciese satisfactorio en cuanto a Python + LP. En septiembre de 2009 ya veo

Agosto 5, 2010: En un chat con Nico Pace, me dice “programación narrativa”, y antes de pensar que es un error busco en Google. Llego a esto: https://secure.sabren.com/svn/workshop/trunk/code/narrative.py

El libro de Knuth

Al fin lo tengo! Comprado en Amazon y traído por Flavio Pardo desde USA.

Stack Overflow

“Stack Overflow is a collaboratively edited question and answer site for programmers”. Muy buena calidad de preguntas y respuestas. Algunas relacionadas con LP:

Sistemas desarrollados usando LP

Leo

Fin de 2009: decidí explorar Leo. Motivaciones: el espíritu de fin de año, una respuesta recibida en docutils-users aconsejando el uso de Leo, mis insatisfacción con mis actuales herramientas (gedit + nwrst), y la buena promoción que tiene Leo (abundante documentación, usuarios satisfechos, desarrollo activo).

Links: Home page, Slashdot article.

Problemas:

Decidí dejar Leo para otro momento, y volver a intentar hacer un backend para noweb que emita reST.

Sphinx

Instalación en la notebook con Ubuntu Hardy: 

$ sudo easy_install -U Sphinx

(no hay paquete para Hardy, sí para las siguientes versiones de Ubuntu).

Se instala en 

/usr/lib/python2.5/site-packages/Sphinx-0.6.3-py2.5.egg/

LP y UML

(La idea de buscar material en la intersección de UML con LP surgió de una charla con Nicolás Pace, 15/sep/2010.)

Bibliografía