O'Reilly logo

Writing Apache Modules with Perl and C by Lincoln Stein, Doug MacEachern

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

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

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required