From: John Napiorkowski Date: Wed, 7 Jan 2015 22:59:21 +0000 (-0600) Subject: more doc tweaks X-Git-Tag: 5.90079_008 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=commitdiff_plain;h=refs%2Ftags%2F5.90079_008 more doc tweaks --- diff --git a/Changes b/Changes index 2e1912a..0a77fa8 100644 --- 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 --- 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 for help in properly nesting applications. + +B 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 --- 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 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 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 allows one to set the response from an external L application. +If you do this, and that external application sets a character set on the content-type, we +C for the rest of the response. This is done to prevent double encoding. + +B 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. + +In general if you want L 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