Literate programming

__Literate programming__ is a programming paradigm introduced by Donald Knuth in which a program is given as an explanation of the program logic in a natural language, interspersed with snippets of macros and traditional source code, from which a compilable source code can be generated - wikipedia

The literate programming paradigm, represents a move away from writing computer program in the manner and order imposed by the computer, and instead enables programmers to develop programs in the order demanded by the logic and flow of their thoughts.

Literate programs are written as an uninterrupted exposition of logic in an natural language, much like the text of an essay, in which elements are included to hide abstractions and traditional source code.

Literate programming tools are used to obtain two representations from a literate source file: one suitable for further compiler or executable (tangled code), and another for viewing as formatted documentation, which is said to be "woven" from the literate source.

While the first generation of literate programming tools were computer language-specific, the later ones are Language-independent specification and exist above the programming languages.

# History and philosophy

Literate programming was first introduced by Donald E. Knuth in 1984. The main intention behind this approach was to treat a program as literature understandable to human beings. This approach was implemented at Stanford University as a part of research on algorithms and digital typography.

This implementation was called “WEB” by Donald Knuth since he believed that it was one of the few three-letter words of English that hadn’t already been applied to computing. However, it correctly resembles the complicated nature of software delicately pieced together from simple materials - wikipedia

# 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 algorithms 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 - wikipedia

A preprocessor is used to substitute arbitrary hierarchies, or rather "interconnected 'webs' of macros", 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, - wikipedia

> 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. The resulting documentation allows the author to restart his 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.

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.

# Contrast with documentation generation

Literate programming is very often misunderstood 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 backwards: well-documented code or documentation extracted from code follows the structure of the code, with documentation embedded in the code; in literate programming code is embedded in documentation, with the code following the structure of the documentation - wikipedia

This misconception has led to claims that comment-extraction tools, such as the Perl Plain Old Documentation or Java (programming language) 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.

# Workflow

Implementing literate programming consists of two steps - wikipedia

- Weaving: Generating comprehensive document about program and its maintenance.

- Tangling: Generating machine executable code

# Links - Literate programming -... - wikipedia.org - What Is a Computational... - stephenwolfram.com - What Is a Computational... - ycombinator.com - Literate Devops with Emacs -... - youtube.com - xkcd: Standards - xkcd.com - The Scientific Paper Is... - theatlantic.com - Computational Essay -... - uio.no - brett-victor's super cool... - google.com - Bret Victor - Inventing on... - vimeo.com

# Literate Devops with Emacs

A demonstration originally given at EmacsConf 2015 that describes how I use org-mode's Babel project and Tramp to configure and work with remote servers in my data center, prior to copying code off into Chef cookbooks and whatnot.

Weaving and tangling are done on the same source so that they are consistent with each other.

YOUTUBE dljNabciEGg Literate Devops with Emacs. Broadcast on 1 Sep 2015.

* My initial essay that started this presentation: http://howardism.org/Technical/Emacs/literate-devops.html * Github that contains the demonstration code and results Sprint Page: https://github.com/howardabrams/literate-devops-demo * Emacs code used to make this demonstration: http://github.com/howardabrams/demo-it * My Emacs configuration files: http://github.com/howardabrams/dot-files

# Examples and Tools

A classic example of literate programming is the literate implementation of the standard wc (Unix) word counting program. This example provides a good illustration of the basic elements of literate programming - wikipedia

# See also