Writing Apache Modules with Perl and C

8.4. 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 ...