• Make your code look beatiful
• Create live documents in Markdown
• Program in any language you like
• Use your favourite editor
• Works well with version control
• Powered by Pandoc

Literate programming /ˈlɪtəɹət ˈpɹəʊɡɹæmɪŋ/ (computing) 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, such as English, interspersed with snippets of macros and traditional source code, from which a compilable source code can be generated. Wikipedia

# About

Entangled helps you write Literate Programs in Mardown. You put all your code inside Markdown code blocks. Entangled automatically extracts the code and writes it to more traditional source files. You can then edit these generated files, and the changes are being fed back to the Markdown.

We’re trying to increase the visibility of Entangled. If you like Entangled, please consider adding this badge to the appropriate location in your project:

[![Entangled badge](https://img.shields.io/badge/entangled-Use%20the%20source!-%2300aeff)](https://entangled.github.io/)

# Get started

“A critical aspect of a programming language is the means it provides for using names to refer to computational objects.” Abelson, Sussman & Sussman - SICP

#### Name your code

 The square of the hypothenuse is the sum
of the two right-angled sides squared:
$$a^2 + b^2 = c^2$$

 {.python #pythagoras}
def vector_length(x, y):
return sqrt(x**2 + y**2)


The square of the hypothenuse is the sum of the two right-angled sides squared: $a^2 + b^2 = c^2$

«pythagoras»=

def vector_length(x, y):
return sqrt(x**2 + y**2)

“Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.” Knuth - Literate Programming

#### Compose your program

 To count the words in a sentence, first
split the sentence into words, then
count the number of words in the list.

 {.python #word-count}
def word_count(sentence):
<<split-into-words>>
<<count-words>>
return count


The default arguments to the .split
method split on any white space.

 {.python #split-into-words}
words = sentence.split()


Counting is done with the length
function.

 {.python #count-words}
count = len(words)


To count the words in a sentence, first split the sentence into words, then count the number of words in the list.

«word-count»=

def word_count(sentence):
<<split-into-words>>
<<count-words>>
return count

The default arguments to the .split method split on any white space.

«split-into-words»=

words = sentence.split()

Counting is done with the len function.

«count-words»=

count = len(words)

“Talk is cheap. Show me the code.” Linus Torvalds

#### Test your documentation

 Counting words, the zero-case:

 {.python .eval #word-count}
word_count("")


And a small sentence:

 {.python .doctest #word-count}
word_count("Hebban olla uogala")
---
4


Counting words, the zero-case:

«word-count»+

word_count("")
0

And a small sentence:

«word-count»+

word_count("Hebban olla uogala")
3
4

# Documentation

The latest version of Entangled is

«entangled-version»=

entangled --version
1.2.4

# Installing Entangled

## Prebuilt binaries

We provide a prebuilt binary for Linux. The binary is statically compiled, so it should run on any distro. You can download them from the Github releases section. We’re still working on providing binaries for Windows and MacOS.

If you downloaded the latest tarball, you can install Entangled by copying the contents to ~/.local/, or /usr/local. If you prefer an uncluttered local directory, checkout GNU Stow.

## From source

Entangled is written in Haskell, and can be built on Linux, MacOS and Windows. Currently the best way to install, is to git clone https://github.com/entangled/entangled, and build with GHC ≥ 8.6 using Cabal 3.0. Most GNU/Linux distributions ship an older version of Haskell. The easiest way to install a newer version is through GHCUp.

## Running Entangled with Docker

Entangled is available as a Docker image.

Assuming you have created a Markdown file, say program.md, you can start entangled by running

docker run --rm --user $(id -u):$(id -g) --volume \$PWD:/data \
nlesc/entangled deamon ./program.md

This command starts a Docker container with the current working directory mounted as /data and running with your user/group id so files are written with the correct ownership.

## Pandoc filters

We have created a set of Python based Pandoc filters that can:

• (forward) Tangle your code
• Add name tags to rendered output
• Run documentation tests through Jupyter

It is easy to install and has almost no dependencies outside of Pandoc and a recent version of Python (≥ 3.7). This also makes the Python filters very easy to setup on automated builds, like Github Actions.

Install these filters using:

    pip install entangled-filters

More information on Entangled filters: https://github.com/entangled/filters

## Bootstrap web template

To help you easily create a presentable website from your literate code, we provide a Bootstrap template for Pandoc. Probably the best way to use this template, is to fork our repository at entangled/bootstrap-submodule, and add your fork as a submodule in your project:

    git submodule add git@github.com:<my bootstrap-submodule fork>

This way you can tweak the template to your own wishes. If you want to play around first, you can also use the cookiecutter template,

    cookiecutter https://github.com/entangled/bootstrap

but this approach is less flexible. For more information, see the tutorial.

# External Links

### Literate Books

These are some awesome books written with a literate philosophy in mind.

### Pharr, Jakob & Humphreys - Physically Based Rendering

Explains physically realistic 3D rendering, while implementing the same techniques in C++. This book is so amazing, it actually won an Acadamy Award for technical achievement. The book uses the same noweb notation for code block references we do.

### Sussman & Wisdom - Structure and Interpretation of Classical Mechanics

Does not use noweb, but subscribes to the many founding principles of literate programming. This is a text book on classical mechanics and specifically the Lagrangian and Hamiltonian discriptions of physics.

### Hudak & Quick - The Haskell School of Music

From signals to symphonies, this book fuses the authors’ passion for music and the Haskell programming language.

### Pandoc filters

• Knitty — Expands code-cells through a Jupyter interface. Uses Panflute.
• pandocsql — Inserts tables in your markdown into an Sqlite database, and run queries that appear as tables in the output. Uses Panflute.

### Dev tools

• Panflute — A “Pythonic” interface for creating Pandoc filters.