Update documentation and README

1 files changed, 84 insertions, 37 deletions

diff --git a/lib/Apache/Inject.pm b/lib/Apache/Inject.pm
index e82e174..15281fb 100644
--- a/lib/Apache/Inject.pm
+++ b/lib/Apache/Inject.pm
@@ -38,65 +38,111 @@ sub Inject {
 
 1;
 __END__
+=encoding latin1
+
 =head1 NAME
 
 Apache::Inject - Apache directive for injecting HTML headers and footers
 
 =head1 SYNOPSIS
 
-DocumentRoot /uar/local/www/apache24/data
-PerlModule Apache::Inject
-<Directory /usr/local/www/apache24/data>
-    Inject head.html foot.html
-</Directory>
+  DocumentRoot /uar/local/www/apache24/data
+  PerlModule Apache::Inject
+  <Directory /usr/local/www/apache24/data>
+      Inject head.html foot.html
+  </Directory>
 
 =head1 DESCRIPTION
 
-Apache::Inject is a mod_perl module that adds the Inject directive.
-It injects a header before the body and (optionally) a footer after the body
-of any requested HTML file.
+Apache::Inject is a mod_perl module that adds an Apache directive
+called Inject.
+
+The Inject directive takes one or two arguments, which correspond
+to the file names of two HTML files in the document root.  The
+contents of these files are then inserted into any requested HTML
+file.  The first file (the header) is inserted before the body of
+the requested HTML file, while the second file (the footer) is
+inserted after the body.
 
-The directive is smart enough to place the inserted contents
-in the proper places.
-The contents of the first file is inserted after any elements
-belonging to E<lt>headE<gt> and before any elements belonging to E<lt>bodyE<gt>,
-regardless of whether any explicit E<lt>headE<gt> or E<lt>bodyE<gt> tag is present
-in the source of the requested HTML page.
-Likewise, the contents of the second file is placed
-before any potential final E<lt>/htmlE<gt>.
+The directive is smart enough to place the header and footer in the
+proper places.  The contents of the header file is inserted after
+any elements belonging to E<lt>headE<gt> and before any elements
+belonging to E<lt>bodyE<gt> (regardless of whether any explicit
+E<lt>headE<gt> or E<lt>bodyE<gt> tag is present in the source of
+the requested HTML page).  Likewise, the contents of the second
+file is placed before any potential final E<lt>/htmlE<gt>.
 
-Note:
+Please note:
 
 =over
+
 =item *
-The Inject directive is valid only inside directory sections,
-such as E<lt>DirectoryE<gt>, E<lt>LocationE<gt> and E<lt>FilesMatchE<gt> blocks.
-It is valid in .htaccess files if AllowOverride Limit/AuthConfig/All is enabled.
+The Inject directive is valid only inside directory sections, such
+as E<lt>DirectoryE<gt>, E<lt>LocationE<gt> and E<lt>FilesMatchE<gt>
+blocks.  It is valid in .htaccess files if AllowOverride
+Limit/AuthConfig/All is enabled.
 
 =item *
 The file paths given to Inject are relative to the document root
 of the current server or virtual server.
+
+=item *
+Apache::Inject is designed for injecting headers and footers that
+belong in the E<lt>body<gt> element, such as headings, menu bars
+and copyright notices.  It is not built for inserting E<lt>headE<gt>
+elements.
+
 =back
 
+=head1 INSTALLATION
+
+To install this module type the following:
+
+  perl Makefile.PL
+  make
+  make test
+  make install
+
+=head1 OPERATION
+
+Behind the scenes, the Inject directive works as an alias for
+PerlResponseHandler and PerlSetVar.  For example, C<Inject head.html
+foot.html> results in the following configuration being added:
+
+  PerlResponseHandler Apache::Inject::Handler
+  PerlSetVar InjectHeader head.html
+  PerlSetVar InjectFooter foot.html
+
+This results in Apache::Inject::Handler being registered as a handler
+for requests to the current directory or location.
+
+Apache::Inject::Handler accepts all requests to files where the
+content type is C<text/html>.  It reads the contents of the requested
+file, as well as the contents of the C<InjectHeader> and C<InjectFooter>
+files, concatenates them intelligently and prints their combined
+contents.
+
 =head1 DIAGNOSTICS
 
-Apache::Inject::Handler, which is the actual handler of the requests,
-logs errors to the Apache log file.
-Below is a list of all issued errors and warnings.
-All of them result in Apache::Inject::Handler declining the request,
-letting Apache handle it as it would if the Inject directive were not used.
+Apache::Inject::Handler logs all errors and warnings to the Apache
+log file.  Below is a list of all issued errors and warnings.
+
+Note that whenever Apache::Inject::Handler issues an error or a
+warning, this means that it also declines the request, letting
+Apache handle it as it would if the Inject directive were not used.
 
 =over
 
-=item Error: InjectHead/InjectFoot should not begin with slash, as it is already always relative to document root
+=item Error: InjectHead/InjectFoot should not begin with slash, as
+it is already always relative to document root
 
 The paths given to Inject are always relative to the document root,
 even if the Inject directive is located within a directory section
 that applies to another path.
 
-Beginning any of the paths with a slash implies that there would be
-some difference in behavior compared to omitting the slash,
-which is false.
+Beginning any of the paths with a slash implies that there would
+be some difference in behavior compared to omitting the slash, which
+is false.
 
 =item Error: InjectHead/InjectFoot cannot extend past document root
 
@@ -105,7 +151,8 @@ go above the document root by using C<../>.
 
 =item Error: InjectHead/InjectFoot I<path/to/file> does not exist
 
-This error is issued if any of the paths given to Inject doesn't exist.
+This error is issued if any of the paths given to Inject doesn't
+exist.
 
 =item Warning: Declining request due to empty document root
 
@@ -116,21 +163,21 @@ cannot retrieve the current document root from Apache.
 
 =head1 CAVEATS
 
-On FreeBSD, you need to enable the accf_http kernel module
-in order for the tests to work.
-Note that Apache::Inject works fine without the module;
-it is only the tests that require it.
+On FreeBSD, you need to enable the accf_http kernel module in order
+for the tests to work.  Note that Apache::Inject works fine without
+the module; it is only the tests that require it.
 
 =head1 AUTHOR
 
-John Ankarström, E<lt>john [at] ankarstrom.se<gt>
+John Ankarström, E<lt>john [at] ankarstrom.seE<gt>
 
 =head1 COPYRIGHT AND LICENSE
 
 Copyright (C) 2021 by John Ankarström
 
 This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself, either Perl version 5.32.1 or,
-at your option, any later version of Perl 5 you may have available.
+it under the same terms as Perl itself, either Perl version 5.32.1
+or, at your option, any later version of Perl 5 you may have
+available.
 
 =cut