How do I use Unicode characters in Pod and perldoc?

Question

I need to use utf-8 characters in my perl-documentation. If I use:

perldoc MyMod.pm

I see strange characters. If I use:

pod2text MyMod.pm

everything is fine.

I use Ubuntu/Debian.

$ locale
LANG=de_DE.UTF-8
LC_CTYPE="de_DE.UTF-8"
LC_NUMERIC="de_DE.UTF-8"
LC_TIME="de_DE.UTF-8"
LC_COLLATE="de_DE.UTF-8"
LC_MONETARY="de_DE.UTF-8"
LC_MESSAGES="de_DE.UTF-8"
LC_PAPER="de_DE.UTF-8"
LC_NAME="de_DE.UTF-8"
LC_ADDRESS="de_DE.UTF-8"
LC_TELEPHONE="de_DE.UTF-8"
LC_MEASUREMENT="de_DE.UTF-8"
LC_IDENTIFICATION="de_DE.UTF-8"
LC_ALL=de_DE.UTF-8

Is there a HowTo about using special characters in Pod?

Here is a small example using german umlauts "Just a Test: äöüßÄÖ":

$ perldoc perl/MyMod.pm
<standard input>:72: warning: can't find character with input code 159
<standard input>:72: warning: can't find character with input code 150
MyMod(3)              User Contributed Perl Documentation             MyMod(3)

NAME
        MyMod.pm - Just a Test: äöüÃÃÃ

perl v5.10.0                      2008-10-16                          MyMod(3)

Answer 1

Use =encoding utf-8 as the first POD directive in your file, and use a fairly recent perldoc (for example from 5.10-maint). Then it should work.

Answer 2

Found this RT ticket.... http://rt.cpan.org/Public/Bug/Display.html?id=39000

This "bug" seems to be introduced with Perl 5.10 and perhaps this pod2man --utf8 needs to be used.

Answer 3

perldoc -t MyMod.pm

From the perldoc manual:

-t Display pod using pod2text instead of Pod::Man and groff (-t is the default on win32 unless -n is specified)