[Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock
Roman Cheplyaka
roma at ro-che.info
Mon Apr 8 15:54:30 CEST 2013
* Ivan Lazar Miljenovic <ivan.miljenovic at gmail.com> [2013-04-08 10:18:32+1000]
> 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
This seems to be a different issue — about unlit, not cpp.
> > * 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