From 713e751bb92b6cf957de17ed6cd7ff3c0a3c9f2c Mon Sep 17 00:00:00 2001 From: root Date: Sat, 24 Apr 2021 14:49:48 +0000 Subject: Update documentation and README --- lib/Apache/Inject.pm | 121 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 84 insertions(+), 37 deletions(-) (limited to 'lib') 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 - - Inject head.html foot.html - + DocumentRoot /uar/local/www/apache24/data + PerlModule Apache::Inject + + Inject head.html foot.html + =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 EheadE and before any elements belonging to EbodyE, -regardless of whether any explicit EheadE or EbodyE 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/htmlE. +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 EheadE and before any elements +belonging to EbodyE (regardless of whether any explicit +EheadE or EbodyE 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/htmlE. -Note: +Please note: =over + =item * -The Inject directive is valid only inside directory sections, -such as EDirectoryE, ELocationE and EFilesMatchE 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 EDirectoryE, ELocationE and EFilesMatchE +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 Ebody element, such as headings, menu bars +and copyright notices. It is not built for inserting EheadE +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 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. It reads the contents of the requested +file, as well as the contents of the C and C +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 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, Ejohn [at] ankarstrom.se +John Ankarström, Ejohn [at] ankarstrom.seE =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 -- cgit v1.2.3