Request for comments on proposal for literate programming using markdown

Philip Holzenspies pkfh at st-andrews.ac.uk
Mon Aug 13 14:57:44 CEST 2012


On 13 Aug 2012, at 13:20, Simon Hengel wrote:
> What is the benefit of doing so?

- Simpler build environment
- Easier to understand interaction and bugs resulting from them (viz. [1], [2]), because the interactions happen in the same domain
- (as mentioned in the proposal) Simplification of the API; not going through temp-files (which, by the way, I don't understand anyway; why not through pipes? Probably pipes are harder to do under Windows).
- (minor) May well help speed things up by not having to reread every file three times and write it twice before actually coming to GHC's parser
- Helps pull the code for unlit into the community; it seems nobody's looking at it at the moment. The README in utils/unlit/ still hails the merits of code-sharing between GHC and LML/HBC, but I don't believe this sharing exists (actively) anymore and it keeps people from improving it. Part of improving it would be to add a little more documentation / commenting. For example, can you explain why "myputc(c,stream)" is called when "c == '#'", regardless of whether we are inside or outside of a code block? I've thought about it for a bit and can't come up with an answer.
- If it is only an optional replacement unlitter in the GHC build system, there is no reward for GHC-hackers to agree on a consistent style of making important notes. Currently, my workflow (when *using* the GHC API) involves the haddock-generated API-documentation, the HsColour generated html-source and the actual source code, because many "[Note: Something or Other]" are formatted in a markdown-style (as already mentioned in the proposal), which turn out unformatted (and thereby largely unreadable) in the generated html.
- Building on the benefit above: As haddock support is being built into the GHC API by keeping comments in the HsSyn, so also could any markdown commenting be built-in for HsColour support. This would lead to much better public documentation of the API, *without* GHC-hackings changing what they do now, i.e. writing block notes in the source.

They may not all be as valuable to everyone, but together they're enough to motivate me to have a go at it. Would there be a benefit to *not* doing this other than *me* not having to do the work?

Regards,
Philip


[1] http://hackage.haskell.org/trac/ghc/ticket/6144
[2] http://hackage.haskell.org/trac/ghc/ticket/4836




More information about the Glasgow-haskell-users mailing list