On Thursday 14 April 2005 21:21, Jan Harkes wrote:
> 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
This would be fine if you can get it to render consistently and usefully 
across browsers. It's great in Opera (full width, useful height). Konqueror 
keeps it full width, but only high enough to fit all the buttons in for the 
scroll bar. Firefox has a similar height to Opera, but trims the width to fit 
between the 'send us mail' on the left and 'WWW mirrors' on the right, for me 
at least. 

Al