[Haskell-cafe] Haddock changes pushed upstream

Carter Schonwald carter.schonwald at gmail.com
Mon Jan 13 16:57:41 UTC 2014

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 <fuuzetsu at fuuzetsu.co.uk <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 at 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 at haskell.org <javascript:;>
> http://www.haskell.org/mailman/listinfo/haskell-cafe
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20140113/48d04832/attachment.html>

More information about the Haskell-Cafe mailing list