From dev-return-15212-apmail-apr-dev-archive=apr.apache.org@apr.apache.org Sat Dec 31 21:15:46 2005 Return-Path: Delivered-To: apmail-apr-dev-archive@www.apache.org Received: (qmail 62697 invoked from network); 31 Dec 2005 21:15:46 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199) by minotaur.apache.org with SMTP; 31 Dec 2005 21:15:46 -0000 Received: (qmail 43324 invoked by uid 500); 31 Dec 2005 21:15:42 -0000 Delivered-To: apmail-apr-dev-archive@apr.apache.org Received: (qmail 43152 invoked by uid 500); 31 Dec 2005 21:15:41 -0000 Mailing-List: contact dev-help@apr.apache.org; run by ezmlm Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Id: Delivered-To: mailing list dev@apr.apache.org Received: (qmail 43122 invoked by uid 99); 31 Dec 2005 21:15:41 -0000 Received: from asf.osuosl.org (HELO asf.osuosl.org) (140.211.166.49) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 31 Dec 2005 13:15:41 -0800 X-ASF-Spam-Status: No, hits=-0.0 required=10.0 tests=SPF_PASS X-Spam-Check-By: apache.org Received-SPF: pass (asf.osuosl.org: domain of chip@force-elite.com designates 216.255.199.145 as permitted sender) Received: from [216.255.199.145] (HELO utopia.in.force-elite.com) (216.255.199.145) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 31 Dec 2005 13:15:40 -0800 X-AuthUser: chip@force-elite.com Received: from [127.0.0.1] (127.0.0.1:39486) by localhost with [XMail 1.17 (Linux/Ix86) ESMTP Server] id for from ; Sat, 31 Dec 2005 13:15:17 -0800 Message-ID: <43B6F4E8.7030801@force-elite.com> Date: Sat, 31 Dec 2005 13:15:20 -0800 From: Paul Querna User-Agent: Thunderbird 1.5 (Macintosh/20051201) MIME-Version: 1.0 To: gerry@lobstertechnology.com CC: dev@apr.apache.org Subject: Re: Documentation References: <1132837417.4385ba29dc471@lobstertechnology.com> <1132837983.4385bc5f4b6c1@lobstertechnology.com> <20051124133914.GM3581@cr> <20051124.230132.41628967.inoue@ariel-networks.com> <1132841869.4385cb8d543a1@lobstertechnology.com> <20051231114446.o09jeaovleck48cc@lobstertechnology.com> In-Reply-To: <20051231114446.o09jeaovleck48cc@lobstertechnology.com> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Virus-Checked: Checked by ClamAV on apache.org X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N gerry@lobstertechnology.com wrote: > > I've been thinking about APR docs in the background for a few weeks > since the brief list thread (that I'm replying against). I've had some > thoughts... > > I've written some stuff using PHP in the past, and quite like the way > they present their documentation: > > http://www.php.net/manual/en/ > http://www.php.net/manual/en/ref.filesystem.php > > They provide a good level of detail in describing each function and > package, and ontop of this they allow developers using it to contribute > a "note" against the methods which generally contain example code, > discussions of memory and CPU useage and other stuff. > > I think this idea can be re-applied to the APR documentation. It's a > fairly embryonic idea at the moment, but I thought I'd kick it out there > and get a bit of feedback before diving-in. > > > DoxyGen can output XML, so we could write some scripts/apps to > manipulate the XML document. This would allow us, for example, to: > > 1) Import each function/packages descriptions into a MySQL database. > > 2) Build a DB table of user submitted notes/comments > > 3) Produce a PHP app that can then present this to the user > > > There are some considerations/assumptions > a) APR doesn't have a huge load so a DB hit isn't such a big deal for > each page request, though if neccessary we could regenerate static > content from the DB on each update. > > b) The web host has, or can be configured with, a DB. The web host must be easily moved between servers. Our current servers do not run a database for any TLP site. > c) The web host has, or can be configured with, a web-scripting language > like PHP/Perl/Java The web host cannot run anything besides CGI. We only use a CGI for the download page. I don't think we want to expand the use of CGI, for the sake of the load average of minotaur and ajax. Our website should be purely static files. This is currently a requirement(1) for almost all the TLPs and their websites. I think better documentation is a good thing. I don't want to stand in the way of that. I am not sure I like the PHP method of allowing comments. I believe documentation should be authoritative, not 'maybe this will work, but try this other way someone mentioned in the comments'. (1) Okay, so its not written in stone anywhere, but I think there would be major resistance to running PHP on the main apache.org webserver(s). Maybe we will have more options once FastCGI support is in mod_proxy... but not right now. -Paul