From 971a58801d2a08b72045268bb416ce624971774c Mon Sep 17 00:00:00 2001
From: Mischa POSLAWSKY <perl@shiar.org>
Date: Wed, 22 Feb 2012 22:20:50 +0100
Subject: [PATCH] document %header defaults, attributes, and changing

---
 TODO              |  1 -
 lib/PLP/Fields.pm | 23 +++++++++++++++++++++--
 2 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/TODO b/TODO
index 1e0ddda..c29369e 100644
--- 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 52040e3..27888ba 100644
--- 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
-- 
2.30.0