                                  [ePerl]

                                About ePerl

          What is ePerl?
          --------------------------------------------------------

          ePerl (,,Embedded Perl 5 for HTML'') can be simply
          explained by the following evolution:

            1. HTML, the Hypertext Markup Language,
               is the way to write documents for pure static
               display.
            2. Perl 5, the popular scripting language,
               is the way to program CGI-scripts for pure dynamic
               display.
            3. ePerl, the embedded Perl language for HTML,
               is the way to program documents for static _AND_
               dynamic display.

          Or in a short phrase: ePerl combines HTML markup with
          Perl 5 programming by exploiting software leverage !!

          How about its Look & Feel?
          --------------------------------------------------------

          Just have a look at a really simple example:

               <html>
               <body>
               Welcome user from <? print $ENV{'REMOTE_HOST'}; !>, nice to meet you!
               </body>
               </html>

          This will give an output like:

               Welcome user from en2.engelschall.de, nice to meet you!

          How does it work?
          --------------------------------------------------------

          It is simply a tricky glue code which only combines the
          programming power of Perl 5 with the markup power of
          HTML.

          A pure standard HTML document will be bristled with
          native Perl 5 code to create a so-called HTML document
          with embedded Perl 5 code. This document is then
          on-the-fly piped through the NPH-CGI program nph-eperl
          when the webserver receives a request for this document
          from the client. At this preprocessing pass ePerl
          expands the mixed language (HTML and Perl) to pure HTML
          by evaluating all Perl statements and passing through
          (without changing) all HTML statements. The result is
          send back to the webbrowser.

          The trick is: ePerl itself only converts the ePerl
          source file into a valid Perl program file which then
          gets entirely evaluated by only one internal instance of
          the Perl 5 interpreter. To archieve this, ePerl
          translates all HTML markup code into (escaped) Perl 5
          print constructs while passing through all embedded
          native Perl 5 code. This approach has the advantage
          that...

             * we only need one Perl 5 interpreter run for
               evaluating a complex ePerl source file, even if
               there are more then one embedded Perl 5 blocks
               exist between the HTML markup code.
             * all embedded Perl blocks share the same interpreter
               runtime, so they can interchange functions and
               variables, e.g. you can define a function at the
               top of your ePerl source file and use it at
               different places in the HTML markup below.
             * there is really performance restrictions on how
               much Perl 5 blocks you use.

          You see: the idea of ePerl is as simple as elegant!

          In other words: ePerl is a special Perl 5 on-the-fly
          interpreter for bristled Perl/HTML source files,
          designed as a NPH-CGI/1.0 conforming program which can
          used in conjunction with any webserver.

          How would I use it?
          --------------------------------------------------------

            1. Compile the nph-eperl binary by the use of an
               already installed Perl 5 system. Perl 5.002 or
               higher is required.

            2. Install the nph-eperl binary to your webservers CGI
               directory, say e.g.
               /path/to/apache/cgi-bin/nph-eperl.

                    NOTICE: You don't need a Perl 5 binary in
                    your path or even on your system under
                    runtime of ePerl, because the nph-eperl
                    executable still is a complete Perl 5
                    interpreter, because ePerl gets
                    statically linked with the Perl 5
                    interpreter library!

            3. Add knowledge about ePerl source files, i.e. files
               with extension .phtml (for ,,Perl HTML''), to your
               HTTP server. For the Apache server you would add
               lines similar to the following to your server
               configuration file:

                    AddType      application/x-httpd-eperl   .phtml .eperl .epl
                    Action       application/x-httpd-eperl   /internal/cgi/nph-eperl
                    ScriptAlias  /internal/cgi               /path/to/apache/cgi-bin

               The first line gives all files with extension
               .phtml (or optionally .eperl and .epl) the
               MIME-type application/x-httpd-eperl, the second
               line then forces all files with this MIME-type to
               be executed by via the ePerl NPH-CGI program and
               the. third line finally maps the URL of the NPH-CGI
               program (and others in this directory) to the real
               Unix path.

            4. Create an ePerl source file and name it
               anyname.phtml and request it through your Web
               browser. It should automatically get evaluated by
               the ePerl interpreter.

                                About ePerl

         Copyright  1996 Ralf S. Engelschall <rse@engelschall.com>
