Add documentation

1 files changed, 57 insertions, 0 deletions

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