Proposal: simple interface to libraries Haddock
Hey all, I'm proposing something simple that should make it easier for both Haskell programmers and Haskell tool writers to find the documentation for a function. We need a simple URL for the Haddock docs of any function. PHP has this already: just hit php.net/funcname for the documentation for funcname(). My proposal is similarly simple: http://docs.haskell.org/funcname A CGI script would find funcname in the index and redirect to the URL of the docs for funcname. The only contentious issue is what to do in case of ambiguous lookups; i.e. would docs.haskell.org/lookup be Data.Map.lookup, or Data.List.lookup? My suggestion is that we present a page saying 'which function did you mean?'. We should also allow a way to be unambiguous in the URL: http://docs.haskell.org/Data.Map.funcname Pros: 1) It's really easy to find the documentation for any function. 2) It's really easy to write a tool that finds documentation for a function (including Firefox keywords, Emacs/Vim integration, GHCi integration and so on). Any comments? -- -David House, dmhouse@gmail.com
David House wrote:
I'm proposing something simple that should make it easier for both Haskell programmers and Haskell tool writers to find the documentation for a function.
Like this? http://haskell.org/hoogle/?q=map
On 02/03/07, Bryan O'Sullivan
Like this? http://haskell.org/hoogle/?q=map
I realise it's similar. I don't they fulfill quite the same aim though. Hoogle might give me two dozen results when I roughly know the name of a function, but this isn't what I want. I know the exact name of a function and want its documentation. Perhaps there's not enough distinction there, but Hoogle isn't convenient enough at the moment for general documentation usage. The main reason this is hard at the moment, incidentally, is that the package name (which you can't guess from just the name of the function) is encoded into the Haddock docs URL. -- -David House, dmhouse@gmail.com
Hi David,
I realise it's similar. I don't they fulfill quite the same aim though. Hoogle might give me two dozen results when I roughly know the name of a function, but this isn't what I want.
hoodoc doesn't, it gives you the exact result.
The main reason this is hard at the moment, incidentally, is that the package name (which you can't guess from just the name of the function) is encoded into the Haddock docs URL.
If this is what you want, this is what Hoogle 4 shall have! It is purely a question of a very very light interface around Hoogle - absolutely all the code is already there. Thanks Neil
On 02/03/07, Neil Mitchell
If this is what you want, this is what Hoogle 4 shall have! It is purely a question of a very very light interface around Hoogle - absolutely all the code is already there.
And when will Hoogle 4 be more than vapourwear? :) I guess the answer is 'whenever people stop asking me and start contributing patches' ;) Seriously, though, this sounds perfect. In fact, in terms of writing Emacs integration, I think enough information is there to be able to use the current hoodoc interface (which involves knowing the module it's defined in, but not the package). In terms of a human interface, though, I think having to specify the module is too much of a burden, so I'll wait on Hoogle 4. Thanks for letting us know about hoodoc. -- -David House, dmhouse@gmail.com
Hi
And when will Hoogle 4 be more than vapourwear? :) I guess the answer is 'whenever people stop asking me and start contributing patches' ;)
Patches are not what I need, since all the ideas/designs are in my head. I'll try and get somewhere on it soon, but my time is pretty well booked for the next 3 months. I reckon I'm perhaps a week of coding away from a text-search only. I'll probably release it as Hoogle 0.4 at that point, so people can use these new features (and test them) while I get the type search working (another week of work, perhaps). The libraries required for Hoogle are done though, TagSoup and BinaryDefer - but I haven't had chance to release them yet...
Seriously, though, this sounds perfect. In fact, in terms of writing Emacs integration, I think enough information is there to be able to use the current hoodoc interface (which involves knowing the module it's defined in, but not the package). In terms of a human interface, though, I think having to specify the module is too much of a burden, so I'll wait on Hoogle 4.
Yes, once Hoogle 4 is out, I can give you pretty much exactly the interface you like. I've designed it so Hoogle 4 has the logic for hoodoc and hoogle combined - making these tricks much easier. Thanks Neil
Hi David,
I'm proposing something simple that should make it easier for both Haskell programmers and Haskell tool writers to find the documentation for a function. We need a simple URL for the Haddock docs of any function. PHP has this already: just hit php.net/funcname for the documentation for funcname(). My proposal is similarly simple:
A sensible idea, and Hoogle 4 will have this built in. Hoogle 3 already has something very similar: http://haskell.org/hoogle/hoodoc.cgi?module=Prelude&name=filter&mode=func Hoogle 4 will expand this to have package= I can then trivially add a "feeling lucky (punk)" mode to Hoogle, and you can have http://haskell.org/hoogle/?mode=lucky&q=funcname Thanks Neil
this reminded me that haddock has long generated files with paths and relative urls that allow you to do that kind of thing, if slightly cryptically, and that i have long wanted to access the local haddocs from vim. since i'm a bit slow learning about new things like hoodoc;-) i had to write a little vim command, the first draft of which is attached (tried with vim7.0, ghc-6.4.1, windows, opera; please change paths/details and fix bugs, as appropriate). it doesn't do much more than encode a qualified name into a haddoc-url, but anyway.. enjoy, claus
On 03/03/07, Claus Reinke
it doesn't do much more than encode a qualified name into a haddoc-url, but anyway..
Again, the problem with this script is that it requires you know the package name for the function you're looking up. I see this as an over-burdenous requirement on the user. My guess is that any haddock script that offers similar functionality will have the same requirement. This is why something more search-orientated like Hoogle is required, I guess. -- -David House, dmhouse@gmail.com
Again, the problem with this script is that it requires you know the package name for the function you're looking up. I see this as an over-burdenous requirement on the user.
okay. sometimes i know/guess the module i'm looking for, but not the item. sometimes i recall the item i'm looking for, but not what module it was in. but it does seem less likely that i know the package as well.
My guess is that any haddock script that offers similar functionality will have the same requirement.
not necessarily. that was just the first attempt. attached is an updated vim script file, with an indexed variant of the Doc command. the index is simply a nested dictionary, populated from haddock's index files (not very helpful format, btw). so now you can type :IDoc "runState" Control.Monad.RWS Control.Monad.State Type number of click with mouse (<Enter> cancels): 1 (the first time round, this will build the index first) and launch opera on ../doc/html/libraries/mtl/Control-Monad-State.html#v%3ArunState
This is why something more search-orientated like Hoogle is required, I guess.
it is natural for Hoogle to incorporate search-like functionalities beyond its original call (searching for items based on their types), if they fit easily into its existing framework. but here we are talking about a straightforward dictionary lookup in Haddock's index files. hth, claus
participants (5)
-
Bryan O'Sullivan -
Claus Reinke -
Dan Piponi -
David House -
Neil Mitchell