• Literate Programming made easy
  • Create live documents in Markdown
  • Program in any language you like
  • Use your favourite editor/IDE
  • Works well with version control

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

With the 2.0 release, Entangled is now available as a Python package, installable through pip,

pip install entangled_cli

Write Markdown

“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

Documentation

Bootstrap web template for Pandoc

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

Blogs

Literate Books

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

Pharr, Jakob & Humphreys - Physically Based Rendering

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.

PBRT
Sussman & Wisdom - Structure and Interpretation of Classical Mechanics

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 descriptions of physics.

SICM
Hudak & Quick - The Haskell School of Music

Hudak & Quick - The Haskell School of Music

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

HSOM

Pandoc filters

Dev tools