perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/src/docs/1.0/guide Changes.pod
Date Thu, 18 Apr 2002 18:13:05 GMT
stas        02/04/18 11:13:05

  Modified:    src/docs/1.0/faqs Changes.pod cgi_to_mod_perl.pod config.cfg
                        mod_perl.pod mod_perl_api.pod mod_perl_cgi.pod
                        mod_perl_cvs.pod mod_perl_faq.pod
                        mod_perl_method_handlers.pod mod_perl_traps.pod
                        mod_perl_tuning.pod perl_myth.pod
               src/docs/1.0/guide Changes.pod
  Added:       src/docs/1.0/faqs httpd+perl.conf.txt httpd.conf.txt
  Log:
  +* Re-arranged the order of the FAQs.
  +
  +* Changed titles of documents to not include underscores, and of
  +  headings inside documents to not be upper-case.
  +
  +* Corrected links and removed stale ones.
  +
  +* Fixed authors where needed.
  +
  +* Did some slight content review, added C<CE<lt>E<gt>>, C<BE<lt>E<gt>>
  +  ...  on many places to make it more readable.
  
  Submitted by:	Per Einar Ellefsen <per.einar@skynet.be>
  
  Revision  Changes    Path
  1.2       +16 -0     modperl-docs/src/docs/1.0/faqs/Changes.pod
  
  Index: Changes.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/Changes.pod,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- Changes.pod	20 Mar 2002 17:42:05 -0000	1.1
  +++ Changes.pod	18 Apr 2002 18:13:05 -0000	1.2
  @@ -9,6 +9,22 @@
   
   The most recent changes are listed first.
   
  +=head1 Thu Apr 18 09:10:00 CET 2002
  +
  +Per Einar Ellefsen E<lt>per.einar (at) skynet.beE<gt>
  +
  +* Re-arranged the order of the FAQs.
  +
  +* Changed titles of documents to not include underscores, and of
  +  headings inside documents to not be upper-case.
  +
  +* Corrected links and removed stale ones.
  +
  +* Fixed authors where needed.
  +
  +* Did some slight content review, added C<CE<lt>E<gt>>, C<BE<lt>E<gt>>
  +  ...  on many places to make it more readable.
  +
   =head1 Sat Sep 15 19:45:41 SGT 2001
   
   * docs ported from the old site
  
  
  
  1.4       +16 -13    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.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- cgi_to_mod_perl.pod	20 Mar 2002 17:42:05 -0000	1.3
  +++ cgi_to_mod_perl.pod	18 Apr 2002 18:13:05 -0000	1.4
  @@ -1,22 +1,25 @@
   =head1 NAME
   
  -cgi_to_mod_perl - First steps needed to use mod_perl as a CGI replacement
  +First steps needed to use mod_perl as a CGI replacement
   
  -=head1 DESCRIPTION
  +=head1 Description
   
  -As the README and other mod_perl documents explain, mod_perl as
  +As the I<README> and other mod_perl documents explain, mod_perl as
   a CGI replacement is only a small piece of what the package offers.
   However, it is the most popular use of mod_perl, this document is here
   so you can cut to the chase.
   
  -=head1 INSTALLATION
  +META: cgi_to_mod_perl and mod_perl_cgi should probably be integrated into
  +one FAQ.
   
  -Read the INSTALL document, in most cases, nothing more is required
  +=head1 Installation
  +
  +Read the I<INSTALL> document, in most cases, nothing more is required
   than:
   
    perl Makefile.PL && make && make install
   
  -=head1 CONFIGURATION
  +=head1 Configuration
   
   For using mod_perl as a CGI replacement, the recommended configuration
   is as follows:
  @@ -49,7 +52,7 @@
   
   Note that `ScriptAlias' does _not_ work for mod_perl.
   
  -=head1 PORTING CGI SCRIPTS
  +=head1 Porting CGI scripts
   
   =over 4
   
  @@ -60,7 +63,7 @@
   C<print()> functions do not work as they do under CGI.  If you're
   using CGI.pm, use C<$query-E<gt>print> instead of plain 'ol C<print()>.
   
  -=item HEADERS
  +=item Headers
   
   By default, mod_perl does not send any headers by itself, however, you
   may wish to change this:
  @@ -76,7 +79,7 @@
   If you're using CGI.pm and 'print $q-E<gt>header' you do
   _not_ need C<PerlSendHeader On>.    
   
  -=item NPH SCRIPTS
  +=item NPH Scripts
   
   To run a CGI `nph' script under mod_perl, simply add to your code:
   
  @@ -88,7 +91,7 @@
    PerlSendHeader Off
    </Files>
   
  -=item PROGRAMMING PRACTICE
  +=item Programming Practice
   
   CGI lets you get away with sloppy programming, mod_perl does not.
   Why?  CGI scripts have the lifetime of a single HTTP request as a
  @@ -105,17 +108,17 @@
   in the long run.  And, of course, clean scripts will still run under
   CGI! 
   
  -=item TRAPS
  +=item Traps
   
   See L<common/known mod_perl traps|faqs::mod_perl_traps>.
   
   =back
   
  -=head1 REPORTING PROBLEMS
  +=head1 Reporting problems
   
   Read the I<SUPPORT> file.
   
  -=head1 SEE ALSO
  +=head1 See Also
   
   Apache::PerlRun(3)
   
  
  
  
  1.5       +7 -5      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.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- config.cfg	20 Mar 2002 17:42:05 -0000	1.4
  +++ config.cfg	18 Apr 2002 18:13:05 -0000	1.5
  @@ -7,21 +7,23 @@
       abstract => 'Miscellaneous mod_perl 1.x documentation',
   
       chapters => [qw(
  +        mod_perl.pod
  +        mod_perl_faq.pod
           cgi_to_mod_perl.pod
           mod_perl_cgi.pod
  -        mod_perl_cvs.pod
  -        mod_perl_faq.pod
  -        mod_perl.pod
           mod_perl_traps.pod
  -        mod_perl_tuning.pod
           mod_perl_api.pod
  -        mod_perl_method_handlers.pod
  +        mod_perl_tuning.pod
           perl_myth.pod
  +        mod_perl_method_handlers.pod
  +        mod_perl_cvs.pod
           Changes.pod
      )],
      copy_glob => [
          qw(
             mjtg-news.txt
  +          httpd.conf.txt
  +          httpd+perl.conf.txt
            )
      ],
   );
  
  
  
  1.4       +156 -117  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.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- mod_perl.pod	20 Mar 2002 17:42:05 -0000	1.3
  +++ mod_perl.pod	18 Apr 2002 18:13:05 -0000	1.4
  @@ -3,7 +3,7 @@
   mod_perl - Embed a Perl interpreter in the Apache HTTP server 
   
   
  -=head1 DESCRIPTION
  +=head1 Description
   
   The Apache/Perl integration project brings together the full power of
   the Perl programming language and the Apache HTTP server.  This is
  @@ -17,14 +17,14 @@
   penalty of Perl start-up (compile) time.  
   
   Without question, the most popular Apache/Perl module is
  -Apache::Registry module.  This module emulates the CGI environment,
  +C<Apache::Registry> module.  This module emulates the CGI environment,
   allowing programmers to write scripts that run under CGI or
   mod_perl without change.  Existing CGI scripts may require some
   changes, simply because a CGI script has a very short lifetime of one
   HTTP request, allowing you to get away with "quick and dirty"
  -scripting.  Using mod_perl and Apache::Registry requires you to be
  +scripting.  Using mod_perl and C<Apache::Registry> requires you to be
   more careful, but it also gives new meaning to the work "quick"!
  -Apache::Registry maintains a cache of compiled scripts, which happens
  +C<Apache::Registry> maintains a cache of compiled scripts, which happens
   the first time a script is accessed by a child server or once again if
   the file is updated on disk.
   
  @@ -37,16 +37,18 @@
   =head1 FAQ
   
   The mod_perl FAQ is maintained by Frank Cringle
  -E<lt>fdc@cliwe.ping.deE<gt>: http://perl.apache.org/faq/
  +E<lt>fdc (at) cliwe.ping.deE<gt>: L<Frequently Asked Questions about
  +mod_perl|faqs::mod_perl_faq>.
   
   =head1 Apache/Perl API
   
  -See 'perldoc Apache' for info on how to use the Perl-Apache API.
  +See 'C<perldoc Apache>' for info on how to use the Perl-Apache API.
   
   See the I<lib/> directory for example modules and
  -L<products::apache-modlist> for a comprehensive list.
  +L<The Apache/Perl module list|products::apache-modlist> for a
  +comprehensive list.
   
  -See the eg/ directory for example scripts.
  +See the I<eg/> directory for example scripts.
   
   =head1 mod_perl
   
  @@ -74,29 +76,29 @@
   
       PerlHandler sub_routine_name
   
  -This is the name of the subroutine to call to handle each request. 
  -e.g. 
  -in the PerlModule Apache::Registry this is "Apache::Registry::handler".
  +This is the name of the subroutine to call to handle each request.
  +e.g. in C<PerlModule Apache::Registry> this is
  +C<Apache::Registry::handler>.
   
   If PerlHandler is not a defined subroutine, mod_perl assumes it is a
   package name which defines a subroutine named "handler".
   
       PerlHandler   Apache::Registry
   
  -Would load Registry.pm (if it is not already) and call it's subroutine
  -"handler".
  +Would load I<Registry.pm> (if it is not already) and call its
  +subroutine C<handler>.
   
   There are several stages of a request where the Apache API allows a
   module to step in and do something.  The Apache documentation will
   tell you all about those stages and what your modules can do.  
  -By default, these hooks are disabled at compile time, see the INSTALL
  +By default, these hooks are disabled at compile time, see the I<INSTALL>
   document for information on enabling these hooks.
   The following configuration directives take one argument, which is the name
   of the subroutine to call.  If the value is not a subroutine name, mod_perl
   assumes it is a package name which implements a 'handler' subroutine.
   
  -    PerlChildInitHandler          (requires apache_1.3.0 or higher)
  -    PerlPostReadRequestHandler    (requires apache_1.3.0 or higher)
  +    PerlChildInitHandler          (requires Apache 1.3.0 or higher)
  +    PerlPostReadRequestHandler    (requires Apache 1.3.0 or higher)
       PerlInitHandler
       PerlTransHandler    
       PerlHeaderParserHandler       
  @@ -108,24 +110,24 @@
       PerlHandler
       PerlLogHandler
       PerlCleanupHandler
  -    PerlChildExitHandler          (requires apache_1.3.0 or higher)
  +    PerlChildExitHandler          (requires Apache 1.3.0 or higher)
   
   Only ChildInit, ChildExit, PostReadRequest and Trans handlers are not
   allowed in .htaccess files.
   
   Modules can check if the code is being run in the parent server during
  -startup by checking the $Apache::Server::Starting variable.
  +startup by checking the C<$Apache::Server::Starting> variable.
   
  -=head1 RESTARTING
  +=head1 Restarting
   
   =over 4
   
   =item PerlFreshRestart
   
   By default, if a server is restarted 
  -(ala kill -USR1 `cat logs/httpd.pid`), Perl scripts and modules are
  +(ala C<kill -USR1 `cat logs/httpd.pid`>), Perl scripts and modules are
   not reloaded.  To reload B<PerlRequire>'s, B<PerlModule>'s, other
  -use()'d modules and flush the B<Apache::Registry> cache, enable with 
  +C<use()>'d modules and flush the B<Apache::Registry> cache, enable with 
   this command:
   
    PerlFreshRestart On  
  @@ -133,7 +135,7 @@
   =item PERL_DESTRUCT_LEVEL
   
   With Apache versions 1.3.0 and higher, mod_perl will call the
  -perl_destruct() Perl API function during the child exit phase.
  +C<perl_destruct()> Perl API function during the child exit phase.
   This will cause proper execution of B<END> blocks found during server
   startup along with invoking the B<DESTROY> method on global objects
   who are still alive.  It is possible that this operation may take a
  @@ -144,7 +146,7 @@
   
   =back
   
  -=head1 ENVIRONMENT
  +=head1 Environment
   
   Under CGI the Perl hash C<%ENV> is magical in that it inherits
   environment variables from the parent process and will set them should
  @@ -166,7 +168,7 @@
   
   =over 4
   
  -=item CONFIGURATION
  +=item Configuration
   
   The C<PerlSetVar> and C<PerlAddVar> directives provide a simple
   mechanism for passing information from configuration files to Perl
  @@ -234,19 +236,56 @@
   
   Modules and files pulled in via require/use which contain C<BEGIN>
   blocks will be executed:
  -  - only once, if pulled in by the parent process
  -  - once per-child process if not pulled in by the parent process
  -  - an additional time, once per-child process if the module is pulled in off of disk again via Apache::StatINC
  -  - an additional time, in the parent process on each restart if PerlFreshRestart is On
  -  - unpredictable if you fiddle with C<%INC> yourself
  +
  +=over
  +
  +=item *
  +
  +only once, if pulled in by the parent process
  +
  +=item *
  +
  +once per-child process if not pulled in by the parent process
  +
  +=item *
  +
  +an additional time, once per-child process if the module is pulled in off
  +of disk again via C<Apache::StatINC>
  +
  +=item *
  +
  +an additional time, in the parent process on each restart if
  +I<PerlFreshRestart> is I<On>
  +
  +=item *
  +
  +unpredictable if you fiddle with C<%INC> yourself
  +
  +=back
   
   B<Apache::Registry> scripts which contain C<BEGIN> blocks will be
   executed: 
  -  - only once, if pulled in by the parent process via B<Apache::RegistryLoader>
  -  - once per-child process if not pulled in by the parent process
  -  - an additional time, once per-child process if the script file has changed on disk
  -  - an additional time, in the parent process on each restart if pulled in by the
  -    parent process via B<Apache::RegistryLoader> and PerlFreshRestart is On
  +
  +=over
  +
  +=item *
  +
  +only once, if pulled in by the parent process via B<Apache::RegistryLoader>
  +
  +=item *
  +
  +once per-child process if not pulled in by the parent process
  +
  +=item *
  +
  +an additional time, once per-child process if the script file has changed on disk
  +
  +=item *
  +
  +an additional time, in the parent process on each restart if pulled in by the
  +parent process via B<Apache::RegistryLoader> and PerlFreshRestart is On
  +
  +=back
   
   =head1 END blocks
   
  @@ -272,9 +311,9 @@
   Module authors may be wish to use C<$r-E<gt>register_cleanup> as an
   alternative to C<END> blocks if this behavior is not desirable. 
   
  -=head1 MEMORY CONSUMPTION
  +=head1 Memory consumption
   
  -Don't be alarmed by the size of your httpd after you've linked with
  +Don't be alarmed by the size of your I<httpd> after you've linked with
   mod_perl.  No matter what, your httpd will be larger than normal to start, 
   simply because you've linked with perl's runtime.
   
  @@ -291,28 +330,28 @@
   
    10545 dougm     49    0  3732K 3340K run     0:05 54.59% 21.48% perl
   
  -Here's my httpd linked with libperl.a, not having served a single request:
  +Here's my I<httpd> linked with I<libperl.a>, not having served a single request:
   
    10386 dougm      5    0  1032K  324K sleep   0:00  0.12%  0.11% httpd-a
   
   You can reduce this if you configure perl 5.004+ with -Duseshrplib.
  -Here's my httpd linked with libperl.sl, not having served a single request:
  +Here's my I<httpd> linked with I<libperl.sl>, not having served a single request:
   
    10393 dougm      5    0   476K  368K sleep   0:00  0.12%  0.10% httpd-s
   
   Now, once the server starts receiving requests, the embedded
  -interpreter will compile code for each 'require' file it has not seen
  -yet, each new Apache::Registry subroutine that's compiled, along with
  +interpreter will compile code for each 'C<require>' file it has not seen
  +yet, each new B<Apache::Registry> subroutine that's compiled, along with
   whatever modules it's use'ing or require'ing.  Not to mention
  -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
  +AUTOLOADing.  (Modules that you 'C<use>' will be compiled when the server
  +starts unless they are inside an eval block.)  I<httpd> will grow just as
  +big as our I</usr/bin/perl> would, or a CGI process for that matter, it
   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').
  +The mod_perl I<INSTALL> document explains how to build the C<Apache::>
  +extensions as shared libraries (with 'C<perl Makefile.PL DYNAMIC=1>').
   This may save you some memory, however, it doesn't work on a few
   systems such as aix and unixware.
   
  @@ -322,7 +361,7 @@
   the same time.  See the L<mod_perl tuning|faqs::mod_perl_tuning>
   document for details.
   
  -=head2 MEMORY TIPS
  +=head2 Memory tips
   
   =over 4
   
  @@ -335,14 +374,14 @@
   =item Perl Options
   
   Newer Perl versions also have other options to reduce runtime memory
  -consumption.  See Perl's INSTALL file for details on C<-DPACK_MALLOC>
  +consumption.  See Perl's I<INSTALL> file for details on C<-DPACK_MALLOC>
   and C<-DTWO_POT_OPTIMIZE>.  With these options, my httpd shrinks down
   ~150K. 
   
   =item Server Startup
   
   Use the B<PerlRequire> and B<PerlModule> directives to load commonly
  -used modules such as CGI.pm, DBI, etc., when the server is started.
  +used modules such as C<CGI.pm>, C<DBI>, etc., when the server is started.
   On most systems, server children will be able to share this space.
   
   =item Importing Functions
  @@ -350,15 +389,15 @@
   When possible, avoid importing of a module functions into your
   namespace.  The aliases which are created can take up quite a bit of
   space.  Try to use method interfaces and fully qualified
  -Package::function names instead.
  -Here's a freshly started httpd who's served one request for a script
  -using the CGI.pm method interface:
  +C<Package::function> names instead.  Here's a freshly started httpd
  +who's served one request for a script using the C<CGI.pm> method
  +interface:
   
    TTY   PID USERNAME  PRI NI   SIZE   RES  STATE   TIME %WCPU  %CPU COMMAND
      p4  5016 dougm     154 20  3808K  2636K sleep   0:01  9.62  4.07 httpd
   
   Here's a freshly started httpd who's served one request for the same
  -script using the CGI.pm function interface:
  +script using the C<CGI.pm> function interface:
   
    TTY   PID USERNAME  PRI NI   SIZE   RES  STATE   TIME %WCPU  %CPU COMMAND
      p4  5036 dougm     154 20  3900K  2708K sleep   0:01  3.19  2.18 httpd
  @@ -371,7 +410,7 @@
   
   It's always a good idea to stay away from global variables when
   possible.  Some variables must be global so Perl can see them, such as
  -a module's B<@ISA> or B<$VERSION> variables.  In common practice, a
  +a module's C<@ISA> or C<$VERSION> variables.  In common practice, a
   combination of C<use strict> and C<use vars> keeps modules clean and
   reduces a bit of noise.  However, B<use vars> also creates aliases as
   the B<Exporter> does, which eat up more space.  When possible, try to
  @@ -392,16 +431,16 @@
   
   =item Further Reading
   
  -In case I forgot to mention, read Vivek Khera's L<mod_perl
  +In case I forgot to mention it, 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
  +=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
  +invoke it with C<`#!'>, 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
  @@ -424,9 +463,9 @@
   perl startup flags such as B<-d> and B<-D>.  See the I<perlrun>
   manpage.
   
  -=head1 PERSISTENT DATABASE CONNECTIONS
  +=head1 Persistent Database Connections
   
  -Another popular use of mod_perl is to take advantage of it's
  +Another popular use of mod_perl is to take advantage of its
   persistance to maintain open database connections.  The basic idea
   goes like so:
   
  @@ -440,7 +479,7 @@
   keeping the connection open for the lifetime of a server process,
   establishing it during the script's first request for that process.
   
  -It's recommended that you use one of the Apache::* database connection
  +It's recommended that you use one of the C<Apache::*> database connection
   wrappers.  Currently for DBI users there is C<Apache::DBI> and for
   Sybase users C<Apache::Sybase::DBlib>.  These modules hide the
   peculiar code example above.  In addition, different scripts may share
  @@ -453,7 +492,7 @@
    my $dbh = DBI->connect(...);
   
   Although B<$dbh> shown here will go out of scope when the script ends,
  -the Apache::DBI module's reference to it does not, keep the connection
  +the C<Apache::DBI> module's reference to it does not, keep the connection
   open.
   
   B<WARNING:> Do not attempt to open a persistent database connection in
  @@ -462,21 +501,21 @@
   handle is used by two processes at the same time.  Each child must
   have it's own unique connection handle.
   
  -=head1 STACKED HANDLERS
  +=head1 Stacked Handlers
   
   With the mod_perl stacked handlers mechanism, it is possible for more
  -than one Perl*Handler to be defined and run during each stage of a 
  +than one C<Perl*Handler> to be defined and run during each stage of a 
   request.  
   
  -Perl*Handler directives can define any number of subroutines,
  +C<Perl*Handler> directives can define any number of subroutines,
   e.g. (in config files)
   
    PerlTransHandler OneTrans TwoTrans RedTrans BlueTrans
   
  -With the method, Apache-E<gt>push_handlers, callbacks can be added to
  +With the method, C<Apache-E<gt>push_handlers>, callbacks can be added to
   the stack by scripts at runtime by mod_perl scripts.
   
  -Apache-E<gt>push_handlers takes the callback hook name as it's first
  +C<Apache-E<gt>push_handlers> takes the callback hook name as it's first
   argument and a subroutine name or reference as it's second. e.g.:
   
    Apache->push_handlers("PerlLogHandler", \&first_one);
  @@ -489,54 +528,54 @@
   After each request, this stack is cleared out.
   
   All handlers will be called unless a handler returns a status other than
  -OK or DECLINED, this needs to be considered more.  Post apache-1.2 will
  -have a DONE return code to signal termiation of a stage, which Rob and
  +C<OK> or C<DECLINED>, this needs to be considered more.  Post apache-1.2 will
  +have a C<DONE> return code to signal termiation of a stage, which Rob and
   I came up with while back when first discussing the idea of stacked
   handlers.  2.0 won't come for quite sometime, so mod_perl will most
   likely handle this before then. 
   
   example uses:
   
  -CGI.pm maintains a global object for it's plain function interface.
  -Since the object is global, it does not go out of scope, DESTROY is
  -never called.  CGI-E<gt>new can call: 
  +C<CGI.pm> maintains a global object for it's plain function interface.
  +Since the object is global, it does not go out of scope, C<DESTROY> is
  +never called.  C<CGI-E<gt>new> can call: 
   
    Apache->push_handlers("PerlCleanupHandler", \&CGI::_reset_globals);
   
   This function will be called during the final stage of a request,
  -refreshing CGI.pm's globals before the next request comes in.  
  +refreshing C<CGI.pm>'s globals before the next request comes in.  
   
  -Apache::DCELogin establishes a DCE login context which must exist for
  -the lifetime of a request, so the DCE::Login object is stored in a
  +C<Apache::DCELogin> establishes a DCE login context which must exist for
  +the lifetime of a request, so the C<DCE::Login> object is stored in a
   global variable.  Without stacked handlers, users must set 
   
    PerlCleanupHandler Apache::DCELogin::purge
   
   in the configuration files to destroy the context.  This is not
  -"user-friendly".  Now, Apache::DCELogin::handler can call:
  +"user-friendly".  Now, C<Apache::DCELogin::handler> can call:
   
    Apache->push_handlers("PerlCleanupHandler", \&purge);
   
  -Persistent database connection modules such as Apache::DBI could push
  -a PerlCleanupHandler handler that iterates over %Connected, refreshing
  -connections or just checking that ones have not gone stale.  Remember,
  -by the time we get to PerlCleanupHandler, the client has what it wants
  -and has gone away, we can spend as much time as we want here without
  -slowing down response time to the client.
  +Persistent database connection modules such as C<Apache::DBI> could push
  +a C<PerlCleanupHandler> handler that iterates over C<%Connected>,
  +refreshing connections or just checking that ones have not gone stale.
  +Remember, by the time we get to C<PerlCleanupHandler>, the client has
  +what it wants and has gone away, we can spend as much time as we want
  +here without slowing down response time to the client.
   
   PerlTransHandlers may decide, based or uri or other condition, whether
  -or not to handle a request, e.g. Apache::MsqlProxy.  Without stacked
  +or not to handle a request, e.g. C<Apache::MsqlProxy>.  Without stacked
   handlers, users must configure:
   
    PerlTransHandler Apache::MsqlProxy::translate
    PerlHandler      Apache::MsqlProxy
   
  -PerlHandler is never actually invoked unless translate() sees the
  -request is a proxy request ($r-E<gt>proxyreq), if it is a proxy request,
  -translate() set $r-E<gt>handler("perl-script"), only then will PerlHandler
  -handle the request.  Now, users do not have to specify 'PerlHandler
  -Apache::MsqlProxy', the translate() function can set it with
  -push_handlers().
  +PerlHandler is never actually invoked unless C<translate()> sees the
  +request is a proxy request (C<$r-E<gt>proxyreq)>, if it is a proxy request,
  +C<translate()> set C<$r-E<gt>handler("perl-script")>, only then will
  +PerlHandler handle the request.  Now, users do not have to specify
  +'C<PerlHandler Apache::MsqlProxy>', the C<translate()> function can set
  +it with C<push_handlers()>.
   
   Includes, footers, headers, etc., piecing together a document,
   imagine (no need for SSI parsing!):
  @@ -576,7 +615,7 @@
      PerlHandler OutputParser AnotherApp
    </Location>
   
  -Now, OutputParser goes first, but it untie's *STDOUT and re-tie's to
  +Now, OutputParser goes first, but it unties C<*STDOUT> and re-ties to
   it's own package like so:
   
    package OutputParser;
  @@ -607,20 +646,20 @@
   
    % perl Makefile.PL PERL_STACKED_HANDLERS=1 [PERL_FOO_HOOK=1,etc]
   
  -Another method 'Apache-E<gt>can_stack_handlers' will return TRUE if
  +Another method 'C<Apache-E<gt>can_stack_handlers>' will return TRUE if
   mod_perl was configured with PERL_STACKED_HANDLERS=1, FALSE
   otherwise. 
   
  -=head1 PERL METHOD HANDLERS
  +=head1 Perl Method Handlers
   
   See L<How to use mod_perl's MethodHandlers|faqs::mod_perl_method_handlers>.
   
  -=head1 PERL SECTIONS
  +=head1 Perl Section
   
  -With E<lt>PerlE<gt>E<lt>/PerlE<gt> sections, it is possible to
  +With C<E<lt>PerlE<gt>E<lt>/PerlE<gt>> sections, it is possible to
   configure your server entirely in Perl.
   
  -E<lt>PerlE<gt> sections can contain *any* and as much Perl code as you
  +E<lt>PerlE<gt> sections can contain C<any> and as much Perl code as you
   wish.  These sections are compiled into a special package who's symbol
   table mod_perl can then walk and grind the names and values of Perl
   variables/structures through the Apache core config gears.  Most of
  @@ -671,7 +710,7 @@
   
   These are somewhat boring examples, but they should give you the basic
   idea.  You can mix in any Perl code your heart desires.
  -See eg/httpd.conf.pl and eg/perl_sections.txt for some examples.
  +See I<eg/httpd.conf.pl> and I<eg/perl_sections.txt> for some examples.
   
   A tip for syntax checking outside of httpd:
   
  @@ -687,26 +726,28 @@
   
   It may be the case that E<lt>PerlE<gt> sections are not completed or
   an oversight was made in an certain area.  If they do not behave as
  -you expect, please send a report to the modperl mailing list.
  +you expect, please send a report to the L<modperl mailing
  +list|maillist::list-modperl>.
   
   To configure this feature build with 
  +
    'perl Makefile.PL PERL_SECTIONS=1'
   
   =head1 mod_perl and mod_include integration
   
   As of apache 1.2.0, mod_include can handle Perl callbacks.
   
  -A `sub' key value may be anything a Perl*Handler can be:
  -subroutine name, package name (defaults to package::handler),
  -Class-E<gt>method call or anonymous sub {}
  +A `C<sub>' key value may be anything a C<Perl*Handler> can be:
  +subroutine name, package name (defaults to C<package::handler>),
  +C<Class-E<gt>method> call or anonymous C<sub { }>
   
   Example:
   
    Child <!--#perl sub="sub {print $$}" --> accessed
    <!--#perl sub="sub {print ++$Access::Cnt }" --> times. <br>
  -
  + 
    <!--#perl sub="Package::handler" arg="one" arg="two" -->
  -
  + 
    #don't forget to escape double quotes!
    Perl is
           <!--#perl sub="sub {for (0..10) {print \"very \"}}"-->
  @@ -719,11 +760,11 @@
   
    <!--#perl sub="Apache::Include" arg="/perl/ssi.pl" -->
   
  -You can also use 'virtual include' to include Apache::Registry scripts
  -of course.  However, using #perl will save the overhead of making
  +You can also use 'C<virtual include>' to include C<Apache::Registry> scripts
  +of course.  However, using C<#perl> will save the overhead of making
   Apache go through the motions of creating/destroying a subrequest and
   making all the necessary access checks to see that the request would
  -be allowed outside of a 'virtual include' context.
  +be allowed outside of a 'C<virtual include>' context.
   
   To enable perl in mod_include parsed files, when building apache the
   following must be present in the Configuration file:
  @@ -735,17 +776,20 @@
    perl Makefile.PL PERL_SSI=1
   
   If you're interested in sprinkling Perl code inside your HTML
  -documents, you'll also want to look at the Apache::Embperl
  -(http://perl.apache.org/embperl/), Apache::ePerl and Apache::SSI modules. 
  +documents, you'll also want to look at the C<Apache::Embperl>
  +(http://perl.apache.org/embperl/), C<Apache::ePerl>
  +(http://www.engelschall.com/sw/eperl/), C<Apache::ASP> 
  +(http://www.apache-asp.org/), C<HTML::Mason> (http://www.masonhq.com/)
  +and C<Apache::SSI> modules.
   
  -=head1 DEBUGGING
  +=head1 Debugging
   
   =over 4
   
   =item MOD_PERL_TRACE
   
   To enable mod_perl debug tracing configure mod_perl with the
  -PERL_TRACE option:
  +C<PERL_TRACE> option:
   
    perl Makefile.PL PERL_TRACE=1
   
  @@ -774,7 +818,7 @@
   
   =back
   
  -=head1 PROFILING
  +=head1 Profiling
   
   It is possible to profile code run under mod_perl with the
   B<Devel::DProf> module available on CPAN.  However, you must have
  @@ -793,18 +837,18 @@
   
   See also: B<Apache::DProf>
   
  -=head1 BENCHMARKING
  +=head1 Benchmarking
   
   How much faster is mod_perl that CGI?  There are many ways to
  -benchmark the two, see the C<benchmark/> directory for some examples.
  +benchmark the two, see the I<benchmark/> directory for some examples.
   
   See also: B<Apache::Timeit>
   
  -=head1 WARNINGS
  +=head1 Warnings
   
   See L<common/known mod_perl traps|faqs::mod_perl_traps>.
   
  -=head1 SUPPORT
  +=head1 Support
   
   See the I<SUPPORT> file.
   
  @@ -817,10 +861,6 @@
   
    http://perl.apache.org/distributions/
   
  -=head1 REVISION
  -
  -$Id: mod_perl.pod,v 1.3 2002/03/20 17:42:05 stas Exp $
  -
   =head1 Maintainers
   
   Maintainer is the person(s) you should contact with updates,
  @@ -846,6 +886,5 @@
   
   Only the major authors are listed above. For contributors see the
   Changes file.
  -
   
   =cut
  
  
  
  1.3       +7 -7      modperl-docs/src/docs/1.0/faqs/mod_perl_api.pod
  
  Index: mod_perl_api.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/mod_perl_api.pod,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- mod_perl_api.pod	20 Mar 2002 17:42:05 -0000	1.2
  +++ mod_perl_api.pod	18 Apr 2002 18:13:05 -0000	1.3
  @@ -1,8 +1,8 @@
   =head1 NAME
   
  -Mod_perl_api - accessing the Apache API via mod_perl
  +Accessing the Apache API via mod_perl
   
  -=head1 DESCRIPTION
  +=head1 Description
   
   This part of the mod_perl FAQ deals with the Apache Application
   Programmer's Interface and how to access it from perl via mod_perl.
  @@ -11,7 +11,7 @@
   
   =head2 Did you enable the required hook?
   
  -As described in the mod_perl/INSTALL document, the only callback hook
  +As described in the I<mod_perl/INSTALL> document, the only callback hook
   enabled by default is PerlHandler.  If you want to intervene at a
   different stage of request processing you must enable the relevant
   hook.  So to add a special authentication handler, for instance, you
  @@ -29,8 +29,8 @@
   If this directive is put in access.conf outside of any restrictive
   context, your handler will be called during the given phase of each
   request processed by the server.  You can make it more selective by
  -restricting it to a directory (-hierarchy) in a E<lt>Directory ...E<gt>
  -section of access.conf or by putting it in a .htaccess file.
  +restricting it to a directory (-hierarchy) in a C<E<lt>Directory ...E<gt>>
  +section of access.conf or by putting it in a I<.htaccess> file.
   
   Here is an example of the directives needed to call a handler during
   Apache's URI to filename translation phase:
  @@ -38,7 +38,7 @@
     PerlRequire         /full/path/to/script/Trans.pl
     PerlTransHandler   Trans::handler
   
  -Trans.pl would start with the statement C<Package Trans;> and define a
  +I<Trans.pl> would start with the statement C<package Trans;> and define a
   subroutine called C<handler>.
   
   =head1 Where can I find examples to get me started?
  @@ -105,7 +105,7 @@
   Ralf Engelschall writes:
   
   When you compiled one httpd with and the other without mod_perl, then
  -you can simply use E<lt>IfModule mod_perl.cE<gt>...E<lt>/IfModuleE<gt>
  +you can simply use C<E<lt>IfModule mod_perl.cE<gt>...E<lt>/IfModuleE<gt>>
   to surround the stuff for the httpd compiled with mod_perl. The other
   then ignores these lines. Example:
   
  
  
  
  1.5       +8 -8      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.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- mod_perl_cgi.pod	20 Mar 2002 17:42:05 -0000	1.4
  +++ mod_perl_cgi.pod	18 Apr 2002 18:13:05 -0000	1.5
  @@ -1,8 +1,8 @@
   =head1 NAME
   
  -Mod_perl_cgi - running CGI scripts under mod_perl
  +Running CGI scripts under mod_perl
   
  -=head1 DESCRIPTION
  +=head1 Description
   
   This part of the mod_perl FAQ deals with questions surrounding CGI
   scripts.
  @@ -37,8 +37,8 @@
   
     perl -c /path/to/my/mod_perl/scripts/foo
   
  -says it is OK, you have probably used __END__ or __DATA__.  Sorry.
  -Mod_perl's Apache::Registry can't deal with that.
  +says it is OK, you have probably used C<__END__> or C<__DATA__>.  Sorry.
  +Mod_perl's C<Apache::Registry> can't deal with that.
   
   =head1 My CGI script behaves strangely under mod_perl.  Why?
   
  @@ -80,7 +80,7 @@
   C<exit()> with C<goto label;>
   
   See also what mod_perl_traps says about C<Apache::exit()> and the way
  -that Apache::Registry causes it to terminate the script but not the
  +that C<Apache::Registry> causes it to terminate the script but not the
   httpd child.
   
   There may be exceptional circumstances in which you explicitly want to
  @@ -107,7 +107,7 @@
   It is good for you!  It will make perl point out all variables that you
   have not explicitly declared.  You can then think about whether they need
   to be global or if they can be lexical.  Try to declare things lexically,
  -with my().  These variables disappear when the block they are declared in
  +with C<my()>.  These variables disappear when the block they are declared in
   ends, so they don't occupy memory when they are not in use and they also
   do not need a run-time symbol table entry.
   
  @@ -158,8 +158,8 @@
   =head2 Variables B<still> retain their value from one request to the next
   
   CGI.pm must pull some extra tricks when it is being used via
  -Apache::Registry.  Versions of CGI.pm before 2.35 did not know this,
  -and Apache::Registry will complain if you try to use an earlier
  +C<Apache::Registry>.  Versions of CGI.pm before 2.35 did not know this,
  +and C<Apache::Registry> will complain if you try to use an earlier
   version.
   
   CGI.pm detects that it is running under Apache::Registry by looking
  
  
  
  1.4       +9 -9      modperl-docs/src/docs/1.0/faqs/mod_perl_cvs.pod
  
  Index: mod_perl_cvs.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/mod_perl_cvs.pod,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- mod_perl_cvs.pod	25 Mar 2002 03:39:00 -0000	1.3
  +++ mod_perl_cvs.pod	18 Apr 2002 18:13:05 -0000	1.4
  @@ -1,14 +1,14 @@
   =head1 NAME
   
  -mod_perl_cvs - Access to the mod_perl CVS development tree
  +Access to the mod_perl CVS development tree
   
  -=head1 DESCRIPTION
  +=head1 Description
   
  -The mod_perl development tree lives on cvs.apache.org.  This tree
  +The mod_perl development tree lives on C<cvs.apache.org>.  This tree
   contains the latest mod_perl bug fixes and developments that have not
   made it to CPAN yet.  Welcome to the bleeding edge.
   
  -=head1 SYNOPSIS
  +=head1 Synopsis
   
   Just as cvs access to the Apache development tree, the mod_perl code
   pulled from cvs is not guaranteed to do anything, especially not
  @@ -19,7 +19,7 @@
   welcome, simply testing the latest snapshots is just as, if not more
   helpful.
   
  -It's recommended to subscribe to the I<modperl-cvs@perl.apache.org> list,
  +It's recommended to subscribe to the L<modperl-cvs|maillist::list-cvs> list,
   which is the place cvs commit logs and diffs are mailed to; at least
   if you're going to work on the code.
   
  @@ -31,7 +31,7 @@
   
   Cvsup has come out of the FreeBSD group. It's a client/server
   beast that offers an efficient way to sync collections of files over
  -the net, and it is very CVS aware, allowing syncronisation of repositories
  +the net, and it is very CVS aware, allowing synchronisation of repositories
   or checked out files using the cvs deltas to bring the client side
   files up to date with minimal data transfer.
   
  @@ -72,7 +72,7 @@
    cvs -d ":pserver:anoncvs@cvs.apache.org:/home/cvspublic" co modperl
   
   
  -For a basic introduction to anoncvs see http://dev.apache.org/anoncvs.txt 
  +For a basic introduction to anoncvs see http://httpd.apache.org/dev/anoncvs.txt 
   
   
   =item from-cvs
  @@ -85,11 +85,11 @@
   A snapshot of the Apache development tree is also rolled every 6 hours
   and placed here:
   
  -http://cvs.apache.org/snapshots/
  +http://cvs.apache.org/snapshots/apache-1.3/
   
   =back
   
  -=head1 SEE ALSO
  +=head1 See Also
   
   cvs(1)
   
  
  
  
  1.6       +38 -47    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.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- mod_perl_faq.pod	20 Mar 2002 17:42:05 -0000	1.5
  +++ mod_perl_faq.pod	18 Apr 2002 18:13:05 -0000	1.6
  @@ -1,15 +1,15 @@
   =head1 NAME
   
  -Mod_perl_faq - frequently asked questions about mod_perl
  +Frequently Asked Questions about mod_perl
   
  -=head1 DESCRIPTION
  +=head1 Description
   
   Mod_perl allows an Apache Web Server to directly execute perl code.  This
   document is designed to answer questions that arise when designing new
   applications, and converting existing applications, to run in the mod_perl
   environment.
   
  -=head1 QUESTIONS & ANSWERS
  +=head1 Questions & Answers
   
   =head2 What is mod_perl?
   
  @@ -47,48 +47,45 @@
   
   =item Perl
   
  -http://www.perl.com/CPAN/src/latest.tar.gz
  -
  -Win32 users note: at the time of writing, ActiveState's Perl cannot be
  -used with mod_perl, because it is based on an old version of perl
  -(perl-5.003_07, build 316).
  +http://www.cpan.org/src/latest.tar.gz
   
   =item Apache
   
  -http://www.apache.org/dist/
  +http://httpd.apache.org/dist/
   
   =back
   
   =head2 How do I install it?
   
   Here is the easiest way to proceed.  Let's assume you have the latest
  -version of perl (5.004) installed.  Unpack the Apache and Mod_perl
  +version of perl installed.  Unpack the Apache and Mod_perl
   tarballs next to one another under a common directory: e.g.
   
     % cd /usr/local/src
  -  % zcat apache_1.2.0.tar.gz | tar xf -
  -  % zcat mod_perl-0.98_12.tar.gz | tar xf -
  +  % zcat apache_1.3.24.tar.gz | tar xf -
  +  % zcat mod_perl-1.26.tar.gz | tar xf -
   
   You probably do not need to change anything in the apache configuration
   before compiling.  Only if you want to enable additional non-standard
  -modules do you need to edit apache_1.2.0/src/Configuration.  There is no
  +modules do you need to edit apache_1.3.24/src/Configuration.  There is no
   need to set CC, CFLAGS, etc., because mod_perl will override them with the
   values that were used to compile your perl.
   
   Now go to the mod_perl directory and follow the instructions in the
  -INSTALL file there.  If "make test" and "make install" are successful, you
  -will find the new web server in apache_1.2.0/src/httpd.  Move it to a
  +I<INSTALL> file there.  If "make test" and "make install" are successful, you
  +will find the new web server in apache_1.3.24/src/httpd.  Move it to a
   suitable location, make sure it has access to the correct configuration
   files, and fire it up.
   
   =head2 What documentation should I read?
   
   The mod_perl documentation in mod_perl.pod.  After you have installed
  -mod_perl you can read it with the command: C<perldoc mod_perl>.
  +mod_perl you can read it with the command:
  +L<perldoc mod_perl|faqs::mod_perl>.
   
   If you are using mod_perl to extend the server functionality, you will
   need to read C<perldoc Apache> and the Apache API notes, which can be
  -found in apache_1.2.0/htdocs/manual/misc/API.html.
  +found in apache_1.3.24/htdocs/manual/misc/API.html.
   
   Existing (perl-) CGI scripts should run as-is under mod_perl.  There are a
   number of reasons why they may need to be adjusted, and these are
  @@ -126,23 +123,24 @@
   You will have to start a new process that runs under a suitable user-id
   (or group-id).  If all requests handled by the script will need the higher
   privileges, you might as well write it as a suid CGI script.  Read the
  -documentation about suEXEC in Apache-1.2.
  +documentation about suEXEC in Apache-1.3.
   
   Alternatively, pre-process the request with mod_perl and fork a suid
   helper process to handle the privileged part of the task.
   
   =head2 Why is httpd using so much memory?
   
  -Read the section on "Memory Consumption" in the mod_perl.pod.
  +Read the section on "Memory Consumption" in the
  +L<mod_perl.pod|faqs::mod_perl/Memory_Consumption>.
   
   Make sure that your scripts are not leaking memory.  Global variables
  -stay around indefinitely, lexical variables (declared with my()) are
  +stay around indefinitely, lexical variables (declared with C<my()>) are
   destroyed when they go out of scope, provided there are no references
   to them from outside of that scope.
   
   To get information about the modules that have been loaded and their
  -symbol-tables, use the Apache::Status module.  It is enabled by adding
  -these lines to a configuration file (e.g. access.conf);
  +symbol-tables, use the C<Apache::Status> module.  It is enabled by adding
  +these lines to a configuration file (e.g. I<httpd.conf>);
   
     <Location /perl-status>
     SetHandler  perl-script
  @@ -165,20 +163,10 @@
   
   =head2 Do I have to restart the server when I change my Perl code?
   
  -Apache::Registry checks the timestamp of scripts that it has loaded
  +C<Apache::Registry> checks the timestamp of scripts that it has loaded
   and reloads them if they change.  This does not happen for other
  -handlers, unless you program it yourself.  One way to do this is in a
  -PerlInitHandler.  If you define
  -
  -  sub MY::init {
  -      delete $INC{"YourModule.pm"};
  -      require YourModule;
  -  }
  -
  -as an init handler, it will unconditionally reload YourModule at the
  -start of each request, which may be useful while you are developing a
  -new module.  It can be made more efficient by storing the timestamp of
  -the file in a global variable and only reloading when necessary.
  +handlers, unless you program it yourself.  You should look into the module
  +C<Apache::StatINC> to do this.
   
   =head2 So how do I use mod_perl in conjunction with ErrorDocument?
   
  @@ -268,8 +256,8 @@
   
   Open questions I could not find documentation for (except RTFS): what
   exactly is PerlSendHeaders and PerlNewSendHeaders. What is the default
  -setting for those? How do these cooperate with CGI.pm, Apache.pm,
  -Apache::Registry?
  +setting for those? How do these cooperate with C<CGI.pm>, C<Apache.pm>,
  +C<Apache::Registry>?
   
   =back
   
  @@ -336,7 +324,7 @@
   require it, you need to be sure that the file containing sub_foo sets
   a package name.  Otherwise, sub_foo gets defined in the namespace that
   is active the first time it is required, and the next require is a
  -no-op because that file is already in %INC.
  +no-op because that file is already in C<%INC>.
   
   The solution is simple, set up your require'd file something along
   these lines:
  @@ -345,7 +333,7 @@
   
     sub sub_foo {...}
   
  -Now, have scripts call SomeName::sub_foo() instead of sub_foo().
  +Now, have scripts call C<SomeName::sub_foo()> instead of C<sub_foo()>.
   
   =head2 What could be causing sporadic errors "in cleanup"?
   
  @@ -356,10 +344,10 @@
   
   Doug writes:
   
  -"I have yet to figure out why, but there have been a few arbitrary
  -cases where Perl (in mod_perl) _insists_ on finding and/or calling a
  -DESTROY method for an object.  Defining an empty sub DESTROY has been
  -the bandaid for these few cases."
  +  "I have yet to figure out why, but there have been a few arbitrary
  +  cases where Perl (in mod_perl) _insists_ on finding and/or calling a
  +  DESTROY method for an object.  Defining an empty sub DESTROY has been
  +  the bandaid for these few cases."
   
   If the specific error message gives you a hint about which object is
   causing difficulty, put the C<sub DESTROY { }> in the module that
  @@ -373,8 +361,8 @@
   
     $ENV{"GATEWAY_INTERFACE"} eq "CGI-Perl/1.1"
   
  -The MOD_PERL variable gets set immediately when the perl interpreter
  -starts up, whereas GATEWAY_INTERFACE may not be set yet when BEGIN
  +The C<MOD_PERL> variable gets set immediately when the perl interpreter
  +starts up, whereas C<GATEWAY_INTERFACE> may not be set yet when C<BEGIN>
   blocks are being processed.
   
   =head1 Maintainers
  @@ -386,8 +374,11 @@
   
   =item *
   
  -Frank D. Cringle E<lt>fdc@cliwe.ping.deE<gt> or the L<modperl docs
  -list|maillist::list-docs-dev>
  +Frank D. Cringle E<lt>fdc@cliwe.ping.deE<gt> 
  +
  +=item * 
  +
  +the L<modperl docs list|maillist::list-docs-dev>
   
   =back
   
  
  
  
  1.5       +27 -25    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.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- mod_perl_method_handlers.pod	20 Mar 2002 17:42:05 -0000	1.4
  +++ mod_perl_method_handlers.pod	18 Apr 2002 18:13:05 -0000	1.5
  @@ -1,42 +1,43 @@
   =head1 NAME 
   
  -mod_perl_method_handlers - How to use mod_perl's MethodHandlers 
  +How to use mod_perl's MethodHandlers 
   
  -=head1 DESCRIPTION
  +=head1 Description
   
   Described here are a few examples and hints how to use MethodHandlers
  -with modperl.
  +with mod_perl.
   
   This document assumes familiarity with at least the I<perltoot>
  -manpage and "normal" usage of the Perl*Handlers.
  +manpage and "normal" usage of the C<Perl*Handlers>.
   
  -It isn't strictly modperl related, more like "what I use objects for
  -in my modperl environment".
  +It isn't strictly mod_perl related, more like "what I use objects for
  +in my mod_perl environment".
   
  -=head1 SYNOPSIS
  +=head1 Synopsis
   
  -If a Perl*Handler is prototyped with '$$', this handler will be
  +If a B<Perl*Handler> is prototyped with 'C<$$>', this handler will be
   invoked as method, being passed a class name or blessed object as its
   first argument and the blessed I<request_rec> as the second argument,
   e.g.
   
    package My;
    @ISA = qw(BaseClass);
  -
  + 
    sub handler ($$) {
        my($class, $r) = @_;
        ...;
    }
  -
  + 
    package BaseClass;
  -
  + 
    sub method ($$) {
        my($class, $r) = @_;
        ...;
    }
  -
  + 
    __END__
   
  +
   Configuration:
   
    PerlHandler My
  @@ -50,13 +51,13 @@
   
    PerlHandler My->method
   
  -In this case, the 'My' class inherits this method from 'BaseClass'.
  +In this case, the 'C<My>' class inherits this method from 'C<BaseClass>'.
   
   To build in this feature, configure with:
   
    % perl Makefile.PL PERL_METHOD_HANDLERS=1 [PERL_FOO_HOOK=1,etc]
   
  -=head1 WHY?
  +=head1 Why?
   
   The short version: For pretty much the same reasons we're using OO
   perl everywhere else. :-) See the I<perltoot> manpage.
  @@ -64,7 +65,7 @@
   The slightly longer version would include some about code reusage and
   more clean interface between modules.
   
  -=head1 SIMPLE EXAMPLE
  +=head1 Simple example
   
   Let's start with a simple example.
   
  @@ -92,14 +93,14 @@
   
    This::Class=HASH(0x8411edc) isa This::Class
   
  -=head1 A LITTLE MORE ADVANCED
  +=head1 A little more advanced
   
   That wasn't really useful, so let's try something little more advanced.
   
   I've a little module which creates a graphical 'datebar' for a client.
  -(See C<http://www.hip.dk/date_bar>). It's reading a lot of small gifs 
  -with numbers and weekdays, and keeping them in memory in GD.pm's native 
  -format, ready to be copied together and served as gifs.
  +It's reading a lot of small gifs with numbers and weekdays, and keeping
  +them in memory in GD.pm's native format, ready to be copied together and
  +served as gifs.
   
   Now I wanted to use it at another site too, but with a different
   look. Obviously something to do with a object. Hence I changed the
  @@ -117,7 +118,7 @@
   	 -elements  => 'wday hour min',
    );
   
  -And then use $Client1::Datebar and $Client2::Datebar as PerlHandlers in my
  +And then use C<$Client1::Datebar> and C<$Client2::Datebar> as PerlHandlers in my
   Apache configuration. Remember to pass them in literal quotes ('') and not
   "" which will be interpolated!
   
  @@ -146,7 +147,7 @@
   
   Very very useful!
   
  -=head1 TRAPS
  +=head1 Traps
   
   mod_perl expects object handlers to be in the form of a string, which it
   will thaw for you. That means that something like 
  @@ -166,7 +167,7 @@
        }
    );
   
  -=head1 AUTHOR
  +=head1 Author
   
   This document is written by Ask Bjoern Hansen E<lt>ask@netcetera.dkE<gt> or
   E<lt>ask@apache.orgE<gt>.  Corrections and suggestions are most
  @@ -176,9 +177,9 @@
   
   Some codesnippets is from Doug MacEachern.
   
  -=head1 SEE ALSO
  +=head1 See Also
   
  -The L<faqs::mod_perl>, the I<Apache>, the I<perltoot> manpages (also
  +The L<mod_per|faqs::mod_perl>, the I<Apache>, the I<perltoot> manpages (also
   available at C<http://www.perl.com/CPAN/doc/FMTEYEWTK/perltoot.html>)
   
   =head1 Maintainers
  @@ -200,7 +201,8 @@
   
   =item *
   
  -Doug MacEachern
  +Ask Bjoern Hansen, E<lt>ask (at) netcetera.dkE<gt> or E<lt>ask (at)
  +apache.orgE<gt>.
   
   =back
   
  
  
  
  1.4       +37 -33    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.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- mod_perl_traps.pod	20 Mar 2002 17:42:05 -0000	1.3
  +++ mod_perl_traps.pod	18 Apr 2002 18:13:05 -0000	1.4
  @@ -1,8 +1,11 @@
   =head1 NAME
   
  -mod_perl_traps - common/known mod_perl traps
  +Common/Known mod_perl traps
   
  -=head1 DESCRIPTION
  +=head1 Description
  +
  +All the features of mod_perl bring with them some common traps. This
  +document tries to tell you what they are and how to avoid them.
   
   In the CGI environment, the server starts a single external process
   (Perl interpreter) per HTTP request which runs single script in that
  @@ -35,7 +38,8 @@
   
   =item *
   
  -Apache::Registry scripts cannot contain  __END__ or __DATA__ tokens
  +C<Apache::Registry> scripts cannot contain  C<__END__> or C<__DATA__>
  +tokens.
   
   =item *
   
  @@ -44,15 +48,15 @@
   
   =item *
   
  -Perl's exit() built-in function cannot be used in mod_perl scripts.
  -The Apache::exit() function should be used instead.  Apache::exit()
  -automatically overrides the built-in exit() for Apache::Registry
  -and Apache::PerlRun scripts. 
  +Perl's C<exit()> built-in function cannot be used in mod_perl scripts.
  +The C<Apache::exit()> function should be used instead.  C<Apache::exit()>
  +automatically overrides the built-in C<exit()> for Apache::Registry
  +and C<Apache::PerlRun> scripts. 
   
   =item *
   
  -Your script *will not* run from the command line if your script makes
  -any direct calls to Apache-E<gt>methods.  See Apache::FakeRequest.
  +Your script B<will not> run from the command line if your script makes
  +any direct calls to C<Apache-E<gt>methods>.  See C<Apache::FakeRequest>.
   
   =back
   
  @@ -60,7 +64,7 @@
   
   =over 4
   
  -=item undefined subroutine &Apache::Registry::handler
  +=item undefined subroutine C<&Apache::Registry::handler>
   
   Interaction with certain modules causes the shortcut configuration to
   break, if you see this message change your configuration from this:
  @@ -86,13 +90,13 @@
   
   =item *
   
  -CGI.pm users B<must> have version B<2.39> of the package or higher,
  +C<CGI.pm> users B<must> have version B<2.39> of the package or higher,
   earlier versions will not work under mod_perl.
   
   =item *
   
   If you use the C<SendHeaders()> function, be sure to call
  -$req_obj-E<gt>cgi-E<gt>done when you are done with a request, just as you
  +C<$req_obj-E<gt>cgi-E<gt>done> when you are done with a request, just as you
   would under I<CGI::MiniSrv>. 
   
   =back
  @@ -105,7 +109,7 @@
   =item *
   
   Files pulled in via C<use> or C<require> statements are not
  -automatically reloaded when changed on disk.  See the Apache::StatINC 
  +automatically reloaded when changed on disk.  See the C<Apache::StatINC> 
   module to add this functionality.
   
   =item Undefined subroutines
  @@ -133,17 +137,17 @@
   
    #required_file.pl
    package Test;
  -
  + 
    sub some_function {...}
  -
  + 
    ...
  -
  + 
    __END__
   
   Now, have your scripts say:
   
    require "required_file.pl";
  -
  + 
    Test::some_function();
   
   
  @@ -170,17 +174,17 @@
   "Out of memory!" message and or "Callback called exit".  A common
   cause of this are never-ending loops, deep recursion or calling an
   undefined subroutine.  Here's one way to catch the problem:
  -See Perl's INSTALL document for this item:
  +See Perl's I<INSTALL> document for this item:
   
   =item -DPERL_EMERGENCY_SBRK
   
  -If PERL_EMERGENCY_SBRK is defined, running out of memory need not be a
  +If C<PERL_EMERGENCY_SBRK> is defined, running out of memory need not be a
   fatal error: a memory pool can allocated by assigning to the special
  -variable $^M.  See perlvar(1) for more details.
  +variable C<$^M>.  See perlvar(1) for more details.
   
  -If you compile with that option and add 'use Apache::Debug level =E<gt> 4;'
  -to your PerlScript, it will allocate the $^M emergency pool and the
  -$SIG{__DIE__} handler will call Carp::confess, giving you a stack
  +If you compile with that option and add 'C<use Apache::Debug level =E<gt> 4;>'
  +to your PerlScript, it will allocate the C<$^M> emergency pool and the
  +C<$SIG{__DIE__}> handler will call C<Carp::confess>, giving you a stack
   trace which should reveal where the problem is.
   
   See the B<Apache::Resource> module for prevention of spinning httpds.
  @@ -191,7 +195,7 @@
   Perl, it must be listed in static_ext in Perl's Config.pm to be linked
   with httpd during the mod_perl build.
   
  -=item Can't load '$Config{sitearchexp}/auto/Foo/Foo.so' for module Foo...
  +=item Can't load 'C<$Config{sitearchexp}/auto/Foo/Foo.so>' for module Foo...
   
   When starting httpd some people have reported seeing an error along
   the lines of:
  @@ -203,7 +207,7 @@
    Perl_sv_undef: referenced symbol not found at
    /usr/local/ap/lib/perl5/sun4-solaris/5.00404/DynaLoader.pm line 166. 
   
  -Or similar for the IO module or whatever dynamic module mod_perl tries
  +Or similar for the C<IO> module or whatever dynamic module mod_perl tries
   to pull in first.  The solution is to re-configure, re-build and
   re-install Perl and dynamic modules with the following flags when
   Configure asks for "additional LD flags":
  @@ -220,7 +224,7 @@
   
   OS distributions that ship with a (broken) binary Perl installation.
   
  -The `perl' program and `libperl.a' library are somehow built with
  +The `I<perl>' program and `I<libperl.a>' library are somehow built with
   different binary compatiblity flags.  
   
   The solution to these problems is to rebuild Perl and extension
  @@ -230,7 +234,7 @@
   
    % ./Configure -des -Dcc=gcc ... && make test && make install
   
  -Read Perl's INSTALL doc for more details.
  +Read Perl's I<INSTALL> doc for more details.
   
   =back
   
  @@ -258,7 +262,7 @@
   
    libs='-lnet -lnsl_s -lgdbm -lndbm -ldb -ldld -lm -lc -lndir -lcrypt';
   
  -Edit B<Config.pm> and move C<-lgdbm> and C<-ldb> to the end of the
  +Edit C<Config.pm> and move C<-lgdbm> and C<-ldb> to the end of the
   list.  Here's how to find B<Config.pm>:
   
    % perl -MConfig -e 'print "$Config{archlibexp}/Config.pm\n"'
  @@ -268,7 +272,7 @@
   Solaris already provides its own DBM and NDBM, and there's no reason
   to build GDBM with them (for us anyway).
   
  -In our Makefile for GDBM, we changed
  +In our I<Makefile> for GDBM, we changed
   
     OBJS = $(DBM_OF) $(NDBM_OF) $(GDBM_OF)
   
  @@ -276,13 +280,13 @@
   
     OBJS = $(GDBM_OF)
   
  -Rebuild libgdbm, then Apache/mod_perl.  
  +Rebuild I<libgdbm>, then Apache/mod_perl.  
   
   =back
   
  -=head1 REGULAR EXPRESSIONS
  +=head1 Regular expressions
   
  -=head2 COMPILED REGULAR EXPRESSIONS
  +=head2 Compiled regular expressions
   
   When using a regular expression that contains an interpolated Perl variable,
   if it is known that the variable (or variables) will not vary during the
  @@ -343,7 +347,7 @@
   
   The only gotcha is that the dummy match that boots the regular expression
   engine must absolutely, positively succeed, otherwise the pattern will not
  -be cached, and the // will match everything. If you can't count on fixed
  +be cached, and the C<//> will match everything. If you can't count on fixed
   text to ensure the match succeeds, you have two possibilities.
   
   If you can guaranteee that the pattern variable contains no meta-characters
  
  
  
  1.5       +22 -23    modperl-docs/src/docs/1.0/faqs/mod_perl_tuning.pod
  
  Index: mod_perl_tuning.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/mod_perl_tuning.pod,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- mod_perl_tuning.pod	20 Mar 2002 17:42:05 -0000	1.4
  +++ mod_perl_tuning.pod	18 Apr 2002 18:13:05 -0000	1.5
  @@ -1,8 +1,8 @@
   =head1 NAME
   
  -mod_perl_tuning - mod_perl performance tuning
  +mod_perl performance tuning
   
  -=head1 DESCRIPTION
  +=head1 Description
   
   Described here are examples and hints on how to configure a mod_perl
   enabled Apache server, concentrating on tips for configuration for
  @@ -22,16 +22,16 @@
   such as The Weather Channel's "Blimp Site-ings" game, the MSIE 4.0
   "Subscribe to Win" game, and the MSN Million Dollar Madness game.
   
  -=head1 BASIC CONFIGURATION
  +=head1 Basic Configuration
   
   The basic configuration for mod_perl is as follows.  In the
   F<httpd.conf> file, I add configuration parameters to make the
   C<http://www.example.com/programs> URL be the base location for all
   mod_perl programs.  Thus, access to
   C<http://www.example.com/programs/printenv> will run the printenv
  -script, as we'll see below.  Also, any *.perl file will be interpreted
  +script, as we'll see below.  Also, any I<*.perl> file will be interpreted
   as a mod_perl program just as if it were in the programs directory,
  -and *.rperl will be mod_perl, but I<without> any HTTP headers
  +and I<*.rperl> will be mod_perl, but I<without> any HTTP headers
   automatically sent; you must do this explicitly.  If you don't want
   these last two, just leave it out of your configuration.
   
  @@ -158,7 +158,7 @@
   When you run this, check the value of the GATEWAY_INTERFACE variable
   to see that you are indeed running mod_perl.
   
  -=head1 REDUCING MEMORY USE
  +=head1 Reducing Memory Use
   
   As a side effect of using mod_perl, your HTTPD processes will be
   larger than without it.  There is just no way around it, as you have
  @@ -196,7 +196,7 @@
   have set the C<PerlFreshRestart> configuration parameter in
   F<httpd.conf> to be "On".
   
  -=head1 REDUCING THE NUMBER OF LARGE PROCESSES
  +=head1 Reducing the Number of Large Processes
   
   Unfortunately, simply reducing the size of each HTTPD process is not
   enough on a very busy site.  You also need to reduce the quantity of
  @@ -224,7 +224,7 @@
   of a challenge when you have multiple servers running on the same
   host, since you must log to different files.
   
  -=head2 TWO MACHINES
  +=head2 Two Machines
   
   The simplest way is to put all static content on one machine, and all
   mod_perl programs on another.  The only trick is to make sure all
  @@ -237,7 +237,7 @@
   The drawback is that you must maintain two machines, and this can get
   expensive.  For extremely large projects, this is the best way to go.
   
  -=head2 TWO IP ADDRESSES
  +=head2 Two IP Addresses
   
   Similar to above, but one HTTPD runs bound to one IP address, while
   the other runs bound to another IP address.  The only difference is
  @@ -250,7 +250,7 @@
   to make each HTTPD respond only to one IP address on this host.  One
   will have mod_perl enabled, and the other will not.
   
  -=head2 TWO PORT NUMBERS
  +=head2 Two Port Numbers
   
   If you cannot get two IP addresses, you can also split the HTTPD
   processes as above by putting one on the standard port 80, and the
  @@ -269,7 +269,7 @@
   
   Thanks to Gerd Knops for this idea.
   
  -=head2 USING ProxyPass WITH TWO SERVERS
  +=head2 Using ProxyPass with two servers
   
   To overcome the limitation of the alternate port above, you can use
   dual Apache HTTPD servers with just slight difference in
  @@ -284,21 +284,21 @@
   that you have included the mod_proxy module in your server when it was
   built.
   
  -Now, when you access http://www.example.com/programs/printenv it will
  +Now, when you access I<http://www.example.com/programs/printenv> it will
   internally be passed through to your HTTPD running on port 8042 as the
  -URL http://localhost:8042/programs/printenv and the result relayed
  +URL I<http://localhost:8042/programs/printenv> and the result relayed
   back transparently.  To the client, it all seems as if it is just one
   server running.  This can also be used on the dual-host version to
   hide the second server from view if desired.
   
  -=begin html
  -<P>
  +=for html
  +<p>
   A complete configuration example of this technique is provided by
   two HTTPD configuration files.
  -<A HREF="httpd.conf.txt">httpd.conf</A> is for the main server for all
  -regular pages, and <A HREF="httpd%2bperl.conf.txt">httpd+perl.conf</A> is
  -for the mod_perl programs accessed in the <CODE>/programs</CODE> URL.
  -</P>
  +<a href="httpd.conf.txt">httpd.conf</a> is for the main server for all
  +regular pages, and <a href="httpd%2bperl.conf.txt">httpd+perl.conf</a> is
  +for the mod_perl programs accessed in the <code>/programs</code> URL.
  +</p>
   
   The directory structure assumes that F</var/www/documents> is the
   C<DocumentRoot> directory, and the the mod_perl programs are in
  @@ -308,15 +308,14 @@
    daemon httpd
    daemon httpd -f conf/httpd+perl.conf
   
  -=end html
   
   Thanks to Bowen Dwelle for this idea.
   
  -=head2 SQUID ACCELERATOR
  +=head2 Squid Accelerator
   
   Another approach to reducing the number of large HTTPD processes on
   one machine is to use an accelerator such as Squid (which can be found
  -at http://squid.nlanr.net/Squid/ on the web) between the clients and
  +at http://www.squid-cache.org/ on the web) between the clients and
   your large mod_perl HTTPD processes.  The idea here is that squid will
   handle the static objects from its cache while the HTTPD processes
   will handle mostly just the mod_perl requests once the cache is
  @@ -384,7 +383,7 @@
   ftp://ftp.netcetera.dk/pub/apache/ to make it insert the
   C<X-Forwarded-For> header.
   
  -=head1 SUMMARY
  +=head1 Summary
   
   To gain maximal performance of mod_perl on a busy site, one must
   reduce the amount of resources used by the HTTPD to fit within what
  
  
  
  1.6       +6 -6      modperl-docs/src/docs/1.0/faqs/perl_myth.pod
  
  Index: perl_myth.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/perl_myth.pod,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- perl_myth.pod	20 Mar 2002 17:42:05 -0000	1.5
  +++ perl_myth.pod	18 Apr 2002 18:13:05 -0000	1.6
  @@ -13,11 +13,11 @@
   
   =item *
   
  -M = Misconception or Myth
  +B<M> = Misconception or Myth
   
   =item *
   
  -R = Response
  +B<R> = Response
   
   =back
   
  @@ -109,11 +109,11 @@
   
   =item *
   
  -B<Vivek Khera's mod_perl performance tuning guide>( http://perl.apache.org/tuning/ )
  +L<Vivek Khera's mod_perl performance tuning guide|faqs::mod_perl_tuning>
   
   =item *
   
  -B<Stas Bekman's Performance Guide>( http://perl.apache.org/guide/performance.html )
  +L<Stas Bekman's Performance Guide|guide::performance>
   
   =back
   
  @@ -243,7 +243,7 @@
   
   =back
   
  -=head1 CREDITS
  +=head1 Credits
   
   Thanks to the mod_perl list for all of the good information and
   criticism.  I'd especially like to thank,
  @@ -303,7 +303,7 @@
   
   =item * 
   
  -Contact the L<modperl docs list|maillist::list-docs-dev>
  +Contact the L<mod_perl docs list|maillist::list-docs-dev>
   
   =back
   
  
  
  
  1.1                  modperl-docs/src/docs/1.0/faqs/httpd+perl.conf.txt
  
  Index: httpd+perl.conf.txt
  ===================================================================
  # This is the main server configuration file. See URL http://www.apache.org/
  # for instructions.
  
  # This configuration only handles the mod_perl requests in /programs and
  # /rprograms under directory /var/www.  Assumes it is redirected from
  # httpd running on port 80 via ProxyPass.
  
  ServerType standalone
  Port 8042
  
  HostnameLookups off
  User www
  Group www
  
  # The following directive disables keepalives and HTTP header flushes for
  # Netscape 2.x and browsers which spoof it. There are known problems with
  # these
  
  BrowserMatch Mozilla/2 nokeepalive
  
  # work around bugs in MSIE 4.0
  BrowserMatch "MSIE 4\.0b2;" nokeepalive force-response-1.0 downgrade-1.0
  
  # ServerAdmin: Your address, where problems with the server should be
  # e-mailed.
  
  ServerAdmin webmaster@www.domain.com
  
  # ServerRoot: The directory the server's config, error, and log files
  # are kept in
  
  ServerRoot /var/www
  
  # ErrorLog: The location of the error log file. If this does not start
  # with /, ServerRoot is prepended to it.
  
  ErrorLog /var/log/httpd/error_log_perl
  
  # TransferLog: The location of the transfer log file. If this does not
  # start with /, ServerRoot is prepended to it.
  
  TransferLog /var/log/httpd/access_log_perl
  
  # PidFile: The file the server should log its pid to
  PidFile /var/run/httpd+perl.pid
  
  ServerName www.domain.com
  
  # CacheNegotiatedDocs: By default, Apache sends Pragma: no-cache with each
  # document that was negotiated on the basis of content. This asks proxy
  # servers not to cache the document. Uncommenting the following line disables
  # this behavior, and proxies will be allowed to cache the documents.
  
  #CacheNegotiatedDocs
  
  # Timeout: The number of seconds before receives and sends time out
  
  Timeout 300
  
  # KeepAlive: Whether or not to allow persistent connections (more than
  # one request per connection). Set to "Off" to deactivate.
  
  KeepAlive Off
  
  # Server-pool size regulation.  Rather than making you guess how many
  # server processes you need, Apache dynamically adapts to the load it
  # sees --- that is, it tries to maintain enough server processes to
  # handle the current load, plus a few spare servers to handle transient
  # load spikes (e.g., multiple simultaneous requests from a single
  # Netscape browser).
  
  # It does this by periodically checking how many servers are waiting
  # for a request.  If there are fewer than MinSpareServers, it creates
  # a new spare.  If there are more than MaxSpareServers, some of the
  # spares die off.  These values are probably OK for most sites ---
  
  MinSpareServers 5
  MaxSpareServers 10
  
  # Number of servers to start --- should be a reasonable ballpark figure.
  
  StartServers 5
  
  # Limit on total number of servers running, i.e., limit on the number
  # of clients who can simultaneously connect --- if this limit is ever
  # reached, clients will be LOCKED OUT, so it should NOT BE SET TOO LOW.
  # It is intended mainly as a brake to keep a runaway server from taking
  # Unix with it as it spirals down...
  
  MaxClients 30
  
  # MaxRequestsPerChild: the number of requests each child process is
  #  allowed to process before the child dies.
  #  The child will exit so as to avoid problems after prolonged use when
  #  Apache (and maybe the libraries it uses) leak.  On most systems, this
  #  isn't really needed, but a few (such as Solaris) do have notable leaks
  #  in the libraries.
  
  MaxRequestsPerChild 50
  
  # combine access.conf right here
  AccessConfig /dev/null
  # access.conf: Global access configuration
  # Online docs at http://www.apache.org/
  
  # prevent Apache from searching for htaccess.conf files below document root
  <Directory />
    AllowOverride None
    order deny,allow
    deny from all
  </Directory>
  
  # put mod_perl programs here
  # startup.perl loads all functions that we want to use within mod_perl
  PerlScript /var/www/perllib/startup.perl
  <Directory /var/www/programs>
    AllowOverride None
    Options ExecCGI FollowSymLinks
    SetHandler perl-script
    PerlHandler Apache::Registry
    PerlSendHeader On
    order allow,deny
    allow from all
  </Directory>
  
  # like above but no HTTP headers
  <Directory /var/www/rprograms>
    AllowOverride None
    Options ExecCGI FollowSymLinks
    SetHandler perl-script
    PerlHandler Apache::Registry
    order allow,deny
    allow from all
  </Directory>
  
  # allow arbitrary *.perl files to be scattered throughout the site.
  <Files *.perl>
    SetHandler perl-script
    PerlHandler Apache::Registry
    PerlSendHeader On
    Options ExecCGI
  </Files>
  
  # like *.perl, but no PerlSendHeader
  <Files *.rperl>
    SetHandler perl-script
    PerlHandler Apache::Registry
    PerlSendHeader Off
    Options ExecCGI
  </Files>
  
  <Location /perl-status>
    SetHandler  perl-script
    PerlHandler Apache::Status
    order deny,allow
    deny from all
    allow from allow from 204.117.82.
  </Location>
  
  <Location /server-status>
   SetHandler server-status
    order deny,allow
    deny from all
    allow from allow from 204.117.82.
  </Location>
  
  <Location /server-info>
   SetHandler server-info
    order deny,allow
    deny from all
    allow from allow from 204.117.82.
  </Location>
  
  
  # combine srm.conf here
  ResourceConfig /dev/null
  
  DocumentRoot /var/www
  
  UserDir disable
  
  # DirectoryIndex: Name of the file or files to use as a pre-written HTML
  # directory index.  Separate multiple entries with spaces.
  
  DirectoryIndex index.html
  
  # FancyIndexing is whether you want fancy directory indexing or standard
  
  FancyIndexing on
  
  # AddIcon tells the server which icon to show for different files or filename
  # extensions
  
  AddIconByEncoding (CMP,/icons/compressed.gif) x-compress x-gzip
  
  AddIconByType (TXT,/icons/text.gif) text/*
  AddIconByType (IMG,/icons/image2.gif) image/*
  AddIconByType (SND,/icons/sound2.gif) audio/*
  AddIconByType (VID,/icons/movie.gif) video/*
  
  AddIcon /icons/binary.gif .bin .exe
  AddIcon /icons/binhex.gif .hqx
  AddIcon /icons/tar.gif .tar
  AddIcon /icons/world2.gif .wrl .wrl.gz .vrml .vrm .iv
  AddIcon /icons/compressed.gif .Z .z .tgz .gz .zip
  AddIcon /icons/a.gif .ps .ai .eps
  AddIcon /icons/layout.gif .html .shtml .htm .pdf
  AddIcon /icons/text.gif .txt
  AddIcon /icons/c.gif .c
  AddIcon /icons/p.gif .pl .py
  AddIcon /icons/f.gif .for
  AddIcon /icons/dvi.gif .dvi
  AddIcon /icons/uuencoded.gif .uu
  AddIcon /icons/script.gif .conf .sh .shar .csh .ksh .tcl
  AddIcon /icons/tex.gif .tex
  AddIcon /icons/bomb.gif core
  
  AddIcon /icons/back.gif ..
  AddIcon /icons/hand.right.gif README
  AddIcon /icons/folder.gif ^^DIRECTORY^^
  AddIcon /icons/blank.gif ^^BLANKICON^^
  
  # DefaultIcon is which icon to show for files which do not have an icon
  # explicitly set.
  
  DefaultIcon /icons/unknown.gif
  
  # AddDescription allows you to place a short description after a file in
  # server-generated indexes.
  # Format: AddDescription "description" filename
  
  ReadmeName README
  HeaderName HEADER
  IndexIgnore */.??* *~ *# */HEADER* */README* */RCS *.conf
  
  AccessFileName htaccess.conf
  
  DefaultType text/plain
  
  AddEncoding x-compress Z
  AddEncoding x-gzip gz
  
  Alias /icons/ /var/www/icons/
  
  # To use CGI scripts:
  AddHandler cgi-script .cgi
  
  # To use server-parsed HTML files
  AddType text/html .shtml
  AddHandler server-parsed .shtml
  
  # Uncomment the following line to enable Apache's send-asis HTTP file
  # feature
  #AddHandler send-as-is asis
  
  # If you wish to use server-parsed imagemap files, use
  AddHandler imap-file map
  
  # To enable type maps, you might want to use
  #AddHandler type-map var
  
  # Action lets you define media types that will execute a script whenever
  # a matching file is called. This eliminates the need for repeated URL
  # pathnames for oft-used CGI file processors.
  # Format: Action media/type /cgi-script/location
  # Format: Action handler-name /cgi-script/location
  
  
  # Customizable error response (Apache style)
  #  these come in three flavors
  #
  #    1) plain text
  #ErrorDocument 500 "The server made a boo boo.
  #  n.b.  the (") marks it as text, it does not get output
  #
  #    2) local redirects
  #ErrorDocument 404 /missing.html
  #  to redirect to local url /missing.html
  #ErrorDocument 404 /cgi-bin/missing_handler.pl
  #  n.b. can redirect to a script or a document using server-side-includes.
  #
  #    3) external redirects
  #ErrorDocument 402 http://some.other_server.com/subscription_info.html
  #
  
  
  
  1.1                  modperl-docs/src/docs/1.0/faqs/httpd.conf.txt
  
  Index: httpd.conf.txt
  ===================================================================
  # This is the main server configuration file. See URL http://www.apache.org/
  # for instructions.
  
  ServerType standalone
  Port 80
  
  HostnameLookups off
  User www
  Group www
  
  # The following directive disables keepalives and HTTP header flushes for
  # Netscape 2.x and browsers which spoof it. There are known problems with
  # these
  
  BrowserMatch Mozilla/2 nokeepalive
  
  # work around bugs in MSIE 4.0
  BrowserMatch "MSIE 4\.0b2;" nokeepalive force-response-1.0 downgrade-1.0
  
  # ServerAdmin: Your address, where problems with the server should be
  # e-mailed.
  
  ServerAdmin webmaster@www.domain.com
  
  # ServerRoot: The directory the server's config, error, and log files
  # are kept in
  
  ServerRoot /var/www
  
  # ErrorLog: The location of the error log file. If this does not start
  # with /, ServerRoot is prepended to it.
  
  ErrorLog /var/log/httpd/error_log
  
  # TransferLog: The location of the transfer log file. If this does not
  # start with /, ServerRoot is prepended to it.
  
  TransferLog /var/log/httpd/access_log
  
  # PidFile: The file the server should log its pid to
  PidFile /var/run/httpd.pid
  
  ServerName www.domain.com
  
  # CacheNegotiatedDocs: By default, Apache sends Pragma: no-cache with each
  # document that was negotiated on the basis of content. This asks proxy
  # servers not to cache the document. Uncommenting the following line disables
  # this behavior, and proxies will be allowed to cache the documents.
  
  #CacheNegotiatedDocs
  
  # Timeout: The number of seconds before receives and sends time out
  
  Timeout 300
  
  # KeepAlive: Whether or not to allow persistent connections (more than
  # one request per connection). Set to "Off" to deactivate.
  
  KeepAlive On
  
  # MaxKeepAliveRequests: The maximum number of requests to allow
  # during a persistent connection. Set to 0 to allow an unlimited amount.
  # We reccomend you leave this number high, for maximum performance.
  
  MaxKeepAliveRequests 100
  
  # KeepAliveTimeout: Number of seconds to wait for the next request
  
  KeepAliveTimeout 15
  
  # Server-pool size regulation.  Rather than making you guess how many
  # server processes you need, Apache dynamically adapts to the load it
  # sees --- that is, it tries to maintain enough server processes to
  # handle the current load, plus a few spare servers to handle transient
  # load spikes (e.g., multiple simultaneous requests from a single
  # Netscape browser).
  
  # It does this by periodically checking how many servers are waiting
  # for a request.  If there are fewer than MinSpareServers, it creates
  # a new spare.  If there are more than MaxSpareServers, some of the
  # spares die off.  These values are probably OK for most sites ---
  
  MinSpareServers 5
  MaxSpareServers 10
  
  # Number of servers to start --- should be a reasonable ballpark figure.
  
  StartServers 5
  
  # Limit on total number of servers running, i.e., limit on the number
  # of clients who can simultaneously connect --- if this limit is ever
  # reached, clients will be LOCKED OUT, so it should NOT BE SET TOO LOW.
  # It is intended mainly as a brake to keep a runaway server from taking
  # Unix with it as it spirals down...
  
  MaxClients 100
  
  # MaxRequestsPerChild: the number of requests each child process is
  #  allowed to process before the child dies.
  #  The child will exit so as to avoid problems after prolonged use when
  #  Apache (and maybe the libraries it uses) leak.  On most systems, this
  #  isn't really needed, but a few (such as Solaris) do have notable leaks
  #  in the libraries.
  
  MaxRequestsPerChild 400
  
  # combine access.conf right here
  AccessConfig /dev/null
  # access.conf: Global access configuration
  # Online docs at http://www.apache.org/
  
  # prevent Apache from searching for htaccess.conf files below document root
  <Directory />
    AllowOverride None
    order deny,allow
    deny from all
  </Directory>
  
  # main directory access
  <Directory /var/www/documents>
    Options Includes FollowSymLinks
    AllowOverride All
    order allow,deny
    allow from all
  </Directory>
  
  #<Directory /var/www/documents/cgi-bin>
  #  AllowOverride None
  #  Options +ExecCGI
  #  DefaultType application/x-httpd-cgi
  #</Directory>
  
  <Location /server-status>
   SetHandler server-status
    order deny,allow
    deny from all
    allow from allow from 204.117.82.
  </Location>
  
  <Location /server-info>
   SetHandler server-info
    order deny,allow
    deny from all
    allow from allow from 204.117.82.
  </Location>
  
  
  # if we get request for program, just pass to perl-enabled httpd
  ProxyPass /programs http://localhost:8042/programs
  ProxyPass /rprograms http://localhost:8042/rprograms
  
  # combine srm.conf here
  ResourceConfig /dev/null
  
  DocumentRoot /var/www/documents
  
  #UserDir www
  
  # DirectoryIndex: Name of the file or files to use as a pre-written HTML
  # directory index.  Separate multiple entries with spaces.
  
  DirectoryIndex index.html index.shtml
  
  # FancyIndexing is whether you want fancy directory indexing or standard
  
  FancyIndexing on
  
  # AddIcon tells the server which icon to show for different files or filename
  # extensions
  
  AddIconByEncoding (CMP,/icons/compressed.gif) x-compress x-gzip
  
  AddIconByType (TXT,/icons/text.gif) text/*
  AddIconByType (IMG,/icons/image2.gif) image/*
  AddIconByType (SND,/icons/sound2.gif) audio/*
  AddIconByType (VID,/icons/movie.gif) video/*
  
  AddIcon /icons/binary.gif .bin .exe
  AddIcon /icons/binhex.gif .hqx
  AddIcon /icons/tar.gif .tar
  AddIcon /icons/world2.gif .wrl .wrl.gz .vrml .vrm .iv
  AddIcon /icons/compressed.gif .Z .z .tgz .gz .zip
  AddIcon /icons/a.gif .ps .ai .eps
  AddIcon /icons/layout.gif .html .shtml .htm .pdf
  AddIcon /icons/text.gif .txt
  AddIcon /icons/c.gif .c
  AddIcon /icons/p.gif .pl .py
  AddIcon /icons/f.gif .for
  AddIcon /icons/dvi.gif .dvi
  AddIcon /icons/uuencoded.gif .uu
  AddIcon /icons/script.gif .conf .sh .shar .csh .ksh .tcl
  AddIcon /icons/tex.gif .tex
  AddIcon /icons/bomb.gif core
  
  AddIcon /icons/back.gif ..
  AddIcon /icons/hand.right.gif README
  AddIcon /icons/folder.gif ^^DIRECTORY^^
  AddIcon /icons/blank.gif ^^BLANKICON^^
  
  # DefaultIcon is which icon to show for files which do not have an icon
  # explicitly set.
  
  DefaultIcon /icons/unknown.gif
  
  # AddDescription allows you to place a short description after a file in
  # server-generated indexes.
  # Format: AddDescription "description" filename
  
  ReadmeName README
  HeaderName HEADER
  IndexIgnore */.??* *~ *# */HEADER* */README* */RCS *.conf
  
  AccessFileName htaccess.conf
  
  DefaultType text/plain
  
  AddEncoding x-compress Z
  AddEncoding x-gzip gz
  
  Alias /icons/ /var/www/icons/
  
  # To use CGI scripts:
  AddHandler cgi-script .cgi
  
  # To use server-parsed HTML files
  AddType text/html .shtml
  AddHandler server-parsed .shtml
  
  # Uncomment the following line to enable Apache's send-asis HTTP file
  # feature
  #AddHandler send-as-is asis
  
  # If you wish to use server-parsed imagemap files, use
  AddHandler imap-file map
  
  # To enable type maps, you might want to use
  #AddHandler type-map var
  
  # Action lets you define media types that will execute a script whenever
  # a matching file is called. This eliminates the need for repeated URL
  # pathnames for oft-used CGI file processors.
  # Format: Action media/type /cgi-script/location
  # Format: Action handler-name /cgi-script/location
  
  
  # Customizable error response (Apache style)
  #  these come in three flavors
  #
  #    1) plain text
  #ErrorDocument 500 "The server made a boo boo.
  #  n.b.  the (") marks it as text, it does not get output
  #
  #    2) local redirects
  #ErrorDocument 404 /missing.html
  #  to redirect to local url /missing.html
  #ErrorDocument 404 /cgi-bin/missing_handler.pl
  #  n.b. can redirect to a script or a document using server-side-includes.
  #
  #    3) external redirects
  #ErrorDocument 402 http://some.other_server.com/subscription_info.html
  #
  
  
  
  1.12      +1 -1      modperl-docs/src/docs/1.0/guide/Changes.pod
  
  Index: Changes.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/Changes.pod,v
  retrieving revision 1.11
  retrieving revision 1.12
  diff -u -r1.11 -r1.12
  --- Changes.pod	17 Apr 2002 04:34:45 -0000	1.11
  +++ Changes.pod	18 Apr 2002 18:13:05 -0000	1.12
  @@ -1,6 +1,6 @@
   =head1 NAME
   
  -CHANGES
  +Changes
   
   =head1 Description
   
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message