Commits

Anonymous committed 44e809f

More install progress

Comments (0)

Files changed (4)

src/wml_backend/p3_eperl/CMakeLists.txt

     PROPERTIES OUTPUT_NAME "wml_p3_${EXE}"
 )
 
+ADD_CUSTOM_COMMAND(
+    OUTPUT "eperl.pod"
+    COMMAND "${PERL_EXECUTABLE}"
+    ARGS "eperl-pod-preproc.pl"
+        "--input" "eperl.proto.pod"
+        "--output" "eperl.pod"
+        "--versionfrom" "eperl_version.c"
+    DEPENDS "eperl-pod-preproc.pl" "eperl.proto.pod" "eperl_version.c"
+)
+
+ADD_CUSTOM_TARGET(
+    "eperl_pod_preproc" ALL
+    DEPENDS "eperl.pod"
+)
+
+INST_RENAME_POD2MAN( "eperl_pod" "eperl.pod" "eperl" "1" "wml_p3_eperl")
+
 INSTALL(TARGETS ${EXE} DESTINATION "${WML_LIBEXE_DIR}")
 
 CONFIGURE_FILE(${CMAKE_CURRENT_SOURCE_DIR}/config_ac.h.cmake ${CMAKE_CURRENT_SOURCE_DIR}/config_ac.h)

src/wml_backend/p3_eperl/eperl-pod-preproc.pl

+#!/usr/bin/perl
+
+use strict;
+use warnings;
+
+use Getopt::Long;
+
+my $i_fn;
+my $o_fn;
+my $v_fn;
+
+GetOptions(
+    'input=s' => \$i_fn,
+    'output=s' => \$o_fn,
+    'versionfrom=s' => \$v_fn,
+);
+
+my $ver;
+open my $ver_fh, "<", $v_fn
+    or die "Cannot open '$v_fn'";
+VER_LOOP:
+while (my $l = <$ver_fh>)
+{
+    if (my ($val) = $l =~ m{"(\d+\.\d+\.\d+)"})
+    {
+        $ver = $val;
+        last VER_LOOP;
+    }
+}
+close($ver_fh);
+
+open my $in, "<", $i_fn
+    or die "Cannot open input - '$i_fn'!";
+
+my $buffer;
+while (my $l = <$in>)
+{
+    $l =~ s{\@V\@}{$ver}g;
+    $buffer .= $l;
+}
+close($in);
+
+open my $out, ">", $o_fn
+    or die "Cannot open output - '$o_fn'!";
+print {$out} $buffer;
+close($out);

src/wml_backend/p3_eperl/eperl.pod

