I agree with Chris that it would be better to have a standard syntax for Haskell documentation. Especially if the alternative is ten different markup languages. (Remember, all of these need to be supported in haddock, which is a basic piece of infrastructure.) Here's a thought. Instead of adding support for markdown, why not enhance the existing haddock markup, making it more expressive, so that it could encode the same range of structural features as markdown? If this were done, we could add a haddock writer to pandoc. There is already a haddock reader in the development version, but a writer is difficult because haddock is so much less expressive than other formats. For example, unless I'm mistaken, it doesn't allow list items with multiple paragraphs or other block elements, or nested lists, or images, or blockquotes. With a pandoc reader and writer for haddock, it would be easy to write your documentation in any format you choose (several variants of markdown, reST, textile, LaTeX, HTML, mediawiki) and produce equivalent haddock markup to paste into the source file. It would also be easy to convert the documentation in your source file to any of the formats supported by pandoc. So, you could generate a man page from your haddock markup, or a web page or blog entry, or a LaTeX document. It seems to me that this would provide most of the advantages people who want a markdown extension for haddock are looking for. But it would not require taking sides in markdown/reST/asciidoc/creole wars, and it would not lead to the fragmentation of documentation formats in Haskell source code. If the extensions to haddock markup were done carefully, it wouldn't even require a special PRAGMA, since all existing markup would have the same interpretation in the extended markup. John +++ Chris Smith [Apr 27 13 12:05 ]:
I don't agree with this at all. Far more important than which convention gets chosen is that Haskell code can be read and written without learning many dialects of Haddock syntax. I see an API for pluggable haddock syntax as more of a liability than a benefit. Better to just stick to what we have than fragment into more islands.
I do think that changing Haddock syntax to include common core pieces of Markdown could be a positive change... but not if it spawns a battle of fragmented documentation syntax that lasts a decade. On Apr 27, 2013 11:08 AM, "Bryan O'Sullivan" <[3]bos@serpentine.com> wrote:
On Sat, Apr 27, 2013 at 2:23 AM, Alistair Bayley <[4]alistair@abayley.org> wrote:
How's about Creole? [5]http://wikicreole.org/ Found it via this: [6]http://www.wilfred.me.uk/blog/2012/07/30/why-markdown-is-not-my-favo urite-language/ If you go with Markdown, I vote for one of the Pandoc implementations, probably Pandoc (strict): [7]http://johnmacfarlane.net/babelmark2/ (at least then we're not creating yet another standard...)
Probably the best way to deal with this is by sidestepping it: make the support for alternative syntaxes as modular as possible, and choose two to start out with in order to get a reasonable shot at constructing a suitable API. I think it would be a shame to bikeshed on which specific syntaxes to support, when a lot of productive energy could more usefully go into actually getting the work done. Better to say "prefer a different markup language? code to this API, then submit a patch!"
_______________________________________________ Haskell-Cafe mailing list [8]Haskell-Cafe@haskell.org [9]http://www.haskell.org/mailman/listinfo/haskell-cafe
References
1. mailto:cdsmith@gmail.com 2. mailto:bos@serpentine.com 3. mailto:bos@serpentine.com 4. mailto:alistair@abayley.org 5. http://wikicreole.org/ 6. http://www.wilfred.me.uk/blog/2012/07/30/why-markdown-is-not-my-favourite-la... 7. http://johnmacfarlane.net/babelmark2/ 8. mailto:Haskell-Cafe@haskell.org 9. http://www.haskell.org/mailman/listinfo/haskell-cafe
_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe