[Haskell-cafe] haddock as a markdown preprocessor
tux_rocker at reinier.de
Fri Feb 22 13:57:27 EST 2008
Op 22-feb-2008, om 1:54 heeft Conal Elliott het volgende geschreven:
> 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.
While I like the idea of a very powerful authoring system, I doubt
that we should mix the documentation code with the source code. It
seems much clearer to me to separate such heavily-formatted
documentation from the source into separate files.
Of course, the source code includes comments that specify what
functions do, and so provide a bit of API documentation. But such
comments should contain as little formatting as possible to keep them
readable in a text editor.
More information about the Haskell-Cafe