From accfbd3ab782b82435cf1cae9c44b87a67e069d2 Mon Sep 17 00:00:00 2001
From: root <root@rbsd.ankarstrom.se>
Date: Fri, 23 Apr 2021 21:22:19 +0000
Subject: Add documentation

---
 lib/Apache/Inject.pm         | 57 ++++++++++++++++++++++++++++++++++++++++++++
 lib/Apache/Inject/Handler.pm |  1 -
 2 files changed, 57 insertions(+), 1 deletion(-)

(limited to 'lib/Apache')

diff --git a/lib/Apache/Inject.pm b/lib/Apache/Inject.pm
index 7a504b6..73b88a4 100644
--- a/lib/Apache/Inject.pm
+++ b/lib/Apache/Inject.pm
@@ -54,5 +54,62 @@ 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.
 
+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>.
+
+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.
+
+=item *
+The file paths given to Inject are relative to the document root
+of the current server or virtual server.
+=back
+
+=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.
+
+=over
+=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.
+
+=item Error: InjectHead/InjectFoot cannot extend past document root
+
+This error is issued if any of the paths given to Inject tries to
+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.
+
+=item Warning: Declining request due to empty document root
+
+This warning is issued if Apache::Inject::Handler for some reason
+cannot retrieve the current document root from Apache.
+
+=back
+
 =cut
 
diff --git a/lib/Apache/Inject/Handler.pm b/lib/Apache/Inject/Handler.pm
index 708b68b..7c32a61 100644
--- a/lib/Apache/Inject/Handler.pm
+++ b/lib/Apache/Inject/Handler.pm
@@ -1,7 +1,6 @@
 package Apache::Inject::Handler;
 
 use strict;
-use warnings FATAL => 'all';
 
 use Apache2::RequestRec ();
 use Apache2::RequestUtil ();
-- 
cgit v1.2.3