[Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock

[Malcolm Wallace]

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?

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.

Regards,
    Malcolm

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