2023-03-08 21:05:42 -06:00
|
|
|
# Literate Pandoc
|
2023-02-16 19:19:47 -06:00
|
|
|
|
2023-03-08 21:05:42 -06:00
|
|
|
[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].
|
2023-02-16 19:19:47 -06:00
|
|
|
|
2023-03-08 21:05:42 -06:00
|
|
|
## Requirements
|
|
|
|
|
|
|
|
- [Pandoc]
|
|
|
|
|
|
|
|
## Install
|
|
|
|
|
|
|
|
Just download this repo:
|
|
|
|
|
|
|
|
git clone https://git.cuates.net/perro/literate-pandoc.git
|
2023-02-17 13:38:38 -06:00
|
|
|
|
2023-02-16 19:19:47 -06:00
|
|
|
## Usage
|
|
|
|
|
2023-03-08 21:05:42 -06:00
|
|
|
With Pandoc installed and this repo downloaded, do:
|
2023-02-16 19:19:47 -06:00
|
|
|
|
2023-03-08 21:05:42 -06:00
|
|
|
pandoc --lua-filter PATH/TO/literate-pandoc/src/literate.lua -t FORMAT DOC
|
2023-02-16 19:19:47 -06:00
|
|
|
|
2023-03-08 21:05:42 -06:00
|
|
|
For example, if `DOC` is `source.md` and the output `FORMAT` is HTML, do:
|
2023-02-16 19:19:47 -06:00
|
|
|
|
2023-03-08 21:05:42 -06:00
|
|
|
pandoc --lua-filter PATH/TO/literate-pandoc/src/literate.lua -t html source.md
|
2023-02-16 19:19:47 -06:00
|
|
|
|
2023-03-08 21:05:42 -06:00
|
|
|
## Manual
|
2023-02-16 19:19:47 -06:00
|
|
|
|
2023-03-08 21:05:42 -06:00
|
|
|
Learn how to do LNP [here].
|
2023-02-16 19:19:47 -06:00
|
|
|
|
2023-03-08 21:05:42 -06:00
|
|
|
## Test
|
2023-02-16 19:19:47 -06:00
|
|
|
|
2023-03-08 21:05:42 -06:00
|
|
|
Inside this repo, do:
|
|
|
|
|
|
|
|
sh scripts/test.sh FORMAT1 FORMAT2
|
2023-02-16 19:19:47 -06:00
|
|
|
|
2023-03-08 21:05:42 -06:00
|
|
|
For example, if `FORMAT1` is Markdwon and `FORMAT2` is HTML, do:
|
2023-02-17 13:38:38 -06:00
|
|
|
|
2023-03-08 21:05:42 -06:00
|
|
|
sh tests/test.sh markdown html
|
|
|
|
|
|
|
|
For distribution tests, do:
|
|
|
|
|
|
|
|
sh scripts/test.sh --dist FORMAT1 FORMAT2
|
|
|
|
|
|
|
|
## Acknowledgments
|
2023-02-17 13:38:38 -06:00
|
|
|
|
2023-03-08 21:05:42 -06:00
|
|
|
This wouldn't be possible without these projects and their collaborators:
|
2023-02-17 13:38:38 -06:00
|
|
|
|
2023-03-08 21:05:42 -06:00
|
|
|
- [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.
|
2023-02-16 19:19:47 -06:00
|
|
|
|
2023-03-08 21:05:42 -06:00
|
|
|
## License
|
|
|
|
|
|
|
|
Literate Pandoc is under [GPLv3].
|
|
|
|
|
|
|
|
Happy hacking :)
|
2023-02-17 14:45:36 -06:00
|
|
|
|
2023-02-16 19:19:47 -06:00
|
|
|
[Pandoc]: https://pandoc.org/
|
|
|
|
[Pandoc filter]: https://pandoc.org/lua-filters.html
|
|
|
|
[Lua]: https://www.lua.org/
|
2023-03-08 21:05:42 -06:00
|
|
|
[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
|
|
|
|
[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
|