You are viewing a plain text version of this content. The canonical link for it is here.
Posted to modperl@perl.apache.org by Rich Bowen <rb...@CooperMcGregor.com> on 2002/06/18 19:30:47 UTC
mod_perl module documentation
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.
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.
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?
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.
--
CooperMcGregor, Inc.
Apache, Perl, and mod_perl
More #! for your $
Re: mod_perl module documentation
Posted by Mads Toftum <ma...@toftum.dk>.
On Tue, Jun 18, 2002 at 01:30:47PM -0400, 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 like it a lot - but then again, I'm a big fan of the apache docs, so
this format is a big hit with me :)
I like the guide, but once you've been through it a couple of times
then this is the sort of document you need IMHO.
Short, concise and more of a reference is the way to go, and it makes
life simpler for someone like me who admins apache more than mod_perl.
vh
Mads Toftum
--
`Darn it, who spiked my coffee with water?!' - lwall
Re: mod_perl module documentation
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> At 11:20 19.06.2002, Leon Brocard wrote:
>
>> Stas Bekman sent the following bits through the ether:
>>
>> > Have you see the work we have done in the last half a year?
>> > http://perl.apache.org/release/docs/
>>
>> I really appreciate all the work that has gone into this. However, I
>> think this content should have replaced all the perl.apache.org root
>> content ages ago. I'm aware of it, but very few other people
>> are. Release early, release often and all that. Is this planned? And
>> if so when? ;-)
We have been posting the URLs to the new site for awhile now, so I
believe most users here are aware of the new site and using it.
> I won't try to speak on behalf of the whole docs-dev list, but IMO we're
> mostly waiting for Allan's latest design update, and we're good to go
> for a release candidate. The most important thing is that we don't crash
> any browsers.
Yup, we don't want people to start complaining about things before we
had a chance to glean out problems we know about (crashes and alike). We
will be releasing it RSN for your preview.
Another reason for withholding the release is a big change in files
structure the docs have gone through, as almost all files have moved to
different locations (with .htaccess making sure that the old links will
still work to some degree). And once we release things we will try to
keep things static so it'll be possible to link to specific pages.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
Re: mod_perl module documentation
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 11:20 19.06.2002, Leon Brocard wrote:
>Stas Bekman sent the following bits through the ether:
>
> > Have you see the work we have done in the last half a year?
> > http://perl.apache.org/release/docs/
>
>I really appreciate all the work that has gone into this. However, I
>think this content should have replaced all the perl.apache.org root
>content ages ago. I'm aware of it, but very few other people
>are. Release early, release often and all that. Is this planned? And
>if so when? ;-)
I won't try to speak on behalf of the whole docs-dev list, but IMO we're
mostly waiting for Allan's latest design update, and we're good to go for a
release candidate. The most important thing is that we don't crash any
browsers.
--
Per Einar Ellefsen
per.einar@skynet.be
Re: mod_perl module documentation
Posted by Leon Brocard <ac...@astray.com>.
Stas Bekman sent the following bits through the ether:
> Have you see the work we have done in the last half a year?
> http://perl.apache.org/release/docs/
I really appreciate all the work that has gone into this. However, I
think this content should have replaced all the perl.apache.org root
content ages ago. I'm aware of it, but very few other people
are. Release early, release often and all that. Is this planned? And
if so when? ;-)
Leon
--
Leon Brocard.............................http://www.astray.com/
Nanoware...............................http://www.nanoware.org/
... Quick! Act as if nothing has happened!
Re: mod_perl module documentation
Posted by Stas Bekman <st...@stason.org>.
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:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
Re: mod_perl module documentation
Posted by Rich Bowen <rb...@CooperMcGregor.com>.
On Thu, 20 Jun 2002, Stas Bekman wrote:
> Doug MacEachern wrote:
> > On Tue, 18 Jun 2002, 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.
> >
> >
> > htdocs/manual/mod/mod_perl.html has been in the modperl dist for 4+ years.
> >
> > granted it was generated by Apache::ModuleDoc, so it even more sparse.
> > but it is in the apache module style. well, the 1.3b5 style anyhow.
> >
> > i'd be happy to see it replaced with yours.
>
> Doh! There is a whole lot of confusion here.
>
> The http://www.apacheadmin.com/mod_perl.html says:
> "Apache HTTP Server Version 2.0"
> so I thought you are writing for mod_perl 2.0 docs... we were talking
> about different things. sigh!
Oops. Sorry. That is from the apache 2.0 module doc template. Crap. I'll
get that fixed.
--
CooperMcGregor, Inc.
Apache, Perl, and mod_perl
More #! for your $
Re: mod_perl module documentation
Posted by Stas Bekman <st...@stason.org>.
Doug MacEachern wrote:
> On Tue, 18 Jun 2002, 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.
>
>
> htdocs/manual/mod/mod_perl.html has been in the modperl dist for 4+ years.
>
> granted it was generated by Apache::ModuleDoc, so it even more sparse.
> but it is in the apache module style. well, the 1.3b5 style anyhow.
>
> i'd be happy to see it replaced with yours.
Doh! There is a whole lot of confusion here.
The http://www.apacheadmin.com/mod_perl.html says:
"Apache HTTP Server Version 2.0"
so I thought you are writing for mod_perl 2.0 docs... we were talking
about different things. sigh!
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
Re: mod_perl module documentation
Posted by Doug MacEachern <do...@covalent.net>.
On Tue, 18 Jun 2002, 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.
htdocs/manual/mod/mod_perl.html has been in the modperl dist for 4+ years.
granted it was generated by Apache::ModuleDoc, so it even more sparse.
but it is in the apache module style. well, the 1.3b5 style anyhow.
i'd be happy to see it replaced with yours.