Merge branch 'colin/encoding_doc' of https://github.com/colinnewell/catalyst-runtime...

diff --combined lib/Catalyst.pm
index 7a1bb65,3906260..f07b269
--- 1/lib/Catalyst.pm
--- 2/lib/Catalyst.pm
+++ b/lib/Catalyst.pm
@@@ -475,7 -475,7 +475,7 @@@ or stash it like so
  
  and access it from the stash.
  
 -Keep in mind that the C<end> method used is that of the caller action. So a C<$c-E<gt>detach> inside a forwarded action would run the C<end> method from the original action requested.
 +Keep in mind that the C<end> method used is that of the caller action. So a C<< $c->detach >> inside a forwarded action would run the C<end> method from the original action requested.
  
  =cut
  
@@@ -2322,6 -2322,10 +2322,10 @@@ sub finalize_encoding 
        (defined($res->body)) and
        (ref(\$res->body) eq 'SCALAR')
      ) {
+         # if you are finding yourself here and your body is already encoded correctly
+         # and you want to turn this off, use $c->clear_encoding to prevent encoding
+         # at this step, or set encoding to undef in the config to do so for the whole
+         # application.  See the ENCODING documentaiton for better notes.
          $c->res->body( $c->encoding->encode( $c->res->body, $c->_encode_check ) );
  
          # Set the charset if necessary.  This might be a bit bonkers since encodable response
@@@ -4765,6 -4769,11 +4769,11 @@@ the encoding configuration to undef
  
  This is recommended for temporary backwards compatibility only.
  
+ To turn it off for a single request use the L<clear_encoding>
+ method to turn off encoding for this request.  This can be useful
+ when you are setting the body to be an arbitrary block of bytes,
+ especially if that block happens to be a block of UTF8 text.
+ 
  Encoding is automatically applied when the content-type is set to
  a type that can be encoded.  Currently we encode when the content type
  matches the following regular expression:
@@@ -4887,7 -4896,7 +4896,7 @@@ andrewalker: André Walker <andre@cpan.
  
  Andrew Bramble
  
 -Andrew Ford E<lt>A.Ford@ford-mason.co.ukE<gt>
 +Andrew Ford <A.Ford@ford-mason.co.uk>
  
  Andrew Ruthven
  
@@@ -4911,7 -4920,7 +4920,7 @@@ Danijel Milicevic C<me@danijel.de
  
  davewood: David Schmidt <davewood@cpan.org>
  
 -David Kamholz E<lt>dkamholz@cpan.orgE<gt>
 +David Kamholz <dkamholz@cpan.org>
  
  David Naughton, C<naughton@umn.edu>