more doc tweaks

diff --git a/Changes b/Changes
index 2e1912a..0a77fa8 100644 (file)
--- a/Changes
+++ b/Changes
@@ -3,7 +3,7 @@
 5.90079_008  - 2015-01-07
   - If we get a response set from $res->from_psgi_response and that response
     has a charset for the content type, we clear encoding for the rest of the
-    response (avoid double encoding).
+    response (avoid double encoding).  Added more documentation around this.
   - Documentation updates and typo fixes across various UTF8 docs (Mark Ellis++)
 
 5.90079_007  - 2015-01-07

diff --git a/lib/Catalyst/Response.pm b/lib/Catalyst/Response.pm
index a3580ff..6143f25 100644 (file)
--- a/lib/Catalyst/Response.pm
+++ b/lib/Catalyst/Response.pm
@@ -551,7 +551,13 @@ Example:
     }
 
 Please note this does not attempt to map or nest your PSGI application under
-the Controller and Action namespace or path.  
+the Controller and Action namespace or path. You may wish to review 'PSGI Helpers'
+under L<Catalyst::Utils> for help in properly nesting applications.
+
+B<NOTE> If your external PSGI application returns a response that has a character
+set associated with the content type (such as "text/html; charset=UTF-8") we set
+$c->clear_encoding to remove any additional content type encoding processing later
+in the application (this is done to avoid double encoding issues).
 
 =head2 encodable_content_type
 

diff --git a/lib/Catalyst/UTF8.pod b/lib/Catalyst/UTF8.pod
index d48def5..dcb6687 100644 (file)
--- 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