Skip to content

Commit

Permalink
Add deprecation message to README
Browse files Browse the repository at this point in the history
  • Loading branch information
sol committed Oct 13, 2012
1 parent 164261d commit f1a0b8d
Showing 1 changed file with 2 additions and 97 deletions.
99 changes: 2 additions & 97 deletions README.markdown
Original file line number Diff line number Diff line change
@@ -1,97 +1,2 @@
# Literate Haskell support for GitHub's Markdown flavor

> `pandoc-unlit` allows you to have a `README.markdown`, that at the same
> time is a *literate Haskell* program.
The following steps show how to set things up, so that:

* The Haskell code in your README.markdown gets syntax highlighted on GitHub
* You can run your literate Haskell within GHCi
* You can create a Cabal `test-suite` from your `README.markdown` (No broken
code examples anymore. *Yeah!*)

### 1. Install `pandoc-unlit`

$ cabal update && cabal install pandoc-unlit


### 2. Create a `README.markdown`


# nifty-library: Do nifty things (effortlessly!)

Here is a basic example:

~~~ {.haskell .literate}
main :: IO ()
main = putStrLn "That was easy!"
~~~

And here is some code that looks nice, but does not yet work:

~~~ {.haskell}
main :: IO ()
main = launchMissiles
~~~

We use fenced code blocks here. They are supported by both, GitHub's README
renderer, and Pandoc.

All code blocks with class `.haskell` are syntax highlighted on GitHub
([like so](https://github.com/sol/pandoc-unlit/blob/master/example/README.markdown#readme)).

All code blocks with classes `.haskell` and `.literate` are part of the
literate program.

### 3. Create a symbolic link `README.lhs -> README.markdown`

$ ln -s README.markdown README.lhs

### 4. Run yor code

At this point we can load the code into GHCi:

$ ghci -pgmLpandoc-unlit README.lhs
*Main> main
That was easy!

Or better yet, pipe the required flag into a `.ghci` file, and forget about it:

```
$ echo ':set -pgmLpandoc-unlit' > .ghci
```
```
$ ghci README.lhs
*Main> main
That was easy!
```

### 5. Create a Cabal `test-suite`

```
name: nifty-library
version: 0.0.0
build-type: Simple
cabal-version: >= 1.8
library
-- nothing here yet
test-suite readme
type: exitcode-stdio-1.0
main-is: README.lhs
build-depends: base
ghc-options: -pgmL pandoc-unlit
```

Run it like so:

$ cabal configure --enable-tests && cabal build && cabal test

## Real world examples

* [attoparsec-parsec](https://github.com/sol/attoparsec-parsec#readme)
* [hspec-expectations](https://github.com/sol/hspec-expectations#readme)
* [wai](https://github.com/yesodweb/wai/tree/master/wai#readme)

That's it, have fun!
This package is deprecated. Use
[markdown-unlit](https://github.com/sol/markdown-unlit) instead.

0 comments on commit f1a0b8d

Please sign in to comment.