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

[Alexander Kjeldaas]

+1 for concistency.

Also, consider interop with non-haskell environments.  For example showing
the documentation of a function in emacs, eclipse, on github, and from a
javascript library.

All of these can be engineered around, and tooling can be provided.

But let me give an example: the other week I was looking for a command-line
tool to extract javadoc to display as contextual information in emacs.
There is no such tool.  Javadoc is "java only".  For me, if I could not
hack it up in an hour, it was too much work.  The solution was rather to
craft a specific google search, use "I'm feeling lucky", and extract the
subsection containing the documentation for the function.

Often the most useful format for documentation is contextual help in an
IDE/editor, so don't forget that use-case.

Alexander



On Sat, Apr 6, 2013 at 1:04 AM, John MacFarlane <jgm at berkeley.edu> wrote:

> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20130406/7072cf7a/attachment.htm>