Editing Literate programming (section)

== 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|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 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;"
! Name
! Supported languages
! Written in
! Markup language
! Macros & custom order
! Cellular execution
! Comments
|-
| [[WEB]] || [[Pascal (programming language)|Pascal]] || [[Pascal (programming language)|Pascal]] || [[TeX]]
|{{yes}}
|{{no}}|| The first published literate programming environment.
|-
| [[CWEB]] || [[C++]] and [[C (programming language)|C]] || [[C (programming language)|C]] || [[TeX]]
|{{yes}}
|{{no}}|| Is [[WEB]] adapted for [[C (programming language)|C]] and [[C++]].
|-
| [[noweb|NoWEB]] || Any || [[C (programming language)|C]], [[AWK]], and [[Icon (programming language)|Icon]] || [[LaTeX]], [[TeX]], [[HTML]] and [[troff]]
|{{yes}}
|{{no}}|| It is well known for its simplicity and it allows for text formatting in HTML rather than going through the TeX system.
|-
| [[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>
|-
| [[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=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=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=November 28, 2018 |website=Wolfram.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]
|{{no}}
|{{yes}}|| Works in the format of notebooks, which combine headings, text (including LaTeX), plots, etc. with the written code.
|-
|[https://nbdev.fast.ai/ nbdev]
|[[Python (programming language)|Python]] and [[Project Jupyter|Jupyter Notebook]]
|
|<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.
|
|
|-
| [[Julia (programming language)]] || || ||
| [https://plutojl.org Pluto.jl] is a [[Reactive programming|reactive]]  notebook environment allowing custom order. But web-like macros aren't supported.
|{{yes}}|| Supports the iJulia mode of development which was inspired by iPython.
|-
| [[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=March 26, 2017 |website=Agda Wiki}}</ref>
|-
| [[Sweave]] || [[R (programming language)|R]] || || [[PDF]]
|
| || <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 |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/zyedidia/Literate Literate] || Any || [[D (programming language)|D]] || [[Markdown]]
|{{yes}}
|{{no}}|| Supports TeX equations. Compatible with Vim.
|}

Other useful tools include:

{{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}
fact 0 = 1
fact (n+1) = (n+1) * fact n
\end{code}
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">
\newenvironment{code}{\lstlistings[language=Haskell]}{\endlstlistings}

\begin{code}
comp :: (beta -> gamma) -> (alpha -> beta) -> (alpha -> gamma)
(g `comp` f) x = g(f x)
\end{code}
</syntaxhighlight>

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