On Tue, Sep 16, 2014 at 2:36 AM, Mateusz Kowalczyk
On 09/15/2014 09:11 PM, Michael Snoyman wrote:
I've had cases where some code I wanted to put in an example could not be expressed in haddock due to escaping rules.
The parser has been improved and the escaping rules have been made saner. You shouldn't have real problems since 2.14 release which came out along with GHC 7.8.1. If you have problems with escaping then I'd like to hear about it on the issue tracker rather than stumbling upon complaints on café.
I ran into these issues over four years ago, discussed them at the time, and the general consensus I got at the time was that these issues weren't going to be resolved, so I didn't follow up. I've seen nothing in recent release announcements to imply otherwise. To test this out, I put together a simple demonstration of a Hamlet synopsis in Markdown[1], and then converted it via Pandoc to Haddock[2]. I copied that Haddock content into a cabal file's description, then indented it, ran cabal haddock, and got: cabal: hamlet.cabal:30: unexpected span: "!" For some reason, the trailing exclamation point is rejected by cabal. I tried removing the exclamation point, and it *did* generate content. However, all of the content was on the same line, because I needed to add periods between each block to deal with cabal's description parsing. After adding those periods, things *mostly* worked, except that my first code sample came out as: <p>Hi, my name is # Notice how the {name} portion has been stripped away. So I see a number of ways that this current situation for writing synopses is inferior: 1. Far more people are comfortable writing Markdown than writing Haddock, even those of us who write a lot of Haddock. Tooling support for editing Markdown is also superior. 2. Having the synopsis in a separate file means that it's easy to give a link to the file on Github and get readable docs, which is *not* the case with linking to a cabal file. 3. I don't have to go through any preprocess step to convert from Markdown to Haddock if that's the way I want to edit. 4. Putting the synopsis in the cabal file means we have to deal with cabal rules *in addition to* Haddock rules, such as the periods between blocks and not having an exclamation point at the end of the line[3]. 5. On top of all that, Haddock still can't handle the documentation I want to write for Hamlet, to demonstrate #{variable} interpolation. So again, I really like the idea of doing the same thing for synopses as we have already for changelogs. Michael [1] http://lpaste.net/111103 [2] http://lpaste.net/111104 [3] For the record, I was completely unaware of this limitation, and stumbled upon it by accident when putting together this example.
I think just about the only thing nowadays that might surprise people is that tokens stretch over newlines but this is by design, especially considering one can embed code.
I would much rather be able to write a synopsis in markdown, or asciidoc, or HTML, rather than haddock markup.
As I mention on the other e-mail, you can now use pandoc to achieve this. If people really care then it should not be difficult to co-ordinate with cabal + Hackage and make it parse your favourite format and splice it into synopsis.
I'd quite like the complaints about the existing Haddock markup, the rules are pretty damn close to what Markdown uses.
-- Mateusz K. _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe