Changes between Version 6 and Version 7 of LiterateMarkdown


Ignore:
Timestamp:
Jun 23, 2013 12:16:57 AM (10 months 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 .