Re: [Tracker] Documentation

[Carlos Garnacho <carlos imendio com>]

Hi!,

On lun, 2008-09-29 at 16:40 +0100, Martyn Russell wrote:
> 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?

GTK+ docs are built from the gtk-doc comments in source code, plus some
docbook files, and as far as I know, making l.g.o build docs for a new
project isn't hard.

Thinking mostly about the modules documentation here, when we allow
building external modules out of tree, we'll have to document the API
that will be public, and a howto for developing modules seems to quite
fit in there...

> We really just need somewhere to list all the documentation links
> collectively I think. We could use live.gnome.org for that.

Yeah, overall I think it's worth it

>
-- 
Carlos Garnacho
Imendio AB - Expert solutions in GTK+
http://www.imendio.com