Re: [Tracker] Documentation

[Jamie McCracken <jamie mccrack googlemail com>]

well i leave it to you guys decide - Im not too bothered about formats

I would prefer html but plain text or docbook if you want is ok with me

jamie


On Mon, 2008-09-29 at 17:51 +0200, Carlos Garnacho wrote:
> 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
>
> >