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 advocacy.pod browserbugs.pod config.pod control.pod correct_headers.pod databases.pod dbm.pod debug.pod help.pod install.pod intro.pod modules.pod multiuser.pod performance.pod perl.pod scenario.pod security.pod snippets.pod start.pod strategy.pod troubleshooting.pod
Date Wed, 03 Apr 2002 09:16:09 GMT
stas        02/04/03 01:16:09

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

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


Mime
View raw message