On Wed, Apr 13, 2005 at 12:28:23PM -0600, Patrick Walsh wrote:
> 	Another thought on documentation: many large projects, such as PHP,
> allow users to add comments on the end of each manual page or section.
> See this page, for example:
> http://us2.php.net/manual/en/function.fopen.php
> 
> 	This is tremendously helpful because users can elaborate on the
> documentation and add feedback, comments, and caveats, which can then be
> incorporated in future versions of the documentation.  And a person
> wouldn't have to reference multiple sources (ie, the wiki errata page
> and the actual manual pages) to find their answer.

I was actually looking at something similar on the zope book and mysql
pages. Also looked at solutions like critlink/annotea/annotation engine.
The zope/php solution is nice but depends on dynamic pages, the critlink
approach is more flexible, but on the other hand far more fragile and
tends to mess up the page layout when it rewrites the page contents.

After a bit of hacking I came up with something where we grab the output
of a cgi script into the footer of a static html page by using a <object
html tag (I guess this is often called 'transclusion').

The cgi script then uses HTTP_REFERER to get the right comments for the
page out of a database. Here is what it looks like,
    http://www.coda.cs.cmu.edu/test.html

Would something like that be useful?
Any comments? Should I use <iframe> instead of <object>?

Jan