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

On 27/01/14 04:59, Evan Laforge wrote:

On Sun, Jan 12, 2014 at 5:37 PM, Mateusz Kowalczyk wrote:

...

* Bold markup added. The syntax is two underscores around what you want bold. Note, we still do not support multi-line markup. It's possible but it's a design choice not to support it.

This is all great, but I have a concern about this one. Do we really need more than one kind of emphasis?

Actually, mostly what I don't like is the / markup, because slashes are common, e.g. URLs and paths, and it's a pain to escape them all the time. Messed up formatting due to forgetting a backslash is very common in my docs, and I've even seen it in GHC docs as well.

This is an existing markup and we won't change it because every piece of documentation using it will break. I have seen plenty of documentation with ugly markup because someone forgot to escape something but it is unavoidable. I agree that ‘/’ might not be the best character but it's as good as any other for this purpose. If it was something else, people would complain about that instead.

I would prefer to swap /s for *s because *s seem less common, but of course that would break stuff. And I'm sure there are people out there who like using /s for emphasis, so we don't need to repaint that bikeshed. But at least we can avoid adding even more special characters you need to remember to escape.

If it was ‘*’ then we'd have to remember that instead (and ‘*’ is also a very common character). The reason I picked two underscores for bold is precisely because it's not that common.

And bold emphasis seems like it's redundant with italics emphasis.

You're free to not use it. A lot of people wanted bold (including myself). It looks different, it's a different kind of emphasis, why not include it? I don't understand your point of view on this. Are you not against different kinds of lists? I mean, all of them enumerate things so why bother with 3 different kinds, right? It is also now a bit late for this post, documentation and tests have been written and it's all done and dusted, just waiting for the imminent 7.8 release. There was plenty of time for input. If you have a pressing reason why bold shouldn't be included, file a Haddock ticket. -- Mateusz K.

On 27/01/14 05:24, Evan Laforge wrote:

On Sun, Jan 26, 2014 at 9:10 PM, Mateusz Kowalczyk wrote:

...

You're free to not use it. A lot of people wanted bold (including myself). It looks different, it's a different kind of emphasis, why not include it? I don't understand your point of view on this. Are you not against different kinds of lists? I mean, all of them enumerate things so why bother with 3 different kinds, right?

Well, every bit of markup added is permanent, and it's one more thing to remember to escape. Redundant kinds of lists aren't so bad because they're not taking up a whole character, but yes if it were just me I would only have one kind of list. Anyway, I missed that it's double underscore, not *s. In that case, it won't be a burden so I'm not worried. Concern withdrawn!

Oh, great. You actually reminded me the real reason why ‘*’ is not bold: we already use ‘*’ for unordered lists and it'd be impossible to tell which one you want at the beginning of a paragraph. -- Mateusz K.