computable-pandoc/README.md

# 👾 Computable Pandoc

Computable Pandoc is a [Pandoc filter] written in [Lua] for [literate] and
[natural] programming (LIN programming), i.e.: "[Programming \[...\] as the
process of creating works of literature][1]".

## Requirements

-   [Pandoc] v3

if you decide to use `lin.min.lua` instead of `lin.bundle.lua`, you need to
install and preload the following rocks:

-   [fennel]
-   [lua-dog]

## Install

1.  Go to [Releases].
2.  Download the latest version of `lin.bundle.lua` or `lin.min.lua`.
3.  Done!

## Usage

With `lin.bundle.lua` or `lin.min.lua` downloaded and Pandoc installed, do:

    pandoc -L PATH/TO/lin.bundle.lua -t FORMAT DOC

For example, if `DOC` is `source.md` and the output `FORMAT` is HTML, do:

    pandoc -L PATH/TO/lin.bundle.lua -t html source.md

## Manual

Learn how to do LIN programming [here].

## Develop

Clone this repo:

    git clone https://git.cuates.net/perro/computable-pandoc.git

Enter the repo:

    cd computable-pandoc

Inside, do the tests:

    pandoc lua scripts/test.lua

For other kind of tests, do:

    pandoc lua scripts/test.lua -h

For make distribution filter, do:

    pandoc lua scripts/make_dist.lua

For make JSON (intented for testing asserts), do:

    pandoc lua scripts/make_jsons.lua

For update Lua modules (needs [`luarocks`]), do:

    sh scripts/get_rocks.sh

Contribute!

## Acknowledgments

This wouldn't be possible without these projects and their collaborators:

-   [Pandoc][]: universal document converter and parser; handles the
    requirements for LIN.
-   [Lua][]: programming language; enables LIN.
-   [Fennel][2]: [Lisp] dialect with full Lua compatibility; allows native
    evals for Lisp.

## License

Computable Pandoc is under [GPLv3].

Happy hacking :)

  [Pandoc filter]: https://pandoc.org/lua-filters.html
  [Lua]: https://www.lua.org/
  [literate]: https://en.wikipedia.org/wiki/Literate_programming
  [natural]: https://en.wikipedia.org/wiki/Natural-language_programming
  [1]: https://web.archive.org/web/20170605163729/http://www.desy.de/user/projects/LitProg/Philosophy.html
  [Pandoc]: https://pandoc.org/
  [fennel]: https://luarocks.org/modules/technomancy/fennel
  [lua-dog]: https://luarocks.org/modules/perro/lua-dog
  [Releases]: https://git.cuates.net/perro/computable-pandoc/releases
  [here]: https://git.cuates.net/perro/computable-pandoc/src/branch/no-masters/man/README.md
  [`luarocks`]: https://luarocks.org/
  [2]: https://fennel-lang.org
  [Lisp]: https://en.wikipedia.org/wiki/Lisp_(programming_language)
  [GPLv3]: https://git.cuates.net/perro/computable-pandoc/src/branch/no-masters/LICENSE.txt