[Haskell-cafe] Re: ANNOUNCE: gitit 0.2 release - wiki using HAppS, git, pandoc

[John MacFarlane]

+++ Anatoly Yakovenko [Dec 03 08 17:03 ]:
> This is pretty cool.  I was wondering how much work would it be for
> gitit to be able to use markdown from the comment sections in source
> files?  It would be a really good way to manage documentation.
> 
> Basically I would like to be able to point gitit at an existing git
> repo, and have it provide a wiki interface to all the documentation so
> developers can view and modify it.

You can do something like that now. You can specify the repository
directory in a configuration file. Anything in the repository (even
in subdirectories) with a ".page" extension will be served up as a
wiki page. So you'd have to use a ".page" extension for your markdown
documentation. Everything else in the repository will appear in the
index. Source code files will be automatically syntax-highlighted, and
you can even view history and diffs through the wiki interface.

But I guess what you want is for the documentation to be in comments
in the source files themselves, not in separate files.  I'm not sure
how to do that -- would the idea be to show just the documentation,
perhaps marked off with some special notation, and not the source?
But then we lose a nice feature, the ability to view source files.
I'm open to ideas.

Soon, gitit will contain support for pages in markdownish literate
Haskell, which might be the best of both worlds for Haskell projects.
(They'd still need the .page extension, since some .lhs files are
LaTeX lhs, but one could use hard links, or there could be a
configuration option to treat .lhs files as wiki pages.)

John