[Haddock] vim help text export

[David Waern]

Hi Lars,

2012/1/15 Lars Krueger <lars_e_krueger at gmx.de>:
> Hi,
>
> I'm trying to implement an exporter to vim help text format and I have a few questions. Maybe you guys can help me out on these.
>
> David Waern suggested I should do this in a separate program due to maintenance issues. My first try was to read all .haddock files from the .cabal and /usr/share directories and generate the docs from it.
>
> Q1: It seems the InstalledInterface instances do not contain the actual documentation, just general info. For instance, hmi_description returns Nothing for most, if not all, modules. I concluded the InstalledInterfaces are meant for regenerating the table of contents files. At least the XHtml backend only uses them that way. Is this assumption correct?

No, InstalledInterface is used for other things besides the table of
content. It contains things that Haddock needs to know about a
package, but which is not available from GHC's .hi files, such as doc
comments.

I think what you want is ifaceDoc from Interface. We should add that
to InstalledInterface.

What do your vim files need to contain? If all they need is doc
comments then you should be fine with InstalledInterface (if we add
ifaceDoc). But if you for example need the Haskell declarations of a
module then writing your backend as a separate program becomes more
complicated as you'd have to invoke the GHC API.

> Q2: I get a lot GHC internal modules, even with filtering by OptHide. I took the code from the render function of haddock. Since the package version matches my installed ghc-7.0.4, it's not a stale file or something. Is there another criterion besides OptHide to filter out those modules from the index?

Do you mean GHC.* modules or modules from the ghc package? Another
criterion besides OptHide is the "hidden-modules" and
"exposed-modules" fields in the .conf files installed with the
packages.

> Q3: How do I test an actual haddock run like cabal does it?

Raise the verbosity level of cabal and copy the command line.

> Q4: If my assumption in Q1 is correct, my separate program will be a stripped-down version of haddock's Main module. The only change/addition will be another call to my backend. I fail to see how this will reduce maintainance efforts. What do I miss here?

It will reduce maintenance efforts because your backend does not have
to be maintained as part of Haddock. So it will be you who maintains
the backend instead of us :-) But if it's not convenient to write your
backend as a separate program (because of the immaturity of the
Haddock API for example), I will accept patches for Haddock.

David