Re: [Haskell-cafe] improved jhc manual

On 06/13/2014 07:33 AM, John Meacham wrote:

On Wed, Jun 4, 2014 at 8:23 AM, Mateusz Kowalczyk wrote:

...

You're correct that there's no such feature at the moment. If you want something, please open an issue on [1]. Note that I have never used JHC or looked into how it works so I will need very careful description of what I need to do to replicate it all, including small test case, any flags that need to be passed in for Haddock to work with JHC, expected behaviour, a small case where there are no recursive modules so I can confirm it works in simple case &c. If it turns out to not be too complicated then you could have it in the next non-minor release (2.15.x).

What would be easiest is to just bypass much of Haddocks middle end, as in, I don't want it to attempt to follow dependencies or figure out types or call ghc by itself at all. rather I want to give it a pre-digested pap of resolved names and types (and whatever else it needs) but let haddock still parse the file and generate the documention with its back end.

GHC does the parsing of stuff for us, as well as module loading, package finding, name resolution, renaming, …. What we do parse is the things that GHC tells us are Haddock comments (the stuff you actually write). What you'd need to produce for us to use XHtml backend is [Interface] where Interface is defined in Haddock.Types. Notably, this involves LHsDecl which is a GHC type which the back-end inspects and decides what to do with. What's more, we use some pretty printing functions from GHC to actually render the stuff. Basically, GHC does the bulk of work and we massage whatever we get back into a friendlier format for humans to read. If you don't want to involve GHC at all then it's not feasible to use Haddock. There *are* plans to splice out the parts that don't need GHC to a separate package (currently unimaginatively called haddock-library) and I have already done so with the comment parser (so you can turn String into Haddock doc type) but there are no plans to just not use GHC all together, it is too much work. We are planning to make writing new back-ends easier but the GHC dependency will not go away. So the short version is, there is no GHC middle-end, it is GHC from the beginning to the end. One way to work around this would be to pre-process what we get out of GHC into Haddock types that no longer refer to the GHC data types that we can expose and back-ends can work with but this is rather a lot of work. It seems like a correct thing to do but I don't think the amount of effort justifies it, at least for me. We just don't have the manpower for this: we're *very* understaffed for such a core project. If you know people who would like to work towards such goal though, I'd love to hear about it.

This would be more generally useful as a haddock feature than trying to have it emulate other compilers as any compiler or tool can output this general metainfo format.

John

-- Mateusz K.