Changes between Version 2 and Version 3 of LiterateMarkdown


Ignore:
Timestamp:
Jun 22, 2013 11:57:51 PM (10 months ago)
Author:
diatchki
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • LiterateMarkdown

    v2 v3  
    33Markdown has grown in popularity since github started encouraging people to write their documentation with it. 
    44Github highlights the source according to how it's labeled, so the haskell code blocks look nice, as do the HTML blocks. 
    5 As an example, here is a blog post written in markdown and rendered by github's source view (please ignore the metadata at the top of the rendered output, as it's only relevant to octopress): 
     5As an example, here is a blog post written in markdown and rendered by github's source view: 
    66 
    77https://github.com/elliottt/elliottt.github.com/blob/source/source/_posts/2013-02-19-serenade-in-haskell.markdown 
     
    1414 
    1515== Current Literate Processing == 
     16 
     17Haskell already supports literate files, using two different styles: 
     18 
     19Using "bird-tracks": 
     20{{{ 
     21This is a comment.  Lines starting with '>' are the actual code. 
     22 
     23> average xs = sum xs / length xs 
     24}}} 
     25 
     26Or, using the LaTeX compatible notation: 
     27{{{ 
     28This is a comment. 
     29 
     30\begin{code} 
     31average = sum xs / length xs 
     32\end{code} 
     33}}} 
     34 
     35Unfortunately, neither of this is compatible with mark-down: in mark-down the bird-tracks signify quoting (in the same way as e-mail clients work), 
     36and, of course, `\begin{code}` is LaTeX.  
     37 
     38== The Proposal == 
     39 
     40The idea is to extend Haskell's literate notation so that it is compatible with markdown, in the same way, that `\begin{code}` makes 
     41it work with LaTeX.  This is great for two reasons: 
     42  1. `markdown` is a simple language that is used by many programmers 
     43  2. there are many existing tools that know how to process the `markdown` notation (e.g., `github`, `pandoc`, etc.) 
     44 
     45To support literate Haskell written in markdown we need two changes: 
     46  1. A new way to indicate what are the code parts in a literate Haskell file 
     47  2. (Optional, but nice.)  Disable bird-tracks style Haskell blocks in markdown files, so that GHC does not accidentally interpret quotes as code. 
     48 
     49 
     50 
     51 
     52 
     53 
    1654 
    1755There is one open ticket on the bug tracker about markdown as a literate format, #4836, that concerns unlit not processing markdown correctly.  As unlit attempts to preserve CPP in the whole file unless otherwise instructed, markdown headings are treated as CPP and left in.