computable-pandoc/README.md

# Literate Pandoc

Literate Pandoc is a [Pandoc reader] 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.lua`.
3.  Done!

## Usage

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

    pandoc -f PATH/TO/literate.lua -t FORMAT DOC

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

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

## Manual

Learn how to do LNP [here].

## Test

Clone this repo:

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

Enter the repo:

    cd literate-pandoc

Inside, 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 reader]: https://pandoc.org/custom-readers.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/
  [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