[Haskell-cafe] Haddock changes pushed upstream

[Carter Schonwald]

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>