You are viewing a plain text version of this content. The canonical link for it is here.
Posted to modperl@perl.apache.org by semuel <se...@semuel.co.il> on 2004/01/10 19:40:20 UTC
[mp2] Documentation - newbie questions
Hello There.
1. In the mp2 documentation (http://perl.apache.org/docs/2.0/api/index.html)
there is one module with "No Title" title. Please fix it.
2. In the handlers lists, please include the name of the object that the
handler is getting as parameter.
That is because I looked, and couldn't decide whether PerlResponseHandler is
getting Apache::RequestRec or Apache::RequestIO.
3. Apache::RequestIO does not exist it the documentation. (at the line in 1)
Thanks.
Semuel Fomberg.
Re: [mp2] Documentation - newbie questions
Posted by Stas Bekman <st...@stason.org>.
semuel wrote:
> From: Stas Bekman
> Sent: Saturday, January 10, 2004 10:52 PM
>
>
>>>2. In the handlers lists, please include the name of the object that the
>>>handler is getting as parameter.
>>
>>Which lists you are talking about, please give us the direct URL.
>
>
> URL: http://perl.apache.org/docs/2.0/user/handlers/http.html
> At the beginning of every handler, there is a "$r=shift" line.
> And what is missing is an "$r is ..." comment.
> Like in the response handler. Like in every other.
OK, instead of repeating it in every handler I've added a skeleton section:
http://perl.apache.org/docs/2.0/user/handlers/http.html#HTTP_Request_Handler_Skeleton
>>>That is because I looked, and couldn't decide whether
>>>PerlResponseHandler is
>>>getting Apache::RequestRec or Apache::RequestIO.
>>
>>There is no Apache::RequestIO object, there is only Apache::RequestRec.
>>Apache::RequestIO is a class that contains some methods operating on
>>Apache::RequestRec, and which you need to load in before you can use them.
>
>
> Oh. You mean that RequestIO adds the content_type and the print functions to
> the $r object, that is RequestRec? Interesting.
> The $r->print syntax confused me. Ok.
Yes. Please check out this helper module:
http://perl.apache.org/docs/2.0/api/ModPerl/MethodLookup.html
It will answer most of your questions w/o any need for documentation.
> Can you please add a paragraph in the RequestRec documentation that says:
>
> "This class represent the request arrived from the browser, and the response
> that your program is about to send. Other classes operate on this object,
> and if you can not find a method, try looking at them:
> ... insert here the list ...
> For example, Apache::RequestIO provide the ability to write a response,
> using a "content_type" function, that is activated using:
> $r->content_type('plain/html');"
>
> And in the classes please add:
> "This class provides additional functionality to the Apache::RequestRec
> object. The syntax for using the functions is:
> $r-><relevant example function name>(<relevant parameters>)
> Where $r is an Apache::RequestRec object."
Good suggestions, but please hold on on it and remind me to add it later. I'll
try to autogenerate the missing pod pages first and then you and others can
help to polish them. Thanks.
>>>3. Apache::RequestIO does not exist it the documentation. (at the line
>>>in 1)
>>
>>what's (at the line in 1)?
>
>
> Oops. That was suppose to be "at the link in 1", namely:
> http://perl.apache.org/docs/2.0/api/index.html
> the RequestIO does not exist there.
That's correct. It doesn't exist. Yet.
>>Yes, there are many missing and incomplete manpages. Please send patches.
>
> If I knew enough to correct your man page, I would not have asked these
> (that I'm sure that they are) stupid questions.
> But I don't. all I can do is to point on something and to say, what did you
> mean there?
Agreed. We have very few resources and we are trying to deal with completing
the mod_perl 2.0 code and fixing bugs as a first priority, the docs are
usually added when we add new features. We need more people to learn the API
and help complete the manpages.
> Well, while I'm around, here are some more:
> 4. The Apache package itself, doesn't have place in the API page. (same
> page) but it does exist, as can be seen at:
> http://perl.apache.org/docs/2.0/user/handlers/http.html#PerlHeaderParserHand
> ler
> (where it use the Apache::DECLINED and Apache::method_register.
The Apache module doesn't really exist in mp2, it's spread all over other
modules. So each method will reside in the manpage of the module it leaves in.
We will probably add an empty Apache manpage which will simply list those
functions and methods and point to the relevant manpages for further
information. Again please remind me to add it if I forget.
> 5. Apache::Connection, APR::UUID, APR::Pool doesn't appear in the API page.
> (http://perl.apache.org/docs/2.0/api/index.html)
Just to give you an idea, about 70 other manpages are missing. There are more
than 80 classes in mod_perl 2.0 and some 400 methods. Let me see if I can
autogenerate those, so we can start filling in the missing gaps.
Of course we should first complete the manpages that deal with HTTP handlers
as these are the most important for those moving to mp2 from mp1.
__________________________________________________________________
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
--
Reporting bugs: http://perl.apache.org/bugs/
Mail list info: http://perl.apache.org/maillist/modperl.html
RE: [mp2] Documentation - newbie questions
Posted by semuel <se...@semuel.co.il>.
From: Stas Bekman
Sent: Saturday, January 10, 2004 10:52 PM
>> 2. In the handlers lists, please include the name of the object that the
>> handler is getting as parameter.
> Which lists you are talking about, please give us the direct URL.
URL: http://perl.apache.org/docs/2.0/user/handlers/http.html
At the beginning of every handler, there is a "$r=shift" line.
And what is missing is an "$r is ..." comment.
Like in the response handler. Like in every other.
>> That is because I looked, and couldn't decide whether
>> PerlResponseHandler is
>> getting Apache::RequestRec or Apache::RequestIO.
> There is no Apache::RequestIO object, there is only Apache::RequestRec.
> Apache::RequestIO is a class that contains some methods operating on
> Apache::RequestRec, and which you need to load in before you can use them.
Oh. You mean that RequestIO adds the content_type and the print functions to
the $r object, that is RequestRec? Interesting.
The $r->print syntax confused me. Ok.
Can you please add a paragraph in the RequestRec documentation that says:
"This class represent the request arrived from the browser, and the response
that your program is about to send. Other classes operate on this object,
and if you can not find a method, try looking at them:
... insert here the list ...
For example, Apache::RequestIO provide the ability to write a response,
using a "content_type" function, that is activated using:
$r->content_type('plain/html');"
And in the classes please add:
"This class provides additional functionality to the Apache::RequestRec
object. The syntax for using the functions is:
$r-><relevant example function name>(<relevant parameters>)
Where $r is an Apache::RequestRec object."
>> 3. Apache::RequestIO does not exist it the documentation. (at the line
>> in 1)
> what's (at the line in 1)?
Oops. That was suppose to be "at the link in 1", namely:
http://perl.apache.org/docs/2.0/api/index.html
the RequestIO does not exist there.
> Yes, there are many missing and incomplete manpages. Please send patches.
If I knew enough to correct your man page, I would not have asked these
(that I'm sure that they are) stupid questions.
But I don't. all I can do is to point on something and to say, what did you
mean there?
Well, while I'm around, here are some more:
4. The Apache package itself, doesn't have place in the API page. (same
page) but it does exist, as can be seen at:
http://perl.apache.org/docs/2.0/user/handlers/http.html#PerlHeaderParserHand
ler
(where it use the Apache::DECLINED and Apache::method_register.
5. Apache::Connection, APR::UUID, APR::Pool doesn't appear in the API page.
(http://perl.apache.org/docs/2.0/api/index.html)
Semuel.
--
Reporting bugs: http://perl.apache.org/bugs/
Mail list info: http://perl.apache.org/maillist/modperl.html
Re: [mp2] Documentation - newbie questions
Posted by Stas Bekman <st...@stason.org>.
semuel wrote:
> Hello There.
>
>
>
> 1. In the mp2 documentation (http://perl.apache.org/docs/2.0/api/index.html)
> there is one module with "No Title" title. Please fix it.
Thanks. fixed.
> 2. In the handlers lists, please include the name of the object that the
> handler is getting as parameter.
Which lists you are talking about, please give us the direct URL.
> That is because I looked, and couldn't decide whether PerlResponseHandler is
> getting Apache::RequestRec or Apache::RequestIO.
There is no Apache::RequestIO object, there is only Apache::RequestRec.
Apache::RequestIO is a class that contains some methods operating on
Apache::RequestRec, and which you need to load in before you can use them.
> 3. Apache::RequestIO does not exist it the documentation. (at the line in 1)
what's (at the line in 1)?
Yes, there are many missing and incomplete manpages. Please send patches.
__________________________________________________________________
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
--
Reporting bugs: http://perl.apache.org/bugs/
Mail list info: http://perl.apache.org/maillist/modperl.html