Re: Annotated online documentation

[Murray Cumming <murrayc murrayc com>]

On Wed, 2005-02-23 at 16:09 +0000, Thomas Wood wrote:
> 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?
> >  
> 
> They use this system in the PHP online documentation at php.net. I have
> always found it to be very usefull and an excellent idea. 
> 
> However, the PHP documentation has a seperate page for each function, so
> the comments are always well focused. I don't know if it'd be such a
> good idea if with the gtk documentation in its current state, since
> there are often multiple functions per page.

I think, with phpwebnotes, you can insert a comments block anywhere in
the page, as often as you like. I guess we could make it
collapsible/summarised somehow, like comments on a blog.

Do bear in mind that I know nothing about competing systems. I'm just
trying phpwebnotes because someone gave me a patch to use it.

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