demo of some haddock hacks

[erantapaa]

Hi all,

I've been hacking on haddock, and I've come up with some mods which enhance the hyperlinked source pages. You can view a demo at:

http://erantapaa.github.io/haddock-demo/src/Data.Compression.Inflate.html#inflate_string

Things to try:

• when hovering over an imported symbol it will show you which module it was imported from
• if you click on a symbol it will show you type information; you can then press the 'a' and 's' keys to grow and shrink the expression

I still consider this at the prototype/proof-of-concept stage. I'm still experimenting with the UI. The most important thing I feel is getting Haddock to emit the requisite information so that the JS can take over.

Note - for this demo I have disabled the standard click action on symbols.

[Helkafen]

Very nice! A few thoughts:

• In your demo the type information is displayed a bit randomly in the page. A fixed div could be a good place to display the type signature (and possibly other information)
• Hovering may also display the type signature (with the possibility to grow/shrink the expression with 'a'/'s')
• In addition to the name of the external module, a link to the symbol definition would be a great addition
• What about selecting an expression with the mouse? Some users may find it more familiar
• For any action other than hovering and clicking, there should be a short howto somewhere in the page

[erantapaa]

Hi Sebastian, thanks for the feedback.

A litte bit more about how things work...

• I left the structure of the hyperlinked-source HTML alone. The only difference is that the anchor tags for imported symbols have an xdef= attribute which holds the module name from which the symbol was imported.
• During the hyperlinked-source generation phase the type-span information for a module is written to a separate JSON file in the src directory. A typical type-span file looks like:

http://erantapaa.github.io/haddock-demo/src/type-spans-Data.Compression.Inflate.js

So the current hightlight.js is compatible with these changes, but it also enables a user to supply their own version and create extra functionality such as what I've shown in the demo. My vision is that by making this information available someone with better JS/HTML skills might come along and make something really cool. Moreover, this additional information might be useful for other purposes.

I have code for both 7.10.x and 8.0.1. Unfortunately because of GHC-API changes there has to be two different versions.

You can view the PR I am in the process of preparing here:

https://github.com/haskell/haddock/compare/master...erantapaa:ghc8

Let me know what your thoughts are. I think it would be a great addition to haddock.

[bgamari]

I left the structure of the hyperlinked-source HTML alone. The only difference is that the anchor tags for imported symbols have an xdef= attribute which holds the module name from which the symbol was imported.

In my understanding you aren't supposed to claim attribute names which aren't defined in the HTML specification. Instead, user-defined attributes should occupy the data- attribute namespace. See this MDN article for details.