Declare your Pod encoding

Pod::Simple 3.21 changed its behavior when it encountered a non-ASCII character in Pod without an encoding. Instead of handling it quietly, it now gives a warning. That’s not so bad, but Test::Pod uses Pod::Simple, and whenever it sees a warning, pod_ok fails, as it did in my Mac::Errors module:

#   Failed test 'POD test for blib/lib/Mac/Errors.pm'
#   at .../Test/Pod.pm line 182.
# blib/lib/Mac/Errors.pm (2776): Non-ASCII character seen before =encoding in 'donÍt'. Assuming ISO8859-1
# Looks like you failed 1 test of 2.
t/pod.t ........... 
Dubious, test returned 1 (wstat 256, 0x100)
Failed 1/2 subtests 

Unfortunately, the Pod tests are the sort that shouldn’t stop an installation, which is why many developers have a separate area for author tests (which I’ll cover in an upcoming Item). Outside of that, you have to fix the Pod.

There are two things here. First, I have a genuine error here. The module is auto generated from other source files and the “donÍt” is a mistake; it should be “don’t” (with a smart quote) or even better, “don’t”. Test::Pod didn’t catch this before. So, that’s not bad.

More importantly, telling Perl that the source code is UTF-8 isn’t enough. When you use the utf8 pragma, the perl interpreter reads the source as UTF-8:

use utf8;

However, a Pod parser ignores all the code. It looks for Pod sections and never sees that pragma, nor does it care. You have to tell the pod which encoding you have if you want to use something outside of ASCII:

=encoding utf8

I hadn’t used that in Mac::Errors, or any of my other modules, although in some of them I had used genuine UTF-8 sequences. Now any person using Test::Pod with the latest Pod::Simple won’t be able to install those modules normally. That is, until I fix them.

I could use other encodings, such as ISO-8859-1, as long as I declare the right thing and save the file correctly.

Things to remember

• The utf8 pragma doesn’t affect the Pod
• Pod::Simple assumes ASCII unless you tell it otherwise
• Declare your Pod encoding with the =encoding directive