Editing Literate programming (section)

== Concept ==
Literate programming is writing out the program logic in a human language with included (separated by a primitive markup) code snippets and macros. Macros in a literate source file are simply title-like or explanatory phrases in a human language that describe human abstractions created while solving the programming problem, and hiding chunks of code or lower-level macros. These macros are similar to the [[algorithm]]s in [[pseudocode]] typically used in teaching [[computer science]]. These arbitrary explanatory phrases become precise new operators, created on the fly by the programmer, forming a ''meta-language'' on top of the underlying programming language.

A [[preprocessor]] is used to substitute arbitrary hierarchies, or rather "interconnected 'webs' of macros",<ref>{{block quote|WEB's macros are allowed to have at most one parameter. Again, I did this in the interests of simplicity, because I noticed that most applications of multiple parameters could in fact be reduced to the one-parameter case. For example, suppose that you want to define something like [example elided]&nbsp;.... In other words, the name of one macro can usefully be a parameter to another macro.
 |sign=[[Donald Knuth|Donald E. Knuth]]
 |source=''Literate Programming''{{ref label|TCJ_LP|1|w}}
}}</ref> to produce the compilable source code with one command ("tangle"), and documentation with another ("weave"). The preprocessor also provides an ability to write out the content of the macros and to add to already created macros in any place in the text of the literate program source file, thereby disposing of the need to keep in mind the restrictions imposed by traditional programming languages or to interrupt the flow of thought.

=== Advantages ===
According to Knuth,<ref name="Knuth">{{Cite web |last1=Knuth |first1=Donald E. |author-link=Donald Knuth |last2=Binstock |first2=Andrew |date=April 25, 2008 |title=Interview with Donald Knuth |url= https://www.informit.com/articles/article.aspx?p=1193856 |access-date=January 4, 2009 |quote=Yet to me, literate programming is certainly the most important thing that came out of the [[TeX]] project. Not only has it enabled me to write and maintain programs faster and more reliably than ever before, and been one of my greatest sources of joy since the 1980s-it has actually been indispensable at times. Some of my major programs, such as the MMIX meta-simulator, could not have been written with any other methodology that I've ever heard of. The complexity was simply too daunting for my limited brain to handle; without literate programming, the whole enterprise would have flopped miserably.&nbsp;... Literate programming is what you need to rise above the ordinary level of achievement.}}</ref><ref>{{block quote|Another surprising thing that I learned while using WEB was that traditional programming languages had been causing me to write inferior programs, although I hadn't realized what I was doing. My original idea was that WEB would be merely a tool for documentation, but I actually found that my WEB programs were better than the programs I had been writing in other languages.
 |sign=[[Donald Knuth|Donald E. Knuth]]
 |source=''Literate Programming''{{ref label|TCJ_LP|1|x}}
}}</ref>
literate programming provides higher-quality programs, since it forces programmers to explicitly state the thoughts behind the program, making poorly thought-out design decisions more obvious. Knuth also claims that literate programming provides a first-rate documentation system, which is not an add-on, but is grown naturally in the process of exposition of one's thoughts during a program's creation.<ref>{{block quote|Thus the WEB language allows a person to express programs in a ''"stream of consciousness" order''. TANGLE is able to scramble everything up into the arrangement that a PASCAL compiler demands. This feature of WEB is perhaps its greatest asset; it makes a WEB-written program much more readable than the same program written purely in PASCAL, even if the latter program is well commented. And the fact that there's no need to be hung up on the question of top-down versus bottom-up, since a programmer can now ''view a large program as a web, to be explored in a '''psychologically correct order''' is perhaps the greatest lesson'' I have learned from my recent experiences.
 |sign=[[Donald Knuth|Donald E. Knuth]]
 |source=''Literate Programming''{{ref label|TCJ_LP|1|y}}
}}</ref> The resulting documentation allows the author to restart their own thought processes at any later time, and allows other programmers to understand the construction of the program more easily. This differs from traditional documentation, in which a programmer is presented with source code that follows a compiler-imposed order, and must decipher the thought process behind the program from the code and its associated comments. The meta-language capabilities of literate programming are also claimed to facilitate thinking, giving a higher "bird's eye view" of the code and increasing the number of concepts the mind can successfully retain and process. Applicability of the concept to programming on a large scale, that of commercial-grade programs, is proven by an edition of [[TeX]] code as a literate program.<ref name="Knuth" />

Knuth also claims that literate programming can lead to easy porting of software to multiple environments, and even cites the implementation of TeX as an example.<ref>{{Cite web |title="Oral History of Donald Knuth"- an Interview with Ed Feigenbaum |url= http://archive.computerhistory.org/resources/text/Oral_History/Knuth_Don_1/Knuth_Don.oral_history.2007.102658053_all.pdf |access-date=December 7, 2018 |website=Archive.ComputerHistory.org}}</ref>

=== 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>