-##
-##        ____           _ 
-##    ___|  _ \ ___ _ __| |
-##   / _ \ |_) / _ \ '__| |
-##  |  __/  __/  __/ |  | |
-##   \___|_|   \___|_|  |_|
-## 
-##  ePerl -- Embedded Perl 5 Language
-##
-##  ePerl interprets an ASCII file bristled with Perl 5 program
-##  statements by evaluating the Perl 5 code while passing through
-##  the plain ASCII data. It can operate in various ways: As a
-##  stand-alone Unix filter or integrated Perl 5 module for general
-##  file generation tasks and as a powerful Webserver scripting
-##  language for dynamic HTML page programming.
-##
-##  ======================================================================
-##
-##  Copyright (c) 1996,1997 Ralf S. Engelschall, All rights reserved.
-##
-##  This program is free software; it may be redistributed and/or modified
-##  only under the terms of either the Artistic License or the GNU General
-##  Public License, which may be found in the ePerl source distribution.
-##  Look at the files ARTISTIC and COPYING or run ``eperl -l'' to receive
-##  a built-in copy of both license files.
-##
-##  This program is distributed in the hope that it will be useful, but
-##  WITHOUT ANY WARRANTY; without even the implied warranty of
-##  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See either the
-##  Artistic License or the GNU General Public License for more details.
-##
-##  ======================================================================
-##
-##  eperl.pod -- ePerl Documentation in Plain Old Document (POD) Format
-##
-
-=head1 NAME
-
-ePerl - Embedded Perl 5 Language
-
-=head1 VERSION
-
-@V@
-
-=head1 SYNOPSIS
-
-B<eperl>
-[B<-d> I<name>=I<value>]
-[B<-D> I<name>=I<value>]
-[B<-B> I<begin_delimiter>]
-[B<-E> I<end_delimiter>]
-[B<-i>]
-[B<-m> I<mode>]
-[B<-o> I<outputfile>]
-[B<-k>]
-[B<-I> I<directory>]
-[B<-P>]
-[B<-C>]
-[B<-L>]
-[B<-x>]
-[B<-T>]
-[B<-w>]
-[B<-c>]
-[I<inputfile>]
-
-B<eperl>
-[B<-r>]
-[B<-l>]
-[B<-v>]
-[B<-V>]
-
-=head1 DESCRIPTION
-
-=head2 Abstract
-
-ePerl interprets an ASCII file bristled with Perl 5 program statements by
-evaluating the Perl 5 code while passing through the plain ASCII data. It can
-operate in various ways: As a stand-alone Unix filter or integrated Perl 5
-module for general file generation tasks and as a powerful Webserver scripting
-language for dynamic HTML page programming.
-
-=head2 Introduction
-
-The B<eperl> program is the I<Embedded Perl 5 Language> interpreter. This
-really is a full-featured Perl 5 interpreter, but with a different calling
-environment and source file layout than the default Perl interpreter (usually
-the executable B<perl> or B<perl5> on most systems).  It is designed for
-general ASCII file generation with the philosophy of I<embedding> the Perl 5
-program code into the ASCII data instead of the usual way where you embed the
-ASCII data into a Perl 5 program (usually by quoting the data and using them
-via C<print> statements).  So, instead of writing a plain Perl script like
-
-  #!/path/to/perl
-  print "foo bar\n";
-  print "baz quux\n";
-  for ($i = 0; $i < 10; $i++) { print "foo #${i}\n"; }
-  print "foo bar\n";
-  print "baz quux\n";
-
-you can write it now as an ePerl script:
-
-  #!/path/to/eperl
-  foo bar
-  baz quux
-  <: for ($i = 0; $i < 10; $i++) { print "foo #${i}\n"; } :>
-  foo bar
-  baz quux
-
-Although the ePerl variant has a different source file layout, the semantic is
-the same, i.e. both scripts create exactly the same resulting data on
-C<STDOUT>.
-
-=head2 Intention
-
-ePerl is simply a glue code which combines the programming power of the Perl 5
-interpreter library with a tricky embedding technique.  The embedding trick is
-this: it converts the source file into a valid Perl script which then gets
-I<entirely> evaluated by only one internal instance of the Perl 5 interpreter.
-To achieve this, ePerl translates all plain code into (escaped) Perl 5 strings
-placed into F<print> constructs while passing through all embedded native Perl
-5 code. As you can see, ePerl itself does exactly the same internally, a silly
-programmer had to do when writing a plain Perl generation script. 
-
-Due to the nature of such bristled code, ePerl is really the better attempt
-when the generated ASCII data contains really more static as dynamic data. Or
-in other words: I<Use ePerl if you want to keep the most of the generated ASCII
-data in plain format while just programming some bristled stuff.> Do not use it
-when generating pure dynamic data. There it brings no advantage to the
-ordinary program code of a plain Perl script. So, the static part should be at
-least 60% or the advantage becomes a disadvantage.
-
-ePerl in its origin was actually designed for an extreme situation: as a
-webserver scripting-language for on-the-fly HTML page generation. Here you
-have the typical case that usually 90% of the data consists of pure static
-HTML tags and plain ASCII while just the remaining 10% are programming
-constructs which dynamically generate more markup code. This is the reason why
-ePerl beside its standard Unix filtering runtime-mode also supports the
-CGI/1.1 and NPH-CGI/1.1 interfaces.
-
-=head2 Embedded Perl Syntax
-
-Practically you can put any valid Perl constructs inside the ePerl blocks the
-used Perl 5 interpreter library can evaluate. But there are some important
-points you should always remember and never forget when using ePerl:
-
-=over 4
-
-=item I<1. Delimiters are always discarded.>
-
-Trivially to say, but should be mentioned at least once. The ePerl block
-delimiters are always discarded and are only necessary for ePerl to recognize
-the embedded Perl constructs. They are never passed to the final output.
-
-=item I<2. Generated content has to go to C<STDOUT>.>
-
-Although you can define subroutines, calculate some data, etc.  inside ePerl
-blocks only data which is explicitly written to the C<STDOUT> filehandle is
-expanded. In other words: When an ePerl block does not generate content on
-C<STDOUT>, it is entirely replaced by an empty string in the final output.
-But when content is generated it is put at the point of the ePerl block in the
-final output. Usually contents is generated via pure C<print> constructs which
-implicitly use C<STDOUT> when no filehandle is given.
-
-=item I<3. Generated content on C<STDERR> always leads to an error.>
-
-Whenever content is generated on the C<STDERR> filehandle, ePerl displays an
-error (including the STDERR content). Use this to exit on errors while passing
-errors from ePerl blocks to the calling environment.
-
-=item I<4. Last semicolon.>
-
-Because of the following point 6 (see below) and the fact that most of the
-users don't have the internal ePerl block translations in mind, ePerl is smart
-about the last semicolon. Usually every ePerl block has to end with the
-semicolon of the last command.
-
-   <: cmd; ...; cmd; :>
-
-But when the last semicolon is missing it is automatically added
-by ePerl, i.e. 
-
-   <: cmd; ...; cmd :>
-
-is also correct syntax.  But sometimes it is necessary to force ePerl I<not>
-to add the semicolon. Then you can add a ``C<_>'' (underscore) as the last
-non-whitespace character in the block to force ePerl to leave the final
-semicolon. Use this for constructs like the following
-
-   <: if (...) { _:>
-   foo
-   <: } else { _:>
-   bar 
-   <: } :>
-
-where you want to spread a Perl directive over more ePerl blocks.
-
-=item I<5. Shorthand for C<print>-only blocks.>
-
-Because most of the time ePerl is used just to interpolate variables, e.g.
-
-   <: print $VARIABLE; :>
-
-it is useful to provide a shortcut for this kind of constructs.  So ePerl
-provides a shortcut via the character '='. When it immediately (no whitespaces
-allowed here) follows the begin delimiter of an ePerl block a C<print>
-statement is implicitly generated, i.e. the above block is equivalent to
-
-   <:=$VARIABLE:>
-
-Notice that the semicolon was also removed here, because it gets automatically
-added (see above).
-
-=item I<6. Special EndOfLine discard command for ePerl blocks.>
-
-ePerl provides a special discard command named ``C<//>'' which discards all
-data up-to and including the following newline character when directly
-followed an end block delimiter. Usually when you write
-
-  foo
-  <: $x = 1; :>
-  quux
-
-the result is
-
-  foo
-  
-  quux
-
-because ePerl always preserves code around ePerl blocks, even
-just newlines. But when you write
-
-  foo
-  <: $x = 1; :>//
-  quux
-
-the result is 
-
-  foo
-  quux
-
-because the ``C<//>'' deleted all stuff to the end of the line, I<including>
-the newline.
-
-=item I<7. Restrictions in parsing.>
-
-Every program has its restrictions, ePerl too. Its handicap is that Perl is
-not only a rich language, it is a horrible one according to parsing its
-constructs. Perhaps you know the phrase ,,Only F<perl> can parse I<Perl>''.
-Think about it. The implication of this is that ePerl never tries to parse the
-ePerl blocks itself. It entirely relies on the Perl interpreter library,
-because it is the only instance which can do this without errors.  But the
-problem is that ePerl at least has to recognize the begin and end positions of
-those ePerl blocks. 
-
-There are two ways: It can either look for the end delimiter while parsing but
-at least recognize quoted strings (where the end delimiter gets treated as
-pure data). Or it can just move forward to the next end delimiter and say that
-it have not occur inside Perl constructs. In ePerl 2.0 the second one was
-used, while in ePerl 2.1 the first one was taken because a lot of users wanted
-it this way while using bad end delimiters like ``C<E<gt>>''. But actually the
-author has again revised its opinion and decided to finally use the second
-approach which is used since ePerl 2.2 now. Because while the first one allows
-more trivial delimiters (which itself is not a really good idea), it fails
-when constructs like ``C<m|"[^"]+"|>'' etc.  are used inside ePerl blocks. And
-it is easier to escape end delimiters inside Perl constructs (for instance via
-backslashes in quoted strings) than rewrite complex Perl constructs to use
-even number of quotes.
-
-So, whenever your end delimiter also occurs inside Perl constructs you have to
-escape it in any way. 
-
-=item I<8. HTML entity conversion.>
-
-Because one of ePerl's usage is as a server-side scripting-language for HTML
-pages, there is a common problem in conjunction with HTML editors.  They
-cannot know ePerl blocks, so when you enter those blocks inside the editors
-they usually encode some characters with the corresponding HTML entities. The
-problem is that this encoding leads to invalid Perl code. ePerl provides the
-option B<-C> for decoding these entities which is automatically turned on in
-CGI modes. See description below under option B<-C> for more details.
-
-=back
-
-=head2 Runtime Modes
-
-ePerl can operate in three different runtime modes:
-
-=over 4
-
-=item I<Stand-alone Unix filter mode>
-
-This is the default operation mode when used as a generation tool from the
-Unix shell or as a batch-processing tool from within other programs or
-scripts:
-
-  $ eperl [options] - < inputfile > outputfile
-  $ eperl [options] inputfile > outputfile
-  $ eperl [options] -o outputfile - < inputfile
-  $ eperl [options] -o outputfile inputfile
-
-As you can see, ePerl can be used in any combination of STDIO and external
-files. Additionally there are two interesting variants of using this mode.
-First you can use ePerl in conjunction with the Unix I<Shebang> magic
-technique to implicitly select it as the interpreter for your script similar
-to the way you are used to with the plain Perl interpreter:
-
-  #!/path/to/eperl [options]
-  foo
-  <: print "bar"; :>
-  quux
-
-Second, you can use ePerl in conjunction with the Bourne-Shell I<Here
-Document> technique from within you shell scripts:
-
-  #!/bin/sh
-  ...
-  eperl [options] - <<EOS
-  foo
-  <: print "quux"; :>
-  quux
-  EOS
-  ...
-
-And finally you can use ePerl directly from within Perl programs by the use of
-the Parse::ePerl(3) package (assuming that you have installed this also; see
-file F<INSTALL> inside the ePerl distribution for more details):
-
-  #!/path/to/perl
-  ...
-  use Parse::ePerl;
-  ...
-  $script = <<EOT;
-  foo
-  <: print "quux"; :>
-  quux
-  EOT
-  ...
-  $result = Parse::ePerl::Expand({
-      Script => $script,
-      Result => \$result,
-  });
-  ...
-  print $result;
-  ...
-
-See Parse::ePerl(3) for more details.
-
-=item I<CGI/1.1 compliant interface mode>
-
-This is the runtime mode where ePerl uses the CGI/1.1 interface of a webserver
-when used as a I<Server-Side Scripting Language> on the Web. ePerl enters this
-mode automatically when the CGI/1.1 environment variable C<PATH_TRANSLATED> is
-set and its or the scripts filename does I<not> begin with the NPH prefix
-``F<nph->''.  In this runtime mode it prefixes the resulting data with
-HTTP/1.0 (default) or HTTP/1.1 (if identified by the webserver) compliant
-response header lines.
-
-ePerl also recognizes HTTP header lines at the beginning of the scripts
-generated data, i.e. for instance you can generate your own HTTP headers like
-
-   <? $url = "..";
-      print "Location: $url\n";
-      print "URI: $url\n\n"; !>
-   <html>
-   ...
-
-But notice that while you can output arbitrary headers, most webservers
-restrict the headers which are accepted via the CGI/1.1 interface. Usually you
-can provide only a few specific HTTP headers like C<Location> or C<Status>.
-If you need more control you have to use the NPH-CGI/1.1 interface mode.
-
-Additionally ePerl provides a useful feature in this mode: It can switch its
-UID/GID to the owner of the script if it runs as a Unix I<SetUID> program (see
-below under L<Security> and the option ``u+s'' of chmod(1)).
-
-There are two commonly known ways of using this CGI/1.1 interface mode on the
-Web. First, you can use it to explicitly transform plain HTML files into
-CGI/1.1 scripts via the I<Shebang> technique (see above). For an Apache
-webserver just put the following line as the first line of the file:
-
-  #!/path/to/eperl -mc
-
-Then rename the script from F<file.html> to F<file.cgi> and set its execution
-bit via
-
-  $ mv file.html file.cgi
-  $ chmod a+rx file.cgi
-
-Now make sure that Apache accepts F<file.cgi> as a CGI program by enabling CGI
-support for the directory where F<file.cgi> resides. For this add the line
-
-  Options +ExecCGI
-
-to the F<.htaccess> file in this directory. Finally make sure that Apache
-really recognizes the extension F<.cgi>. Perhaps you additionally have to add
-the following line to your F<httpd.conf> file:
-
-  AddHandler cgi-script .cgi
-
-Now you can use F<file.cgi> instead of F<file.html> and make advantage of the
-achieved programming capability by bristling F<file.cgi> with your Perl
-blocks (or the transformation into a CGI script would be useless).
-
-Alternatively (or even additionally) a webmaster can enable ePerl support in a
-more seemless way by configuring ePerl as a real implicit server-side
-scripting language. This is done by assigning a MIME-type to the various valid
-ePerl file extensions and forcing all files with this MIME-type to be
-internally processed via the ePerl interpreter. You can accomplish this for
-Apache by adding the following to your F<httpd.conf> file
-
-  AddType      application/x-httpd-eperl  .phtml .eperl .epl
-  Action       application/x-httpd-eperl  /internal/cgi/eperl
-  ScriptAlias  /internal/cgi              /path/to/apache/cgi-bin
-
-and creating a copy of the F<eperl> program in your CGI-directory:
-
-  $ cp -p /path/to/eperl /path/to/apache/cgi-bin/eperl
-
-Now all files with the extensions F<.phtml>, F<.eperl> and F<.epl> are
-automatically processed by the ePerl interpreter. There is no need for a
-I<Shebang> line or any locally enabled CGI mode.
-
-One final hint: When you want to test your scripts offline, just run them with
-forced CGI/1.1 mode from your shell. But make sure you prepare all environment
-variables your script depends on, e.g. C<QUERY_STRING> or C<PATH_INFO>.
-
-  $ export QUERY_STRING="key1=value1&key2=value2"
-  $ eperl -mc file.phtml
-
-
-=item I<NPH-CGI/1.1 compliant interface mode>
-
-This runtime mode is a special variant of the CGI/1.1 interface mode, because
-most webservers (e.g. Apache) provide it for special purposes.   It is known
-as I<Non-Parsed-Header> (NPH) CGI/1.1 mode and is usually used by the
-webserver when the filename of the CGI program is prefixed with ``C<nph->''.
-In this mode the webserver does no processing on the HTTP response headers and
-no buffering of the resulting data, i.e. the CGI program actually has to
-provide a complete HTTP response itself. The advantage is that the program can
-generate arbitrary HTTP headers or MIME-encoded multi-block messages.
-
-So, 
-above we have renamed the file to F<file.cgi> which restricted us a little
-bit. When we alternatively rename F<file.html> to F<nph-file.cgi> and force
-the NPH-CGI/1.1 interface mode via option B<-mn> then this file becomes a
-NPH-CGI/1.1 compliant program under Apache and other webservers. Now our
-script can provide its own HTTP response (it need not, because when absent
-ePerl provides a default one for it).
-
-  #!/path/to/bin/eperl -mn
-  <? print "HTTP/1.0 200 Ok\n";
-     print "X-MyHeader: Foo Bar Quux\n";
-     print "Content-type: text/html\n\n";
-  <html>
-  ...
-
-As you expect this can be also used with the implicit Server-Side Scripting
-Language technique. Put  
-
-  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
-
-into your F<httpd.conf> and run the command
-
-  $ cp -p /path/to/eperl /path/to/apache/cgi-bin/nph-eperl
-
-from your shell. I<This is the preferred way of using ePerl as a Server-Side
-Scripting Language, because it provides most flexibility>.
-
-=back
-
-=head2 Security
-
-When you are installing ePerl as a CGI/1.1 or NPH-CGI/1.1 compliant program
-(see above for detailed description of these modes) via
-
-  $ cp -p /path/to/eperl /path/to/apache/cgi-bin/eperl
-  $ chown root /path/to/apache/cgi-bin/eperl
-  $ chmod u+s  /path/to/apache/cgi-bin/eperl
-
-or
-
-  $ cp -p /path/to/eperl /path/to/apache/cgi-bin/nph-eperl
-  $ chown root /path/to/apache/cgi-bin/nph-eperl
-  $ chmod u+s  /path/to/apache/cgi-bin/nph-eperl
-
-i.e. with I<SetUID> bit enabled for the B<root> user, ePerl can switch to the
-UID/GID of the I<scripts owner>. Although this is a very useful feature for
-script programmers (because one no longer need to make auxiliary files
-world-readable and temporary files world-writable!), it can be to risky for
-you when you are paranoid about security of SetUID programs. If so just don't
-install ePerl with enabled SetUID bit! This is the reason why ePerl is per
-default only installed as a Stand-Alone Unix filter which never needs this
-feature.
-
-For those of us who decided that this feature is essential for them ePerl
-tries really hard to make it secure. The following steps have to be
-successfully passed before ePerl actually switches its UID/GID (in this
-order):
-
-  1. The script has to match the following extensions:
-     .html, .phtml, .ephtml, .epl, .pl, .cgi
-  2. The UID of the calling process has to be a valid UID,
-     i.e. it has to be found in the systems password file
-  3. The UID of the calling process has to match the 
-     following users: root, nobody
-  4. The UID of the script owner has to be a valid UID,
-     i.e. it has to be found in the systems password file
-  5. The GID of the script group has to be a valid GID,
-     i.e. it has to be found in the systems group file
-  6. The script has to stay below or in the owners homedir
-
-I<IF ONLY ONE OF THOSE STEPS FAIL, NO UID/GID SWITCHING TAKES PLACE!>.
-Additionally (if C<DO_ON_FAILED_STEP> was defined as C<STOP_AND_ERROR> in
-F<eperl_security.h> - not per default defined this way!) ePerl can totally stop
-processing and display its error page.  This is for the really paranoid
-webmasters. Per default when any step failed the UID/GID switching is just
-disabled, but ePerl goes on with processing. Alternatively you can disable
-some steps at compile time. See F<eperl_security.h>.
-
-I<Also remember that ePerl always eliminates the effective UID/GID,
-independent of the runtime mode and independent if ePerl has switched to the
-UID/GID of the owner. For security reasons, the effective UID/GID is always
-destroyed before the script is executed.>
-
-=head2 ePerl Preprocessor
-
-ePerl provides an own preprocessor similar to F<CPP> in style which is either
-enabled manually via option B<-P> or automatically when ePerl runs in
-(NPH-)CGI mode.  The following directives are supported:
-
-=over 4
-
-=item C<#include path> 
-
-This directive is an include directive which can be used to include really any
-stuff, but was actually designed to be used to include other ePerl source
-files. The I<path> can be either a relative or absolute path for the local
-filesystem or a fully qualified HTTP URL.
-
-In case of the absolute path the file is directly accessed on the filesystem,
-while the relative path is first searched in the current working directory and
-then in all directories specified via option B<-I>. In the third case
-(HTTP URL) the file is retrieves via a HTTP/1.0 request on the network. 
-Here HTTP redirects (response codes 301 and 302) are supported, too.
-
-Notice: While ePerl strictly preserves the line numbers when translating the
-bristled ePerl format to plain Perl format, the ePerl preprocessor can't do
-this (because its a B<pre>processor which expands) for this directive.  So,
-whenever you use C<#include>, remember that line numbers in error messages are
-wrong.
-
-Also notice one important security aspect: Because you can include any stuff
-as it is provided with this directive, use it only for stuff which is under
-your direct control. Don't use this directive to include foreign data, at
-least not from external webservers. For instance say you have a ePerl page
-with C<#include http://www.foreigner.com/nice-page.html> and at the next
-request of this page your filesystem is lost! Why? Because the foreigner
-recognizes that you include his page and are using ePerl and just put a simple
-``C<E<lt>?  system("rm -rf /"); !E<gt>>'' in his page. Think about it.
-I<NEVER USE #INCLUDE FOR ANY DATA WHICH IS NOT UNDER YOUR OWN CONTROL>.
-Instead always use C<#sinclude> for such situations.
-
-=item C<#sinclude path> 
-
-This is the secure variant of C<#include> where after reading the data from
-I<path> all ePerl begin and end delimiters are removed. So risky ePerl blocks
-lost their meaning and are converted to plain text. Always use this directive
-when you want to include data which is not under your own control.
-
-=item C<#if expr>, C<#elsif expr>, C<#else>, C<#endif>
-
-These implement a CPP-style C<#if-[#else-]#endif> construct, but with a Perl
-semantic. While the other directives are real preprocessor commands which are
-evaluated at the preprocessing step, this construct is actually just
-transformed into a low-level ePerl construct, so it is B<not> actually
-evaluated at the preprocessing step. It is just a handy shortcut for the
-following (where BD is the currently used begin delimiter and ED the end
-delimiter):
-
-  ``#if expr''    ->  ``BD if (expr) { _ ED//''
-  ``#elsif expr'' ->  ``BD } elsif (expr) { _ ED//''
-  ``#else''       ->  ``BD } else { _ ED//''
-  ``#endif''      ->  ``BD } _ ED//''
-
-The advantage of this unusual aproach is that the if-condition really can be
-any valid Perl expression which provides maximum flexibility. The disadvantage
-is that you cannot use the if-construct to make real preprocessing decisions.
-As you can see, the design goal was just to provide a shorthand for the more
-complicated Perl constructs.
-
-=item C<#c>
-
-This is the comment directive which just discards all data up to and including
-the newline character. Use this one to comment out any stuff, even other
-preprocessor directives.
-
-=back
-
-=head2 Provided Functionality
-
-Up to know you've understand that ePerl provides a nice facility to embed Perl
-code into any ASCII data. But now the typical question is: Which Perl code can
-be put into these ePerl blocks and does ePerl provide any special
-functionality inside these ePerl blocks?
-
-The answers are: First, you can put really I<any> Perl code into the ePerl
-blocks which are valid to the Perl interpreter ePerl was linked with. Second,
-ePerl does I<not> provide any special functionality inside these ePerl blocks,
-because Perl is already sophisticated enough ;-)
-
-The implication of this is: Because you can use any valid Perl code you can
-make use of all available Perl 5 modules, even those ones which use shared
-objects (because ePerl I<is> a Perl interpreter, including DynaLoader
-support). So, browse to the Comprehensive Perl Archive Network (CPAN) via
-http://www.perl.com/perl/CPAN and grab your favorite packages which can make
-your life easier (both from within plain Perl scripts I<and> ePerl scripts)
-and just use the construct ``C<use name;>'' in any ePerl block to use them
-from within ePerl. 
-
-When using ePerl as a Server-Side-Scripting-Language I really recommend you to
-install at least the packages F<CGI.pm> (currently vers.  2.36),
-F<HTML-Stream> (1.40), F<libnet> (1.0505) and F<libwww-perl> (5.08).  When you
-want to generate on-the-fly images as well, I recommend you to additionally
-install at least F<GD> (1.14) and F<Image-Size> (2.3). The ePerl interpreter
-in conjunction with these really sophisticated Perl 5 modules will provide you
-with maximum flexibility and functionality. In other words: I<Make use of
-maximum Software Leverage in the hackers world of Perl as great as possible>.
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-d> I<name>=I<value>
-
-Sets a Perl variable in the package C<main> which can be referenced
-via C<$name> or more explicitly via C<$main::name>. The command
-
-  eperl -d name=value ..
-  
-is actually equivalent to having
-
-  <? $name = value; !>
-
-at the beginning of I<inputfile>. This option can occur more than once.
-
-=item B<-D> I<name>=I<value>
-
-Sets a environment variable which can be referenced via C<$ENV{'variable'}>
-inside the Perl blocks. The command
-
-  eperl -D name=value ..
-  
-is actually equivalent to 
-
-  export name=value; eperl ...
-
-but the advantage of this option is that it doesn't manipulate the callers
-environment. This option can occur more than once.
-
-=item B<-B> I<begin_delimiter>
-
-Sets the Perl block begin delimiter string. Use this in conjunction with C<-E>
-to set different delimiters when using ePerl as an offline HTML
-creation-language while still using it as an online HTML scripting-language.
-Default delimiters are C<E<lt>?> and C<!E<gt>> for CGI modes and C<E<lt>:> and
-C<:E<gt>> for stand-alone Unix filtering mode.
-
-There are a lot of possible variations you could choose: "C<E<lt>:>" and
-"C<:E<gt>>" (the default ePerl stand-alone filtering mode delimiters),
-"C<E<lt>?>" and "C<!E<gt>>" (the default ePerl CGI interface mode delimiters),
-"C<E<lt>script language='ePerl'E<gt>>" and "C<E<lt>/scriptE<gt>>" (standard
-HTML scripting language style), "C<E<lt>script type="text/eperl"E<gt>>" and
-"C<E<lt>/scriptE<gt>>" (forthcoming HTML3.2+ aka Cougar style),
-"C<E<lt>eperlE<gt>>" and "C<E<lt>/eperlE<gt>>" (HTML-like style),
-"C<E<lt>!--#eperl code='>" and "C<' --E<gt>>" (NeoScript and SSI style) or
-even "C<E<lt>?>" and "C<E<gt>>" (PHP/FI style; but this no longer recommended
-because it can lead to parsing problems. Should be used only for backward
-compatibility to old ePerl versions 1.x).
-
-The begin and end delimiters are searched case-insensitive.
-
-=item B<-E> I<end_delimiter>
-
-Sets the Perl block end delimiter string. See also option B<-B>.
-
-=item B<-i>
-
-Forces the begin and end delimiters to be searched case-insensitive.  Use this
-when you are using delimiters like
-``C<E<lt>ePerlE<gt>>...C<E<lt>/ePerlE<gt>>'' or other more textual ones.
-
-=item B<-m> I<mode>
-
-This forces ePerl to act in a specific runtime mode.  See above for a detailed
-description of the three possible modes: Stand-alone filter (I<mode>=C<f>,
-i.e. option B<-mf>), CGI/1.1 interface mode (I<mode>=C<c>, i.e. option B<-mc>)
-or the NPH-CGI/1.1 interface mode (I<mode>=C<n>, i.e. option B<-mn>).
-
-=item B<-o> I<outputfile>
-
-Forces the output to be written to F<outputfile> instead of F<STDOUT>. Use
-this option when using ePerl as a filter. The outputfile ``F<->'' sets F<STDOUT>
-as the output handle explicitly. Notice that this file is relative to the
-source file directory when the runtime mode is forced to CGI or NPH-CGI.
-
-=item B<-k>
-
-Forces ePerl to keep the current working directory from where it was started.
-Per default ePerl will change to the directory where the file to be executed
-stays. This option is useful if you use ePerl as an offline filter on
-a temporary file.
-
-=item B<-x>
-
-This sets debug mode where ePerl outputs the internally created Perl script to
-the console (F</dev/tty>) before executing it. Only for debugging problems with
-the inputfile conversion.
-
-=item B<-I> I<directory>
-
-Specify a directory which is both used for C<#include> and C<#sinclude>
-directives of the ePerl preprocessor and added to C<@INC> under runtime.  This
-option can occur more than once.
-
-=item B<-P>
-
-Manually enables the special ePerl Preprocessor (see above). This option is
-enabled for all CGI modes automatically.
-
-=item B<-C>
-
-This enables the HTML entity conversion for ePerl blocks. This option is
-automatically forced in CGI modes. 
-
-The solved problem here is the following: When you use ePerl as a
-Server-Side-Scripting-Language for HTML pages and you edit your ePerl source
-files via a HTML editor, the chance is high that your editor translates some
-entered characters to HTML entities, for instance ``C<E<lt>>'' to ``C<&lt;>''.
-This leads to invalid Perl code inside ePerl blocks, because the HTML editor
-has no knowledge about ePerl blocks. Using this option the ePerl parser
-automatically converts all entities found inside ePerl blocks back to plain
-characters, so the Perl interpreter again receives valid code blocks.
-
-=item B<-L>
-
-This enables the line continuation character ``C<\>'' (backslash) outside
-ePerl blocks. With this option you can spread oneline-data over more lines.
-But use with care: This option changes your data (outside ePerl blocks).
-Usually ePerl really pass through all surrounding data as raw data. With this
-option the newlines become new semantics.
-
-=item B<-T>
-
-This enabled Perl's I<Tainting mode> where the Perl interpreter takes special
-precautions called taint checks to prevent both obvious and subtle traps.  See
-perlsec(1) for more details.
-
-=item B<-w>
-
-This enables Warnings where the Perl interpreter produces some lovely
-diagnostics. See perldiag(1) for more details.
-
-=item B<-c>
-
-This runs a pure syntax check which is similar to ``C<perl -c>''.
-
-=item B<-r>
-
-This prints the internal ePerl README file to the console.
-
-=item B<-l>
-
-This prints the internal ePerl LICENSE file to the console.
-
-=item B<-v>
-
-This prints ePerl version information to the console.
-
-=item B<-V>
-
-Same as option B<-v> but additionally shows the Perl compilation parameters.
-
-=back
-
-=head1 ENVIRONMENT
-
-=head2 Used Variables
-
-=over 4
-
-=item C<PATH_TRANSLATED>
-
-This CGI/1.1 variable is used to determine the source file when ePerl operates
-as a NPH-CGI/1.1 program under the environment of a webserver.
-
-=back
-
-=head2 Provided Variables
-
-=over 4
-
-=item C<SCRIPT_SRC_PATH>
-
-The absolute pathname of the script. Use this when you want to
-directly access the script from within itself, for instance to do
-C<stat()> and other calls.
-
-=item C<SCRIPT_SRC_PATH_DIR>
-
-The directory part of C<SCRIPT_SRC_PATH>. Use this one when you want to
-directly access other files residing in the same directory as the script, for
-instance to read config files, etc.
-
-=item C<SCRIPT_SRC_PATH_FILE>
-
-The filename part of C<SCRIPT_SRC_PATH>. Use this one when you need the name
-of the script, for instance for relative self-references through URLs.
-
-=item C<SCRIPT_SRC_URL>
-
-The fully-qualified URL of the script. Use this when you need a URL for
-self-reference.
-
-=item C<SCRIPT_SRC_URL_DIR>
-
-The directory part of C<SCRIPT_SRC_URL>. Use this one when you want to
-directly access other files residing in the same directory as the script via
-the Web, for instance to reference images, etc.
-
-=item C<SCRIPT_SRC_URL_FILE>
-
-The filename part of C<SCRIPT_SRC_URL>. Use this one when you need the name of
-the script, for instance for relative self-references through URLs.  Actually
-the same as C<SCRIPT_SRC_PATH_FILE>, but provided for consistency. 
-
-=item C<SCRIPT_SRC_SIZE>
-
-The filesize of the script, in bytes.
-
-=item C<SCRIPT_SRC_MODIFIED>
-
-The last modification time of the script, in seconds since 0 hours, 0 minutes,
-0 seconds, January 1, 1970, Coordinated Universal Time.
-
-=item C<SCRIPT_SRC_MODIFIED_CTIME>
-
-The last modification time of the script, in ctime(3) format (``WDAY MMM DD
-HH:MM:SS YYYY\n'').
-
-=item C<SCRIPT_SRC_MODIFIED_ISOTIME>
-
-The last modification time of the script, in ISO format (``DD-MM-YYYY
-HH:MM'').
-
-=item C<SCRIPT_SRC_OWNER>
-
-The username of the script owner.
-
-=item C<VERSION_INTERPRETER>
-
-The ePerl identification string.
-
-=item C<VERSION_LANGUAGE>
-
-The identification string of the used Perl interpreter library.
-
-=back
-
-=head2 Provided Built-In Images
-
-The following built-in images can be accessed via URL
-C</url/to/nph-eperl/>I<NAME>C<.gif>:
-
-=over 4
-
-=item C<logo.gif>
-
-The standard ePerl logo. Please do not include this one on your website.
-
-=item C<powered.gif>
-
-The ``I<powered by ePerl 2.2>'' logo. Feel free to use this on your website.
-
-=back
-
-=head1 AUTHOR
-
-  Ralf S. Engelschall
-  rse@engelschall.com
-  www.engelschall.com
-
-=head1 SEEALSO
-
-Parse::ePerl(3), Apache::ePerl(3).
-
-Web-References:
-
-  Perl:   perl(1),  http://www.perl.com/
-  ePerl:  eperl(1), http://www.ossp.org/pkg/tool/eperl/
-  Apache: httpd(8), http://www.apache.org/
-
-=cut
-
-##EOF##

