[Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock
Roman Cheplyaka
roma at ro-che.info
Mon Apr 8 15:52:53 CEST 2013
* Malcolm Wallace <malcolm.wallace at me.com> [2013-04-08 10:00:11+0100]
> And cpphs strips C comments too. :-)
>
> But seriously, John's use-case is the exact opposite of what you
> suggest. John wants to keep the # inside the comment block. You
> suggest to remove the comment-block altogether?
No, my point was that the preprocessor has to be aware of the language's
comments, and treat them accordingly. In this case, "accordingly"
probably means leave them intact.
> When I checked the example with cpphs, it turns out that the # line is
> retained, generating a warning but not an error. I expect Gnu cpp is
> the software that throws an error.
>
> In my opinion, it is perfectly valid to have intentional preprocessor
> directives inside Haskell comments.
Could you give an example where this is useful?
#ifs and #ifdefs can be moved outside of the comment most of the time.
And macro expansions inside the comments are rather exotic.
On the other hand, the liberty to write whatever one wants inside a
comment feels important to me.
> On 7 Apr 2013, at 22:12, Roman Cheplyaka wrote:
>
> > Looks like a bug in cpphs to me (CC'ing Malcolm). It should respect
> > comments. E.g. GNU cpp strips C comments.
> >
> > 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
More information about the Haskell-Cafe
mailing list