[Haskell-cafe] haddock as a markdown preprocessor

[Conal Elliott]

I guess there was some confusion about the haddock-as-preprocessor idea.
Here's another try:

Pare the Haddock markup language down to very few markup directives, say
just 'foo' and "Foo.Bar".  (Of course, Haddock continues to read and process
type signatures and module import & export specs.)  Compose this slimmed
down Haddock with a more mainstream and powerful markup language/processor
like markdown/pandoc.  How to compose?  By having Haddock translate its
markdown extensions into markdown and pass through all the rest.

The goal redesigning for composability is that we get more for less.
Haddock can focus on its speciality, namely hyperlinked Haskell code
documentation, and pandoc on its, namely human-writable and -readable prose
with modern features (images, friendly hyperlinks, smart quotes & dashes,
footnotes, super- and subscripts, pretty math, bibliography-style link
specs, etc).  Haddock development can focus its resources on
Haskell-specific functionality, and we library writers can still use a
full-featured mark-up language.

I love Haddock's Haskell-smarts, and I love (extended) markdown's features
and usability.  Currently, I have to choose between them, and I'd rather get
both at once.

We can take this composability idea further and plug in other nifty tools
like hscolour and lhs2TeX.  And a new tool that hyperlinks and annotates
source code in a variety of ways.  For instance, hover over an identifier to
see its type and doc string in a pop-up, or click to jump to the source code
(also annotated with type, doc, and source links).  And other tools we
haven't yet thought of.

Cheers,  - Conal


On Thu, Feb 21, 2008 at 5:12 AM, Alistair Bayley <alistair at abayley.org>
wrote:

> On 21/02/2008, Duncan Coutts <duncan.coutts at worc.ox.ac.uk> wrote:
> >
> > To be honest I like the fact that haddock's markup is really simple and
> >  perhaps somewhat restrictive. A great improvement though would be to
> >  make it easy to extract the docs from haddock in a nice format so that
> >  the could be re-used in other contexts rather than just generating html
> >  api documentation. Haddock does have support for multiple backends,
> >  someone just needs to define and write a generic backend that spits out
> >  the info that haddock gathers in a machine readable format.
>
> I have probably misunderstood both of you, but I think that Conal
> proposed that Haddock *input* syntax is largely unchanged; Haddock
> should be able to *output* markdown, for consumption by pandoc.
>
> (Which I think is also what you're suggesting.)
>
> Alistair
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.haskell.org/pipermail/haskell-cafe/attachments/20080221/ad3c2b9a/attachment.htm