Revise haddock reader to fit new haddock markup

[jgm]

Haddock uses a new parser, so pandoc's parser, which is based on the old haddock, is out of date.

The haddock library is supposed to factor out and expose the parser, without a GHC dependency, which would enable us to use it directly.

[jgm]

See #1135 for relevant comments.

[Fuuzetsu]

It has been done but is not going into 2.14.x revisions shipping with GHC 7.8.x. When time comes, we will ship a separate package called haddock-library (name subject to change) which exposes a parser function of type String -> DocH a Identifier (a is irrelevant here) and Identifier just being (Char, String, Char). Currently the only dependencies are base, bytestring and deepseq.

Thinking about it though, I think we could just release haddock-library independently for people to use considering that's not tightly bound to GHC. I'll consider releasing it soon.

We don't offer anything for the writer as we don't have a use case for it.

[jgm]

It would be great if haddock-library could be released! I understand that this would only help with the reader.

[Fuuzetsu]

OK, I'll see whether I can release it today.

[Fuuzetsu]

See haddock-library on Hackage . Please let me know if it doesn't do something you'd expect. Tested with 7.6.3, 7.8.{1,2,soontobe3} and HEAD.

[jgm]

Great! I sent you a small pull request to let it build on 7.4.

+++ Mateusz Kowalczyk [Jun 18 14 00:12 ]:

See [1]haddock-library on Hackage . Please let me know if it doesn't do
something you'd expect. Tested with 7.6.3, 7.8.{1,2,soontobe3} and
HEAD.

—
Reply to this email directly or [2]view it on GitHub.

References

1. http://hackage.haskell.org/package/haddock-library
2. Revise haddock reader to fit new haddock markup #1346 (comment)

[jgm]

The newhaddock branch has a new improved haddock reader based
on haddock-library. I'm reluctant to merge this into master,
though, until haddock-library is modified to work with ghc 7.4
(see my pull request).

[jgm]

I've pushed a new haddock reader and writer to pandoc master.

[Fuuzetsu]

That's cool to hear.

[jgm]

By the way, I ran into a couple of oddities in haddock-library.
I was able to work around them, but I wonder whether they are
intentional.

On the input "one\n\ntwo", parseParas gives

DocAppend (DocParagraph (DocString "one")) (DocParagraph (DocString "two"))

But on the input "1. one\n\n two", it gives

DocOrderedList [DocParagraph (DocAppend (DocString "one")
(DocParagraph (DocString "two")))]

This is strange. I would have expected that the contents of the ordered
list item would be the same as the same content outside a list.
And I don't really understand why this is being represented as
a paragraph that contains some text and another paragraph, rather
than two paragraphs at the same level. Is that intentional?

Another quirk was that DocHeaders appear inside DocParagraphs. e.g.

DocParagraph (DocHeader (Header {headerLevel = 2, headerTitle =
DocString "Hi"}))

Is that intentional?

[Fuuzetsu]

Is that intentional?

Yes. Here is how it looks when we put it in a comment:

{-|
1. one

    two
-}

This falls into the rules for nesting in lists which is a new feature from 2.14.x onwards. It allows one to write things like

{-|
1. one

    1. sub one
-}

If in your example you don't indent ‘two’, you'd get what I think you're saying is the expected behaviour:

*Documentation.Haddock.Parser> parseParas "1. one\n\ntwo"             
DocAppend (DocOrderedList [DocParagraph (DocString "one")]) (DocParagraph (DocString "two"))

Another quirk was that DocHeaders appear inside DocParagraphs.…

I admit that I don't remember why it is but I speculate that it was to ensure proper rendering. It may very well be that this is not necessary, I will investigate.

It is possible that there may be some weird behaviour, please don't hesitate to report anything, I can only come up with so many tests.

[jgm]

I understand that this is an ordered list item with two paragraphs contained in the item. What I don't understand is why it is

DocOrderedList [DocParagraph (DocAppend (DocString "one")
(DocParagraph (DocString "two")))]

and not

DocOrderedList [DocAppend (DocParagraph (DocString "one"))
(DocParagraph (DocString "two")]

That is: shouldn't the contents of the list be a paragraph appended to a paragraph, rather than a paragraph that contains some text appended to another paragraph?

[Fuuzetsu]

OK, I see what you mean. We do this on purpose (unexported joinPara function) although I can't tell you why off the top of my head, I'll investigate today whether doing it the expected way affects our output.

[jgm]

If you do change how it works, please let me know so I can make corresponding changes in pandoc.

[Fuuzetsu]

I have found some time to investigate it and as it turns out, both the problems you pointed out were just my brainfarts. I have made changes so that DocHeader is no longer wrapped in DocParagraph and paragraph nesting inside lists is as you were expecting it to be to begin with.

Please see version 1.1.0, now on Hackage. In the future please make issues on haskell/haddock GitHub repository, thanks for spotting and reporting.

[jgm]

Excellent. That helps me simplify some crufty code.