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

[Mateusz Kowalczyk]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 27/04/13 22:18, John MacFarlane wrote:
> 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
> 
> _______________________________________________ Haskell-Cafe
> mailing list Haskell-Cafe at haskell.org 
> http://www.haskell.org/mailman/listinfo/haskell-cafe
> 
I was under the impression that Markdown specifically was requested
due to its high popularity, ease of writing and being very readable to
a human. As you mention, currently Haddock is not expressive enough to
have a writer and would need extending first.

The advantages of extending Haddock this way are obvious: people write
the documentation in whatever they want and then use Pandoc to convert
it to a format they want to distribute in.

I'm unsure however whether such an extension is strictly a good thing:
what's more readable in source: Haddock with even more stuff tacked on
or Markdown with some already present Haddock constructs? There are a
fair few complaints about how unwieldy Haddock currently is and I'm
worried that extending it for the sake of (a really nice) ability of
conversion between formats with Pandoc might make it even more
unwieldy. Yes, you can write the docs in any of the billion formats
Pandoc supports and then convert it but many people simply want to
write docs right into their source files, right as they write actual
code without reliance on external tools -- something Markdown would
excel at if implemented.

So in the end, it just comes down to to what the community _really_
wants: more expressive core Haddock with ability to convert between
the formats or yet another Markdown flavour tacked onto Haddock as an
extension. It should be noted that this would probably end up serving
as a basis for the Pandoc module anyway so why duplicate the effort?
Pandoc already handles Markdown, as Christopher Howard pointed out.


Discussion on the topic will is most welcome. I am one of the students
interested in this project and I have already written a draft proposal
with the idea of implementing Markdown as an extension because that's
what it seems the community wanted in previous threads and
discussions. Is this _really_ what we want though?

Personally, I think the benefits of extending Haddock itself and
writing a writer module for Pandoc not only cover everything a new,
Haskell specific Markdown could do but provide even greater
flexibility. I'd also prefer to work on extending Haddock rather than
just tacking an extension to it that might not get used because some
people might dislike Markdown and would miss out on any new features.

The SoC proposal deadlines are on 3rd of May so it'd be great to hear
some opinions on this within the next 3 days or so, after which point
I will adjust my proposal accordingly, cross my fingers and hope for
the best ;)

- -- 
Mateusz K.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.19 (GNU/Linux)

iQIcBAEBAgAGBQJRfFXcAAoJEM1mucMq2pqX8kkQAI+xRwMOVsq9T14bKLZ3Wiv7
citbn/hWDYSC8zpSnFIGW87On9/phBIhXaBA5F878mao0AAOMmN0S2ZfcTusaRjk
zXm2Dfof6ZKa38xTTjcoBuNWvv7mNwY8592krRPKden2if+II+2bXEd8kqSOX2zi
JibaTlXE1ud8sKiUB9hMlE+dcYm3J/G5FJqTFJv45kX2XeApni7J4/4M6ST0X/8z
bRqZ4HSDPeJ1JGZYxqET9VBSqtgjQqrFrhZ0LucGs2BQXNTrpqzeXE2MYOpDTUP9
kYIuVpg1/0Ys/4f8bbex2JbjXPi7km25I1nm8b1Tb8zSGDKNJ6/4Wd+Um/9JN6K8
gUkz1tp6kIsyd2XYlPoXEUxnoGkNP4M27AuhOQFDkdhfA0H1IMcgpCuy1KAc2Yhs
AqSIRzVHzssBo2iqYQTJ8YqTIIcCKHmSvozHROe8n3M0v6DbbyJgQ7q7OF7q8cW6
XxMJDQcwF3j5pPJSFuMM9SiTOW7sRgqGTq6yd7mzjTencvDFk6iujEiO2JGtCtBI
67osEWmFVSNK04BPcZxClWjdycsWs4fBxz9jvnplQ88wkRBvbM0WT73DAG3mnHh0
rNTFKXdjAyS8JIyVMZuOjdQG4hwAzdFpAc30aDIua2dh014V0DdsLK6aRHZdzl8J
x0fcULmCp6A814SliMqe
=qi3A
-----END PGP SIGNATURE-----