apr-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Paul Querna <c...@force-elite.com>
Subject Re: Documentation
Date Sat, 31 Dec 2005 21:15:20 GMT
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

Mime
View raw message