The main idea of literate programing is to write programs as mathematical texts. One can define what does it mean every concept needed in the program as clear as possible, then explain how it is implemented in the language and why one decided to do it in such way and not other or what is going to be changed later.
The changes can be also documented by commenting the piece of code to change and inserting the new one explaining the reason for the change.
Some changes may depend on transformations of the code to optimize it's performance. For example making one loop, instead of 2 loops in some C like language, change one expression for a simpler one, etc. Or something more complex like changing other data structure to represent information.
Every change is well justified and documented.
One can understand about the problem domain of the program, just reading the source code, understanding it in depth. Avoiding mistakes due to ambiguities.
The genesis of the program is completely documented, one can recall everything later, because every thought is in the program.
Strictly speaking one can write literate programs with plain text, if the program is developed, but typesetting it in TeX/LaTeX is the most aesthetic, functional and easiest way, because it is not difficult to place LaTeX markup within the most programming languages.
It is natural to write literate programs in Haskell, because a Haskell script contain a set of declarations not instructions. You can place all declarations in any order. That is different in other languages where it is important to order the instructions in a particular way.
I have not used web nor cweb or similar programs, but those programs help to typeset the programs in a logical order for a human, whereas the program modules can be generated for proper compilation.
There is a LaTeX package called listings which is easy to use you can start every piece of code closing the comment and ending the code opening a new comment, as far as I remember, something like this:
% /* begin of literate program
\documentstyle{article}
\usepackage{listings}
\lstdefinitions here I do not remember the syntax. Here one can define
a replacement for startcode*/ and /*endcode for spaces.
more definitions here
\begin{document}
Your explanation including formulas like $s=c\times\sum_{i=0}^{i=N} x_i$ etc.
\begin{lstlising}
startcode*/
s=0
for(i=0;i<=N;i++) s=s+x[i];
s=c*s;
etc..
/*endofcode
\end{lstlisting}
More explanation ...
\end{document}
% end of literate program */
in the preamble of the text you can define startcode*/ and /*endofcode as keywords to replace by spaces in the extra definitions for the listings package. See the package documentation.
at the end of the LaTeX source simply type:
% end of literate program */
which is a comment in LaTeX
in the beginning you can place the opposite:
% /* start of program
Removing the % LaTeX comment sign when you want to compile the program, and putting it again when compiling by LaTeX.
If you have never used LaTeX before, you can start with plain text first.
Maybe combining it with doxigen to index everything.
Doxigen is not needed with LaTeX because it is a typesetting system, where you can create several indexes, hyper-links, structure the documentation as a book.
Haskell programs are usually written in literate style. Maybe it is a good idea to browse some book or article to see one.
