On Mon, 10 Mar 2003 [EMAIL PROTECTED] wrote:
Hi -
I'm getting frustrated. I'm trying to parse the incoming uri (url) in mod_perl 2, and I can't seem to be able to find documentation. For example, Nick gave me the following snippet of code last week:
[...]
Have you tried the pretty good (tm) search engine on the mod_perl site itself? Note that you can restrict your search to the 2.0 docs. For example, searching for `APR::URI->parse' gave me one result: http://perl.apache.org/docs/2.0/user/compat/compat.html#C_Apache__URI_E_gt_parse__r____uri___
which has exactly what I need.
Now of course it also refers me to the man page for APR::URI, which does not (apparently) exist.
Well, I've added pointers to the manpages while writing the compat docs, so once they get added I don't have to go back and look where I want it to be added ;) Hey, the build system is smart enough to check whether the manpage actually exist and link to it. So once it's added the plain text will become a link. But I'm sure it doesn't help you *now*.
I think it may be harder for you, Beau, since you started working with mod_perl with this beta 2.0 version, and don't have a grounding in mod_perl from v. 1.0.
The docs work best when you know what you want to do and how to do it in mp1, and can then find the equivalent for mp2.
Currently, your best source of information:
1) for APIs that haven't changed since mp1 (or have remained quite similar) is to look at perl.apache.org/docs/1.0/ (as Nick has pointer out)
2) for APIs that are new to mp2 (and for mp1 APIs) look at the tests that exercise them. It's the best place to see how things work, because you can actually run them. See modperl-2.0/t/*/*/*.pm (modperl-2.0/t/*.t are driving the tests).
Now re: docs
Documentation is roughly split into API manpages and user guide (plus core developer docs).
1) The API manpages are just that: the manpage. Lyle and Gerald were working on a system to automatically generate the API manpages from apache docs (and after that we will need to massage them to bring them to the perl world). I haven't heard from the folks for a while. Lyle and Gerald, can you please update us if there was any advancement in the project?
2) The user guide part is the actual tutorial-like docs, where the API is devided not by class/method but by functionality. I've started working on it and now you have tutorials for writing filters, protocol modules, HTTP handlers, but only the basic things. Now we need to produce more tutorial-like sections covering the various tasks at hand (e.g. what Beau needed: parsing uris). Think of the eagle book and the cookbook. We need something similar. And also don't forget that we have a bunch of mp1 docs that can be ported to mp2 with a little effort.
So if you want the docs, you need to help to produce them. One you figure out how to parse uri, look at the mentioned books and mp1 docs and produce a section for others to re-use. Somebody else will figure out how to use pools and submit a section on how to use these. Etc.. If everybody were to contribute a little, we would have a great tutorial pretty soon. And the frustration factor will get much lower. People will again start grumbling that there are too many docs for their liking, as it is situation with mp1 docs. But I prefer the latter ;)
Looking forward for your docs submission.
__________________________________________________________________ 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
