From a3a4d694959ff6549ab0a37632440f529229c576 Mon Sep 17 00:00:00 2001
From: Mischa POSLAWSKY <perl@shiar.org>
Date: Wed, 28 May 2008 03:55:29 +0000
Subject: [PATCH] expand backend documentation

Add descriptions for PLP::Backend::FastCGI and ::Apache explaining
their configuration and advantages, and recommend/reorder backends
accordingly.

Document a major bug in mod_perl2, and discourage its use for now.
Not investigated, but easily reproducable with:

	<:
	use Cwd qw(cwd);
	say cwd, '<br>';
	sleep 10;  # now request a plp from a different directory
	say cwd, '<br>';
---
 PLP.pm                 | 12 +++++++-----
 PLP/Backend/Apache.pm  | 30 +++++++++++++++++++++++++-----
 PLP/Backend/CGI.pm     |  4 ++--
 PLP/Backend/FastCGI.pm | 28 ++++++++++++++++++++++++++--
 4 files changed, 60 insertions(+), 14 deletions(-)

diff --git a/PLP.pm b/PLP.pm
index e7ec30c..8a535da 100644
--- a/PLP.pm
+++ b/PLP.pm
@@ -293,13 +293,15 @@ F<httpd.conf> for a L<mod_perl|PLP::Backend::Apache> setup:
 PLP is yet another Perl embedder, primarily for HTML documents. Unlike with
 other Perl embedders, there is no need to learn a meta-syntax or object
 model: one can just use the normal Perl constructs. PLP runs under
-L<mod_perl|PLP::Backend::Apache> and L<FastCGI|PLP::Backend::FastCGI>
+L<FastCGI|PLP::Backend::FastCGI> and L<mod_perl|PLP::Backend::Apache>
 for speeds comparable to those of PHP, but can also be run as a standard
 L<CGI|PLP::Backend::CGI> script.
 
 =head2 Setup
 
-See either L<CGI|PLP::Backend::CGI>, L<FastCGI|PLP::Backend::FastCGI>
+See either
+L<CGI|PLP::Backend::CGI>,
+L<FastCGI|PLP::Backend::FastCGI> (recommended)
 or L<Apache|PLP::Backend::Apache>.
 At least the following servers are supported:
 
@@ -311,9 +313,9 @@ With L<mod_fastcgi|PLP::Backend::FastCGI> or L<mod_cgi|PLP::Backend::CGI>.
 
 =item Apache
 
-Either version 1 or 2.
-Using L<mod_perl|PLP::Backend::Apache>,
-L<mod_fastcgi, mod_fcgid|PLP::Backend::FastCGI>,
+Either version 1 or 2. Using
+L<mod_fcgid, mod_fastcgi|PLP::Backend::FastCGI>,
+L<mod_perl|PLP::Backend::Apache>,
 or L<mod_action|PLP::Backend::CGI>.
 
 =back
diff --git a/PLP/Backend/Apache.pm b/PLP/Backend/Apache.pm
index 89e32c6..eb13d36 100644
--- a/PLP/Backend/Apache.pm
+++ b/PLP/Backend/Apache.pm
@@ -92,33 +92,53 @@ Naturally, you'll need to enable I<mod_perl>:
 
     apache-modconf apache enable mod_perl
 
-Setup F<httpd.conf> (often just create a F</etc/apache2/conf.d/plp>) with:
+Setup F<httpd.conf> (in new installs just create F</etc/apache/conf.d/plp>) with:
 
     <IfModule mod_perl.c>
         <Files *.plp>
             SetHandler perl-script
             PerlHandler PLP::Backend::Apache
             PerlSendHeader On
-            PerlSetVar PLPcache On
         </Files>
     </IfModule>
 
 =head1 DESCRIPTION
 
-=head2 PerlSetVar configuration directives
+=head2 Configuration directives
+
+PLP behaviour can be configured by B<PerlSetVar> rules.
+These can be added to a F<.htaccess> file or most any scope of server
+configuration.  For example, to disable caching for a specific site:
+
+	<Directory /var/www/somesite/>
+		PerlSetVar PLPcache Off
+	</Directory>
 
 =over 16
 
 =item PLPcache
 
