From c425b50ff4140d6e6d9556fd1e4c380def5fc3e0 Mon Sep 17 00:00:00 2001
From: Mischa POSLAWSKY <perl@shiar.org>
Date: Sat, 31 Mar 2007 02:52:19 +0200
Subject: [PATCH] document caveats for quoting functions; fix documentation
 indenting/wrapping.

---
 PLP.pm           | 12 ++++++------
 PLP/FAQ.pod      | 13 +++++++------
 PLP/Functions.pm | 13 +++++++++++--
 3 files changed, 24 insertions(+), 14 deletions(-)

diff --git a/PLP.pm b/PLP.pm
index 57292ad..a5936fd 100644
--- 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 91965cb..7496f54 100644
--- 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 3a0f002..ef5b311 100644
--- 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.
 
-- 
2.30.0