Inconsistency in html file naming: Data.Bifoldable.html vs. Data-Bifoldable.html

[jhrcek]

There is an inconsistency in how html filenames are generated for haddock vs. source documentation.

Compare

1. haddock: https://hackage.haskell.org/package/base-4.16.0.0/docs/src/Data.Bifoldable.html -> source files under "docs/src" folder contain dot as module separator (Data - dot - Bifoldable)
2. source html: https://hackage.haskell.org/package/base-4.16.0.0/docs/Data-Bifoldable.html -> haddock files under "docs" contain hyphen as module separator (Data - hyphen - Bifoldable).

This inconsistency makes it hard to implement "open documentation on hackage" in haskell-language-server, as described in https://github.com/haskell/haskell-language-server/issues/2508

This inconsistency started appearing in relatively recent version of haddock (2.26?). It seems that older versions used hyphens in

Could you please let me know if this is by design, or unintended consequence of some refactoring? Or potentially track down in which commit this change happened?

[sjakobi]

https://gitlab.haskell.org/ghc/ghc/-/issues/20698 and https://gitlab.haskell.org/ghc/ghc/-/issues/20699 seem somewhat related.

[stevehartdata]

I can't tell you whether this change was by design or not, but here is some information that I've been able to gather that may be helpful.

The format of hyperlinked source URLs is actually controlled partially by Haddock and partially by Cabal.

On the Cabal side

• If Haddock's version is >= 2.17 and the user passed Cabal the --haddock-hyperlinked-source option, then Cabal passes Haddock the --hyperlinked-source option.
• If the user passed Cabal the --haddock-hyperlinked-source option, then Cabal also passes Haddock --source-module=src/%{MODULE/./-}.html, --source-entity=src/%{MODULE/./-}.html#%{NAME}, and (if Haddock >= 2.14) --source-entity-line=src/%{MODULE/./-}.html#line-%{LINE}. These arguments control the format of the links that Haddock produces, and the defaults convert dots to dashes.

On the Haddock side

If the --hyperlinked-source option is provided, then the --source-module= and related arguments are ignored, and no conversion of dots to dashes happens. The URL uses the module names as-is. If the --hyperlinked-source argument is not provided, then Haddock uses the format specified by the --source-module= argument.

Other notes

• You can get the old URL format back by passing the old Haddock options through cabal without including the --haddock-hyperlinked-source option:

  cabal haddock --haddock-options="--source-module='src/%{MODULE/./-}.html' --source-entity='src/%{MODULE/./-}.html#%{NAME}' --source-entity-line='src/%{MODULE/./=}.html#line-%{LINE}'" taget
  

  However, Cabal will not produce the source code files if Haddock's version is >= 2.17, so you would have to produce them yourself.

• The changes on the Haddock side were implemented as part of a 2015 Google SoC project (see #410). Unfortunately, the original spec is no longer available (it was on the old Trac site), and the commit messages don't seem to indicate whether the change from dashes to dots was intentional or not. Perhaps @panhania would remember whether the change was intentional.

• ab070206d67748232995a262b533957a5a7b9315 is where Haddock began ignoring its --source-module= argument in the presence of --hyperlinked-source, and it looks like this change was first released in Haddock 2.17. Cabal e96bf2b is where Cabal started using Haddock's hyperlinker instead of HsColour.

• It seems like you might have a hard time determining whether to use dots or dashes when generating URLs without knowing which version of cabal and Haddock were used to build the package documentation.

[panhania]

The changes on the Haddock side were implemented as part of a 2015 Google SoC project (see Source hyperlinker #410). Unfortunately, the original spec is no longer available (it was on the old Trac site), and the commit messages don't seem to indicate whether the change from dashes to dots was intentional or not. Perhaps @panhania would remember whether the change was intentional.

Unfortunately, I don't remember why it was done like this—I doubt that there was a very good reason for the change. Most probably it was just simpler to code or I found it more aesthetically pleasing than the hyphen notation as it directly corresponds to Haskell's module path syntax.