@hackage readme-lhs0.2.1

See readme.md

readme-lhs Build Status

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

import Protolude
import Readme.Lhs

code

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

10! is equal to:

3628800

Output that doesn’t exist is simply cleared.

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