-Sets caching B<On>/B<Off>. When caching, PLP saves your script in memory and
-doesn't re-read and re-parse it if it hasn't changed. PLP will use more memory,
+Sets caching B<On>/B<Off>.
+When caching, PLP saves your script in memory and doesn't re-read
+and re-parse it if it hasn't changed. PLP will use more memory,
 but will also run 50% faster.
 
 B<On> is default, anything that isn't =~ /^off$/i is considered On.
 
 =back
 
+=head1 BUGS
+
+With mod_perlB<2>, any new request will change the cwd for all processes.
+This means that if you're running files from multiple directories,
+you I<should not use the current path> for it may change at any time.
+
+The bug has been confirmed with at least mod_perl 2.0.2/3/4 on Apache 2.2.3/8.
+Using this backend on Apache2 is extremely discouraged until this is fixed.
+Instead, L<the FastCGI backend|PLP::Backend::FastCGI> is recommended.
+
+Apache1 does not show any problems.
+
 =head1 AUTHOR
 
 Mischa POSLAWSKY <perl@shiar.org>
diff --git a/PLP/Backend/CGI.pm b/PLP/Backend/CGI.pm
index 7058b3e..1a4f49c 100644
--- a/PLP/Backend/CGI.pm
+++ b/PLP/Backend/CGI.pm
@@ -102,8 +102,8 @@ enable I<mod_cgi> (add/outcomment in server.modules), and add:
 
 =head2 Apache
 
-Enable I<mod_actions> and setup F<httpd.conf>
-(often just create a F</etc/apache2/conf.d/plp>) with:
+Enable I<mod_actions> and
+setup F<httpd.conf> (in new installs just create F</etc/apache/conf.d/plp>) with:
 
     <IfModule mod_actions.c>
         ScriptAlias /PLP_COMMON/ /foo/bar/
diff --git a/PLP/Backend/FastCGI.pm b/PLP/Backend/FastCGI.pm
index f83675a..85a5234 100644
--- a/PLP/Backend/FastCGI.pm
+++ b/PLP/Backend/FastCGI.pm
@@ -50,8 +50,8 @@ Example F</foo/bar/plp.fcgi>:
     #!/usr/bin/perl
     use PLP::Backend::FastCGI;
 
-Then enable either I<mod_fastcgi> or I<mod_fcgid>, and setup F<httpd.conf>
-(often just create a F</etc/apache2/conf.d/plp>) with:
+Then enable either I<mod_fcgid> (recommended) or I<mod_fastcgi>, and
+setup F<httpd.conf> (in new installs just create F</etc/apache/conf.d/plp>) with:
 
     <IfModule mod_fastcgi.c>
         AddHandler fastcgi-script plp
@@ -63,6 +63,30 @@ Then enable either I<mod_fastcgi> or I<mod_fcgid>, and setup F<httpd.conf>
         FCGIWrapper /foo/bar/plp.fcgi .plp
     </IfModule>
 
+=head1 DESCRIPTION
+
+This is usually the preferred backend, providing persistent processes
+for speeds comparable to L<mod_perl|PLP::Backend::Apache> and
+reliability closer to L<CGI|PLP::Backend::CGI>.
+
+Servers often feature auto-adjusting number of daemons, script timeouts,
+and occasional restarts.
+
+=head2 Configuration directives
+
+PLP behaviour can be configured by setting environment variables.
+
+=over 16
+
+=item PLP_CACHE
+
+Sets caching off if false (0 or empty), on otherwise (true or undefined).
+When caching, PLP saves your script in memory and doesn't re-read
+and re-parse it if it hasn't changed. PLP will use more memory,
+but will also run 50% faster.
+
+=back
+
 =head1 AUTHOR
 
 Mischa POSLAWSKY <perl@shiar.org>
-- 
2.30.0