readme-lhs

The language in which we express our ideas has a strong influence on our thought processes. Knuth

ghc options

{-# OPTIONS_GHC -Wall #-}

pragmas

{-# LANGUAGE NoImplicitPrelude #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE DataKinds #-}
{-# LANGUAGE ScopedTypeVariables #-}
{-# LANGUAGE TypeOperators #-}
{-# LANGUAGE FlexibleInstances #-}

libraries

• protolude
• readme-lhs

import Protolude
import Readme.Lhs

code

• hoogle

main :: IO ()
main = do
  let n = 10
  let answer = product [1..n::Integer]
  void $ runOutput ("example.lhs", LHS) ("readme.md", GitHubMarkdown) $ do
    output "example1" (Fence "Simple example of an output")

Simple example of an output

    output "example2" (Fence (show answer))

10! is equal to:

3628800

As well as fenced output, output can be Text that replaces the {.output} code block

    output "example3" (Replace "Fenced code block was overwritten")

Fenced code block was overwritten

or be native pandoc.

    output "example4" (Native [BulletList [[plain "a"], [plain "bullet"], [plain "list"]]])

• a
• bullet
• list

Output that doesn’t exist is simply cleared.

Fenced code block was overwritten

Technicals

This is an example of mixing literate haskell with markdown, and in using readme-lhs. The file is composed of several elements:

• literate haskell. Bird-tracks are used, as the alternative lhs method is latex. Pandoc can read this, but defaults to bird tracks when rendering markdown+lhs.

• markdown. All non bird-tracked lines are considered to be markdown. It’s probably incompatible with haddock. This might be easily fixable.

• fenced code blocks with an output class, which are used to insert computation results. The fenced code blocks look like:

  ```{.output .example} ```

As it currently stands, ghc cannot read a file with fenced code-blocks that look like:

\```haskell
\```

Given this, a file cannot be both a valid haskell file, and a markdown file that is rendered nicely by github. This would resolve with adoption of the literate markdown ghc proposal.

template

A bare bones stack template is located in other/readme-lhs.hsfiles. It contains what you need to quickly get started with literate programming.

workflow

stack build --test --exec "$(stack path --local-install-root)/bin/readme-lhs-example" --file-watch