Merge branch 'encoding-warnings' into expect-chars

lib/Pod/Simple.pod

@@ -14,6 +14,8 @@ documentation") markup language that is typically used for writing
 documentation for Perl and for Perl modules. The Pod format is explained
 L<perlpod>; the most common formatter is called C<perldoc>.
 
+Be sure to read L</ENCODING> if your Pod contains non-ASCII characters.
+
 Pod formatters can use Pod::Simple to parse Pod documents and render them into
 plain text, HTML, or any number of other formats. Typically, such formatters
 will be subclasses of Pod::Simple, and so they will inherit its methods, like
@@ -322,6 +324,17 @@ Log an error unless C<< $parser->no_whining( TRUE ); >>.
 
 =back
 
+=head1 ENCODING
+
+The Pod::Simple parser expects to read B<octets>.  The parser will decode the
+octets into Perl's internal character string representation using the value of
+the C<=encoding> declaration in the POD source.
+
+If the POD source does not include an C<=encoding> declaration, the parser will
+attempt to guess the encoding (selecting one of UTF-8 or Latin-1) by examining
+the first non-ASCII bytes and applying the heuristic described in
+L<perlpodspec>.
+
 =head1 CAVEATS
 
 This is just a beta release -- there are a good number of things still

lib/Pod/Simple/TranscodeSmart.pm

@@ -32,7 +32,7 @@ sub make_transcoder {
   my $x;
   return sub {
     foreach $x (@_) {
-      $x = Encode::decode($e, $x);
+      $x = Encode::decode($e, $x) unless Encode::is_utf8($x);
     }
     return;
   };