HTML::Mason Debian package
==========================

All Mason documentation is available [1]on the Mason website. An
introduction to Mason can be found in [2]Mason.html, and the
Administrator's Manual in [3]Admin.html.

   1. http://www.masonhq.com/docs/manual/
   2. http://www.masonhq.com/docs/manual/Mason.html
   3. http://www.masonhq.com/docs/manual/Admin.html

Some basic Mason examples can be found in the libhtml-mason-perl-doc
package.

Using HTML::Mason with mod_perl
-------------------------------

The standard way to run Mason is with mod_perl. The references above
provide detailed information about this configuration. The following
information is extracted directly from the Administrator's Manual.
Please refer to the manual for a more detailed explanation.

The absolutely most minimal configuration looks like this:

    PerlModule HTML::Mason::ApacheHandler
    <Location />
        SetHandler perl-script
        PerlHandler HTML::Mason::ApacheHandler
    </Location>

In practice, this is a bad idea, as you don't want Mason to try to
process images or other binary files, nor do you want private
(non-top-level) Mason components to be served to users. The
recommended naming scheme is to use "normal" extensions for top-level
components, adding an "m" prefix for private components.

Here is a configuration that enforces this naming scheme:

    <Perl>
        use HTML::Mason::ApacheHandler;
        use Apache2::Const -compile => qw(HTTP_NOT_FOUND);
    </Perl>

    <LocationMatch "(\.html|\.txt|\.pl)$">
        SetHandler perl-script
        PerlHandler HTML::Mason::ApacheHandler
    </LocationMatch>

    <LocationMatch "(\.m(html|txt|pl)|dhandler|autohandler)$">
        SetHandler perl-script
        PerlInitHandler Apache2::Const::HTTP_NOT_FOUND
    </LocationMatch>

Using HTML::Mason with SpeedyCGI
--------------------------------

While mod_perl is definitely the standard way to run Mason, it is also
possible to run it in a CGI environment. This would be preferable, for
example, in some shared hosting environments (as mod_perl runs everything
under the same process), or when using a web server other than Apache.

Standard CGI is prohibitavely expensive, but this can be mostly
overcome by a persistent CGI framework, such as SpeedyCGI or FastCGI.
SpeedyCGI is the simpler of the two, and is recommended unless you
have other reasons to pursue FastCGI.

First, you need to install speedy-cgi-perl. (Note that it is also
possible to use libapache-mod-speedycgi, although this won't be
covered here.)

In httpd.conf, enable mod_actions and configure like this:

    Action html-mason /cgi-bin/speedycgi-handler.cgi
    AddHandler html-mason .html

Or equivilantly:

    Action html-mason /cgi-bin/speedycgi-handler.cgi
    <LocationMatch "\.html$">
        SetHandler html-mason
    </Location>

Create /usr/lib/cgi-bin/speedycgi-handler.cgi like so:

====
#!/usr/bin/speedy
# -*- perl -*-

use HTML::Mason::CGIHandler;

BEGIN { warn "Loading speedycgi-handler.cgi"; };
warn "Executing speedycgi-handler.cgi";

my $h = HTML::Mason::CGIHandler->new(data_dir => "/var/cache/mason");

$h->handle_request;
====

Obviously, you can take out the "warn" lines in real use, but for
testing this will demonstrate that mason-handler.cgi itself is only
loaded once.

Remember that stopping Apache does not kill off the speedy_backend
processes!

It is also possible to run Mason via CGI entirely from .htaccess files
in your public_html directory. The instructions to do so were
contributed by a previous maintainer, Steve Haslam, in March 2004.
They may be out of date, but are provided here as a starting point for
those who are interested.

# /home/shaslam/public_html/mason_test/.htaccess:
RewriteEngine On
RewriteBase /~shaslam/mason_test/
RewriteRule ^mason_example_cgi/$ /~shaslam/mason_test/speedycgi_handler.cgi/mason_example/index.html
RewriteRule ^mason_example_cgi/(.+)/$ /~shaslam/mason_test/speedycgi_handler.cgi/mason_example/$1/index.html
RewriteRule ^mason_example_cgi/(.+) /~shaslam/mason_test/speedycgi_handler.cgi/mason_example/$1
Options +ExecCGI
AddHandler cgi-script .cgi

And speedycgi_handler.cgi must specify 'comp_root =>
"/home/shaslam/public_html/mason_test"' when constructing the
CGIHandler object.

The fiddling to rewrite requests to /index.html is not necessary if
your URIs really do map to the mason components, because then mod_dir
will do it. OTOH, you need to avoid rewriting requests ending in / in
that case. Something like:

RewriteRule ^mason_example_cgi/(.*[^/]) /~shaslam/mason_test/speedycgi_handler.cgi/mason_example/$1

And then, assuming "mason_example_cgi" is a directory with the
components under it, requests ending in "/" will *not* be rewritten,
so mod_dir will pick them up and look for "index.html" (DirectoryIndex
setting) locations as usual.

In general, this fiddling is not fun for novices.

 -- Charles Fry <debian@frogcircus.org>, Fri, 17 Jun 2005 01:21:57 -0400
