From da455137a47490d44e10258c1b875c63e0b34b2d Mon Sep 17 00:00:00 2001 From: Shiar Date: Wed, 30 Apr 2008 07:00:45 +0200 Subject: [PATCH] seperate/rewritten README file Plain text README should be a minimal introductionary basics: intro (first paragraph of pod description), installation, help, copyright. Leave the pod (and only that) to be the full manual. All users should be able to run perldoc, without being held off by some wannabe text conversion. --- README | 181 +++++++-------------------------------------------------- 1 file changed, 20 insertions(+), 161 deletions(-) diff --git a/README b/README index deb8daf..17e11ff 100644 --- a/README +++ b/README @@ -1,176 +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 mod_perl for speeds comparable to those of PHP, but can also be +run as a 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. An - alternative way of setting headers is using Perl's BEGIN blocks. BEGIN - blocks are executed as soon as possible, before anything else. - - 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 and HowTo - A lot of questions are asked often, so before asking yours, please read - the FAQ at PLP::FAQ. Some examples can be found at PLP::HowTo. +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, PLP::HowTo +This software is free software; you can redistribute and/or modify it +under the terms of the MIT/X11 license (see COPYING). -- 2.30.0