

LiteratePrograms.org: An Executable Wiki - andrewvc
http://en.literateprograms.org/LiteratePrograms:Welcome

======
thangalin
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
The best example I can think for online, executable wikis is
<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
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?

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

~~~
stewbrew
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?

------
mckoss
I wrote this site to combine Markdown documents and executable <script>
sections.

<http://wiki.pageforest.com>