src/wml_backend/p3_eperl/eperl.proto.pod

+##
+##        ____           _ 
+##    ___|  _ \ ___ _ __| |
+##   / _ \ |_) / _ \ '__| |
+##  |  __/  __/  __/ |  | |
+##   \___|_|   \___|_|  |_|
+## 
+##  ePerl -- Embedded Perl 5 Language
+##
+##  ePerl interprets an ASCII file bristled with Perl 5 program
+##  statements by evaluating the Perl 5 code while passing through
+##  the plain ASCII data. It can operate in various ways: As a
+##  stand-alone Unix filter or integrated Perl 5 module for general
+##  file generation tasks and as a powerful Webserver scripting
+##  language for dynamic HTML page programming.
+##
+##  ======================================================================
+##
+##  Copyright (c) 1996,1997 Ralf S. Engelschall, All rights reserved.
+##
+##  This program is free software; it may be redistributed and/or modified
+##  only under the terms of either the Artistic License or the GNU General
+##  Public License, which may be found in the ePerl source distribution.
+##  Look at the files ARTISTIC and COPYING or run ``eperl -l'' to receive
+##  a built-in copy of both license files.
+##
+##  This program is distributed in the hope that it will be useful, but
+##  WITHOUT ANY WARRANTY; without even the implied warranty of
+##  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See either the
+##  Artistic License or the GNU General Public License for more details.
+##
+##  ======================================================================
+##
+##  eperl.pod -- ePerl Documentation in Plain Old Document (POD) Format
+##
+
+=head1 NAME
+
+ePerl - Embedded Perl 5 Language
+
+=head1 VERSION
+
+@V@
+
+=head1 SYNOPSIS
+
+B<eperl>
+[B<-d> I<name>=I<value>]
+[B<-D> I<name>=I<value>]
+[B<-B> I<begin_delimiter>]
+[B<-E> I<end_delimiter>]
+[B<-i>]
+[B<-m> I<mode>]
+[B<-o> I<outputfile>]
+[B<-k>]
+[B<-I> I<directory>]
+[B<-P>]
+[B<-C>]
+[B<-L>]
+[B<-x>]
+[B<-T>]
+[B<-w>]
+[B<-c>]
+[I<inputfile>]
+
+B<eperl>
+[B<-r>]
+[B<-l>]
+[B<-v>]
+[B<-V>]
+
+=head1 DESCRIPTION
+
+=head2 Abstract
+
+ePerl interprets an ASCII file bristled with Perl 5 program statements by
+evaluating the Perl 5 code while passing through the plain ASCII data. It can
+operate in various ways: As a stand-alone Unix filter or integrated Perl 5
+module for general file generation tasks and as a powerful Webserver scripting
+language for dynamic HTML page programming.
+
+=head2 Introduction
+
+The B<eperl> program is the I<Embedded Perl 5 Language> interpreter. This
+really is a full-featured Perl 5 interpreter, but with a different calling
+environment and source file layout than the default Perl interpreter (usually
+the executable B<perl> or B<perl5> on most systems).  It is designed for
+general ASCII file generation with the philosophy of I<embedding> the Perl 5
+program code into the ASCII data instead of the usual way where you embed the
+ASCII data into a Perl 5 program (usually by quoting the data and using them
+via C<print> statements).  So, instead of writing a plain Perl script like
+
+  #!/path/to/perl
+  print "foo bar\n";
+  print "baz quux\n";
+  for ($i = 0; $i < 10; $i++) { print "foo #${i}\n"; }
+  print "foo bar\n";
+  print "baz quux\n";
+
+you can write it now as an ePerl script:
+
+  #!/path/to/eperl
+  foo bar
+  baz quux
+  <: for ($i = 0; $i < 10; $i++) { print "foo #${i}\n"; } :>
+  foo bar
+  baz quux
+
+Although the ePerl variant has a different source file layout, the semantic is
+the same, i.e. both scripts create exactly the same resulting data on
+C<STDOUT>.
+
+=head2 Intention
+
+ePerl is simply a glue code which combines the programming power of the Perl 5
+interpreter library with a tricky embedding technique.  The embedding trick is
+this: it converts the source file into a valid Perl script which then gets
+I<entirely> evaluated by only one internal instance of the Perl 5 interpreter.
+To achieve this, ePerl translates all plain code into (escaped) Perl 5 strings
+placed into F<print> constructs while passing through all embedded native Perl
+5 code. As you can see, ePerl itself does exactly the same internally, a silly
+programmer had to do when writing a plain Perl generation script. 
+
+Due to the nature of such bristled code, ePerl is really the better attempt
+when the generated ASCII data contains really more static as dynamic data. Or
+in other words: I<Use ePerl if you want to keep the most of the generated ASCII
+data in plain format while just programming some bristled stuff.> Do not use it
+when generating pure dynamic data. There it brings no advantage to the
+ordinary program code of a plain Perl script. So, the static part should be at
+least 60% or the advantage becomes a disadvantage.
+
+ePerl in its origin was actually designed for an extreme situation: as a
+webserver scripting-language for on-the-fly HTML page generation. Here you
+have the typical case that usually 90% of the data consists of pure static
+HTML tags and plain ASCII while just the remaining 10% are programming
+constructs which dynamically generate more markup code. This is the reason why
+ePerl beside its standard Unix filtering runtime-mode also supports the
+CGI/1.1 and NPH-CGI/1.1 interfaces.
+
+=head2 Embedded Perl Syntax
+
+Practically you can put any valid Perl constructs inside the ePerl blocks the
+used Perl 5 interpreter library can evaluate. But there are some important
+points you should always remember and never forget when using ePerl:
+
+=over 4
+
+=item I<1. Delimiters are always discarded.>
+
+Trivially to say, but should be mentioned at least once. The ePerl block
+delimiters are always discarded and are only necessary for ePerl to recognize
+the embedded Perl constructs. They are never passed to the final output.
+
+=item I<2. Generated content has to go to C<STDOUT>.>
+
+Although you can define subroutines, calculate some data, etc.  inside ePerl
+blocks only data which is explicitly written to the C<STDOUT> filehandle is
+expanded. In other words: When an ePerl block does not generate content on
+C<STDOUT>, it is entirely replaced by an empty string in the final output.
+But when content is generated it is put at the point of the ePerl block in the
+final output. Usually contents is generated via pure C<print> constructs which
+implicitly use C<STDOUT> when no filehandle is given.
+
+=item I<3. Generated content on C<STDERR> always leads to an error.>
+
+Whenever content is generated on the C<STDERR> filehandle, ePerl displays an
+error (including the STDERR content). Use this to exit on errors while passing
+errors from ePerl blocks to the calling environment.
+
+=item I<4. Last semicolon.>
+
+Because of the following point 6 (see below) and the fact that most of the
+users don't have the internal ePerl block translations in mind, ePerl is smart
+about the last semicolon. Usually every ePerl block has to end with the
+semicolon of the last command.
+
+   <: cmd; ...; cmd; :>
+
+But when the last semicolon is missing it is automatically added
+by ePerl, i.e. 
+
+   <: cmd; ...; cmd :>
+
+is also correct syntax.  But sometimes it is necessary to force ePerl I<not>
+to add the semicolon. Then you can add a ``C<_>'' (underscore) as the last
+non-whitespace character in the block to force ePerl to leave the final
+semicolon. Use this for constructs like the following
+
+   <: if (...) { _:>
+   foo
+   <: } else { _:>
+   bar 
+   <: } :>
+
+where you want to spread a Perl directive over more ePerl blocks.
+
+=item I<5. Shorthand for C<print>-only blocks.>
+
+Because most of the time ePerl is used just to interpolate variables, e.g.
+
+   <: print $VARIABLE; :>
+
+it is useful to provide a shortcut for this kind of constructs.  So ePerl
+provides a shortcut via the character '='. When it immediately (no whitespaces
+allowed here) follows the begin delimiter of an ePerl block a C<print>
+statement is implicitly generated, i.e. the above block is equivalent to
+
+   <:=$VARIABLE:>
+
+Notice that the semicolon was also removed here, because it gets automatically
+added (see above).
+
+=item I<6. Special EndOfLine discard command for ePerl blocks.>
+
+ePerl provides a special discard command named ``C<//>'' which discards all
+data up-to and including the following newline character when directly
+followed an end block delimiter. Usually when you write
+
+  foo
+  <: $x = 1; :>
+  quux
+
+the result is
+
+  foo
+  
+  quux
+
+because ePerl always preserves code around ePerl blocks, even
+just newlines. But when you write
+
+  foo
+  <: $x = 1; :>//
+  quux
+
+the result is 
+
+  foo
+  quux
+
+because the ``C<//>'' deleted all stuff to the end of the line, I<including>
+the newline.
+
+=item I<7. Restrictions in parsing.>
+
+Every program has its restrictions, ePerl too. Its handicap is that Perl is
+not only a rich language, it is a horrible one according to parsing its
+constructs. Perhaps you know the phrase ,,Only F<perl> can parse I<Perl>''.
+Think about it. The implication of this is that ePerl never tries to parse the
+ePerl blocks itself. It entirely relies on the Perl interpreter library,
+because it is the only instance which can do this without errors.  But the
+problem is that ePerl at least has to recognize the begin and end positions of
+those ePerl blocks. 
+
+There are two ways: It can either look for the end delimiter while parsing but
+at least recognize quoted strings (where the end delimiter gets treated as
+pure data). Or it can just move forward to the next end delimiter and say that
+it have not occur inside Perl constructs. In ePerl 2.0 the second one was
+used, while in ePerl 2.1 the first one was taken because a lot of users wanted
+it this way while using bad end delimiters like ``C<E<gt>>''. But actually the
+author has again revised its opinion and decided to finally use the second
+approach which is used since ePerl 2.2 now. Because while the first one allows
+more trivial delimiters (which itself is not a really good idea), it fails
+when constructs like ``C<m|"[^"]+"|>'' etc.  are used inside ePerl blocks. And
+it is easier to escape end delimiters inside Perl constructs (for instance via
+backslashes in quoted strings) than rewrite complex Perl constructs to use
+even number of quotes.
+
+So, whenever your end delimiter also occurs inside Perl constructs you have to
+escape it in any way. 
+
+=item I<8. HTML entity conversion.>
+
+Because one of ePerl's usage is as a server-side scripting-language for HTML
+pages, there is a common problem in conjunction with HTML editors.  They
+cannot know ePerl blocks, so when you enter those blocks inside the editors
+they usually encode some characters with the corresponding HTML entities. The
+problem is that this encoding leads to invalid Perl code. ePerl provides the
+option B<-C> for decoding these entities which is automatically turned on in
+CGI modes. See description below under option B<-C> for more details.
+
+=back
+
+=head2 Runtime Modes
+
+ePerl can operate in three different runtime modes:
+
+=over 4
+
+=item I<Stand-alone Unix filter mode>
+
+This is the default operation mode when used as a generation tool from the
+Unix shell or as a batch-processing tool from within other programs or
+scripts:
+
+  $ eperl [options] - < inputfile > outputfile
+  $ eperl [options] inputfile > outputfile
+  $ eperl [options] -o outputfile - < inputfile
+  $ eperl [options] -o outputfile inputfile
+
+As you can see, ePerl can be used in any combination of STDIO and external
+files. Additionally there are two interesting variants of using this mode.
+First you can use ePerl in conjunction with the Unix I<Shebang> magic
+technique to implicitly select it as the interpreter for your script similar
+to the way you are used to with the plain Perl interpreter:
+
+  #!/path/to/eperl [options]
+  foo
+  <: print "bar"; :>
+  quux
+
+Second, you can use ePerl in conjunction with the Bourne-Shell I<Here
+Document> technique from within you shell scripts:
+
+  #!/bin/sh
+  ...
+  eperl [options] - <<EOS
+  foo
+  <: print "quux"; :>
+  quux
+  EOS
+  ...
+
+And finally you can use ePerl directly from within Perl programs by the use of
+the Parse::ePerl(3) package (assuming that you have installed this also; see
+file F<INSTALL> inside the ePerl distribution for more details):
+
+  #!/path/to/perl
+  ...
+  use Parse::ePerl;
+  ...
+  $script = <<EOT;
+  foo
+  <: print "quux"; :>
+  quux
+  EOT
+  ...
+  $result = Parse::ePerl::Expand({
+      Script => $script,
+      Result => \$result,
+  });
+  ...
+  print $result;
+  ...
+
+See Parse::ePerl(3) for more details.
+
+=item I<CGI/1.1 compliant interface mode>
+
+This is the runtime mode where ePerl uses the CGI/1.1 interface of a webserver
+when used as a I<Server-Side Scripting Language> on the Web. ePerl enters this
+mode automatically when the CGI/1.1 environment variable C<PATH_TRANSLATED> is
+set and its or the scripts filename does I<not> begin with the NPH prefix
+``F<nph->''.  In this runtime mode it prefixes the resulting data with
+HTTP/1.0 (default) or HTTP/1.1 (if identified by the webserver) compliant
+response header lines.
+
+ePerl also recognizes HTTP header lines at the beginning of the scripts
+generated data, i.e. for instance you can generate your own HTTP headers like
+
+   <? $url = "..";
+      print "Location: $url\n";
+      print "URI: $url\n\n"; !>
+   <html>
+   ...
+
+But notice that while you can output arbitrary headers, most webservers
+restrict the headers which are accepted via the CGI/1.1 interface. Usually you
+can provide only a few specific HTTP headers like C<Location> or C<Status>.
+If you need more control you have to use the NPH-CGI/1.1 interface mode.
+
+Additionally ePerl provides a useful feature in this mode: It can switch its
+UID/GID to the owner of the script if it runs as a Unix I<SetUID> program (see
+below under L<Security> and the option ``u+s'' of chmod(1)).
+
+There are two commonly known ways of using this CGI/1.1 interface mode on the
+Web. First, you can use it to explicitly transform plain HTML files into
+CGI/1.1 scripts via the I<Shebang> technique (see above). For an Apache
+webserver just put the following line as the first line of the file:
+
+  #!/path/to/eperl -mc
+
+Then rename the script from F<file.html> to F<file.cgi> and set its execution
+bit via
+
+  $ mv file.html file.cgi
+  $ chmod a+rx file.cgi
+
+Now make sure that Apache accepts F<file.cgi> as a CGI program by enabling CGI
+support for the directory where F<file.cgi> resides. For this add the line
+
+  Options +ExecCGI
+
+to the F<.htaccess> file in this directory. Finally make sure that Apache
+really recognizes the extension F<.cgi>. Perhaps you additionally have to add
+the following line to your F<httpd.conf> file:
+
+  AddHandler cgi-script .cgi
+
+Now you can use F<file.cgi> instead of F<file.html> and make advantage of the
+achieved programming capability by bristling F<file.cgi> with your Perl
+blocks (or the transformation into a CGI script would be useless).
+
+Alternatively (or even additionally) a webmaster can enable ePerl support in a
+more seemless way by configuring ePerl as a real implicit server-side
+scripting language. This is done by assigning a MIME-type to the various valid
+ePerl file extensions and forcing all files with this MIME-type to be
+internally processed via the ePerl interpreter. You can accomplish this for
+Apache by adding the following to your F<httpd.conf> file
+
+  AddType      application/x-httpd-eperl  .phtml .eperl .epl
+  Action       application/x-httpd-eperl  /internal/cgi/eperl
+  ScriptAlias  /internal/cgi              /path/to/apache/cgi-bin
+
+and creating a copy of the F<eperl> program in your CGI-directory:
+
+  $ cp -p /path/to/eperl /path/to/apache/cgi-bin/eperl
+
+Now all files with the extensions F<.phtml>, F<.eperl> and F<.epl> are
+automatically processed by the ePerl interpreter. There is no need for a
+I<Shebang> line or any locally enabled CGI mode.
+
+One final hint: When you want to test your scripts offline, just run them with
+forced CGI/1.1 mode from your shell. But make sure you prepare all environment
+variables your script depends on, e.g. C<QUERY_STRING> or C<PATH_INFO>.
+
+  $ export QUERY_STRING="key1=value1&key2=value2"
+  $ eperl -mc file.phtml
+
+
+=item I<NPH-CGI/1.1 compliant interface mode>
+
+This runtime mode is a special variant of the CGI/1.1 interface mode, because
+most webservers (e.g. Apache) provide it for special purposes.   It is known
+as I<Non-Parsed-Header> (NPH) CGI/1.1 mode and is usually used by the
+webserver when the filename of the CGI program is prefixed with ``C<nph->''.
+In this mode the webserver does no processing on the HTTP response headers and
+no buffering of the resulting data, i.e. the CGI program actually has to
+provide a complete HTTP response itself. The advantage is that the program can
+generate arbitrary HTTP headers or MIME-encoded multi-block messages.
+
+So, 
+above we have renamed the file to F<file.cgi> which restricted us a little
+bit. When we alternatively rename F<file.html> to F<nph-file.cgi> and force
+the NPH-CGI/1.1 interface mode via option B<-mn> then this file becomes a
+NPH-CGI/1.1 compliant program under Apache and other webservers. Now our
+script can provide its own HTTP response (it need not, because when absent
+ePerl provides a default one for it).
+
+  #!/path/to/bin/eperl -mn
+  <? print "HTTP/1.0 200 Ok\n";
+     print "X-MyHeader: Foo Bar Quux\n";
+     print "Content-type: text/html\n\n";
+  <html>
+  ...
+
+As you expect this can be also used with the implicit Server-Side Scripting
+Language technique. Put  
+
+  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
+
+into your F<httpd.conf> and run the command
+
+  $ cp -p /path/to/eperl /path/to/apache/cgi-bin/nph-eperl
+
+from your shell. I<This is the preferred way of using ePerl as a Server-Side
+Scripting Language, because it provides most flexibility>.
+
+=back
+
+=head2 Security
+
+When you are installing ePerl as a CGI/1.1 or NPH-CGI/1.1 compliant program
+(see above for detailed description of these modes) via
+
+  $ cp -p /path/to/eperl /path/to/apache/cgi-bin/eperl
+  $ chown root /path/to/apache/cgi-bin/eperl
+  $ chmod u+s  /path/to/apache/cgi-bin/eperl
+
+or
+
+  $ cp -p /path/to/eperl /path/to/apache/cgi-bin/nph-eperl
+  $ chown root /path/to/apache/cgi-bin/nph-eperl
+  $ chmod u+s  /path/to/apache/cgi-bin/nph-eperl
+
+i.e. with I<SetUID> bit enabled for the B<root> user, ePerl can switch to the
+UID/GID of the I<scripts owner>. Although this is a very useful feature for
+script programmers (because one no longer need to make auxiliary files
+world-readable and temporary files world-writable!), it can be to risky for
+you when you are paranoid about security of SetUID programs. If so just don't
+install ePerl with enabled SetUID bit! This is the reason why ePerl is per
+default only installed as a Stand-Alone Unix filter which never needs this
+feature.
+
+For those of us who decided that this feature is essential for them ePerl
+tries really hard to make it secure. The following steps have to be
+successfully passed before ePerl actually switches its UID/GID (in this
+order):
+
+  1. The script has to match the following extensions:
+     .html, .phtml, .ephtml, .epl, .pl, .cgi
+  2. The UID of the calling process has to be a valid UID,
+     i.e. it has to be found in the systems password file
+  3. The UID of the calling process has to match the 
+     following users: root, nobody
+  4. The UID of the script owner has to be a valid UID,
+     i.e. it has to be found in the systems password file
+  5. The GID of the script group has to be a valid GID,
+     i.e. it has to be found in the systems group file
+  6. The script has to stay below or in the owners homedir
+
+I<IF ONLY ONE OF THOSE STEPS FAIL, NO UID/GID SWITCHING TAKES PLACE!>.
+Additionally (if C<DO_ON_FAILED_STEP> was defined as C<STOP_AND_ERROR> in
+F<eperl_security.h> - not per default defined this way!) ePerl can totally stop
+processing and display its error page.  This is for the really paranoid
+webmasters. Per default when any step failed the UID/GID switching is just
+disabled, but ePerl goes on with processing. Alternatively you can disable
+some steps at compile time. See F<eperl_security.h>.
+
+I<Also remember that ePerl always eliminates the effective UID/GID,
+independent of the runtime mode and independent if ePerl has switched to the
+UID/GID of the owner. For security reasons, the effective UID/GID is always
+destroyed before the script is executed.>
+
+=head2 ePerl Preprocessor
+
+ePerl provides an own preprocessor similar to F<CPP> in style which is either
+enabled manually via option B<-P> or automatically when ePerl runs in
+(NPH-)CGI mode.  The following directives are supported:
+
+=over 4
+
+=item C<#include path> 
+
+This directive is an include directive which can be used to include really any
+stuff, but was actually designed to be used to include other ePerl source
+files. The I<path> can be either a relative or absolute path for the local
+filesystem or a fully qualified HTTP URL.
+
+In case of the absolute path the file is directly accessed on the filesystem,
+while the relative path is first searched in the current working directory and
+then in all directories specified via option B<-I>. In the third case
+(HTTP URL) the file is retrieves via a HTTP/1.0 request on the network. 
+Here HTTP redirects (response codes 301 and 302) are supported, too.
+
+Notice: While ePerl strictly preserves the line numbers when translating the
+bristled ePerl format to plain Perl format, the ePerl preprocessor can't do
+this (because its a B<pre>processor which expands) for this directive.  So,
+whenever you use C<#include>, remember that line numbers in error messages are
+wrong.
+
+Also notice one important security aspect: Because you can include any stuff
+as it is provided with this directive, use it only for stuff which is under
+your direct control. Don't use this directive to include foreign data, at
+least not from external webservers. For instance say you have a ePerl page
+with C<#include http://www.foreigner.com/nice-page.html> and at the next
+request of this page your filesystem is lost! Why? Because the foreigner
+recognizes that you include his page and are using ePerl and just put a simple
+``C<E<lt>?  system("rm -rf /"); !E<gt>>'' in his page. Think about it.
+I<NEVER USE #INCLUDE FOR ANY DATA WHICH IS NOT UNDER YOUR OWN CONTROL>.
+Instead always use C<#sinclude> for such situations.
+
+=item C<#sinclude path> 
+
+This is the secure variant of C<#include> where after reading the data from
+I<path> all ePerl begin and end delimiters are removed. So risky ePerl blocks
+lost their meaning and are converted to plain text. Always use this directive
+when you want to include data which is not under your own control.
+
+=item C<#if expr>, C<#elsif expr>, C<#else>, C<#endif>
+
+These implement a CPP-style C<#if-[#else-]#endif> construct, but with a Perl
+semantic. While the other directives are real preprocessor commands which are
+evaluated at the preprocessing step, this construct is actually just
+transformed into a low-level ePerl construct, so it is B<not> actually
+evaluated at the preprocessing step. It is just a handy shortcut for the
+following (where BD is the currently used begin delimiter and ED the end
+delimiter):
+
+  ``#if expr''    ->  ``BD if (expr) { _ ED//''
+  ``#elsif expr'' ->  ``BD } elsif (expr) { _ ED//''
+  ``#else''       ->  ``BD } else { _ ED//''
+  ``#endif''      ->  ``BD } _ ED//''
+
+The advantage of this unusual aproach is that the if-condition really can be
+any valid Perl expression which provides maximum flexibility. The disadvantage
+is that you cannot use the if-construct to make real preprocessing decisions.
+As you can see, the design goal was just to provide a shorthand for the more
+complicated Perl constructs.
+
+=item C<#c>
+
+This is the comment directive which just discards all data up to and including
+the newline character. Use this one to comment out any stuff, even other
+preprocessor directives.
+
+=back
+
+=head2 Provided Functionality
+
+Up to know you've understand that ePerl provides a nice facility to embed Perl
+code into any ASCII data. But now the typical question is: Which Perl code can
+be put into these ePerl blocks and does ePerl provide any special
+functionality inside these ePerl blocks?
+
+The answers are: First, you can put really I<any> Perl code into the ePerl
+blocks which are valid to the Perl interpreter ePerl was linked with. Second,
+ePerl does I<not> provide any special functionality inside these ePerl blocks,
+because Perl is already sophisticated enough ;-)
+
+The implication of this is: Because you can use any valid Perl code you can
+make use of all available Perl 5 modules, even those ones which use shared
+objects (because ePerl I<is> a Perl interpreter, including DynaLoader
+support). So, browse to the Comprehensive Perl Archive Network (CPAN) via
+http://www.perl.com/perl/CPAN and grab your favorite packages which can make
+your life easier (both from within plain Perl scripts I<and> ePerl scripts)
+and just use the construct ``C<use name;>'' in any ePerl block to use them
+from within ePerl. 
+
+When using ePerl as a Server-Side-Scripting-Language I really recommend you to
+install at least the packages F<CGI.pm> (currently vers.  2.36),
+F<HTML-Stream> (1.40), F<libnet> (1.0505) and F<libwww-perl> (5.08).  When you
+want to generate on-the-fly images as well, I recommend you to additionally
+install at least F<GD> (1.14) and F<Image-Size> (2.3). The ePerl interpreter
+in conjunction with these really sophisticated Perl 5 modules will provide you
+with maximum flexibility and functionality. In other words: I<Make use of
+maximum Software Leverage in the hackers world of Perl as great as possible>.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-d> I<name>=I<value>
+
+Sets a Perl variable in the package C<main> which can be referenced
+via C<$name> or more explicitly via C<$main::name>. The command
+
+  eperl -d name=value ..
+  
+is actually equivalent to having
+
+  <? $name = value; !>
+
+at the beginning of I<inputfile>. This option can occur more than once.
+
+=item B<-D> I<name>=I<value>
+
+Sets a environment variable which can be referenced via C<$ENV{'variable'}>
+inside the Perl blocks. The command
+
+  eperl -D name=value ..
+  
+is actually equivalent to 
+
+  export name=value; eperl ...
+
+but the advantage of this option is that it doesn't manipulate the callers
+environment. This option can occur more than once.
+
+=item B<-B> I<begin_delimiter>
+
+Sets the Perl block begin delimiter string. Use this in conjunction with C<-E>
+to set different delimiters when using ePerl as an offline HTML
+creation-language while still using it as an online HTML scripting-language.
+Default delimiters are C<E<lt>?> and C<!E<gt>> for CGI modes and C<E<lt>:> and
+C<:E<gt>> for stand-alone Unix filtering mode.
+
+There are a lot of possible variations you could choose: "C<E<lt>:>" and
+"C<:E<gt>>" (the default ePerl stand-alone filtering mode delimiters),
+"C<E<lt>?>" and "C<!E<gt>>" (the default ePerl CGI interface mode delimiters),
+"C<E<lt>script language='ePerl'E<gt>>" and "C<E<lt>/scriptE<gt>>" (standard
+HTML scripting language style), "C<E<lt>script type="text/eperl"E<gt>>" and
+"C<E<lt>/scriptE<gt>>" (forthcoming HTML3.2+ aka Cougar style),
+"C<E<lt>eperlE<gt>>" and "C<E<lt>/eperlE<gt>>" (HTML-like style),
+"C<E<lt>!--#eperl code='>" and "C<' --E<gt>>" (NeoScript and SSI style) or
+even "C<E<lt>?>" and "C<E<gt>>" (PHP/FI style; but this no longer recommended
+because it can lead to parsing problems. Should be used only for backward
+compatibility to old ePerl versions 1.x).
+
+The begin and end delimiters are searched case-insensitive.
+
+=item B<-E> I<end_delimiter>
+
+Sets the Perl block end delimiter string. See also option B<-B>.
+
+=item B<-i>
+
+Forces the begin and end delimiters to be searched case-insensitive.  Use this
+when you are using delimiters like
+``C<E<lt>ePerlE<gt>>...C<E<lt>/ePerlE<gt>>'' or other more textual ones.
+
+=item B<-m> I<mode>
+
+This forces ePerl to act in a specific runtime mode.  See above for a detailed
+description of the three possible modes: Stand-alone filter (I<mode>=C<f>,
+i.e. option B<-mf>), CGI/1.1 interface mode (I<mode>=C<c>, i.e. option B<-mc>)
+or the NPH-CGI/1.1 interface mode (I<mode>=C<n>, i.e. option B<-mn>).
+
+=item B<-o> I<outputfile>
+
+Forces the output to be written to F<outputfile> instead of F<STDOUT>. Use
+this option when using ePerl as a filter. The outputfile ``F<->'' sets F<STDOUT>
+as the output handle explicitly. Notice that this file is relative to the
+source file directory when the runtime mode is forced to CGI or NPH-CGI.
+
+=item B<-k>
+
+Forces ePerl to keep the current working directory from where it was started.
+Per default ePerl will change to the directory where the file to be executed
+stays. This option is useful if you use ePerl as an offline filter on
+a temporary file.
+
+=item B<-x>
+
+This sets debug mode where ePerl outputs the internally created Perl script to
+the console (F</dev/tty>) before executing it. Only for debugging problems with
+the inputfile conversion.
+
+=item B<-I> I<directory>
+
+Specify a directory which is both used for C<#include> and C<#sinclude>
+directives of the ePerl preprocessor and added to C<@INC> under runtime.  This
+option can occur more than once.
+
+=item B<-P>
+
+Manually enables the special ePerl Preprocessor (see above). This option is
+enabled for all CGI modes automatically.
+
+=item B<-C>
+
+This enables the HTML entity conversion for ePerl blocks. This option is
+automatically forced in CGI modes. 
+
+The solved problem here is the following: When you use ePerl as a
+Server-Side-Scripting-Language for HTML pages and you edit your ePerl source
+files via a HTML editor, the chance is high that your editor translates some
+entered characters to HTML entities, for instance ``C<E<lt>>'' to ``C<&lt;>''.
+This leads to invalid Perl code inside ePerl blocks, because the HTML editor
+has no knowledge about ePerl blocks. Using this option the ePerl parser
+automatically converts all entities found inside ePerl blocks back to plain
+characters, so the Perl interpreter again receives valid code blocks.
+
+=item B<-L>
+
+This enables the line continuation character ``C<\>'' (backslash) outside
+ePerl blocks. With this option you can spread oneline-data over more lines.
+But use with care: This option changes your data (outside ePerl blocks).
+Usually ePerl really pass through all surrounding data as raw data. With this
+option the newlines become new semantics.
+
+=item B<-T>
+
+This enabled Perl's I<Tainting mode> where the Perl interpreter takes special
+precautions called taint checks to prevent both obvious and subtle traps.  See
+perlsec(1) for more details.
+
+=item B<-w>
+
+This enables Warnings where the Perl interpreter produces some lovely
+diagnostics. See perldiag(1) for more details.
+
+=item B<-c>
+
+This runs a pure syntax check which is similar to ``C<perl -c>''.
+
+=item B<-r>
+
+This prints the internal ePerl README file to the console.
+
+=item B<-l>
+
+This prints the internal ePerl LICENSE file to the console.
+
+=item B<-v>
+
+This prints ePerl version information to the console.
+
+=item B<-V>
+
+Same as option B<-v> but additionally shows the Perl compilation parameters.
+
+=back
+
+=head1 ENVIRONMENT
+
+=head2 Used Variables
+
+=over 4
+
+=item C<PATH_TRANSLATED>
+
+This CGI/1.1 variable is used to determine the source file when ePerl operates
+as a NPH-CGI/1.1 program under the environment of a webserver.
+
+=back
+
+=head2 Provided Variables
+
+=over 4
+
+=item C<SCRIPT_SRC_PATH>
+
+The absolute pathname of the script. Use this when you want to
+directly access the script from within itself, for instance to do
+C<stat()> and other calls.
+
+=item C<SCRIPT_SRC_PATH_DIR>
+
+The directory part of C<SCRIPT_SRC_PATH>. Use this one when you want to
+directly access other files residing in the same directory as the script, for
+instance to read config files, etc.
+
+=item C<SCRIPT_SRC_PATH_FILE>
+
+The filename part of C<SCRIPT_SRC_PATH>. Use this one when you need the name
+of the script, for instance for relative self-references through URLs.
+
+=item C<SCRIPT_SRC_URL>
+
+The fully-qualified URL of the script. Use this when you need a URL for
+self-reference.
+
+=item C<SCRIPT_SRC_URL_DIR>
+
+The directory part of C<SCRIPT_SRC_URL>. Use this one when you want to
+directly access other files residing in the same directory as the script via
+the Web, for instance to reference images, etc.
+
+=item C<SCRIPT_SRC_URL_FILE>
+
+The filename part of C<SCRIPT_SRC_URL>. Use this one when you need the name of
+the script, for instance for relative self-references through URLs.  Actually
+the same as C<SCRIPT_SRC_PATH_FILE>, but provided for consistency. 
+
+=item C<SCRIPT_SRC_SIZE>
+
+The filesize of the script, in bytes.
+
+=item C<SCRIPT_SRC_MODIFIED>
+
+The last modification time of the script, in seconds since 0 hours, 0 minutes,
+0 seconds, January 1, 1970, Coordinated Universal Time.
+
+=item C<SCRIPT_SRC_MODIFIED_CTIME>
+
+The last modification time of the script, in ctime(3) format (``WDAY MMM DD
+HH:MM:SS YYYY\n'').
+
+=item C<SCRIPT_SRC_MODIFIED_ISOTIME>
+
+The last modification time of the script, in ISO format (``DD-MM-YYYY
+HH:MM'').
+
+=item C<SCRIPT_SRC_OWNER>
+
+The username of the script owner.
+
+=item C<VERSION_INTERPRETER>
+
+The ePerl identification string.
+
+=item C<VERSION_LANGUAGE>
+
+The identification string of the used Perl interpreter library.
+
+=back
+
+=head2 Provided Built-In Images
+
+The following built-in images can be accessed via URL
+C</url/to/nph-eperl/>I<NAME>C<.gif>:
+
+=over 4
+
+=item C<logo.gif>
+
+The standard ePerl logo. Please do not include this one on your website.
+
+=item C<powered.gif>
+
+The ``I<powered by ePerl 2.2>'' logo. Feel free to use this on your website.
+
+=back
+
+=head1 AUTHOR
+
+  Ralf S. Engelschall
+  rse@engelschall.com
+  www.engelschall.com
+
+=head1 SEEALSO
+
+Parse::ePerl(3), Apache::ePerl(3).
+
+Web-References:
+
+  Perl:   perl(1),  http://www.perl.com/
+  ePerl:  eperl(1), http://www.ossp.org/pkg/tool/eperl/
+  Apache: httpd(8), http://www.apache.org/
+
+=cut
+
+##EOF##