stas 02/02/27 10:03:39
Modified: src config.cfg
src/docs/1.0/api Apache.pod
src/docs/1.0/faqs cgi_to_mod_perl.pod config.cfg
mod_perl.pod mod_perl_cgi.pod mod_perl_faq.pod
mod_perl_method_handlers.pod mod_perl_traps.pod
src/docs/1.0/guide advocacy.pod browserbugs.pod config.pod
control.pod correct_headers.pod databases.pod
dbm.pod debug.pod download.pod frequent.pod
hardware.pod help.pod install.pod intro.pod
modules.pod multiuser.pod performance.pod perl.pod
porting.pod scenario.pod security.pod snippets.pod
start.pod strategy.pod style.css
troubleshooting.pod
src/docs/1.0/win32 win32_binaries.pod win32_compile.pod
src/docs/2.0/api/mod_perl-2.0/APR PerlIO.pod
src/docs/2.0/api/mod_perl-2.0/Apache ServerUtil.pod
src/docs/2.0/devel/help help.pod
src/docs/2.0/devel/porting_from_1.x porting_from_1.x.pod
src/docs/2.0/devel/testing testing.pod
src/docs/2.0/user/compat compat.pod
src/docs/2.0/user/design design.pod
src/docs/2.0/user/install install.pod
src/maillist email-etiquette.pod list-advocacy.pod
list-announce.pod list-asp.pod list-cvs.pod
list-dev.pod list-docs-cvs.pod list-docs-dev.pod
list-embperl.pod list-test-cvs.pod
list-test-dev.pod list-users.pod maillist.tmpl
Removed: src/docs/1.0/faqs email-etiquette.pod
Log:
- loads of fixes for the internal linking implementation
Revision Changes Path
1.12 +13 -0 modperl-docs/src/config.cfg
Index: config.cfg
===================================================================
RCS file: /home/cvs/modperl-docs/src/config.cfg,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- config.cfg 4 Feb 2002 11:48:18 -0000 1.11
+++ config.cfg 27 Feb 2002 18:03:35 -0000 1.12
@@ -89,6 +89,19 @@
# location of the templates (searched left to right)
tmpl => [qw(tmpl/custom tmpl/std tmpl)],
+
+ # search path for pods, etc. must put more specific paths first!
+ search_path => [qw(
+ docs/2.0/api/mod_perl-2.0
+ docs/2.0/api/ModPerl-Registry
+ docs/2.0
+ docs/1.0/api
+ docs/1.0
+ .
+ )],
+ # what extensions to search for
+ search_exts => [qw(pod pm html)],
+
},
file => {
1.5 +3 -3 modperl-docs/src/docs/1.0/api/Apache.pod
Index: Apache.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/api/Apache.pod,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- Apache.pod 24 Jan 2002 14:54:25 -0000 1.4
+++ Apache.pod 27 Feb 2002 18:03:35 -0000 1.5
@@ -313,7 +313,7 @@
=item $c-E<gt>local_addr
A packed SOCKADDR_IN in the same format as returned by
-L<Socket/pack_sockaddr_in>, containing the port and address on the
+C<Socket::pack_sockaddr_in>, containing the port and address on the
local host that the remote client is connected to. This is set by
the server when the connection record is created so it is always
defined.
@@ -321,7 +321,7 @@
=item $c-E<gt>remote_addr
A packed SOCKADDR_IN in the same format as returned by
-L<Socket/pack_sockaddr_in>, containing the port and address on the
+C<Socket::pack_sockaddr_in>, containing the port and address on the
remote host that the server is connected to. This is set by the
server when the connection record is created so it is always defined.
@@ -432,7 +432,7 @@
Returns an array reference of hash references, containing information
related to the B<require> directive. This is normally used for access
-control, see L<Apache::AuthzAge> for an example.
+control, see C<Apache::AuthzAge> for an example.
=item $r-E<gt>auth_type
1.2 +2 -2 modperl-docs/src/docs/1.0/faqs/cgi_to_mod_perl.pod
Index: cgi_to_mod_perl.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/cgi_to_mod_perl.pod,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- cgi_to_mod_perl.pod 5 Jan 2002 19:20:01 -0000 1.1
+++ cgi_to_mod_perl.pod 27 Feb 2002 18:03:35 -0000 1.2
@@ -107,13 +107,13 @@
=item TRAPS
-See L<mod_perl_traps>.
+See L<common/known mod_perl traps|faqs::mod_perl_traps>.
=back
=head1 REPORTING PROBLEMS
-Read the L<SUPPORT> file.
+Read the I<SUPPORT> file.
=head1 SEE ALSO
1.3 +0 -1 modperl-docs/src/docs/1.0/faqs/config.cfg
Index: config.cfg
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/config.cfg,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- config.cfg 21 Feb 2002 08:53:50 -0000 1.2
+++ config.cfg 27 Feb 2002 18:03:35 -0000 1.3
@@ -18,7 +18,6 @@
mod_perl_api.pod
mod_perl_method_handlers.pod
perl_myth.pod
- email-etiquette.pod
),
],
copy_glob => [
1.2 +34 -28 modperl-docs/src/docs/1.0/faqs/mod_perl.pod
Index: mod_perl.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/mod_perl.pod,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- mod_perl.pod 5 Jan 2002 19:20:01 -0000 1.1
+++ mod_perl.pod 27 Feb 2002 18:03:35 -0000 1.2
@@ -43,14 +43,15 @@
See 'perldoc Apache' for info on how to use the Perl-Apache API.
-See the lib/ directory for example modules and L<apache-modlist.html>
-for a comprehensive list.
+See the I<lib/> directory for example modules and
+L<products::apache-modlist> for a comprehensive list.
See the eg/ directory for example scripts.
=head1 mod_perl
-For using mod_perl as a CGI replacement see the L<cgi_to_mod_perl> document.
+For using mod_perl as a CGI replacement see the L<First steps needed
+to use mod_perl as a CGI replacement|faqs::cgi_to_mod_perl> document.
You may load modules at server startup via:
@@ -225,10 +226,11 @@
as possible. The same is true under mod_perl. However, since
mod_perl normally only compiles scripts and modules once, in the
parent server or once per-child, C<BEGIN> blocks in that code will
-only be run once. As L<perlmod> explains, once a C<BEGIN> has run, it
-is immediately undefined. In the mod_perl environment, this means
-C<BEGIN> blocks will not be run during each incoming request unless
-that request happens to be one that is compiling the code.
+only be run once. As the I<perlmod> manpage explains, once a C<BEGIN>
+has run, it is immediately undefined. In the mod_perl environment,
+this means C<BEGIN> blocks will not be run during each incoming
+request unless that request happens to be one that is compiling the
+code.
Modules and files pulled in via require/use which contain C<BEGIN>
blocks will be executed:
@@ -248,10 +250,10 @@
=head1 END blocks
-As L<perlmod> explains, an C<END> subroutine is executed as late as
-possible, that is, when the interpreter is being exited. In the
-mod_perl environment, the interpreter does not exit until the server
-is shutdown. However, mod_perl does make a special case for
+As the I<perlmod> manpage explains, an C<END> subroutine is executed
+as late as possible, that is, when the interpreter is being exited.
+In the mod_perl environment, the interpreter does not exit until the
+server is shutdown. However, mod_perl does make a special case for
B<Apache::Registry> scripts.
Normally, C<END> blocks are executed by Perl during it's C<perl_run()>
@@ -305,8 +307,9 @@
AUTOLOADing. (Modules that you 'use' will be compiled when the server
starts unless they are inside an eval block.) httpd will grow just as
big as our /usr/bin/perl would, or a CGI process for that matter, it
-all depends on your setup. The L<mod_perl_tuning> document gives
-advice on how to best setup your mod_perl server environment.
+all depends on your setup. The L<mod_perl
+tuning|faqs::mod_perl_tuning> document gives advice on how to best
+setup your mod_perl server environment.
The mod_perl INSTALL document explains how to build the Apache::
extensions as shared libraries (with 'perl Makefile.PL DYNAMIC=1').
@@ -316,7 +319,8 @@
However, on most systems, this strategy will only make the httpd
I<look> smaller. When in fact, an httpd with Perl linked static with
take up less real memory and preform faster than shared libraries at
-the same time. See the L<mod_perl_tuning> document for details.
+the same time. See the L<mod_perl tuning|faqs::mod_perl_tuning>
+document for details.
=head2 MEMORY TIPS
@@ -388,20 +392,21 @@
=item Further Reading
-In case I forgot to mention, read Vivek Khera's L<mod_perl_tuning>
-document for more tips on improving Apache/mod_perl performance.
+In case I forgot to mention, read Vivek Khera's L<mod_perl
+tuning|faqs::mod_perl_tuning> document for more tips on improving
+Apache/mod_perl performance.
=back
=head1 SWITCHES
Normally when you run perl from the command line or have the shell
-invoke it with `#!', you may choose to pass perl switch arguments
-such as C<-w> or C<-T>. Since the command line is only parsed once,
-when the server starts, these switches are unavailable to mod_perl
-scripts. However, most command line arguments have a perl special
-variable equivilant. For example, the C<$^W> variable coresponds
-to the C<-w> switch. Consult L<perlvar> for more details. With
+invoke it with `#!', you may choose to pass perl switch arguments such
+as C<-w> or C<-T>. Since the command line is only parsed once, when
+the server starts, these switches are unavailable to mod_perl scripts.
+However, most command line arguments have a perl special variable
+equivilant. For example, the C<$^W> variable coresponds to the C<-w>
+switch. Consult the I<perlvar> manpage for more details. With
mod_perl it is also possible to turn on warnings globaly via the
B<PerlWarn> directive:
@@ -416,7 +421,8 @@
Now, any and all code compiled inside httpd will be checked.
The environment variable B<PERL5OPT> can be used to set additional
-perl startup flags such as B<-d> and B<-D>. See L<perlrun>.
+perl startup flags such as B<-d> and B<-D>. See the I<perlrun>
+manpage.
=head1 PERSISTENT DATABASE CONNECTIONS
@@ -607,7 +613,7 @@
=head1 PERL METHOD HANDLERS
-See L<mod_perl_method_handlers>.
+See L<How to use mod_perl's MethodHandlers|faqs::mod_perl_method_handlers>.
=head1 PERL SECTIONS
@@ -796,15 +802,15 @@
=head1 WARNINGS
-See L<mod_perl_traps>.
+See L<common/known mod_perl traps|faqs::mod_perl_traps>.
=head1 SUPPORT
-See the L<SUPPORT> file.
+See the I<SUPPORT> file.
=head1 Win32
-See L<INSTALL.win32> for building from sources.
+See I<INSTALL.win32> for building from sources.
Info about win32 binary distributions of mod_perl are available
from:
@@ -813,7 +819,7 @@
=head1 REVISION
-$Id: mod_perl.pod,v 1.1 2002/01/05 19:20:01 stas Exp $
+$Id: mod_perl.pod,v 1.2 2002/02/27 18:03:35 stas Exp $
=head1 AUTHOR
1.3 +1 -1 modperl-docs/src/docs/1.0/faqs/mod_perl_cgi.pod
Index: mod_perl_cgi.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/mod_perl_cgi.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- mod_perl_cgi.pod 22 Feb 2002 08:33:09 -0000 1.2
+++ mod_perl_cgi.pod 27 Feb 2002 18:03:35 -0000 1.3
@@ -112,7 +112,7 @@
do not need a run-time symbol table entry.
Beware, though, of referring to a lexical variable indirectly from within a
-subroutine. To quote L<perlsub/"Private Variables via my()">, the
+subroutine. To quote I<perlsub/"Private Variables via my()">, the
variable "... now becomes unreachable by the outside world, but retains
its value between calls to ..." the subroutine. You will see classic
"sticky query" symptoms if your code looks like this:
1.3 +5 -4 modperl-docs/src/docs/1.0/faqs/mod_perl_faq.pod
Index: mod_perl_faq.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/mod_perl_faq.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- mod_perl_faq.pod 22 Feb 2002 08:33:09 -0000 1.2
+++ mod_perl_faq.pod 27 Feb 2002 18:03:35 -0000 1.3
@@ -98,12 +98,13 @@
=head2 How do I run CGI scripts under mod_perl?
-Refer to L<mod_perl_cgi> for tips on writing and converting CGI
-scripts for mod_perl.
+Refer to the L<running CGI scripts under mod_perl|faqs::mod_perl_cgi>
+document for tips on writing and converting CGI scripts for mod_perl.
=head2 How do I access the Apache API from mod_perl?
-Interfacing with Apache is discussed in L<mod_perl_api>.
+Interfacing with Apache is discussed in L<accessing the Apache API via
+mod_perl|faqs::mod_perl_api>.
=head2 How secure are mod_perl scripts?
@@ -290,7 +291,7 @@
needed to be loaded when the server starts up. Put a PerlRequire
directive into one of the httpd config files that pulls in a small
module containing the relevant C<use>-statements. There is an example
-of this in L<mod_perl_tuning>.
+of this in L<mod_perl performance tuning|faqs::mod_perl_tuning>.
=head2 How can I pass arguments to a SSI script?
1.3 +5 -5
modperl-docs/src/docs/1.0/faqs/mod_perl_method_handlers.pod
Index: mod_perl_method_handlers.pod
===================================================================
RCS file:
/home/cvs/modperl-docs/src/docs/1.0/faqs/mod_perl_method_handlers.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- mod_perl_method_handlers.pod 5 Jan 2002 20:42:52 -0000 1.2
+++ mod_perl_method_handlers.pod 27 Feb 2002 18:03:35 -0000 1.3
@@ -7,8 +7,8 @@
Described here are a few examples and hints how to use MethodHandlers
with modperl.
-This document assumes familiarity with at least L<perltoot> and
-"normal" usage of the Perl*Handlers.
+This document assumes familiarity with at least the I<perltoot>
+manpage and "normal" usage of the Perl*Handlers.
It isn't strictly modperl related, more like "what I use objects for
in my modperl environment".
@@ -59,7 +59,7 @@
=head1 WHY?
The short version: For pretty much the same reasons we're using OO
-perl everywhere else. :-) See L<perltoot>.
+perl everywhere else. :-) See the I<perltoot> manpage.
The slightly longer version would include some about code reusage and
more clean interface between modules.
@@ -178,5 +178,5 @@
=head1 SEE ALSO
-L<mod_perl>, L<Apache>, L<perltoot> (also available at
-C<http://www.perl.com/CPAN/doc/FMTEYEWTK/perltoot.html>)
+The L<faqs::mod_perl>, the I<Apache>, the I<perltoot> manpages (also
+available at C<http://www.perl.com/CPAN/doc/FMTEYEWTK/perltoot.html>)
1.2 +7 -6 modperl-docs/src/docs/1.0/faqs/mod_perl_traps.pod
Index: mod_perl_traps.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/mod_perl_traps.pod,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- mod_perl_traps.pod 5 Jan 2002 19:20:01 -0000 1.1
+++ mod_perl_traps.pod 27 Feb 2002 18:03:35 -0000 1.2
@@ -25,7 +25,8 @@
=item *
-Be sure to have read L<cgi_to_mod_perl>
+Be sure to have read L<First steps needed to use mod_perl as a CGI
+replacement|faqs::cgi_to_mod_perl>.
=item *
@@ -124,11 +125,11 @@
compiled into a unique package name (base on the uri). So, if
multiple scripts in the same process try to require the same file,
which does not declare a package, only one script will actually be
-able to see the subroutines. The solution is to read L<perlmodlib>,
-L<perlmod> and related perl documentation and re-work your required
-file into a module which exports functions or defines a method
-interface.
-Or something more simple, along these lines:
+able to see the subroutines. The solution is to read the
+I<perlmodlib>, the I<perlmod> manpages and related perl documentation
+and re-work your required file into a module which exports functions
+or defines a method interface. Or something more simple, along these
+lines:
#required_file.pl
package Test;
1.2 +0 -2 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.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- advocacy.pod 6 Jan 2002 16:54:56 -0000 1.1
+++ advocacy.pod 27 Feb 2002 18:03:36 -0000 1.2
@@ -132,7 +132,5 @@
=back
-
-
=cut
1.3 +1 -4 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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- browserbugs.pod 4 Feb 2002 13:50:25 -0000 1.2
+++ browserbugs.pod 27 Feb 2002 18:03:36 -0000 1.3
@@ -19,7 +19,6 @@
with query strings. It is not a problem when the URL is the result
of submitting a form because the browsers I<have> to get that right.
-
=head1 IE 4.x does not re-post data to a non-port-80 URL
One problem with publishing 8080 port numbers (or so I have been
@@ -27,9 +26,7 @@
URL. It drops the port designator and uses port 80 anyway.
See L<Publishing Port Numbers other than
-80|config/Publishing_Port_Numbers_other_than_80>.
-
-
+80|guide::config/Publishing_Port_Numbers_other_than_80>.
=cut
1.3 +17 -193 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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- config.pod 29 Jan 2002 15:43:13 -0000 1.2
+++ config.pod 27 Feb 2002 18:03:36 -0000 1.3
@@ -2,7 +2,6 @@
mod_perl Configuration
-
=head1 Server Configuration
The next step after building and installing your new mod_perl enabled
@@ -28,8 +27,6 @@
convenience, you could still do everything in I<httpd.conf> if you
wished.
-
-
=head1 Apache Configuration
Apache configuration can be confusing. To minimize the number of
@@ -59,7 +56,6 @@
Now you can test the server, for example by accessing http://localhost
from a browser running on the same host.
-
=head2 Configuration Directives
For a basic setup there are just a few things to configure. If you
@@ -89,7 +85,6 @@
C<E<lt>LocationE<gt>> sections) which apply only to certain areas of your Web
space. As mentioned earlier you will find them all in I<httpd.conf>.
-
=head2 .htaccess files
If there is a file with the name I<.htaccess> in any directory, Apache
@@ -109,7 +104,6 @@
directive in I<httpd.conf>, Apache will not try to look for
I<.htaccess> at all.
-
=head2 E<lt>DirectoryE<gt>, E<lt>LocationE<gt> and E<lt>FilesE<gt> Sections
I'll explain just the basics of the C<E<lt>DirectoryE<gt>>,
C<E<lt>LocationE<gt>> and
@@ -155,7 +149,6 @@
it is not. It is not always obvious which directive takes precedence
in these cases. This can be a trap for the unwary.
-
=over
=item * E<lt>Directory directoryPathE<gt> ... E<lt>/DirectoryE<gt>
@@ -210,8 +203,6 @@
=back
-
-
=item * C<E<lt>Files filenameE<gt>> ... C<E<lt>/FilesE<gt>>
Can appear in server and virtual host configurations, and I<.htaccess>
@@ -286,12 +277,8 @@
allow from .example.com
</Location>
-
=back
-
-
-
=head2 How Directory, Location and Files Sections are Merged
When configuring the server, it's important to understand the order in
@@ -315,7 +302,6 @@
=back
-
Apart from C<E<lt>DirectoryE<gt>>, each group is processed in the
order that it appears in the configuration files.
C<E<lt>DirectoryE<gt>> (group 1 above) is processed in the order
@@ -332,9 +318,6 @@
Later sections override earlier ones.
-
-
-
=head2 Sub-Grouping of E<lt>LocationE<gt>, E<lt>DirectoryE<gt> and
E<lt>FilesE<gt> Sections
Let's say that you want all files, except for a few of the files in a
@@ -358,9 +341,6 @@
sections inside a C<E<lt>LocationE<gt>> section, but you can put them
inside a C<E<lt>DirectoryE<gt>> section.
-
-
-
=head2 Options Directive
Normally, if multiple C<Options> directives apply to a directory, then
@@ -394,9 +374,6 @@
then the options C<FollowSymLinks> and C<Includes> are set for the
I</home/httpd/docs/shtml> directory.
-
-
-
=head1 mod_perl Configuration
When you have tested that the Apache server works on your machine,
@@ -425,7 +402,6 @@
program can be executed (also at server startup time) simply by
mentioning its name in a C<PerlRequire> or C<PerlModule> directive.
-
=head2 Alias Configurations
The C<ScriptAlias> and C<Alias> directives provide a mapping of a URI
@@ -462,7 +438,7 @@
directive (for example C<PerlHandler>) tells mod_perl which handler
(Perl module) the script should be run under, and hence for which
phase of the request. Refer to the section
-L<Perl*Handlers|config/Perl_Handlers> for more information about
+L<Perl*Handlers|guide::config/Perl_Handlers> for more information about
handlers for the various request phases.
When you have decided which methods to use to run your scripts and
@@ -512,9 +488,7 @@
mod_cgi mode from a mod_perl-enabled server--the resource consumption
is too high. It is better to run these on a plain Apache server. See
L<Standalone mod_perl Enabled Apache
-Server|strategy/Standalone_mod_perl_Enabled_Apac>.
-
-
+Server|guide::strategy/Standalone_mod_perl_Enabled_Apac>.
=head2 E<lt>LocationE<gt> Configuration
@@ -618,7 +592,7 @@
Here is another very similar example, this time using
C<Apache::PerlRun> (For more information see
-L<Apache::PerlRun|porting/Apache__PerlRun__a_closer_look>):
+L<Apache::PerlRun|guide::porting/Apache__PerlRun__a_closer_look>):
<Location /cgi-perl>
SetHandler perl-script
@@ -628,12 +602,10 @@
PerlSendHeader On
</Location>
-
The only difference from the C<Apache::Registry> configuration is the
argument of the C<PerlHandler> directive, where C<Apache::Registry>
has been replaced with C<Apache::PerlRun>.
-
=head2 Overriding E<lt>LocationE<gt> Setting in "Sub-Location"
So if you have:
@@ -654,8 +626,6 @@
Now, all the requests starting with I</foo/bar> would be served by
Apache's default handler.
-
-
=head2 PerlModule and PerlRequire Directives
As we saw earlier, a module should be loaded before it is used.
@@ -681,11 +651,6 @@
C<require()>'d, it must return a I<true> value. To ensure that this
happens don't forget to add C<1;> at the end of I<startup.pl>.
-
-
-
-
-
=head2 Perl*Handlers
As you probably know Apache traverses a loop for each HTTP request it
@@ -716,7 +681,7 @@
I<Makefile.PL> file for its compilation, you must specify whether or
not you will want to handle parts of the request loop other than the
usual content generation phase. If so you need to specify which
-parts. See the "L<Callback Hooks|install/Callback_Hooks>" section for
+parts. See the "L<Callback Hooks|guide::install/Callback_Hooks>" section for
how to do this.
Apache specifies about eleven phases of the request loop, namely (and
@@ -766,7 +731,6 @@
PerlDispatchHandler
PerlRestartHandler
-
C<PerlChildInitHandler> and C<PerlChildExitHandler> do not refer to
parts of the request loop, they are to allow your modules to
initialize data structures and to clean up at the child process
@@ -800,10 +764,9 @@
The Apache documentation will tell you all about these stages and what
your modules can do. By default, most of these hooks are disabled at
-compile time, see the"L<Callback Hooks|install/Callback_Hooks>"
+compile time, see the"L<Callback Hooks|guide::install/Callback_Hooks>"
section for information on enabling them.
-
=head2 The handler subroutine
By default the mod_perl API expects a subroutine called C<handler()>
@@ -853,12 +816,6 @@
$r->warn("Logging request");
}
-
-
-
-
-
-
=head2 Stacked Handlers
With the mod_perl stacked handlers mechanism, during any stage of a
@@ -1016,17 +973,11 @@
% perl Makefile.PL PERL_STACKED_HANDLERS=1 [ ... ]
-
If you want to test whether your running mod_perl Apache can stack
handlers, the method C<Apache-E<gt>can_stack_handlers> will return
C<TRUE> if mod_perl was configured with C<PERL_STACKED_HANDLERS=1>,
and C<FALSE> otherwise.
-
-
-
-
-
=head2 Perl Method Handlers
If a C<Perl*Handler> is prototyped with C<$$>, this handler will be
@@ -1071,17 +1022,6 @@
% perl Makefile.PL PERL_METHOD_HANDLERS=1 [ ... ]
-
-
-
-
-
-
-
-
-
-
-
=head2 PerlFreshRestart
To reload C<PerlRequire>, C<PerlModule> and other C<use()>'d modules,
@@ -1091,7 +1031,7 @@
PerlFreshRestart On
Make sure you read L<Evil things might happen when using
-PerlFreshRestart|troubleshooting/Evil_things_might_happen_when_us>.
+PerlFreshRestart|guide::troubleshooting/Evil_things_might_happen_when_us>.
Starting from mod_perl version 1.22 C<PerlFreshRestart> is ignored
when mod_perl is compiled as a DSO. But it almost doesn't matter,
@@ -1105,9 +1045,6 @@
and mod_perl as a DSO you will still get a I<FreshRestart>.
-
-
-
=head2 PerlSetVar, PerlSetEnv and PerlPassEnv
PerlSetEnv key val
@@ -1120,7 +1057,7 @@
Regarding the setting of C<PerlPassEnv PERL5LIB> in I<httpd.conf>: if
you turn on taint checks (C<PerlTaintCheck On>), C<$ENV{PERL5LIB}>
will be ignored (unset). See the 'L<Switches -w,
--T|porting/Command_Line_Switches_w_T_e>' section.
+-T|guide::porting/Command_Line_Switches_w_T_e>' section.
C<PerlSetVar> is very similar to C<PerlSetEnv>, but you extract it
with another method.
@@ -1180,23 +1117,14 @@
C<$ENV{ORACLE_HOME}> (or another environment variable that you need in
these early request processing stages).
-
-
=head2 PerlSetupEnv
-See L<PerlSetupEnv Off|performance/PerlSetupEnv_Off>.
-
-
-
-
+See L<PerlSetupEnv Off|guide::performance/PerlSetupEnv_Off>.
=head2 PerlWarn and PerlTaintCheck
For B<PerlWarn> and B<PerlTaintCheck> directives see the 'L<Switches
--w, -T|porting/Command_Line_Switches_w_T_e>' section.
-
-
-
+-w, -T|guide::porting/Command_Line_Switches_w_T_e>' section.
=head2 MinSpareServers MaxSpareServers StartServers MaxClients
MaxRequestsPerChild
@@ -1216,13 +1144,9 @@
These five directives are very important for achieving the best
performance from your server. The section ' L<Performance Tuning by
Tweaking Apache
-Configuration|performance/Performance_Tuning_by_Tweaking_A>' provides
+Configuration|guide::performance/Performance_Tuning_by_Tweaking_A>' provides
all the details.
-
-
-
-
=head1 The Startup File
At server startup, before child processes are spawned to receive
@@ -1386,13 +1310,7 @@
But the old method is still available for backward compatibility.
See also the 'L<Apache::Status -- Embedded interpreter status
-information|debug/Apache_Status_Embedded_Inter>' section.
-
-
-
-
-
-
+information|guide::debug/Apache_Status_Embedded_Inter>' section.
=head2 What Modules You Should Add to the Startup File and Why
@@ -1402,21 +1320,17 @@
You can even preload your CGI script with C<Apache::RegistryLoader>
(See L<Preload Perl modules at server
-startup|performance/Preloading_Perl_Modules_at_Serve>) and you can get
+startup|guide::performance/Preloading_Perl_Modules_at_Serve>) and you can get
the children to preopen their database connections with
C<Apache::DBI>.
-
-
-
-
=head2 The Confusion with use() in the Server Startup File
Some people wonder why you need to duplicate the C<use()> clause in
the startup file and in the script itself. The confusion arises due to
misunderstanding the C<use()> function. C<use()> normally performs two
operations, namely C<require()> and C<import()>, called within a
-C<BEGIN> block. See the section "L<use()|perl/use__>" for a detailed
+C<BEGIN> block. See the section "L<use()|guide::perl/use__>" for a detailed
explanation of the use(), require() and import() functions.
In the startup file we don't want to import any symbols since they
@@ -1478,14 +1392,6 @@
Read the C<Exporter> and C<perlmod> manpages for more information
about C<import()>.
-
-
-
-
-
-
-
-
=head1 Apache Configuration in Perl
With C<E<lt>PerlE<gt>>...C<E<lt>/PerlE<gt>> sections, it is possible
@@ -1589,7 +1495,6 @@
}
</Perl>
-
Behind the scenes, mod_perl defines a package called
C<Apache::ReadConfig>. Here it keeps all the variables that you
define inside the C<E<lt>PerlE<gt>> sections. Therefore it's not
@@ -1619,15 +1524,11 @@
----------
PerlRequire /home/httpd/perl/lib/apache_config.pl
-
-
-
=head2 Enabling
To enable C<E<lt>PerlE<gt>> sections you should build mod_perl with
S<perl Makefile.PL PERL_SECTIONS=1 [ ... ]>.
-
=head2 Caveats
Be careful when you declare package names inside C<E<lt>PerlE<gt>>
@@ -1659,8 +1560,6 @@
$PerlTransHandler = "My::Trans";
</Perl>
-
-
=head2 Verifying
This section shows how to check and dump the configuration you have
@@ -1681,7 +1580,7 @@
In a running httpd you can see how you have configured the
C<E<lt>PerlE<gt>> sections through the URI
-L</perl-status|debug/Apache__Status____Embedded_Interpreter_Status_Information>,
by choosing I<Perl
+L</perl-status|guide::debug/Apache__Status____Embedded_Interpreter_Status_Information>,
by choosing I<Perl
Section Configuration> from the menu. In order to make this item show
up in the menu you should set C<$Apache::Server::SaveConfig> to a true
value. When you do that the I<Apache::ReadConfig> namespace (in which
@@ -1718,7 +1617,6 @@
You can then C<require()> that file in some other C<E<lt>PerlE<gt>>
section.
-
=head2 Strict C<E<lt>PerlE<gt>> Sections
If the Perl code doesn't compile, the server won't start. If the
@@ -1736,11 +1634,10 @@
and will C<croak> (die) if this is the case. At the time of writing the
default value is C<0>.
-
=head2 Debugging
If you compile mod_perl with C<PERL_TRACE=1> and set the environment
-variable L<MOD_PERL_TRACE|debug/Debug_Tracing> then you should see
+variable L<MOD_PERL_TRACE|guide::debug/Debug_Tracing> then you should see
some useful diagnostics when mod_perl is processing C<E<lt>PerlE<gt>>
sections.
@@ -1751,8 +1648,6 @@
META: a direct link?
-
-
=head1 Validating the Configuration Syntax
C<apachectl configtest> tests the configuration file without starting
@@ -1784,13 +1679,6 @@
return if Apache->define('syntax_check');
-
-
-
-
-
-
-
=head1 Enabling Remote Server Configuration Reports
The nifty mod_info module displays the complete server configuration
@@ -1809,9 +1697,6 @@
http://www.example.com/server-info
-
-
-
=head1 Publishing Port Numbers other than 80
If you are using a two-server setup, with a mod_perl server listening
@@ -1832,12 +1717,6 @@
closed, therefore users behind the firewalls will be unable to reach
your service, running on the blocked port.
-
-
-
-
-
-
=head1 Configuring Apache + mod_perl with mod_macro
mod_macro is an Apache module written by Fabien Coelho that lets you
@@ -1882,7 +1761,6 @@
# example
Use registry stuff stuff.pl
-
If you're using content handlers packaged as modules, you can use the
following macro:
@@ -1967,16 +1845,8 @@
reader. These can be easily constructed based on the examples
presented in this section.
-
-
-
-
-
=head1 General Pitfalls
-
-
-
=head2 My CGI/Perl Code Gets Returned as Plain Text Instead of Being
Executed by the Webserver
Check your configuration files and make sure that the C<ExecCGI> is
@@ -1990,41 +1860,23 @@
PerlSendHeader On
</Location>
-
-
-
-
-
=head2 My Script Works under mod_cgi, but when Called via mod_perl I Get a
'Save-As' Prompt
Did you put B<PerlSendHeader On> in the configuration part of the
C<E<lt>Location fooE<gt>E<lt>/LocationE<gt>>.
-
-
-
-
-
=head2 Is There a Way to Provide a Different startup.pl File for Each
Individual Virtual Host
No. Any virtual host will be able to see the routines from a I<startup.pl>
loaded for any other virtual host.
-
-
-
-
=head2 Is There a Way to Modify @INC on a Per-Virtual-Host or Per-Location
Basis.
You can use C<PerlSetEnv PERL5LIB ...> or a C<PerlFixupHandler> with
the C<lib> pragma (C<use lib qw(...)>).
A better way is to use
-L<Apache::PerlVINC|modules/Apache__PerlVINC___Allows_Module_Versioning_in_Location_blocks_and_Virtual_Hosts>
-
-
-
-
+L<Apache::PerlVINC|guide::modules/Apache__PerlVINC___Allows_Module_Versioning_in_Location_blocks_and_Virtual_Hosts>
=head2 A Script From One Virtual Host Calls a Script with the Same Path From
the Other Virtual Host
@@ -2044,12 +1896,6 @@
$Apache::Registry::NameWithVirtualHost = 0;
-
-
-
-
-
-
=head2 the Server no Longer Retrieves the DirectoryIndex Files for a
Directory
The problem was reported by users who declared mod_perl configuration
@@ -2123,10 +1969,6 @@
that last regex could be rewritten as C<^(/.+)$> and all would be
well.
-
-
-
-
=head1 Configuration Security Concerns
It is better not to advertise the port that mod_perl server uses to
@@ -2135,7 +1977,7 @@
on.
For more information see L<Publishing Port Numbers other than
-80|config/Publishing_Port_Numbers_other_th>.
+80|guide::config/Publishing_Port_Numbers_other_th>.
The more modules you have in your web server, the more complex the
code.
@@ -2179,12 +2021,6 @@
So as you see that a lot of information is revealed and a C<Full>
C<ServerTokens> has been used.
-
-
-
-
-
-
=head1 Apache Restarts Twice On Start
When the server is restarted, the configuration and module
@@ -2238,15 +2074,6 @@
8001. In the mod_perl server just check the C<PORT> variable to tell
if the connection is secure.
-
-
-
-
-
-
-
-
-
=head1 Adding Custom Configuration Directives
This is covered in the Eagle Book in a great detail. This is just a
@@ -2277,8 +2104,6 @@
'INC' => Apache::src->new->inc,
);
-
-
TestDirective.pm
----------------
package Apache::TestDirective;
@@ -2300,7 +2125,6 @@
1;
__END__
-
In the mod_perl source tree, add this to I<t/docs/startup.pl>:
1.3 +7 -65 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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- control.pod 4 Feb 2002 13:50:25 -0000 1.2
+++ control.pod 27 Feb 2002 18:03:36 -0000 1.3
@@ -28,7 +28,7 @@
children) processes. You are looking for the parent process. If you
run your server as root, you will easily locate it since it belongs to
root. If you run the server as some other user (when you L<don't have
-root access|install/Installation_Without_Superuser_P>, the processes
+root access|guide::install/Installation_Without_Superuser_P>, the processes
will belong to that user unless defined differently in I<httpd.conf>.
It's still easy to find which is the parent--usually it's the process
with the smallest PID.
@@ -52,7 +52,6 @@
be omitted and under some operating systems they will need to be preceded by
a minus sign, e.g. C<kill -15> or C<kill -TERM> followed by the PID.
-
=head1 Server Stopping and Restarting
We will concentrate here on the implications of sending C<TERM>,
@@ -99,7 +98,6 @@
happens when Perl code loaded in memory is not completely torn down,
leading to a memory leak.
-
=item USR1 Signal: Gracefully Restart Now
The C<USR1> signal causes the parent process to advise the children to
@@ -126,8 +124,7 @@
PerlFreshRestart On
Make sure you read L<Evil things might happen when using
-PerlFreshRestart|troubleshooting/Evil_things_might_happen_when_us>.
-
+PerlFreshRestart|guide::troubleshooting/Evil_things_might_happen_when_us>.
=head1 Speeding up the Apache Termination and Restart
@@ -161,9 +158,6 @@
lock on some resource are significant operations, but closing an
ordinary file isn't.
-
-
-
=head1 Using apachectl to Control the Server
The Apache distribution comes with a script to control the server.
@@ -204,11 +198,6 @@
delete the PID file by hand while the server is running, C<apachectl>
will be unable to stop or restart the server.
-
-
-
-
-
=head1 Safe Code Updates on a Live Production Server
You have prepared a new version of code, uploaded it into a production
@@ -304,9 +293,6 @@
Usually everything will be fine, and I have had only about 10 seconds
of downtime, which is pretty good!
-
-
-
=head1 An Intentional Disabling of Live Scripts
What happens if you really must take down the server or disable the
@@ -318,7 +304,7 @@
happened> message or perhaps a customized error message if you have
added code to trap and customize the errors. See L<Redirecting Errors
to the Client instead of to the
-error_log|snippets/Redirecting_Errors_to_the_Client> for the latter
+error_log|guide::snippets/Redirecting_Errors_to_the_Client> for the latter
case.
A much friendlier approach is to confess to your users that you are
@@ -423,14 +409,6 @@
If you need to disable a location handled by some module, the second
approach would work just as well.
-
-
-
-
-
-
-
-
=head1 SUID Start-up Scripts
If you want to allow a few people in your team to start and stop the
@@ -519,7 +497,6 @@
users to start the server as root user, the rest is exactly the same
as if you were executing the script as root in first place.
-
=head2 Sample Apache Startup SUID Script
Now if you are still with us, here is an example of the setuid Apache
@@ -581,11 +558,6 @@
die "Script must be named start_httpd, stop_httpd, or restart_httpd.\n";
-
-
-
-
-
=head1 Preparing for Machine Reboot
When you run your own development box, it's okay to start the
@@ -763,10 +735,6 @@
I</etc/rc.d/init.d> is what matters and not the name of the script the
link points to.
-
-
-
-
=head1 Monitoring the Server. A watchdog.
With mod_perl many things can happen to your server. It is possible
@@ -938,16 +906,12 @@
close MAIL;
}
-
-
-
-
=head1 Running a Server in Single Process Mode
Often while developing new code, you will want to run the server in
single process mode. See L<Sometimes it works Sometimes it does
-Not|porting/Sometimes_it_Works_Sometimes_it> and L<Names collisions
-with Modules and libs|porting/Name_collisions_with_Modules_and>.
+Not|guide::porting/Sometimes_it_Works_Sometimes_it> and L<Names collisions
+with Modules and libs|guide::porting/Name_collisions_with_Modules_and>.
Running in single process mode inhibits the server from "daemonizing",
and this allows you to run it under the control of a debugger more
easily.
@@ -978,12 +942,6 @@
forking any children, there is no controlling parent to write the
status messages.
-
-
-
-
-
-
=head1 Starting a Personal Server for Each Developer
If you are the only developer working on the specific server:port you
@@ -1130,12 +1088,8 @@
bypass the light server listening to the default port 80, and go
directly to the I<server:port> of the full URI.
-
-
-
=head1 Wrapper to Emulate the Server Perl Environment
-
Often you will start off debugging your script by running it from your
favorite shell program. Sometimes you encounter a very weird
situation when the script runs from the shell but dies when processed
@@ -1235,8 +1189,6 @@
# Note that we set Warning and Taint modes ON!!!
system qq{/usr/bin/perl -I$PERL5LIB -Tw $cgi $params};
-
-
=head1 Server Maintenance Chores
It's not enough to have your server and service up and running. You
@@ -1257,8 +1209,6 @@
aren't covered here, but at least you will be alerted that these
chores are real and should be taken care of.
-
-
=head2 Handling Log Files
There are two issues to solve with log files. First they should be
@@ -1422,8 +1372,6 @@
Can you spot the security holes? Take your time... This code
shouldn't be used in hostile situations.
-
-
=head3 Non-Scheduled Emergency Log Rotation
As we have mentioned before, there are times when the web server goes
@@ -1482,8 +1430,6 @@
will work very slowly if at all, and a normal watchdog should detect
this abnormal situation and restart the Apache server.
-
-
=head1 Swapping Prevention
Before I delve into swapping process details, let's refresh our
@@ -1621,7 +1567,7 @@
of possible processes will be small enough using the C<MaxClients>
directive (For the technique for choosing the right C<MaxClients>
refer to the section 'L<Choosing
-MaxClients|performance/Choosing_MaxClients>'). This will ensure that
+MaxClients|guide::performance/Choosing_MaxClients>'). This will ensure that
at peak hours the system won't swap. Remember that swap space is an
emergency pool, not a resource to be used routinely. If you are low
on memory and you badly need it, buy it or reduce the number of
@@ -1637,9 +1583,7 @@
For swapping monitoring techniques see the section 'L<Apache::VMonitor
-- Visual System and Apache Server
-Monitor|debug/Apache_VMonitor_Visual_Syste>'.
-
-
+Monitor|guide::debug/Apache_VMonitor_Visual_Syste>'.
=head1 Preventing mod_perl Processes From Going Wild
@@ -1666,10 +1610,8 @@
do the latter. Putting it in all your mod_perl modules would be
redundant (and might give you compile-time errors).
-
This will produce a nice error in I<error_log>, giving the line number
of the call and the name of the undefined subroutine.
-
=cut
1.3 +6 -14 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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- correct_headers.pod 4 Feb 2002 13:50:25 -0000 1.2
+++ correct_headers.pod 27 Feb 2002 18:03:36 -0000 1.3
@@ -37,16 +37,16 @@
If the number of hits is significant, you might want to consider what
cache-friendliness means (you may also want to read
-L<[4]|correct_headers/_4_>) and how you can cooperate with caches to
+L<[4]|guide::correct_headers/_4_>) and how you can cooperate with caches to
increase the performance of your site. Especially if you use Squid in
accelerator mode (helpful hints for Squid, see
-L<[1]|correct_headers/_1_>), you will have a strong motivation to
+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
-The HTTP standard (v 1.1 is specified in L<[3]|correct_headers/_3_>, v
-1.0 in L<[2]|correct_headers/_2_>) describes lots of headers. In this
+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
document, we only discuss those headers which are most relevant to
caching.
@@ -118,7 +118,7 @@
use Date::Parse;
# Date::Parse parses RCS format, Apache::Util::parsedate doesn't
$Mtime ||=
- Date::Parse::str2time(substr q$Date: 2002/02/04 13:50:25 $, 6);
+ Date::Parse::str2time(substr q$Date: 2002/02/27 18:03:36 $, 6);
$r->set_last_modified($Mtime);
=head2 2.1.3) Expires and Cache-Control
@@ -199,7 +199,6 @@
problem that remains is that there are broken browsers which ignore
C<Expires> headers.
-
=head2 2.2) Content Related Headers
=head2 2.2.1) Content-Type
@@ -215,7 +214,6 @@
is specified in the relevant C<DefaultType> configuration directive or
C<text/plain> if none is active.
-
=head2 2.2.2) Content-Length
According to section 14.13 of the HTTP specifications, the
@@ -385,7 +383,6 @@
workaround, you won't enjoy your Squid accelerator for these documents
:-(
-
=head1 3) Requests
Section 13.11 of the specifications states that the only two cacheable
@@ -506,7 +503,6 @@
http://example.com/query;BGCOLOR=blue;FGCOLOR=red;FONT=/font/bla
-
=head2 3.4) Conditional GET
A rather challenging request mod_perl programmers can get is the
@@ -530,7 +526,7 @@
value of this method is anything other than C<OK>, you should return
that value from your handler and you're done. Apache handles the rest
for you. The following example is taken from
-L<[5]|correct_headers/_5_>:
+L<[5]|guide::correct_headers/_5_>:
if((my $rc = $r->meets_conditions) != OK) {
return $rc;
@@ -570,7 +566,6 @@
would use the out of date C<finfo> when generating the response
header.
-
=head1 References
=head2 [1]
@@ -622,10 +617,7 @@
=item *
-
=back
-
-
=cut
1.3 +2 -19 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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- databases.pod 4 Feb 2002 13:50:25 -0000 1.2
+++ databases.pod 27 Feb 2002 18:03:36 -0000 1.3
@@ -34,7 +34,6 @@
It's almost as straightforward as is it sounds; there are just a few
things to know about and we will cover them in this section.
-
=head2 Introduction
The DBI module can make use of the C<Apache::DBI> module. When it
@@ -156,12 +155,11 @@
connection won't be closed either.
See the section L<Handling the 'User pressed Stop button'
-case|debug/Handling_the__User_pressed_Stop_button__case>
+case|guide::debug/Handling_the__User_pressed_Stop_button__case>
for more information on prevention.
=head2 Troubleshooting
-
=head3 The Morning Bug
The SQL server keeps a connection to the client open for a limited
@@ -204,7 +202,6 @@
it from the cache. So always initiate connections using the same
parameters and set C<LongReadLen> (or whatever) afterwards.
-
=head3 Cannot find the DBI handler
You must use C<DBI::connect()> as in normal DBI usage to get your $dbh
@@ -215,7 +212,6 @@
return your cached connection. Any C<disconnect()> call will be just
ignored.
-
=head3 Apache:DBI does not work
Make sure you have it installed.
@@ -236,7 +232,6 @@
and adapt the connect string. Do not change anything in your scripts
for use with C<Apache::DBI>.
-
=head3 Skipping connection cache during server startup
Does your error_log look like this?
@@ -258,8 +253,6 @@
You must use the C<Apache::DBI-E<gt>connect_on_init()> method in the
startup file.
-
-
=head3 Debugging code which deploys DBI
To log a trace of C<DBI> statement execution, you must set the
@@ -310,7 +303,6 @@
=back
-
=head1 mysql_use_result vs. mysql_store_result.
Since many mod_perl developers use mysql as their preferred SQL
@@ -344,7 +336,6 @@
This can tie up the server and prevent other threads from updating the
tables.
-
=head1 Optimize: Run Two SQL Engine Servers
Sometimes you end up running many databases on the same machine. These
@@ -358,10 +349,9 @@
performance needs.
This is basically a similar idea to having L<two Apache
-servers|strategy/One_Plain_Apache_and_One_mod_perl_enabled_Apache_Servers>,
+servers|guide::strategy/One_Plain_Apache_and_One_mod_perl_enabled_Apache_Servers>,
each optimized for its specific requirements.
-
=head1 Some useful code snippets to be used with relational Databases
In this section you will find scripts, modules and code snippets to
@@ -389,7 +379,6 @@
(Note that you will not find this on CPAN. at least not yet :)
-
=head2 My::DB Module's Usage Examples
To use C<My::DB> in your script, you first have to create a C<My::DB>
@@ -419,7 +408,6 @@
$total++;
}
-
Now let's count how many users we have (in table C<users>):
my $count = $db_obj->sql_count_matched("users");
@@ -449,7 +437,6 @@
return "Current status: Is Online and idle for $idle minutes.";
}
-
A complex query. I join two tables, and I want a reference to an array
which will store a slice of the matched query (C<LIMIT $offset,$hits>)
sorted by C<username>. Each row in the array is to include the fields
@@ -552,9 +539,5 @@
# Now %matched includes the usernames of the users who are being
# watched by $username and currently are online.
-
=cut
-
-
-
1.4 +3 -13 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.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- dbm.pod 4 Feb 2002 14:16:49 -0000 1.3
+++ dbm.pod 27 Feb 2002 18:03:36 -0000 1.4
@@ -2,8 +2,6 @@
mod_perl and dbm files
-
-
=head1 Where and Why to use dbm files
Some of the earliest databases implemented on Unix were dbm files, and
@@ -207,7 +205,7 @@
The result is a starving process, which will timeout the request, and
it will fail to update the DB. Ken Williams solved the above problem
-with his L<C<Tie::DB_Lock>|dbm/mod_perl_and_dbm> module, which is
+with his L<C<Tie::DB_Lock>|guide::dbm/mod_perl_and_dbm> module, which is
discussed in one of the following sections.
There are several locking wrappers for C<DB_File> in CPAN right now.
@@ -215,7 +213,6 @@
mind. It is therefore worth knowing the difference, so that you can
pick the right one for your application.
-
=head1 Flawed Locking Methods Which Must Not Be Used
I<Caution>: The suggested locking methods in the Camel book and
@@ -307,9 +304,6 @@
file before tie()-ing it, untie() it before releasing the lock, and
in the case of write to call sync() before untie()-ing it.
-
-
-
=head1 Locking Wrappers Overview
Here are some of the correctly working dbm locking wrappers on (three
@@ -326,7 +320,7 @@
wrapper in situations where reads may be very lengthy and therefore
write starvation problem may occur. On the other hand if you have big
dbm files, it may create a big load on the system if the updates are
-quite frequent. L<More information|dbm/mod_perl_and_dbm>.
+quite frequent. L<More information|guide::dbm/mod_perl_and_dbm>.
=item *
@@ -350,7 +344,7 @@
=item *
-L<C<DB_File::Lock2>|dbm/mod_perl_and_dbm> -- does the same thing as
+L<C<DB_File::Lock2>|guide::dbm/mod_perl_and_dbm> -- does the same thing as
C<DB_File::Lock>, but has a slightly different implementation. I
wrote it before David Harris released his C<DB_File::Lock> and I
didn't want to kill mine, so I'll keep it here for a while :).
@@ -368,7 +362,6 @@
=back
-
=head1 Tie::DB_Lock
C<Tie::DB_Lock> ties hashes to databases using shared and exclusive
@@ -391,9 +384,6 @@
copied, and puts the responsibility of copying the read-only file on
the writer, not the reader. It would need some care to make sure it
does not disturb readers when putting a new read-only copy into place.
-
-
-
=head1 DB_File::Lock2
1.3 +15 -238 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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- debug.pod 21 Feb 2002 09:08:38 -0000 1.2
+++ debug.pod 27 Feb 2002 18:03:36 -0000 1.3
@@ -2,7 +2,6 @@
Debugging mod_perl
-
=head1 Warning and Errors Explained
Let's talk first about things that bother most web (and non-web)
@@ -11,8 +10,6 @@
turning this obvious to the newbie programmer enemies into our best
friends.
-
-
=head2 Curing The "Internal Server Error"
You have just installed this new CGI script and when you try it out
@@ -234,14 +231,6 @@
Second problem solved!
-
-
-
-
-
-
-
-
=head2 Helping error_log to Help Us
It's a good idea to keep it open all the time in a dedicated terminal
@@ -281,10 +270,7 @@
of colored output for easier reading). You might need to ask your ISP
to install this script for general use. See L<Watching the error_log
file without telneting to the
-server|snippets/Watching_the_error_log_File_With> .
-
-
-
+server|guide::snippets/Watching_the_error_log_File_With> .
=head2 The Importance of Warnings
@@ -383,18 +369,6 @@
The C<diagnostics> pragma can shed more light on errors and warnings,
as you will see in a moment.
-
-
-
-
-
-
-
-
-
-
-
-
=head3 diagnostics pragma
This module extends the terse diagnostics normally emitted by both the
@@ -422,14 +396,7 @@
C<diagnostics> mode adds a large performance overhead in comparison
with just having warnings mode On. You can see the benchmark results
in the section 'L<Code Profiling
-Techniques|performance/Code_Profiling_Techniques>'.
-
-
-
-
-
-
-
+Techniques|guide::performance/Code_Profiling_Techniques>'.
=head1 Handling the 'User pressed Stop button' case
@@ -491,8 +458,6 @@
127.0.0.1 - - [09/Jan/2001:10:28:18 +0100]
"GET /perl/test.pl HTTP/1.0" 200 10 -
-
-
=head2 Detecting Aborted Connections
Let's use the knowledge we have acquired to trace the execution of the
@@ -660,7 +625,6 @@
reopen with the open() call, which first closes a file. Let's see
what problems we might encounter, and possible solutions for them.
-
=head3 Critical Section
First we want to make a little detour to discuss the I<"critical
@@ -854,7 +818,6 @@
creating a new array and copying lines from one array to another, we
append the file directly to the C<@lines> array.
-
=head3 Safe Resource Locking and Cleanup Code
Let's get back to the main issue of this section, which is safe
@@ -1103,14 +1066,10 @@
C<Apache::MyModule::cleanup()> performs the cleanup, obviously.
-
-
-
-
=head1 Handling Server Timeout Cases and Working with $SIG{ALRM}
A similar situation to L<Pressed Stop button
-disease|debug/Handling_the_User_pressed_Stop_> happens when the
+disease|guide::debug/Handling_the_User_pressed_Stop_> happens when the
browser times out the connection (is it about 2 minutes?). There are
cases when your script is about to perform a very long operation and
there is a chance that its duration will be longer than the client's
@@ -1131,19 +1090,12 @@
It was recently discovered that C<local $SIG{'ALRM'}> does not restore
the original underlying C handler. This was fixed in mod_perl 1.19_01
-(L<CVS version|download/mod_perl>). As a matter of fact none of the
+(L<CVS version|guide::download/mod_perl>). As a matter of fact none of the
C<local $SIG{FOO}> signals restores the original C handler - read
L<Debugging Signal Handlers
-($SIG{FOO})|debug/Debugging_Signal_Handlers_SIG_> for a debug
+($SIG{FOO})|guide::debug/Debugging_Signal_Handlers_SIG_> for a debug
technique and a possible workaround.
-
-
-
-
-
-
-
=head1 Looking inside the server
Your server is up and running, but something appears to be wrong. You
@@ -1188,7 +1140,7 @@
If you don't put C<Apache::Status> before C<Apache::DBI>, you won't
get the C<Apache::DBI> menu entry in the status. For more about
C<Apache::DBI> see L<Persistent DB
-Connections|performance/Persistent_DB_Connections>.
+Connections|guide::performance/Persistent_DB_Connections>.
=head3 Extended Configuration
@@ -1269,7 +1221,6 @@
There is more information about C<Apache::Status> in its manpage.
-
=head3 Usage
Assuming that your mod_perl server listens on port 81, fetch
@@ -1310,7 +1261,6 @@
child has not yet compiled the script you are asking for,
I</perl-status> will just show you the main menu.
-
=head2 mod_status
The Status module allows a server administrator to find out how well
@@ -1344,7 +1294,6 @@
the page http://localhost/status (as long as your server recognizes
localhost:).
-
The details given by mod_status are:
=over
@@ -1371,30 +1320,15 @@
=back
-
-
=head2 Apache::VMonitor -- Visual System and Apache Server Monitor
This module is covered in the section "L<Apache::*
-Modules|modules/Apache_VMonitor_Visual_Syste>"
-
-
-
-
-
-
-
+Modules|guide::modules/Apache_VMonitor_Visual_Syste>"
=head1 Sometimes My Script Works, Sometimes It Does Not
See L<Sometimes it Works Sometimes it does
-Not|porting/Sometimes_it_Works_Sometimes_it>
-
-
-
-
-
-
+Not|guide::porting/Sometimes_it_Works_Sometimes_it>
=head1 Code Debug
@@ -1449,14 +1383,10 @@
itself (mod_perl is written in C), that was in a deep slumber before
your code awakened it.
-
In the following sections we will go through in detail each of the
problems presented, thoroughly discuss them and present a few
techniques to solve them.
-
-
-
=head2 Locating and correcting Syntax Errors
While developing code we often make syntax mistakes, like forgetting
@@ -1560,12 +1490,6 @@
You are OK www.foo.com
-
-
-
-
-
-
=head2 Finding the Line Which Triggered the Error or Warning
Perl has no problem with the line numbers and file names for modules
@@ -1629,7 +1553,6 @@
use Carp ();
local $SIG{__WARN__} = \&Carp::cluck;
-
=head2 Using print() for Debugging
The universal debugging tool across nearly all platforms and
@@ -1791,8 +1714,6 @@
my ($day,$month,$year) = (localtime)[3..5];
$month++;
-
-
=head2 Using print() and Data::Dumper for Debugging
Sometimes you need to peek into complex data structures, and trying to
@@ -1828,7 +1749,6 @@
]
};
-
While writing this example I made a mistake and wrote C<qw(a b c d)>
instead of C<[qw(a b c d)]>. When I pretty-printed the contents of
C<$data> I immediately saw my mistake:
@@ -1854,7 +1774,6 @@
instead of print to have all the debug messages in the error_log,
which makes it even easier to debug your code.
-
=head2 The Importance of a Good Concise Coding Style
Don't strive for elegant, clever code. Try to develop a good coding
@@ -1964,7 +1883,6 @@
as fast as the first), but because there are more ways to put a bug in
the first version than there are in the last one.
-
=head2 Introduction to the Perl Debugger
As we saw earlier, it's I<almost> always possible to debug code with
@@ -2163,7 +2081,6 @@
print "$sym\n";
-
% perl -d test.pl
main::(test.pl:3): my $sym = Symbol::gensym();
@@ -2282,7 +2199,6 @@
return $retval;
}
-
We'll start by setting a few breakpoints and then we use the C<List>
command (C<L>) to display them:
@@ -2475,7 +2391,6 @@
return $retval;
}
-
There are only two arguments in the list, so stopping to look at each
one isn't too time consuming, but consider the debugging pace if we
had a large list of 100 or so entries. It is possible to customize
@@ -2586,16 +2501,10 @@
ptkdb is not part of the standard perl distribution; it
is available from CPAN: http://www.perl.com/CPAN/authors/id/A/AE/AEPAGE/
-
-
-
-
-
=head2 Non-Interactive Perl Debugging under mod_perl
-
To debug scripts running under mod_perl either use L<Apache::DB
-(interactive Perl debugging)|debug/Interactive_mod_perl_Debugging> or
+(interactive Perl debugging)|guide::debug/Interactive_mod_perl_Debugging> or
an older non-interactive method as described below.
The C<NonStop> debugger option enables you to get some decent debugging
@@ -2767,18 +2676,6 @@
debugger for various situations. Once you have a good strategy, bug
squashing can actually be quite a bit of fun!
-
-
-
-
-
-
-
-
-
-
-
-
=head2 ptkdb and Interactive mod_perl Debugging
As you saw earlier you can use the C<ptkdb> visual debugger to
@@ -2822,11 +2719,6 @@
Any Perl/Tk guru to assist???
-
-
-
-
-
=head2 Debugging when Server Crashes on Startup before Writing to Log File.
If your server crashes on startup, you need to start it under gdb and
@@ -2922,8 +2814,6 @@
#0 0x400da4e1 in __kill () from /lib/libc.so.6
-
-
=head1 Hanging Processes: Detection and Diagnostics
Sometimes a httpd process might hang in the middle of processing a
@@ -2934,9 +2824,6 @@
(detection), so we can reproduce the problem and after that to
discover why there is problem (diagnostics).
-
-
-
=head2 Hanging because of the OS Problem
Sometimes you can find a process hanging because of some kind of the
@@ -2956,8 +2843,6 @@
resource it was waiting on. It might point the way to what component
of the system was misbehaving if the problem occurred frequently.
-
-
=head2 An Example of Code that Might Hang a Process
Deadlock is the situation where, for example, two processes, say X and
@@ -3051,7 +2936,6 @@
}
close LOCK;
-
It's very easy to see I<WRITE> process starvation if you spawn a few
of the above scripts simultaneously. Start the first few as I<READ>
processes and then start one I<WRITE> process like this:
@@ -3091,10 +2975,6 @@
until the lock is gained. Only when a write to a client's broken
connection is attempted will Apache terminate the script.
-
-
-
-
=head2 Detecting hanging processes
It's not so easy to detect hanging processes. There is no way you can
@@ -3137,7 +3017,7 @@
But if you have fifty processes, it can be quite hard to spot such a
process. L<Apache::Watchdog::RunAway is a hanging processes monitor
-and terminator|modules/Apache_Watchdog_RunAway_Hang> that implements
+and terminator|guide::modules/Apache_Watchdog_RunAway_Hang> that implements
this feature and should be used to solve this kind of problem.
If you've got a real problem, and the processes hang one after the
@@ -3148,7 +3028,7 @@
resolve it and notify the administrator using a simple crontab
watchdog that requests some very light script periodically. (See
L<Monitoring the Server. A
-watchdog.|control/Monitoring_the_Server_A_watchdo>)
+watchdog.|guide::control/Monitoring_the_Server_A_watchdo>)
In the watchdog you set a timeout appropriate for your service, which
may be anything from a few seconds to a few minutes. If the server
@@ -3165,9 +3045,6 @@
more servers or more memory, or perhaps split your single machine
across a cluster of machines.
-
-
-
=head2 Determination of the reason
Given the process id (PID), there are three ways to find out where the
@@ -3196,7 +3073,6 @@
=back
-
=head3 Using the Perl Trace
To see where an httpd is "spinning", try adding this to your script or
@@ -3212,7 +3088,7 @@
other parts of the server.
We check the registered signal handlers with help of
-L<Apache::Status|debug/Apache__Status____Embedded_Interpreter_Status_Information>.
What we see at
+L<Apache::Status|guide::debug/Apache__Status____Embedded_Interpreter_Status_Information>.
What we see at
http://localhost/perl-status?sig is :
USR2 = \&MyStartUp::__ANON__
@@ -3265,9 +3141,6 @@
line 5 of the I</home/httpd/perl/debug/perl_trace.pl> script, and it
was called by the hanging_sub() routine defined at line 4.
-
-
-
=head3 Using the System Calls Trace
Depending on the operating system you should have one of the
@@ -3536,8 +3409,6 @@
META: add the note about using the 'curinfo' gdb macro to perform an
easy detecting of the hanging location.
-
-
=head1 Debugging Hanging processes (continued)
META: incomplete
@@ -3590,26 +3461,15 @@
to produce a Perl stacktrace.
-
-
-
=head2 Debugging core Dumping Code
-
-
$ perl -e dump
Abort(coredump)
-
META: should I move the C<Apache::StatINC> here? (I think not, since it
relates to other topics like reloading config files, but you should
mention it here with a pointer to it)
-
-
-
-
-
=head1 PERL_DEBUG=1 Build Option
Building mod_perl with C<PERL_DEBUG=1>:
@@ -3638,14 +3498,6 @@
=back
-
-
-
-
-
-
-
-
=head1 Apache::Debug
(META: to be written)
@@ -3664,21 +3516,6 @@
$SIG{__DIE__} = \&Carp::confess;
eval { Carp::confess("init") };
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
=head1 Debug Tracing
To enable mod_perl debug tracing, configure mod_perl with the
@@ -3735,14 +3572,6 @@
% setenv MOD_PERL_TRACE all
% httpd -X
-
-
-
-
-
-
-
-
=head1 gdb says there are no debugging symbols
During I<make install> Apache strips all the debugging symbols. To
@@ -3769,16 +3598,6 @@
I<Makefile.tmpl> do it directly in I<Makefile>). Alternatively you
rerun C<make> and copy the unstripped httpd binary away.
-
-
-
-
-
-
-
-
-
-
=head1 Debugging Signal Handlers ($SIG{FOO})
The current Perl implementation does not restore the original Apache C
@@ -3803,7 +3622,7 @@
C<Sys::Signal> module, which solves the problem:
C<Sys::Signal> - Set signal handlers with restoration of the existing
-C sighandler. Get it from L<CPAN|download/Perl>.
+C sighandler. Get it from L<CPAN|guide::download/Perl>.
The usage is simple. If the original code was:
@@ -3817,7 +3636,6 @@
};
die $@ if $@;
-
Now you would write:
use Sys::Signal ();
@@ -3839,12 +3657,6 @@
static char *sigsave[] = { "ALRM", NULL };
-
-
-
-
-
-
=head1 Code Profiling
(Meta: duplication??? I've started to write about profiling somewhere
@@ -3867,14 +3679,6 @@
See also: C<Apache::DProf>
-
-
-
-
-
-
-
-
=head1 Devel::Peek
Devel::Peek - A data debugging tool for the XS programmer
@@ -3933,12 +3737,6 @@
Note: Previously allocating a scalar in this
way saves reallocation in v5.005 but may not do so in other versions.
-
-
-
-
-
-
=head1 How can I find out if a mod_perl code has a memory leak
The C<Apache::Leak> module (derived from C<Devel::Leak>) should help
@@ -4002,13 +3800,6 @@
C<Apache::Status> includes a C<StatusLexInfo> option which can show
you the internals of your code.
-
-
-
-
-
-
-
=head1 Debugging your code in Single Server Mode
Running in httpd -X mode is good only for testing during the
@@ -4088,9 +3879,6 @@
any children, there is no controlling parent to write the status
messages.
-
-
-
=head1 Apache::DumpHeaders - Watch HTTP Transaction Via Headers
This module is used to watch an HTTP transaction, looking at client
@@ -4106,16 +3894,13 @@
For more information read the module's manpage.
-Download the module from L<CPAN|download/CPAN_Downloads>.
-
-
-
+Download the module from L<CPAN|guide::download/CPAN_Downloads>.
=head1 Apache::DebugInfo - Log Various Bits Of Per-Request Data
C<Apache::DebugInfo> offers the ability to monitor various bits of
per-request data. Its functionality is similar to
-L<Apache::DumpHeaders|debug/Debugging_mod_perl_>
+L<Apache::DumpHeaders|guide::debug/Debugging_mod_perl_>
while offering several additional features, including the ability to:
=over
@@ -4137,13 +3922,5 @@
=back
See the module's manpage for more details.
-
-
-
-
-
-
-
-
=cut
1.2 +0 -9 modperl-docs/src/docs/1.0/guide/download.pod
Index: download.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/download.pod,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- download.pod 6 Jan 2002 16:54:56 -0000 1.1
+++ download.pod 27 Feb 2002 18:03:36 -0000 1.2
@@ -30,7 +30,6 @@
C<Apache::DumpHeaders>, you can type:
http://search.cpan.org/search?dist=Apache-DumpHeaders .
-
=head1 Apache
Get the latest Apache webserver and documentation from
@@ -50,7 +49,6 @@
from http://perl.apache.org/snapshots/modperl/, all the mod_perl
related projects are available from http://perl.apache.org/snapshots/.
-
RPM: http://perl.apache.org/rpm/
Debian users will find Perl, Apache and mod_perl are available
@@ -82,7 +80,6 @@
http://www.cpan.org/authors/id/ABH/mod_proxy_add_forward.c, complete
with instructions on how to compile it and whatnot.
-
=head1 httperf -- webserver Benchmarking tool
http://www.hpl.hp.com/personal/David_Mosberger/httperf.html
@@ -100,7 +97,6 @@
should be available from the mod_backhand CVS tree:
http://www.backhand.org/mod_backhand/
-
=head1 High-Availability and Load Balancing Projects
=head2 mod_backhand -- Load Balancing for Apache
@@ -120,7 +116,6 @@
The homepage of mod_redundancy is http://www.ask-the-guru.com .
-
=head2 High-Availability Linux Project
You will find the definitive guide to load balancing techniques
@@ -155,8 +150,6 @@
ipnat. That may be a simple solution for a few specific load problem.
http://coombs.anu.edu.au/~avalon/ipf3.4beta3.tgz
-
-
=head1 Apache::Request
The package name is I<libapreq>.
@@ -180,7 +173,5 @@
http://home-of-linux.org/gnome/libgtop/
-
=cut
-
1.3 +3 -7 modperl-docs/src/docs/1.0/guide/frequent.pod
Index: frequent.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/frequent.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- frequent.pod 4 Feb 2002 13:50:25 -0000 1.2
+++ frequent.pod 27 Feb 2002 18:03:36 -0000 1.3
@@ -7,21 +7,17 @@
Some problems come up very often on the mailing list. If there is
some important problem that is being reported frequently on the list
which is not included below, even if it is found elsewhere in the Guide,
-please L<tell me|help/Contacting_me>.
-
+please L<tell me|guide::help/Contacting_me>.
=head1 my() scoped variable in nested subroutines
See the section "L<my() Scoped Variable in Nested
-Subroutines|perl/my___Scoped_Variable_in_Nested_Subroutines>".
-
-
+Subroutines|guide::perl/my___Scoped_Variable_in_Nested_Subroutines>".
=head1 Segfaults caused by PerlFreshRestart
See the section L<Evil things might happen when using
-PerlFreshRestart|troubleshooting/Evil_things_might_happen_when_using_PerlFreshRestart>
-
+PerlFreshRestart|guide::troubleshooting/Evil_things_might_happen_when_using_PerlFreshRestart>
=cut
1.2 +2 -16 modperl-docs/src/docs/1.0/guide/hardware.pod
Index: hardware.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/hardware.pod,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- hardware.pod 6 Jan 2002 16:54:56 -0000 1.1
+++ hardware.pod 27 Feb 2002 18:03:36 -0000 1.2
@@ -121,7 +121,6 @@
Also remember that the less money you spend on OS and Software, the
more you will be able to spend on faster and stronger hardware.
-
=head2 Discontinued Products
The OSs in this hazard group tend to be developed by a single company
@@ -167,7 +166,6 @@
can always have a go yourself, but do not under-estimate the amounts
of work involved. There are many, many man-years of work in an OS.
-
=head2 OS Releases
Actively developed OSs generally try to keep pace with the latest
@@ -185,13 +183,6 @@
almost the same functionality for much less money if you were to buy
an older model of the same product.
-
-
-
-
-
-
-
=head1 Choosing Hardware
Sometimes the most expensive machine is not the one which provides the
@@ -212,7 +203,6 @@
(or an upgrade) and keep your service running - the main server will
simply not dispatch the requests to the machine that was taken down.
-
=item *
Load balancing - users are given the name of one of your machines but
@@ -225,7 +215,7 @@
clustering too.
There are many load balancing techniques. (See L<High-Availability
-Linux Project|download/High_Availability_Linux_Project> for more info.)
+Linux Project|guide::download/High_Availability_Linux_Project> for more
info.)
=item *
@@ -283,7 +273,6 @@
Wisdom and prophecy, that's all it takes :)
-
=head3 Single Strong Machine vs Many Weaker Machines
Let's start with a claim that a four years old processor is still very
@@ -356,7 +345,6 @@
a busy internet site you always have some slow clients. This is a
difficult thing to simulate in benchmark testing, though.
-
=head2 I/O Performance
If your service is I/O bound (does a lot of read/write operations to
@@ -407,7 +395,7 @@
serve one. Now you can calculate how many server processes you need.
If you know the maximum size your servers can grow to, you know how
much memory you need. If your OS supports L<memory
-sharing|hardware/Sharing_Memory>, you can make best use of this
+sharing|guide::hardware/Sharing_Memory>, you can make best use of this
feature by preloading the modules and scripts at server startup, and
so you will need less memory than you have calculated.
@@ -483,6 +471,4 @@
hardware will likewise be forced to adapt as well.
=cut
-
-
1.3 +2 -90 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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- help.pod 4 Feb 2002 13:50:25 -0000 1.2
+++ help.pod 27 Feb 2002 18:03:36 -0000 1.3
@@ -17,19 +17,14 @@
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|help/Get_help_with_mod_perl>.
-
-
-
-
-
+For more information See L<Get helped with
mod_perl|guide::help/Get_help_with_mod_perl>.
=head1 Contacting me
Hi, I wrote this document to help people with mod_perl. It does not
mean that if you have any question regarding mod_perl, perl or
whatever you think I might know, you should send it directly to me.
-Please see the L<Get help with mod_perl|help/Get_help_with_mod_perl>
+Please see the L<Get help with mod_perl|guide::help/Get_help_with_mod_perl>
section and follow the guidelines described there.
However, you are welcome to submit corrections and suggestions
@@ -46,8 +41,6 @@
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!>
-
-
=head2 How to Report Problems
Always send these details:
@@ -145,7 +138,6 @@
% perl -V:archlibexp
-
=item Spinning Processes
The gdb attaching to the live process approach is helpful when
@@ -178,11 +170,6 @@
Finally send all these details to the modperl mailing list.
-
-
-
-
-
=head1 Get help with mod_perl
=over
@@ -216,7 +203,6 @@
1-56592-567-X, Order Number: 567X
746 pages, $34.95
-
=item * The mod_perl Developer's Cookbook
Home site: http://www.modperlcookbook.org
@@ -230,7 +216,6 @@
Price: $39.99
Pages: 600
-
=item * Managing and Programming mod_perl
http://www.modperlbook.com is the home site of the new mod_perl book,
@@ -252,8 +237,6 @@
See also Andrew's collection of reference card for Apache and other
programs: http://www.refcards.com.
-
-
=back
=item * mod_perl Guide
@@ -280,7 +263,6 @@
at http://perl.apache.org/dist/mod_perl_traps.html .
-
=item * Articles
=over
@@ -296,7 +278,6 @@
=back
-
=item * mod_perl mailing lists
=over
@@ -393,8 +374,6 @@
http://www.apachelabs.org/test-dev/
-
-
=item * The advocacy mailing list
The list for mod_perl advocacy issues, discussions about
@@ -406,7 +385,6 @@
The archive: http://www.mail-archive.com/[email protected]/.
-
=item * The modperl-cvs mailing list
The modperl developers list is the list where you can watch mod_perl
@@ -421,23 +399,10 @@
No archives available.
-
-
=back
-
=back
-
-
-
-
-
-
-
-
-
-
=head1 Get help with Perl
=over
@@ -525,20 +490,8 @@
List's archive is available at
http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/.
-
=back
-
-
-
-
-
-
-
-
-
-
-
=head1 Get help with Perl/CGI
=over
@@ -570,17 +523,8 @@
subscribe cgi-list
-
=back
-
-
-
-
-
-
-
-
=head1 Get help with Apache
=over
@@ -626,23 +570,12 @@
Installing and Securing the Apache Webserver with SSL
http://www.securityfocus.com/infocus/1356
-
=item * mod_throttle_access
mod_throttle_access is available at http://www.fremen.org/apache/
-
=back
-
-
-
-
-
-
-
-
-
=head1 Get help with DBI and SQL
=over
@@ -677,13 +610,6 @@
=back
-
-
-
-
-
-
-
=head1 Get help with Squid - Internet Object Cache
=over 4
@@ -706,15 +632,10 @@
=back
-
-
-
-
=head1 Get help with CVS -- Concurrent Version Control
=over
-
=item *
mod_perl repository specific doc: mod_perl_cvs.pod, located in the
@@ -751,10 +672,8 @@
Introduction to CVS
http://www.sourcegear.com/CVS/Docs/blandy
-
=back
-
=head1 Get help with Performance and Scalability
=over
@@ -783,8 +702,6 @@
=back
-
-
=head1 Get help with Unix OS flavors -- Unix OS related resources
=over
@@ -796,11 +713,6 @@
=item *
-
=back
-
-
-
-
=cut
1.4 +11 -235 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.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- install.pod 5 Feb 2002 02:51:36 -0000 1.3
+++ install.pod 27 Feb 2002 18:03:36 -0000 1.4
@@ -204,8 +204,6 @@
describing different installation passes, once the overview of the
four building steps is completed.
-
-
=head3 Configuration parameters
The command C<perl Makefile.PL>, which is also known as a
@@ -281,8 +279,6 @@
mod_perl will be installed. Note that, C<make test> won't work until
you have built the server.
-
-
=head4 Callback Hooks
A callback hook (abbrev. I<callback>) is a reference to a
@@ -331,21 +327,15 @@
ALL_HOOKS=1
-
=head4 EVERYTHING
To enable everything set:
EVERYTHING=1
-
-
=head4 PERL_TRACE
-To enable L<debug tracing|debug/Debug_Tracing> set: C<PERL_TRACE=1>
-
-
-
+To enable L<debug tracing|guide::debug/Debug_Tracing> set: C<PERL_TRACE=1>
=head4 APACHE_HEADER_INSTALL
@@ -360,8 +350,6 @@
APACHE_HEADER_INSTALL=0
-
-
=head4 PERL_STATIC_EXTS
Normally, if an extension is statically linked with Perl it is listed in
@@ -373,7 +361,6 @@
perl Makefile.PL "PERL_STATIC_EXTS=Something::Static Another::One"
-
=head4 APACI_ARGS
When you use the C<USE_APACI=1> parameter, you can tell C<Makefile.PL>
@@ -396,8 +383,6 @@
stripping the backslashes. This causes all the arguments except the
first to be ignored by the configuration process.
-
-
=head4 APACHE_PREFIX
Alternatively to:
@@ -438,7 +423,6 @@
in the I<httpd.conf> used for S<'make test'> stage. (Introduced in
mod_perl v1.23.)
-
=head3 Reusing Configuration Parameters
When you have to upgrade the server, it's quite hard to remember what
@@ -492,13 +476,6 @@
C<apache_x.x.x/config.status> and the mod_perl parameters in
C<mod_perl_x.xx/apaci/mod_perl.config>.
-
-
-
-
-
-
-
=head3 Discovering Whether Some Option Was Configured
mod_perl version 1.25 has introduced C<Apache::Myconfig>, which
@@ -545,7 +522,6 @@
use the feature in question. If it wasn't configured Apache will give
an error message
-
=head3 Using an Alternative Configuration File
By default mod_perl provides its own copy of the I<Configuration> file
@@ -557,10 +533,8 @@
Where I<Configuration.custom> is the pathname of the file I<relative
to the Apache source tree you build against>.
-
=head3 perl Makefile.PL Troubleshooting
-
=head4 "A test compilation with your Makefile configuration failed..."
When you see this during the C<perl Makefile.PL> stage:
@@ -582,7 +556,7 @@
installed.
The most frequent pitfall is a missing gdbm library. See L<Missing or
-Misconfigured libgdbm.so|install/Missing_or_Misconfigured_libgdbm_so>
+Misconfigured libgdbm.so|guide::install/Missing_or_Misconfigured_libgdbm_so>
for more info.
But why guess, when we can actually see the real error message and
@@ -598,9 +572,6 @@
and try again. Now you should get a useful error message.
-
-
-
=head4 Missing or Misconfigured libgdbm.so
On some Linux RedHat systems you might encounter a problem during the
@@ -654,7 +625,6 @@
numbers. We didn't use the usual I<xx.xx> version replacement here, to
make it easier to understand how the symbolic links should be set.
-
=head4 About gdbm, db and ndbm libraries
Both the gdbm and db libraries offer ndbm emulation, which is the
@@ -667,8 +637,6 @@
have trouble copying the dbm file from one system to another or even
using it after an upgrade.
-
-
=head4 Undefined reference to `PL_perl_destruct_level'
When manually building mod_perl using the shared library:
@@ -703,7 +671,6 @@
shared I<libperl.a>. Build a dynamically linked Perl (with
I<libperl.a>) and the problem will disappear.
-
=head2 mod_perl Building (make)
After completing the configuration you build the server, by calling:
@@ -718,11 +685,8 @@
Note: don't put the mod_perl directory inside the Apache
directory. This confuses the build process.
-
-
=head3 make Troubleshooting
-
=head4 Undefined reference to 'Perl_newAV'
This and similar error messages may show up during the C<make>
@@ -732,7 +696,6 @@
another properly built binary package. Run C<perl -V> to learn what
version of Perl you are using and other important details.
-
=head4 Unrecognized format specifier for...
This error usually reported due to the problems with some versions of
@@ -740,7 +703,6 @@
problem. Or if you don't really need SFIO, rebuild Perl without this
library.
-
=head2 Built Server Testing (make test)
After building the server, it's a good idea to test it thoroughly, by
@@ -784,8 +746,6 @@
I</dev/null>) so you'll have to change these by hand. The tests are
run with the C<SSLDisable> directive.
-
-
=head3 Manual Testing
Tests are invoked by running the C<./TEST> script located in the
@@ -802,7 +762,6 @@
for some reason it fails to start, use C<make start_httpd> to start it
manually.
-
=head3 make test Troubleshooting
=head4 make test fails
@@ -833,7 +792,6 @@
instead.
-
=head4 make test......skipping test on this platform
While doing C<make test> you will notice that some of the tests are
@@ -878,11 +836,6 @@
Also make sure that you have the loopback device [lo] configured.
[Hint: try 'ifconfig lo' to test for its existence.]
-
-
-
-
-
=head2 Installation (make install)
After testing the server, the last step left is to install it. First
@@ -899,10 +852,6 @@
Now the installation should be considered complete. You may now
configure your server and start using it.
-
-
-
-
=head2 Building Apache and mod_perl by Hand
If you wish to build httpd separately from mod_perl, you should use
@@ -933,7 +882,7 @@
AddModule modules/perl/libperl.a
We suggest you add this entry at the end of the I<Configuration> file
-if you want your L<callback hooks|install/Callback_Hooks> to have
+if you want your L<callback hooks|guide::install/Callback_Hooks> to have
precedence over core handlers.
Add the following to C<EXTRA_LIBS>:
@@ -973,19 +922,11 @@
% make
% make install
-
-
-
-
-
=head1 Installation Scenarios for Standalone mod_perl
There are various ways available to build Apache with the new hybrid
build environment (using C<USE_APACI=1>):
-
-
-
=head2 The All-In-One Way
If your goal is just to build and install Apache with mod_perl out of
@@ -1005,10 +946,6 @@
default C</usr/local/apache> tree and mod_perl into the C<site_perl>
hierarchy of your existing Perl installation. All in one step.
-
-
-
-
=head2 The Flexible Way
This is the normal situation where you want to be flexible while
@@ -1172,8 +1109,6 @@
dynamically load and insert mod_perl into httpd) are automatically
added to I<httpd.conf>.
-
-
=head2 Build mod_perl as a DSO outside the Apache Source Tree via APXS
Above we've seen how to build mod_perl as a DSO I<inside> the Apache
@@ -1199,13 +1134,6 @@
tree with the new Apache 1.3 support tool C<apxs> and install it into
the existing Apache hierarchy.
-
-
-
-
-
-
-
=head1 Installation Scenarios for mod_perl and Other Components
([ReaderMETA]: Please send more scenarios of mod_perl + other
@@ -1267,8 +1195,6 @@
default location. When you run C<make install> the installation
program tells you where it's going to install the files.
-
-
=head2 mod_perl and mod_ssl (+openssl)
mod_ssl provides strong cryptography for the Apache 1.3 webserver via
@@ -1327,8 +1253,6 @@
mod_perl/1.21_01-dev mod_ssl/2.4.8 OpenSSL/0.9.4 configured
-- resuming normal operations
-
-
=head2 mod_perl and mod_ssl Rolled from RPMs
As in the previous section this shows an installation of mod_perl and
@@ -1464,9 +1388,6 @@
% httpd -DSSL
-
-
-
=head2 mod_perl and apache-ssl (+openssl)
Apache-SSL is a secure Webserver, based on Apache and SSLeay/OpenSSL.
@@ -1521,11 +1442,6 @@
Now proceed with configuration of the apache_ssl and mod_perl parts of
the server configuration files, before starting the server.
-
-
-
-
-
=head2 mod_perl and Stronghold
Stronghold is a secure SSL Web server for Unix which allows you to
@@ -1578,13 +1494,6 @@
Rule WANTHSREGEX=no
-
-
-
-
-
-
-
=head2 mod_perl and mod_php
This is a simple installation scenario of the mod_perl and mod_php in
@@ -1776,14 +1685,6 @@
and after answering a few questions, go out for a coffee.
-
-
-
-
-
-
-
-
=head1 Installing on multiple machines
You may wish to build httpd once, then copy it to other machines. The
@@ -1834,24 +1735,11 @@
([ReaderMETA]: Dear reader, Can you please share a step by step scenario of
preparation of SRPMs for mod_perl? Thanks!!!)
-
-
-
-
-
-
-
-
-
-
-
=head1 using RPM and other packages to install mod_perl
[ReaderMETA]: Currently only RPM package. Please submit info about
other available packages if you use such.
-
-
=head2 A word on mod_perl RPM packages
The virtues of RPM packages is a subject of much debate among mod_perl
@@ -1908,7 +1796,6 @@
mod_perl RPM (or vice versa). Sticking with one format or the other
at first will result in fewer headaches and more hair.
-
=head2 Installing a single apache+mod_perl RPM
If you use an Apache+mod_perl RPM, chances are C<rpm -i> or C<glint>
@@ -1986,16 +1873,9 @@
/usr/sbin/modperl-enable off
-
-
-
-
-
-
-
=head2 Compiling libapreq (Apache::Request) with the RH 6.0 mod_perl RPM
-Libapreq provides the L<Apache::Request|download/Apache__Request>
+Libapreq provides the L<Apache::Request|guide::download/Apache__Request>
module.
Despite many reports of libapreq not working properly with various RPM
@@ -2099,7 +1979,6 @@
Apply this patch to libapreq:
http://www.davideous.com/modperlrpm/distrib/libapreq-0.31_include.patch
-
=item 4
Follow the libapreq directions as usual:
@@ -2109,7 +1988,6 @@
=back
-
=head2 Installing separate Apache and mod_perl RPMs
If you are trying to install separate Apache and mod_perl RPMs, like
@@ -2118,7 +1996,7 @@
http://localhost will bring up some type of web page for you.
However, after installation of the mod_perl RPM, the L<How can I tell
whether mod_perl is
-running|install/How_can_I_tell_whether_mod_perl_is_running_> test will
+running|guide::install/How_can_I_tell_whether_mod_perl_is_running_> test will
show that Apache is not mod_perl enabled. This is because mod_perl
needs to be added as a separate module using Apache's Dynamic Shared
Objects.
@@ -2126,7 +2004,6 @@
To use mod_perl as a DSO, make the following modifications to your
Apache configuration files:
-
httpd.conf:
----------
LoadModule perl_module modules/libperl.so
@@ -2144,19 +2021,11 @@
After a complete shutdown and startup of the server, mod_perl should
be up and running.
-
-
-
-
-
-
-
-
=head2 Testing the mod_perl API
Some people have reported that even when the server responds
positively to the L<How can I tell whether mod_perl is
-running|install/How_can_I_tell_whether_mod_perl_is_running_> tests,
+running|guide::install/How_can_I_tell_whether_mod_perl_is_running_> tests,
the mod_perl API will not function properly. You may want to run the
following script to verify the availability of the mod_perl API.
@@ -2165,9 +2034,6 @@
$r->send_http_header('text/html');
$r->print("It worked!!!\n");
-
-
-
=head1 Installation Without Superuser Privileges
As you have already learned, mod_perl enabled Apache consists of two
@@ -2177,7 +2043,6 @@
I'll show a complete installation example using I<stas> as a username,
assuming that I</home/stas> is the home directory of that user.
-
=head2 Installing Perl Modules into a Directory of Choice
Since without superuser permissions you aren't allowed to install
@@ -2241,7 +2106,6 @@
Writing /home/stas/lib/perl5/auto/CGI/.packlist
Appending installation info to /home/stas/lib/perl5/perllocal.pod
-
If you have to use the explicit target parameters, instead of a single
C<PREFIX> parameter, you will find it useful to create a file called
for example I<~/.perl_dirs> (where I<~> is C</home/stas> in our
@@ -2273,18 +2137,6 @@
% perl Makefile.PL `cat ~/.perl_dirs.develop`
-
-
-
-
-
-
-
-
-
-
-
-
=head2 Making Your Scripts Find the Locally Installed Modules
Perl modules are generally placed in four main directories. To find
@@ -2461,17 +2313,6 @@
variable and the explicit C<@INC> extension code at the beginning of
the scripts as described above.
-
-
-
-
-
-
-
-
-
-
-
=head2 The CPAN.pm Shell and Locally Installed Modules
As we saw in the section describing the usage of the C<CPAN.pm> shell
@@ -2565,19 +2406,6 @@
If you arrange all the above parameters in one line, you can remove
the backslashes (C<\>).
-
-
-
-
-
-
-
-
-
-
-
-
-
=head2 Making a Local Apache Installation
Just like with Perl modules, if you don't have permissions to install
@@ -2627,17 +2455,6 @@
group you belong to. You must set the C<User> and C<Group> directives
in I<httpd.conf> to appropriate values.
-
-
-
-
-
-
-
-
-
-
-
=head2 Manual Local mod_perl Enabled Apache Installation
Now when we have learned how to install local Apache and Perl modules
@@ -2705,8 +2522,7 @@
performs script compilation. As a result, C<@INC> will be reset to its
original value after the scripts are compiled and the hard-coded
settings will be forgotten. See the section 'L<@INC and
-mod_perl|porting/_INC_and_mod_perl>' for more information.
-
+mod_perl|guide::porting/_INC_and_mod_perl>' for more information.
The only place you can alter the "original" value is during the server
configuration stage either in the startup file or by putting
@@ -2734,7 +2550,7 @@
=item *
Reduce resources usage (see L<Limiting the size of the
-processes|performance/Limiting_the_Size_of_the_Processes>).
+processes|guide::performance/Limiting_the_Size_of_the_Processes>).
=item *
@@ -2756,16 +2572,6 @@
=back
-
-
-
-
-
-
-
-
-
-
=head2 Local mod_perl Enabled Apache Installation with CPAN.pm
Again, CPAN makes installation and upgrades simpler. You have seen
@@ -2827,7 +2633,6 @@
cpan> o conf makepl_arg.save PREFIX=/home/stas
-
Second, set a new value, to be used by the mod_perl installation
process. (You can add parameters to this line, or remove them,
according to your needs.)
@@ -2853,10 +2658,6 @@
on a piece of paper instead of saving it to C<makepl_arg.save>, but
you are more likely to make a mistake that way.
-
-
-
-
=head1 Automating installation
=over
@@ -2882,15 +2683,6 @@
=back
-
-
-
-
-
-
-
-
-
=head1 How can I tell whether mod_perl is running?
There are a few ways. In older versions of apache ( < 1.3.6 ?) you
@@ -2899,7 +2691,6 @@
it installed, you have to configure it for mod_perl and restart the
server too.
-
=head2 Checking the error_log
When starting the server, just check the C<error_log> file for the
@@ -2952,7 +2743,7 @@
However, just because you have got mod_perl linked in there, that does
not mean that you have configured your server to handle Perl scripts
with mod_perl. You will find configuration assistance at
-L<ModPerlConfiguration|config/>
+L<ModPerlConfiguration|guide::config/>
=head2 Testing via a CGI script
@@ -3025,9 +2816,9 @@
takes care of overriding the C<exit()> call for you, so it's not an
issue. For reasons and implementations see: L<Terminating requests
and processes, exit()
-function|porting/Terminating_requests_and_processes__the_exit___and_child_terminate___functions>
+function|guide::porting/Terminating_requests_and_processes__the_exit___and_child_terminate___functions>
and also L<Writing Mod Perl scripts and Porting plain CGIs to
-it|porting/>.
+it|guide::porting/>.
=head2 Testing via lwp-request
@@ -3072,7 +2863,6 @@
C<@INC> in the startup script, but it is better to build afresh to
save you getting into a mess.
-
=head2 Perl installation requirements
Make sure you have Perl installed! The latest stable version if
@@ -3085,8 +2875,6 @@
Do you wish to use dynamic loading? [y]
-
-
=head2 mod_auth_dbm nuances
If you are a C<mod_auth_dbm> or C<mod_auth_db> user you may need to
@@ -3128,8 +2916,6 @@
Rebuild libgdbm before Apache/mod_perl.
-
-
=head2 Stripping Apache to make it almost a Perl-server
Since most of the functionality that various apache mod_* modules
@@ -3140,7 +2926,6 @@
Perl-server, with C code to handle the tricky HTTP bits. The only
module you will need to leave in is C<mod_actions>.
-
=head2 Saving the config.status Files with mod_perl, php, ssl and Other
Components
Typically, when building the bloated Apache that sits behind Squid or
@@ -3179,9 +2964,6 @@
Hint: Take a look at the I<Config.pm> module or the output of C<perl
-V>.
-
-
-
=head1 OS Related Notes
=over 3
@@ -3206,9 +2988,6 @@
=back
-
-
-
=head1 Pros and Cons of Building mod_perl as DSO
On modern Unix derivatives there is a nifty mechanism usually called
@@ -3254,7 +3033,6 @@
-i> command followed by an S<apachectl restart> to bring a new version
of your currently developed module into the running Apache server.
-
=back
Cons:
@@ -3307,8 +3085,6 @@
Configuration file or on the configure command line.
=back
-
-
=cut
1.4 +3 -6 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.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- intro.pod 4 Feb 2002 14:16:49 -0000 1.3
+++ intro.pod 27 Feb 2002 18:03:36 -0000 1.4
@@ -43,7 +43,6 @@
http://perl.apache.org/tidbits.html and
http://perl.apache.org/stories/ for the facts.)
-
=head2 mod_cgi
When you run your CGI scripts by using a configuration like this:
@@ -168,13 +167,13 @@
writing and porting existing Perl scripts to run under mod_perl. Note
that it does not attempt to enter the big world of using the Perl API
or C API. You will find pointers to coverage of these topics in the
-L<Getting Help and Further Learning|help/> section of this
+L<Getting Help and Further Learning|guide::help/> section of this
document. This guide tries to cover the most of the
C<Apache::Registry> and C<Apache::PerlRun> modules. Along with
mod_perl related topics, there are many more issues related to
administering Apache servers, debugging scripts, using databases,
mod_perl related Perl, code snippets and more. The L<Guide's
-Overview|start/> will help you to find your way through the guide.
+Overview|guide::start/> will help you to find your way through the guide.
It is assumed that you know at least the basics of building and
installing Perl and Apache. (If you do not, just read the INSTALL documents
@@ -184,7 +183,7 @@
mod_perl installation and get the server running in a short time.
If after reading this guide and the other documents listed in
-L<Getting Help and Further Learning|help/> you feel that your
+L<Getting Help and Further Learning|guide::help/> you feel that your
questions remain unanswered, you could try asking the apache/mod_perl
mailing list to help you. But first try to browse the mailing list
archive (located at http://mathforum.org/epigone/modperl ). Often you
@@ -339,9 +338,7 @@
Apache/1.3.9 (Unix) mod_perl/1.16
-
=back
-
=head1 References and Acknowledgments
1.2 +8 -66 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.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- modules.pod 6 Jan 2002 16:54:56 -0000 1.1
+++ modules.pod 27 Feb 2002 18:03:36 -0000 1.2
@@ -88,20 +88,10 @@
session tracking abilities. C<HTML::Embperl> hooks into
C<Apache::Session> for you.
-
-
-
-
-
-
-
=head1 Apache::DBI - Initiate a persistent database connection
See L<mod_perl and relational
-Databases|databases/Apache_DBI_Initiate_a_persist>
-
-
-
+Databases|guide::databases/Apache_DBI_Initiate_a_persist>
=head1 Apache::Watchdog::RunAway - Hanging Processes Monitor and Terminator
@@ -122,15 +112,10 @@
Refer to the C<Apache::Watchdog::RunAway> manpage for the
configuration details.
-
-
-
-
-
=head1 Apache::VMonitor -- Visual System and Apache Server Monitor
C<Apache::VMonitor> is the next generation of
-L<mod_status|debug/mod_status>. It provides all the information
+L<mod_status|guide::debug/mod_status>. It provides all the information
mod_status provides and much more.
This module emulates the reporting functions of the top(), mount(),
@@ -181,7 +166,6 @@
@Apache::VMonitor::NETDEVS = qw(lo eth0);
$Apache::VMonitor::PROC_REGEX = join "\|", qw(httpd mysql squid);
-
More information is available in the module's extensive manpage.
It requires C<Apache::Scoreboard> and C<GTop> to work. C<GTop> in
@@ -189,11 +173,6 @@
platforms. Visit http://www.home-of-linux.org/gnome/libgtop/ to check
whether
your platform/flavor is supported.
-
-
-
-
-
=head1 Apache::GTopLimit - Limit Apache httpd processes
This module allows you to kill off Apache processes if they grow
@@ -202,10 +181,9 @@
size on every request:
The module is thoroughly explained in the sections: "L<Keeping the
-Shared Memory Limit|performance/Keeping_the_Shared_Memory_Limit>" and
+Shared Memory Limit|guide::performance/Keeping_the_Shared_Memory_Limit>" and
"L<Limiting the Size of the
-Processes|performance/Limiting_the_Size_of_the_Process>"
-
+Processes|guide::performance/Limiting_the_Size_of_the_Process>"
=head1 Apache::Request (libapreq) - Generic Apache Request Library
@@ -230,17 +208,14 @@
C<Apache::Request> and libapreq are tied tightly to the Apache API,
to which there is no access in a process running under mod_cgi.
-(L<Apache::Request|download/Apache__Request>)
-
-
-
+(L<Apache::Request|guide::download/Apache__Request>)
=head1 Apache::RequestNotes - Allow Easy, Consistent Access to Cookie and
Form Data Across Each Request Phase
C<Apache::RequestNotes> provides a simple interface allowing all
phases of the request cycle access to cookie or form input parameters
in a consistent manner. Behind the scenes, it uses libapreq
-L<Apache::Request|modules/Apache__Request__libapreq____Generic_Apache_Request_Library>)
+L<Apache::Request|guide::modules/Apache__Request__libapreq____Generic_Apache_Request_Library>)
functions to parse request data and puts references to the data in
C<pnotes()>.
@@ -251,19 +226,10 @@
See the C<Apache::RequestNotes> manpage for more information.
-
-
-
=head1 Apache::PerlRun - Run unaltered CGI scripts under mod_perl
See L<Apache::PerlRun - a closer
-look|porting/Apache_PerlRun_a_closer_look>.
-
-
-
-
-
-
+look|guide::porting/Apache_PerlRun_a_closer_look>.
=head1 Apache::RegistryNG -- Apache::Registry New Generation
@@ -291,9 +257,6 @@
C<Apache::RegistryBB> (Bare-Bones) is another subclass that skips the
stat() call performed by C<Apache::Registry> on each request.
-
-
-
=head1 Apache::RegistryBB -- Apache::Registry Bare Bones
It works just like C<Apache::Registry>, but does not test the x bit
@@ -310,11 +273,6 @@
PerlHandler Apache::RegistryBB->handler
</Location>
-
-
-
-
-
=head1 Apache::OutputChain -- Chain Stacked Perl Handlers
Apache::OutputChain was written as a way of exploring the possibilities
@@ -356,17 +314,14 @@
It's really a regular C<Apache::Registry> setup, except for the added
modules in the PerlHandler line.
-(L<Apache::GzipChain|modules/Apache__GzipChain___compress_HTML__or_anything__in_the_OutputChain>
allows to
+(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)
-
-
=head1 Apache::GzipChain - compress HTML (or anything) in the OutputChain
Have you ever served a huge HTML file (e.g. a file bloated with
@@ -412,8 +367,6 @@
Here we are using C<Apache::PassFile> but you can use any module which
creates output.
-
-
=head1 Apache::Gzip - Auto-compress web files with Gzip
Similar to C<Apache::GzipChain> but works with C<Apache::Filter>.
@@ -466,7 +419,6 @@
And you will get the data compressed if configured correctly.
-
=head1 Apache::PerlVINC - Allows Module Versioning in Location blocks and
Virtual Hosts
With this module you can have different C<@INC> for different virtual
@@ -549,9 +501,6 @@
should only be used in a development environment, not a production
one.
-
-
-
=head1 Apache::LogSTDERR
When Apache's builtin syslog support is used, the stderr stream is
@@ -566,9 +515,6 @@
[META: see
http://mathforum.org/epigone/modperl/vixquimwhen ]
-
-
-
=head1 Apache::RedirectLogFix
Because of the way mod_perl handles redirects, the status code is
@@ -587,7 +533,6 @@
$r->status(304);
$r->send_http_header();
-
=head1 Apache::SubProcess
The output of C<system()>, C<exec()>, and C<open(PIPE,"|program")>
@@ -726,8 +671,5 @@
See the module manpage for more information.
-
=cut
-
-
1.4 +8 -12 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.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- multiuser.pod 4 Feb 2002 13:50:25 -0000 1.3
+++ multiuser.pod 27 Feb 2002 18:03:36 -0000 1.4
@@ -47,7 +47,7 @@
write) any other files that belong to the same user and/or group the
web server is running as. Note that L<it's impossible to run
C<suEXEC> and C<cgiwrap> extensions under
-mod_perl|install/Is_it_possible_to_run_mod_perl_enabled_Apache_as_suExec_>.
+mod_perl|guide::install/Is_it_possible_to_run_mod_perl_enabled_Apache_as_suExec_>.
Another issue is the security of the database connections. If you use
C<Apache::DBI>, by hacking the C<Apache::DBI> code you can pick a
@@ -147,7 +147,7 @@
Another solution would be to use a setuid startup script, but think
twice before you go with it, since if users can modify the scripts
they will get a root access. For more information refer to the section
-"L<SUID Start-up Scripts|control/SUID_Start_up_Scripts>".
+"L<SUID Start-up Scripts|guide::control/SUID_Start_up_Scripts>".
=item *
@@ -206,11 +206,9 @@
we don't want the user to override, such as the port number. Even if
the user changes the port number in his I<username.httpd.conf> file,
Apache reads our settings last, so they take precedence. Note that
-you can use L<Perl sections|config/Apache_Configuration_in_Perl> to
+you can use L<Perl sections|guide::config/Apache_Configuration_in_Perl> to
make the configuration much easier.
-
-
=item 3
A much better, but costly solution is I<co-location>. Let the user
@@ -297,25 +295,23 @@
=back
-
-
=head1 Virtual Hosts in the guide
If you are about to use I<Virtual Hosts> you might want to read these
sections:
-L<Apache Configuration in Perl|config/Apache_Configuration_in_Perl>
+L<Apache Configuration in Perl|guide::config/Apache_Configuration_in_Perl>
L<Easing the Chores of Configuring Virtual Hosts with
-mod_macro|config/Configuring_Apache___mod_perl_with_mod_macro>
+mod_macro|guide::config/Configuring_Apache___mod_perl_with_mod_macro>
L<Is There a Way to Provide a Different startup.pl File for Each
-Individual Virtual
Host|config/Is_There_a_Way_to_Provide_a_Different_startup_pl_File_for_Each_Individual_Virtual_Host>
+Individual Virtual
Host|guide::config/Is_There_a_Way_to_Provide_a_Different_startup_pl_File_for_Each_Individual_Virtual_Host>
L<Is There a Way to Modify @INC on a Per-Virtual-Host or Per-Location
-Basis.|config/Is_There_a_Way_to_Modify__INC_on_a_Per_Virtual_Host_or_Per_Location_Basis_>
+Basis.|guide::config/Is_There_a_Way_to_Modify__INC_on_a_Per_Virtual_Host_or_Per_Location_Basis_>
L<A Script From One Virtual Host Calls a Script with the Same Path
-From the Other Virtual
Host|config/A_Script_From_One_Virtual_Host_Calls_a_Script_with_the_Same_Path_From_the_Other_Virtual_Host>
+From the Other Virtual
Host|guide::config/A_Script_From_One_Virtual_Host_Calls_a_Script_with_the_Same_Path_From_the_Other_Virtual_Host>
=cut
1.2 +34 -284 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.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- performance.pod 6 Jan 2002 16:54:56 -0000 1.1
+++ performance.pod 27 Feb 2002 18:03:36 -0000 1.2
@@ -2,8 +2,6 @@
Performance Tuning
-
-
=head1 The Big Picture
To make the user's Web browsing experience as painless as possible,
@@ -64,24 +62,16 @@
service business you should start worrying about the client's browsing
experience and B<not only> how good your code benchmarks are.
-
-
-
-
-
=head1 System Analysis
Before we try to solve a problem we need to identify it. In our case
we want to get the best performance we can with as little monetary and
time investment as possible.
-
=head2 Software Requirements
Covered in the section "L<Choosing an Operating
-System|hardware/Choosing_an_Operating_System>".
-
-
+System|guide::hardware/Choosing_an_Operating_System>".
=head2 Hardware Requirements
@@ -138,11 +128,7 @@
but exponentially!
More coverage is provided in the section "L<Choosing
-Hardware|hardware/Choosing_Hardware>".
-
-
-
-
+Hardware|guide::hardware/Choosing_Hardware>".
=head1 Essential Tools
@@ -160,8 +146,6 @@
relative results from the tests running on your machine, don't compare
your absolute results with those in this Guide.
-
-
=head2 Benchmarking Applications
How much faster is mod_perl than mod_cgi (aka plain perl/CGI)? There
@@ -183,9 +167,8 @@
directory of the mod_perl distribution includes such an example.
See also two tools for benchmarking:
-L<ApacheBench|performance/Configuration_Tuning_with_ApacheBench> and
-L<crashme test|performance/the_crashme_Script>
-
+L<ApacheBench|guide::performance/Configuration_Tuning_with_ApacheBench> and
+L<crashme test|guide::performance/the_crashme_Script>
=head3 Benchmarking Perl Code
@@ -219,9 +202,7 @@
my $elapsed = tv_interval($start_time,$end_time);
print "The sub took $elapsed seconds."
-See also the L<crashme test|performance/the_crashme_Script>.
-
-
+See also the L<crashme test|guide::performance/the_crashme_Script>.
=head3 Benchmarking a Graphic Hits Counter with Persistent DB Connections
@@ -253,18 +234,6 @@
http://www.realtime.net/~parkerm/perl/conf98/sld006.htm. It's now a
dead link. If you know its new location, please let me know.
-
-
-
-
-
-
-
-
-
-
-
-
=head3 Benchmarking Response Times
In the next sections we will talk about tools that allow us to
@@ -316,8 +285,6 @@
efficient we will try to improve it and run the benchmark again, to
see whether we have any improve in performance.
-
-
=head4 httperf
httperf is a utility written by David Mosberger. Just like
@@ -364,7 +331,7 @@
Errors: total 299 client-timo 299 socket-timo 0 connrefused 0 connreset 0
Errors: fd-unavail 0 addrunavail 0 ftab-full 0 other 0
-L<httperf download|download/httperf____webserver_Benchmarking_tool>
+L<httperf download|guide::download/httperf____webserver_Benchmarking_tool>
=head4 http_load
@@ -407,8 +374,7 @@
./http_load: unknown protocol -
-L<http_load
download|download/http_load____another_webserver_Benchmarking_tool>
-
+L<http_load
download|guide::download/http_load____another_webserver_Benchmarking_tool>
=head4 the crashme Script
@@ -445,7 +411,6 @@
=code lwp-bench.pl The LWP::Parallel::UserAgent benchmark
-
=head3 Benchmarking PerlHandlers
The C<Apache::Timeit> module does C<PerlHandler> Benchmarking. With
@@ -471,9 +436,6 @@
The C<Apache::Timeit> package is a part of the I<Apache-Perl-contrib>
files collection available from CPAN.
-
-
-
=head2 Code Profiling Techniques
The profiling process helps you to determine which subroutines or just
@@ -648,7 +610,6 @@
%Time ExclSec CumulS #Calls sec/call Csec/c Name
0.00 0.000 -0.000 1 0.0000 - main::test_code
-
It is possible to profile code running under mod_perl with the
C<Devel::DProf> module, available on CPAN. However, you must have
apache version 1.3b3 or higher and the C<PerlChildExitHandler> enabled
@@ -688,7 +649,6 @@
(Lookup the C<ServerRoot> directive's value in I<httpd.conf> to figure
out what's your C<$ServerRoot>.)
-
=head2 Measuring the Memory of the Process
Very important aspect of performance tuning is to make sure that your
@@ -817,14 +777,11 @@
For more information refer to the C<BSD::Resource> manpage.
-
-
=head2 Measuring the Memory Usage of Subroutines
With help of C<Apache::Status> you can find out the size of each
and every subroutine.
-
=over
=item 1
@@ -958,7 +915,6 @@
th 114 bytes | 0 OPs
b 113 bytes | 0 OPs
-
=back
Note, that the above is correct if you didn't precompile all
@@ -983,7 +939,6 @@
startup imported even if you ask for only one symbol. It
seems to me like a bug, but probably that's how C<CGI.pm> works.
-
BTW, you can check the number of opcodes in the code by a simple
command line run. For example comparing S<'my %hash'> vs. S<'my %hash =
()'>.
@@ -1001,33 +956,8 @@
Note that you shouldn't use C<Apache::Status> module on production
server as it adds quite a bit of overhead for each request.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
=head1 Know Your Operating System
-
In order to get the best performance it helps to get intimately
familiar with the Operating System (OS) the web server is running
on. There are many OS specific things that you may be able to optimize
@@ -1036,7 +966,6 @@
The following sections will reveal some of the most important details
you should know about your OS.
-
=head2 Sharing Memory
The sharing of memory is one very important factor. If your OS
@@ -1087,17 +1016,16 @@
large, otherwise you lose some of the benefit of sharing memory.
See L<Choosing
-MaxRequestsPerChild|performance/Choosing_MaxRequestsPerChild> for more
+MaxRequestsPerChild|guide::performance/Choosing_MaxRequestsPerChild> for more
about tuning the C<MaxRequestsPerChild> parameter.
-
=head3 How Shared Is My Memory?
You've probably noticed that the word shared is repeated many times in
relation to mod_perl. Indeed, shared memory might save you a lot of
money, since with sharing in place you can run many more servers than
without it. See L<the Formula and the
-numbers|performance/Choosing_MaxClients>.
+numbers|guide::performance/Choosing_MaxClients>.
How much shared memory do you have? You can see it by either using
the memory utility that comes with your system or you can deploy the
@@ -1114,9 +1042,6 @@
C<RES> (or C<RSS>) columns with the C<SHARE> column. C<RES> is
RESident memory, which is the size of pages currently swapped in.
-
-
-
=head3 Calculating Real Memory Usage
I have shown how to measure the size of the process' shared memory,
@@ -1169,7 +1094,7 @@
this number on your own risk.
I've used this technique to display real memory usage in the module
-L<Apache::VMonitor|debug/Apache__VMonitor____Visual_System_and_Apache_Server_Monitor>,
so instead of
+L<Apache::VMonitor|guide::debug/Apache__VMonitor____Visual_System_and_Apache_Server_Monitor>,
so instead of
trying to manually calculate this number you can use this module to do
it automatically. In fact in the calculations used in this module
there is no separation between the parent and child processes, they
@@ -1201,7 +1126,6 @@
So now C<$total_real> contains approximately the really used memory.
-
=head3 Are My Variables Shared?
How do you find out if the code you write is shared between the
@@ -1431,8 +1355,6 @@
sub match { readonly =~ /\w/g; }
1;
-
-
=head3 Preloading Perl Modules at Server Startup
You can use the C<PerlRequire> and C<PerlModule> directives to load
@@ -1580,9 +1502,6 @@
fantastic ratio, but this example is certainly helps to feel the
difference.
-
-
-
=head3 Preloading Registry Scripts at Server Startup
What happens if you find yourself stuck with Perl CGI scripts and you
@@ -1665,8 +1584,7 @@
I won't show any benchmarks here, since the effect is absolutely the
same as with preloading modules.
-See also L<BEGIN blocks|porting/BEGIN_blocks>
-
+See also L<BEGIN blocks|guide::porting/BEGIN_blocks>
=head3 Modules Initializing at Server Startup
@@ -1677,8 +1595,6 @@
specific modules in their respective manpages. We will present a few
examples of widely used modules where the code can be initialized.
-
-
=head4 Initializing DBI.pm
The first example is the C<DBI> module. As you know C<DBI> works with
@@ -1891,8 +1807,6 @@
So you can tell the difference (17% more child processes in the first
version).
-
-
=head4 Initializing CGI.pm
C<CGI.pm> is a big module that by default postpones the compilation of
@@ -2047,14 +1961,6 @@
META: I've heard that the 3.x generation will be less bloated, so
probably I'll have to rerun this using the new version.
-
-
-
-
-
-
-
-
=head2 Increasing Shared Memory With mergemem
C<mergemem> is an experimental utility for linux, which looks I<very>
@@ -2079,7 +1985,6 @@
This software comes with a utility called C<memcmp> to tell you how
much you might save.
-
=head2 Forking and Executing Subprocesses from mod_perl
It's desirable to avoid forking under mod_perl. Since when you do, you
@@ -2606,7 +2511,6 @@
shifting the first value of the C<ARGV> array if available. The
C<FreezeThaw> module does a very similar thing.
-
=head3 Starting a Short Running External Program
Sometimes you need to call an external program and you cannot continue
@@ -2638,10 +2542,6 @@
solutions provided by other Perl modules like C<IPC::Open2> which
allows to open a process for both reading and writing.
-
-
-
-
=head3 Executing system() or exec() in the Right Way
The exec() and system() system calls behave identically in the way
@@ -2674,9 +2574,6 @@
pointing to the existing program code plus your data space, thus will
not create this overhead.
-
-
-
=head2 OS Specific Parameters for Proxying
Most of the mod_perl enabled servers use a proxy front-end
@@ -2688,9 +2585,7 @@
There are very important OS parameters that you might want to change
in order to improve the server performance. This topic is
discussed in the section: L<Setting the Buffering Limits on Various
-OSes|scenario/Setting_the_Buffering_Limits_on_>
-
-
+OSes|guide::scenario/Setting_the_Buffering_Limits_on_>
=head1 Performance Tuning by Tweaking Apache Configuration
@@ -2718,12 +2613,12 @@
multiple clients calling the mod_perl scripts on your server
simultaneously. While there are commercial solutions, you can get
away with free ones which do the same job. You can use the
-L<ApacheBench|performance/Configuration_Tuning_with_ApacheBench> B<C<ab>>
utility
+L<ApacheBench|guide::performance/Configuration_Tuning_with_ApacheBench>
B<C<ab>> utility
which comes with the Apache distribution, the L<crashme
-script|performance/the_crashme_Script> which uses
+script|guide::performance/the_crashme_Script> which uses
C<LWP::Parallel::UserAgent>,
-L<httperf|performance/httperf> or
-L<http_load|performance/http_load>.
+L<httperf|guide::performance/httperf> or
+L<http_load|guide::performance/http_load>.
It is important to make sure that you run the load generator (the
client which generates the test requests) on a system that is more
@@ -3015,7 +2910,6 @@
1000 50 5 2.83
1000 100 10 6.51
-
B<Conclusions:> When we drastically reduce C<MaxRequestsPerChild>, the
performance starts to become closer to plain mod_cgi.
@@ -3039,8 +2933,6 @@
about 100 seconds to be served. In the second and third tests they
waited 1000 seconds!
-
-
=head2 Choosing MaxClients
The C<MaxClients> directive sets the limit on the number of
@@ -3051,7 +2943,7 @@
possible, because in this way we can limit the resources used by the
server children. Since we can restrict each child's process size (see
L<Limiting the size of the
-processes|performance/Limiting_the_Size_of_the_Process>), the
+processes|guide::performance/Limiting_the_Size_of_the_Process>), the
calculation of C<MaxClients> is pretty straightforward:
Total RAM Dedicated to the Webserver
@@ -3061,7 +2953,7 @@
So if I have 400Mb left for the webserver to run with, I can set
C<MaxClients> to be of 40 if I know that each child is limited to 10Mb
of memory (e.g. with
-L<C<Apache::SizeLimit>|performance/Limiting_the_Size_of_the_Processes>).
+L<C<Apache::SizeLimit>|guide::performance/Limiting_the_Size_of_the_Processes>).
You will be wondering what will happen to your server if there are
more concurrent users than C<MaxClients> at any time. This situation
@@ -3087,7 +2979,7 @@
Your children can share memory between them when the OS supports that.
You must take action to allow the sharing to happen - See L<Preload
Perl modules at server
-startup|performance/Preloading_Perl_Modules_at_Serve>. If you do
+startup|guide::performance/Preloading_Perl_Modules_at_Serve>. If you do
this, the chances are that your C<MaxClients> can be even higher. But
it seems that it's not so simple to calculate the absolute number. If
you come up with a solution please let us know! If the shared memory
@@ -3136,7 +3028,6 @@
392% more servers! Now you can feel the importance of having as much
shared memory as possible.
-
=head2 Choosing MaxRequestsPerChild
The C<MaxRequestsPerChild> directive sets the limit on the number of
@@ -3164,8 +3055,8 @@
C<Apache::PerlRun> if this is the case.
Another approach is to use the
-L<Apache::SizeLimit|performance/Limiting_the_Size_of_the_Processes> or
-the L<Apache::GTopLimit|performance/Keeping_the_Shared_Memory_Limit>
+L<Apache::SizeLimit|guide::performance/Limiting_the_Size_of_the_Processes> or
+the L<Apache::GTopLimit|guide::performance/Keeping_the_Shared_Memory_Limit>
modules. By using either of these modules you should be able to
discontinue using the C<MaxRequestPerChild>, although for some
developers, using both in combination does the job. In addition the
@@ -3173,9 +3064,8 @@
drops below a specified limit.
See also L<Preload Perl modules at server
-startup|performance/Preloading_Perl_Modules_at_Serve> and L<Sharing
-Memory|performance/Sharing_Memory>.
-
+startup|guide::performance/Preloading_Perl_Modules_at_Serve> and L<Sharing
+Memory|guide::performance/Sharing_Memory>.
=head2 Choosing MinSpareServers, MaxSpareServers and StartServers
@@ -3224,7 +3114,6 @@
as a rule, but rather as examples to show you some possible scenarios.
Use this information with caution!
-
=head2 Summary of Benchmarking to tune all 5 parameters
OK, we've run various benchmarks -- let's summarize the conclusions:
@@ -3300,20 +3189,6 @@
=back
-
-
-
-
-
-
-
-
-
-
-
-
-
-
=head2 KeepAlive
If your mod_perl server's I<httpd.conf> includes the following
@@ -3377,11 +3252,6 @@
$r->header_out('Content-Length', $length);
-
-
-
-
-
=head2 PerlSetupEnv Off
C<PerlSetupEnv Off> is another optimization you might consider. This
@@ -3435,8 +3305,6 @@
Notice that we have got the value of the environment variable I<TEST>.
-
-
=head2 Reducing the Number of stat() Calls Made by Apache
If you watch the system calls that your server makes (using I<truss>
@@ -3679,16 +3547,6 @@
in the normal way (no C<E<lt>PerlE<gt>> section required).
-
-
-
-
-
-
-
-
-
-
=head1 TMTOWTDI: Convenience and Habit vs. Performance
TMTOWTDI (sometimes pronounced I<"tim toady">), or I<"There's More
@@ -3947,7 +3805,6 @@
have just seen when we have tried the same benchmark on a different
machine.
-
=head2 "Bloatware" modules
Perl modules like IO:: are very convenient, but let's see what it
@@ -4064,7 +3921,6 @@
Anybody who's thinking of choosing one of these might do well to
digest these numbers first.
-
=head2 Apache::args vs. Apache::Request::param vs. CGI::param
Let's write three C<Apache::Registry> scripts that use
@@ -4176,9 +4032,6 @@
modules, whereas C<Apache::Request::param> is much faster than
C<CGI::param>.
-
-
-
=head2 Using $|=1 Under mod_perl and Better print() Techniques.
As you know, C<local $|=1;> disables the buffering of the currently
@@ -4223,7 +4076,6 @@
<BODY>
}
-
If you try the following:
print qq{
@@ -4292,7 +4144,6 @@
B<Conclusion>: Do not blindly follow suggestions, but think what is best for
you in each case.
-
=head2 Global vs. Fully Qualified Variables
It's always a good idea to avoid using global variables where it's
@@ -4367,9 +4218,6 @@
One could save 2.3Mb per single process with C<'use POSIX ();'> and
using fully qualifying C<POSIX::> function calls.
-
-
-
=head2 Object Methods Calls vs. Function Calls
Which subroutine calling form is more efficient: Object methods or
@@ -4423,8 +4271,6 @@
C<Foo-E<gt>$method()>. And the improvement does not address the
C<@ISA> lookup that still happens in either case.
-
-
=head3 The Overhead with Heavy Subroutines
But that doesn't mean that you shouldn't use methods. Generally your
@@ -4454,7 +4300,6 @@
function => sub { Foo::bar('Foo');},
});
-
We get a very close benchmarks!
function: 33 wallclock secs (15.81 usr + 1.12 sys = 16.93 CPU)
@@ -4484,7 +4329,6 @@
over the life of a project may turn out to be the most significant
cost factor.
-
=head3 Are All Methods Slower than Functions?
Some modules' API is misleading, for example C<CGI.pm> allows you to
@@ -4545,14 +4389,6 @@
functional forms. Therefore, the functional form should be slightly
slower than the object form.
-
-
-
-
-
-
-
-
=head2 Imported Symbols and Memory Usage
There is a real memory hit when you import all of the functions into
@@ -4607,7 +4443,6 @@
more when importing all the C<CGI.pm>'s symbols than when you import
none at all.
-
Generally you use more than one script, run more than one process and
probably import more symbols from the additional modules that you
deploy. So the real numbers are much bigger.
@@ -4621,14 +4456,11 @@
reference to an object, but even then it can be passed by value.
I strongly endorse L<Apache::Request (libapreq) - Generic Apache
-Request Library|modules/Apache_Request_libapreq_Gen>. Its core is
+Request Library|guide::modules/Apache_Request_libapreq_Gen>. Its core is
written in C, giving it a significant memory and performance benefit.
It has all the functionality of C<CGI.pm> except the HTML generation
functions.
-
-
-
=head2 Interpolation, Concatenation or List
Somewhat overlapping with the previous section we want to revisit the
@@ -4724,15 +4556,9 @@
be slower than direct append to the string whenever a new string
springs into existence.
-
-
[ReaderMETA]: Please send more mod_perl relevant Perl performance
hints
-
-
-
-
=head2 Using Perl stat() Call's Cached Results
When you do a stat() (or its variations C<-M> -- last modification
@@ -4758,10 +4584,6 @@
Two stat() calls were saved!
-
-
-
-
=head1 Apache::Registry and Derivatives Specific Notes
These are the sections that deal solely with C<Apache::Registry> and
@@ -4769,7 +4591,6 @@
Perl handlers code is discussed here, so if you don't use these
modules, feel free to skip this section.
-
=head2 Be Careful with Symbolic Links
As you know C<Apache::Registry> caches the scripts in the packages
@@ -4792,7 +4613,7 @@
http://localhost/perl/news.pl
To spot the duplication you should use the
-L<C<Apache::Status>|debug/Apache__Status____Embedded_Interpreter_Status_Information>
module.
+L<C<Apache::Status>|guide::debug/Apache__Status____Embedded_Interpreter_Status_Information>
module.
Amongst other things, it shows all the compiled C<Apache::Registry>
scripts (using their respective packages):
@@ -4821,9 +4642,7 @@
processes would show only one entry or none at all, since they might
not serve the same requests as the others. For more hints see the
section "L<Run the server in single
-mode|control/Running_a_Server_in_Single_Proce>".
-
-
+mode|guide::control/Running_a_Server_in_Single_Proce>".
=head1 Improving Performance by Prevention
@@ -4838,7 +4657,6 @@
programming techniques that would help you to keep your service in
order, even if you are not around.
-
=head2 Memory leakage
Scripts under mod_perl can very easily leak memory! Global variables
@@ -4898,7 +4716,6 @@
# been modified
}
-
If you work with arrays or hashes it's:
@{$var_lr} dereferences an array
@@ -4936,7 +4753,6 @@
either modify variables passed by reference or expressly return a
result (e.g. C<$content=process($content);>).
-
=head3 Work With Databases
If you do some DB processing, you will often encounter the need to
@@ -5113,12 +4929,10 @@
} # end of sub {}
}; # end of my $rsub = eval {
-
You might also want to check the section L<Limiting the Size of the
-Processes|performance/Limiting_the_Size_of_the_Process>
+Processes|guide::performance/Limiting_the_Size_of_the_Process>
and L<Limiting Other Resources Used by Apache Child
-Processes|performance/Limiting_Other_Resources_Used_by>.
-
+Processes|guide::performance/Limiting_Other_Resources_Used_by>.
=head2 Keeping the Shared Memory Limit
@@ -5146,7 +4960,7 @@
That's where the C<Apache::GTopLimit> module comes to help. If you
are lucky to have your OS among those that can build the
-L<libgtop|download/libgtop> library, you will be able to build the
+L<libgtop|guide::download/libgtop> library, you will be able to build the
C<GTop> module that provides the Perl API for C<libgtop>, which in
turn used by C<Apache::GTopLimit> (that's the I<GTop> part in the
name).
@@ -5189,7 +5003,6 @@
$Apache::GTopLimit::DEBUG = 1;
-
=head2 Limiting the Size of the Processes
So now you know how to prevent processes from consuming more real
@@ -5359,19 +5172,13 @@
Refer to the C<Apache::Resource> and C<setrlimit(2)> manpages for more
information.
-
-
-
-
-
=head2 Limiting the Number of Processes Serving the Same Resource
If you want to limit number of Apache children that could
simultaneously be serving the (nearly) same resource, you should take
-a look at the L<C<mod_throttle_access>|download/mod_throttle_access>
+a look at the L<C<mod_throttle_access>|guide::download/mod_throttle_access>
module.
-
It solves the problem of too many concurrent request accessing the
same URI, if for example the handler that serves this URI uses some
resource that has a limitation on the maximum number of possible users
@@ -5417,32 +5224,16 @@
http://www.modperl.com/chapters/ch6.html#Blocking_Greedy_Clients
-
-
-
-
-
-
-
-
-
-
-
=head1 Perl Modules for Performance Improvement
-
These sections are about Perl modules that improve performance without
requiring changes to your code. Mostly you just need to tweak the
configuration file to plug these modules in.
-
-
=head2 Sending Plain HTML as Compressed Output
See L<Apache::GzipChain - compress HTML (or anything) in the
-OutputChain|modules/Apache_GzipChain_compress_HTM>
-
-
+OutputChain|guide::modules/Apache_GzipChain_compress_HTM>
=head2 Caching Components with HTML::Mason
@@ -5467,20 +5258,14 @@
META: Should also mention Embperl (especially since its C + XS)
-
-
-
-
=head1 Efficient Work with Databases under mod_perl
-
Most of the mod_perl enabled servers work with database engines, so in
this section we will learn about two things: how mod_perl makes working
with databases faster and a few tips for a more efficient DBI coding in
Perl. (DBI provides an identical Perl interface to many database
implementations.)
-
=head2 Persistent DB Connections
Another popular use of mod_perl is to take advantage of its ability to
@@ -5584,12 +5369,6 @@
connections to achieve the same result, although this is at the risk
of getting deadlocks depending on what you are trying to do!
-
-
-
-
-
-
=head2 mod_perl Database Performance Improving
=head3 Analysis of the Problem
@@ -5699,7 +5478,7 @@
database, C<Apache::DBI> returns a cached connection, thus saving the
significant time penalty of repeatedly connecting to the database. You
will find a full treatment of C<Apache::DBI> at L<Persistent DB
-Connections|performance/Persistent_DB_Connections>
+Connections|guide::performance/Persistent_DB_Connections>
When C<Apache::DBI> is in use, none of the code in the example needs
to change. The code is upgraded from naive to respectable with the use
@@ -5898,7 +5677,6 @@
}
# ...
-
Notice that several improvements have been made. Since the statement
handles have a longer life than the request, there is no need for each
request to prepare the statement, and no need to call the statement
@@ -5926,18 +5704,6 @@
improving your database indexing scheme or web server buffering and
load balancing.
-
-
-
-
-
-
-
-
-
-
-
-
=head1 Using 3rd Party Applications
It's been said that no one can do everything well, but one can do
@@ -5953,16 +5719,11 @@
Let's take a look at a few of these.
-
=head2 Proxying the mod_perl Server
Proxy gives you a great performance increase in most cases. It's
discussed in the section L<Adding a Proxy Server in http Accelerator
-Mode|strategy/Adding_a_Proxy_Server_in_http_Ac>.
-
-
-
-
+Mode|guide::strategy/Adding_a_Proxy_Server_in_http_Ac>.
=head1 Upload and Download of Big Files
@@ -5978,13 +5739,12 @@
downloading of big files, you probably want it to be executed on a
plain apache server under mod_cgi (i.e. performing this operation on
the front-end server, if you use L<a dual-server
-setup|scenario/One_Plain_and_One_mod_perl_enabl>.
+setup|guide::scenario/One_Plain_and_One_mod_perl_enabl>.
This of course assumes that the script requires none of the
functionality of the mod_perl server, such as custom authentication
handlers.
-
=head1 Apache/mod_perl Build Options
It's important how you build mod_perl enabled Apache. It influences
@@ -5993,7 +5753,6 @@
[ReaderMETA: Any other building time things that influence performance?]
-
=head2 mod_perl Process Size as a Function of Compiled in C Modules and
mod_perl Features
You might wonder whether it's better to compile in only the required
@@ -6050,7 +5809,6 @@
Everything 1044432 +151504
Everything+Debug 1162100 +269172
-
Indeed when you strip most of the default things, the server size is
slimmer. But the savings are insignificant since you don't multiply
the added size by the number of child processes if your OS supports
@@ -6070,18 +5828,14 @@
components and disabling the unneeded default components, makes you a
good Apache administrator.
-
-
=head1 Perl Build Options
-
The Perl interpreter lays in the brain of the mod_perl server and if
we can optimize perl into doing things faster under mod_perl we make
the whole server faster. Generally, optimizing the Perl interpreter
means enabling or disabling some command line options. Let's see a few
important ones.
-
=head2 -DTWO_POT_OPTIMIZE and -DPACK_MALLOC Perl Build Options
Newer Perl versions also have build time options to reduce runtime
@@ -6112,9 +5866,6 @@
Important: both options are On by default in perl versions 5.005 and
higher.
-
-
-
=head2 -Dusemymalloc Perl Build Option
You have a choice to use the native or Perl's own malloc()
@@ -6135,7 +5886,6 @@
to configure Perl with -Dusemymalloc. Perl's malloc is not
much of a win under linux, but makes a B<huge> difference under
Solaris.
-
=head1 Architecture Specific Compile Options
1.2 +9 -126 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.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- perl.pod 6 Jan 2002 16:54:56 -0000 1.1
+++ perl.pod 27 Feb 2002 18:03:36 -0000 1.2
@@ -12,12 +12,6 @@
information provided here. The rest of the Guide assumes that you
have read this chapter and understood it.
-
-
-
-
-
-
=head1 perldoc's Rarely Known But Very Useful Options
First of all, I want to stress that you cannot become a Perl hacker
@@ -34,7 +28,6 @@
installed on your system. To find out what Perl manpages are
available execute:
-
% perldoc perl
To find what functions perl has, execute:
@@ -63,11 +56,6 @@
% perldoc perldoc
-
-
-
-
-
=head1 Tracing Warnings Reports
Sometimes it's very hard to understand what a warning is complaining
@@ -197,16 +185,11 @@
operator and "here documents" are known to throw off Perl's line
numbering, so the messages reporting warnings and errors can have
incorrect line numbers. (See L<Finding the Line Which Triggered the
-Error or Warning|debug/Finding_the_Line_Which_Triggered> for more
+Error or Warning|guide::debug/Finding_the_Line_Which_Triggered> for more
information).
Getting the trace helps a lot.
-
-
-
-
-
=head1 Variables Globally, Lexically Scoped And Fully Qualified
META: this material is new and requires polishing so read with care.
@@ -215,7 +198,6 @@
scoping in Perl discussions, but little of it will make any sense
without a few key facts:
-
=head2 Symbols, Symbol Tables and Packages; Typeglobs
There are two important types of symbol: package global and lexical.
@@ -380,36 +362,20 @@
=back
-
-
-
=head2 Additional reading references
For more information see: L<Using global variables and sharing them
-between modules/packages|perl/Using_Global_Variables_and_Shari> and an
+between modules/packages|guide::perl/Using_Global_Variables_and_Shari> and an
article by Mark-Jason Dominus about how Perl handles variables and
namespaces, and the difference between C<use vars()> and C<my()> -
http://www.plover.com/~mjd/perl/FAQs/Namespaces.html .
-
-
-
-
-
-
-
-
-
=head1 my() Scoped Variable in Nested Subroutines
Before we proceed let's make the assumption that we want to develop
the code under the C<strict> pragma. We will use lexically scoped
variables (with help of the my() operator) whenever it's possible.
-
-
-
-
=head2 The Poison
Let's look at this code:
@@ -473,11 +439,6 @@
our code has some kind of memory for the results of the first
execution, or it ignores the arguments in subsequent executions.
-
-
-
-
-
=head2 The Diagnosis
Let's follow the guidelines and use the C<-w> flag. Now execute the
@@ -539,9 +500,6 @@
outer subroutine. There are two copies of the C<$x> variable, no
longer a single one shared by the two routines.
-
-
-
=head2 The Remedy
The C<diagnostics> pragma suggests that the problem can be solved by
@@ -594,8 +552,6 @@
So we can see that the problem is solved.
-
-
=head1 Understanding Closures -- the Easy Way
In Perl, a closure is just a subroutine that refers to one or more
@@ -685,9 +641,6 @@
identical code references and therefore it ignores any future changes
to the lexical variables outside of it.
-
-
-
=head1 When You Cannot Get Rid of The Inner Subroutine
First you might wonder, why in the world will someone need to define
@@ -796,16 +749,14 @@
it won't work as you expect starting from the second call, as was
explained in the previous section.
-
=head2 Remedies for Inner Subroutines
First of all there is nothing to worry about, as long as you don't
forget to turn the warnings On. If you do happen to have the
"L<my() Scoped Variable in Nested
-Subroutines|perl/my_Scoped_Variable_in_Nested_S>"
+Subroutines|guide::perl/my_Scoped_Variable_in_Nested_S>"
problem, Perl will always alert you.
-
Given that you have a script that has this problem, what are the ways
to solve it? There are many of them and we will discuss some of them
here.
@@ -1035,7 +986,6 @@
it is not updatable as would be the case of calling the function with
a literal, e.g. I<increment_counter(5)>).
-
multirun5.pl
-----------
#!/usr/bin/perl -w
@@ -1101,28 +1051,12 @@
1 ;
-
Now you have at least six workarounds to choose from.
-
For more information please refer to perlref and perlsub manpages.
-
-
-
-
-
-
-
-
-
-
-
-
=head1 use(), require(), do(), %INC and @INC Explained
-
-
=head2 The @INC array
C<@INC> is a special Perl variable which is the equivalent of the
@@ -1138,7 +1072,6 @@
of the directories in C<@INC>, or you can provide the full path to the
file.
-
=head2 The %INC hash
C<%INC> is another special Perl variable that is used to cache the
@@ -1284,7 +1217,6 @@
recompile the C<FindBin> module on each request. So it may not be
worth it.
-
=head2 Modules, Libraries and Program Files
Before we proceed, let's define what we mean by I<module>,
@@ -1333,7 +1265,6 @@
}
1;
-
=item * Modules
A file which contains perl subroutines and other code.
@@ -1378,10 +1309,6 @@
=back
-
-
-
-
=head2 require()
require() reads a file containing Perl code and compiles it. Before
@@ -1410,7 +1337,7 @@
the suggestion is to put "C<1;>" at the end of file.
Although you should use the real filename for most files, if the file
-is a L<module|perl/Modules__Libraries_and_Program_Files>, you may use the
+is a L<module|guide::perl/Modules__Libraries_and_Program_Files>, you may use
the
following convention instead:
require My::Module;
@@ -1477,7 +1404,7 @@
use(), just like require(), loads and compiles files containing Perl
code, but it works with
-L<modules|perl/Modules__Libraries_and_Program_Files> only. The only way to
+L<modules|guide::perl/Modules__Libraries_and_Program_Files> only. The only
way to
pass a module to load is by its module name and not its filename. If
the module is located in I<MyCode.pm>, the correct way to use() it is:
@@ -1539,7 +1466,6 @@
imported by C<use>, i.e., it calls C<Module-E<gt>unimport(LIST)>
instead of C<import()>.
-
=head2 do()
While do() behaves almost identically to require(), it reloads the
@@ -1552,21 +1478,6 @@
successfully compiled, do() returns the value of the last expression
evaluated.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
=head1 Using Global Variables and Sharing Them Between Modules/Packages
It helps when you code your application in a structured way, using the
@@ -1591,7 +1502,7 @@
import(). This will work only if you do not use C<strict> pragma; but
you I<have> to use this pragma if you want to run your scripts under
mod_perl. Read L<The strict
-pragma|porting/The_strict_pragma> to find out why.
+pragma|guide::porting/The_strict_pragma> to find out why.
=head2 Making Variables Global With strict Pragma On
@@ -1692,7 +1603,6 @@
My::HTML::printmyheader();
-
My/HTML.pm
----------------
package My::HTML;
@@ -1741,7 +1651,6 @@
}
1;
-
=head2 Using the Perl Aliasing Feature to Share Global Variables
As the title says you can import a variable into a script or module
@@ -1889,7 +1798,6 @@
my $config_module = $r->dir_config('FooConfigModule') || '';
-
=head1 The Scope of the Special Perl Variables
Special Perl variables like C<$|> (buffering), C<$^T> (script's start
@@ -1948,18 +1856,6 @@
but within the enclosing block, the global variable will be visible
with its new value inside the subroutine.
-
-
-
-
-
-
-
-
-
-
-
-
=head1 Compiled Regular Expressions
When using a regular expression that contains an interpolated Perl
@@ -2094,12 +1990,6 @@
The qr() operator compiles the pattern for each request and then use
the compiled version in the actual match.
-
-
-
-
-
-
=head1 Exception Handling for mod_perl
Here are some guidelines for S<clean(er)> exception handling in
@@ -2177,7 +2067,6 @@
}
# all is well or has been handled
-
=head2 Alternative Exception Handling Techniques
An often suggested method for handling global exceptions in mod_perl,
@@ -2249,8 +2138,6 @@
inform them of better ways to code. The following material is an
attempt to do just that.
-
-
=head2 Better Exception Handling
The C<eval{}> construct in itself is a fairly weak way to handle
@@ -2449,7 +2336,7 @@
overcome this by overriding the core die function. This is slightly
more complex than implementing a C<$SIG{__DIE__}> handler, but is far
less magical, and is the right thing to do, according to the
-L<perl5-porters mailing list|help/Get_help_with_Perl>.
+L<perl5-porters mailing list|guide::help/Get_help_with_Perl>.
Overriding core functions has to be done from an external
package/module. So we're going to add that to our C<My::Exception>
@@ -2490,7 +2377,6 @@
there's no "finally" clause, and no exception stack, but that's another topic
for another time).
-
=head2 A Single UnCaught Exception Class
Until the Perl core gets its own base exception class (which will likely
happen
@@ -2548,7 +2434,6 @@
check the source code of anything you install to make sure it follows
your exception handling technique, or just uses die() with strings.
-
=head2 Some Uses
I'm going to come right out and say now: I abuse this system horribly!
@@ -2581,7 +2466,6 @@
programmer style really. There's a lot of literature out there about
exception handling, so I suggest doing some research.
-
=head2 Conclusions
Here I've demonstrated a simple and scalable (and useful) exception
@@ -2593,7 +2477,7 @@
delivering to thousands of users.
For similar exception handling techniques, see the section "L<Other
-Implementations|perl/Other_Implementations>".
+Implementations|guide::perl/Other_Implementations>".
=head2 The My::Exception class in its entirety
@@ -2661,7 +2545,7 @@
=item * Error.pm
Graham Barr's excellent OO styled "try, throw, catch" module (from
-L<CPAN|download/Perl>). This should be considered your best option
+L<CPAN|guide::download/Perl>). This should be considered your best option
for structured exception handling because it is well known and well
supported and used by a lot of other applications.
@@ -2677,7 +2561,6 @@
classes that provide extra methods or data. For example, an exception
class for database errors could provide a method for returning the SQL
and bound parameters in use at the time of the error.
-
=item * Try.pm
1.3 +33 -357 modperl-docs/src/docs/1.0/guide/porting.pod
Index: porting.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/porting.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- porting.pod 21 Feb 2002 09:08:38 -0000 1.2
+++ porting.pod 27 Feb 2002 18:03:36 -0000 1.3
@@ -34,23 +34,13 @@
functions that were reimplemented to work better in mod_perl
environment.
-
-
-
-
-
-
-
-
-
-
=head1 Before you start to code
It can be a good idea to tighten up some of your Perl programming
practices, since mod_perl doesn't tolerate sloppy programming.
This chapter relies on a certain level of Perl knowledge. Please
-read through the L<Perl Reference|perl/Perl_Reference_> chapter and make
sure you
+read through the L<Perl Reference|guide::perl/Perl_Reference_> chapter and
make sure you
know the material covered there. This will allow me to concentrate on
pure mod_perl issues and make them more prominent to the experienced
Perl programmer, which would otherwise be lost in the sea of Perl
@@ -82,16 +72,6 @@
=back
-
-
-
-
-
-
-
-
-
-
=head1 Exposing Apache::Registry secrets
Let's start with some simple code and see what can go wrong with it,
@@ -119,7 +99,6 @@
print "Counter is equal to $counter !\r\n";
}
-
You would expect to see the output:
Counter is equal to 1 !
@@ -144,9 +123,6 @@
counter over 5 and inconsistent growth over reloads. Let's investigate
this script.
-
-
-
=head2 The First Mystery
First let's peek into the C<error_log> file. Since we have enabled the
@@ -160,7 +136,7 @@
opposed to anonymous - subroutine defined inside another subroutine)
that refers to a lexically scoped variable defined outside this nested
subroutine. This effect is explained in L<my() Scoped Variable in
-Nested Subroutines|perl/my_Scoped_Variable_in_Nested_S>.
+Nested Subroutines|guide::perl/my_Scoped_Variable_in_Nested_S>.
Do you see a nested named subroutine in my script? I don't! What's
going on? Maybe it's a bug? But wait, maybe the perl interpreter sees
@@ -298,7 +274,7 @@
(unless I create them myself :).
The section 'L<Remedies for Inner
-Subroutines|perl/Remedies_for_Inner_Subroutines>' discusses
+Subroutines|guide::perl/Remedies_for_Inner_Subroutines>' discusses
many other possible workarounds for this problem.
You shouldn't be intimidated by this issue at all, since Perl is your
@@ -341,9 +317,6 @@
Why didn't we notice this when we were trying the software on our
development server? Keep reading and you will understand why.
-
-
-
=head2 The Second Mystery
Let's return to our original example and proceed with the second
@@ -385,21 +358,10 @@
Of course none of the warnings will be reported if the warning
mechanism is not turned B<On>. Refer to the section "L<Tracing
-Warnings Reports|perl/Tracing_Warnings_Reports>" to learn about
-warnings in general and to the "L<Warnings|porting/Warnings>" section
+Warnings Reports|guide::perl/Tracing_Warnings_Reports>" to learn about
+warnings in general and to the "L<Warnings|guide::porting/Warnings>" section
to learn how to turn them on and off under mod_perl.
-
-
-
-
-
-
-
-
-
-
-
=head1 Sometimes it Works, Sometimes it Doesn't
When you start running your scripts under mod_perl, you might find
@@ -480,11 +442,8 @@
return (SOME_USER_PASSWD_CHECK_IS_OK) ? 1 : 0;
}
-
Of course this example is trivial--but believe me it happens!
-
-
=head2 Thinking mod_cgi
Just another little one liner that can spoil your day, assuming you
@@ -524,25 +483,10 @@
}
To make sure you don't miss these bugs always test your CGI in
-L<single process mode|control/Running_a_Server_in_Single_Process_Mode>.
+L<single process
mode|guide::control/Running_a_Server_in_Single_Process_Mode>.
To solve this particular B</o> modifier problem refer to L<Compiled
-Regular Expressions|perl/Compiled_Regular_Expressions>.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+Regular Expressions|guide::perl/Compiled_Regular_Expressions>.
=head1 Script's name space
@@ -551,22 +495,10 @@
your URI is C</perl/test.pl> the package will be called
C<Apache::ROOT::perl::test_2epl>.
-
-
-
-
-
-
-
-
-
-
-
-
=head1 @INC and mod_perl
The basic Perl C<@INC> behaviour is explained in section L<use(), require(),
-do(), %INC and @INC Explained|perl/use_require_do_INC_and>.
+do(), %INC and @INC Explained|guide::perl/use_require_do_INC_and>.
When running under mod_perl, once the server is up C<@INC> is frozen
and cannot be updated. The only opportunity to B<temporarily> modify
@@ -604,22 +536,12 @@
PerlRequire /path/to/startup.pl
-
=back
-
-
-
-
-
-
-
-
-
=head1 Reloading Modules and Required Files
You might want to read the "L<use(), require(), do(), %INC and @INC
-Explained|perl/use_require_do_INC_and>" before you proceed with this
+Explained|guide::perl/use_require_do_INC_and>" before you proceed with this
section.
When you develop plain CGI scripts, you can just change the code, and
@@ -649,7 +571,7 @@
The simplest approach is to restart the server each time you apply
some change to your code. See L<Server Restarting
-techniques|control/Restarting_Techniques>.
+techniques|guide::control/Restarting_Techniques>.
After restarting the server about 100 times, you will tire of it and
you will look for other solutions.
@@ -697,11 +619,10 @@
value.
To make sure that you have set C<@INC> correctly, configure
-L</perl-status
location|debug/Apache__Status____Embedded_Interpreter_Status_Information>, fetch
+L</perl-status
location|guide::debug/Apache__Status____Embedded_Interpreter_Status_Information>,
fetch
http://www.example.com/perl-status?inc and look at the bottom of the
page, where the contents of C<@INC> will be shown.
-
Notice the following trap:
While "C<.>" is in C<@INC>, perl knows to require() files with
@@ -715,7 +636,6 @@
If you want Apache::StatINC to reload your script--modify C<@INC> at
server startup, or use a full path in the require() call.
-
=head2 Using Apache::Reload
C<Apache::Reload> comes as a drop-in replacement for
@@ -787,7 +707,6 @@
This module might have a problem with reloading single modules that
contain multiple packages that all use pseudo-hashes.
-
Also if you have modules loaded from directories which are not in
C<@INC>, C<Apache::Reload> will fail to find the files, due the fact
that C<@INC> is reset to its original value even if it gets temporary
@@ -810,12 +729,9 @@
and restart the server. Now the problem is solved.
-
=head3 Availability
-This module is available from L<CPAN|download/CPAN_Downloads>.
-
-
+This module is available from L<CPAN|guide::download/CPAN_Downloads>.
=head2 Configuration Files: Writing, Dynamically Updating and Reloading
@@ -1156,12 +1072,10 @@
},
);
-
You have just learned how to make configuration files easily
maintainable, and how to save memory by avoiding the export of
variables into a script's namespace.
-
=head3 Reloading Configuration Files
First, lets look at a simple case, when we just have to look after a
@@ -1289,7 +1203,7 @@
variables on its first invocation. To do that, you would need to
replace each occurrence of return() and warn() with die(). If you do
that, take a look at the section "L<Redirecting Errors to the Client
-instead of error_log|snippets/Redirecting_Errors_to_the_Client>".
+instead of error_log|guide::snippets/Redirecting_Errors_to_the_Client>".
I used the above approach when I had a huge configuration file that
was loaded only at server startup, and another little configuration
@@ -1634,7 +1548,6 @@
} # end sub conf_modification_form
-
Once updated the script generates a file like:
$c{release} = '5.6';
@@ -1645,8 +1558,6 @@
1;
-
-
=head2 Reloading handlers
If you want to reload a perlhandler on each invocation, the following
@@ -1656,27 +1567,10 @@
do() reloads C<MyTest.pm> on every request.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
=head1 Name collisions with Modules and libs
This section requires an in-depth understanding of L<use(), require(),
-do(), %INC and @INC |perl/use_require_do_INC_and>.
+do(), %INC and @INC |guide::perl/use_require_do_INC_and>.
To make things clear before we go into details: each child process has
its own C<%INC> hash which is used to store information about its
@@ -1742,7 +1636,6 @@
=back
-
Let's look at three scripts with faults related to name space. For the
following discussion we will consider just one individual child process.
@@ -1757,11 +1650,9 @@
compiled. This is a direct result of using C<%INC>, which has keys
equal to the names of the modules. Two identical names will refer to
the same key in the hash. (Refer to the section 'L<Looking inside the
-server|debug/Looking_inside_the_server>' to find out how you can know
+server|guide::debug/Looking_inside_the_server>' to find out how you can know
what is loaded and where.)
-
-
So if you have two different C<Foo> modules in two different
directories and two scripts C<script1.pl> and C<script2.pl>, placed
like this:
@@ -1771,7 +1662,6 @@
./tool2/Foo.pm
./tool2/tool2.pl
-
Where some sample code could be:
./tool1/tool1.pl
@@ -1806,7 +1696,7 @@
about C<Foo>. When you call the second script it will not know about
C<Foo> at all--it's like you've forgotten to write C<use Foo;>. Run
the server in L<single server
-mode|control/Running_a_Server_in_Single_Proce> to detect this kind of
+mode|guide::control/Running_a_Server_in_Single_Proce> to detect this kind of
bug immediately.
You will see the following in the error_log file:
@@ -1861,7 +1751,6 @@
=back
-
There are three solutions for this:
=over
@@ -1977,19 +1866,6 @@
server! You have to run a separate server for each. They can be on the
same machine, but the servers will use different ports.
-
-
-
-
-
-
-
-
-
-
-
-
-
=head1 More package name related issues
If you have the following:
@@ -2001,17 +1877,6 @@
then the C<Apache::Work::Foo> package gets defined, so mod_perl does
not try to pull in C<Apache/Work/Foo.pm>
-
-
-
-
-
-
-
-
-
-
-
=head1 __END__ and __DATA__ tokens
C<Apache::Registry> scripts cannot contain C<__END__> or C<__DATA__>
@@ -2062,20 +1927,6 @@
Also, remember that whatever applies to C<Apache::Registry> scripts,
in most cases applies to C<Apache::PerlRun> scripts.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
=head1 Output from system calls
The output of C<system()>, C<exec()>, and C<open(PIPE,"|program")> calls
@@ -2089,21 +1940,12 @@
But you're throwing performance out the window either way. It's best
not to fork at all if you can avoid it. See the "L<Forking or
Executing subprocesses from
-mod_perl|performance/Forking_and_Executing_Subprocess>" section
+mod_perl|guide::performance/Forking_and_Executing_Subprocess>" section
to learn about implications of forking.
-Also read about
L<Apache::SubProcess|porting/CGI_to_mod_perl_Porting__mod_perl_Coding_guidelines__>
for
+Also read about
L<Apache::SubProcess|guide::porting/CGI_to_mod_perl_Porting__mod_perl_Coding_guidelines__>
for
overridden system() and exec() implementations that work with mod_perl.
-
-
-
-
-
-
-
-
-
=head1 Using format() and write()
The interface to filehandles which are linked to variables with Perl's
@@ -2120,9 +1962,6 @@
Another alternative is to use the C<Text::Reform> module.
-
-
-
=head1 Terminating requests and processes, the exit() and child_terminate()
functions
Perl's C<exit()> built-in function (all versions prior to 5.6) cannot
@@ -2202,16 +2041,11 @@
The above is the code that is used by the C<Apache::SizeLimit> module
which terminates processes that grow bigger than a value you choose.
-L<Apache::GTopLimit|modules/Apache__GTopLimit___Limit_Apache_httpd_processes>
(based on
+L<Apache::GTopLimit|guide::modules/Apache__GTopLimit___Limit_Apache_httpd_processes>
(based on
I<libgtop> and C<GTop.pm>) is a similar module. It does the same
thing, plus you can configure it to terminate processes when their
shared memory shrinks below some specified size.
-
-
-
-
-
=head1 die() and mod_perl
When you write:
@@ -2246,7 +2080,6 @@
$SIG{__DIE__} = sub { print STDERR @_; Apache::exit(); }
-
=head1 Return Codes
C<Apache::Registry> normally assumes a return code of C<OK> (C<200>).
@@ -2259,17 +2092,12 @@
C<$r-E<gt>send_http_header()> (assuming that you have C<PerlSendHeader
Off>).
-
=head1 Testing the Code from the Shell
Your CGI scripts will B<not> yet run from the command line unless you
use C<CGI::Switch> or C<CGI.pm> and have Perl 5.004 or later. They
must not make any direct calls to Apache's Perl API methods.
-
-
-
-
=head1 I/O is different
If you are using Perl 5.004 or later, most CGI scripts can run under
@@ -2279,10 +2107,6 @@
functions do not work as they do under CGI. If you're using C<CGI.pm>,
use C<$query-E<gt>print> instead of plain ol' C<print()>.
-
-
-
-
=head1 STDIN, STDOUT and STDERR streams
In mod_perl both C<STDIN> and C<STDOUT> are tied to the socket the
@@ -2301,12 +2125,10 @@
Note that C<OUT> was picked just as an example -- there is nothing
special about it. If you are looking to redirect the STDOUT stream
into a scalar, see the L<Redirecting STDOUT into a
-String|porting/Redirecting_STDOUT_into_a_Scalar> section.
+String|guide::porting/Redirecting_STDOUT_into_a_Scalar> section.
C<STDERR> is tied to the file defined by the C<ErrorLog> directive.
-
-
=head1 Redirecting STDOUT into a Scalar
Sometimes you have a situation where a black box functions prints the
@@ -2328,8 +2150,6 @@
# reset default fh to previous value
select($old_fh) if defined $old_fh;
-
-
=head1 Apache::print() and CORE::print()
Under mod_perl C<CORE::print()> will redirect its data to
@@ -2359,8 +2179,6 @@
print(scalar($foo));
-
-
=head1 Global Variables Persistence
Since the child process generally doesn't exit before it has serviced
@@ -2368,7 +2186,7 @@
from request to request. This means that you must never rely on the
value of the global variable if it wasn't initialized at the beginning
of the request processing. See "L<Variables globally, lexically scoped
-and fully qualified|perl/Variables_Globally_Lexically_Sc>" for more
+and fully qualified|guide::perl/Variables_Globally_Lexically_Sc>" for more
info.
You should avoid using global variables unless it's impossible without
@@ -2377,15 +2195,9 @@
they are used. Use my() scoped variables wherever you can.
You should be especially careful with L<Perl Special
-Variables|perl/The_Scope_of_the_Special_Perl_Va> which cannot be
+Variables|guide::perl/The_Scope_of_the_Special_Perl_Va> which cannot be
lexically scoped. You have to use local() instead.
-
-
-
-
-
-
=head1 Generating correct HTTP Headers
A HTTP response header consists of at least two fields. HTTP response
@@ -2538,7 +2350,6 @@
$r->send_http_header;
}
-
Note that you can always use the code in the else part of the above
example, no matter whether the C<PerlSendHeader> directive is On or
Off.
@@ -2689,7 +2500,7 @@
Why can't we use a lexical without hitting the nested subroutine
effect? Because when we've discussed L<Apache::Registry
-secrets|porting/Exposing_Apache_Registry_secret> we have seen that the
+secrets|guide::porting/Exposing_Apache_Registry_secret> we have seen that the
code is wrapped in a C<handler> routine, effectively turning any
subroutines within the file a script resides in into nested
subroutines. Hence we are forced to use a global in this situation.
@@ -2704,19 +2515,7 @@
additional headers, such as cookies.
See also L<Correct Headers--A quick guide for mod_perl
-users|correct_headers/>
-
-
-
-
-
-
-
-
-
-
-
-
+users|guide::correct_headers/>
=head1 NPH (Non Parsed Headers) scripts
@@ -2732,13 +2531,6 @@
PerlSendHeader Off
</Files>
-
-
-
-
-
-
-
=head1 BEGIN blocks
Perl executes C<BEGIN> blocks as soon as possible, at the time of
@@ -2780,7 +2572,6 @@
=back
-
C<BEGIN> blocks in C<Apache::Registry> scripts will be executed, as
above plus:
@@ -2810,18 +2601,7 @@
=back
Make sure you read L<Evil things might happen when using
-PerlFreshRestart|troubleshooting/Evil_things_might_happen_when_us>.
-
-
-
-
-
-
-
-
-
-
-
+PerlFreshRestart|guide::troubleshooting/Evil_things_might_happen_when_us>.
=head1 END blocks
@@ -2854,7 +2634,7 @@
used to emulate plain perl's C<END{}> block behavior.
The last paragraph is very important for handling the case of L<'User
-Pressed the Stop Button'|debug/Handling_the_User_pressed_Stop_>.
+Pressed the Stop Button'|guide::debug/Handling_the_User_pressed_Stop_>.
If you only want something to run once in the parent on shutdown or
restart you can use C<$r-E<gt>register_cleanup()> in the I<startup.pl>.
@@ -2881,11 +2661,6 @@
% perl -e 'eval qq(CHECK { print "ok\n" })'
-
-
-
-
-
=head1 Command Line Switches (-w, -T, etc)
Normally when you run perl from the command line, you have the shell
@@ -3000,8 +2775,6 @@
the C<PerlTaintCheck> configuration directive and will otherwise
ignore it.
-
-
=head2 Other switches
Finally, if you still need to set additional perl startup flags
@@ -3017,17 +2790,7 @@
[META: verify]
See also
-L<Apache::PerlRun|modules/Apache__PerlRun___Run_unaltered_CGI_scripts_under_mod_perl>.
-
-
-
-
-
-
-
-
-
-
+L<Apache::PerlRun|guide::modules/Apache__PerlRun___Run_unaltered_CGI_scripts_under_mod_perl>.
=head1 The strict pragma
@@ -3050,18 +2813,6 @@
time. And, of course, clean scripts will still run under mod_cgi
(plain CGI)!
-
-
-
-
-
-
-
-
-
-
-
-
=head1 Passing ENV variables to CGI
To pass an environment variable from I<httpd.conf>, add to it:
@@ -3100,15 +2851,9 @@
}
</Perl>
-See also L<PerlSetupEnv|performance/PerlSetupEnv_Off> which can
+See also L<PerlSetupEnv|guide::performance/PerlSetupEnv_Off> which can
enable/disable environment variables settings.
-
-
-
-
-
-
=head1 -M and other time() file tests under mod_perl
Under mod_perl, files that have been created after the server's
@@ -3141,31 +2886,15 @@
system call, and uses the already available time of the request has
been started at via C<$r-E<gt>request_time> method.
-
-
-
-
-
-
-
-
-
-
-
-
-
=head1 Apache and syslog
When native syslog support is enabled, the stderr stream will be
redirected to C</dev/null>!
It has nothing to do with mod_perl (plain Apache does the same). Doug
-wrote the
L<Apache::LogSTDERR|porting/CGI_to_mod_perl_Porting__mod_perl_Coding_guidelines__>
module to work
+wrote the
L<Apache::LogSTDERR|guide::porting/CGI_to_mod_perl_Porting__mod_perl_Coding_guidelines__>
module to work
around this.
-
-
-
=head1 File tests operators
Remember that with mod_perl you might get negative times when you use
@@ -3184,11 +2913,6 @@
META: Above is near duplicate of "-M and other time() file tests under
mod_perl"
make a link instead
-
-
-
-
-
=head1 Filehandlers and locks leakages
META: duplication at
@@ -3211,7 +2935,7 @@
Even if you do call close(), if for some reason the interpreter
was stopped before the C<close()> call, the leakage will still happen.
See for example L<Handling the 'User pressed Stop button'
-case|debug/Handling_the_User_pressed_Stop_>. After a long run without
+case|guide::debug/Handling_the_User_pressed_Stop_>. After a long run without
restarting Apache your machine might run out of file descriptors, and
worse, files might be left locked and unusable.
@@ -3252,25 +2976,13 @@
open my $fh, $filename or die $! ;
-
-
-
-
-
-
-
-
-
=head1 Code has been changed, but it seems the script is running the old code
Files pulled in via B<use> or B<require> statements are not
automatically reloaded when they change on disk. See L<Reloading Modules
-and Required Files|porting/Reloading_Modules_and_Required_F> for more
+and Required Files|guide::porting/Reloading_Modules_and_Required_F> for more
info.
-
-
-
=head1 The Script Is Too Dirty, But It Does The Job And I Cannot Afford To
Rewrite It.
You still can win from using mod_perl.
@@ -3291,7 +3003,7 @@
PerlSendHeader On
</Location>
-See L<Apache::PerlRun--a closer look|porting/Apache__PerlRun__a_closer_look>
+See L<Apache::PerlRun--a closer
look|guide::porting/Apache__PerlRun__a_closer_look>
Another "bad", but workable method is to set C<MaxRequestsPerChild> to
1, which will force each child to exit after serving only one request.
@@ -3303,17 +3015,6 @@
than actually required and the killed one will immediately be replaced
with a fresh one. Probably that's not what you want.
-
-
-
-
-
-
-
-
-
-
-
=head1 Apache::PerlRun--a closer look
C<Apache::PerlRun> gives you the benefit of preloaded Perl and its
@@ -3370,19 +3071,6 @@
logs its messages to the I<error_log> file, so you should expect the
output there and not together with STDOUT.
-
-
-
-
-
-
-
-
-
-
-
-
-
=head1 Sharing variables between processes
META: to be completed
@@ -3417,9 +3105,6 @@
=back
-
-
-
=head1 Transitioning from Apache::Registry to Apache handlers
Even if you are a CGI script die-hard at some point you might want to
@@ -3529,7 +3214,6 @@
return scalar localtime;
} # end of sub generate_sessionID
-
The code is very simple. It creates a session if you've pressed the
I<'Start'> button or deletes it if you've pressed the I<'Stop'>
button. The session is stored and retrieved using the cookies
@@ -3555,8 +3239,6 @@
unique session every time it was called. And it should be secure,
i.e. users will not be able to forge one and do nasty things.
-
-
=head2 Converting into Perl Content Handler
Now let's convert this script into a content handler. There are two
@@ -3720,7 +3402,6 @@
}
1;
-
and now we have a fully fledged Perl Content Handler.
=head2 Converting to use Apache Perl Modules
@@ -3730,10 +3411,9 @@
better performance, mainly because the internals of many of these Perl
modules are implemented in C, therefore we should get a significant
improvement in speed. The section "L<TMTOWTDI: Convenience and
-Performance|performance/TMTOWTDI_Convenience_and_Habit_>"
+Performance|guide::performance/TMTOWTDI_Convenience_and_Habit_>"
compares the three approaches.
-
What we are going to do is to replace C<CGI.pm> and C<CGI::Cookie>
with C<Apache::Request> and C<Apache::Cookie> respectively. The two
modules are written in C with the XS interface to Perl, which makes
@@ -3903,15 +3583,11 @@
the file I</home/httpd/perl/Test/Cookie2.pm> since we have called this
package C<Test::Cookie2>.
-
=head2 Conclusion
If your took care to write the original plain CGI script's code in a
clean and modular way, you can see that the transition is a very
simple one and doesn't take a lot of effort. Almost no code was
modified.
-
-
-
=cut
1.4 +15 -64 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.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- scenario.pod 21 Feb 2002 09:08:38 -0000 1.3
+++ scenario.pod 27 Feb 2002 18:03:36 -0000 1.4
@@ -86,7 +86,7 @@
There are many additional optional parameters. You can find some of
them later in this section and in the L<Server
-Configuration|config/mod_perl_Configuration> section.
+Configuration|guide::config/mod_perl_Configuration> section.
While running C<perl Makefile.PL ...> the process will check for
prerequisites and tell you if something is missing. If you are
@@ -122,7 +122,6 @@
Now the build and installation processes are complete.
-
=head2 Configuration
First, a simple configuration. Configure Apache as you usually would
@@ -239,14 +238,13 @@
degree of sloppiness they may need anything from minor tweaking to a
major rewrite to make them work properly. (See L<Sometimes My Script
Works, Sometimes It Does
-Not|debug/Sometimes_My_Script_Works__Sometimes_It_Does_Not> )
+Not|guide::debug/Sometimes_My_Script_Works__Sometimes_It_Does_Not> )
The above setup is very basic, but as with Perl, you can start to
benefit from mod_perl from the very first moment you try it. As you
become more familiar with mod_perl you will want to start writing
Apache handlers and make more use of its power.
-
=head1 One Plain and One mod_perl enabled Apache Servers
Since we are going to run two Apache servers we will need two complete
@@ -384,7 +382,6 @@
configuration and the manual executable name adjustment as described
at the beginning of this section .
-
=head3 Building the httpd_perl Server
Now we proceed with the sources configuration and installation of the
@@ -429,7 +426,7 @@
[META:
It's very important to use the same compiler you build the perl with.
See the section 'L<What Compiler Should Be Used to Build
-mod_perl|install/What_Compiler_Should_Be_Used_to_Build_mod_perl_>'
+mod_perl|guide::install/What_Compiler_Should_Be_Used_to_Build_mod_perl_>'
for more information.
[META: --- Hmm, what's the option that overrides the compiler when
@@ -458,12 +455,12 @@
If C<make test> fails, look into
I</usr/src/httpd_perl/mod_perl-x.xx/t/logs> and read the error_log
-file. Also see L<make test fails|install/make_test_fails>.
+file. Also see L<make test fails|guide::install/make_test_fails>.
While doing C<perl Makefile.PL ...> mod_perl might complain by warning
you about a missing library C<libgdbm>. This is a crucial warning. See
L<Missing or Misconfigured
-libgdbm.so|install/Missing_or_Misconfigured_libgdbm_so> for more info.
+libgdbm.so|guide::install/Missing_or_Misconfigured_libgdbm_so> for more info.
Now rename C<httpd> to C<httpd_perl>:
@@ -475,11 +472,6 @@
% perl -p -i -e 's|bin/httpd|bin/httpd_perl|' \
/usr/local/httpd_perl/bin/apachectl
-
-
-
-
-
=head2 Configuration of the servers
Now when we have completed the building process, the last stage before
@@ -499,7 +491,6 @@
/usr/local/httpd_docs/bin/apachectl start
-
=head3 Basic httpd_perl Server Configuration
Edit the I</usr/local/httpd_perl/conf/httpd.conf>. As with the
@@ -525,12 +516,12 @@
server like Squid.
For more details see L<Publishing Port Numbers other than
-80|config/Publishing_Port_Numbers_other_than_80>, L<Running One Webserver
+80|guide::config/Publishing_Port_Numbers_other_than_80>, L<Running One
Webserver
and Squid in httpd Accelerator
-Mode|scenario/Running_One_Webserver_and_Squid_in_httpd_Accelerator_Mode>,
+Mode|guide::scenario/Running_One_Webserver_and_Squid_in_httpd_Accelerator_Mode>,
L<Running Two Webservers and Squid in httpd Accelerator
-Mode|scenario/Running_Two_webservers_and_Squid_in_httpd_Accelerator_Mode>
-and L<Using mod_proxy|scenario/mod_proxy>.
+Mode|guide::scenario/Running_Two_webservers_and_Squid_in_httpd_Accelerator_Mode>
+and L<Using mod_proxy|guide::scenario/mod_proxy>.
Now we proceed to the mod_perl specific directives. It will be a good
idea to add them all at the end of C<httpd.conf>, since you are going
@@ -577,18 +568,17 @@
nph (non-parsed-headers) scripts.
This is only a very basic configuration. The L<Server
-Configuration|config/> section covers the rest of the details.
+Configuration|guide::config/> section covers the rest of the details.
Now start the server with:
/usr/local/httpd_perl/bin/apachectl start
-
=head1 Running Two webservers and Squid in httpd Accelerator Mode
While I have detailed the mod_perl server installation, you are on
your own with installing the Squid server (See L<Getting
-Helped|help/> for more details).
+Helped|guide::help/> for more details).
I run Linux, so I downloaded the RPM package, installed it, configured
the I</etc/squid/squid.conf>, fired off the server and all was set.
@@ -709,7 +699,7 @@
But this is only possible if you set the headers correctly. Refer to
the chapter L<Correct Headers - A quick guide for mod_perl
-users|correct_headers/> to learn more about generating the proper
+users|guide::correct_headers/> to learn more about generating the proper
caching headers under mod_perl. In case where only the scripts under
I</perl/caching-unfriendly> are not I<caching friendly> fix the above
setting to be:
@@ -720,7 +710,7 @@
But if you are lazy, or just have too many things to deal with, you
can leave the above directives the way we described. Just keep in
mind that one day you will want to reread this section and L<the
-headers generation tutorial|correct_headers/> to squeeze even more
+headers generation tutorial|guide::correct_headers/> to squeeze even more
power from your servers without investing money in more memory and
better hardware.
@@ -1035,9 +1025,6 @@
cachemgr_passwd disable shutdown
-
-
-
=head1 mod_proxy
mod_proxy implements a proxy/cache for Apache. It implements proxying
@@ -1127,8 +1114,6 @@
directives.) Do not use the C<ProxyRequests> directive on your
reverse proxy servers.
-
-
=head2 Buffering Feature
In addition to correcting the URI on its way back from the back-end
@@ -1199,7 +1184,6 @@
seems to be the best solution for these specific scripts whose major
function is receiving large amounts of upstream data.
-
[META: check this: --]
Of course just like mod_perl, mod_proxy writes the data it
@@ -1230,7 +1214,6 @@
returns the success of data transmission. (The last, is the part I am
not sure on)
-
[/META]
Unfortunately you cannot set the socket buffer size as large as you
@@ -1326,7 +1309,6 @@
When you tell the kernel to use bigger sockets you can set bigger
values for I<ProxyReceiveBufferSize>. e.g. 1048576 (1MB).
-
=head3 Hacking the Code
Some folks have patched the Apache's 1.3.x source code to make the
@@ -1358,8 +1340,6 @@
C<ProxySocketBufferSize>. This would also remove some of the
confusion about what it actually does.
-
-
=head2 Caching Feature
META: complete the conf details
@@ -1369,8 +1349,6 @@
the Apache documentation for more details on the configuration of this
capability.
-
-
=head2 Build Process
To build mod_proxy into Apache just add I<--enable-module=proxy>
@@ -1378,8 +1356,6 @@
the mod_rewrite capability enable it as well with
I<--enable-module=rewrite>.
-
-
=head1 Front-end Back-end Proxying with Virtual Hosts
This section explains a configuration setup for proxying your back-end
@@ -1469,7 +1445,7 @@
the back-end port.
To get the I<real> remote IP addresses from proxy, the
-L<My::ProxyRemoteAddr|scenario/Getting_the_Remote_Server_IP_in_the_Back_end_server_in_the_Proxy_Setup>
+L<My::ProxyRemoteAddr|guide::scenario/Getting_the_Remote_Server_IP_in_the_Back_end_server_in_the_Proxy_Setup>
handler is used based on the C<mod_proxy_add_forward> Apache module.
Prior to mod_perl 1.22 this setting must have been set per-virtual
host, since it wasn't inherited by the virtual hosts.
@@ -1488,13 +1464,12 @@
by the front-end as we did in the previous example to handle files
with the extensions I<.gif>, I<.jpg>, I<.png> and I<.txt> internally.
-
=head1 Getting the Remote Server IP in the Back-end server in the Proxy Setup
Ask Bjoern Hansen has written the C<mod_proxy_add_forward> module for
Apache. It sets the C<X-Forwarded-For> field when doing a
C<ProxyPass>, similar to what Squid can do. Its location is specified
-in the L<download|download/mod_proxy_add_forward> section.
+in the L<download|guide::download/mod_proxy_add_forward> section.
Basically, this module adds an extra HTTP header to proxying requests.
You can access that header in the mod_perl-enabled server, and set the
@@ -1516,7 +1491,6 @@
I<--enable-module=proxy_add_forward> enables this module as you have
guessed already.
-
=head2 Usage
If you are using C<Apache::Registry> or C<Apache::PerlRun> modules
@@ -1548,7 +1522,6 @@
Otherwise if you write your own mod_perl content handler, you can
retrieve it directly in your code using a similar code.
-
=head2 Security
Different sites have different needs. If you use the header to set
@@ -1652,11 +1625,6 @@
the back-end server, and the remote IP appears in the back-end
server's I<access_log> file.
-
-
-
-
-
=head1 HTTP Authentication With Two Servers Plus a Proxy
Assuming that you have a setup of one "front-end" server, which
@@ -1678,19 +1646,6 @@
the SSL requests. So if your machine is secured from inside, your
back-end server can do secure transactions.
-
-
-
-
-
-
-
-
-
-
-
-
-
=head1 mod_rewrite Examples
In the mod_proxy + mod_perl servers scenario, C<ProxyPass> was used to
@@ -1777,10 +1732,6 @@
RewriteRule ^/(images|style) - [L]
RewriteRule ^/(.*) http://www.example.com:8080/$1 [P]
ProxyPassReverse / http://www.example.com/
-
-
-
-
=head1 Caching in mod_proxy
1.2 +2 -7 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.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- security.pod 6 Jan 2002 16:54:56 -0000 1.1
+++ security.pod 27 Feb 2002 18:03:36 -0000 1.2
@@ -29,9 +29,9 @@
When you want to make sure that a user is who he claims to be, you
generally ask her for a username and a password. Once you have both,
you can check them against your L<database of username/password
-pairs|databases/>. If they match, the user has passed the
+pairs|guide::databases/>. If they match, the user has passed the
B<Authentication> stage. From now on if you keep the
-L<session|modules/Apache__Session___Maintain_session_state_across_HTTP_requests>
open all you need to
+L<session|guide::modules/Apache__Session___Maintain_session_state_across_HTTP_requests>
open all you need to
do is to remember the username.
=item Authorization
@@ -46,7 +46,6 @@
session_ids can be spoofed (forged), and that is why you should not do
B<Authorization> without B<Authentication>.
-
=back
Actually you've been familiar with both these concepts for a while.
@@ -58,7 +57,6 @@
checks the permissions on this file (B<Authorization>). You may hear
about B<Access control> which is another name for the same thing.
-
=head1 Illustrated Security Scenarios
I am going to present some real world security requirements and their
@@ -167,7 +165,6 @@
to OK, and the Authentication stage will ask the user for a login and
password.
-
=head1 Authentication code snippets
=head2 Forcing re-authentication
@@ -191,7 +188,6 @@
This may not work! The browser's behaviour is in no way guaranteed.
-
=head2 OK, AUTH_REQUIRED and FORBIDDEN in Authentication handlers
When your authentication handler returns OK, it means that user has
@@ -233,7 +229,6 @@
$r->custom_response(SERVER_ERROR, "/errors/suspended_account.html");
return FORBIDDEN if $suspended;
-
=head1 Apache:Auth* modules
1.3 +1 -124 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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- snippets.pod 4 Feb 2002 13:50:25 -0000 1.2
+++ snippets.pod 27 Feb 2002 18:03:36 -0000 1.3
@@ -2,7 +2,6 @@
Code Snippets
-
=head1 Redirecting Errors to the Client Instead of error_log
Many error conditions result in an I<exception> (or I<signal> -- same
@@ -22,7 +21,7 @@
information to the client instead of to I<error_log> you have to take
the responsibility yourself, by writing your own exception handler to
implement this behaviour. See the section "L<Exception Handling for
-mod_perl|perl/Exception_Handling_for_mod_perl>" for more information.
+mod_perl|guide::perl/Exception_Handling_for_mod_perl>" for more information.
The code examples below can be useful with your own exception handlers
as well as with the default handlers.
@@ -190,10 +189,6 @@
Please note that as of version 2.49, CGI.pm provides the cgi_error()
method to print the errors and won't die() unless you want it to.
-
-
-
-
=head1 Reusing Data from POST request
What happens if you need to access the POSTed data more than once, say
@@ -256,10 +251,6 @@
C<Apache::Request>-E<gt>instance() within a single request you always
get the same C<Apache::Request> object back.
-
-
-
-
=head1 Redirecting POST Requests
Under mod_cgi it's not easy to redirect POST requests to some other
@@ -279,7 +270,6 @@
Of course that last line can be any other kind of redirect.
-
=head1 Redirecting While Maintaining Environment Variables
Let's say you have a module that sets some environment variables.
@@ -293,18 +283,6 @@
subprocess_env(). The only nuance is that the C<%ENV> keys will be
prefixed with C<REDIRECT_>.
-
-
-
-
-
-
-
-
-
-
-
-
=head1 Terminating a Child Process on Request Completion
If you want to terminate the child process serving the current
@@ -315,8 +293,6 @@
Apache won't actually terminate the child until everything it needs to
do is done and the connection is closed.
-
-
=head1 Setting Content-type and Content-encoding headers in non-OK responses
You cannot set I<Content-type> and I<Content-encoding> headers in
@@ -325,7 +301,6 @@
r->content_type = "text/html; charset=iso-8859-1";
-
=head1 More on Relative Paths
Many people use relative paths for C<require>, C<use>, etc., and when
@@ -363,16 +338,6 @@
will use the cached value, which would be probably incorrect if they
reside in different directories.
-
-
-
-
-
-
-
-
-
-
=head1 Watching the error_log File Without Telneting to the Server
I wrote this script a long time ago, when I had to debug my CGI
@@ -469,10 +434,6 @@
: $context;
}
-
-
-
-
=head1 Accessing Variables from the Caller's Package
Sometimes you want to access variables from the caller's
@@ -484,10 +445,6 @@
print qq[$caller --- ${"${caller}::var"}];
}
-
-
-
-
=head1 Handling Cookies
Unless you use some well known module like C<CGI::Cookie> or
@@ -520,12 +477,6 @@
}
-
-
-
-
-
-
=head1 Sending Multiple Cookies with the Perl API
Given that you have prepared your cookies in C<@cookies>, the
@@ -535,8 +486,6 @@
$r->headers_out->add( 'Set-Cookie' => $_ );
}
-
-
=head1 Sending Cookies in REDIRECT Response
You should use err_headers_out() and not headers_out() when you want
@@ -551,9 +500,6 @@
$r->send_http_header;
return OK;
-
-
-
=head1 Passing and Preserving Custom Data Structures Between Handlers
Let's say that you wrote a few handlers to process a request, and they
@@ -578,12 +524,6 @@
The stored information will be destroyed at the end of the request.
-
-
-
-
-
-
=head1 Passing Notes Between mod_perl and other (non-Perl) Apache Modules
The notes() method can be used to make various Apache modules talk to
@@ -639,7 +579,6 @@
$r->main->notes('answer');
-
=head1 Passing Environment Variables Between Handlers
This is a simple example of passing environment variables between
@@ -668,7 +607,6 @@
Adding C<%{TICKET}e> and C<%{TICKET}n> to the C<LogFormat> for
access_log works fine too.
-
=head1 Verifying Whether A Request Was Received Over An SSL Connection
Just like C<$ENV{MODPERL}> is checked to see whether the code is run
@@ -692,7 +630,6 @@
but it's not one hundred percent certain unless you control the server
and you know that you run a secure server on the port 443.
-
=head1 CGI::params in the mod_perl-ish Way
You can retrieve the request parameters in a similar to C<CGI::params>
@@ -706,12 +643,6 @@
Also take a look at C<Apache::Request> which has the same API as
C<CGI.pm> for extracting and setting request parameters.
-
-
-
-
-
-
=head1 Subclassing Apache::Request
To subclass a package you simply modify @ISA, for example:
@@ -748,15 +679,6 @@
1;
__END__
-
-
-
-
-
-
-
-
-
=head1 Sending Email from mod_perl
There is nothing special about sending email from mod_perl, it's just
@@ -846,13 +768,6 @@
} # end of sub send_mail
-
-
-
-
-
-
-
=head1 A Simple Handler To Print The Environment Variables
The code:
@@ -880,11 +795,6 @@
http://localhost/env
-
-
-
-
-
=head1 mod_rewrite in Perl
We can easily implement everything mod_rewrite does in Perl. We do
@@ -926,8 +836,6 @@
C<$uri> will hold I<http://www2.example.com/news/> and that's where
the request will be redirected.
-
-
=head1 URI Rewrite in PerlTransHandler
Suppose that before a content handler is invoked you want to make this
@@ -967,7 +875,6 @@
separate slot, so you cannot just push them into the original
URI. Therefore the args() method should be used.
-
=head1 Setting PerlHandler Based on MIME Type
It's very easy to implement a dispatching module based on the MIME
@@ -1005,10 +912,6 @@
the end we return C<DECLINED> so some other fixup handler could take
over.
-
-
-
-
=head1 SSI and Embperl -- Doing Both
This handler lets you use both SSI and Embperl in the same request:
@@ -1021,7 +924,6 @@
PerlHandler Apache::EmbperlFilter Apache::SSI
</FilesMatch>
-
package Apache::EmbperlFilter;
use Apache::Util qw(parsedate);
@@ -1066,14 +968,6 @@
1;
__END__
-
-
-
-
-
-
-
-
=head1 Getting the Front-end Server's Name in the Back-end Server
Assume that you have more than one front-end server, and you want to
@@ -1096,8 +990,6 @@
sort, but if query string is good enough for you, then this should
work really nicely.
-
-
=head1 Authentication Snippets
Getting the authenticated username: C<$r-E<gt>connection-E<gt>user()>,
@@ -1112,7 +1004,6 @@
my $user = $r->connection->user;
-
=head1 Emulating the Authentication Mechanism
You can provide your own mechanism to authenticate users, instead of
@@ -1125,10 +1016,6 @@
that you can have your "username" passed as if it was transmitted to
Apache through HTTP authentication.
-
-
-
-
=head1 An example of using Apache::Session::DBI with cookies
META: should be annotated at some point. (an example was posted to the
@@ -1172,7 +1059,6 @@
}
-
=head1 Using DESTROY to Finalize Output
Well, as always with Perl -- TMTOWTDI (There's More Than One Way To Do
@@ -1307,8 +1193,6 @@
After all, it's a little awkward to need a C<LogHandler> to clean up
after ourselves....
-
-
=head1 Setting Environment Variables For Scripts Called From CGI.
Perl uses C<sh()> for its C<system()> and C<open()> calls. So if you
@@ -1337,8 +1221,6 @@
containing a subroutine which you can then call directly from your
mod_perl script.
-
-
=head1 Mysql Backup and Restore Scripts
This is somewhat off-topic, but since many of us use mysql or some
@@ -1366,7 +1248,6 @@
=code mysql-3.22.30+_backup.pl This is the code modified to work with
mysql-3.22.30+
-
You might need to change the executable paths according to your
system. List the names of the databases you want to backup using
the C<db_names> array.
@@ -1397,9 +1278,5 @@
that can make an atomic snapshot of a database. (by Tim Bunce) So you
may consider using it instead.
-
=cut
-
-
-
1.3 +26 -30 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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- start.pod 4 Feb 2002 13:50:25 -0000 1.2
+++ start.pod 27 Feb 2002 18:03:36 -0000 1.3
@@ -8,36 +8,36 @@
overall picture of this wonderful technology. There is more than one
way to use a mod_perl-enabled webserver. You have to decide which
mod_perl scheme you want to use. L<Picking the Right
-Strategy|strategy/> chapter presents various approaches and discusses
+Strategy|guide::strategy/> chapter presents various approaches and discusses
their pros and cons.
Once you know what best fits your requirements, you should proceed
-to L<Real World Scenarios Implementation|scenario/>. This chapter
+to L<Real World Scenarios Implementation|guide::scenario/>. This chapter
provides very detailed scenarios of the schemes discussed in the
-L<Choosing the Right Strategy|strategy/> chapter.
+L<Choosing the Right Strategy|guide::strategy/> chapter.
-The L<Server Installation|install/> chapter follows on from the L<Real
-World Scenarios Implementation|scenario/> chapter by providing more
+The L<Server Installation|guide::install/> chapter follows on from the L<Real
+World Scenarios Implementation|guide::scenario/> chapter by providing more
in-depth installation details.
-The L<Server Configuration|config/> chapter adds to the basic
+The L<Server Configuration|guide::config/> chapter adds to the basic
configurations presented in the L<Real World Scenarios
-Implementation|scenario/> chapter with extended configurations and
+Implementation|guide::scenario/> chapter with extended configurations and
various configuration examples.
-The L<Frequent mod_perl problems|frequent/> chapter is a collection of
+The L<Frequent mod_perl problems|guide::frequent/> chapter is a collection of
links to other chapters. It is an attempt to stress some of the most
frequently encountered mod_perl problems. So this is the first place
you should check if you have got a problem.
Probably the most important chapter is L<CGI to mod_perl
-Porting. mod_perl Coding guidelines|porting/>. It explains the
+Porting. mod_perl Coding guidelines|guide::porting/>. It explains the
differences between scripts running under mod_cgi and mod_perl, and
what should be done in order to make existing scripts run under
mod_perl. Along with the porting notes it provides guidelines for
proper mod_perl programming.
-L<Performance. Benchmarks|performance/> is the biggest and a very
+L<Performance. Benchmarks|guide::performance/> is the biggest and a very
important chapter. It explains the details of tuning mod_perl and the
scripts running under it, so you can squeeze every ounce of the power
from your server. A large part of the chapter is benchmarks, the
@@ -54,37 +54,37 @@
all the intimate details of what is happening to your scripts. But
the problem is that it speaks a secret language. To learn the alphabet
and the grammar of this language, refer to the chapter L<Warnings and
-Errors: Where and Why|troubleshooting/>.
+Errors: Where and Why|guide::troubleshooting/>.
-L<Protecting Your Site|security/> - All about security.
+L<Protecting Your Site|guide::security/> - All about security.
If you are into driving relational databases with your cgi scripts,
-the L<mod_perl and Relational Databases|databases/> chapter will tell
+the L<mod_perl and Relational Databases|guide::databases/> chapter will tell
you all about the database-related goodies mod_perl has prepared for
you.
If you are using good old dbm files for your databases, the L<mod_perl
-and dbm files|dbm/> chapter explains how to utilize them better under
+and dbm files|guide::dbm/> chapter explains how to utilize them better under
mod_perl.
More and more Internet Service Providers (ISPs) are evaluating the
possibility of providing mod_perl services to their users. Is this
possible? Is it secure? Will it work? What resources does it take?
-The L<mod_perl for ISPs. mod_perl and Virtual Hosts|multiuser/>
+The L<mod_perl for ISPs. mod_perl and Virtual Hosts|guide::multiuser/>
chapter answers all these questions. If you want to run a mod_perl-
enabled server, but do not have root access, read this chapter as
well, either to learn how to do it yourself, or maybe to persuade your
ISP to provide this service.
If you have to administer your Apache mod_perl server the
-L<Controlling and Monitoring the Server|control/> chapter is for
+L<Controlling and Monitoring the Server|guide::control/> chapter is for
you. Among the topics are: server restarting and monitoring
techniques, preventing the server from eating up all your disk space
in a matter of minutes, and more.
(META: fix this)
The L<mod_perl Status. Peeking into the Server's Perl
-Innards|config/mod_perl_Configuration> chapter shows you the ways you
+Innards|guide::config/mod_perl_Configuration> chapter shows you the ways you
can peek at what is going on in a mod_perl-enabled server while it is
running. Like looking at the value of some global variable, what
database connections are open, looking up what modules are loaded and
@@ -95,16 +95,16 @@
flag and debug it. Is it possible to do the same under mod_perl? After
all you cannot debug every CGI script by executing it from the command
line: some scripts will not run from the command line. The L<Debugging
-mod_perl|debug/> chapter proves debugging under mod_perl is possible.
+mod_perl|guide::debug/> chapter proves debugging under mod_perl is possible.
Sometimes browsers that interact with our servers have bugs, which
cause big headaches for CGI developers. Coping with these bugs
is discussed in the L<Workarounds for some known bugs in
-browsers|browserbugs/> chapter.
+browsers|guide::browserbugs/> chapter.
Many modules were written to extend mod_perl's core
functionality. Some important modules are covered in the L<Apache::*
-modules|modules/> chapter.
+modules|guide::modules/> chapter.
Some folks decide to go with mod_perl even though they are not
experienced Perl programmers. mod_perl is a demanding environment
@@ -113,31 +113,27 @@
barrier; Perl comes with copious and high quality on-line
documentation and there are many Perl books available which will get
you up to speed. Get a good Perl book and start reading. The L<Perl
-Reference|perl/> chapter gives some basic, mod_perl specific Perl
+Reference|guide::perl/> chapter gives some basic, mod_perl specific Perl
lessons, delivering the knowledge without which you cannot start to
program mod_perl scripts.
-The L<Code Snippets|snippets/> chapter is just a collection of code
+The L<Code Snippets|guide::snippets/> chapter is just a collection of code
snippets I have found useful while writing the scripts.
-The L<Choosing an Operating System and Hardware|hardware/> chapter
+The L<Choosing an Operating System and Hardware|guide::hardware/> chapter
gives you an idea on how to choose the software and hardware for the
webserver.
-The L<mod_perl Advocacy|advocacy/> tries to make it easier to advocate
+The L<mod_perl Advocacy|guide::advocacy/> tries to make it easier to advocate
mod_perl around the world.
-The L<Getting Help and Further Learning|help/> chapter refers you to
+The L<Getting Help and Further Learning|guide::help/> chapter refers you to
other related information resources, like learning Perl programming
and SQL, understanding security, building databases, and more.
-L<Appendix A: Downloading software and documentation|download/>
+L<Appendix A: Downloading software and documentation|guide::download/>
includes pointers to the software that was explained and/or mentioned
in this guide.
=cut
-
-
-
-
1.2 +14 -72 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.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- strategy.pod 6 Jan 2002 16:54:56 -0000 1.1
+++ strategy.pod 27 Feb 2002 18:03:36 -0000 1.2
@@ -38,11 +38,6 @@
=back
-
-
-
-
-
=head1 mod_perl Deployment Overview
There are several different ways to build, configure and deploy your
@@ -115,12 +110,10 @@
The DSO module (C<mod_so>) adds size and complexity to your binaries.
Refer to the section L<"Pros and Cons of Building mod_perl as
-DSO|install/Pros_and_Cons_of_Building_mod_pe"> for more information.
+DSO|guide::install/Pros_and_Cons_of_Building_mod_pe"> for more information.
Build details: L<Build mod_perl as DSO inside Apache source tree via
-APACI|install/Build_mod_perl_as_a_DSO_inside_t>
-
-
+APACI|guide::install/Build_mod_perl_as_a_DSO_inside_t>
=item 4
@@ -130,18 +123,11 @@
=back
-
-
-
-
-
-
-
=head1 Alternative architectures for running one and two servers
The next part of this chapter discusses the pros and the cons of each
of these presented configurations. L<Real World Scenarios
-Implementation|scenario/> describes the implementation techniques of
+Implementation|guide::scenario/> describes the implementation techniques of
these schemes.
We will look at the following installations:
@@ -158,7 +144,6 @@
=back
-
=head2 Standalone mod_perl Enabled Apache Server
The first approach is to implement a straightforward mod_perl
@@ -248,11 +233,9 @@
for you!
For implementation notes, see the "L<One Plain and One mod_perl
-enabled Apache Servers|scenario/One_Plain_and_One_mod_perl_enabl>"
+enabled Apache Servers|guide::scenario/One_Plain_and_One_mod_perl_enabl>"
section in the implementations chapter.
-
-
=head2 One Plain Apache and One mod_perl-enabled Apache Servers
As I have mentioned before, when running scripts under mod_perl you
@@ -310,8 +293,7 @@
hide the internal port implementations, so the client sees only one
server running on port C<80>. (See L<Publishing Port Numbers other
than
-80|config/Publishing_Port_Numbers_other_th>)
-
+80|guide::config/Publishing_Port_Numbers_other_th>)
The disadvantages:
@@ -355,10 +337,10 @@
Before you go on with this solution you really want to look at the
L<Adding a Proxy Server in http Accelerator
-Mode|strategy/Adding_a_Proxy_Server_in_http_Ac> section.
+Mode|guide::strategy/Adding_a_Proxy_Server_in_http_Ac> section.
For implementation notes see the "L<One Plain and One mod_perl enabled
-Apache Servers|scenario/One_Plain_and_One_mod_perl_enabl>" section in
+Apache Servers|guide::scenario/One_Plain_and_One_mod_perl_enabl>" section in
implementations chapter.
=head2 One light non-Apache and One mod_perl enabled Apache Servers
@@ -370,7 +352,6 @@
since it is very simple and uses almost no memory (260K) and does not
spawn child processes.
-
The Advantages:
=over 4
@@ -400,7 +381,6 @@
=back
-
The Disadvantages:
=over 4
@@ -412,7 +392,6 @@
=back
-
Another interesting choice is a kHTTPd webserver for Linux. kHTTPd is
different from other webservers in that it runs from within the
Linux-kernel as a module (device-driver). kHTTPd handles only static
@@ -422,8 +401,6 @@
Also check out the Boa webserver: http://www.boa.org/
-
-
=head1 Adding a Proxy Server in http Accelerator Mode
At the beginning there were two servers: one plain Apache server,
@@ -532,7 +509,7 @@
and therefore will not be discussed here. There is a plenty of
information available at the Internet though. For more information see
L<'High-Availability Linux
-Project'|download/High_Availability_Linux_Project>)
+Project'|guide::download/High_Availability_Linux_Project>)
=item *
@@ -601,7 +578,6 @@
Chapter on page XXX (mod_proxy_add_forward) we present a solution for
this problem.
-
=back
Have I succeeded in convincing you that you want a proxy server?
@@ -612,7 +588,6 @@
feeding a slow client is gone. You are probably better off sticking
with a straight mod_perl server in this case.
-
=head1 Implementations of Proxy Servers
As of this writing, two proxy implementations are known to be widely
@@ -698,12 +673,11 @@
For implementation details, see the sections L<Running One Webserver
and Squid in httpd Accelerator
-Mode|scenario/Running_One_Webserver_and_Squid_> and L<Running Two
+Mode|guide::scenario/Running_One_Webserver_and_Squid_> and L<Running Two
Webservers and Squid in httpd Accelerator
-Mode|scenario/Running_Two_webservers_and_Squid> in the implementations
+Mode|guide::scenario/Running_Two_webservers_and_Squid> in the implementations
chapter.
-
=head2 Apache's mod_proxy
I do not think the difference in speed between Apache's B<mod_proxy>
@@ -725,7 +699,6 @@
already sent, so that it does not change in the client's B<Location>
window.
-
The Advantages:
=over 4
@@ -752,7 +725,7 @@
=item *
It does mod_perl output buffering like squid does. See the L<Using
-mod_proxy|scenario/mod_proxy> notes for more details.
+mod_proxy|guide::scenario/mod_proxy> notes for more details.
=item *
@@ -780,10 +753,9 @@
=back
For implementation see the "L<Using
-mod_proxy|scenario/mod_proxy>" section in the
+mod_proxy|guide::scenario/mod_proxy>" section in the
implementation chapter.
-
=head2 Closing Lingering Connections with Lingerd
Because of some technical complications in TCP/IP, at the end of each
@@ -824,9 +796,6 @@
For more information about C<lingerd> see:
http://www.iagora.com/about/software/lingerd/
-
-
-
=head1 When One Machine is not Enough for RDBMS Database and mod_perl
Imagine a scenario where you start your business as a small service
@@ -894,7 +863,6 @@
some heavy Java applets, but that movie is screened in another
theater.
-
=head2 Servers' Requirements
Let's first understand what kind of software the web and database
@@ -927,7 +895,6 @@
small amounts (otherwise)
* CPU: medium to high (according to needs)
-
=head2 The Problem
With the database and the httpd on the same machine, you have
@@ -965,7 +932,6 @@
process is getting 99.9% CPU time, and the kernel scheduler is using
the remainder.
-
=head2 The Solution
Adding another machine, which allows a set-up where both the database
@@ -1002,8 +968,6 @@
=back
-
-
=head3 Cons
=over
@@ -1046,10 +1010,8 @@
new requests. So the overall machine performance can be worse than it
was originally when you had just a single machine for both servers.
-
=back
-
=head2 Three Machines Model
Since we are talking about using a dedicated machine for each server,
@@ -1065,10 +1027,6 @@
the hardware requirement will depend on the number of objects you will
have to serve and the rate at which they are requested.
-
-
-
-
=head1 Running More than One mod_perl Server on the Same Machine.
Let's assume that you have two different sets of code which have
@@ -1094,13 +1052,12 @@
webserver.
According to the equation developed in the section: "L<Choosing
-MaxClients|performance/Choosing_MaxClients>":
+MaxClients|guide::performance/Choosing_MaxClients>":
Total_RAM - Shared_RAM_per_Child
MaxClients = ---------------------------------------
Max_Process_Size - Shared_RAM_per_Child
-
MaxClients = (251 - 11)/(17-11) = 40
We see that we can run 40 processes, using the given memory and the
@@ -1202,15 +1159,13 @@
the second code set won't work with a new version of a module it was
relying on.
-
-
=head1 SSL functionality and a mod_perl Server
If you need SSL functionality, you can get it by adding the mod_ssl or
equivalent Apache_ssl to the light front-end server (httpd_docs) or
the heavy back-end mod_perl server (httpd_perl). ( The configuration
and installation instructions are located
-L<here|install/mod_perl_and_mod_ssl___openssl_>.)
+L<here|guide::install/mod_perl_and_mod_ssl___openssl_>.)
The question is: Is it a good idea to add mod_ssl into the back-end
mod_perl enabled server? Given that your internal network is secured,
@@ -1267,18 +1222,5 @@
to adapt you'll have more freedom to change what software you're using
and more control of things. So the choice is in your hand.
-
-
-
-
-
-
-
-
-
=cut
-
-
-
-
1.2 +0 -2 modperl-docs/src/docs/1.0/guide/style.css
Index: style.css
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/style.css,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- style.css 6 Jan 2002 16:54:56 -0000 1.1
+++ style.css 27 Feb 2002 18:03:36 -0000 1.2
@@ -1,10 +1,8 @@
-
body { font-family: helvetica, arial, sans-serif;
color: #000000;
background-color: #ffffee;
margin: 1em 4em;
}
-
h1, h2, h3 { color: #005A9C }
h1, h2, h3, h4, h5, h6 {
1.4 +19 -152 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.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- troubleshooting.pod 4 Feb 2002 14:16:49 -0000 1.3
+++ troubleshooting.pod 27 Feb 2002 18:03:36 -0000 1.4
@@ -7,39 +7,22 @@
Perl's warnings mode is immensely helpful in detecting possible
problems. Make sure you always turn on warnings while you are
developing code. See L<The Importance of
-Warnings|debug/The_Importance_of_Warnings>.
+Warnings|guide::debug/The_Importance_of_Warnings>.
Enabling C<use diagnostics;> generally helps you to determine the
source of the problem and how to solve it. See L<diagnostics
-pragma|debug/diagnostics_pragma> for more information.
-
-
-
-
-
-
-
+pragma|guide::debug/diagnostics_pragma> for more information.
=head1 Building and Installation
-See L<make Troubleshooting|install/make_Troubleshooting> and
-L<make test Troubleshooting|install/make_test_Troubleshooting>
-
-
-
-
-
-
-
-
-
+See L<make Troubleshooting|guide::install/make_Troubleshooting> and
+L<make test Troubleshooting|guide::install/make_test_Troubleshooting>
=head1 Configuration and Startup
This section talks about errors reported when you attempt to start the
server.
-
=head2 SegFaults During Startup
You have to build mod_perl with the same compiler as Perl was built
@@ -117,8 +100,6 @@
For more information see the I<ld> manpage and an essay on
C<LD_LIBRARY_PATH>: http://www.visi.com/~barr/ldpath.html
-
-
=head2 Invalid command 'PerlHandler'...
Syntax error on line 393 of /etc/httpd/conf/httpd.conf: Invalid
@@ -137,10 +118,6 @@
This can also happen when you try to run a non-mod_perl Apache server
using the configuration from a mod_perl server.
-
-
-
-
=head2 RegistryLoader: Translation of uri [...] to filename failed
RegistryLoader: Translation of uri [/home/httpd/perl/test.pl] to filename
@@ -155,12 +132,6 @@
complex cases. C<Apache::RegistryLoader>'s man page shows how to
handle these cases as well (look for the trans() sub).
-
-
-
-
-
-
=head2 "Apache.pm failed to load!"
If your server startup fails with:
@@ -171,51 +142,17 @@
PerlModule Apache
-
-
-
-
-
-
-
-
-
-
=head1 Code Parsing and Compilation
-
-
-
-
-
-
-
=head2 Value of $x will not stay shared at - line 5
L<my() Scoped Variable in Nested
-Subroutines|perl/my___Scoped_Variable_in_Nested_Subroutines>.
-
-
-
-
-
-
-
+Subroutines|guide::perl/my___Scoped_Variable_in_Nested_Subroutines>.
=head2 Value of $x may be unavailable at - line 5.
L<my() Scoped Variable in Nested
-Subroutines|perl/my___Scoped_Variable_in_Nested_Subroutines>.
-
-
-
-
-
-
-
-
-
-
+Subroutines|guide::perl/my___Scoped_Variable_in_Nested_Subroutines>.
=head2 Can't locate loadable object for module XXX
@@ -227,12 +164,6 @@
C<EVERYTHING=1> or C<DYNAMIC=1> parameters to enable and build all the
components of C<Apache::Util>.
-
-
-
-
-
-
=head2 Can't locate object method "get_handlers"...
Can't locate object method "get_handlers" via package "Apache"
@@ -240,22 +171,12 @@
You need to rebuild your mod_perl with stacked handlers, i.e.
C<PERL_STACKED_HANDLERS=1> or more simply C<EVERYTHING=1>.
-
-
-
-
-
-
=head2 Missing right bracket at line ...
Most often you will find that you really do have a syntax error.
However the other reason might be that a script running under
C<Apache::Registry> is using C<__DATA__> or C<__END__> tokens. L<Learn
-why|porting/__END___and___DATA___tokens>.
-
-
-
-
+why|guide::porting/__END___and___DATA___tokens>.
=head2 Can't load '.../auto/DBI/DBI.so' for module DBI
@@ -294,17 +215,6 @@
This problem is only known to be caused by installing gnu ld under Solaris.
-
-
-
-
-
-
-
-
-
-
-
=head1 Runtime
=head2 "exit signal Segmentation fault (11)" with mysql
@@ -317,8 +227,6 @@
Solution: re-compile PHP without the built-in MySQL support (you can
still connect to MySQL).
-
-
=head2 foo ... at /dev/null line 0
Under mod_perl you may receive a warning or an error in the
@@ -328,13 +236,11 @@
handler, because there is no actual file associated with the handler.
Therefore C<$0> is set to I</dev/null> and that's what you see.
-
=head2 Preventing mod_perl Processes From Going Wild
See the sections "L<Non-Scheduled Emergency Log
-Rotation|control/Non_Scheduled_Emergency_Log_Rotation>" and "L<All RAM
-Consumed|control/All_RAM_Consumed>"
-
+Rotation|guide::control/Non_Scheduled_Emergency_Log_Rotation>" and "L<All RAM
+Consumed|guide::control/All_RAM_Consumed>"
=head2 Segfaults when using XML::Parser
@@ -347,20 +253,15 @@
Starting from mod_perl version 1.23 this option is disabled by default.
-
=head2 My CGI/Perl Code Gets Returned as Plain Text Instead of Being
Executed by the Webserver
See L<My CGI/Perl Code Gets Returned as Plain Text Instead of Being
-Executed by the
Webserver|config/My_CGI_Perl_Code_Gets_Returned_as_Plain_Text_Instead_of_Being_Executed_by_the_Webserver>.
-
-
+Executed by the
Webserver|guide::config/My_CGI_Perl_Code_Gets_Returned_as_Plain_Text_Instead_of_Being_Executed_by_the_Webserver>.
=head2 Incorrect line number reporting in error/warn log messages
See L<Use of uninitialized value at (eval 80) line
-12.|troubleshooting/Use_of_uninitialized_value_at__eval_80__line_12_>
-
-
+12.|guide::troubleshooting/Use_of_uninitialized_value_at__eval_80__line_12_>
=head2 rwrite returned -1
@@ -370,7 +271,7 @@
There was a bug that reported this debug message regardless of the
value of the C<LogLevel> directive. It was fixed in mod_perl 1.19_01
-(L<CVS version|download/mod_perl>).
+(L<CVS version|guide::download/mod_perl>).
Generally C<LogLevel> is either C<debug> or C<info>. C<debug> logs
everything, C<info> is the next level, which doesn't include debug
@@ -378,18 +279,12 @@
At the moment there is no way to prevent users from aborting
connections.
-
-
=head2 Can't upgrade that kind of scalar ...
Fixed in mod_perl 1.23.
-
-
-
=head2 caught SIGPIPE in process
-
[modperl] caught SIGPIPE in process 1234
[modperl] process 1234 going to Apache::exit with status...
@@ -398,7 +293,7 @@
'Stop' button. It gives you an opportunity to do cleanups if the
script was aborted in the middle of its execution. See L<Handling the
'User pressed Stop button'
-case|debug/Handling_the__User_pressed_Stop_button__case> for more
+case|guide::debug/Handling_the__User_pressed_Stop_button__case> for more
info.
If your mod_perl version is earlier than 1.17 you might also get the
@@ -410,9 +305,7 @@
Process 2493 going to Apache::exit with status=-2
You may see this message in mod_perl versions less than 1.17. See also
-L<caught SIGPIPE in process|troubleshooting/caught_SIGPIPE_in_process>.
-
-
+L<caught SIGPIPE in
process|guide::troubleshooting/caught_SIGPIPE_in_process>.
=head2 Global symbol "$foo" requires explicit package name
@@ -475,10 +368,6 @@
verbose and will tell you more than you might wish to know including
full source.
-
-
-
-
=head2 Use of uninitialized value at (eval 80) line 12.
Your code includes some undefined variable that you have used as if it
@@ -497,14 +386,12 @@
empty string in our example).
Also read about L<Finding the Line Which Triggered the Error or
-Warning|debug/Finding_the_Line_Which_Triggered_the_Error_or_Warning>.
+Warning|guide::debug/Finding_the_Line_Which_Triggered_the_Error_or_Warning>.
=head2 Undefined subroutine &Apache::ROOT::perl::test_2epl::some_function
called at
See L<Names collisions with Modules and
-libs|porting/Name_collisions_with_Modules_and_libs>.
-
-
+libs|guide::porting/Name_collisions_with_Modules_and_libs>.
=head2 Callback called exit
@@ -565,12 +452,9 @@
this way, when the real problem happens, C<Carp::confess> doesn't eat
memory in the emergency pool (C<$^M>).
-
-
-
=head2 server reached MaxClients setting, consider raising the MaxClients
setting
-See L<Choosing MaxClients|performance/Choosing_MaxClients>.
+See L<Choosing MaxClients|guide::performance/Choosing_MaxClients>.
=head2 syntax error at /dev/null line 1, near "line arguments:"
@@ -589,7 +473,6 @@
# mknod /dev/null c 1 3
# chmod a+rw /dev/null
-
=head2 Can't call method "register_cleanup" (CGI.pm)
Can't call method "register_cleanup" on an
@@ -617,14 +500,8 @@
my %bar = $cookies->{foo}->value;
}
-
-
-
-
=head1 Shutdown and Restart
-
-
=head2 Evil things might happen when using PerlFreshRestart
Unfortunately, not all perl modules are robust enough to survive
@@ -662,9 +539,6 @@
problem with code within a CGI script, moving all the code into a
module (or a library) and require()ing it should solve the problem.
-
-
-
=head2 Can't undef active subroutine
Can't undef active subroutine at
@@ -680,9 +554,6 @@
with B<$SIG{PIPE}>. It's also triggered only when you've changed your
script on disk and mod_perl is trying to reload it.
-
-
-
=head2 [warn] child process 30388 did not exit, sending another SIGHUP
From mod_perl.pod: With Apache versions 1.3.0 and higher, mod_perl
@@ -697,7 +568,6 @@
variable to C<-1>. Be aware that `your code' includes any modules you
use and I<they> may well have C<DESTROY> and C<END> blocks...
-
=head2 Processes Get Stuck on Graceful Restart
If you see a process stuck in "G" (Gracefully finishing) after a doing
@@ -706,18 +576,16 @@
cleanup normally isn't a requirement, you can disable it by setting
the PERL_DESTRUCT_LEVEL environment variable to -1. See the section
"L<Speeding up the Apache Termination and
-Restart|control/Speeding_up_the_Apache_Termination_and_Restart>" for
+Restart|guide::control/Speeding_up_the_Apache_Termination_and_Restart>" for
more information.
-
=head2 httpd keeps on growing after each restart
See the I<HUP Signal> explanation at the section:
-L<Server Stopping and Restarting|control/Server_Stopping_and_Restarting>
+L<Server Stopping and
Restarting|guide::control/Server_Stopping_and_Restarting>
=head1 Windows OS specific notes
-
=head2 Apache::DBI
C<Apache::DBI> causes the server to exit when it starts up, with:
@@ -738,6 +606,5 @@
C<PerlRequire> and C<PerlModule> statements on the first load, so they
can succeed on the second load. Without that flag, the second load
fails.
-
=cut
1.3 +3 -3 modperl-docs/src/docs/1.0/win32/win32_binaries.pod
Index: win32_binaries.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/win32/win32_binaries.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- win32_binaries.pod 10 Jan 2002 22:32:08 -0000 1.2
+++ win32_binaries.pod 27 Feb 2002 18:03:38 -0000 1.3
@@ -172,9 +172,9 @@
=head1 SEE ALSO
-L<mod_perl>, L<Apache>, http://perl.apache.org/, especially the guide,
-http://take23.org/, http://httpd.apache.org/, and
-http://www.activestate.com/.
+The I<mod_perl> manpage, the L<Apache> manpage,
+http://perl.apache.org/, especially the guide, http://take23.org/,
+http://httpd.apache.org/, and http://www.activestate.com/.
=cut
1.3 +2 -2 modperl-docs/src/docs/1.0/win32/win32_compile.pod
Index: win32_compile.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/win32/win32_compile.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- win32_compile.pod 10 Jan 2002 22:32:08 -0000 1.2
+++ win32_compile.pod 27 Feb 2002 18:03:38 -0000 1.3
@@ -169,7 +169,7 @@
=head1 SEE ALSO
-L<mod_perl>, L<Apache>, http://perl.apache.org/, especially
-the guide, and http://take23.org/.
+The I<mod_perl> manpage, the L<Apache> manpage,
+http://perl.apache.org/, especially the guide, and http://take23.org/.
=cut
1.3 +1 -1 modperl-docs/src/docs/2.0/api/mod_perl-2.0/APR/PerlIO.pod
Index: PerlIO.pod
===================================================================
RCS file:
/home/cvs/modperl-docs/src/docs/2.0/api/mod_perl-2.0/APR/PerlIO.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- PerlIO.pod 2 Jan 2002 11:14:22 -0000 1.2
+++ PerlIO.pod 27 Feb 2002 18:03:38 -0000 1.3
@@ -61,7 +61,7 @@
=head1 SEE ALSO
-L<perliol(1)>, L<perlapio(1)>, L<perl(1)>.
+The I<perliol(1)>, I<perlapio(1)> and I<perl(1)> manpages.
=cut
1.4 +1 -1
modperl-docs/src/docs/2.0/api/mod_perl-2.0/Apache/ServerUtil.pod
Index: ServerUtil.pod
===================================================================
RCS file:
/home/cvs/modperl-docs/src/docs/2.0/api/mod_perl-2.0/Apache/ServerUtil.pod,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- ServerUtil.pod 20 Nov 2001 02:35:07 -0000 1.3
+++ ServerUtil.pod 27 Feb 2002 18:03:38 -0000 1.4
@@ -54,7 +54,7 @@
with a trailing C</>. (it's the same as using C<''> as C<$fname>'s
value).
-Also see the L<C<server_root>> constant.
+Also see the C<server_root> constant.
=back
1.5 +4 -4 modperl-docs/src/docs/2.0/devel/help/help.pod
Index: help.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/devel/help/help.pod,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- help.pod 9 Jan 2002 18:09:49 -0000 1.4
+++ help.pod 27 Feb 2002 18:03:38 -0000 1.5
@@ -6,8 +6,8 @@
This document covers the resources available to the mod_perl 2.0 core
developer. Please notice that you probably want to read the L<user's
-help documentation|../../user/help/help.pod> if you have problems
-using mod_perl.
+help documentation|user::help::help> if you have problems using
+mod_perl.
The following mailing lists and resources can be of a major interest
to the mod_perl 2.0 developers.
@@ -219,8 +219,8 @@
=head1 More Help
-There is a L<parallel help document|../../user/help/help.pod> in the
-user documentation set which covers mod_perl user's issues.
+There is a L<parallel help document|user::help::help> in the user
+documentation set which covers mod_perl user's issues.
=head1 Maintainers
1.4 +2 -2
modperl-docs/src/docs/2.0/devel/porting_from_1.x/porting_from_1.x.pod
Index: porting_from_1.x.pod
===================================================================
RCS file:
/home/cvs/modperl-docs/src/docs/2.0/devel/porting_from_1.x/porting_from_1.x.pod,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- porting_from_1.x.pod 27 Dec 2001 12:07:53 -0000 1.3
+++ porting_from_1.x.pod 27 Feb 2002 18:03:38 -0000 1.4
@@ -83,8 +83,8 @@
C<Apache::Test> testing framework that comes together with mod_perl
2.x works with 1.x and 2.x mod_perl versions. Therefore you should
-consider porting your test suite to use
-C<Apache::Test>. L<writing_tests> explains how to do that.
+consider porting your test suite to use L<the Apache::Test
+Framework|devel::testing::testing>.
=head1 Maintainers
1.12 +1 -1 modperl-docs/src/docs/2.0/devel/testing/testing.pod
Index: testing.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/devel/testing/testing.pod,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- testing.pod 21 Feb 2002 04:39:01 -0000 1.11
+++ testing.pod 27 Feb 2002 18:03:38 -0000 1.12
@@ -676,7 +676,7 @@
=back
The debugging options I<-debug> and I<-breakpoint> are covered in the
-L<Debugging> section.
+L</Debugging> section.
For a complete list of available switches see the output of C<t/TEST
-help>.
1.9 +1 -1 modperl-docs/src/docs/2.0/user/compat/compat.pod
Index: compat.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/compat/compat.pod,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- compat.pod 29 Jan 2002 07:55:56 -0000 1.8
+++ compat.pod 27 Feb 2002 18:03:38 -0000 1.9
@@ -132,7 +132,7 @@
...;
}
-see the L<attributes> manpage for additional information on subroutine
+see the I<attributes> manpage for additional information on subroutine
attributes.
mod_perl 2.0 doesn't support the C<($$)> prototypes, mainly because
1.4 +1 -1 modperl-docs/src/docs/2.0/user/design/design.pod
Index: design.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/design/design.pod,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- design.pod 16 Jan 2002 05:36:53 -0000 1.3
+++ design.pod 27 Feb 2002 18:03:38 -0000 1.4
@@ -21,7 +21,7 @@
being implemented as a complete re-write from scratch.
For a more detailed introduction and functionality overview, see
-L<Overview|overview/overview/"test">.
+L<Overview|user::overview::overview/"test">.
=head1 Interpreter Management
1.8 +5 -3 modperl-docs/src/docs/2.0/user/install/install.pod
Index: install.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/install/install.pod,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- install.pod 27 Dec 2001 11:51:54 -0000 1.7
+++ install.pod 27 Feb 2002 18:03:38 -0000 1.8
@@ -196,7 +196,8 @@
% make test
-L<../testing/testing.pod> document covers the C<make test> suite.
+L<Apache::Test Framework|devel::testing::testing> document covers the
+C<make test> suite.
META: probably need to link directly to the 'Running Tests' section.
@@ -214,8 +215,9 @@
% perl build/source_scan.pl apxs $apache_prefix/bin/apxs
-META: this is covered in L<core_explained> should probably move/point
-there.
+META: this is covered in L<Core
+Explained|devel::core_explained::core_explained> should probably
+move/point there.
=head2 Re-using Build Options
1.2 +17 -14 modperl-docs/src/maillist/email-etiquette.pod
Index: email-etiquette.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/maillist/email-etiquette.pod,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- email-etiquette.pod 5 Jan 2002 19:15:41 -0000 1.1
+++ email-etiquette.pod 27 Feb 2002 18:03:38 -0000 1.2
@@ -1,4 +1,8 @@
-=head1 The mod_perl Mailing List Guidelines
+=head1 NAME
+
+The mod_perl Mailing List Guidelines
+
+=head1 Introduction
=for html <!--
email-etiquette: This version dated 21 October 2001.
@@ -13,7 +17,6 @@
Except where noted the language of all documents is English.
-
=head1 What is mod_perl?
http://perl.apache.org/guide/intro.html#What_is_mod_perl
@@ -94,8 +97,8 @@
I<Posting> to the list is just sending a message to the address which
you will be given after you subscribe.
-Your message will not be accepted unless you have first
-L<subscribed|To Get On The List>.
+Your message will not be accepted unless you have first L<To Get On
+The List|maillist::list-users>.
Do not post to [EMAIL PROTECTED], except to subscribe to
the list! Please do not post to the list itself to attempt to
@@ -358,15 +361,15 @@
It is a large document, you probably will want to download it and read
it off-line. If you get the source (see below, L<Corrections and
-Contributions>) it comes with a build file to turn the .pod (Plain Old
-Documentation) source into HTML, .ps (PostScript) and .pdf (Portable
-Document Format). You will need at least Perl version 5.005 to build
-it. If you browse the Guide on-line you can use one of the search
-engines to find things in it. If you build and browse your own local
-HTML copy of the Guide, some of the links in it will not work unless
-you are connected to the Internet. Some people prefer to work
-offline, using tools like `grep' or `mc' to search the .pod source
-directly.
+Contributions|/Corrections_and_Contributions>) it comes with a
+build file to turn the .pod (Plain Old Documentation) source into
+HTML, .ps (PostScript) and .pdf (Portable Document Format). You will
+need at least Perl version 5.005 to build it. If you browse the Guide
+on-line you can use one of the search engines to find things in it.
+If you build and browse your own local HTML copy of the Guide, some of
+the links in it will not work unless you are connected to the
+Internet. Some people prefer to work offline, using tools like `grep'
+or `mc' to search the .pod source directly.
=head2 Finding the Guide
@@ -377,7 +380,7 @@
The sources are available from CPAN and other mirrors:
-http://www.perl.com/CPAN-local/authors/id/S/ST/STAS/
+http://www.cpan.org/authors/id/S/ST/STAS/
=head2 Corrections And Contributions
1.3 +10 -6 modperl-docs/src/maillist/list-advocacy.pod
Index: list-advocacy.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/maillist/list-advocacy.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- list-advocacy.pod 5 Feb 2002 16:19:17 -0000 1.2
+++ list-advocacy.pod 27 Feb 2002 18:03:38 -0000 1.3
@@ -1,7 +1,11 @@
-###########################################
-# WARNING: Do not edit this file! #
-# Edit data.pl instead and re-run make.pl #
-###########################################
+###################################################
+# WARNING: Do not edit this file!
+# If you do the changes will be lost!
+# Instead edit data.pl instead and re-run make.pl
+#
+# Don't forget to commit the changes to both .txt and the generated
+# .pod to cvs, since others won't run the local make.pl
+####################################################
=head1 NAME
@@ -12,8 +16,8 @@
A mailing list for B<mod_perl advocacy issues>,
discussions about the site, etc.
-Please read the mailing list L<Guidelines|email-etiquette> before
-posting.
+Please read the mailing list L<Guidelines|maillist::email-etiquette>
+before posting.
=head1 Subscription Information
1.3 +10 -6 modperl-docs/src/maillist/list-announce.pod
Index: list-announce.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/maillist/list-announce.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- list-announce.pod 5 Feb 2002 16:19:17 -0000 1.2
+++ list-announce.pod 27 Feb 2002 18:03:38 -0000 1.3
@@ -1,7 +1,11 @@
-###########################################
-# WARNING: Do not edit this file! #
-# Edit data.pl instead and re-run make.pl #
-###########################################
+###################################################
+# WARNING: Do not edit this file!
+# If you do the changes will be lost!
+# Instead edit data.pl instead and re-run make.pl
+#
+# Don't forget to commit the changes to both .txt and the generated
+# .pod to cvs, since others won't run the local make.pl
+####################################################
=head1 NAME
@@ -12,8 +16,8 @@
The B<announce> list is for announcing mod_perl and related products
releases.
-Please read the mailing list L<Guidelines|email-etiquette> before
-posting.
+Please read the mailing list L<Guidelines|maillist::email-etiquette>
+before posting.
=head1 Subscription Information
1.3 +10 -6 modperl-docs/src/maillist/list-asp.pod
Index: list-asp.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/maillist/list-asp.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- list-asp.pod 5 Feb 2002 16:19:17 -0000 1.2
+++ list-asp.pod 27 Feb 2002 18:03:38 -0000 1.3
@@ -1,7 +1,11 @@
-###########################################
-# WARNING: Do not edit this file! #
-# Edit data.pl instead and re-run make.pl #
-###########################################
+###################################################
+# WARNING: Do not edit this file!
+# If you do the changes will be lost!
+# Instead edit data.pl instead and re-run make.pl
+#
+# Don't forget to commit the changes to both .txt and the generated
+# .pod to cvs, since others won't run the local make.pl
+####################################################
=head1 NAME
@@ -11,8 +15,8 @@
The B<asp> list is for C<Apache::ASP> discussions.
-Please read the mailing list L<Guidelines|email-etiquette> before
-posting.
+Please read the mailing list L<Guidelines|maillist::email-etiquette>
+before posting.
=head1 Subscription Information
1.3 +10 -6 modperl-docs/src/maillist/list-cvs.pod
Index: list-cvs.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/maillist/list-cvs.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- list-cvs.pod 5 Feb 2002 16:19:17 -0000 1.2
+++ list-cvs.pod 27 Feb 2002 18:03:38 -0000 1.3
@@ -1,7 +1,11 @@
-###########################################
-# WARNING: Do not edit this file! #
-# Edit data.pl instead and re-run make.pl #
-###########################################
+###################################################
+# WARNING: Do not edit this file!
+# If you do the changes will be lost!
+# Instead edit data.pl instead and re-run make.pl
+#
+# Don't forget to commit the changes to both .txt and the generated
+# .pod to cvs, since others won't run the local make.pl
+####################################################
=head1 NAME
@@ -16,8 +20,8 @@
committed to the modperl CVS repository a mail is sent here with the
diff.
-Please read the mailing list L<Guidelines|email-etiquette> before
-posting.
+Please read the mailing list L<Guidelines|maillist::email-etiquette>
+before posting.
=head1 Subscription Information
1.3 +10 -6 modperl-docs/src/maillist/list-dev.pod
Index: list-dev.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/maillist/list-dev.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- list-dev.pod 5 Feb 2002 16:19:17 -0000 1.2
+++ list-dev.pod 27 Feb 2002 18:03:38 -0000 1.3
@@ -1,7 +1,11 @@
-###########################################
-# WARNING: Do not edit this file! #
-# Edit data.pl instead and re-run make.pl #
-###########################################
+###################################################
+# WARNING: Do not edit this file!
+# If you do the changes will be lost!
+# Instead edit data.pl instead and re-run make.pl
+#
+# Don't forget to commit the changes to both .txt and the generated
+# .pod to cvs, since others won't run the local make.pl
+####################################################
=head1 NAME
@@ -12,8 +16,8 @@
The B<development> mailing list is for discussions about the
development of the core mod_perl.
-Please read the mailing list L<Guidelines|email-etiquette> before
-posting.
+Please read the mailing list L<Guidelines|maillist::email-etiquette>
+before posting.
=head1 Subscription Information
1.3 +10 -6 modperl-docs/src/maillist/list-docs-cvs.pod
Index: list-docs-cvs.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/maillist/list-docs-cvs.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- list-docs-cvs.pod 5 Feb 2002 16:19:17 -0000 1.2
+++ list-docs-cvs.pod 27 Feb 2002 18:03:38 -0000 1.3
@@ -1,7 +1,11 @@
-###########################################
-# WARNING: Do not edit this file! #
-# Edit data.pl instead and re-run make.pl #
-###########################################
+###################################################
+# WARNING: Do not edit this file!
+# If you do the changes will be lost!
+# Instead edit data.pl instead and re-run make.pl
+#
+# Don't forget to commit the changes to both .txt and the generated
+# .pod to cvs, since others won't run the local make.pl
+####################################################
=head1 NAME
@@ -12,8 +16,8 @@
A mailing list where all the B<mod_perl documentation modification
commits> are sent.
-Please read the mailing list L<Guidelines|email-etiquette> before
-posting.
+Please read the mailing list L<Guidelines|maillist::email-etiquette>
+before posting.
=head1 Subscription Information
1.3 +10 -6 modperl-docs/src/maillist/list-docs-dev.pod
Index: list-docs-dev.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/maillist/list-docs-dev.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- list-docs-dev.pod 5 Feb 2002 16:19:17 -0000 1.2
+++ list-docs-dev.pod 27 Feb 2002 18:03:38 -0000 1.3
@@ -1,7 +1,11 @@
-###########################################
-# WARNING: Do not edit this file! #
-# Edit data.pl instead and re-run make.pl #
-###########################################
+###################################################
+# WARNING: Do not edit this file!
+# If you do the changes will be lost!
+# Instead edit data.pl instead and re-run make.pl
+#
+# Don't forget to commit the changes to both .txt and the generated
+# .pod to cvs, since others won't run the local make.pl
+####################################################
=head1 NAME
@@ -11,8 +15,8 @@
A mailing list for discussing B<mod_perl documentation>
-Please read the mailing list L<Guidelines|email-etiquette> before
-posting.
+Please read the mailing list L<Guidelines|maillist::email-etiquette>
+before posting.
=head1 Subscription Information
1.3 +10 -6 modperl-docs/src/maillist/list-embperl.pod
Index: list-embperl.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/maillist/list-embperl.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- list-embperl.pod 5 Feb 2002 16:19:17 -0000 1.2
+++ list-embperl.pod 27 Feb 2002 18:03:38 -0000 1.3
@@ -1,7 +1,11 @@
-###########################################
-# WARNING: Do not edit this file! #
-# Edit data.pl instead and re-run make.pl #
-###########################################
+###################################################
+# WARNING: Do not edit this file!
+# If you do the changes will be lost!
+# Instead edit data.pl instead and re-run make.pl
+#
+# Don't forget to commit the changes to both .txt and the generated
+# .pod to cvs, since others won't run the local make.pl
+####################################################
=head1 NAME
@@ -13,8 +17,8 @@
L<http://perl.apache.org/embperl/> users and developers to share
ideas, ask question and solve problems.
-Please read the mailing list L<Guidelines|email-etiquette> before
-posting.
+Please read the mailing list L<Guidelines|maillist::email-etiquette>
+before posting.
=head1 Subscription Information
1.3 +10 -6 modperl-docs/src/maillist/list-test-cvs.pod
Index: list-test-cvs.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/maillist/list-test-cvs.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- list-test-cvs.pod 5 Feb 2002 16:19:17 -0000 1.2
+++ list-test-cvs.pod 27 Feb 2002 18:03:38 -0000 1.3
@@ -1,7 +1,11 @@
-###########################################
-# WARNING: Do not edit this file! #
-# Edit data.pl instead and re-run make.pl #
-###########################################
+###################################################
+# WARNING: Do not edit this file!
+# If you do the changes will be lost!
+# Instead edit data.pl instead and re-run make.pl
+#
+# Don't forget to commit the changes to both .txt and the generated
+# .pod to cvs, since others won't run the local make.pl
+####################################################
=head1 NAME
@@ -14,8 +18,8 @@
including cvs commits of changes for mod_perl's sub-project
C<Apache::Test>.
-Please read the mailing list L<Guidelines|email-etiquette> before
-posting.
+Please read the mailing list L<Guidelines|maillist::email-etiquette>
+before posting.
=head1 Subscription Information
1.3 +10 -6 modperl-docs/src/maillist/list-test-dev.pod
Index: list-test-dev.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/maillist/list-test-dev.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- list-test-dev.pod 5 Feb 2002 16:19:18 -0000 1.2
+++ list-test-dev.pod 27 Feb 2002 18:03:38 -0000 1.3
@@ -1,7 +1,11 @@
-###########################################
-# WARNING: Do not edit this file! #
-# Edit data.pl instead and re-run make.pl #
-###########################################
+###################################################
+# WARNING: Do not edit this file!
+# If you do the changes will be lost!
+# Instead edit data.pl instead and re-run make.pl
+#
+# Don't forget to commit the changes to both .txt and the generated
+# .pod to cvs, since others won't run the local make.pl
+####################################################
=head1 NAME
@@ -14,8 +18,8 @@
because mod_perl's sub-project C<Apache::Test> is discussed on this
list.
-Please read the mailing list L<Guidelines|email-etiquette> before
-posting.
+Please read the mailing list L<Guidelines|maillist::email-etiquette>
+before posting.
=head1 Subscription Information
1.3 +10 -6 modperl-docs/src/maillist/list-users.pod
Index: list-users.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/maillist/list-users.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- list-users.pod 5 Feb 2002 16:19:18 -0000 1.2
+++ list-users.pod 27 Feb 2002 18:03:38 -0000 1.3
@@ -1,7 +1,11 @@
-###########################################
-# WARNING: Do not edit this file! #
-# Edit data.pl instead and re-run make.pl #
-###########################################
+###################################################
+# WARNING: Do not edit this file!
+# If you do the changes will be lost!
+# Instead edit data.pl instead and re-run make.pl
+#
+# Don't forget to commit the changes to both .txt and the generated
+# .pod to cvs, since others won't run the local make.pl
+####################################################
=head1 NAME
@@ -13,8 +17,8 @@
mod_perl users and developers to share ideas, solve problems and discuss
things related to mod_perl and the C<Apache::*> modules.
-Please read the mailing list L<Guidelines|email-etiquette> before
-posting.
+Please read the mailing list L<Guidelines|maillist::email-etiquette>
+before posting.
=head1 Subscription Information
1.3 +2 -2 modperl-docs/src/maillist/maillist.tmpl
Index: maillist.tmpl
===================================================================
RCS file: /home/cvs/modperl-docs/src/maillist/maillist.tmpl,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- maillist.tmpl 5 Feb 2002 03:31:34 -0000 1.2
+++ maillist.tmpl 27 Feb 2002 18:03:38 -0000 1.3
@@ -15,8 +15,8 @@
[% list.desc -%]
-Please read the mailing list L<Guidelines|email-etiquette> before
-posting.
+Please read the mailing list L<Guidelines|maillist::email-etiquette>
+before posting.
=head1 Subscription Information
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
