document %header defaults, attributes, and changing

diff --git a/TODO b/TODO
index 1e0dddacd2761f2130a5e1909c37534616da7f80..c29369e51795d46d76c24f93f9e3e35597faca60 100644 (file)
--- a/TODO
+++ b/TODO
@@ -5,5 +5,4 @@ In no particular order or significance:
 - complete plp parsing tests [3.23]
 - redisplay include errors [3.23]
 - object instead of $PLP::
-- document utf8 io
 - update plp.shiar.net, maybe reg plpage.nl or something

diff --git a/lib/PLP/Fields.pm b/lib/PLP/Fields.pm
index 52040e3f3455c082ff63c379a5d4d7235c907b37..27888babee8e2617ef733d4a7c215fb81ecf3175 100644 (file)
--- a/lib/PLP/Fields.pm
+++ b/lib/PLP/Fields.pm
@@ -105,8 +105,18 @@ are B<not> automatically url-decoded.
 
 =item C<%header>, C<%headers>
 
-In this hash, you can set headers. Underscores are converted to normal minus
-signs, so you can leave out quotes. The hash is case insensitive: the case used
+This is a hash of HTTP headers to accompany the first output.
+By default it will contain C<X-PLP-Version> to identify the serving module,
+and C<Content-Type> set to C<text/html>.
+
+If STDOUT has been opened as :utf8,
+a C<charset=utf-8> attribute will automatically be added.
+This will not be possible with FastCGI
+because FCGI (as of version 0.74) does not support output layers.
+
+Headers can be added and/or changed as long as they have not yet been sent.
+Underscores in key names are converted to normal minus signs,
+so you can leave out quotes.  The hash is case insensitive: the case used
 when sending the headers is the one you used first. The following are equal:
 
     $header{CONTENT_TYPE}
@@ -118,6 +128,15 @@ If a value contains newlines, the header is repeated for each line:
 
        $header{Allow} = "HEAD\nGET";  # equivalent to HEAD,GET
 
+For example, to send out a non-HTML text instead of the default HTML:
+
+    <:
+    $header{content_type} = 'text/plain';
+    use open ':std', ':utf8';
+    :>
+    This text should be prefixed by the following header:
+        Content-Type: text/plain; charset=utf-8
+
 =back
 
 =head1 AUTHOR