[Doc-SIG] Re: POD (resend)

[Ken Manheimer]

Whoops - somehow that last message got sent before i was done, as a result
of switching desktops.  I wanted to point out that while i'm not crazy
about the processed, plain-text pod output (*.pod), i really dislike the
stuff in the source.  Take a look in particular at the last paragraph in
my excerpt - such markup may be a necessary evil, but i'm really hoping we
don't have to put something of the sort in function docstrings.

Ken

8<---------------------------------------------------------------->8

=head1 NAME

Apache - Perl interface to the Apache server API

=head1 SYNOPSIS

   use Apache ();

=head1 DESCRIPTION

This module provides a Perl interface the Apache API.  It is here
mainly for B<mod_perl>, but may be used for other Apache modules that
wish to embed a Perl interpreter.  We suggest that you also consult
the description of the Apache C API at http://www.apache.org/docs/.

=head1 THE REQUEST OBJECT

The request object holds all the information that the server needs to
service a request.  Apache B<Perl*Handler>s will be given a reference to the
request object as parameter and may choose update or use it in various
ways.  Most of the methods described below obtain information from or
updates the request object.
The perl version of the request object will be blessed into the B<Apache> 
package, it is really a C<request_rec*> in disguise.

=over 4

=item Apache->request([$r])

The Apache->request method will return a reference to the request object.

B<Perl*Handler>s can obtain a reference to the request object when it
is passed to them via C<@_>.  However, scripts that run under 
B<Apache::Registry>, for example, need a way to access the request object.
B<Apache::Registry> will make a request object available to these scripts
by passing an object reference to C<Apache-E<gt>request($r)>.
If handlers use modules such as B<CGI::Apache> that need to access
C<Apache-E<gt>request>, they too should do this (e.g. B<Apache::Status>).