Re: [Haskell-cafe] Haddock changes pushed upstream

Thank you for your great work on haddock. We all appreciate it and look forward to your other works in progress. On Monday, January 13, 2014, Mateusz Kowalczyk wrote:

On 13/01/14 08:58, Sven Panne wrote:

...

2014/1/13 Mateusz Kowalczyk javascript:;>:

...

[...] * none of your documentation should get parse failures: any previously-failing documentation should now be displayed. [...]

Do we still get warnings or is there a command line flag to get errors back? I definitely don't want to browse through dozens of HTML pages to check if they look OK. For developing purposes I want as many errors I can get. (well, almost ;-) _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org javascript:; http://www.haskell.org/mailman/listinfo/haskell-cafe

No there is no way to get warnings or errors because it no longer makes sense to do so. The reason for failures in the past was due to Haddock's shortcomings rather than user failures: if your docs failed to parse, you probably tried escaping something where it didn't expect it &c. Ideally, it should have never had parse failures in the past but the parser had many short-comings. It's very hard to give warnings because we can't tell what the user actually wanted to do, only whether they have input valid markup or not. The only change is that now all markup should check out as valid.

If your docs look OK now, they will almost certainly look OK with the new version. If they are broken now, they might look terrible in the new version BUT if they are broken now, it's very easy to tell as you'll be getting parse failures.

I suggest that if you have any broken documentation right now, go and fix it. If you don't, great, you should be set. Note that even the old/current version of Haddock would never present you with any warnings: it would either error or not.

I did start to write a tool which would look at your existing documentation and try to point out any changes between the versions that might affect you but I did not have the time to finish it and it would be very naive even if I did. You can find it at [1] but it does close to nothing.

All in all you should be safe. The new markup rules are a lot more intuitive than the old ones and we have not changed anything that would greatly change existing, well-formed documentation. I don't think there is any documentation that will start to look worse except for few edge cases, such as people relying on Haddock not being able to nest markup to put in some other markup symbols verbatim into their text. You can now nest markup so that might end up looking slightly differently. Nothing major.

John MacFarlane suggested that I create a sort of dingus which would allow people to input some Haddock markup and be able to see the output from various versions. I think it'd be a useful tool not only for migration but for daily use. I did not have the time to start it but it's certainly in my plans. I'm starting to sit my mid-terms from tomorrow until the end of the month but I might be able to code something up after that. If someone is interested in doing this themselves, let me know so we don't duplicate efforts.

[1]: http://hackage.haskell.org/package/doccheck

-- Mateusz K. _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org javascript:; http://www.haskell.org/mailman/listinfo/haskell-cafe