home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam    

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.


 


   Show Contents   Previous Page   Next Page

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.

   Show Contents   Previous Page   Next Page
Copyright © 1999 by O'Reilly & Associates, Inc.










??????????????@Mail.ru