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

> NOTE: Pandoc has [Literate Haskell support], but it doesn't support all input
> and output formats. This filter tries to support to all of them.

## 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 :)

## TODO

In order to support any markup language, the filter:

-   Can't rely in the built-in pandoc code blocks.
-   Requires syntaxis for custom literate programming blocks.

[^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/
  [Literate Haskell support]: https://pandoc.org/MANUAL.html#literate-haskell-support
  [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