[Haskell-cafe] GSoC Project: A Haddock + Pandoc documentation tool

[Alvaro Vilanova Vidal (viator)]

> 1) Two places containing the API reference.
>
> In your example documentation the API reference is included in one of
> the chapters. Wouldn't it be better to just have it in one place - the
> Haddock docs?
>

The example is just a test of how you could create a full-customizable
single document which includes the Haddock reference. Of course, the idea is
that you could create documentation without any Haddock render directive
(but keeping the cross references) and then, you could enable the attachment
Haddock reference in the same document or in another document.


> 2) Integration with Haddock docs.
>
> I think it would be best if the pages generated by this system and the
> pages generated by Haddock would be integrated as much as possible -
> both style wise (sharing CSS, structure, headers, footers, sidebars
> etc) and also in terms of hyper linking. Identifiers in your
> documentation should go to the Haddock docs. It should feel as if the
> Haddock pages are just a part of the whole documentation structure.
>

I agree, and I tried to represent that in the example (but I created a new
css). All the documentation will be rendered by Pandoc so there is no
difference between the format of each side. I also think it would be
interesting to be able to refer to parts of the documentation from Haddock,
but keeping the Haddock format (This is not shown in the example).


> 3) Configuration
>
> I haven't looked at this yet but I suspect people will not want
> another configuration file in their projects. Perhaps you could
> propose some kind of Cabal integration instead.
>

That would be awesome. I have to see how Cabal handles these files.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.haskell.org/pipermail/haskell-cafe/attachments/20100409/b12c9dbb/attachment.html