X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=blobdiff_plain;f=lib%2FCatalyst%2FUTF8.pod;h=dcb66873df5336a6cae82643878ba0a2fa500d2e;hp=d48def59017d8e68e032b775550c9f2b6cb6b736;hb=refs%2Ftags%2F5.90079_008;hpb=51b34249806efbb5eb2572baf32ebaf619840d17

diff --git a/lib/Catalyst/UTF8.pod b/lib/Catalyst/UTF8.pod
index d48def5..dcb6687 100644
--- a/lib/Catalyst/UTF8.pod
+++ b/lib/Catalyst/UTF8.pod
@@ -372,8 +372,11 @@ This will use the alternative encoding for a single response.
 
 B<NOTE> If you manually set the content-type character set to whatever $c->encoding->mime_name
 is set to, we STILL encode, rather than assume your manual setting is a flag to override.  This
-is done to support backward compatible assumptions.  If you are going to handle encoding
-manually you may set $c->clear_encoding for a single request response cycle.
+is done to support backward compatible assumptions (in particular L<Catalyst::View::TT> has set
+a utf-8 character set in its default content-type for ages, even though it does not itself do any
+encoding on the body response).  If you are going to handle encoding manually you may set
+$c->clear_encoding for a single request response cycle, or as in the above example set an alternative
+encoding.
 
 =head2 Encoding with streaming type responses
 
@@ -529,6 +532,24 @@ We tried to make sure most common views worked properly and noted all workaround
 missed something please alert the development team (instead of introducing a local hack into
 your application that will mean nobody will ever upgrade it...).
 
+=head2 Setting the response from an external PSGI application.
+
+L<Catalyst::Response> allows one to set the response from an external L<PSGI> application.
+If you do this, and that external application sets a character set on the content-type, we
+C<clear_encoding> for the rest of the response.  This is done to prevent double encoding.
+
+B<NOTE> Even if the character set of the content type is the same as the encoding set in
+$c->encoding, we still skip encoding.  This is a regrettable difference from the general rule
+outlined above, where if the current character set is the same as the current encoding, we
+encode anyway.  Nevertheless I think this is the correct behavior since the earlier rule exists
+only to support backward compatibility with L<Catalyst::View::TT>.
+
+In general if you want L<Catalyst> to handle encoding, you should avoid setting the content
+type character set since Catalyst will do so automatically based on the requested response
+encoding.  Its best to request alternative encodings by setting $c->encoding and if you  really
+want manual control of encoding you should always $c->clear_encoding so that programmers that
+come after you are very clear as to your intentions.
+
 =head2 Disabling default UTF8 encoding
 
 You may encounter issues with your legacy code running under default UTF8 body encoding.  If