On Fri, 2005-02-25 at 14:27 -0500, Owen Taylor wrote: > [ Cc'ing gtk-doc list ] > > On Wed, 2005-02-23 at 13:53 +0100, Murray Cumming wrote: > > I think it would be nifty if people could add comments to the online > > documentation. Obviously we'd rather have patches to the > > documentation/source, put people don't often go to that trouble after > > they have discovered something - they need code changes to be submitted > > but documentation changes are not essential to them personally. However, > > they'll make comments immediately if it's easy, and maintainers can then > > make their own changes. > > > > One gtkmm user suggested phpnotes, which you can see demoed here: > > http://www.murrayc.com/temp/gtkmm_book_with_comments/html/ch13s02.php > > > > It was very easy to add the php code to the html with xsl: > > http://bugzilla.gnome.org/attachment.cgi?id=37773&action=view > > > > It's the first time I've heard of it, and I don't know about any similar > > systems. I have the usual dislike php. Any thoughts? > > Thoughts ... > > - Without looking at implementation, I suspect it would be relatively > easy to add something like --enable-phpnotes to GTK_DOC_CHECK() > and gtk-doc.make. (Which turned on a XSL stylesheet parameter, > perhaps.) > > - One big problem is making sure that comments get preserved if > documentation is moved around and across versions of documentation.
I think it uses IDs. You can specify section IDs in docbook that stay the same. I'm not sure how it would work in gtk-doc. > - You probably do want some way of attaching comments to individual > functions rather than the entire page. I suspect some sort of > CSS layer/Javascript thing might be needed to be useful without > too much clutter. (Icons you can click on to get a popup or > something like that.) Yes. > - I think user comments are a bit of a bad idea without an active > editorial process. Useful information needs to be moved into the > real docs. Wrong information needs to be deleted. Yes. This phpwebnotes thing does allow easy moderation. If I use it for gtkmm.org then I will actively update the original documentation and ruthlessly delete nonsense. I think any commented documentation would need a dedicated moderator. It's work. > I've not been 100% impressed with the PHP comments; they are > useful at times. At other times, it's just a noisy discussion > between people who don't really understand what's going on. I think moderation could help there. > - You'd need to figure out the license situation for comments and > sample code in the comments and make it pretty explicit to people > submitting comments. Yeah, some little disclaimer should do that. -- Murray Cumming [EMAIL PROTECTED] www.murrayc.com www.openismus.com _______________________________________________ gtk-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gtk-doc-list
