The concept is simple: Think source code embedded in documentation instead of documentation (comments) embedded in source code.
If you have to explain your program to an audience, you would not start with several hundreds of lines of boring include files. (Unless you are bad at oral presentations! :-) ) You would instead go directly to the interesting and complicated bits and then describe the overall layout. Or you could describe the overall layout first and then the tasty bits. In any case, the order of the program that is dictated by a typical programming language source code does not match any of the presentations above.
A literate programming tool is an advanced preprocessor that allows you to create a document that when read, describes the program in the same order as you would like to present it to an audince for maximum understanding and interest.
The key to its usefulness lies in that the documentation and the source code to be compiled are derived from the same document. This means that it is much easier to update both at the same time. If documentation are stored separately from the source code, its inevitable that documentation and source drift in synchronization. Sometimes, there is a permanent rift in between.
Ok, so we have an original source file: test.gw.
When this file is processed, the result is three files:
The documentation, test.html
The java source, Goo.java
The database source, database.sql
Literate programming was conceived by Knuth. You can read more about it and find other tools at the literate programming homepage. GWeb uses the same syntax as noweb.
I had to write gweb since there was no tool with good enough support for Java. The problem is that Java does not support the #line 123 "goo.gw" compiler directive. So, to make javac report the correct line in the gweb source, we have to parse the output of javac and patch the references. This is accomplished with the fixlines script.
Other neato things with gweb is direct support for html, instead of converting latex to html at a later stage. HTML is generated directly from the source.
GWeb will have typesetting of sourcecode and index of identifiers for multiple languages and support to extract interface descriptions, much like javadoc.