atom feed18 messages in net.php.lists.phpdocRe: [PHP-DOC] User commentary in docs
FromSent OnAttachments
Rich BowenApr 6, 2010 7:56 am 
Daniel BrownApr 6, 2010 8:18 am 
Philip OlsonApr 6, 2010 8:25 am 
Rasmus LerdorfApr 6, 2010 9:04 am 
Rasmus LerdorfApr 6, 2010 9:08 am 
Robert P. J. DayApr 6, 2010 9:40 am 
Daniel BrownApr 6, 2010 9:47 am 
Rasmus LerdorfApr 6, 2010 9:50 am 
Rich BowenApr 6, 2010 9:51 am 
Robert P. J. DayApr 6, 2010 9:53 am 
Philip OlsonApr 6, 2010 9:55 am 
Rich BowenApr 6, 2010 9:55 am 
Rasmus LerdorfApr 6, 2010 9:57 am 
Rich BowenApr 6, 2010 10:00 am 
Stelian MocanitaApr 6, 2010 10:11 am 
Bill SalakApr 6, 2010 11:40 pm 
Hannes MagnussonApr 8, 2010 6:00 am 
Bill SalakApr 8, 2010 9:17 am 
Subject:Re: [PHP-DOC] User commentary in docs
From:Rasmus Lerdorf (ras@lerdorf.com)
Date:Apr 6, 2010 9:04:36 am
List:net.php.lists.phpdoc

On 04/06/2010 07:56 AM, Rich Bowen wrote:

A few of us on the Apache HTTP Server documentation team are investigating what it would take to add a user commentary system to the Apache HTTPD docs, like that used on the PHP docs. What software is used for that? Is it easily reusable in other places? Where can I get some more info about it?

It's custom code for our docs, but it probably wouldn't be too hard to bolt onto another system. Start here:

http://svn.php.net/viewvc/web/php/trunk/manual/add-note.php?view=markup

That's the end point users use to add a note to the manual. The note gets sent to a central server (master.php.net). The receiving script for those notes is:

http://svn.php.net/viewvc/web/php-master/trunk/entry/user-note.php?view=markup

And the schema for the central notes DB is here:

http://svn.php.net/viewvc/web/php-master/trunk/note.sql?view=markup

There is a note management console at:

http://master.php.net/manage/user-notes.php

The source for that console is here:

http://svn.php.net/viewvc/web/php-master/trunk/manage/user-notes.php?view=markup

Then, to get the notes back out onto the mirror sites we have an rsync server which runs a cronjob:

http://svn.php.net/viewvc/systems/trunk/update-phpweb-backend?view=markup

That cron job calls this script:

http://svn.php.net/viewvc/web/php-master/trunk/scripts/update-user-notes?view=markup

which fetches the user notes from master with this script:

http://svn.php.net/viewvc/web/php-master/trunk/fetch/user-notes.php?view=markup

So, now we have all the user notes on the rsync server. All the mirror sites fetch those notes every couple of hours. So all that is left to do is to show the notes. The code to show them is here:

http://svn.php.net/viewvc/web/php/trunk/include/shared-manual.inc?view=markup

See the various manual_note* functions in that file. Also note that people who are "logged in" by having the MAGIC_COOKIE set can click directly on a note to reject it or edit it on the master server from the manual page instead of having to go hunting for it manually in the note console.

There are also a couple of helper scripts here: http://svn.php.net/viewvc/web/doc/trunk/scripts/

I probably missed a few bits, but that should be the bulk of it. It might be easier to just steal bits and pieces of this and write your own from that.

-Rasmus