Editing Literate programming (section)

=== Contrast with documentation generation ===
Literate programming is very often misunderstood<ref name="MJD2000">{{Cite web |last=Dominus |first=Mark-Jason |author-link=Mark Jason Dominus |date=March 20, 2000 |title=POD is not Literate Programming |url= https://www.perl.com/pub/tchrist/litprog.html/ |url-status=live |archive-url= https://web.archive.org/web/20090102151452/http://www.perl.com/pub/a/tchrist/litprog.html |archive-date=January 2, 2009 |website=Perl.com}}</ref> to refer only to formatted documentation produced from a common file with both source code and comments – which is properly called [[documentation generation]] – or to voluminous commentaries included with code. This is the converse of  literate programming: well-documented code or documentation extracted from code follows the structure of the code, with documentation embedded in the code; while in literate programming, code is embedded in documentation, with the code following the structure of the documentation.

This misconception has led to claims that comment-extraction tools, such as the [[Perl]] [[Plain Old Documentation]] or [[Java (programming language)|Java]] [[Javadoc]] systems, are "literate programming tools". However, because these tools do not implement the "web of abstract concepts" hiding behind the system of natural-language macros, or provide an ability to change the order of the source code from a machine-imposed sequence to one convenient to the human mind, they cannot properly be called literate programming tools in the sense intended by Knuth.<ref name="MJD2000" /><ref>{{block quote|I chose the name WEB partly because it was one of the few three-letter words of English that hadn't already been applied to computers. But as time went on, I've become extremely pleased with the name, because I think that a complex piece of software is, indeed, best regarded as a web that has been delicately pieced together from simple materials. We understand a complicated system by understanding its simple parts, and by understanding the simple relations between those parts and their immediate neighbors. If we express a program as a web of ideas, we can emphasize its structural properties in a natural and satisfying way.
 |sign=[[Donald Knuth|Donald E. Knuth]]
 |source=''Literate Programming''{{ref label|TCJ_LP|1|z}}
}}</ref>