computable-pandoc/README.md

# Pandoc Literate Programming

[Pandoc] is world famous as a "swiss-army" document converted. However, this is
because Pandoc is also a document parser. Thanks to this capability, this repo
is a [Pandoc filter] for [literate programming][]: evaluate the code written in
your documents with Pandoc and [Lua].

## Usage

In your terminal, just execute:

    sh tests/test.sh FORMAT

Pick one or more [FORMAT namespaces], e.g.:

    sh tests/test.sh markdown html

You can also use this filter for your documents:[^1]

    pandoc --lua-filter literate.lua -t FORMAT YOUR_DOC

Besides your document, you must add the class `eval` in the [fenced code
blocks] that you want to evaluate. If you also want to replace the code block
content with the evaluation result, you also must add the class `replace`.
Check [this test] if you don't known what I am talking about.

Happy hacking :)

[^1]: Right now this is only for testing, so only a subset of Lisp function are
    supported (`+`, `list`, `first`)... The objective is to support any
    programming language and more!

  [Pandoc]: https://pandoc.org/
  [Pandoc filter]: https://pandoc.org/lua-filters.html
  [literate programming]: https://en.wikipedia.org/wiki/Literate_programming
  [Lua]: https://www.lua.org/
  [FORMAT namespaces]: https://pandoc.org/MANUAL.html#option--to
  [fenced code blocks]: https://pandoc.org/MANUAL.html#fenced-code-blocks
  [this test]: https://git.cuates.net/perro/literate-pandoc/src/branch/no-masters/tests/src/t2.md?display=source