Literate Tools

Here we collect software tools inspired by the idea of literate programming - wikipedia

# History

The first published literate programming environment was WEB, introduced by Donald Knuth in 1981 for his TeX typesetting system; it uses Pascal (programming language) as its underlying programming language and TeX for typesetting of the documentation.

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. The free CWEB, written by Knuth and Silvio Levy, is WEB adapted for C (programming language) and C++, runs on most operating systems and can produce TeX and Portable Document Format documentation.

# Implementations

There are various other implementations of the literate programming concept:

- Axiom (computer algebra system)|Axiom, which is evolved from scratchpad, a computer algebra system developed by IBM. It is now being developed by Tim Daly, one of the developers of scratchpad, Axiom is totally written as a literate program.

- noweb is independent of the programming language of the source code. It is well known for its simplicity, given the need of using only two text markup conventions and two tool invocations, and it allows for text formatting in HTML rather than going through the TeX system.

- Literate is a "modern literate programming system." Like noweb, it works with any programming language, but it produces pretty-printed and syntax-highlighted HTML, and it tries to retain all the advantages of CWEB, including output formatted like CWEB. Other notable advantages compared with older tools include being based on Markdown and generating well-formatted "tangled" code - github

- FunnelWeb is another LP tool that can produce HTML documentation output. It has more complicated markup (with "@" escaping any FunnelWeb command), but has many more flexible options. Like noweb, it is independent of the programming language of the source code - ross.net

- Nuweb can translate a single LP source into any number of code files in any mix of languages together with documentation in LaTeX. It does it in a single invocation; it does not have separate weave and tangle commands. It does not have the extensibility of noweb, but it can use the listings package of LaTeX to provide pretty-printing and the hyperref package to provide hyperlinks in PDF output. It also has extensive indexing and cross-referencing facilities including cross-references from the generated code back to the documentation, both as automatically generated comments and as strings that the code can use to report its behaviour. Vimes is a type-checker for Z notation which shows the use of nuweb in a practical application. Around 15,000 lines of nuweb source are translated into nearly 15,000 lines of C/C++ code and over 460 pages of documentation - sourceforge

- pyWeb is a literate programming tool that has syntax for macros similar to CWEB, but uses ReStructuredText instead of TeX for markup and respects indentation which makes usable for the languages like Python_(programming_language) |Python, though you can use it for any programming language - github

- Molly is an LP tool written in Perl, which aims to modernize and scale it with "folding HTML" and "virtual views" on code. It uses "noweb" markup for the literate source files - github

- Codnar is an inverse literate programming tool available as a Ruby Gem. Instead of the machine-readable source code being extracted out of the literate documentation sources, the literate documentation is extracted out of the normal machine-readable source code files. This allows these source code files to be edited and maintained as usual. The approach is similar to that used by popular API documentation tools, such as JavaDoc. Such tools, however, generate API reference documentation, while Codnar generates a linear narrative describing the code, similar to that created by classical LP tools. Codnar can co-exist with API documentation tools, allowing both a reference manual and a linear narrative to be generated from the same set of source code files - github

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

- The Haskell (programming language)|Haskell programming language has native support for semi-literate programming. The compiler/interpreter supports two file name extensions: `.hs` and `.lhs`; the latter stands for literate Haskell.

- The LaTeX <code>listings</code> package provides a`lstlisting` environment which can be used to embellish the source code.

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

- Emacs org-mode for literate programming through Babel, which allows embedding blocks of source code from multiple programming languages 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.

- CoffeeScript supports a "literate" mode, which enables programs to be compiled from a source document written in Markdown with indented blocks of code.

- Wolfram Mathematica|Wolfram notebooks are a platform-agnostic literate programming method that combines text and graphics with live code.

- Swift (programming language), created by Apple Inc. can be edited in Playgrounds which provide 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.

- Jupyter Notebook works in the format of notebooks, which combine headings, text (including LaTeX), plots, etc. with the written code.

- Julia (programming language) 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

- Eve programming language programs are primarily prose. Eve combines variants of Datalog and Markdown with a live graphical development environment - witheve.com

- Similar to Jupyter Notebooks, R Notebooks are a method of literate programming that allows for direct interaction with R (programming language)|R (support for Python, SQL, and Bash are also explicitly named) while producing a reproducible document with publication-quality output - bookdown.org

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

# See also