6 ms·

LiteratePrograms.org: An Executable Wiki

35 points by andrewvc 15y ago

seles 15y ago
"a unique wiki where every article is simultaneously a document and a piece of code" <- except that article
- stewbrew 15y ago
  From what I gather they meant to say that you can download the code, which is automatically extracted from the wiki page. ctangle for mediawiki?
thangalin 15y ago
Knuth's literate programming is an excellent idea. The literate programming examples I have seen lack suitable modern integrated development environments. The idea of interweaving source code and commentary in a book style has few advantages over Javadocs, Doxygen, and the like. And they are more work for the developer. The concept of coupling comments to code is a good one. What we need to do is loosely source code to its comments using an intelligent editor. Mute the music and watch the end of the following video: http://www.youtube.com/watch?v=u3QqjhzhnAw&t=1m41s http://www.youtube.com/watch?v=u3QqjhzhnAw&t=1m41s Essentially, a dual panel editor. On one side is source code, on the other are the comments linked to each line in the source code. You could still generate the wiki-like interwoven documentation, but you could also generate the documentation as a single document (without source code). Further, since the documentation editor is independent of the source code editor, the documentation could be written using a simple mark-up. You could also embed business requirements within the commentary to suggest the exact business requirement being met by the code (using linked text and a single source; update the business requirement and you know what code needs to change). Conversely, formal technical documentation (user guides, administration manuals) could link directly to the source code commentary (a single source, once again). I'd be interested in reading the disadvantages to such a dual editor system.
v21 15y ago
The best example I can think for online, executable wikis is http://scraperwiki.com http://scraperwiki.com - it allows you to create web scrapers, then periodically runs the scrapers and offers up the data in a nicer feed. As it's a wiki, anyone can reuse the scraper, or fix it when the structure of the page changes and the scraper breaks. But it doesn't follow the example of literate programming, I guess largely because the code is generally boring, and written to quickly solve a problem, not primarily to act as an exemplar.
TeMPOraL 15y ago
I've been trying to do Literate Programming in one project and somehow I can't stop feeling like this is a big time sink (writing down all this prose) that ultimately makes programs harder to understand (single code module can be spread across half of the file) and harder to modify (when you change one part, you have to look through half of your prose to check if there is something to be removed/rephrased). I don't know, maybe I'm doing it wrong?
mckoss 15y ago
I wrote this site to combine Markdown documents and executable <script> sections. http://wiki.pageforest.com http://wiki.pageforest.com

35 points by andrewvc 15y ago

seles 15y ago

"a unique wiki where every article is simultaneously a document and a piece of code" <- except that article

stewbrew 15y ago
From what I gather they meant to say that you can download the code, which is automatically extracted from the wiki page. ctangle for mediawiki?

thangalin 15y ago

Knuth's literate programming is an excellent idea. The literate programming examples I have seen lack suitable modern integrated development environments. The idea of interweaving source code and commentary in a book style has few advantages over Javadocs, Doxygen, and the like. And they are more work for the developer. The concept of coupling comments to code is a good one. What we need to do is loosely source code to its comments using an intelligent editor. Mute the music and watch the end of the following video: http://www.youtube.com/watch?v=u3QqjhzhnAw&t=1m41s http://www.youtube.com/watch?v=u3QqjhzhnAw&t=1m41s Essentially, a dual panel editor. On one side is source code, on the other are the comments linked to each line in the source code. You could still generate the wiki-like interwoven documentation, but you could also generate the documentation as a single document (without source code). Further, since the documentation editor is independent of the source code editor, the documentation could be written using a simple mark-up. You could also embed business requirements within the commentary to suggest the exact business requirement being met by the code (using linked text and a single source; update the business requirement and you know what code needs to change). Conversely, formal technical documentation (user guides, administration manuals) could link directly to the source code commentary (a single source, once again). I'd be interested in reading the disadvantages to such a dual editor system.

v21 15y ago

The best example I can think for online, executable wikis is http://scraperwiki.com http://scraperwiki.com - it allows you to create web scrapers, then periodically runs the scrapers and offers up the data in a nicer feed. As it's a wiki, anyone can reuse the scraper, or fix it when the structure of the page changes and the scraper breaks. But it doesn't follow the example of literate programming, I guess largely because the code is generally boring, and written to quickly solve a problem, not primarily to act as an exemplar.

TeMPOraL 15y ago

I've been trying to do Literate Programming in one project and somehow I can't stop feeling like this is a big time sink (writing down all this prose) that ultimately makes programs harder to understand (single code module can be spread across half of the file) and harder to modify (when you change one part, you have to look through half of your prose to check if there is something to be removed/rephrased). I don't know, maybe I'm doing it wrong?

mckoss 15y ago

I wrote this site to combine Markdown documents and executable <script> sections. http://wiki.pageforest.com http://wiki.pageforest.com