I've messed around with my own literate programming system that was a more "true" system (where you have a kind of macro-like approach), and I have to agree: th

I've messed around with my own literate programming system that was a more "true" system (where you have a kind of macro-like approach), and I have to agree: the docco approach is missing the key bonus: organizing your code into chapters and paragraphs and then statements. Think of it this way, if you're building an API, you should consider usage. So you then generate examples. But not just one, maybe 3-5 of them to really do it right. Then, as you proceed, you implement and build tests, probably down towards the end of "the chapter". It's a different way of thinking about how your code is consumed. The "documentation systems" of the past (e.g., javaDoc) really are reference documentation on details of a method. But if you want to really grasp the system, you probably lead with examples. Maybe a picture. And you probably don't need to have to navigate to 7 different implementations of your interface Foo to figure out what the design is. But having those 7 different implementation files is nice when you know the system later. Where literate programming systems completely break down is the toolset. You typically can't work in "example down" mode and "single source file" mode at the same time - like, to debug, or make a small change. I've tried to build "diff and patch" between the source and the literate documentation, and when that's buggy, whew, that sucks.