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

[Anatoly Yakovenko]

On Wed, Dec 3, 2008 at 5:54 PM, John MacFarlane <jgm at berkeley.edu> wrote:
> +++ 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.

cool.  Does it add any other files to the reposoitory?  Could you use
it over a read only one?

> 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.

I was thinking it would show both the documentation and the source,
but have the documentation as the editable part of the page.  Do you
think that's possible?

Or it could parse out the documentation and show 2 dynamically
generated pages, one for just the docs and one for the source.  But i
think it would be useful to be able to see the documentation in the
context of the source that its referring to.

Unfortunately I am not a web guy, so i have no idea how hard any of
this would be :).