haddock Links are misparsed when at beginning of line

Place the following snippet in a cabal file and run cabal new-haddock:

Description:         Bla
                     [link](http://example.com)

Result:

Removing the newline fixes the issue.

A link at the beginning of the very first line also parses fine.

Mar 13 '18 00:03 sjakobi

IIRC the reason for this was the syntactical overlap with the definition lists syntax, and the last time I brought this up w/ @alexbiehl he seemed positive we could tweak the parser to make it prefer the markdown link production here.

Mar 13 '18 13:03 hvr

Simon, you might want to give it a try?

Mar 13 '18 13:03 alexbiehl

Sounds like a good exercise given that I don't know much about parsing.

Can you give me some pointers where to start?

Mar 13 '18 14:03 sjakobi

All the stuff related to parsing is located in Documentation.Haddock.Parser in haddock-library. I think the description field from cabal files is parsed with parseParas. You will soon reach the paragraph parser which tries many parsers one-by-one to parse the many forms of paragraphs.

Hope this helps finding your way through the mess. Feel free to ask any questions here.

Mar 13 '18 15:03 alexbiehl

I haven't looked at the parser yet, but I've tried to set up a test case and I'm already stuck. ;)

I have added this file as html-test/src/Bug774.htm:

{-|
Bla
[link](http://example.com)

[def]: foo
-}

module Bug774 where

I then ran the testsuite and copied the resulting html file from html-test/out to html-test/ref.

When I run the testsuite again I get this error:

Diff for file "Bug774.html":
6,7c6,7
<     ><link href="#" rel="stylesheet" type="text/css" title="Ocean"
<      /><link rel="stylesheet" type="text/css" href="#"
---
>     ><link href="ocean.css" rel="stylesheet" type="text/css" title="Ocean"
>      /><link rel="stylesheet" type="text/css" href="quick-jump.css"
17c17
< 	><a href="#"
---
> 	><a href="index.html"
21c21
< 	><a href="#"
---
> 	><a href="doc-index.html"
60c60,64
<     ></div
---
>     ><p
>       >Produced by <a href="http://www.haskell.org/haddock/"
> 	>Haddock</a
> 	> version 2.19.0.1</p
>       ></div

But when I now diff the two files they are identical! Am I misunderstanding the setup of the testsuite?

Mar 14 '18 10:03 sjakobi

Simon, you should opt for the fixtures in haddock-library for your use case. It is a lot simpler and I think you have better insight into the parsed structure there.

For the html-test: Hyperrefs in haddock generation may include host dependent pathes. html-test makes sure to strip hyperrefs before comparing. Manually copying a test result into the ref folder doesn't work unless you strip the links yourself.

As this is a common problem html-test has the -a flag which "accepts" test inputs and generates the corresponding file in ref.

Mar 14 '18 10:03 alexbiehl

Thanks, I'll try again with the fixtures.

Also, that's good info about html-test. Do you already have something like a developer guide where you could record similar info?

Mar 14 '18 10:03 sjakobi

Do you already have something like a developer guide where you could record similar info?

No, feel free to add something to the README.md. I will be happy to accept those patches.

Mar 14 '18 11:03 alexbiehl

I can't new-test haskell-library with GHC-8.4.1 because tree-diff isn't compatible yet. I'm going with GHC-8.2.2 for now.

new-configure --enable-tests for the entire project fails too but firstly for reasons in haddock-api.

Is ghc-8.4 the right branch to develop from?

Mar 14 '18 11:03 sjakobi

Simon, you can try these (with ghc-8.4.1)

$ cabal new-build --enable-tests --allow-newer
$ cabal new-test fixtures --allow-newer

Mar 14 '18 11:03 alexbiehl

Good call, @alexbiehl! :)

Mar 14 '18 11:03 sjakobi

@alexbiehl Since this issue persists until today, i would like to add a hint to the docs as a "quickfix" until this issue is resolved. See #1444

Dec 14 '21 16:12 malteneuss