You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-dev@perl.apache.org by Rich Bowen <rb...@CooperMcGregor.com> on 2002/06/18 20:57:46 UTC
mod_perl module docs, a la Apache module docs
Sorry I posted this to the wrong list earlier. Here it is again, in the
right list.
Stas has already responded to the effect that if it is kept bare-bones
and minimalist, like it is at the moment, with pointers to the more
detailed documentation and examples, that it would be acceptable, but
that we want to avoid duplication in order to avoid getting out of sync.
I agree with this sentiment.
So, here's the note, for those that did not already see it on the other
mailing list.
--------------
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 - More #! for your $
Apache training, tech support, and services
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: mod_perl module docs, a la Apache module docs
Posted by Stas Bekman <st...@stason.org>.
Rich Bowen wrote:
> On Wed, 19 Jun 2002, Stas Bekman wrote:
>
>
>>Currently it has no fit into the mod_perl documentation. I don't see
>>anything in this doc which is already not covered in the docs that I've
>>committed just a few days ago:
>>http://perl.apache.org/release/docs/2.0/user/config/config.html
>>http://perl.apache.org/release/docs/2.0/user/handlers/handlers.html
>
>
> OK, those ones I had missed. I thought I had been pretty thoroughally
> through the rest of the site, but these must post-date my reading.
Yup, I've added them a few days ago but forgot to link to them, which
I've fixed yesterday.
If you plan to work on something just drop a note saying so, so there
will be no wasted work.
>>All these people who comment in favor of your doc, haven't even seen
>>what we have already and don't know what has been planned.
>
>
> You're right. They are currently rather hard to find.
Because the new site wasn't released yet. We are still polishing the
design (cross-platform/browsers issues). Should be released really soon now.
>>Rich, what don't you like about the current format? The docs at the URLs
>>I've posted are incomplete but the plan is to have a page of Appendix
>>style where you have all the info placed concisely in one place. e.g.
>>Apache style doc doesn't give you this:
>>http://perl.apache.org/release/docs/2.0/user/config/config.html#mod_perl_Directives_Argument_Types_and_Allowed_Location
>
>
> No, it is not at all that I don't like the current format. The current
> format is good. People used to the Apache documentation frequently ask,
> in my hearing, for a similar document for mod_perl. I have heard this in
> numerous seminars I have taught and attended. I have seen it on mailing
> lists and on IRC. This is not saying that one format is bad, but that
> another is familiar.
mod_perl has a lot of documentation and there will be even more. Our
documents are written in POD because mod_perl is distributed on CPAN
where all docs are written in POD. By referring to Apache doc format you
mean the reference pages, which are just a few (one?) in the mod_perl
land. Would you rather see the mod_perl documentation written
consistently, or have an odd document which look different in the middle?
>>But before we do anything in that direction I don't think there is a
>>need for it. Do you think that there is such a need?
>
> I will defer to you on this. I don't want, at any level, to imply that
> what has been done to date is lacking. This is merely a familiar format
> that people have asked for, and I was trying to fill a need. I'll back
> off now on this issue, if there is not general consensus that it is
> desired. You are right in saying that the new docs fill many of the
> needs that I am addressing, and the only real different is actual page
> layout. When can we expect to have these new docs readily accessible
> from the front page of perl.apache.org?
RSN
> I am very interested in being involved in mod_perl documentation in
> some capacity, but I will lurk for a month or son and see where the need
> is.
Great, take your time and tune in when you feel ready.
Don't destroy your doc, because mod_perl 1.0 does have this doc
(surprise, surprise!):
http://cvs.apache.org/viewcvs.cgi/modperl/htdocs/manual/mod/mod_perl.html
But just as I said, it was last touched 4 years, 3 months ago.
So we probably will supply an Apache style config reference doc with
pointers to real docs once those are written.
I wonder if we should create some incoming dir and drop your file there,
so it won't get lost. Alternatively post it here, so it'll be archived.
__________________________________________________________________
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
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: mod_perl module docs, a la Apache module docs
Posted by Rich Bowen <rb...@CooperMcGregor.com>.
On Wed, 19 Jun 2002, Stas Bekman wrote:
> Currently it has no fit into the mod_perl documentation. I don't see
> anything in this doc which is already not covered in the docs that I've
> committed just a few days ago:
> http://perl.apache.org/release/docs/2.0/user/config/config.html
> http://perl.apache.org/release/docs/2.0/user/handlers/handlers.html
OK, those ones I had missed. I thought I had been pretty thoroughally
through the rest of the site, but these must post-date my reading.
> All these people who comment in favor of your doc, haven't even seen
> what we have already and don't know what has been planned.
You're right. They are currently rather hard to find.
> Rich, what don't you like about the current format? The docs at the URLs
> I've posted are incomplete but the plan is to have a page of Appendix
> style where you have all the info placed concisely in one place. e.g.
> Apache style doc doesn't give you this:
> http://perl.apache.org/release/docs/2.0/user/config/config.html#mod_perl_Directives_Argument_Types_and_Allowed_Location
No, it is not at all that I don't like the current format. The current
format is good. People used to the Apache documentation frequently ask,
in my hearing, for a similar document for mod_perl. I have heard this in
numerous seminars I have taught and attended. I have seen it on mailing
lists and on IRC. This is not saying that one format is bad, but that
another is familiar.
> > Doc will be provided in some format that is easy to maintain. The XML
> > doc is very nice, but as long as we don't have a means to convert, it is
> > a little silly. So I'll do the initial convert, and then we'll go from
> > there.
>
> Convert where?
I actually created the doc in my httpd-docs-2.0 cvs checkout, and used
the tools there to convert it. That way I can write it in simple XML and
not have to write HTML.
> > How's that? How do we proceed?
>
> DocSet, the framework that is currently used for building the docs/site
> accepts pod and html as the source format and can be extended to other
> formats, like xml. The problem with xml is that it has lots of
> prerequisites which sometimes are hard to get. Though I agree that xml
> is a superior data format to pod when it comes to tabulated data.
>
> But before we do anything in that direction I don't think there is a
> need for it. Do you think that there is such a need?
I will defer to you on this. I don't want, at any level, to imply that
what has been done to date is lacking. This is merely a familiar format
that people have asked for, and I was trying to fill a need. I'll back
off now on this issue, if there is not general consensus that it is
desired. You are right in saying that the new docs fill many of the
needs that I am addressing, and the only real different is actual page
layout. When can we expect to have these new docs readily accessible
from the front page of perl.apache.org?
I am very interested in being involved in mod_perl documentation in
some capacity, but I will lurk for a month or son and see where the need
is.
--
Rich Bowen
Apache Administrators Handbook
ApacheAdmin.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: mod_perl module docs, a la Apache module docs
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
> It's true that Stas has done a wonderful job for those 2.0 docs, which
> shouldn't be neglected.
Don't forget that Doug wrote the initial major part. I'm writing on top
of his work.
> However we don't have such reference docs for
> 1.0, so that might be useful. And I'm sure we could make the 2 docs
> co-exist happily.
And as I said before, 2.0 docs are *the* priority now. 1.0 docs may be
not perfect, but they are sure thing covering most of the material. 2.0
docs are scarce and very soon the rate of 2.0 questions on the list will
rocket and I prefer to reply with RTFM URLs and create new things at the
saved time, rather than waste time and write explicit replies.
> But one thing's for sure, we're proud of our docs and
> don't want to replace them :-)
Actually our motives have nothing to do with the proud (in case that
you've missed the smiley in Per Einar's comment).
The problem is that everybody and their mom comes to ask questions at
the modperl list. When the documentation is forked it becomes extremely
hard to help those users who read their info in various places, not
talking about how hard it makes for users to choose what source to read.
Therefore we apply a big effort to have a *single* source of
documentation which satisfies the major mass and we are absolutely open
to contributions from others and looking forward to these. The only
requirement we have is that we fit the contributions into the docs core
as we find appropriate, and may reject certain contributions, because we
happen to intimately know the layout of the docs, the logic behind these
docs, what areas are already covered and what material is out of scope.
Not talking about the huge amount of time we put into creating the
infrastructure.
I hope you understand that we act in the interests of the whole
community and not going after our proud. I'm looking forward to delegate
all those docs that I wrote and maintain to other people so I can move
on doing other things, so if you feel that you know certain areas of
mod_perl quite well feel free to take over these or simply help working
on these.
__________________________________________________________________
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
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: mod_perl module docs, a la Apache module docs
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 04:35 19.06.2002, Stas Bekman wrote:
>Rich Bowen wrote:
>>On Tue, 18 Jun 2002, Rich Bowen wrote:
>>
>>>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.
>>
>>OK, so, given the various comments, I gather that the following.
>>The document itself meets with general approval, as a concept.
>>We should leave it exceedingly simple, and provide links to additional
>>documentation in the guide, where available.
>
>Currently it has no fit into the mod_perl documentation. I don't see
>anything in this doc which is already not covered in the docs that I've
>committed just a few days ago:
>http://perl.apache.org/release/docs/2.0/user/config/config.html
>http://perl.apache.org/release/docs/2.0/user/handlers/handlers.html
>
>All these people who comment in favor of your doc, haven't even seen what
>we have already and don't know what has been planned.
>
>What I was saying that if you prefer to still keep it, don't extend on it,
>but provide pointers to directives discussions. Which I'd also hold off,
>because the 2.0 docs are on move and their layout will change a lot as
>more docs get written.
It's true that Stas has done a wonderful job for those 2.0 docs, which
shouldn't be neglected. However we don't have such reference docs for 1.0,
so that might be useful. And I'm sure we could make the 2 docs co-exist
happily. But one thing's for sure, we're proud of our docs and don't want
to replace them :-)
--
Per Einar Ellefsen
per.einar@skynet.be
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: mod_perl module docs, a la Apache module docs
Posted by Stas Bekman <st...@stason.org>.
Rich Bowen wrote:
> On Tue, 18 Jun 2002, Rich Bowen wrote:
>
>
>>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.
>
>
> OK, so, given the various comments, I gather that the following.
>
> The document itself meets with general approval, as a concept.
>
> We should leave it exceedingly simple, and provide links to additional
> documentation in the guide, where available.
Currently it has no fit into the mod_perl documentation. I don't see
anything in this doc which is already not covered in the docs that I've
committed just a few days ago:
http://perl.apache.org/release/docs/2.0/user/config/config.html
http://perl.apache.org/release/docs/2.0/user/handlers/handlers.html
All these people who comment in favor of your doc, haven't even seen
what we have already and don't know what has been planned.
What I was saying that if you prefer to still keep it, don't extend on
it, but provide pointers to directives discussions. Which I'd also hold
off, because the 2.0 docs are on move and their layout will change a lot
as more docs get written.
Of course nobody is trying to prevent other people who instead of
helping with a single source of documentation try to duplicate the
efforts and simply bring a lot of confusion to poor users who already
somehow have to sip through hundreds of pages of docs.
Rich, what don't you like about the current format? The docs at the URLs
I've posted are incomplete but the plan is to have a page of Appendix
style where you have all the info placed concisely in one place. e.g.
Apache style doc doesn't give you this:
http://perl.apache.org/release/docs/2.0/user/config/config.html#mod_perl_Directives_Argument_Types_and_Allowed_Location
> Doc will be provided in some format that is easy to maintain. The XML
> doc is very nice, but as long as we don't have a means to convert, it is
> a little silly. So I'll do the initial convert, and then we'll go from
> there.
Convert where?
> How's that? How do we proceed?
DocSet, the framework that is currently used for building the docs/site
accepts pod and html as the source format and can be extended to other
formats, like xml. The problem with xml is that it has lots of
prerequisites which sometimes are hard to get. Though I agree that xml
is a superior data format to pod when it comes to tabulated data.
But before we do anything in that direction I don't think there is a
need for it. Do you think that there is such a need?
__________________________________________________________________
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
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: mod_perl module docs, a la Apache module docs
Posted by Rich Bowen <rb...@CooperMcGregor.com>.
On Tue, 18 Jun 2002, Rich Bowen wrote:
> 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.
OK, so, given the various comments, I gather that the following.
The document itself meets with general approval, as a concept.
We should leave it exceedingly simple, and provide links to additional
documentation in the guide, where available.
Doc will be provided in some format that is easy to maintain. The XML
doc is very nice, but as long as we don't have a means to convert, it is
a little silly. So I'll do the initial convert, and then we'll go from
there.
How's that? How do we proceed?
--
Rich Bowen, CTO, CooperMcGregor
http://www.CooperMcGregor.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org