[Haddock] Fw: [Haskell-cafe] Haddock API and .haddock interface files questions

[Claus Reinke]

Reposted - I guess mailman ate the cc:, so noone noticed this
on haskell-cafe. I'm trying to get an idea of how realistic it is 
to use the Haddock API to write Haddock "plugins"/backends
without having to extend Haddock itself.

Claus

PS. I've subscribed to haddock@ now, but if you were to reply
    on haskell-cafe, that'd be one less list to follow for me;-)

--------------------------------------------------
From: "Claus Reinke" <claus.reinke at talk21.com>
Sent: Tuesday, October 26, 2010 5:03 PM
To: <haskell-cafe at haskell.org>
Subject: [Haskell-cafe] Haddock API and .haddock interface files questions

> Some questions about Haddock usage:
> 
> 1. Haddock executable and library are a single hackage package,
>    but GHC seems to include only the former (haddock does not
>    even appear as a hidden package anymore). Is that intended?
> 
> 2. Naively, I'd expect Haddock processing to involve three stages:
>    1. extract information for each file/package
>    2. mix and match information batches for crosslinking
>    3. generate output for each file/package
> 
>    I would then expect .haddock interface files to repesent the
>    complete per-package information extracted in step 1, so 
>    that packages with source can be used interchangeably
>    with packages with .haddock files.
> 
>    However, I can't seem to use 'haddock --hoogle', say, with
>    only .haddock interface files as input ("No input file(s).").
> 
> 3. It would be nice if the Haddock executable was just a thin
>    wrapper over the Haddock API, if only to test that the API
>    exposes sufficient functionality for implementing everything
>    Haddock can do.
> 
>    Instead, there is an awful lot of useful code in Haddock's
>    Main.hs, which is not available via the API. So when coding
>    against the API, for instance, to extract information from
>    .haddock files, one has to copy much of that code.
> 
>    Also, some inportant functionality isn't exported (e.g., the
>    standard form of constructing URLs), so it has to be copied
>    and kept in synch with the in-Haddock version of the code.
> 
>    It might also be useful to think about the representation
>    of the output of stage 2 above: currently, Haddock directly
>    generates indices in XHtml form, even though much of
>    the index computation should be shareable accross
>    backends. That is, current "backends" seem to do both
>    stage 2 and stage 3, with little reuse of code for stage 2.
> 
> It seems that exposing sufficient information in the API, and
> allowing .haddock interface files as first-class inputs, there
> should be less need for hardcoding external tools into Haddock
> (such as --hoogle, or haddock-leksah). Instead, clients should
> be able to code alternative backends separately, using Haddock
> to extract information from sources into .haddock files, and
> the API for processing those .haddock files. 
> 
> Are these expectations reasonable, or am I misreading the 
> intent behind API and .haddock files? Is there any 
> documentation about the role and usage of these two
> Haddock features, as well as the plans for their development?

4. Just how unstable is the Haddock API? haskellmode for Vim
    used to extract information from Haddock-generated HTML
    indices, which used to be fairly stable in format. That has
    changed for GHC 7.x, so I'd like to switch to using the
    .haddock files, via the Haddock API. Will that code have
    to change for GHC 7.x as well?

> 
> Claus