Copyright (c) 1998, 1999 by Jonathan Swartz. All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

Welcome to Mason, a Perl-based web site development and delivery
system.  Mason allows web pages and sites to be constructed from
shared, reusable building blocks called components. Components contain
a mix of Perl and HTML, and can call each other and pass values back
and forth like subroutines. Components increase modularity and
eliminate repetitive work: common design elements (headers, footers,
menus, logos) can be extracted into their own components where they
need be changed only once to affect the whole site.

Other Mason features include a graphical site previewing utility, an
HTML/data caching model, and the ability to walk through requests with
the Perl debugger.

INSTALLATION

To install Mason, run the standard sequence:

	perl Makefile.PL
	make
	make install

After Mason is installed, you will need to activate it by adding some
directives to your Apache configuration files, and customizing Mason's
Config.pm and eg/handler.pl files to match your system.

The included pod docs have been pre-converted to HTML for you and
placed in the htdocs/ directory. The Mason overview (a good place to
start) is in Mason.html.

WARNINGS!

* Don't use Mason with an older mod_perl DSO (dynamic shared object).

Using Mason with an older mod_perl DSO will cause your Apache server
to fail silently at startup. Red Hat 6.1 is one distribution that
includes such a broken mod_perl DSO.

The fix for this problem is to install Apache/mod_perl with mod_perl
compiled statically into the Apache binary.  Packages of Apache with a
static mod_perl are available around the net; check
http://rpmfind.net/ as a starting point.

Recent testing with Apache 1.3.12/mod_perl 1.24 compiled from source
on Linux 2.2.13 did not exhibit these problems.  Your mileage may
vary.

* Don't use Mason with taint checking on.

The current version of Mason interacts badly with a nasty taint bug in
Perl, causing unexpected behavior such as infinite loops.

GETTING HELP

The official Mason web site is at http://www.masonhq.com/.  There
you'll find Mason documentation, news, etc.

A recent copy of the FAQ (Frequently Asked Questions) list is
included in this release under the faq/ directory.  The most
recent version is always available on the web site.

The Mason mailing list, maintained by Kirrily Roberts, is an excellent
place to ask questions and learn techniques. To subscribe or browse the
archives, visit http://netizen.com.au/mailman/listinfo/mason.

If the question is more generally about mod_perl, you may wish to post
additionally (or only) to the mod_perl mailing list at
modperl@apache.org.

If you have a question or comment that you don't feel is appropriate
for the group, write to the author at swartz@transbay.net.

CODE EXAMPLES

The samples/ directory contains a few basic components as well as
a miniature commerce site built with components.

The Mason component archive (http://www.masonhq.com/arch/), launched
in November 1999, should be another good source of examples.

REPORTING BUGS

Send bug reports to the Mason mailing list for quickest response.
It is a good idea to search the mailing list archives first to see
if the problem has already been reported.

For all bug reports indicate your architecture, Apache/Perl/module
versions, etc. For installation problems send your handler.pl and
httpd.conf. For component problems try to isolate the bug in a single
small component or set of components, and send those.

CONTENT MANAGEMENT

There is a companion content management system for Mason, maintained
by Mark Schmick.  CM is a web-based interface to your component and
content files; it allows designers and programmers to work on a site
remotely without resorting to ftp or telnet. It supports
staging/production sites, RCS versioning of files, global content
searching, and a host of other features. CM is written entirely as a
set of Mason components.  Find out more and download a copy at
http://www.masonhq.com/Mason-CM/.

LICENSE

Mason was originally developed for the Internet technology group at
CMP Media, a publisher of technology magazines. CMP
graciously supported our efforts to release Mason as open source
software to the Perl community.  However, CMP has NO direct
involvement with the open source release and bears NO responsibility
for its support or maintenance.

Mason is provided "as is" and without any express or implied
warranties, including, without limitation, the implied warranties of
merchantibility and fitness for a particular purpose.  Mason is
released under the same terms as Perl itself.  For more information
see the "README" or "Artistic" files provided with the Perl
distribution.

AUTHOR

Jonathan Swartz
swartz@transbay.net
