computable-pandoc/README.md

# Literate Pandoc

[Pandoc] is a world famous "swiss-army" document converted. This is because
Pandoc is also a document parser. Thanks to this capability, this repo is a
[Pandoc filter] written in [Lua] for [literate] and [natural] programming
(LNP), i.e.: ["Programming \[...\] as the process of creating works of
literature"][1].

## Requirements

-   [Pandoc]

## Install

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

## Usage

With `literate.min.lua` downloaded and Pandoc installed, do:

    pandoc --lua-filter PATH/TO/literate.min.lua -t FORMAT DOC

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

    pandoc --lua-filter PATH/TO/literate.min.lua -t html source.md

## Manual

Learn how to do LNP [here].

## Test

Inside this repo, do:

    sh scripts/test.sh FORMAT1 FORMAT2

For example, if `FORMAT1` is Markdwon and `FORMAT2` is HTML, do:

    sh tests/test.sh markdown html

For distribution tests, do:

    sh scripts/test.sh --dist FORMAT1 FORMAT2

## Acknowledgments

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

-   [Pandoc][]: universal document converter and parser; handles the
    requirements for LNP.
-   [Lua][]: programming language; enables LNP.
-   [Fennel][]: [Lisp] dialect with full Lua compatibility; allows to go from
    LNP to Lisp or Lua.

## License

Literate Pandoc is under [GPLv3].

Happy hacking :)

  [Pandoc]: https://pandoc.org/
  [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
  [Releases]: https://git.cuates.net/perro/literate-pandoc/releases
  [here]: https://git.cuates.net/perro/literate-pandoc/src/branch/no-masters/man/README.md
  [Fennel]: https://fennel-lang.org
  [Lisp]: https://en.wikipedia.org/wiki/Lisp_(programming_language)
  [GPLv3]: https://git.cuates.net/perro/literate-pandoc/src/branch/no-masters/LICENSE.txt