
[feature request near the end] Hi Neil,
Documentation isn't my strong point :)
i noticed that you often reply to feature requests by pointing to undocumented tools/features, either already released in secret, or forthcoming. not that it isn't nice to have those tools, but won't you lose track of your software and its capabilities at this rate (not to talk about your customers' confusion)?-)
It was originally only intended to be an internal thing for Hoogle, but it does seem generally useful.
in spite of the option name, it doesn't seem Hoogle-specific at all, nor does it really fall into the remit of Haddock as annotation processor. i used to think that type info and such could be added to tags-files, but that is also not quite right - tags files can be extended with such info, but they have no room for tags without source code reference. Haddock-ghc might be equipped to provide the information, but do we really want it to become a general information extractor? perhaps this kind of index generation should really be a feature of the Haskell implementation itself; and indeed, there are :browse and :info already. how about an :index command?
You can always download hoogle.txt, or perhaps we could supply summary.txt with the HTML output as the documentation? The GHC people would have to be the ones to decide it - Hugs doesn't ship with documentation anyway.
separate downloads go out of sync, so tools should be able to rely on info included with releases. as for documentation: one of the nicest features of windows GHC releases is the inclusion of html docs - i use that all the time. of course, Hugs comes with sources instead of docs, so when Hugs was still my main platform, :find was one of my favourite features.
My experience with parsing haddock generated HTML is that its painful, and usually wrong. The indexes might be a bit clearer, but parsing out the type signatures and names was a nightmare.
yes, it is a hack. and it is more pattern-based extraction than proper parsing.
ghc-haddock will fix that. Extracting names from the index will also miss those without type signatures.
for the libraries, anything not documented doesn't exist!-) but yes, until it is integrated with GHC, Haddock will not produce complete indices. which brings me back to my point that GHC(i) should produce those indices itself.
$ ghc -e ":b Data.Char"
I experimented with this as the means for getting information for Hoogle. It was fine, apart from extracting instances (you needed the instance and the type both to be in scope, which you can't really do, or the instance is missed).
yes, if one wants instances, one could use :info <class>, but doing that automatically for every class becomes tedious quickly. also, the pretty printing really gets in the way of simple-minded post-processing. Hugs used to have a :browse all, but i don't recall what all meant there. so here is a feature request for Haskell implementations: in addition to :browse, :info, :[ce]tags, i'd like to see :index, as a way to dump the symbol table for a Haskell project and libraries (including those not available in source code). the output should include, for every available item: - identifier (unqualified name/symbol) - qualifier (module prefix) - namespace (function/data constructor, type/constructor, class, module,..) - type - package - source reference relative to package top - doc reference relative to package doc top all in an easy-to-process-by-various-tools format (think ide/editor, not usually written in Haskell itself), please?-) thanks, claus