Post-GHC 9.6.7, links between GHC boot packages fail in Haddock documentation

[mpilgrem]

Context:

• Stackage haddock core libs source links broken stackage#7818

On Windows, GHC 9.6.7 provides HTML files for Haddock documentation of GHC boot packages in folders like:

• ... \ghc-9.6.7\doc\html\libraries\base-4.18.3.0

Subsequently, GHC provides those files in folders like (e.g. GHC 9.10.3):

• ...\ghc-9.10.3\doc\html\libraries\base-4.20.2.0-39f9

Stack is unware of this change and in .stack-work\install\ ... \doc continues to have folders named after GHC boot package name-version (not id/key).

This situation results in duff links between GHC boot packages in Haddock documentation.

[mpilgrem]

What is Stack currently doing? I look at a plain vanilla stack new testGHC9103 with snapshot: ghc-9.10.3. There seem to be three potentially important steps (reformatted):

The first uses Cabal's haddock command:

Run process within ...\testGHC9103\: 
  D:\sr\setup-exe-cache\x86_64-windows\Cabal-simple_O_vy6YIf_3.12.1.0_ghc-9.10.3.exe 
  --verbose=1 
  --builddir=.stack-work\dist\1a191874 
  haddock 
  --html 
  --hoogle 
  --html-location=../$pkg-$version/ 
  --haddock-option=--hyperlinked-source 
  --haddock-option=--quickjump

The --html-location option specifies a template for the location of HTML documentation for prerequisite packages. The substitutions ($pkg, $version) are applied to the template to obtain a location for each package.

I can't see a way to specify a different template for GHC boot package to all other packages. Further, Cabal appears to offer no substition for a package's id or key field. Consequently, I cannot currently see how GHC's post-GHC 9.6.7 schema can be integrated with that used by all other packages.

and

The second uses Cabal's copy command:

Run process within ...\testGHC9103\: 
  D:\sr\setup-exe-cache\x86_64-windows\Cabal-simple_O_vy6YIf_3.12.1.0_ghc-9.10.3.exe 
  --verbose=1 
  --builddir=.stack-work\dist\1a191874 
  copy 
  lib:testGHC9103 
  exe:testGHC9103-exe

The third uses the haddock executable:

Run process within ...\testGHC9103\.stack-work\install\7a8a6b17\doc\all\:
  D:\sr\programs\x86_64-windows\ghc-9.10.3\bin\haddock-ghc-9.10.3.exe 
  --optghc=-package-db=D:\sr\snapshots\02ded40e\pkgdb 
  --optghc=-package-db=...\testGHC9103\.stack-work\install\7a8a6b17\pkgdb 
  --gen-contents 
  --gen-index 
  -i ..\ghc-bignum-1.3-cba1,D:\sr\programs\x86_64-windows\ghc-9.10.3\lib/../doc/html/libraries/ghc-bignum-1.3-cba1/ghc-bignum.haddock 
  -i ..\ghc-internal-9.1003.0-57e0,D:\sr\programs\x86_64-windows\ghc-9.10.3\lib/../doc/html/libraries/ghc-internal-9.1003.0-57e0/ghc-internal.haddock 
  -i ..\testGHC9103-0.1.0.0,D:\Users\mike\Code\Haskell\testGHC9103\.stack-work\install\7a8a6b17\doc\testGHC9103-0.1.0.0\testGHC9103.haddock 
  -i ..\ghc-prim-0.12.0-fb7e,D:\sr\programs\x86_64-windows\ghc-9.10.3\lib/../doc/html/libraries/ghc-prim-0.12.0-fb7e/ghc-prim.haddock 
  -i ..\base-4.20.2.0-39f9,D:\sr\programs\x86_64-windows\ghc-9.10.3\lib/../doc/html/libraries/base-4.20.2.0-39f9/base.haddock

Each of the -i <docpath>,<file> tells Haddock that an interface file is located at <file> and the documentation for the modules listed in the interface is located at <docpath>.