A compiler for Literate Erlang - inspired by Literate CoffeeScript.
The purpose of this compiler is to help new users unfamiliar with Erlang to more easily understand Erlang code on GitHub by supporting a literate style.
This is intended to reduce the barriers to new users joining the community.
The Literate Erlang, like Literate CoffeeScript is blocks of Markdown interpolated with indented blocks of Erlang. This particular dialect is aimed at GitHub-flavoured Markdown.
The Literate Erlang compiler is implemented as a
rebar plugin. For more details of
rebar and its role in Erlang development see https://github.com/rebar/rebar.
Literate Erlang files end with
.hrl.md and are stored in the
/include_md directories alonside the
/include directories as part of a normal Erlang/OTP file structure.
Details of the normal erlang directory structure can be found in the Erlang Design principles document http://www.erlang.org/doc/design_principles/applications.html#id73971
The compiler is implemented as a rebar pluging - the source code for it is in the directory
The compiler works by transforming the Literate Erlang to plain erlang and then compiling that.
Write your literate-erlang files in the directory
/src_md naming them like
mymodule.erl.md. Header files are written in
/include_md and named
Compile them to normal erlang:
and then compile that up as per normal
Note: you should put your rebar
project.app.src file in
/src_md from where will be copied over to
The tooling for literate Erlang is immature and will likely to remain that way for a long term. The reverse compiler enables authors of Erlang to write using their normal tools (ie emacs with erlang-mode or sublime-text with erlang mode) - but publish the results to their communities as Literate Erlang on GitHub.
The reverse compiler implmented as a
rebar plugin called
This turns all files ending
.erl in the
/src_md/.erl directory into markdown files which are placed in an
/src_md directory and all
.hrl files in
include_md/.hrl directory into
.hrl.md filed in
The canonical version under version control is the markdown files in the
/include_md directories. So the first step is to compile them to erlang:
Then copy the
.erl files to the directory
src_md/.erl and the `..hrl
files to/include_md/.hrl`` and edit them there.
The production of working beam files is then:
This is the simplest possible implementation of a Literate Erlang compiler designed to establish the idea and get it working on GitHub. There are plenty of ways it could be improved.
- it has no tooling - no SublimeText plugins or Emacs major modes - they would be nice
- it has no native Erlang markup compiler to turn it into html. There is an Erlang Markdown compiler (https://github.com/erlware/erlmarkdown) which could be used to do that. It currently supports normal Markdown and not GitHub-flavoured markdown.
Users on Windows/Macs can have this preview rendered by GitHub for a higher level of fidelity.
Contributing is easy, fork and fire away.