Literate programming is all about explaining how computer programs work at the same time as actually getting them to work. If you are the sort of person who likes explaining things to an audience, you will probably like literate programming. (If not, you probably won't.)
Knuth introduced the ideas of literate programming in the early 1980s through a pre-processible form of Pascal which he called WEB (described in a famous paper published in The Computer Journal in 1984.) Since then, the ideas has been adapted to many other programming languages, and even a language-independent idiom called noweb. The most comprehensive current reference is Daniel Mall's literate programming site.
There are three keys ideas in literate programming.
The first idea is summarized by slightly paraphrasing the opening of the book TeX the Program:
A literate program is an ordinary computer program that has been cut up and rearranged to make it easier for a human to understand. An ordinary computer program is a literate program that has been cut up and rearranged to make it easier for a computer to understand.
Literate programs resemble pseudo-code used for explaining
algorithms more than ordinary code. Or rather, they resemble a lot of
small pieces of pseudo-code all hyperlinked together. (This was why
Knuth called his first literate programming system WEB,
though it long predated what we now call the web.)
You run literate program source through a preprocessor called
tangle (or similar) and then compile in the usual way.
The second idea is formatting and cross-referencing of the
code. For this you run literate program source through a preprocessor
called weave (or similar) to get a document. Almost
invariably the document is in TeX/LaTeX, though any
document-formatting language could be used.
The elaborateness of weave varies. The
language-independent noweb system provides only the bare
bones of formatting and cross-referencing, whereas CWEB
and Rambutan have syntax-sensitive pretty-printing,
hyperlinked cross-references, and other goodies.
The third idea is `change files'. This works like
patch
but cooperates better with tangle and weave.
The basic tools for writing literate programs are the
preprocessors tangle and weave (or similarly
named), and associated TeX/LaTeX macro files.
Literate programming should not be confused with other aspects of documentation. In particular:
Literate programming is NOT an elaborate system for writing comments. (In fact, writing literate programs tends to reduce the volume of comments needed.)
Nor is it a way of splitting programs into subroutines. (The sections in a literate program are typically smaller than subroutines and more deeply nested. Also, they don't need to follow the syntax and scoping rules of the programming language. Which may sound strange, but is actually a very useful freedom, because humans and compilers differ in how they like their information organized.)
Literate programming is not a kind of folding editor either. (Folding editors imply a top-down structure, but not all literate programs have a top-down structure. Some do, but most are a mixture of top-down and bottom-up.)
Finally, literate programming is not a form of Javadoc. (Javadoc is about documenting programming interfaces, literate programming is about the internal workings of programs.)
For examples to emulate, see Knuth's programs to read, which includes a literate version of Colossal Cave Adventure if you can imagine such a thing.