Documentation with online comments

[Murray Cumming <murrayc murrayc com>]

Thanks Roel,

So, here is a test site:
http://www.murrayc.com/temp/gtkmm_book_with_comments/html/

Feel free to play around with that.

I"m discussing this with the GNOME web developers, on gnome-web-list:
http://mail.gnome.org/archives/gnome-web-list/

On Fri, 2005-02-18 at 20:03 +0100, Murray Cumming wrote:
> 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