Examine individual changes

'@@ -1,46 +1,42 @@ {{Short description|A programming approach of software development}} +{{Use American English|{{subst:DATE}}}} +{{Use mdy dates|cs1-dates=ll|date=June 2024}} [[File:Literate Programming book cover.jpg|thumb|''Literate Programming'' by [[Donald Knuth]] is the seminal book on literate programming.]] +'''Literate programming''' is a [[programming paradigm]] introduced in 1984 by [[Donald Knuth]] in which a [[computer program]] is given as an explanation of how it works in a [[natural language]], such as English, interspersed (embedded) with [[Snippet (programming)|snippets]] of [[Macro (computer science)|macros]] and traditional [[source code]], from which [[Compiler|compilable]] source code can be generated.<ref name="TCJ_LP">{{note label|TCJ_LP||v}}{{note label|TCJ_LP||w}}{{note label|TCJ_LP||x}}{{note label|TCJ_LP||y}}{{note label|TCJ_LP||z}}{{Cite journal |last=Knuth |first=Donald E. |author-link=Donald Knuth |date=1984 |title=Literate Programming |url= http://www.literateprogramming.com/knuthweb.pdf |journal=[[The Computer Journal]] |publisher=[[British Computer Society]] |volume=27 |issue=2 |pages=97–111 |doi=10.1093/comjnl/27.2.97 |access-date=January 4, 2009 |doi-access=free}}</ref> The approach is used in [[scientific computing]] and in [[data science]] routinely for [[reproducible research]] and [[open access]] purposes.<ref>{{Cite journal |last=Schulte |first=Eric |date=2012 |title=A Multi-Language Computing Environment for Literate Programming and Reproducible Research |url= https://www.jstatsoft.org/article/view/v046i03/v46i03.pdf |url-status=live |journal=Journal of Statistical Software |volume=46 |issue=3 |doi=10.18637/jss.v046.i03 |archive-url= https://web.archive.org/web/20141109113411/https://www.jstatsoft.org/article/view/v046i03/v46i03.pdf |archive-date=November 9, 2014 |access-date=May 30, 2020 |doi-access=free}}</ref> Literate programming tools are used by millions of programmers today.<ref>{{Cite conference |last=Kery |first=Mary Beth |date=April 2018 |title=The Story in the Notebook: Exploratory Data Science using a Literate Programming Tool |book-title=CHI '18: Proceedings of the 2018 CHI Conference on Human Factors in Computing Systems |publisher=[[Association for Computing Machinery]] |pages=1–11 |doi=10.1145/3173574.3173748}}</ref> -'''Literate programming''' is a [[programming paradigm]] introduced in 1984 by [[Donald Knuth]] in which a [[computer program]] is given as an explanation of how it works in a [[natural language]], such as English, interspersed (embedded) with [[Snippet (programming)|snippets]] of [[Macro (computer science)|macros]] and traditional [[source code]], from which [[Compiler|compilable]] source code can be generated.<ref name="TCJ_LP">{{note label|TCJ_LP||v}}{{note label|TCJ_LP||w}}{{note label|TCJ_LP||x}}{{note label|TCJ_LP||y}}{{note label|TCJ_LP||z}}{{Cite journal |last=Knuth |first=Donald E. |author-link=Donald Knuth |year=1984 |title=Literate Programming |url=http://www.literateprogramming.com/knuthweb.pdf |journal=[[The Computer Journal]] |publisher=[[British Computer Society]] |volume=27 |issue=2 |pages=97–111 |doi=10.1093/comjnl/27.2.97 |access-date=January 4, 2009 |doi-access=free}}</ref> The approach is used in [[scientific computing]] and in [[data science]] routinely for [[reproducible research]] and [[open access]] purposes.<ref>{{Cite journal |last=Schulte |first=Eric |year=2012 |title=A Multi-Language Computing Environment for Literate Programming and Reproducible Research |url=https://www.jstatsoft.org/article/view/v046i03/v46i03.pdf |url-status=live |journal=Journal of Statistical Software |volume=46 |issue=3 |doi=10.18637/jss.v046.i03 |archive-url=https://web.archive.org/web/20141109113411/https://www.jstatsoft.org/article/view/v046i03/v46i03.pdf |archive-date=9 November 2014 |access-date=30 May 2020 |doi-access=free}}</ref> Literate programming tools are used by millions of programmers today.<ref>{{Cite conference |last=Kery |first=Mary Beth |date=April 2018 |title=The Story in the Notebook: Exploratory Data Science using a Literate Programming Tool |publisher=ACM |pages=1–11 |doi=10.1145/3173574.3173748 |book-title=CHI '18: Proceedings of the 2018 CHI Conference on Human Factors in Computing Systems}}</ref> +The literate programming paradigm, as conceived by Donald Knuth, represents a move away from writing computer programs in the manner and order imposed by the compiler, and instead gives [[programmer]]s macros to develop programs in the order demanded by the logic and flow of their thoughts.<ref>{{block quote|I had the feeling that top-down and bottom-up were opposing methodologies: one more suitable for program exposition and the other more suitable for program creation. But after gaining experience with WEB, I have come to realize that there is no need to choose once and for all between top-down and bottom-up, because a program is best thought of as a web instead of a tree. A hierarchical structure is present, but the most important thing about a program is its structural relationships. A complex piece of software consists of simple parts and simple relations between those parts; the programmer's task is to state those parts and those relationships, in whatever order is best for human comprehension not in some rigidly determined order like top-down or bottom-up. |author=[[Donald Knuth|Donald E. Knuth]] |source=''Literate Programming''{{ref label|TCJ_LP|1|v}} }}</ref> Literate programs are written as an exposition of logic in more [[natural language]] in which [[Macro (computer science)|macros]] are used to hide abstractions and traditional [[source code]], more like the text of an [[essay]]. -The literate programming paradigm, as conceived by Donald Knuth, represents a move away from writing computer programs in the manner and order imposed by the compiler, and instead gives [[programmer]]s macros to develop programs in the order demanded by the logic and flow of their thoughts.<ref>"I had the feeling that top-down and bottom-up were opposing methodologies: one more suitable for program exposition and the other more suitable for program creation. But after gaining experience with WEB, I have come to realize that there is no need to choose once and for all between top-down and bottom-up, because a program is best thought of as a web instead of a tree. A hierarchical structure is present, but the most important thing about a program is its structural relationships. A complex piece of software consists of simple parts and simple relations between those parts; the programmer's task is to state those parts and those relationships, in whatever order is best for human comprehension not in some rigidly determined order like top-down or bottom-up." — [[Donald Knuth|Donald E. Knuth]], Literate Programming{{ref label|TCJ_LP|1|v}}</ref> Literate programs are written as an exposition of logic in more [[natural language]] in which [[Macro (computer science)|macros]] are used to hide abstractions and traditional [[source code]], more like the text of an [[essay]]. - -Literate programming (LP) tools are used to obtain two representations from a source file: one understandable by a compiler or interpreter, the "tangled" code, and another for viewing as formatted [[documentation]], which is said to be "woven" from the literate source.<ref name="ObliqueScottReference">If one remembers that the first version of the tool was called WEB, the amusing literary reference hidden by Knuth in these names becomes obvious: "Oh, what a tangled web we weave when first we practise to deceive" – [[Sir Walter Scott]], in Canto VI, Stanza 17 of ''[[Marmion (poem)|Marmion]]'' (1808) an epic poem about the [[Battle of Flodden]] in 1513. – the actual citation appeared as an epigraph in a May 1986 article by Jon Bentley and Donald Knuth in one of the classical Programming Pearls columns in Communications of the ACM, vol 29 num 5 on p.365</ref> While the first generation of literate programming tools were [[computer language]]-specific, the later ones are [[Language-independent specification|language-agnostic]] and exist beyond the individual programming languages. +Literate programming (LP) tools are used to obtain two representations from a source file: one understandable by a compiler or interpreter, the "tangled" code, and another for viewing as formatted [[documentation]], which is said to be "woven" from the literate source.<ref name="ObliqueScottReference">If one remembers that the first version of the tool was called WEB, the amusing literary reference hidden by Knuth in these names becomes obvious: "Oh, what a tangled web we weave when first we practise to deceive" — [[Sir Walter Scott]], in Canto VI, Stanza 17 of ''[[Marmion (poem)|Marmion]]'' (1808) an epic poem about the [[Battle of Flodden]] in 1513. – the actual citation appeared as an epigraph in a May 1986 article by Jon Bentley and Donald Knuth in one of the classical "Programming Pearls" columns in ''Communications of the ACM'', vol. 29, no. 5, p. 365.</ref> While the first generation of literate programming tools were [[computer language]]-specific, the later ones are [[Language-independent specification|language-agnostic]] and exist beyond the individual programming languages. == History and philosophy == -Literate programming was first introduced in 1984 by Donald Knuth, who intended it to create programs that were suitable literature for human beings. He implemented it at [[Stanford University]] as a part of his research on [[algorithm]]s and digital [[typography]]. The implementation was called "[[WEB]]" since he believed that it was one of the few three-letter words of English that had not yet been applied to computing.<ref>{{Cite web |title=Literate Programming |url=http://www.literateprogramming.com/knuthweb.pdf |access-date=2019-06-03 |website=archive.computerhistory.org}}</ref> However, it resembles the complicated nature of software delicately pieced together from simple materials.<ref name="TCJ_LP" /> The practice of literate programming has seen an important resurgence in the 2010s with the use of [[Notebook_interface|computational notebooks]], especially in [[data science]]. +Literate programming was first introduced in 1984 by Donald Knuth, who intended it to create programs that were suitable literature for human beings. He implemented it at [[Stanford University]] as a part of his research on [[algorithm]]s and digital [[typography]]. The implementation was called "[[WEB]]" since he believed that it was one of the few three-letter words of English that had not yet been applied to computing.<ref>{{Cite web |title=Literate Programming |url= http://www.literateprogramming.com/knuthweb.pdf |access-date=June 3, 2019 |website=Archive.ComputerHistory.org}}</ref> However, it resembles the complicated nature of software delicately pieced together from simple materials.<ref name="TCJ_LP" /> The practice of literate programming has seen an important resurgence in the 2010s with the use of [[Notebook_interface|computational notebooks]], especially in [[data science]]. == 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>{{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... In other words, the name of one macro can usefully be a parameter to another macro. This particular trick makes it possible to..." +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}} + |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. ... Literate programming is what you need to rise above the ordinary level of achievement.}}</ref><ref>{{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." +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}} + |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>{{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." +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}} + |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=2018-12-07 |website=archive.computerhistory.org}}</ref> +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. +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>{{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." +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}} + |source=''Literate Programming''{{ref label|TCJ_LP|1|z}} }}</ref> - -=== Critique === -In 1986, [[Jon Bentley (computer scientist)|Jon Bentley]] asked Knuth to demonstrate the concept of literate programming for his ''Programming Pearls'' column in the ''[[Communications of the ACM]]'', by writing a program in WEB. Knuth sent him a program for a problem previously discussed in the column (that of sampling ''M'' random numbers in the range 1..''N''), and also asked for an "assignment". Bentley gave him the problem of finding the ''K'' most common words from a text file, for which Knuth wrote a WEB program that was published together with a review by [[Douglas McIlroy]] of Bell Labs. McIlroy praised the intricacy of Knuth's solution, his choice of a data structure (a variant of Frank M. Liang's [[hash trie]]), and the presentation. He criticized some matters of style, such as the fact that the central idea was described late in the paper, the use of [[magic number (programming)|magic constants]], and the absence of a diagram to accompany the explanation of the data structure. McIlroy also used the review to critique the programming task itself, pointing out that in Unix (developed at Bell Labs), utilities for text processing ([[tr (Unix)|tr]], [[sort (Unix)|sort]], [[uniq]] and [[sed]]) had been written previously that were "staples", and a solution that was easy to implement, debug and reuse could be obtained by combining these utilities in a six-line [[shell script]]. In response, Bentley wrote that:<ref>{{Cite journal |last1=Bentley |first1=Jon |author-link=Jon Bentley (computer scientist) |last2=D. E. Knuth |last3=M. D. McIlroy |author-link3=Douglas McIlroy |year=1986 |title=Programming pearls |url=https://www.cs.tufts.edu/~nr/cs257/archive/don-knuth/pearls-2.pdf |journal=[[Communications of the ACM]] |volume=29 |issue=6 |pages=471–483 |doi=10.1145/5948.315654 |s2cid=10128137}}</ref> -{{Blockquote|[McIlroy] admires the execution of the solution, but faults the problem on engineering grounds. (That is, of course, my responsibility as problem assigner; Knuth solved the problem he was given on grounds that are important to most engineers—the paychecks provided by their problem assigners.)}} -McIlroy later admitted that his critique was unfair, since he criticized Knuth's program on engineering grounds, while Knuth's purpose was only to demonstrate the literate programming technique.<ref>{{Cite web |last=Mahoney |first=Michael S. |author-link=Michael Sean Mahoney |date=18 August 1989 |title=Interview with M.&nbsp;D. McIlroy |url=https://www.princeton.edu/~hos/mike/transcripts/mcilroy.htm}}</ref> In 1987, ''[[Communications of the ACM]]'' published a followup article which illustrated literate programming with a C program that combined the artistic approach of Knuth with the engineering approach of McIlroy, with a critique by John Gilbert.<ref>{{Cite journal |last1=Van Wyk |first1=Christopher J. |last2=Hanson |first2=David R. |author-link2=David Hanson (computer scientist) |last3=Gilbert |first3=John |date=July 1987 |title=Literate programming |url=https://www.cs.tufts.edu/~nr/cs257/archive/chris-van-wyk/p583-van_wyk.pdf |journal=Communications of the ACM |volume=30 |pages=593–599 |doi=10.1145/28569.315738 |number=7 |s2cid=5328652}}</ref> == Workflow == @@ -54,8 +50,8 @@ == Example == -A classic example of literate programming is the literate implementation of the standard [[Unix]] <code>[[wc (Unix)|wc]]</code> word counting program. Knuth presented a [[CWEB]] version of this example in Chapter 12 of his ''Literate Programming'' book. The same example was later rewritten for the [[noweb]] literate programming tool.<ref name="noweb-wc">{{Cite web |last=Ramsey |first=Norman |date=May 13, 2008 |title=An Example of noweb |url=https://www.cs.tufts.edu/~nr/noweb/examples/wc.html |access-date=January 4, 2009}}</ref> This example provides a good illustration of the basic elements of literate programming. +A classic example of literate programming is the literate implementation of the standard [[Unix]] <code>[[wc (Unix)|wc]]</code> word counting program. Knuth presented a [[CWEB]] version of this example in Chapter 12 of his ''Literate Programming'' book. The same example was later rewritten for the [[noweb]] literate programming tool.<ref name="noweb-wc">{{Cite web |last=Ramsey |first=Norman |date=May 13, 2008 |title=An Example of noweb |url= https://www.cs.tufts.edu/~nr/noweb/examples/wc.html |access-date=January 4, 2009}}</ref> This example provides a good illustration of the basic elements of literate programming. === Creation of macros === -The following snippet of the <code>wc</code> literate program<ref name="noweb-wc" /> shows how arbitrary descriptive phrases in a natural language are used in a literate program to create macros, which act as new "operators" in the literate programming language, and hide chunks of code or other macros. The mark-up notation consists of double angle brackets ("<code><<...>></code>") that indicate macros, the "<code>@</code>" symbol which indicates the end of the code section in a noweb file. The "<code><<*>></code>" symbol stands for the "root", topmost node the literate programming tool will start expanding the web of macros from. Actually, writing out the expanded source code can be done from any section or subsection (i.e. a piece of code designated as "<code><<name of the chunk>>=</code>", with the equal sign), so one literate program file can contain several files with machine source code. +The following snippet of the <code>wc</code> literate program<ref name="noweb-wc" /> shows how arbitrary descriptive phrases in a natural language are used in a literate program to create macros, which act as new "operators" in the literate programming language, and hide chunks of code or other macros. The mark-up notation consists of double angle brackets (<code>&lt;&lt;...&gt;&gt;</code>) that indicate macros, the <code>@</code> symbol which indicates the end of the code section in a noweb file. The <code>&lt;&lt;*&gt;&gt;</code> symbol stands for the "root", topmost node the literate programming tool will start expanding the web of macros from. Actually, writing out the expanded source code can be done from any section or subsection (i.e. a piece of code designated as <code>&lt;&lt;name of the chunk&gt;&gt;=</code>, with the equal sign), so one literate program file can contain several files with machine source code. <syntaxhighlight lang="c"> The purpose of wc is to count lines, words, and/or characters in a list of files. The @@ -80,9 +76,9 @@ === Program as a web === -Macros are not the same as "section names" in standard documentation. Literate programming macros hide the real code behind themselves, and be used inside any low-level machine language operators, often inside logical operators such as "<code>if</code>", "<code>while</code>" or "<code>case</code>". This can be seen in the following <code>wc</code> literate program.<ref name="noweb-wc" /> +Macros are not the same as "section names" in standard documentation. Literate programming macros hide the real code behind themselves, and be used inside any low-level machine language operators, often inside logical operators such as <code>if</code>, <code>while</code> or <code>case</code>. This can be seen in the following <code>wc</code> literate program.<ref name="noweb-wc" /> <syntaxhighlight lang="c"> The present chunk, which does the counting, was actually one of -the simplest to write. We look at each character and change state if it begins or ends +the simplest to write. We look at each character and change state i<nowiki />f it begins or ends a word. @@ -110,5 +106,5 @@ === Order of human logic, not that of the compiler === -In a noweb literate program besides the free order of their exposition, the chunks behind macros, once introduced with "<code><<...>>=</code>", can be grown later in any place in the file by simply writing "<code><<name of the chunk>>=</code>" and adding more content to it, as the following snippet illustrates ("plus" is added by the document formatter for readability, and is not in the code).<ref name="noweb-wc" /> +In a noweb literate program besides the free order of their exposition, the chunks behind macros, once introduced with <code>&lt;&lt;...&gt;&gt;=</code>, can be grown later in any place in the file by simply writing <code>&lt;&lt;name of the chunk&gt;&gt;=</code> and adding more content to it, as the following snippet illustrates (<code>+</code> is added by the document formatter for readability, and is not in the code).<ref name="noweb-wc" /> {{pre|1= @@ -118,5 +114,5 @@ zeroed.'&NoBreak;' (Get it?) - <<Global variables>>+= + &lt;&lt;Global variables&gt;&gt;+= {{codett|2=c|long tot_word_count, tot_line_count,}} tot_char_count; @@ -126,5 +122,5 @@ === Record of the train of thought === -The documentation for a literate program is produced as part of writing the program. Instead of comments provided as side notes to source code a literate program contains the explanation of concepts on each level, with lower level concepts deferred to their appropriate place, which allows for better communication of thought. The snippets of the literate <code>wc</code> above show how an explanation of the program and its source code are interwoven. Such exposition of ideas creates the flow of thought that is like a literary work. Knuth wrote a "novel" which explains the code of the [[interactive fiction]] game [[Colossal Cave Adventure]].<ref>The game, also known as ''ADVENT'', was originally written by Crowther in about 700 lines of FORTRAN code; Knuth recast it into the WEB idiom. It is available at [http://www.literateprogramming.com/cweb_download.html literateprogramming.com] or on [https://cs.stanford.edu/~knuth/programs.html Knuth's website] {{webarchive|url=https://web.archive.org/web/20080820091137/http://sunburn.stanford.edu/~knuth/programs.html |date=2008-08-20 }}.</ref> +The documentation for a literate program is produced as part of writing the program. Instead of comments provided as side notes to source code a literate program contains the explanation of concepts on each level, with lower level concepts deferred to their appropriate place, which allows for better communication of thought. The snippets of the literate <code>wc</code> above show how an explanation of the program and its source code are interwoven. Such exposition of ideas creates the flow of thought that is like a literary work. Knuth wrote a "novel" which explains the code of the [[interactive fiction]] game [[Colossal Cave Adventure]].<ref>The game, also known as ''ADVENT'', was originally written by Crowther in about 700 lines of FORTRAN code; Knuth recast it into the WEB idiom. It is available at [http://www.literateprogramming.com/cweb_download.html literateprogramming.com] or on [https://cs.stanford.edu/~knuth/programs.html Knuth's website] {{webarchive|url= https://web.archive.org/web/20080820091137/http://sunburn.stanford.edu/~knuth/programs.html |date=August 20, 2008}}.</ref> === Remarkable examples === @@ -133,7 +129,7 @@ == Literate programming practices == -The first published literate programming environment was [[WEB]], introduced by Knuth in 1981 for his [[TeX]] typesetting system; it uses [[Pascal (programming language)|Pascal]] as its underlying programming language and TeX for typesetting of the documentation. The complete commented TeX source code was published in Knuth's ''TeX: The program'', volume B of his 5-volume ''[[Computers and Typesetting]]''. Knuth had privately used a literate programming system called DOC as early as 1979. He was inspired by the ideas of [[Pierre-Arnoul de Marneffe]].<ref>{{Cite report |last=de Marneffe |first=Pierre Arnoul |author-link=Pierre-Arnoul de Marneffe |date=December 1973 |title=Holon Programming – A Survey |publisher=[[University of Liège|University de Liège]], Service d'Informatique |pages=135 |url=https://github.com/holon-scribe/holon-programming}}</ref> The free [[CWEB]], written by Knuth and Silvio Levy, is WEB adapted for [[C (programming language)|C]] and [[C++]], runs on most operating systems and can produce TeX and [[Portable Document Format|PDF]] documentation. +The first published literate programming environment was [[WEB]], introduced by Knuth in 1981 for his [[TeX]] typesetting system; it uses [[Pascal (programming language)|Pascal]] as its underlying programming language and TeX for typesetting of the documentation. The complete commented TeX source code was published in Knuth's ''TeX: The program'', volume B of his 5-volume ''[[Computers and Typesetting]]''. Knuth had privately used a literate programming system called DOC as early as 1979. He was inspired by the ideas of [[Pierre-Arnoul de Marneffe]].<ref>{{Cite report |last=de Marneffe |first=Pierre Arnoul |author-link=Pierre-Arnoul de Marneffe |date=December 1973 |title=Holon Programming – A Survey |publisher=[[University of Liège|Université de Liège]], Service d'Informatique |pages=135 |url= https://github.com/holon-scribe/holon-programming |via=[[GitHub]]}}</ref> The free [[CWEB]], written by Knuth and Silvio Levy, is WEB adapted for [[C (programming language)|C]] and [[C++]], runs on most operating systems, and can produce TeX and [[Portable Document Format|PDF]] documentation. -There are various other implementations of the literate programming concept as given below. Many of the newer ones among these don't have macros and hence violate the [[#Order of human logic, not that of the compiler|order of human logic]] principle, which makes them more of semi-literate tools. These, however, allow cellular execution of code which makes them more on the likes of [[exploratory programming]] tools. +There are various other implementations of the literate programming concept as given below. Many of the newer among these do not have macros and hence do not comply with the [[#Order of human logic, not that of the compiler|order of human logic]] principle, which makes them perhaps "semi-literate" tools. These, however, allow cellular execution of code which makes them more along the lines of [[exploratory programming]] tools. {| class="wikitable sortable" style="text-align: center;" @@ -168,9 +164,9 @@ | [http://nuweb.sourceforge.net/ NuWEB] || Any || [[C++]] || [[LaTeX]] | -| || It can translate a single LP source into any number of code files. It does it in a single invocation; it does not have separate weave and tangle commands. It does not have the extensibility of [[noweb]] +| || It can translate a single LP source into any number of code files. It does it in a single invocation; it does not have separate weave and tangle commands. It does not have the extensibility of [[noweb]]. |- | [https://github.com/slott56/py-web-tool pyWeb] || Any || [[Python (programming language)|Python]] || [[ReStructuredText]] |{{yes}} -| || Respects indentation which makes usable for the languages like [[Python (programming language)|Python]], though you can use it for any programming language. +| || Respects indentation which makes usable for the languages like [[Python (programming language)|Python]], though one can use it for any programming language. |- | [https://github.com/unixtechie/Literate-Molly Molly] || Any || [[Perl]] || [[HTML]] @@ -184,21 +180,21 @@ | [[Emacs]] [[org-mode]] || Any || [[Emacs Lisp]] || [[Plain text]] | -| || Requires Babel,<ref>{{Cite web |title=Babel: Introduction |url=https://orgmode.org/worg/org-contrib/babel/intro.html}}</ref> which allows embedding blocks of source code from multiple programming languages<ref>{{Cite web |title=Babel Languages: redirect |url=https://orgmode.org/worg/org-contrib/babel/languages.html#langs |website=orgmode.org}}</ref> within a single text document. Blocks of code can share data with each other, display images inline, or be parsed into pure source code using the [[noweb]] reference syntax.<ref>{{Cite web |title=Babel: Introduction |url=https://orgmode.org/worg/org-contrib/babel/intro.html#literate-programming}}</ref> +| || Requires Babel,<ref>{{Cite web |title=Babel: Introduction |url= https://orgmode.org/worg/org-contrib/babel/intro.html}}</ref> which allows embedding blocks of source code from multiple programming languages<ref>{{Cite web |title=Babel Languages: redirect |url= https://orgmode.org/worg/org-contrib/babel/languages.html#langs |website=OrgMode.org}}</ref> within a single text document. Blocks of code can share data with each other, display images inline, or be parsed into pure source code using the [[noweb]] reference syntax.<ref>{{Cite web |title=Babel: Introduction |url= https://orgmode.org/worg/org-contrib/babel/intro.html#literate-programming}}</ref> |- | [[CoffeeScript]] || [[CoffeeScript]] || [[CoffeeScript]], [[JavaScript]] || [[Markdown]] | -| || [[CoffeeScript]] supports a "literate" mode, which enables programs to be compiled from a source document written in [[Markdown]] with indented blocks of code.<ref>{{Cite web |last=Ashkenas |first=Jeremy |title=Literate CoffeeScript |url=https://coffeescript.org/#literate |access-date=13 November 2014}}</ref> +| || [[CoffeeScript]] supports a "literate" mode, which enables programs to be compiled from a source document written in [[Markdown]] with indented blocks of code.<ref>{{Cite web |last=Ashkenas |first=Jeremy |title=Literate CoffeeScript |url= https://coffeescript.org/#literate |access-date=November 13, 2014}}</ref> |- | [[Maple (software)|Maple worksheets]] || [[Maple (software)]] || || [[XML]] | -| || [[Maple (software)|Maple worksheets]] are a platform-agnostic literate programming environment that combines text and graphics with live code for symbolic computation.{{Cite web |title=Maple Worksheets |url=https://www.maplesoft.com/support/help/Maple/view.aspx?path=Worksheet |access-date=2020-05-30 |website=www.maplesoft.com}} +| || [[Maple (software)|Maple worksheets]] are a platform-agnostic literate programming environment that combines text and graphics with live code for symbolic computation.{{Cite web |title=Maple Worksheets |url= https://www.maplesoft.com/support/help/Maple/view.aspx?path=Worksheet |access-date=May 30, 2020 |website=MapleSoft.com}} |- | [[Wolfram Mathematica|Wolfram Notebooks]] || [[Wolfram Language]] || || [[Wolfram Language]] | -| || [[Wolfram Mathematica|Wolfram notebooks]] are a platform-agnostic literate programming method that combines text and graphics with live code.<ref>[https://archive.org/details/milestonesincomp0000reil/page/157 <!-- quote="Stephen Wolfram" "Literate programming". --> Milestones in Computer Science and Information Technology] by Edwin D. Reilly, p. 157.</ref><ref>{{Cite web |title=Wolfram Notebooks |url=https://www.wolfram.com/notebooks/ |access-date=2018-11-28 |website=www.wolfram.com}}</ref> +| || [[Wolfram Mathematica|Wolfram notebooks]] are a platform-agnostic literate programming method that combines text and graphics with live code.<ref>[https://archive.org/details/milestonesincomp0000reil/page/157 <!-- quote="Stephen Wolfram" "Literate programming". --> Milestones in Computer Science and Information Technology] by Edwin D. Reilly, p. 157.</ref><ref>{{Cite web |title=Wolfram Notebooks |url= https://www.wolfram.com/notebooks/ |access-date=November 28, 2018 |website=Wolfram.com}}</ref> |- | [https://developer.apple.com/swift-playgrounds/ Playgrounds] || [[Swift (programming language)]] || || | -| || Provides an interactive programming environment that evaluates each statement and displays live results as the code is edited. Playgrounds also allow the user to add [[Markup language]] along with the code that provide headers, inline formatting and images.<ref>{{Cite web |title=Markup Formatting Reference: Markup Overview |url=https://developer.apple.com/library/ios/documentation/Xcode/Reference/xcode_markup_formatting_ref/index.html#//apple_ref/doc/uid/TP40016497-CH2-SW1 |access-date=2015-11-15 |website=developer.apple.com}}</ref> +| || Provides an interactive programming environment that evaluates each statement and displays live results as the code is edited. Playgrounds also allow the user to add [[Markup language]] along with the code that provide headers, inline formatting and images.<ref>{{Cite web |title=Markup Formatting Reference: Markup Overview |url= https://developer.apple.com/library/ios/documentation/Xcode/Reference/xcode_markup_formatting_ref/index.html#//apple_ref/doc/uid/TP40016497-CH2-SW1 |access-date=November 15, 2015 |website=Developer.Apple.com}}</ref> |- | [[Project Jupyter#Jupyter Notebook|Jupyter Notebook]], formerly [[IPython|IPython Notebook]] || [[Python (programming language)|Python]] and any with a Jupyter Kernel || || [[JSON]] format Specification for [https://ipython.org/ipython-doc/3/notebook/nbformat.html ipynb] @@ -217,5 +213,5 @@ |[[Python (programming language)|Python]] and [[Project Jupyter|Jupyter Notebook]] | -|<code>nbdev</code> is a library that allows you to develop a python library in Jupyter Notebooks, putting all your code, tests and documentation in one place. +|<code>nbdev</code> is a library that allows one to develop a python library in Jupyter Notebooks, putting all code, tests and documentation in one place. | | @@ -227,9 +223,9 @@ | [[Agda (programming language)]] || || || | -| || Supports a limited form of literate programming out of the box.<ref>{{Cite web |title=Literate Agda |url=http://wiki.portal.chalmers.se/agda/pmwiki.php?n=Main.LiterateAgda |access-date=2017-03-26 |website=Agda Wiki}}</ref> +| || Supports a limited form of literate programming out of the box.<ref>{{Cite web |title=Literate Agda |url= http://wiki.portal.chalmers.se/agda/pmwiki.php?n=Main.LiterateAgda |access-date=March 26, 2017 |website=Agda Wiki}}</ref> |- | [http://witheve.com Eve programming language] || || || | -| || Programs are primarily prose.<ref>{{Cite web |title=Eve and Literate Progamming |url=http://docs.witheve.com/handbook/literate-programming/ |url-status=dead |archive-url=https://web.archive.org/web/20170524092539/http://docs.witheve.com/handbook/literate-programming/ |archive-date=2017-05-24 |access-date=2017-05-25 |website=Eve Handbook}}</ref> Eve combines variants of [[Datalog]] and [[Markdown]] with a live graphical development environment +| || Programs are primarily prose.<ref>{{Cite web |title=Eve and Literate Progamming |url= http://docs.witheve.com/handbook/literate-programming/ |url-status=dead |archive-url= https://web.archive.org/web/20170524092539/http://docs.witheve.com/handbook/literate-programming/ |archive-date=May 24, 2017 |access-date=May 25, 2017 |website=Eve Handbook}}</ref> Eve combines variants of [[Datalog]] and [[Markdown]] with a live graphical development environment |- | [https://rmarkdown.rstudio.com/ R Markdown] Notebooks (or R Notebooks) || [[R (programming language)|R]], [[Python (programming language)|Python]], [[Julia (programming language)|Julia]] and [[SQL]] || || [[PDF]], [[Microsoft Word]], [[LibreOffice]] and presentation or [[slide show]] formats plus interactive formats like [[Web widget|HTML widgets]] @@ -243,9 +239,9 @@ | [[Sweave]] || [[R (programming language)|R]] || || [[PDF]] | -| || <ref name="Leisch2002">{{Cite web |last=Leisch |first=Friedrich |year=2002 |title=Sweave, Part I: Mixing R and LaTeX: A short introduction to the Sweave file format and corresponding R functions |url=https://cran.r-project.org/doc/Rnews/Rnews_2002-3.pdf |access-date=22 January 2012 |website=R News |pages=28–31 |volume=2 |issue=3}}</ref><ref name="Pineda-Krch2011">{{Cite web |last=Pineda-Krch |first=Mario |date=17 January 2011 |title=The Joy of Sweave – A Beginner's Guide to Reproducible Research with Sweave |url=http://www.math.ualberta.ca/~mlewis/links/the_joy_of_sweave_v1.pdf |access-date=22 Jan 2012}}</ref> +| || <ref name="Leisch2002">{{Cite journal |last=Leisch |first=Friedrich |date=2002 |title=Sweave, Part I: Mixing R and LaTeX: A short introduction to the Sweave file format and corresponding R functions |url= https://cran.r-project.org/doc/Rnews/Rnews_2002-3.pdf |access-date=January 22, 2012 |journal=R News |pages=28–31 |volume=2 |issue=3}}</ref><ref name="Pineda-Krch2011">{{Cite web |last=Pineda-Krch |first=Mario |date=January 17, 2011 |title=The Joy of Sweave – A Beginner's Guide to Reproducible Research with Sweave |url= http://www.math.ualberta.ca/~mlewis/links/the_joy_of_sweave_v1.pdf |access-date=January 22, 2012}}</ref> |- | [[Knitr]] || [[R (programming language)|R]] || || [[LaTeX]], [[PDF]], [[LyX]], [[HTML]], [[Markdown]], [[AsciiDoc]], and [[reStructuredText]] | -| ||<ref>{{Cite book |last=Xie |first=Yihui |url=http://www.crcpress.com/product/isbn/9781498716963 |title=Dynamic Documents with R and knitr, 2nd Edition |publisher=Chapman & Hall/CRC |year=2015 |isbn=9781498716963}}</ref><ref>{{Cite web |last=Xie |first=Yihui |title=knitr: A General-Purpose Tool for Dynamic Report Generation in R |url=https://github.com/yihui/knitr/releases/download/doc/knitr-manual.pdf |website=[[GitHub]]}}</ref> +| ||<ref>{{Cite book |last=Xie |first=Yihui |url= http://www.crcpress.com/product/isbn/9781498716963 |title=Dynamic Documents with R and knitr, 2nd Edition |publisher=Chapman & Hall/CRC |date=2015 |isbn=9781498716963}}</ref><ref>{{Cite web |last=Xie |first=Yihui |title=knitr: A General-purpose Tool for Dynamic Report Generation in R |url= https://github.com/yihui/knitr/releases/download/doc/knitr-manual.pdf |via=[[GitHub]]}}</ref> |- | [https://github.com/gpoore/codebraid Codebraid] || [[Pandoc]], [[Rust (programming language)|Rust]], [[Julia (programming language)|Julia]], [[Python (programming language)|Python]], [[R (programming language)|R]], [[Bash (Unix shell)|Bash]] || [[Python (programming language)|Python]] || [[Markdown]] @@ -267,5 +263,5 @@ |[https://github.com/ganelson/inweb/ Inweb] || [[The C Programming Language|C]], [[C++]], [[Inform#Inform 6|Inform 6]], [[Inform#Inform 7|Inform 7]] || [[The C Programming Language|C]], [[CWEB]] || [[TeX]], [[HTML]] |Yes? -| || Used to write the Inform Programming Language since 2004.<ref>{{Cite web |date=17 June 2022 |title=ganelson/inweb: A modern system for literate programming |url=https://github.com/ganelson/inweb |website=[[GitHub]]}}</ref> +| || Used to write the Inform Programming Language since 2004.<ref>{{Cite web |last=Nelson |first=Graham A. |date=June 17, 2022 |title=ganelson/inweb: A modern system for literate programming |url= https://github.com/ganelson/inweb |via=[[GitHub]]}}</ref> |- |[https://github.com/mljar/mercury Mercury] @@ -300,8 +296,11 @@ Other useful tools include: -* The [[Leo (text editor)|Leo text editor]] is an ''outlining'' editor which supports optional noweb and CWEB markup. The author of Leo mixes two different approaches: first, Leo is an outlining editor, which helps with management of large texts; second, Leo incorporates some of the ideas of literate programming, which in its pure form (i.e., the way it is used by Knuth Web tool or tools like "noweb") is possible only with some degree of inventiveness and the use of the editor in a way not exactly envisioned by its author (in modified @root nodes). However, this and other extensions (@file nodes) make outline programming and text management successful and easy and in some ways similar to literate programming.<ref>{{Cite web |last=Ream |first=Edward K. |date=September 2, 2008 |title=Leo's Home Page |url=http://leoeditor.com/ |access-date=April 3, 2015}}</ref> -* The [[Haskell (programming language)|Haskell]] programming language has native support for semi-literate programming. The compiler/interpreter supports two file name extensions: <code>.hs</code> and <code>.lhs</code>; the latter stands for literate Haskell. -:The literate scripts can be full LaTeX source text, at the same time it can be compiled, with no changes, because the interpreter only compiles the text in a code environment, for example: -:<syntaxhighlight lang="lhs"> +{{bulleted list|reason=Template used due to complicated list items, to avoid mangled markup that fails [[MOS:ACCESS]]. +|1=The [[Leo (text editor)|Leo text editor]] is an ''outlining'' editor which supports optional noweb and CWEB markup. The author of Leo mixes two different approaches: first, Leo is an outlining editor, which helps with management of large texts; second, Leo incorporates some of the ideas of literate programming, which in its pure form (i.e., the way it is used by Knuth Web tool or tools like "noweb") is possible only with some degree of inventiveness and the use of the editor in a way not exactly envisioned by its author (in modified @root nodes). However, this and other extensions (@file nodes) make outline programming and text management successful and easy and in some ways similar to literate programming.<ref>{{Cite web |last=Ream |first=Edward K. |date=September 2, 2008 |title=Leo's Home Page |url= http://leoeditor.com/ |access-date=April 3, 2015}}</ref> +|2=The [[Haskell (programming language)|Haskell]] programming language has native support for semi-literate programming. The compiler/interpreter supports two file name extensions: <code>.hs</code> and <code>.lhs</code>; the latter stands for literate Haskell. + +The literate scripts can be full LaTeX source text, at the same time it can be compiled, with no changes, because the interpreter only compiles the text in a code environment, for example: + +<syntaxhighlight lang="lhs"> % here text describing the function: \begin{code} @@ -311,7 +310,10 @@ here more text </syntaxhighlight> -:The code can be also marked in the Richard Bird style, starting each line with a greater than symbol and a space, preceding and ending the piece of code with blank lines. -:The LaTeX <code>listings</code> package provides a <code>lstlisting</code> environment which can be used to embellish the source code. It can be used to define a <code>code</code> environment to use within Haskell to print the symbols in the following manner: -:<syntaxhighlight lang="lhs"> + +The code can be also marked in the Richard Bird style, starting each line with a greater than symbol and a space, preceding and ending the piece of code with blank lines. + +The LaTeX <code>listings</code> package provides a <code>lstlisting</code> environment which can be used to embellish the source code. It can be used to define a <code>code</code> environment to use within Haskell to print the symbols in the following manner: + +<syntaxhighlight lang="lhs"> \newenvironment{code}{\lstlistings[language=Haskell]}{\endlstlistings} @@ -321,14 +323,19 @@ \end{code} </syntaxhighlight> -:which can be configured to yield: -::<math> + +which can be configured to yield: + +{{block indent|1=<math> \begin{align} &comp :: (\beta \to \gamma) \to (\alpha \to \beta) \to (\alpha \to \gamma)\\ &(g \operatorname{comp} f) x = g(f x) \end{align} -</math> -:Although the package does not provide means to organize chunks of code, one can split the LaTeX source code in different files. See [http://mirrors.ctan.org/macros/latex/contrib/listings/listings.pdf listings manual] for an overview. -* The Web 68 Literate Programming system used [[Algol 68]] as the underlying programming language, although there was nothing in the pre-processor 'tang' to force the use of that language.<ref>{{Cite web |last=Mountbatten |first=Sian |title=Web 68: Literate programming with Algol 68 |url=http://www.poenikatu.co.uk/html/Web68man.html |url-status=dead |archive-url=https://web.archive.org/web/20130120154432/http://www.poenikatu.co.uk/html/Web68man.html |archive-date=20 January 2013 |access-date=1 January 2013}}</ref> -* The customization mechanism of the [[Text Encoding Initiative]] which enables the constraining, modification, or extension of the [[Text Encoding Initiative|TEI]] scheme enables users to mix prose documentation with fragments of schema specification in their [[Text Encoding Initiative#ODD|One Document Does-it-all]] format. From this prose documentation, schemas, and processing model pipelines can be generated and Knuth's Literate Programming paradigm is cited as the inspiration for this way of working.<ref>{{Cite web |title=TEI Guidelines |url=http://www.tei-c.org/release/doc/tei-p5-doc/en/html/USE.html#IMGD |url-status=dead |archive-url=https://web.archive.org/web/20180822123639/http://www.tei-c.org/release/doc/tei-p5-doc/en/html/USE.html#IMGD |archive-date=2018-08-22 |access-date=2018-08-23 |website=TEI Consortium}}</ref> +</math>}} + +Although the package does not provide means to organize chunks of code, one can split the LaTeX source code in different files.<ref>See [http://mirrors.ctan.org/macros/latex/contrib/listings/listings.pdf listings manual] for an overview.</ref> + +|3=The Web 68 Literate Programming system used [[Algol 68]] as the underlying programming language, although there was nothing in the pre-processor 'tang' to force the use of that language.<ref>{{Cite web |last=Mountbatten |first=Sian |title=Web 68: Literate programming with Algol 68 |url= http://www.poenikatu.co.uk/html/Web68man.html |url-status=dead |archive-url= https://web.archive.org/web/20130120154432/http://www.poenikatu.co.uk/html/Web68man.html |archive-date=January 20, 2013 |access-date=January 1, 2013}}</ref> +|4=The customization mechanism of the [[Text Encoding Initiative]] which enables the constraining, modification, or extension of the [[Text Encoding Initiative|TEI]] scheme enables users to mix prose documentation with fragments of schema specification in their [[Text Encoding Initiative#ODD|One Document Does-it-all]] format. From this prose documentation, schemas, and processing model pipelines can be generated and Knuth's Literate Programming paradigm is cited as the inspiration for this way of working.<ref>{{Cite web |title=TEI Guidelines |url= http://www.tei-c.org/release/doc/tei-p5-doc/en/html/USE.html#IMGD |url-status=dead |archive-url= https://web.archive.org/web/20180822123639/http://www.tei-c.org/release/doc/tei-p5-doc/en/html/USE.html#IMGD |archive-date=August 22, 2018 |access-date=August 23, 2018 |website=TEI-C.org |publisher=TEI Consortium}}</ref> +}}<!--End bulleted list.--> ==See also== @@ -343,11 +350,11 @@ == Further reading == {{refbegin}} -* {{Cite news |last=Sewell |first=Wayne |year=1989 |title=Weaving a Program: Literate Programming in WEB |publisher=Van Nostrand Reinhold |url=https://archive.org/details/weavingprogramli0000sewe |url-access=registration |isbn=0-442-31946-0}} -* {{Cite book |last=Knuth |first=Donald E. |title=Literate Programming |publisher=[[Stanford University]] Center for the Study of Language and Information |year=1992 |isbn=978-0-937073-80-3 |location=California |author-link=Donald Knuth}} -* {{Cite book |last=Gurari |first=Eitan M. |title=TeX & LaTeX: Drawing and Literate Programming |publisher=McGraw Hill |year=1994 |isbn=0-07-911616-7}} (includes software) -* {{Cite web |last=Nørmark |first=Kurt |date=August 13, 1998 |title=Literate Programming – Issues and Problems |url=http://www.cs.aau.dk/~normark/litpro/issues-and-problems.html |publisher=[[University of Aalborg]]}} -* {{Cite news |last=Schulte |first=Eric |date=January 2012 |title=A Multi-Language Computing Environment for Literate Programming and Reproducible Research |volume=46 |journal=Journal of Statistical Software |issue=3 |url=https://www.jstatsoft.org/article/view/v046i03/v46i03.pdf |doi=10.18637/jss.v046.i03}} -* {{Cite web |last=Mall |first=Daniel |title=Literate Programming |url=http://literateprogramming.com/}} -* {{Cite conference |last=Walsh |first=Norman |date=2002-10-15 |title=Literate Programming in XML |url=http://www.idealliance.org/papers/xml02/dx_xml02/papers/06-01-01/06-01-01.html |conference=XML 2002 |citeseerx=10.1.1.537.6728 |archive-url=https://web.archive.org/web/20080511181057/http://www.idealliance.org/papers/xml02/dx_xml02/papers/06-01-01/06-01-01.html |archive-date=2008-05-11 |df=mdy}} +* {{Cite news |last=Sewell |first=Wayne |date=1989 |title=Weaving a Program: Literate Programming in WEB |publisher=Van Nostrand Reinhold |url= https://archive.org/details/weavingprogramli0000sewe |url-access=registration |isbn=0-442-31946-0}} +* {{Cite book |last=Knuth |first=Donald E. |author-link=Donald Knuth |title=Literate Programming |publisher=[[Stanford University]] Center for the Study of Language and Information |date=1992 |isbn=978-0-937073-80-3}} +* {{Cite book |last=Gurari |first=Eitan M. |title=TeX & LaTeX: Drawing and Literate Programming |publisher=McGraw Hill |date=1994 |isbn=0-07-911616-7}} (includes software) +* {{Cite web |last=Nørmark |first=Kurt |date=August 13, 1998 |title=Literate Programming – Issues and Problems |url= http://www.cs.aau.dk/~normark/litpro/issues-and-problems.html |publisher=[[University of Aalborg]]}} +* {{Cite news |last=Schulte |first=Eric |date=January 2012 |title=A Multi-Language Computing Environment for Literate Programming and Reproducible Research |volume=46 |journal=Journal of Statistical Software |issue=3 |url= https://www.jstatsoft.org/article/view/v046i03/v46i03.pdf |doi=10.18637/jss.v046.i03}} +* {{Cite web |last=Mall |first=Daniel |title=Literate Programming |url= http://literateprogramming.com/}} +* {{Cite conference |last=Walsh |first=Norman |date=October 15, 2002 |title=Literate Programming in XML |url= http://www.idealliance.org/papers/xml02/dx_xml02/papers/06-01-01/06-01-01.html |conference=XML 2002 |citeseerx=10.1.1.537.6728 |archive-url= https://web.archive.org/web/20080511181057/http://www.idealliance.org/papers/xml02/dx_xml02/papers/06-01-01/06-01-01.html |archive-date=May 11, 2008}} {{refend}} '