Request for comments on proposal for literate programming using markdown

Simon Hengel sol at typeful.net
Mon Aug 13 16:18:34 CEST 2012


Hi Philip,

On Mon, Aug 13, 2012 at 12:57:44PM +0000, Philip Holzenspies 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.

Thanks a lot for the clarification.

I see some value in your proposal to replace GHC's unlit, mainly in
terms of setting a common standard.  Personally, I'd still feel more
comfortable if that proposed standard would be developed as a Hackage
package, so that it can proof itself useful first.  I'm less convinced,
that it should be inlined into GHC (I do agree, that this would be
necessary, if you want to include the markdown into the AST.  But where
is the user?  HsSyn does not even use the GHC API, AFAIK.).

Anyway, just my *personal* opinion ;)

> Would there be a benefit to *not* doing this other than *me* not
> having to do the work?

Yes, currently you can replace the unlit phase.  So you can use
arbitrary markup in .lhs files.  Which I think is quite useful.

Changing this would also have practical implications.  Let's assume I
want to use my favorite markup language *foo* in .lhs files, after a lot
of bikeshedding the community agrees that *foo* is a good idea, and I
have to modify GHC to add support for *foo*, then:

 * The barrier to modify GHC is still much higher than writing a custom
   unlit.

 * I have to wait for the next GHC release before I can use *foo*.

 * When finally a new version of GHC with support for *foo* has been
   released, a program that uses *foo* will still only work with the
   latest version of GHC.  If I e.g. want to support the latest three
   major versions of GHC, I need to wait an other year before I can
   actually use *foo*.

Cheers,
Simon



More information about the Glasgow-haskell-users mailing list