Just speaking as a mod_perl user/developer, I think the format of Rich's docs is
excellent. Since these are directives that belong in httpd.conf, it makes sense
for their documentation to look like the documentation of other non-perl
directives that belong in httpd.conf. Organization-wise, Rich's docs seem like a
reference, whereas most of the docs Stas points to seem to be more tutorial or
task-oriented in nature.
Perhaps Rich's docs should remain fairly slim, with links to more comprehensive
discussion in the 'tutorial/howto' docs? Would that be maintainable?
Wes
Stas Bekman <[EMAIL PROTECTED]> on 06/18/2002 02:09:51 PM
To: Rich Bowen <[EMAIL PROTECTED]>
cc: [EMAIL PROTECTED] (bcc: Wesley
Sheldahl/Lex/Lexmark)
Subject: Re: mod_perl module documentation
Rich Bowen wrote:
> It has long frustrated me that there was no mod_perl module
> documentation, in the style of the standard Apache module documentation.
> I don't mean to bash the docs that are there - clearly, they are of
> exceptional quality. But I wanted something like the standard module
> docs.
>
> So, rather than complaining, which would seem to be, at best, in poor
> taste, given the quantity of stuff that folks like Stas have already
> written, I've started on a mod_perl module doc, based on the Apache 2.0
> module documentation XML template. You can see the first cut at
> http://www.apacheadmin.com/mod_perl.html
>
> I know, it is gravely lacking, and needs help. And I intend to do
> something about that. But I have a few questions before I burn a lot of
> time on that.
If you plan to leave it just as it's now (bare bones) it's ok. But if
you plan to really write full fledged docs, please don't. Why duplicated
efforts and confuse users with inconsistent documentation which is
already *huge*.
Have you see the work we have done in the last half a year?
http://perl.apache.org/release/docs/
I've been working on docs similar to your doc recently:
http://perl.apache.org/release/docs/2.0/user/config/config.html
http://perl.apache.org/release/docs/2.0/user/handlers/handlers.html
not very different than yours but adhers to the rest of the documentation.
We already have 106 pods (2.3MB) and growing. So if you want to help
please join the docs list and let's talk there:
http://perl.apache.org/release/maillist/docs-dev.html#Subscription_Information
we may come up with an idea to make Apache style docs as well, but only
bare bones with pointers to the real docs. let's talk over docs-dev.
> Where, if anywhere, should such a document go? Yeah, it can stay
> where it is, but I would not think that anyone would think to look
> there.
we have it already.
> Has someone already done this, and I'm just missing it? I know that
> there is similar information at
> http://www.apacheref.com/ref/mod_perl.html but I was hesitant to steal
> that wholesale. Besides, everyone should buy Ralf's book, and I don't
> want to dilute that in any way. ;-)
>
> Is there currently, or are there any plans for, a mod_perl
> documentation cvs repository, where something like this could live?
the repository exists for some 9 months, called modperl-docs
> Anyways, tell me what you think. I have the original XML, which is
> vastly more useful than the HTML output, and would be glad to give that
> to anyone that wants it.
see above
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:[EMAIL PROTECTED] http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
