Re: [Tracker] Documentation

["Mikkel Kamstrup Erlandsen" <mikkel kamstrup gmail com>]

2008/9/29 Martyn Russell <martyn imendio com>:
> Jamie McCracken wrote:
> > agree - maybe gtkdoc?
>
> I would rather not, I hate GtkDoc :) and it is far from compliant with
> Windows, Tor had to add hacks around GtkDoc to get Evolution and other
> technologies working on Windows with it. I have had to do this too.
>
> To me it makes sense to just use a simple text format. This is really
> short documentation pieces describing how to integrate with Tracker for
> developers. It doesn't need to be too fancy or exported to any formats
> like PDF. HTML browsers can usually read clear text too so we don't need
> to use Docbook I would say.
>
> > that way we could point to it in svn as html like gtk documentation
>
> Well, it isn't that simple. The GTK+ documentation is actually generated
>  from what is stored in the GTK+ source tree and then hosted somewhere.
> So we would have to manually do that extra step. Unless someone on l.g.o
> would do that for us with the other projects that have documentation?
>
> We really just need somewhere to list all the documentation links
> collectively I think. We could use live.gnome.org for that.

If it is a big priority that windows users can build the docs then I
see your point. Otherwise not.

One huge advantage of gtk-doc is that it integrates with Devhelp which
is after all in the Gnome development module and can be expected to be
part of any G* development setup on Linux laptops I believe.

I give you that it might not be that funny setting up gtk-doc, but
once everything is up and running I think it works fairly well. Also
all my programming experience tells me that documentation that does
not live next to the functions gets outdated, but maybe I just tend to
hack together with slackers (or maybe I am the slacker ;-P).

Alternatively there are also ways to extract docbook from a Moin wiki
(like lgo) and collect several pages into a book (which is then
compiled to a PDF). It works fairly well (we do it at work, and in the
Xesam project).

-- 
Cheers,
Mikkel