Pisces theme

[taktoa]

Pisces, written by @lamefun in his fork of Haddock, is a not-yet-merged Haddock theme that looks pretty good. However, until I updated it yesterday, it had bitrotten considerably, and could not be applied to the latest Haddock master.

The main issue here is that the patch combines some refactoring with semantic changes; I tackled this by simply looking at all the commits modifying relevant files since Pisces was written, and manually applied them to the refactored code as best I could. Assuming the refactoring he did is acceptable to the Haddock maintainers -- it comprises mostly good changes like using qualified imports, and for the most part only affects haddock-api/Haddock/Backend/Xhtml.hs -- I think the best course of action might be to try to get his changes merged before they bitrot again.

I made a pull request against his Haddock fork, but I suspect that he does not use GitHub very much, so I'm willing to be a point of contact for getting these changes merged, though I am not sure if there is a legal issue there.

Currently, there are a few issues with the patch as it stands:

1. I couldn't figure out a way to easily get it compiling under the GHC 8.2 release candidate on my machine, so after I managed to rebase it onto master, I backported the code to the commit before the haddock-2.17.5-release tag so that I could build it more easily. Once GHC 8.2 is released, it will be easier for me to use, since nixpkgs will have the relevant packages in its binary cache.
2. I am not 100% sure that I correctly applied the changes related to adding signature support (Backpack). I think I did, but I'd like to test it, and I can't do that without compiling under the new GHC.
3. Obviously, due to the refactoring, this will not be easy to code review. I think the best way to approach reviewing this is to simply read the new code and regression test (manually).
4. There are still some issues with the theme itself. In particular:
   • The expand/collapse buttons seem to be broken
   • Some things still don't look quite right
   • I wasn't able to figure out how to merge commits related to supporting the listing of orphan instances in modules, so that feature doesn't yet exist.

cc @lamefun, @ezyang (regarding the signature stuff)

[ezyang]

Which commit are the Backpack changes? I looked at the PR but couldn't find it.

[taktoa]

It's easiest to read here: https://github.com/taktoa/haddock/commit/86df6bb57a26df84bd90abd475774163da2cc225 The relevant file is haddock-api/src/Haddock/Backends/Xhtml.hs

[lamefun]

I'm glad to see that somebody has finally picked up on this.

I made a pull request against his Haddock fork, but I suspect that he does not use GitHub very much

I've simply lost interest in this. It's mainly because I started to do is to refactor functions like ppHtml to accept a few records instead of huge argument lists, since I was steadily adding more and more arguments to some of them and just got bored with this after a while. Having to put every such record into a separate module as a best practice to avoid collisions was also annoying.

I've also got banned from /r/haskell on top of that (mainly over my praising of OOP, Python, Apple Swift and Microsoft C#, I'm OK with the ban in case anyone's wondering), so even if I pick this up again, I won't be able to directly announce any progress anymore.

I am not sure if there is a legal issue there.

What legal issue? Isn't Haskell 100% open-source?

[taktoa]

Well, technically you have the copyright on your changes, so it seemed like it might be an issue.

[lamefun]

I'll be glad if this is finished.

P.S. Pretty please implement standalone documentation pages (this was a part of my original plan), so that people can include tutorials and stuff directly into their Haskell packages without making dummy modules. Having to scrounge documentation from blogs and wikis (which can go offline, go outdated or remove information about old versions) is just plain silly.

[ezyang]

@taktoa The Backpack changes look fine, modulo the missing CSS fragment.

[brezal]

@taktoa How are things coming along? How long do you think this will take?

[taktoa]

@brezal Currently just waiting on GHC 8.2.1 hitting nixpkgs. Then I'll update the commit with ezyang's CSS suggestion, rebase it to master, and test it. After that, I'll go over the generated output with a fine-tooth comb and create a list of outstanding problems (as another comment on this issue).

[fredefox]

Is there a PR for this anywhere?

[alexbiehl]

Unfortunately not. Would love to see this revived!