[Haskell-cafe] Haddock changes pushed upstream

[Mateusz Kowalczyk]

On 13/01/14 08:58, Sven Panne wrote:
> 2014/1/13 Mateusz Kowalczyk <fuuzetsu at fuuzetsu.co.uk>:
>> [...] * 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
> 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.