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 +++++++++++++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 95 insertions(+), 25 deletions(-) (limited to 'README') 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. -- cgit v1.2.3