Changes between Version 6 and Version 7 of LiterateMarkdown


Ignore:
Timestamp:
Jun 23, 2013 12:16:57 AM (2 years ago)
Author:
diatchki
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • LiterateMarkdown

    v6 v7  
    4848
    4949
     50=== How to Recognize Code Blocks ===
    5051
    51 
    52 
    53 
    54 
    55 There 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.
     52A new code block would be started by {{{```}}} or {{{```haskell}}} at the beginning of a line, the code starts on the next line.  The code block
     53is terminated by a line that starts with {{{```}}}.  For example:
    5654
    5755{{{
    5856# Heading
     57
     58This is a comment, and next there will be some code:
    5959
    6060```haskell
     
    6464}}}
    6565
    66 Is translated to the following by unlit:
     66Markdown supports snippets of code in different languages, which is why there is {{{haskelll}}} after the ticks.
     67If a language is not explicitly specified, then we assume that the block contains Haskell---after all, we are
     68working with literate Haskell files. 
    6769
    68 {{{
    69 # Heading
     70=== When to Use Literate Markdown ===
     71
     72Currently, GHC supports mixing various styles code blocks---one may have a literate Haskell
     73file that contains both bird-tracks and LaTeX style literate Haskell.   It is very unclear if
     74this generality is ever useful.
     75
     76For literate markdown we propose a different approach: the style of the literate Haskell file
     77will be determined by the file's extension.  So, if the compiler is handed a file ending in `.md` or `.markdown`,
     78the common suffixes for `markdown` files, then it will unlit the file using the markdown convention.
     79Ordinary `.lhs` files will be processed as usual, so this is fully backward compatible.
    7080
    7181
    72 x :: Int
    73 x  = 10
    7482
    75 }}}
     83== Implementation ==
    7684
    77 == Handling Markdown ==
     85The above design has been implemented in https://github.com/elliottt/ghc/tree/literate-markdown .
    7886
    79 As markdown has two commonly used extensions, .md and .markdown, it seems reasonable to instruct unlit to not attempt to keep lines that it views as CPP from within code blocks.  Unlit has two flags that should be able to handle this, -r and -#, which when combined will not leave any markdown headers in the resulting source.
     87The implementation involved the following:
    8088
    81 Additionally, if the .md and .markdown extensions are to be supported, it should be reasonable to start ghci simply using the module name, and have ghc also search for files with those extensions.
     89  1. Modify `unlit` to support the new form of code block
     90  2. Don't get confused with CPP handline (see bug #4836)
     91  3. Make GHC look for modules in `.md` and `.markdown` files.
     92  4. TODO: when unliting markdown, do not recognize bird-tracks as code blocks.
    8293
    83 == Patch ==
    84 
    85 The above suggestion has been implemented in https://github.com/elliottt/ghc/tree/literate-markdown .