X-Git-Url: http://git.shiar.nl/gitweb.cgi/perl/plp/.git/blobdiff_plain/0daff7b8f9f15f54cfd2af57e4c8f868db199dda..refs/tags/3.22_02:/README?ds=inline
diff --git a/README b/README
index 10ff4f0..0f057eb 100644
--- a/README
+++ b/README
@@ -1,173 +1,35 @@
-NAME
- PLP - Perl in HTML pages
+PLP - PERL IN HTML PAGES
-MODULE INSTALLATION
+PLP is yet another Perl embedder, primarily for HTML documents. Unlike
+with other Perl embedders, there is no need to learn a meta-syntax or
+object model: one can just use the normal Perl constructs. PLP runs
+under FastCGI and mod_perl for speeds comparable to those of PHP, but
+can also be run as a standard CGI script.
+
+INSTALLATION
+
+To install this module, run the following commands:
perl Makefile.PL
make
+ make test
make install
-SYNOPSIS
- mod_perl installation
- * httpd.conf (for mod_perl setup)
-
- SetHandler perl-script
- PerlHandler PLP
- PerlSendHeader On
- PerlSetVar PLPcache On
-
-
- # Who said CGI was easier to set up? :)
-
- CGI installation
- * /foo/bar/plp.cgi (local filesystem address)
- #!/usr/bin/perl
- use PLP;
- PLP::everything();
-
- * httpd.conf (for CGI setup)
- ScriptAlias /foo/bar/ /PLP_COMMON/
-
- AllowOverride None
- Options +ExecCGI
- Order allow,deny
- Allow from all
-
- AddHandler plp-document plp
- Action plp-document /PLP_COMMON/plp.cgi
-
- Test script (test.plp)
-
- <:
- print "Hurrah, it works!
" for 1..10;
- :>
-
-
-DESCRIPTION
- PLP is yet another Perl embedder, primarily for HTML documents. Unlike
- with other Perl embedders, there is no need to learn a meta-syntax or
- object model: one can just use the normal Perl constructs. PLP runs
- under mod_perl for speeds comparable to those of PHP, but can also be
- run as a CGI script.
-
- PLP Syntax
- "<: perl_code(); :>" With "<:" and ":>", you can add Perl code to your
- document. This is what PLP is all about. All code
- outside of these tags is printed. It is possible
- to mix perl language constructs with normal HTML
- parts of the document:
-
- <: unless ($ENV{REMOTE_USER}) { :>
- You are not logged in.
- <: } :>
-
- ":>" always stops a code block, even when it is
- found in a string literal.
-
- "<:= $expression :>" Includes a dynamic expression in your document.
- The expression is evaluated in list context.
- Please note that the expression should not end a
- statement: avoid semi-colons. No whitespace may be
- between "<:" and the equal sign.
-
- "foo <:= $bar :> $baz" is like "<: print 'foo ',
- $bar, ' baz'; :>".
-
- "<(filename)>" Includes another file before the PLP code is
- executed. The file is included literally, so it
- shares lexical variables. Because this is a
- compile-time tag, it's fast, but you can't use a
- variable as the filename. You can create recursive
- includes, so beware! (PLP will catch simple
- recursion: the maximum depth is 128.) Whitespace
- in the filename is not ignored so "<( foo.txt)>"
- includes the file named " foo.txt", including the
- space in its name. A compile-time alternative is
- include(), which is described in PLP::Functions.
-
- PLP Functions
- These are described in PLP::Functions.
-
- PLP Variables
- $ENV{PLP_NAME} The URI of the PLP document, without the query
- string. (Example: "/foo.plp")
-
- $ENV{PLP_FILENAME} The filename of the PLP document. (Example:
- "/var/www/index.plp")
-
- $PLP::VERSION The version of PLP.
-
- $PLP::DEBUG Controls debugging output, and should be treated
- as a bitmask. The least significant bit (1)
- controls if run-time error messages are reported
- to the browser, the second bit (2) controls if
- headers are sent twice, so they get displayed in
- the browser. A value of 3 means both features are
- enabled. The default value is 1.
-
- $PLP::ERROR Contains a reference to the code that is used to
- report run-time errors. You can override this to
- have it in your own design, and you could even
- make it report errors by e-mail. The sub reference
- gets two arguments: the error message as plain
- text and the error message with special characters
- encoded with HTML entities.
-
- %header, %cookie, %get, %post, %fields
- These are described in PLP::Fields.
-
- (mod_perl only) PerlSetVar configuration directives
- PLPcache Sets caching On/Off. When caching, PLP saves your
- script in memory and doesn't re-read and re-parse
- it if it hasn't changed. PLP will use more memory,
- but will also run 50% faster.
-
- On is default, anything that isn't =~ /^off$/i is
- considered On.
-
- Things that you should know about
- Not only syntax is important, you should also be aware of some other
- important features. Your script runs inside the package "PLP::Script"
- and shouldn't leave it. This is because when your script ends, all
- global variables in the "PLP::Script" package are destroyed, which is
- very important if you run under mod_perl (they would retain their values
- if they weren't explicitly destroyed).
-
- Until your first output, you are printing to a tied filehandle "PLPOUT".
- On first output, headers are sent to the browser and "STDOUT" is
- selected for efficiency. To set headers, you must assign to $header{
- $header_name} before any output. This means the opening "<:" have to be
- the first characters in your document, without any whitespace in front
- of them. If you start output and try to set headers later, an error
- message will appear telling you on which line your output started.
-
- Because the interpreter that mod_perl uses never ends, "END { }" blocks
- won't work properly. You should use "PLP_END { };" instead. Note that
- this is a not a built-in construct, so it needs proper termination with
- a semi-colon (as do and ).
+SUPPORT AND DOCUMENTATION
- Under mod_perl, modules are loaded only once. A good modular design can
- improve performance because of this, but you will have to reload the
- modules yourself when there are newer versions.
+After installing, documentation will be installed as manual pages:
- The special hashes are tied hashes and do not always behave the way you
- expect, especially when mixed with modules that expect normal CGI
- environments, like CGI.pm. Read PLP::Fields for information more about
- this.
+ man PLP
-FAQ
- A lot of questions are asked often, so before asking yours, please read
- the FAQ at PLP::FAQ.
+It can also be found at CPAN:
-NO WARRANTY
- No warranty, no guarantees. Use PLP at your own risk, as I disclaim all
- responsibility.
+ http://search.cpan.org/dist/PLP
-AUTHORS
- Currently maintained by Mischa POSLAWSKY
+COPYRIGHT
- Originally by Juerd Waalboer
+Copyright (c) 2000-2002 Juerd Waalboer, 2005-2008 Mischa POSLAWSKY.
+All rights reserved.
-SEE ALSO
- PLP::Functions, PLP::Fields, PLP::FAQ
+This software is free software; you can redistribute and/or modify it
+under the terms of the MIT/X11 license (see COPYING).