<div dir="ltr"><div><div>+1 for concistency.<br><br></div>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.<br>
<br>All of these can be engineered around, and tooling can be provided.<br><br>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.<br>
<br></div>Often the most useful format for documentation is contextual help in an IDE/editor, so don't forget that use-case.<br><div><br>Alexander<br><br></div></div><div class="gmail_extra"><br><br><div class="gmail_quote">
On Sat, Apr 6, 2013 at 1:04 AM, John MacFarlane <span dir="ltr"><<a href="mailto:jgm@berkeley.edu" target="_blank">jgm@berkeley.edu</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
I like markdown and use it all the time. While I acknowledge the<br>
problems that have been pointed out, markdown has the advantage of being<br>
easily readable "as it is" in the source document, and not looking like<br>
markup.<br>
<br>
But I do want to point out one problem with markdown as a format for<br>
documentation in Haskell files. Consider:<br>
<br>
----------------------------------------------------<br>
module MyModule<br>
{-<br>
# Introduction<br>
<br>
This is my module<br>
-}<br>
where<br>
import System.Environment<br>
<br>
main = getArgs >>= print<br>
----------------------------------------------------<br>
<br>
Now try to compile with -cpp, and you'll get an error because of the '#'<br>
in column 1. '#' in column 1 is common in markdown (and even<br>
indispensible for level 3+ headers).<br>
<br>
One could work around this by disallowing level 3+ headers, by allowing<br>
the headers to be indented, or by introducing new setext-like syntax for<br>
level 3+ headers, but it is a problem for the idea of using a markdown<br>
SUPERset.<br>
<br>
John<br>
<br>
+++ <a href="mailto:dag.odenhall@gmail.com">dag.odenhall@gmail.com</a> [Apr 05 13 21:59 ]:<br>
<div class="im">> I forgot the mention the craziness with the *significant trailing<br>
> whitespace*.<br>
><br>
</div><div><div class="h5">> On Fri, Apr 5, 2013 at 9:49 PM, [1]<a href="mailto:dag.odenhall@gmail.com">dag.odenhall@gmail.com</a><br>
> <[2]<a href="mailto:dag.odenhall@gmail.com">dag.odenhall@gmail.com</a>> wrote:<br>
><br>
> Personally I think Markdown sucks, although perhaps less than Haddock<br>
> markup.<br>
> Still:<br>
> * No document meta data<br>
> * No code block meta data like language for syntax highlighting<br>
> * No tables<br>
> * No footnotes<br>
> * HTML fallback is insecure<br>
> * Confusing syntax (is it []() or ()[] for links?)<br>
> * Syntax that gets in the way (maybe I don't want *stars* emphasized)<br>
> * Above point leads to non-standard dialects like "GitHub Markdown"<br>
> (no, GitHub doesn't use markdown)<br>
> * Not extensible, leading to even more non-standard hacks and<br>
> work-arounds (GitHub Markdown, Pandoc Markdown, other Markdown<br>
> libraries have their own incompatible extensions)<br>
> * Not well suited for web input (e.g. four-space indentation for code<br>
> blocks), although not that important for Haddock<br>
> An important thing to note here is that no, Markdown has *not* won<br>
> because no one is actually using *Markdown*. They're using their own,<br>
> custom and incompatible dialects.<br>
> Only two of the above points apply to reStructuredText (web input and<br>
> syntax getting in the way), and those particular points don't apply to<br>
> Creole. Therefore I tend to advocate Creole for web applications and<br>
> reStructuredText for documents.<br>
> On Thu, Apr 4, 2013 at 6:49 PM, Johan Tibell<br>
</div></div><div class="im">> <[3]<a href="mailto:johan.tibell@gmail.com">johan.tibell@gmail.com</a>> wrote:<br>
><br>
> Hi all,<br>
> Haddock's current markup language leaves something to be desired<br>
> once<br>
> you want to write more serious documentation (e.g. several<br>
> paragraphs<br>
> of introductory text at the top of the module doc). Several features<br>
> are lacking (bold text, links that render as text instead of URLs,<br>
> inline HTML).<br>
> I suggest that we implement an alternative haddock syntax that's a<br>
> superset of Markdown. It's a superset in the sense that we still<br>
> want<br>
> to support linkifying Haskell identifiers, etc. Modules that want to<br>
> use the new syntax (which will probably be incompatible with the<br>
> current syntax) can set:<br>
> {-# HADDOCK Markdown #-}<br>
> on top of the source file.<br>
</div>> Ticket: [4]<a href="http://trac.haskell.org/haddock/ticket/244" target="_blank">http://trac.haskell.org/haddock/ticket/244</a><br>
<div class="im">> -- Johan<br>
> _______________________________________________<br>
> Haskell-Cafe mailing list<br>
</div>> [5]<a href="mailto:Haskell-Cafe@haskell.org">Haskell-Cafe@haskell.org</a><br>
> [6]<a href="http://www.haskell.org/mailman/listinfo/haskell-cafe" target="_blank">http://www.haskell.org/mailman/listinfo/haskell-cafe</a><br>
><br>
> References<br>
><br>
> 1. mailto:<a href="mailto:dag.odenhall@gmail.com">dag.odenhall@gmail.com</a><br>
> 2. mailto:<a href="mailto:dag.odenhall@gmail.com">dag.odenhall@gmail.com</a><br>
> 3. mailto:<a href="mailto:johan.tibell@gmail.com">johan.tibell@gmail.com</a><br>
> 4. <a href="http://trac.haskell.org/haddock/ticket/244" target="_blank">http://trac.haskell.org/haddock/ticket/244</a><br>
> 5. mailto:<a href="mailto:Haskell-Cafe@haskell.org">Haskell-Cafe@haskell.org</a><br>
> 6. <a href="http://www.haskell.org/mailman/listinfo/haskell-cafe" target="_blank">http://www.haskell.org/mailman/listinfo/haskell-cafe</a><br>
<div class="HOEnZb"><div class="h5"><br>
> _______________________________________________<br>
> Haskell-Cafe mailing list<br>
> <a href="mailto:Haskell-Cafe@haskell.org">Haskell-Cafe@haskell.org</a><br>
> <a href="http://www.haskell.org/mailman/listinfo/haskell-cafe" target="_blank">http://www.haskell.org/mailman/listinfo/haskell-cafe</a><br>
<br>
<br>
_______________________________________________<br>
Haskell-Cafe mailing list<br>
<a href="mailto:Haskell-Cafe@haskell.org">Haskell-Cafe@haskell.org</a><br>
<a href="http://www.haskell.org/mailman/listinfo/haskell-cafe" target="_blank">http://www.haskell.org/mailman/listinfo/haskell-cafe</a><br>
</div></div></blockquote></div><br></div>