-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On 27/04/13 22:18, John MacFarlane wrote: > 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 > > _______________________________________________ Haskell-Cafe > mailing list Haskell-Cafe@haskell.org > http://www.haskell.org/mailman/listinfo/haskell-cafe > I was under the impression that Markdown specifically was requested due to its high popularity, ease of writing and being very readable to a human. As you mention, currently Haddock is not expressive enough to have a writer and would need extending first.
The advantages of extending Haddock this way are obvious: people write the documentation in whatever they want and then use Pandoc to convert it to a format they want to distribute in. I'm unsure however whether such an extension is strictly a good thing: what's more readable in source: Haddock with even more stuff tacked on or Markdown with some already present Haddock constructs? There are a fair few complaints about how unwieldy Haddock currently is and I'm worried that extending it for the sake of (a really nice) ability of conversion between formats with Pandoc might make it even more unwieldy. Yes, you can write the docs in any of the billion formats Pandoc supports and then convert it but many people simply want to write docs right into their source files, right as they write actual code without reliance on external tools -- something Markdown would excel at if implemented. So in the end, it just comes down to to what the community _really_ wants: more expressive core Haddock with ability to convert between the formats or yet another Markdown flavour tacked onto Haddock as an extension. It should be noted that this would probably end up serving as a basis for the Pandoc module anyway so why duplicate the effort? Pandoc already handles Markdown, as Christopher Howard pointed out. Discussion on the topic will is most welcome. I am one of the students interested in this project and I have already written a draft proposal with the idea of implementing Markdown as an extension because that's what it seems the community wanted in previous threads and discussions. Is this _really_ what we want though? Personally, I think the benefits of extending Haddock itself and writing a writer module for Pandoc not only cover everything a new, Haskell specific Markdown could do but provide even greater flexibility. I'd also prefer to work on extending Haddock rather than just tacking an extension to it that might not get used because some people might dislike Markdown and would miss out on any new features. The SoC proposal deadlines are on 3rd of May so it'd be great to hear some opinions on this within the next 3 days or so, after which point I will adjust my proposal accordingly, cross my fingers and hope for the best ;) - -- Mateusz K. -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.19 (GNU/Linux) iQIcBAEBAgAGBQJRfFXcAAoJEM1mucMq2pqX8kkQAI+xRwMOVsq9T14bKLZ3Wiv7 citbn/hWDYSC8zpSnFIGW87On9/phBIhXaBA5F878mao0AAOMmN0S2ZfcTusaRjk zXm2Dfof6ZKa38xTTjcoBuNWvv7mNwY8592krRPKden2if+II+2bXEd8kqSOX2zi JibaTlXE1ud8sKiUB9hMlE+dcYm3J/G5FJqTFJv45kX2XeApni7J4/4M6ST0X/8z bRqZ4HSDPeJ1JGZYxqET9VBSqtgjQqrFrhZ0LucGs2BQXNTrpqzeXE2MYOpDTUP9 kYIuVpg1/0Ys/4f8bbex2JbjXPi7km25I1nm8b1Tb8zSGDKNJ6/4Wd+Um/9JN6K8 gUkz1tp6kIsyd2XYlPoXEUxnoGkNP4M27AuhOQFDkdhfA0H1IMcgpCuy1KAc2Yhs AqSIRzVHzssBo2iqYQTJ8YqTIIcCKHmSvozHROe8n3M0v6DbbyJgQ7q7OF7q8cW6 XxMJDQcwF3j5pPJSFuMM9SiTOW7sRgqGTq6yd7mzjTencvDFk6iujEiO2JGtCtBI 67osEWmFVSNK04BPcZxClWjdycsWs4fBxz9jvnplQ88wkRBvbM0WT73DAG3mnHh0 rNTFKXdjAyS8JIyVMZuOjdQG4hwAzdFpAc30aDIua2dh014V0DdsLK6aRHZdzl8J x0fcULmCp6A814SliMqe =qi3A -----END PGP SIGNATURE----- _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
