CatalisWiki

Esta página es de solo lectura. Puedes ver la fuente pero no puedes cambiarla. Pregunta a tu administrador si crees que esto es incorrecto.
====== 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 [[http://groups.google.com/group/comp.programming.literate/browse_thread/thread/577492d8e32d6772/|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
  * Leo
  * LyX
  * nuweb
  * literate programs wiki
  * ...

==== Noweb ====

 * [[http://moonflare.com/code/select/index.php|Select]] (ejemplo sencillo)


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

  * Resaltado de sintaxis, a nivel de noweb (no ya de cada lenguaje utilizado). P.ej. para distinguir los "''%%<<...>>=%%''" y tal vez para marcar con otro color los bloques de docs (delimitados entre "''^@[espacio]''" y "''%%^<<...>>=%%''")
  * Outline browser en el panel lateral (similar al class browser plugin de gedit), que permita acceder fácilmente a los code chunks y a los títulos de secciones/subsecciones. (En castellano, "outline" se puede traducir como "esquema", al menos así aparece en MS Word.)
  * Herramientas LaTeX (e.g. toolbar buttons) para archivos .nw

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 [[http://txt2tags.sourceforge.net/userguide/index.html|este ejemplo]]. Leer [[http://txt2tags.wordpress.com/?s=htmldoc|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)

  * [[http://groups.google.com/group/comp.programming.literate/browse_thread/thread/9664e6d1bb068f96/|several docs from the same noweb file?]] (1994)
  * [[http://groups.google.com/group/comp.programming.literate/browse_thread/thread/8fcb5f51b9c2ca3a/|non-intrusive literate programming?]] (1999)

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

<file>
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. 
</file>

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:

<code>
$ 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
</code>

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

Ventaja: tiene Outline.

==== Editores ====

  * vim y familia (vi, gvim, cream)
  * emacs
  * gedit
  * bluefish
  * geany
  * scribes
  * . . .

  * [[http://www.vim.org/scripts/script.php?script_id=2129|Noweb : A hacked-up noweb syntax file]] (vim)
  * [[http://www.mpi-inf.mpg.de/~michail/software.shtml|Vim's manual folding for noweb and Lweb]]
  * [[http://dfan.org/real/noweb-outline.html|noweb-outline.el]] is a mode for Emacs that allows you to easily navigate the chunk tree of a noweb program.

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:

  * Creé los archivos ''rst.lang'' y ''noweb.lang'', que usan la sintaxis xml correspondiente a gtksourceview 2.0. En ''noweb.lang'' se hace referencia a ''rst.lang'' para el resaltado de los bloques de documentación. Los guardo en algún directorio de mi home, preferiblemente bajo control de versiones. (Los puse al principio en '~/.gnome2/gtksourceview-2.0/language-specs/', pero luego los moví.)
  * Para que gedit los encuentre, creé links simbólicos a esos archivos en ''/usr/share/gtksourceview-2.0/language-specs/''. De esa forma, en el menú //View -> Highlight mode// de Gedit aparecen las dos nuevas opciones.
  * Los archivos ''.lang'' hacen referencia a los estilos que se definen en un archivo ''.xml''. Los originales están en ''/usr/share/gtksourceview-2.0/styles/'' **CONTINUAR** FIXME

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.

  * [[http://trac.edgewall.org/wiki/WikiRestructuredText|reStructuredText como wiki markup en Trac]]
  * [[http://pylit.berlios.de/literate-programming.html|PyLit]]


=== reStructuredText ===

  * [[http://docutils.sourceforge.net/rst.html|Página principal de reST]]
  * [[http://goldenspud.com/rest-wordpress/|reST plugin para WordPress]] ("a simple wrapper for Docutils' reStructuredText"). Podría servir para DokuWiki?
  * [[http://docutils.sourceforge.net/tools/editors/|editor support]]
  * [[http://textmethod.com/wiki/ReStructuredTextToolsForGedit|reStructuredText Tools for Gedit]]

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 =====

  * [[http://catalis.uns.edu.ar/reclas-inmabb/reclas.html|Reclasificación de libros del INMABB]]
  * noweb-rst: soporte para documentos noweb escritos con reStructuredText.


===== 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 

  * [[http://stackoverflow.com/questions/1267280/whats-the-best-way-to-do-literate-programming-in-python-on-windows|What’s the best way to do literate programming in Python on Windows?]]
  * [[http://homepage.mac.com/s_lott/steve/python/index.html#literate-programming-with-pyweb|Literate Programming with pyWeb]]
  * [[http://homepage.mac.com/s_lott/_static/pyweb/pyweb.html|pyWeb. In Python, Yet Another Literate Programming Tool]] (Tiene fecha 2003. ¿Cómo no lo había encontrado antes?) Ver también: http://sourceforge.net/projects/pywebtool/ y http://architects.dzone.com/news/literate-programming

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:

  * [[http://stackoverflow.com/questions/1246406/intuitive-motivation-for-literate-programming|Intuitive motivation for Literate Programming?]]
  * [[http://stackoverflow.com/questions/219168/literate-programming|Literate programming]]
  * [[http://stackoverflow.com/questions/152160/using-noweb-on-a-large-java-project|Using noweb on a large Java project]]
  * [[http://stackoverflow.com/questions/299076/scaling-literate-programming|Scaling Literate Programming?]]
===== Sistemas desarrollados usando LP =====

  * [[http://www.pbrt.org/|Physically Based Rendering]]. "The rendering system described in this book is itself highly readable, written in a style called //literate programming// that mixes text describing the system with the code that implements it. Literate programming gives a gentle introduction to working with programs of this size. This lucid pairing of text and code offers the most complete and in-depth book available for understanding, designing, and building physically realistic rendering systems." (Encontrado vía [[http://stackoverflow.com/questions/299076/scaling-literate-programming|Stack Overflow]]. Ver además una descripción en [[http://www.literateprogramming.com|literateprogramming.com]].)

  * [[http://inform7.com/|Inform]]. "Inform is a design system for interactive fiction based on natural language. It is a radical reinvention of the way interactive fiction is designed, guided by contemporary work in semantics and by the practical experience of some of the world's best-known writers of IF." And then: "The main aim of the Inform project since autumn 2007 has been to publish the whole work. [...] We believe it will then be the largest literate program ever published." La sorpresa está en [[http://inform7.com/sources/inweb/|Inweb: The literate programming tool used by Inform]]. La [[http://inform7.com/sources/src/inweb/Woven/Complete.pdf|documentación de inweb]] (que está escrito en él mismo) contiene una detallada explicación de las razones que llevaron al autor a crear su propia herramienta para LP, luego de probar con ''CWEB''. (Encontrado de casualidad (se dice //serendipity//!) mientras buscaba ''weaving tangling -hair'' en Google.) Leer el **[[http://inform7.com/sources/src/inweb/Woven/P-man.pdf|User Manual for Inweb]]** (19 pp.). Según el autor, //inweb// es una versión mejorada de CWEB; está orientado a TeX (sí, plain TeX; nada de LaTeX), y a PDF como salida (no vi ejemplos de salida HTML, ni se menciona en el manual, aunque desde luego debería poder generarse a partir del .tex).

  * Axiom

  * [[http://www.stanford.edu/~blp/avl/|GNU libavl]], "the most complete, well-documented collection of binary search tree and balanced tree library routines anywhere." ... "Version 2.0 of libavl was released on January 6, 2002. It is a complete rewrite of earlier versions implemented in a “literate programming” fashion, such that in addition to being a useful library, it is also a book describing in full the algorithms behind the library."

===== 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: [[http://webpages.charter.net/edreamleo/front.html|Home page]], [[http://developers.slashdot.org/article.pl?sid=02/08/28/1655207&tid=156|Slashdot article]].

Problemas:

  * Qué versión instalar en mi (ya viejo) Ubuntu 8.04 Hardy. Las versiones más recientes (4.6.x, 4.7 beta) tienen problemas de dependencias; por otra parte son más atractivas porque usan Qt con lo que se mejora el aspecto de la interfaz gráfica. Por ahora probemos con una versión vieja: 4.5.1, de sep. 2008, que funciona bien (notebook). http://sourceforge.net/projects/leo/files/. Esto puede ser útil en algún momento: [[http://erl.nfshost.com/2008/10/11/installing-antialiased-leo-on-ubuntu/|Installing antialiased Leo on Ubuntu]]. En mi PC del inmabb, también con Ubuntu Hardy, Leo 4-6-b1 funciona.

  * Cómo hacer el weaving. Ver [[http://groups.google.com/group/leo-editor/browse_thread/thread/91009fb6f2aa25e4/85d9ef7aef6ee0fc|Weave as rsT]], [[http://groups.google.com/group/leo-editor/browse_thread/thread/16272ea3cee6b8eb/6d1840dec44a6268|Producing Latex documents from Leo]], [[http://groups.google.com/group/leo-editor/browse_thread/thread/3cd5cb06d32264d/18eb92fb715af5f2|rst3 and section names]], [[http://leo.zwiki.org/RstEmacs|RstEmacs]]. Mi primera conclusión ---basada en la lectura de los mensajes en el grupo--- es que no parece trivial hacer con Leo lo que con noweave es tan simple. Hay un gran énfasis en que "la mejor manera de entender el código es mediante outlines", y la generación de un documento lineal (a la noweave) está un tanto relegada.

  * Cómo "importar" en Leo el código noweb de Litero.

  * Uso de Leo con control de versiones. Ver [[http://webpages.charter.net/edreamleo/FAQ.html#how-should-i-use-leo-with-bzr-git-hg-svn-cvs|How should I use Leo with bzr/git/hg/svn/cvs?]].

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.)

  * [[http://eprints.ucl.ac.uk/933/|Literate modelling: capturing business knowledge with the UML]]
  * [[http://www.tug.org/TUGboat/Articles/tb24-1/moon-uml.pdf|Literate programming meets UML]]

===== Bibliografía =====

  * [[http://xml.coverpages.org/xmlLitProg.html|SGML/XML and Literate Programming]]

  * [[http://www.google.com/search?tbs=bks:1&tbo=1&q=%22literate+programming%22&btnG=Search+Books|Google Book Search]]

  * [[http://portal.acm.org/citation.cfm?id=129057|Trabajos que citan el libro de Knuth]]

  * [[http://slott-softwarearchitect.blogspot.com/2010/03/literate-programming-life-cycle.html|Literate Programming Life Cycle]]