HTML::Embperl - Embbed perl code in HMTL documents

Copyright (c) 1997-1998 Gerald Richter / ECOS

You may distribute under the terms of either the GNU General Public 
License or the Artistic License, as specified in the Perl README file.
For use with Apache httpd and mod_perl, see also Apache copyright.

THIS PACKAGE 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.


OVERVIEW

Look at "perldoc Embperl" for documentation.
or at http://perl.apache.org/embperl.html for a short description
"perldoc Faq", will display (short) FAQs.

Embperl allows you to embed perl code in your HTML documents. The code can 
be used to compute something (e.g. retrieve data from a database) or to 
produce output (e.g. display a variable). Also some metacommands are 
available which give you the ability to create "loops" or to conditional 
process your HTML document. As fours feature some HTML tags are specially
interpreted. This allows dynamic table creation and an easier form processing.

Embperl can run offline, as CGI script or as module using mod_perl of the 
Apache httpd (which is the fastest approach).

There is also a database module (DBIx::Recordset) available for (not only)
use with Embperl (see below).

INSTALLATION

- Unpack the archive
- perl Makefile.PL
You will be ask if want to compile in support for Apache mod_perl. If 
you say yes, the source of Apache is searched (for headerfiles). If 
it can't found, please specify the basepath. Please make sure 
mod_perl is already installed. If you have installed mod_perl-0.96 or
higher Makefile.PL automaticly suggest the same source path as used to
build mod_perl.

- make
- make test
- make install

See perldoc Embperl how it goes on.
See the eg/ directory for examples.

I have successfully tested this on Linux 2.0.27, mod_perl 0.96 and higher,
with perl 5.004 and Apache 1.2.x and 1.3b3,5,6. It also works with Apache-SSL
and Stronghold. Since there is (as far as I can see)
no system dependent stuff, it should work on other systems as well.
As far as possible use perl 5.004_04, because 5.004 has memory leaks.
Also I suggest to use mod_perl-1.07_02 or higher because of a memory leak
in Apache->push_handler in mod_perl versions before 1.07_02

WIN 32

I have tested the offline mode on Windows 95 with Microsoft Visual C++ 4.2
compiler and I have succesfully run Embperl with apache_1.3b5 / mod_perl-1.08
/ perl5.004_04 on Windows NT with VC++ 5.0. 
NOTE: It was necessary for me to compile perl5.004_04 with the VC++ on my own
to get it run with apache and mod_perl, while I was able to use the binary
distribution (/authors/id/GSAR/perl5.00402-bindist04-bc.tar.gz) of perl for
offline testing under Win 95.

NOTE: If you use mod_perl <= 1.11 you should aply the win32.patch, otherwise you will
get a deadlock 


On Windows 95/NT you have todo the following:

perl Makefile.PL
nmake (you must have the c compiler in your path)

you will get an error about compiling Embperl.c. Edit Embperl.c and change

-#line  "Embperl.xs"

to

+#line  1 "Embperl.xs"

now rerun nmake and it should compile.

"nmake test"
"nmake install"


NOTE!

In version 0.16 and above you need to set the 'Options ExecCGI' in your
srm.conf for running under mod_perl!


COMPATIBILITY

I have tested Embperl succesfully

on Linux 2.x with

perl5.004_04
apache_1.2.5
apache_1.2.6
apache_1.3b3
apache_1.3b5
apache_1.3b6
apache_1.3.0
apache_ssl (Ben SSL)
Stronghold 2.2

on Windows NT 4.0 with

perl5.004_04
apache_1.3b5
apache_1.3.0

on Windows 95 with
perl5.004_02 (binary distribution)
Offline mode

I know from other people that it works on many other UNIX systems


FEEDBACK and BUG REPORTS

Please let me know if you use or test this module.  Bugs, questions,
suggestions for things you would find useful, etc., are discussed on
the mod_perl mailling list.

>From the mod_perl README:
 
The Apache/Perl mailing list (modperl@apache.org) is available for mod_perl
users and developers to share ideas, solve problems and discuss things related
to mod_perl and the Apache::* (and Embperl) modules. To subscribe to this list, send mail to
majordomo@apache.org with the string "subscribe modperl" in the body. 


There is a hypermail archive for this list available from:
http://outside.organic.com/mail-archives/modperl/

There is an Epigone archive for the mod_perl mailing list at
http://forum.swarthmore.edu/epigone/modperl


SUPPORT

You can get free support on the mod_perl mailing list (see above).  If
you need commercial support (with a guarantee for response time or a
solution) for Embperl or want a web site where you can run your
Embperl/mod_perl scripts without setting up your own web server,
please send email to info@ecos.de.


REFERENCES

 mod_perl               http://perl.apache.org/
 mod_perl FAQ           http://perl.apache.org/faq
 Embperl                http://perl.apache.org/embperl.html
 DBIx::Recordset	http://ftp.dev.ecos.de/pub/perl/dbi
 apache web server      http://www.apache.org/
 ben-ssl (free httpsd)  http://www.apache-ssl.org/
 stronghold (commerical httpsd) http://www.c2.net/
    europe              http://www.eu.c2.net/
 see also               http://www.perl.com/CPAN/modules/by-module/Apache/apache-modlist.html


AUTHOR

G. Richter (richter@dev.ecos.de)

