Writing Apache Modules with Perl and C By:   Lincoln Stein and Doug MacEachern Published:   O'Reilly & Associates, Inc.  - March 1999 Copyright © 1999 by O'Reilly & Associates, Inc.

Chapter 8 - Customizing the Apache Configuration Process
Documenting Configuration Files

When mod_perl is configured with the server, configuration files can be documented with POD (Perl's "plain old documentation" system). There are only a handful of POD directives that mod_perl recognizes but enough to mix POD with an actual server configuration. The recognized directives are as follows:

=pod

When a =pod token is found in the configuration file, mod_perl will soak up the file line- by-line, until a =cut token or a special =over token is reached.

=cut

When a =cut token is found, mod_perl will turn the configuration processing back over to Apache.

=over

The =over directive can be used in conjunction with the =back directive to hand sections back to Apache for processing. This allows the pod2* converters to include the actual configuration sections in its output. In order to allow for =over to be used elsewhere, mod_perl will hand these sections back to Apache only if the line contains the string apache.

=over to apache

=back

When mod_perl is inside a special =over section as described above, it will go back to POD-soaking mode once it sees a =back directive.

=back to pod

__END__

Although __END__ is not a POD directive, mod_perl recognizes this token when present in a server configuration file. It will simply read in the rest of the configuration file, ignoring each line until there is nothing left to read.

Here is a complete example:

=pod

=head1 NAME

httpd.conf - The main server configuration file

=head2 Standard Module Configuration

=over 4

=item mod_status

=over to apache

 #Apache will process directives in this section
<Location /server-status>
   SetHandler server-status
   ...
</Location>

=back to pod

=item ...

...

=back

=cut

__END__
The server will not try to process anything here

We've now covered the entire Apache module API, at least as far as Perl is concerned. The next chapter presents a complete reference guide to the Perl API, organized by topic. This is followed in Chapters 10 and 11, C API Reference Guide, by a reference guide to the C-language API, which fills in the details that C programmers need to know about.