# Request for comments on proposal for literate programming using markdown

Philip Holzenspies pkfh at st-andrews.ac.uk
Mon Aug 13 13:02:59 CEST 2012

Dear Simon,

On 13 Aug 2012, at 10:23, Simon Hengel wrote:
> I think it makes sense, that you do not want to depend on pandoc for
> GHC's build process.  But would a more lightweight unlit for Markdown
> work?

Ultimately, all unlitting does is replace things not in code blocks by white lines. Bird-style unlitting also replaces '>' at the start of a line with a space. It doesn't take that much.

> Hmm, one issue could arise with a huge codebase (like GHC's) that uses
> both traditional literate Haskell and Markdown.  You can't set the unlit
> program globally then.  I think this could be solved by adding
>
>    {-# OPTIONS_GHC -pgmL unlit-markdown #-}
>
> to source files that use Markdown.  Sadly this is no valid Markdown, so
> it is not really sane to add it to a Markdown file.

This would be a way to do it with the means available now. My proposal, however, is to replace the external unlit and cpp binaries, the former of which is shipped as source with the GHC code, built separately and then called as an external program from the compiler. The latter is assumed to be present on the host system and also called as an external program. My proposition is to replace these external programs by code *inside* GHC.

There is indeed no formal standard for Markdown declaring one version of the language 'valid' but it's like the unlitting for LaTeX-style lhs; there is no standard for LaTeX, so there is no Valid LaTeX, but you can still define the unlitting nicely by saying; you need to stick "\begin{code}" on a line, starting at column 1, not followed by anything. The same can be done for Markdown. Just choose a style. I suggested using GitHub style-markdown. Then the unlitting is just defined as: stick three backticks followed by "hs" or "haskell" onto a line, starting at column 1, not followed by anything.

> Would it work to adapt GHC's option sniffing, so that it recognizes
> options in HTML comments (which are valid Markdown):
>
>    <!-- OPTIONS_GHC -pgmL unlit-markdown -->
>
> Possibly with the requirement that it has to be on the first line, and
> maybe guarded by a flag (e.g. -ext-options-sniffing)?

Again; this could well work, but it's only relevant if we're wanting to have the unlitting as an external process. If we build the unlitter into GHC, we need not pollute the files with options to be passed to the compiler. See the proposal for suggested ways of disambiguating Markdown files. We could also add an option to GHC to say that a file is in Markdown mode, overruling all the detection mechanisms suggested in the proposal, but it wouldn't be a pgm-option, because it wouldn't be about calling something external.

Regards,
Philip