Skip to content
This repository was archived by the owner on Aug 3, 2024. It is now read-only.

Fix hyperlinks to external items and modules - #1482

Merged
Kleidukos merged 1 commit into
haskell:ghc-9.2from
lf-:fix-ext-hyperlinks
May 7, 2022
Merged

Kleidukos merged 1 commit into
haskell:ghc-9.2from
lf-:fix-ext-hyperlinks

Conversation

@lf-

@lf- lf- commented May 6, 2022

Copy link
Copy Markdown
Contributor

Fixes #1481.

There were two bugs in this:

  • We were assuming that we were always getting a relative path to the
    module in question, while Nix gives us file:// URLs sometimes. This
    change checks for those and stops prepending .. to them.
  • We were not linking to the file under the module. This seems
    to have been a regression introduced by Use .hie files for the Hyperlinker backend #977. That is, the URLs were
    going to something like
    file:///nix/store/3bwbsy0llxxn1pixx3ll02alln56ivxy-ghc-9.0.2-doc/share/doc/ghc/html/libraries/base-4.15.1.0/src
    which does not have the appropriate HTML file or fragment for the item
    in question at the end.

There is a remaining instance of the latter bug, but not in the
hyperlinker: the source links to items reexported from other modules are
also not including the correct file name. e.g. the reexport of Entity in
esqueleto, from persistent has a source link file:///nix/store/jwrrwxbkr2pcpf4kjgd3zyalf6jakxkz-persistent-2.13.3.5-doc/share/doc/persistent-2.13.3.5/html/src. This bug is probably somewhere around here: https://github.com/haskell/haddock/blob/ghc-9.2/haddock-api/src/Haddock/Backends/Xhtml/Layout.hs#L289-L293

NOTE: This needs to get tested with relative-path located modules. It seems
correct for Nix based on my testing.

Testing strategy:

nix-shell '<nixpkgs>' --pure -A haskell.packages.ghc922.aeson
mkdir /tmp/aesonbuild && cd /tmp/aesonbuild
export out=/tmp/aesonbuild/out
genericBuild

ln -sf $HOME/co/haddock/haddock-api/resources .
./Setup haddock --with-haddock=$HOME/path/to/haddock/exec --hyperlink-source

Fixes haskell#1481.

There were two bugs in this:
* We were assuming that we were always getting a relative path to the
  module in question, while Nix gives us file:// URLs sometimes. This
  change checks for those and stops prepending `..` to them.
* We were not linking to the file under the module. This seems
  to have been a regression introduced by haskell#977. That is, the URLs were
  going to something like
  file:///nix/store/3bwbsy0llxxn1pixx3ll02alln56ivxy-ghc-9.0.2-doc/share/doc/ghc/html/libraries/base-4.15.1.0/src
  which does not have the appropriate HTML file or fragment for the item
  in question at the end.

There is a remaining instance of the latter bug, but not in the
hyperlinker: the source links to items reexported from other modules are
also not including the correct file name. e.g. the reexport of Entity in
esqueleto, from persistent.

NOTE: This needs to get tested with relative-path located modules. It seems
correct for Nix based on my testing.

Testing strategy:

```
nix-shell '<nixpkgs>' --pure -A haskell.packages.ghc922.aeson
mkdir /tmp/aesonbuild && cd /tmp/aesonbuild
export out=/tmp/aesonbuild/out
genericBuild

ln -sf $HOME/co/haddock/haddock-api/resources .
./Setup haddock --with-haddock=$HOME/path/to/haddock/exec --hyperlink-source
```
@Kleidukos
Kleidukos self-requested a review May 6, 2022 21:15
@Kleidukos
Kleidukos merged commit ab53ccf into haskell:ghc-9.2 May 7, 2022
lf- added a commit to lf-/nixpkgs that referenced this pull request Jun 16, 2022
This was disabled basically by accident before.

The links are jacked, but that was is true for every package; it is not
unique to this PR. I fixed it upstream here:
haskell/haddock#1482
but it's not in any release distributions yet I don't think.

Fixes NixOS#171841
@lf-

lf- commented Jun 20, 2022

Copy link
Copy Markdown
Contributor Author

@Kleidukos does anything need to be done on my end to get this forward-ported to ghc-9.4?

@Kleidukos

Kleidukos commented Jun 21, 2022 •

Copy link
Copy Markdown
Member

I'm on it. :)

@Kleidukos

Copy link
Copy Markdown
Member

@lf- There will be no problem for ghc-9.4.

@sternenseemann

Copy link
Copy Markdown

@Kleidukos This doesn't seem to be in GHC 9.4.1-rc1, since the patch we add in nixpkgs still applies?! Is that accurate or is something else wrong?

@Kleidukos

Copy link
Copy Markdown
Member

@sternenseemann From my interactions with the GHC release team, there will be a release of Haddock bundled with GHC 9.4.1

@Kleidukos

Copy link
Copy Markdown
Member

(note that this probably will also mark the move of Haddock to the GHC tree)

@sternenseemann

Copy link
Copy Markdown

Maybe it's wise to follow up? Currently utils/haddock is a submodule pointing to 2368e93 on GHC's ghc-9.4 branch and arguably haddock is a pretty big thing to change after the first release candidate has been published…

duog pushed a commit to duog/haddock that referenced this pull request Jul 29, 2022
Fixes haskell#1481.

There were two bugs in this:
* We were assuming that we were always getting a relative path to the
  module in question, while Nix gives us file:// URLs sometimes. This
  change checks for those and stops prepending `..` to them.
* We were not linking to the file under the module. This seems
  to have been a regression introduced by haskell#977. That is, the URLs were
  going to something like
  file:///nix/store/3bwbsy0llxxn1pixx3ll02alln56ivxy-ghc-9.0.2-doc/share/doc/ghc/html/libraries/base-4.15.1.0/src
  which does not have the appropriate HTML file or fragment for the item
  in question at the end.

There is a remaining instance of the latter bug, but not in the
hyperlinker: the source links to items reexported from other modules are
also not including the correct file name. e.g. the reexport of Entity in
esqueleto, from persistent.

NOTE: This needs to get tested with relative-path located modules. It seems
correct for Nix based on my testing.

Testing strategy:

```
nix-shell '<nixpkgs>' --pure -A haskell.packages.ghc922.aeson
mkdir /tmp/aesonbuild && cd /tmp/aesonbuild
export out=/tmp/aesonbuild/out
genericBuild

ln -sf $HOME/co/haddock/haddock-api/resources .
./Setup haddock --with-haddock=$HOME/path/to/haddock/exec --hyperlink-source
```

(cherry picked from commit ab53ccf)
Kleidukos added a commit that referenced this pull request Jul 29, 2022
Backport 9-4: Fix hyperlinks to external items and modules (#1482)
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Hyperlinked sources as generated by the Nix toolchain prepend ../ in absolute paths

3 participants