Returning local documentation urls does not appear to work?

[mdorman]

So I am very happy to be shown wrong on this, but whether I use the CLI interface or the web interface, I always seem to get URLs that direct me to the hackage copies of the documentation.

I assumed that this was because of something about how my copies of the docs were setup causing a problem, but when I went looking through the source to try and figure out what I needed to fix, it appeared to me that maybe this should be expected, even if it's not desired.

I base this on the observation that the various read* functions in Generate more or less uniformly do yield (name, hackagePackageURL name, src), where hackagePackageURL is, unsurprisingly, creating a URL that points to hackage.

If you then trace back from showURL (which appears to be the leaf in the callstack that should handle hoogle server --local), you find that it's only possibly stripping file:/// prefixes, which isn't going to affect anything that's already pointing to hackage.

Now there is, I have to admit, a giant disconnect in what I've examined---between that yield, and the showResults call that is presenting the results, maybe that hackage URL is getting stripped back out---but I'm guessing not.

[ndmitchell]

If you do hoogle generate --local, which uses ghc-pkg, it does (or at least should) pick up the ghc-pkg registration of where you put the docs. If you do --local=dir it has no idea where the docs are, so defaults to Hackage. That isn't particularly useful. There are two ways to get around it:

• If you rewrite all the .txt files so the line immediately before @package is @url ... then you can override the Hackage URL and point at something with file:// in it. I've done this trick several times.
• If we can figure out a better mechanism, I'll incorporate that into --local=dir. Should the docs be in the same directory? An extra parameter for where they live? There's a reasonable design space, and I've never hit on a sweet spot that works for everything.

[mdorman]

OK, thanks for the details. Darn, it's a shame I can't just see a path for invoking hoogle after ghc's environment has already been set up...but unfortunately that's just not possible, at least not given my knowledge of Nix.

It seems attractive to try to include the @url in the file (make it self-describing, basically), but I take it from they way you describe it that this isn't something we could coerce haddock into doing for us (by invoking it with some particular flag---at least I don't see one that is clearly that flag), but instead something we would have to do as post-processing.

That makes it less attractive, but definitely a straightforward option. Incidentally, does hoogle actually ever refer to the .txt files after it's built the database, or does everything get put in the .hoo file? If so, then at least the modified files could be effectively disposable, and only exist for the duration of database creation.

Hmmmm. I dunno, all things considered, it seems to me that the default is to have the .txt file in the same directory as everything else, and it doesn't seem outrageous to me to reward using the default.

Still, if you wanted that additional flexibility, I could imagine --localdoc=dir (which defaults to the same directory as --local=dir so you would only have one code-path) that could be consulted (via s/path/docpath/) to see if the corresponding location sported a foo.haddock or foo.html file, and if so it was used as the file:// URL for the doc.

But really, if someone's choosing to split their hoogle files from their html and haddock files, it doesn't seem out of bounds to suggest that if they also want local URLs to work correctly they should add @url to the files. So unless it was truly zero effort, I personally might pass.

Does any of this sound sensible?

[ndmitchell]

The .txt files are never required after. Defaulting to the same directory only makes sense once you have recursive search for the .txt, which we now do, so I agree that's the right way to go.

[ndmitchell]

I think #186 solves this nicely - I've already used it in anger very successfully. Please reopen if you think there is more to do.

[mdorman]

I think this is working great, I'm quite satisfied.