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 --- README | 120 +++++++++++++++++++++++++++++++++++++++----------- lib/Apache/Inject.pm | 121 +++++++++++++++++++++++++++++++++++---------------- 2 files changed, 179 insertions(+), 62 deletions(-) diff --git a/README b/README index c93070e..636bd09 100644 --- a/README +++ b/README @@ -1,40 +1,110 @@ -Apache-Inject version 0.01 -========================== +NAME + Apache::Inject - Apache directive for injecting HTML headers and footers -The README is used to introduce the module and provide instructions on -how to install the module, any machine dependencies it may have (for -example C compilers and installed libraries) and any other information -that should be provided before the module is installed. +SYNOPSIS + DocumentRoot /uar/local/www/apache24/data + PerlModule Apache::Inject + + Inject head.html foot.html + -A README file is required for CPAN modules since CPAN extracts the -README file from a module distribution so that people browsing the -archive can use it get an idea of the modules uses. It is usually a -good idea to provide version information here so that people can -decide whether fixes for the module are worth downloading. +DESCRIPTION + 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 header and footer in the + proper places. The contents of the header file is inserted after any + elements belonging to and before any elements belonging to + (regardless of whether any explicit or tag is present in + the source of the requested HTML page). Likewise, the contents of the + second file is placed before any potential final . + + Please note: + + * The Inject directive is valid only inside directory sections, such + as , and blocks. It is valid in + .htaccess files if AllowOverride Limit/AuthConfig/All is enabled. + + * The file paths given to Inject are relative to the document root of + the current server or virtual server. + + * Apache::Inject is designed for injecting headers and footers that + belong in the element, such as headings, menu bars and + copyright notices. It is not built for inserting elements. INSTALLATION + To install this module type the following: + + perl Makefile.PL + make + make test + make install + +OPERATION + Behind the scenes, the Inject directive works as an alias for + PerlResponseHandler and PerlSetVar. For example, "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 "text/html". It reads the contents of the requested file, as + well as the contents of the "InjectHeader" and "InjectFooter" files, + concatenates them intelligently and prints their combined contents. + +DIAGNOSTICS + Apache::Inject::Handler logs all errors and warnings to the Apache log + file. Below is a list of all issued errors and warnings. -To install this module type the following: + 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. - perl Makefile.PL - make - make test - make install + 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. -DEPENDENCIES + 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. -This module requires these other modules and libraries: + 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 "../". - blah blah blah + Error: InjectHead/InjectFoot *path/to/file* does not exist + This error is issued if any of the paths given to Inject doesn't + exist. -COPYRIGHT AND LICENCE + 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. -Put the correct copyright and licence information here. +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. -Copyright (C) 2021 by Charlie & +AUTHOR + 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. +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. 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