Re: gtkmm capabilities

[Murray Cumming <murrayc murrayc com>]

On Fri, 2005-02-18 at 19:35 +0100, Roel Vanhout wrote:
> 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.

Yes, that might be useful if nothing else is possible. Making it submit
them to bugzilla would be a nice extra step.

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

Sure. Please just submit a patch in bugzilla.

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

It's good if you can do that, but this would not be a big problem if the
comments are fairly well maintained. I don't expect there to be many
meaningful comments that would not be quickly put into the the original
documentation, even if I'm forced to do it myself.

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

Thanks and well done.

-- 
Murray Cumming
murrayc murrayc com
www.murrayc.com
www.openismus.com