[Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock
Ivan Lazar Miljenovic
ivan.miljenovic at gmail.com
Mon Apr 8 02:18:32 CEST 2013
On 8 April 2013 07:12, Roman Cheplyaka <roma at ro-che.info> wrote:
> Looks like a bug in cpphs to me (CC'ing Malcolm). It should respect
> comments. E.g. GNU cpp strips C comments.
Not quite: http://hackage.haskell.org/trac/ghc/ticket/4836
>
> Roman
>
> * John MacFarlane <jgm at berkeley.edu> [2013-04-05 16:04:32-0700]
>> I like markdown and use it all the time. While I acknowledge the
>> problems that have been pointed out, markdown has the advantage of being
>> easily readable "as it is" in the source document, and not looking like
>> markup.
>>
>> But I do want to point out one problem with markdown as a format for
>> documentation in Haskell files. Consider:
>>
>> ----------------------------------------------------
>> module MyModule
>> {-
>> # Introduction
>>
>> This is my module
>> -}
>> where
>> import System.Environment
>>
>> main = getArgs >>= print
>> ----------------------------------------------------
>>
>> Now try to compile with -cpp, and you'll get an error because of the '#'
>> in column 1. '#' in column 1 is common in markdown (and even
>> indispensible for level 3+ headers).
>>
>> One could work around this by disallowing level 3+ headers, by allowing
>> the headers to be indented, or by introducing new setext-like syntax for
>> level 3+ headers, but it is a problem for the idea of using a markdown
>> SUPERset.
>>
>> John
>>
>> +++ dag.odenhall at gmail.com [Apr 05 13 21:59 ]:
>> > I forgot the mention the craziness with the *significant trailing
>> > whitespace*.
>> >
>> > On Fri, Apr 5, 2013 at 9:49 PM, [1]dag.odenhall at gmail.com
>> > <[2]dag.odenhall at gmail.com> wrote:
>> >
>> > Personally I think Markdown sucks, although perhaps less than Haddock
>> > markup.
>> > Still:
>> > * No document meta data
>> > * No code block meta data like language for syntax highlighting
>> > * No tables
>> > * No footnotes
>> > * HTML fallback is insecure
>> > * Confusing syntax (is it []() or ()[] for links?)
>> > * Syntax that gets in the way (maybe I don't want *stars* emphasized)
>> > * Above point leads to non-standard dialects like "GitHub Markdown"
>> > (no, GitHub doesn't use markdown)
>> > * Not extensible, leading to even more non-standard hacks and
>> > work-arounds (GitHub Markdown, Pandoc Markdown, other Markdown
>> > libraries have their own incompatible extensions)
>> > * Not well suited for web input (e.g. four-space indentation for code
>> > blocks), although not that important for Haddock
>> > An important thing to note here is that no, Markdown has *not* won
>> > because no one is actually using *Markdown*. They're using their own,
>> > custom and incompatible dialects.
>> > Only two of the above points apply to reStructuredText (web input and
>> > syntax getting in the way), and those particular points don't apply to
>> > Creole. Therefore I tend to advocate Creole for web applications and
>> > reStructuredText for documents.
>> > On Thu, Apr 4, 2013 at 6:49 PM, Johan Tibell
>> > <[3]johan.tibell at gmail.com> wrote:
>> >
>> > Hi all,
>> > Haddock's current markup language leaves something to be desired
>> > once
>> > you want to write more serious documentation (e.g. several
>> > paragraphs
>> > of introductory text at the top of the module doc). Several features
>> > are lacking (bold text, links that render as text instead of URLs,
>> > inline HTML).
>> > I suggest that we implement an alternative haddock syntax that's a
>> > superset of Markdown. It's a superset in the sense that we still
>> > want
>> > to support linkifying Haskell identifiers, etc. Modules that want to
>> > use the new syntax (which will probably be incompatible with the
>> > current syntax) can set:
>> > {-# HADDOCK Markdown #-}
>> > on top of the source file.
>> > Ticket: [4]http://trac.haskell.org/haddock/ticket/244
>> > -- Johan
>> > _______________________________________________
>> > Haskell-Cafe mailing list
>> > [5]Haskell-Cafe at haskell.org
>> > [6]http://www.haskell.org/mailman/listinfo/haskell-cafe
>> >
>> > References
>> >
>> > 1. mailto:dag.odenhall at gmail.com
>> > 2. mailto:dag.odenhall at gmail.com
>> > 3. mailto:johan.tibell at gmail.com
>> > 4. http://trac.haskell.org/haddock/ticket/244
>> > 5. mailto:Haskell-Cafe at haskell.org
>> > 6. 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
>>
>>
>> _______________________________________________
>> Haskell-Cafe mailing list
>> Haskell-Cafe at haskell.org
>> 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
--
Ivan Lazar Miljenovic
Ivan.Miljenovic at gmail.com
http://IvanMiljenovic.wordpress.com
More information about the Haskell-Cafe
mailing list