[EMAIL PROTECTED] 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
