[Haskell-cafe] Markdown extension for Haddock as a GSoC project

[John MacFarlane]

I agree with Chris that it would be better to have a standard syntax for
Haskell documentation.  Especially if the alternative is ten different
markup languages. (Remember, all of these need to be supported in
haddock, which is a basic piece of infrastructure.)

Here's a thought.  Instead of adding support for markdown, why not
enhance the existing haddock markup, making it more expressive, so that
it could encode the same range of structural features as markdown?

If this were done, we could add a haddock writer to pandoc.  There is
already a haddock reader in the development version, but a writer is
difficult because haddock is so much less expressive than other formats.
For example, unless I'm mistaken, it doesn't allow list items with
multiple paragraphs or other block elements, or nested lists, or images,
or blockquotes.

With a pandoc reader and writer for haddock, it would be easy to write
your documentation in any format you choose (several variants of
markdown, reST, textile, LaTeX, HTML, mediawiki) and produce equivalent
haddock markup to paste into the source file.

It would also be easy to convert the documentation in your source file
to any of the formats supported by pandoc.  So, you could generate a man
page from your haddock markup, or a web page or blog entry, or a LaTeX
document.

It seems to me that this would provide most of the advantages people
who want a markdown extension for haddock are looking for.  But it would
not require taking sides in markdown/reST/asciidoc/creole wars,
and it would not lead to the fragmentation of documentation formats
in Haskell source code.  If the extensions to haddock markup were done
carefully, it wouldn't even require a special PRAGMA, since all existing
markup would have the same interpretation in the extended markup.

John

+++ Chris Smith [Apr 27 13 12:05 ]:
>    I don't agree with this at all. Far more important than which
>    convention gets chosen is that Haskell code can be read and written
>    without learning many dialects of Haddock syntax. I see an API for
>    pluggable haddock syntax as more of a liability than a benefit. Better
>    to just stick to what we have than fragment into more islands.
> 
>    I do think that changing Haddock syntax to include common core pieces
>    of Markdown could be a positive change... but not if it spawns a battle
>    of fragmented documentation syntax that lasts a decade.
>    On Apr 27, 2013 11:08 AM, "Bryan O'Sullivan" <[3]bos at serpentine.com>
>    wrote:
> 
>    On Sat, Apr 27, 2013 at 2:23 AM, Alistair Bayley
>    <[4]alistair at abayley.org> wrote:
> 
>    How's about Creole?
>    [5]http://wikicreole.org/
>    Found it via this:
>    [6]http://www.wilfred.me.uk/blog/2012/07/30/why-markdown-is-not-my-favo
>    urite-language/
>    If you go with Markdown, I vote for one of the Pandoc implementations,
>    probably Pandoc (strict):
>    [7]http://johnmacfarlane.net/babelmark2/
>    (at least then we're not creating yet another standard...)
> 
>    Probably the best way to deal with this is by sidestepping it: make the
>    support for alternative syntaxes as modular as possible, and choose two
>    to start out with in order to get a reasonable shot at constructing a
>    suitable API.
>    I think it would be a shame to bikeshed on which specific syntaxes to
>    support, when a lot of productive energy could more usefully go into
>    actually getting the work done. Better to say "prefer a different
>    markup language? code to this API, then submit a patch!"
> 
>      _______________________________________________
>      Haskell-Cafe mailing list
>      [8]Haskell-Cafe at haskell.org
>      [9]http://www.haskell.org/mailman/listinfo/haskell-cafe
> 
> References
> 
>    1. mailto:cdsmith at gmail.com
>    2. mailto:bos at serpentine.com
>    3. mailto:bos at serpentine.com
>    4. mailto:alistair at abayley.org
>    5. http://wikicreole.org/
>    6. http://www.wilfred.me.uk/blog/2012/07/30/why-markdown-is-not-my-favourite-language/
>    7. http://johnmacfarlane.net/babelmark2/
>    8. mailto:Haskell-Cafe at haskell.org
>    9. http://www.haskell.org/mailman/listinfo/haskell-cafe

> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe