+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 <j...@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.odenh...@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.odenh...@gmail.com > > <[2]dag.odenh...@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.tib...@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@haskell.org > > [6]http://www.haskell.org/mailman/listinfo/haskell-cafe > > > > References > > > > 1. mailto:dag.odenh...@gmail.com > > 2. mailto:dag.odenh...@gmail.com > > 3. mailto:johan.tib...@gmail.com > > 4. http://trac.haskell.org/haddock/ticket/244 > > 5. mailto:Haskell-Cafe@haskell.org > > 6. http://www.haskell.org/mailman/listinfo/haskell-cafe > > > _______________________________________________ > > Haskell-Cafe mailing list > > Haskell-Cafe@haskell.org > > http://www.haskell.org/mailman/listinfo/haskell-cafe > > > _______________________________________________ > Haskell-Cafe mailing list > Haskell-Cafe@haskell.org > http://www.haskell.org/mailman/listinfo/haskell-cafe >
_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe