Re: gtkmm capabilities

[Roel Vanhout <roel riks nl>]

Murray Cumming wrote:
> > Anyway, a wiki-ish documentation annotation system like PHP has would be 
> > great for gtkmm documentation. There is software to do that available on 
> > http://webnotes.futureware.biz/. I'm not sure how hard it would be to 
> > adapt it to make it work with the gtkmm doxygen/docbook-generated pages.
> I'd be happy to have this kind of thing if someone can make it work. 
> I can imagine the following problems:
> - Changes to the generated documentation on the webs site could conflict
> with changes/updates to the original. These must be dealt with somehow.
> - Changes to the generated documentation might have to be rewritten as
> changes to the source. It would be nice if the system allowed people to
> change a copy of the source online and then regenerated the
> documentation.
> I heard that mono/gtk# had a system that did something similar, but I
> can't find it now.
> It would be best to try this on some external website at first. I can
> help with hosting if someone wants to try.

Ok well I'll try to set it up then. Murray, your concerns seem to 
indicate that you see the system slightly different as what I meant: I 
didn't mean an on-line editor for the documentation, but more an 
annotation system where users can enter problems they ran into (and 
possible solutions) so that the maintainer of the documentation can go 
over that feedback from time to time, incorporate what he/she thinks is 
useful and delete the non-relevant notes. Or leave some notes than don't 
fit well into the documentation but could be of use to someone. Have a 
look at the php documentation: http://nl3.php.net/manual/en/ref.http.php.

With that out of the way: there are two parts to be considered: the 
tutorial (generated from docbook) and the reference documentation. I 
haven't looked at the doxygen part yet but I've written a small 
stylesheet that will put in the necessary code to make the 
docbook-generated pages support phpwebnotes. It's a small stylesheet and 
the only other change needed is to add an extra target to the 
makefile.am in the docs/tutorial directory. I have it running on my 
local machine but unfortunately I don't have a server at the moment 
where I can put it on to demonstrate. So if I can mail anyone the files 
needed to demonstrate and the procedure to do it all, let me know. Or if 
you have a machine where you can give me a shell I'll do it myself.
One problem that I encountered is that in order for the comments to 
identify which page they belong to, the filename of that page has to 
stary the same over time. With auto-generated page names that won't 
work, so we'd have to put in id's for every chunk that will become a 
page and set the use.id.as.filename parameter to 1 when processing the 
docbook xml.

The second part, the doxygen-generated documentation, isn't clear yet, I 
haven't yet looked at how easy it is to extend doxygen. I'll do that 
next week I hope, at least, if there is interest.

cheers,

roel