Request for comments on proposal for literate programming using markdown

[Simon Marlow]

On 22/08/12 16:22, Philip Holzenspies wrote:
>
> On 22 Aug 2012, at 16:13, Brandon Allbery wrote:
>
>> On Wed, Aug 22, 2012 at 4:37 AM, Philip Holzenspies
>> <pkfh at st-andrews.ac.uk <mailto:pkfh at st-andrews.ac.uk>> wrote:
>>
>>     So, there are many things people read in the proposal that I
>>     didn't want to put in, but the things I very much do want to
>>     include get lost in translation also. I wanted to allow the GHC
>>     source itself to be written in markdown.
>>
>>
>> If the existing source tree is using one form of markup, changes and
>> additions should really be consistent with what's already there
>> instead of introducing a new kind of markup. This could actually be
>> *more* disruptive.
>
> The point was that quite a bit of the GHC source has markdown-like
> things in it, using LaTeX-style code-fencing, but LaTeX-incompatible
> markup (like underlining section with ~~~~~).

I tend to gently nudge the codebase towards illiterate source whenever I 
can.  This is probably a personal preference, but I haven't been 
convinced that literate code is worth the effort.  I want the code to 
look its most readable in a text editor, which is where I look at it most.

Now, perhaps if I had an editor that rendered the markdown on the fly 
while syntax-highlighting the code, maybe that would tip the balance. 
(the editor must be emacs, though).

I have nothing against adding the extension you propose to GHC, I'm just 
not sure that we'll actually want to use it in GHC.

Cheers,
	Simon