# -*- cperl -*-

=head1 Using POD as HTML with Apache

This HOW-TO describes how to make apache interpret Perl Old
Documentation (pod) files. Those files should be written on
.pod files.

=over 4

=item (1)

As root, edit the file /etc/httpd/conf/mime.types
For example, under the text/css entry, enter something
like:

 text/pod			pod

=item (2)

Edit, too, the /etc/httpd/conf/httpd.conf file. Somewhere, put:

 Action text/pod /cgi-bin/pod2html.pl

=item (3)

If you would like to have index.pod files as directory index, add
index.pod in the DirectoryIndex entry.

=item (4)

Now, create the /home/httpd/cgi-bin/pod2html.pl file:

 #!/usr/bin/perl

 use CGI qw/:standard/;
 $file = $ENV{PATH_TRANSLATED};
 print header;
 open READ, "pod2html $file |";
 while(<READ>) {
    print
 }

Inside the while loop, you can change any format you would like
(for example, include a CSS link...). Don't forget to make it
executable:

 chmod +x pod2html.pl

Note: if apache does not have pod2html in it's path (well, normally
apache have /bin and /usr/bin as default path) you must change the 
open line to:

 open READ, "/path/to/pod2html $file |";

If you does not want the index at the top of the document, use
pod2html --noindex.

=item 5

Because apache runs as nobody, you must create files under
/home/httpd/cgi-bin the following files

 pod2htmd.x~~
 pod2htmi.x~~

This, if you have perl 5.6.0. If you have a lower version, then
you must create the file

 pod2html-itemcache
 pod2html-dircache

Then, change owner to nobody.nobody... something like

 chown nobody.nobody <file>

=item 6

Now, restart the apache, and see if it is working.

=back

=head2 BUGS

Send bug reports to E<lt>albie@alfarrabio.di.uminho.ptE<gt>

=cut