=head1 NAME

Text::MicroMason::ReadMe - About the MicroMason distribution

=head1 MOTIVATION

The HTML::Mason module provides a useful syntax for dynamic template
interpretation (sometimes called embedded scripting):  plain text
(or HTML) containing occasional chunks of Perl code whose results
are interpolated into the text when the template is "executed."

However, HTML::Mason also provides a full-featured web application
framework with mod_perl integration, a caching engine, and numerous
other functions, and there are times in which I'd like to use the
templating capability without configuring a full Mason installation.

Thus, the Text::MicroMason module was born: it supports the core
aspects of the HTML::Mason syntax ("<%...%>" expressions, "%...\n"
and "<%perl>...</%perl>" blocks, "<& file &>" includes, "%ARGS"
and "$_out->()" ), and omits the features that are web specific
(like autohandlers) or are less widely used (like "<%method>"
blocks).

=head2 Related Modules

You may well be thinking "yet another dynamic templating module?
Sheesh!" And you'd have a good point. There certainly are a variety
of templating toolkits on CPAN already; even restricting ourselves
to those which use Perl syntax for both interpolated expressions
and flow control (as opposed to "little languages") there's a fairly
crowded field, including L<Template::Toolkit|Template::Toolkit>,
L<Template::Perl|Template::Perl>, L<Text::Template|Text::Template>,
and L<Text::ScriptTemplate|Text::ScriptTemplate>, as well as those
that are part of full-blown web application frameworks like
L<Apache::ASP|Apache::ASP>, ePerl, L<HTML::Embperl|HTML::Embperl>,
and L<HTML::Mason|HTML::Mason>.

Nonetheless, I think this module occupies a useful niche: it provides
a reasonable subset of HTML::Mason syntax in a very light-weight
fashion. In comparison to the other modules listed, MicroMason aims
to be fairly lightweight, using one eval per parse, converting the
template to an cacheable unblessed subroutine ref, eschewing method
calls, and containing just a few hundred lines of Perl code in the 
core, with optional features activated only if requested.

=head2 Compatibility with HTML::Mason

See L<HTML::Mason> for a much more full-featured version of the
capabilities provided by this module.

If you've already got HTML::Mason installed, configured, and loaded
into your process, you're probably better off using it rather than
this package. HTML::Mason's C<$interp-E<gt>make_component()> method
allows you to parse a text string without saving it to disk first.


The following sets of HTML::Mason features B<are> supported by Text::MicroMason:

=over 4

=item *

Template interpolation with <% expr %> 

=item *

Literal Perl lines with leading % 

=item *

Named %args, %perl, %once, %init, %cleanup, and %doc blocks

=item *

The $m mason object, although with many fewer methods

=item *

Expression filtering with |h and |u (via -Filter mixin)

=back


The following sets of HTML::Mason features are B<not> supported by Text::MicroMason:

=over 4

=item *

No %attr, %shared, %method, or %def blocks.

=item *

No $r request object

=item *

No shared files like autohandler and dhandler.

=item *

No mod_perl integration or configuration capability.

=back



=head1 DISTRIBUTION

This is version 1.92_0 of Text::MicroMason. 

This is an EXPERIMENTAL release on a development track for a 2.0 release.

This module has been available on CPAN for over two years, with a
relatively stable interface and feature set. If you encounter
any problems, please inform the author and I'll endeavor to patch
them promptly. 

This module's CPAN registration should read:

  Name            DSLIP  Description
  --------------  -----  ---------------------------------------------
  Text::
  ::MicroMason    Rdpfp  Simplified HTML::Mason Templating

This module should be categorized under group 11, Text Processing.


=head1 INSTALLATION

This module should work with any version of Perl 5, without platform
dependencies or additional modules beyond the core distribution.

You should be able to install this module using the CPAN shell interface:

  perl -MCPAN -e 'install Text::MicroMason'

Alternately, you may retrieve this package from CPAN (C<http://search.cpan.org/~evo/>) or from the author's site (C<http://www.evoscript.org/Text-MicroMason>).

After downloading the distribution, follow the normal procedure to unpack and install it, using the commands shown below or their local equivalents on your system:

  tar xzf Text-MicroMason-*.tar.gz
  cd Text-MicroMason-*
  perl Makefile.PL
  make test && sudo make install

=head2 Tested Platforms

This release has been tested succesfully on the following platforms:

  5.6.1 on darwin

Earlier releases have also tested OK on a wide variety of platforms.
You may review the current test results from CPAN-Testers:

=over 2

=item *

http://testers.cpan.org/show/Text-MicroMason.html

=back


=head1 SUPPORT

If you have questions or feedback about this module, please feel
free to contact the author at the below address. Although there is
no formal support program, I do attempt to answer email promptly. 

I would be particularly interested in any suggestions towards
improving the documentation, correcting any Perl-version or platform
dependencies, as well as general feedback and suggested additions.

Bug reports that contain a failing test case are greatly appreciated,
and suggested patches will be promptly considered for inclusion in
future releases.

To report bugs via the CPAN web tracking system, go to 
C<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Text-MicroMason> or send mail 
to C<Dist=Text-MicroMason#rt.cpan.org>, replacing C<#> with C<@>.

If you've found this module useful or have feedback about your
experience with it, consider sharing your opinion with other Perl users
by posting your comment to CPAN's ratings system
(C<http://cpanratings.perl.org/rate/?distribution=Text-MicroMason>).

For more general discussion, you may wish to post a message on PerlMonks
(C<http://perlmonks.org/?node=Seekers%20of%20Perl%20Wisdom>) or on the
comp.lang.perl.misc newsgroup
(C<http://groups.google.com/groups?group=comp.lang.perl.misc>).


=head1 AUTHOR

Developed by Matthew Simon Cavalletto at Evolution Softworks.  You may
contact the author directly at C<evo#cpan.org> or
C<simonm#cavalletto.org>, replacing C<#> with C<@>.

Custom development and technical consulting are available at
C<www.evolutionsoftworks.com>. More free Perl software is available at
C<www.evoscript.org>.


=head1 THANKS

Based on the superb HTML::Mason, originally developed by Jonathan Swartz. 

My sincere thanks to the following users for their feedback:

  Pascal Barbedor
  Mark Hampton
  Philip King
  Daniel J. Wright
  William Kern
  Tommi Maekitalo
  Alan Ferrency

=head1 LICENSE

Copyright 2002, 2003, 2004 Matthew Simon Cavalletto. 

Portions copyright 2001 Evolution Online Systems, Inc.

You may use, modify, and distribute this software under the same terms as Perl.

=cut
