stas 02/04/03 01:16:09
Modified: src/docs/1.0/guide Changes.pod advocacy.pod browserbugs.pod
config.pod control.pod correct_headers.pod
databases.pod dbm.pod debug.pod help.pod
install.pod intro.pod modules.pod multiuser.pod
performance.pod perl.pod scenario.pod security.pod
snippets.pod start.pod strategy.pod
troubleshooting.pod
Log:
* guide::modules
o extend on Apache::Filter(Per Einar Ellefsen)
* guide::correct headers
o rewrite the headers of this chapter (Per Einar Ellefsen)
* guide::config
o extended on method handlers (Per Einar Ellefsen)
* guide::debug
o extended on curinfo macro (Per Einar Ellefsen)
* guide::
o added descriptions to all chapters (Per Einar Ellefsen)
Revision Changes Path
1.5 +20 -0 modperl-docs/src/docs/1.0/guide/Changes.pod
Index: Changes.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/Changes.pod,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- Changes.pod 26 Mar 2002 01:42:58 -0000 1.4
+++ Changes.pod 3 Apr 2002 09:16:08 -0000 1.5
@@ -11,6 +11,22 @@
=head1 ??? ver 1.32
+* guide::modules
+
+ o extend on Apache::Filter(Per Einar Ellefsen)
+
+* guide::correct headers
+
+ o rewrite the headers of this chapter (Per Einar Ellefsen)
+
+* guide::config
+
+ o extended on method handlers (Per Einar Ellefsen)
+
+* guide::debug
+
+ o extended on curinfo macro (Per Einar Ellefsen)
+
* guide::multiuser
o chroot(1) info
@@ -23,6 +39,8 @@
o jail(8) urls (Andrew McNaughton)
+ o link to the internal resources (Per Einar Ellefsen)
+
* guide::install
o James G Smith has uploaded his Apache Builder to CPAN, update the
@@ -47,6 +65,8 @@
bigger collection of the documents, which need to be fully
qualified, so each document can link to other documents in
different projects/subprojects.
+
+ o added descriptions to all chapters (Per Einar Ellefsen)
* Minor corrections:
1.4 +13 -4 modperl-docs/src/docs/1.0/guide/advocacy.pod
Index: advocacy.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/advocacy.pod,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- advocacy.pod 20 Mar 2002 17:43:03 -0000 1.3
+++ advocacy.pod 3 Apr 2002 09:16:08 -0000 1.4
@@ -4,13 +4,22 @@
=head1 Description
-FIXME: DESCRIPTION
+Having a hard time getting mod_perl into your organization? We have
+collected some arguments you can use to convince your boss why the
+organization wants mod_perl.
+
+You can contact the L<mod_perl advocacy list|maillist::list-advocacy>
+if you have any more questions, or good arguments you have used (any
+success-stories are also welcome to L<the docs-dev
+list|maillist::list-docs-dev>).
+
+Also see L<Popular Perl Complaints and Myths|faqs::perl_myth>.
=head1 Thoughts about scalability and flexibility
-Your need for scalability and flexibility depends on what you need from
-your web site. If you only want a simple guest book or database gateway
-with no feature headroom, you can get away with any
+Your need for scalability and flexibility depends on what you need
+from your web site. If you only want a simple guest book or database
+gateway with no feature headroom, you can get away with any
EASY_AND_FAST_TO_DEVELOP_TOOL (Exchange, MS IIS, Lotus Notes, etc).
Experience shows that you will soon want more functionality, at which
1.5 +3 -1 modperl-docs/src/docs/1.0/guide/browserbugs.pod
Index: browserbugs.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/browserbugs.pod,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- browserbugs.pod 20 Mar 2002 17:43:03 -0000 1.4
+++ browserbugs.pod 3 Apr 2002 09:16:08 -0000 1.5
@@ -4,7 +4,9 @@
=head1 Description
-FIXME: DESCRIPTION
+Unfortunately for web programmers, browser bugs are not uncommon, and
+sometimes we have to deal with them; refer to this chapter for some
+known bugs and how you can work around them.
=head1 Preventing QUERY_STRING from getting corrupted because of &entity key
names
1.6 +70 -11 modperl-docs/src/docs/1.0/guide/config.pod
Index: config.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/config.pod,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- config.pod 20 Mar 2002 17:43:03 -0000 1.5
+++ config.pod 3 Apr 2002 09:16:08 -0000 1.6
@@ -4,7 +4,9 @@
=head1 Description
-FIXME: DESCRIPTION
+This section documents the various configuration options available for
+Apache and mod_perl, as well as the Perl startup files, and more esoteric
+possibilites such as configuring Apache with Perl.
=head1 Server Configuration
@@ -987,7 +989,7 @@
If a C<Perl*Handler> is prototyped with C<$$>, this handler will be
invoked as a method. For example:
- package My;
+ package MyClass;
@ISA = qw(BaseClass);
sub handler ($$) {
@@ -1003,28 +1005,85 @@
}
1;
- __END__
Configuration:
- PerlHandler My
+ PerlHandler MyClass
or
- PerlHandler My->handler
+ PerlHandler MyClass->handler
Since the handler is invoked as a method, it may inherit from other
classes:
- PerlHandler My->method
+ PerlHandler MyClass->method
+
+In this case, the C<MyClass> class inherits this method from
+C<BaseClass>. This means that any method of C<MyClass> or any of its
+parent classes can serve as a mod_perl handler, and that you can apply
+good OO methodology within your mod_perl handlers.
+
+For instance, you could have this base class:
+
+ package ServeContent;
+
+ use Apache::Constants qw(OK);
+
+ sub handler($$) {
+ my($class, $r) = @_;
+
+ $r->send_http_header('text/plain');
+ $r->print($class->get_content());
+
+ return OK;
+ }
+
+ sub get_content {
+ return 'Hello World';
+ }
+
+ 1;
+
+And then use the same base class for different contents:
-META: requires more explanation!
+ package HelloWorld;
+
+ use ServeContent;
+ @ISA = qw(ServeContent);
+
+ sub get_content {
+ return 'Hello, happy world!';
+ }
+
+ package GoodbyeWorld;
+
+ use ServeContent;
+ @ISA = qw(ServeContent);
+
+ sub get_content {
+ return 'Goodbye, cruel world!';
+ }
+
+ 1;
+
+Now you can keep the same handler subroutine for a group of modules
+which are similiar. The following configuration will enable the
+handlers from the subclasses:
-In this case, the C<My> class inherits this method from C<BaseClass>.
+ <Location /hello>
+ SetHandler perl-script
+ PerlHandler HelloWorld->handler
+ </Location>
+
+ <Location /bye>
+ SetHandler perl-script
+ PerlHandler GoodbyeWorld->handler
+ </Location>
To build in this feature, configure with:
- % perl Makefile.PL PERL_METHOD_HANDLERS=1 [ ... ]
+ % perl Makefile.PL PERL_METHOD_HANDLERS=1 [ ... ]
=head2 PerlFreshRestart
@@ -1649,9 +1708,9 @@
=head2 References
For more info see
-http://www.modperl.com Chapter 8
+I<Writing Apache Modules with Perl and C>, Chapter 8:
+http://modperl.com:9000/book/chapters/ch8.html
-META: a direct link?
=head1 Validating the Configuration Syntax
1.7 +3 -1 modperl-docs/src/docs/1.0/guide/control.pod
Index: control.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/control.pod,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- control.pod 20 Mar 2002 17:43:03 -0000 1.6
+++ control.pod 3 Apr 2002 09:16:08 -0000 1.7
@@ -4,7 +4,9 @@
=head1 Description
-FIXME: DESCRIPTION
+Covers techniques to restart mod_perl enabled Apache, SUID scripts,
+monitoring, and other maintenance chores, as well as some specific
+setups.
=head1 Restarting Techniques
1.5 +26 -29 modperl-docs/src/docs/1.0/guide/correct_headers.pod
Index: correct_headers.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/correct_headers.pod,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- correct_headers.pod 20 Mar 2002 17:43:03 -0000 1.4
+++ correct_headers.pod 3 Apr 2002 09:16:08 -0000 1.5
@@ -4,9 +4,10 @@
=head1 Description
-FIXME: DESCRIPTION
-
-
+To make caching of dynamic documents possible, which can give you a
+considerable performance gain, setting a number of HTTP headers is of
+a vital importance. This document explains which headers you need to
+pay attention to, and how to work with them.
=head1 SYNOPSIS
@@ -17,17 +18,15 @@
This chapter has been contributed to the Guide by Andreas Koenig. You
will find the references and other related info at the bottom of this
-page. I'll try to keep it up to date with the Master version which
-resides on CPAN. If in doubt -- always check the CPAN for
-C<Apache::correct_headers>.
+page. It was previously distributed from CPAN, but this Guide is now its
+official resting-place.
If you have any questions regarding this specific document only,
please refer to Andreas, since he is the guru on this subject. On any
other matter please contact the mod_perl mailing list.
-=head1 DESCRIPTION
-=head1 1) Why Headers
+=head1 Why Headers
Dynamic Content is dynamic, after all, so why would anybody care about
HTTP headers? Header composition is a task often neglected in the CGI
@@ -49,7 +48,7 @@
L<[1]|guide::correct_headers/_1_>), you will have a strong motivation to
cooperate with it. This document may help you to do it correctly.
-=head1 2) Which Headers
+=head1 Which Headers
The HTTP standard (v 1.1 is specified in L<[3]|guide::correct_headers/_3_>, v
1.0 in L<[2]|guide::correct_headers/_2_>) describes lots of headers. In this
@@ -59,9 +58,9 @@
I have grouped the headers into three groups: date headers,
content headers, and the special Vary header.
-=head2 2.1) Date Related Headers
+=head2 Date Related Headers
-=head2 2.1.1) Date
+=head3 Date
Section 14.18 of the HTTP standard deals with the circumstances under
which you must or must not send a C<Date> header. For almost
@@ -74,7 +73,7 @@
C<$r-E<gt>request_time>. A mod_perl script can read, but not change,
C<$r-E<gt>request_time>.
-=head2 2.1.2) Last-Modified
+=head3 Last-Modified
Section 14.29 of the HTTP standard deals with this. The
C<Last-Modified> header is mostly used as a so-called weak
@@ -124,10 +123,10 @@
use Date::Parse;
# Date::Parse parses RCS format, Apache::Util::parsedate doesn't
$Mtime ||=
- Date::Parse::str2time(substr q$Date: 2002/03/20 17:43:03 $, 6);
+ Date::Parse::str2time(substr q$Date: 2002/04/03 09:16:08 $, 6);
$r->set_last_modified($Mtime);
-=head2 2.1.3) Expires and Cache-Control
+=head3 Expires and Cache-Control
Section 14.21 of the HTTP standard deals with the C<Expires>
header. The purpose of the C<Expires> header is to determine a point
@@ -205,9 +204,9 @@
problem that remains is that there are broken browsers which ignore
C<Expires> headers.
-=head2 2.2) Content Related Headers
+=head2 Content Related Headers
-=head2 2.2.1) Content-Type
+=head3 Content-Type
You are most probably familiar with C<Content-Type>. Sections 3.7,
7.2.1 and 14.17 of the HTTP specs cover the details. mod_perl has the
@@ -220,7 +219,7 @@
is specified in the relevant C<DefaultType> configuration directive or
C<text/plain> if none is active.
-=head2 2.2.2) Content-Length
+=head3 Content-Length
According to section 14.13 of the HTTP specifications, the
C<Content-Length> header is the number of octets in the body of a
@@ -253,7 +252,7 @@
So be careful never to send a wrong C<Content-Length>, either in a
GET or in a HEAD request.
-=head2 2.2.3) Entity Tags
+=head3 Entity Tags
An C<Entity Tag> is a validator which can be used instead of, or in
addition to, the C<Last-Modified> header. An entity tag is a quoted
@@ -344,7 +343,7 @@
tag, thus giving caches a chance to transfer the document in chunks.
(Anybody in the mood to add a chapter about ranges to this document?)
-=head2 2.3) Content Negotiation
+=head2 Content Negotiation
Content negotiation is a particularly wonderful feature that was
introduced with HTTP 1.1. Unfortunately it is not yet widely
@@ -367,7 +366,7 @@
outside the request-header fields or within extension header fields
not defined by this specification.
-=head2 2.3.1) Vary
+=head3 Vary
In order to signal to the recipient that content negotiation has been
used to determine the best available representation for a given
@@ -389,12 +388,12 @@
workaround, you won't enjoy your Squid accelerator for these documents
:-(
-=head1 3) Requests
+=head1 Requests
Section 13.11 of the specifications states that the only two cacheable
methods are C<GET> and C<HEAD>.
-=head2 3.1) HEAD
+=head2 HEAD
Among the above recommended headers, the date-related ones (C<Date>,
C<Last-Modified>, and C<Expires>/C<Cache-Control>) are usually easy to
@@ -421,7 +420,7 @@
whole C<HEAD> request for you, but under some circumstances it may not
be allowed to do so.
-=head2 3.2) POST
+=head2 POST
The response to a C<POST> request is not cacheable due to an
underspecification in the HTTP standards. Section 13.4 does not forbid
@@ -439,7 +438,7 @@
If you have long C<POST> requests, Squid doesn't buy you anything. So
always consider using a C<GET> instead of a C<POST> if possible.
-=head2 3.3) GET
+=head2 GET
A normal C<GET> is what we usually write our mod_perl programs for.
Nothing special about it. We send our headers followed by the body.
@@ -509,7 +508,7 @@
http://example.com/query;BGCOLOR=blue;FGCOLOR=red;FONT=/font/bla
-=head2 3.4) Conditional GET
+=head2 Conditional GET
A rather challenging request mod_perl programmers can get is the
conditional C<GET>, which typically means a request with an
@@ -548,7 +547,7 @@
handle conditional C<GET>s as well even if a Squid accelerator is
running.
-=head1 4.) Avoiding Dealing with Headers
+=head1 Avoiding Dealing with Headers
There is another approach to dynamic content that is possible with
mod_perl. This approach is appropriate if the content changes
@@ -621,8 +620,6 @@
Web Caching and Content Delivery Resources
http://www.web-caching.com/
-=item *
-
=back
=head1 Maintainers
@@ -645,7 +642,7 @@
=item *
-Stas Bekman E<lt>stas (at) stason.orgE<gt>
+Andreas Koenig E<lt>andreas.koenig (at) anima.deE<gt>
=back
1.6 +4 -2 modperl-docs/src/docs/1.0/guide/databases.pod
Index: databases.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/databases.pod,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- databases.pod 20 Mar 2002 18:15:36 -0000 1.5
+++ databases.pod 3 Apr 2002 09:16:08 -0000 1.6
@@ -4,8 +4,10 @@
=head1 Description
-FIXME: DESCRIPTION
-
+Creating dynamic websites with mod_perl often involves using
+relational databases. C<Apache::DBI>, which provides a database
+connections persistence which boosts the mod_perl performance, is
+explained in this chapter.
=head1 Why Relational (SQL) Databases
1.7 +3 -2 modperl-docs/src/docs/1.0/guide/dbm.pod
Index: dbm.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/dbm.pod,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- dbm.pod 20 Mar 2002 18:15:36 -0000 1.6
+++ dbm.pod 3 Apr 2002 09:16:08 -0000 1.7
@@ -4,8 +4,9 @@
=head1 Description
-FIXME: DESCRIPTION
-
+Small databases can be implemented pretty efficiently using dbm files,
+but there are still some precautions that must be taken to use
+properly under mod_perl.
=head1 Where and Why to use dbm files
1.6 +16 -4 modperl-docs/src/docs/1.0/guide/debug.pod
Index: debug.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/debug.pod,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- debug.pod 20 Mar 2002 17:43:03 -0000 1.5
+++ debug.pod 3 Apr 2002 09:16:08 -0000 1.6
@@ -4,7 +4,8 @@
=head1 Description
-FIXME: DESCRIPTION
+Tired of Internal Server Errors? Find out how to debug your mod_perl
+applications, thanks to a number of features of Perl and mod_perl.
=head1 Warning and Errors Explained
@@ -3411,8 +3412,19 @@
in the C<while(1)> loop isn't aborted by Apache. The next section
covers this.
-META: add the note about using the 'curinfo' gdb macro to perform an
-easy detecting of the hanging location.
+To easily detect the hanging location, you can go through these steps
+while running gdb:
+
+ (gdb) where
+ (gdb) source ~/.gdbinit
+ (gdb) curinfo
+
+(adjust the path to I<.gdbinit> if needed.)
+
+After loading the special macros file (I<.gdbinit>) you can use the
+I<curinfo> gdb macro to figure out the file and line number the code
+stuck in.
+
=head1 Debugging Hanging processes (continued)
@@ -3664,7 +3676,7 @@
=head1 Code Profiling
-(Meta: duplication??? I've started to write about profiling somewhere
+(META: duplication??? I've started to write about profiling somewhere
in this file)
It is possible to profile code run under mod_perl with the
1.10 +30 -89 modperl-docs/src/docs/1.0/guide/help.pod
Index: help.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/help.pod,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- help.pod 25 Mar 2002 15:50:14 -0000 1.9
+++ help.pod 3 Apr 2002 09:16:08 -0000 1.10
@@ -4,7 +4,9 @@
=head1 Description
-FIXME: DESCRIPTION
+If your question isn't answered by reading this guide, check this section
+for information on how to get help on mod_perl, Apache, or other topics
+discussed here.
=head1 READ ME FIRST
@@ -22,7 +24,7 @@
help and you should I<RTFM> before you call for I<HELP>. (Remember the
fable of the shepherd boy and the wolves).
-For more information See L<Get helped with
mod_perl|guide::help/Get_help_with_mod_perl>.
+For more information See L<Get help with
mod_perl|guide::help/Get_help_with_mod_perl>.
=head1 Contacting me
@@ -34,7 +36,7 @@
However, you are welcome to submit corrections and suggestions
directly to me at
[EMAIL PROTECTED] If you are
+stas (at) stason.org?subject=mod_perl%20guide%20corrections. If you are
going to submit heavy corrections of the text (I love those!), please
help me by downloading the source pages in POD from
http://www.stason.org/guide-snapshots/, directly editing them and
@@ -43,8 +45,9 @@
I<PLEASE DO NOT SEND QUESTIONS DIRECTLY TO ME, I didn't invite those
by writing the guide. They will all be immediately deleted. Please
-ask questions on the mod_perl list and if we can answer your question,
-one (or more) of us will answer it on the list. Thank you!>
+ask questions on the L<mod_perl list|maillist::list-users> and if we can
+answer your question, one (or more) of us will answer it on the list.
+Thank you!>
=head2 How to Report Problems
@@ -221,7 +224,7 @@
Price: $39.99
Pages: 600
-=item * Managing and Programming mod_perl
+=item * Practical mod_perl
http://www.modperlbook.com is the home site of the new mod_perl book,
that Eric Cholet and Stas Bekman are co-authoring. We expect
@@ -285,125 +288,62 @@
=item * mod_perl mailing lists
-=over
-
-=item * The mod_perl mailing list
-
-The Apache/Perl mailing list I<is available for mod_perl users and
-developers to share ideas, solve problems and discuss things related
-to mod_perl and the Apache::* modules.> To subscribe to this list,
-send email to [EMAIL PROTECTED] . To unsubscribe send
-email to [EMAIL PROTECTED] .
-
-To subscribe to the digest list send email to
[EMAIL PROTECTED] .
-
-Searchable mailing list archives are available:
+META: shouldn't we just link directly to the mailing list page? (once
+linking to a section works).
=over
=item *
-http://mathforum.org/epigone/modperl
-
-=item *
+L<The mod_perl mailing list|maillist::list-users>
-http://www.geocrawler.com/lists/3/web/182/0/
-
-=item *
-
-http://www.mail-archive.com/modperl%40apache.org/
-
-=item *
-
-http://www.davin.ottawa.on.ca/archive/modperl/
+The Apache/Perl mailing list I<is available for mod_perl users and
+developers to share ideas, solve problems and discuss things related
+to mod_perl and the Apache::* modules.>
-=item *
+See the L<mailing list's info page|maillist::list-users> for more info.
-http://marc.theaimsgroup.com/?l=apache-modperl
=item *
-http://www.egroups.com/group/modperl/
-
-=back
-
-=item * The mod_perl development mailing list
+L<The mod_perl development mailing list|maillist::list-dev>
This list is for discussions about the development of the core
mod_perl.
-Subscription information.
-
-To subscribe to this list send an empty email to
[EMAIL PROTECTED] To unsubscribe from the list send an
-empty email to [EMAIL PROTECTED] To get help with the
-list send an empty email to [EMAIL PROTECTED]
-
-List's searchable archives:
-
-=over
-
-=item *
-
-http://marc.theaimsgroup.com/?l=apache-modperl-dev&r=1&w=2#apache-modperl-dev
=item *
-http://www.mail-archive.com/dev%40perl.apache.org/
-
-=back
-
-=item * The mod_perl documentation mailing list
+L<The mod_perl documentation mailing list|maillist::list-docs-dev>
-This mailing list is for discussing mod_perl documentation.
+This mailing list is for discussing mod_perl documentation, and is the one
+you should contact with issues related to this Guide or other
+documentation on this website.
-Subscription information
-
- Subscribe to the list: [EMAIL PROTECTED]
- Unsubscribe from the list: [EMAIL PROTECTED]
- Get help with the list: [EMAIL PROTECTED]
+=item *
-=item * The Apache test framework development mailing list
+L<The Apache test framework development mailing
+list|maillist::list-test-dev>
The test-dev list is the list where Apache HTTP Test project is
discussed.
-Subscription information:
-
- Subscribe to the list: [EMAIL PROTECTED]
- Unsubscribe from the list: [EMAIL PROTECTED]
- Get help with the list: [EMAIL PROTECTED]
-
-List's searchable archive:
-
-http://www.apachelabs.org/test-dev/
+=item *
-=item * The advocacy mailing list
+L<The advocacy mailing list|maillist::list-advocacy>
The list for mod_perl advocacy issues, discussions about
sites, etc.
-Subscribe by sending a mail to [EMAIL PROTECTED]
-Unsubscribe by sending a mail to [EMAIL PROTECTED]
-Use advocacy@perl.apache.org to post to the list.
-
-The archive: http://www.mail-archive.com/advocacy@perl.apache.org/.
+=item *
-=item * The modperl-cvs mailing list
+L<The modperl-cvs mailing list|maillist::list-cvs>
The modperl developers list is the list where you can watch mod_perl
getting patched. No real discussions happen on this list, but if you
want to know about the latest changes in the mod_perl core before
everyone else, this is a list to be on.
-To subscribe to this list, send email to
[EMAIL PROTECTED] . To unsubscribe send email to
[EMAIL PROTECTED] . Send email to
[EMAIL PROTECTED] to post to the list.
-
-No archives available.
-
=back
=back
@@ -451,6 +391,7 @@
I<Advanced Perl Programming> By Sriram Srinivasan. Published by
O'Reilly & Associates. ISBN: 1-56592-220-4. Chapters 18-20.
+http://www.oreilly.com/catalog/advperl/
perl-xs mailing list on perl.org (mail [EMAIL PROTECTED])
@@ -511,7 +452,7 @@
=item * Idiot's Guide to CGI programming
-http://www.perl.com/CPAN/doc/FAQs/cgi/idiots-guide.html
+http://www.webdeveloper.com/cgi-perl/cgi_idiots_guide_to_perl.html
=item * WWW Security FAQ
1.8 +4 -1 modperl-docs/src/docs/1.0/guide/install.pod
Index: install.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/install.pod,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- install.pod 26 Mar 2002 01:42:58 -0000 1.7
+++ install.pod 3 Apr 2002 09:16:08 -0000 1.8
@@ -4,7 +4,10 @@
=head1 Description
-FIXME: DESCRIPTION
+An in-depth explanation of the mod_perl installation process, from the
+basic installation in 10 steps, to more complex one with all the
+possible options you might want to use, including DSO build. It
+includes troubleshooting tips too.
=head1 A Summary of a Basic mod_perl Installation
1.7 +3 -1 modperl-docs/src/docs/1.0/guide/intro.pod
Index: intro.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/intro.pod,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- intro.pod 25 Mar 2002 03:39:00 -0000 1.6
+++ intro.pod 3 Apr 2002 09:16:08 -0000 1.7
@@ -4,7 +4,9 @@
=head1 Description
-FIXME: DESCRIPTION
+An introduction to what mod_perl is all about, its different features,
+and some explanations of C<Apache::Registry>, C<Apache::PerlRun> and
+the Apache/Perl API.
=head1 What is mod_perl
1.5 +82 -6 modperl-docs/src/docs/1.0/guide/modules.pod
Index: modules.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/modules.pod,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- modules.pod 20 Mar 2002 17:43:04 -0000 1.4
+++ modules.pod 3 Apr 2002 09:16:08 -0000 1.5
@@ -4,7 +4,35 @@
=head1 Description
-FIXME: DESCRIPTION
+Overview of some of the most popular modules for mod_perl, both to use
+directly from your code and as mod_perl handlers.
+
+Over the time, mod_perl has collected an impressive amount of modules
+which are distributed in the standard Perl way, over CPAN. Found in
+the C<Apache::> namespace, these implement various functionalities you
+might need when creating a mod_perl-based website. For mod_perl, we
+can actually make a distinction between two types of modules:
+
+=over
+
+=item *
+
+Apache handlers, which handle request phases or whole requests and are
+standalone (C<Apache::GTopLimit> for example).
+
+=item *
+
+Convenience modules, which are like standard Perl modules,
+implementing some useful aspect of web programming, usually using
+mod_perl API for a greater performance or functionality unavailable in
+plain Perl. (A good example of this is C<Apache::Session>.) These
+modules exist under the C<Apache::> namespace because they can only be
+used under mod_perl.
+
+=back
+
+For a complete list of modules, see the L<Apache/Perl Module
+list|products::apache-modlist>.
=head1 Apache::Session - Maintain session state across HTTP requests
@@ -233,7 +261,7 @@
=head1 Apache::PerlRun - Run unaltered CGI scripts under mod_perl
See L<Apache::PerlRun - a closer
-look|guide::porting/Apache_PerlRun_a_closer_look>.
+look|guide::porting/Apache__PerlRun__a_closer_look>.
=head1 Apache::RegistryNG -- Apache::Registry New Generation
@@ -318,13 +346,61 @@
It's really a regular C<Apache::Registry> setup, except for the added
modules in the PerlHandler line.
-(L<Apache::GzipChain|guide::modules/Apache__GzipChain___compress_HTML__or_anything__in_the_OutputChain>
allows to
-compress the output on the fly.)
+(L<Apache::GzipChain|guide::modules/Apache__GzipChain___compress_HTML__or_anything__in_the_OutputChain>
+allows to compress the output on the fly.)
=head1 Apache::Filter - Alter the output of previous handlers
-META: to be written (actually summarized the info from Apache::Filter
-manpage)
+C<Apache::Filter>, like C<Apache::OutputChain>, allows you to chain
+stacked handlers. It's not very different from C<Apache::OutputChain>,
+except for the way you configure the filters. A normal configuration
+with C<Apache::Filter> would be the following:
+
+ PerlModule Apache::Filter Apache::RegistryFilter Apache::SSI Apache::Gzip
+ Alias /perl /home/httpd/perl
+ <Location /perl>
+ SetHandler "perl-script"
+ Options +ExecCGI
+ PerlSetVar Filter On
+ PerlHandler Apache::RegistryFilter Apache::SSI Apache::Gzip
+ </Location>
+
+This accomplishes some things many CGI programmers want: you can
+output SSI code from your C<Apache::Registry> scripts, have it parsed
+by C<Apache::SSI>, and then compressed with C<Apache::Gzip> (see
+L<Apache::Gzip|guide::modules/Apache__Gzip___Auto_compress_web_files_with_Gzip>
+below).
+
+Thanks to C<Apache::Filter>, you can also write your own filter
+modules, which allow you to read in the output from the previous
+handler in the chain and modify it. You would do something like this
+in your C<handler> subroutine:
+
+ $r = $r->filter_register(); # Required
+ my $fh = $r->filter_input(); # Optional (you might not need the input FH)
+ while (<$fh>) {
+ s/ something / something else /;
+ print;
+ }
+
+Another interesting thing to do with C<Apache::Filter> would be to use
+it for XML output from your scripts(these modules are hypothetical,
+this is handled much better by AxKit, Matt Seargeant's XML application
+server for mod_perl (see http://www.axkit.org/ ).
+
+ <Location /perl/xml-output>
+ SetHandler perl-script
+ Options +ExecCGI
+ PerlSetVar Filter On
+ PerlHandler Apache::RegistryFilter Apache::XSLT
+ </Location>
+
+As you can see, you can get a lot of freedom by using stacked
+handlers, allowing you to separate various parts of your programs and
+leave those tasks up to other modules, which may already be available
+from CPAN (this is much better than the CGI time when your script
+would have to do I<everything> itself, because you couldn't do much
+with its output).
=head1 Apache::GzipChain - compress HTML (or anything) in the OutputChain
1.7 +9 -1 modperl-docs/src/docs/1.0/guide/multiuser.pod
Index: multiuser.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/multiuser.pod,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- multiuser.pod 25 Mar 2002 15:41:50 -0000 1.6
+++ multiuser.pod 3 Apr 2002 09:16:08 -0000 1.7
@@ -4,7 +4,15 @@
=head1 Description
-FIXME: DESCRIPTION
+mod_perl hosting by ISPs: fantasy or reality? This section covers some
+topics that might be of interest to users looking for ISPs to host
+their mod_perl-based website, and ISPs looking for a way to provide
+such services.
+
+Today, it is a reality: there are a number of ISPs hosting mod_perl,
+although the number of these is not as big as we would have liked it
+to be. To see a list of ISPs that can provide mod_perl hosting, see
+L<ISPs supporting mod_perl|support::isps>.
=head1 ISPs providing mod_perl services - a fantasy or a reality
1.7 +3 -2 modperl-docs/src/docs/1.0/guide/performance.pod
Index: performance.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/performance.pod,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- performance.pod 21 Mar 2002 10:16:35 -0000 1.6
+++ performance.pod 3 Apr 2002 09:16:08 -0000 1.7
@@ -4,8 +4,9 @@
=head1 Description
-FIXME: DESCRIPTION
-
+An exhaustive list of various techniques you might want to use to get
+the most performance possible out of your mod_perl server:
+configuration, coding, memory use and more.
=head1 The Big Picture
1.4 +4 -0 modperl-docs/src/docs/1.0/guide/perl.pod
Index: perl.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/perl.pod,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- perl.pod 20 Mar 2002 17:43:04 -0000 1.3
+++ perl.pod 3 Apr 2002 09:16:08 -0000 1.4
@@ -2592,6 +2592,10 @@
Stas Bekman E<lt>stas (at) stason.orgE<gt>
+=item *
+
+Matt Sergeant E<lt>matt (at) sergeant.orgE<gt>
+
=back
Only the major authors are listed above. For contributors see the
1.6 +2 -2 modperl-docs/src/docs/1.0/guide/scenario.pod
Index: scenario.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/scenario.pod,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- scenario.pod 20 Mar 2002 17:43:04 -0000 1.5
+++ scenario.pod 3 Apr 2002 09:16:08 -0000 1.6
@@ -4,8 +4,8 @@
=head1 Description
-FIXME: DESCRIPTION
-
+This chapter provides step by step installation guide for the various
+setups discussed in L<Choosing the Right Strategy|guide::strategy>.
=head1 Assumptions
1.4 +4 -1 modperl-docs/src/docs/1.0/guide/security.pod
Index: security.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/security.pod,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- security.pod 20 Mar 2002 17:43:04 -0000 1.3
+++ security.pod 3 Apr 2002 09:16:08 -0000 1.4
@@ -4,7 +4,10 @@
=head1 Description
-FIXME: DESCRIPTION
+Securing your site should be your first priority, because of the
+consequences a break-in might have. We discuss the various
+authentication and authorization techniques available, a very
+interesting use of mod_perl.
=head1 The Importance of Your site's Security
1.6 +2 -2 modperl-docs/src/docs/1.0/guide/snippets.pod
Index: snippets.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/snippets.pod,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- snippets.pod 20 Mar 2002 18:15:36 -0000 1.5
+++ snippets.pod 3 Apr 2002 09:16:08 -0000 1.6
@@ -4,8 +4,8 @@
=head1 Description
-FIXME: DESCRIPTION
-
+A collection of mod_perl code snippets which you can either adapt to
+your own use or integrate directly into your own code.
=head1 Redirecting Errors to the Client Instead of error_log
1.5 +3 -1 modperl-docs/src/docs/1.0/guide/start.pod
Index: start.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/start.pod,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- start.pod 20 Mar 2002 17:43:05 -0000 1.4
+++ start.pod 3 Apr 2002 09:16:08 -0000 1.5
@@ -4,7 +4,9 @@
=head1 Description
-FIXME: DESCRIPTION
+The overview of the different parts of the guide, giving you an idea
+of what you should read, and in which order. Provides a good summary
+of all the documentation.
=head1 What's inside?
1.4 +10 -6 modperl-docs/src/docs/1.0/guide/strategy.pod
Index: strategy.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/strategy.pod,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- strategy.pod 20 Mar 2002 17:43:05 -0000 1.3
+++ strategy.pod 3 Apr 2002 09:16:08 -0000 1.4
@@ -4,8 +4,8 @@
=head1 Description
-FIXME: DESCRIPTION
-
+This document discusses various mod_perl setup strategies used to get
+the best performance and scalability of the services.
=head1 Do it like I do it!?
@@ -648,14 +648,18 @@
=item *
-Memory usage. Squid uses quite a bit of memory.
-
-META: more details?
+Memory usage. Squid uses quite a bit of memory. In fact, it caches a good
+part of its content in memory, to be able to serve it directly from RAM,
+a technique which is a lot quicker than serving from disk. However, as you
+already have your mod_perl server caching its code in RAM, you might not
+want another RAM-hogging beast taking up your precious memory (see the
+Squid FAQ for reference: http://www.squid-cache.org/Doc/FAQ/FAQ-8.html ).
=item *
HTTP protocol level. Squid is pretty much a C<HTTP/1.0> server, which
-seriously limits the deployment of C<HTTP/1.1> features.
+seriously limits the deployment of C<HTTP/1.1> features, such as
+C<Keep-Alive> requests.
=item *
1.6 +3 -2 modperl-docs/src/docs/1.0/guide/troubleshooting.pod
Index: troubleshooting.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/troubleshooting.pod,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- troubleshooting.pod 20 Mar 2002 17:43:05 -0000 1.5
+++ troubleshooting.pod 3 Apr 2002 09:16:08 -0000 1.6
@@ -4,8 +4,9 @@
=head1 Description
-FIXME: DESCRIPTION
-
+If you encounter an error or warning you don't understand, check this
+chapter for solutions to common warnings and errors that the mod_perl
+community has encountered in the last few years.
=head1 General Advice
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
