document caveats for quoting functions; fix documentation indenting/wrapping.

diff --git a/PLP.pm b/PLP.pm
index 57292ad2589d0760f3b1aa84668eb22c66b0c6ec..a5936fd9d00f22cf4da44f1ad2eecdd298224819 100644 (file)
--- a/PLP.pm
+++ b/PLP.pm
@@ -24,7 +24,7 @@ our $VERSION = '3.18';
 #  everything                       Do everything: CGI
 #  handler($r)                      Do everything: mod_perl
 #  mod_perl_init($r)                Initialization for mod_perl
-#  mod_perl_print                  Faster printing for mod_perl
+#  mod_perl_print                   Faster printing for mod_perl
 #  sendheaders                      Send headers
 #  source($path, $level, $linespec) Read and parse .plp files
 #  start                            Start the initialized PLP script
@@ -354,7 +354,7 @@ PLP - Perl in HTML pages
         SetHandler perl-script
         PerlHandler PLP
         PerlSendHeader On
-       PerlSetVar PLPcache On
+        PerlSetVar PLPcache On
     </Files>
 
     # Who said CGI was easier to set up? :)
@@ -375,10 +375,10 @@ PLP - Perl in HTML pages
 
     ScriptAlias /foo/bar/ /PLP_COMMON/
     <Directory /foo/bar/>
-       AllowOverride None
-       Options +ExecCGI
-       Order allow,deny
-       Allow from all
+        AllowOverride None
+        Options +ExecCGI
+        Order allow,deny
+        Allow from all
     </Directory>
     AddHandler plp-document plp
     Action plp-document /PLP_COMMON/plp.cgi

diff --git a/PLP/FAQ.pod b/PLP/FAQ.pod
index 91965cb6ac6859b35bf874c31cb5b46cdb094f21..7496f54157658595246b9ade68ed515fe939fa1c 100644 (file)
--- a/PLP/FAQ.pod
+++ b/PLP/FAQ.pod
@@ -8,7 +8,8 @@ PLP::FAQ - Frequently Asked Questions about PLP
 
 =item What does PLP stand for?
 
-PerlPage. The name used to be HTMPL, but HyperText Markup with Perl Language was too long.
+PerlPage. The name used to be HTMPL, but HyperText Markup with Perl Language
+was too long.
 
 =item Is PLP hard to install?
 
@@ -48,17 +49,17 @@ design, you can add a little more speed.
 
 =item Can I use Perl's CGI module with PLP?
 
-You certainly can! If you do not want %get and %post and the like, just not use
-them. They will be generated on first access, so if you never access them, the
-hashes are never filled.
+You certainly can! If you do not want %get and %post and the like, just don't
+use them. They will be generated on first access, so if you never access them,
+the hashes are never filled.
 
 If you want to use CGI.pm's header functions, C<select STDOUT;> first, to break
 out of PLP's tied C<PLPOUT> filehandle.
 
 =item Why does C<< <($filename)> >> not work?
 
-C<< <(...)> >> is a compile-time tag, opposed to C<include()>, which is evaluated at
-run-time. At compile time, variables are not yet known, and PLP will try to
+C<< <(...)> >> is a compile-time tag, opposed to C<include()>, which is evaluated
+at run-time. At compile time, variables are not yet known, and PLP will try to
 include a file literally called C<$filename>.
 
     <: $filename = 'foo.inc.plp'; include($filename); :>

diff --git a/PLP/Functions.pm b/PLP/Functions.pm
index 3a0f0023c103c178b4777b1cbb3311b103403a0f..ef5b311070ec6c35744169a9cd9cf79160144f91 100644 (file)
--- a/PLP/Functions.pm
+++ b/PLP/Functions.pm
@@ -253,17 +253,26 @@ In void context, B<changes> the values of the given variables. In other contexts
 
     <: print Entity($user_input); :>
 
+Be warned that this function also HTMLizes consecutive whitespace and newlines (using &nbsp; and <br> respectively).
+For simple escaping, use L<XML::Quote>. To escape high-bit characters as well, use L<HTML::Entities>.
+
 =item EncodeURI LIST
 
-Replaces characters by their %-encoded values.
+Encodes URI strings according to RFC 3986. All disallowed characters are replaced by their %-encoded values.
 
 In void context, B<changes> the values of the given variables. In other contexts, returns the changed versions.
 
     <a href="/foo.plp?name=<:= EncodeURI($name) :>">Link</a>
 
+Note that the following reserved characters are I<not> percent-encoded, even though they may have a special meaning in URIs:
+
+       / ? : @ $
+
+This should be safe for escaping query values (as in the example above), but it may be a better idea to use L<URI::Escape> instead.
+
 =item DecodeURI LIST
 
-Decodes %-encoded strings.
+Decodes %-encoded strings. Unlike L<URI::Escape>, it also translates + characters to spaces (as browsers use those).
 
 In void context, B<changes> the values of the given variables. In other contexts, returns the changed versions.