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

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.

/I3az/

Answer 2

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 3

I can't make perldoc work with the "=encoding utf-8" directive. As with maletin's original question, pod2text works just fine, but perldoc does not. Do I need to hunt for a newer version of perldoc? Mine is the one distributed with ActiveState 5.10.1 (see perldoc -V below).

15:10:26 $ cat test.pl
=encoding utf-8

=head1 UNICODE CHARACTERS

These are less-than-or-equals characters: '≤', 'E<le>', 'E<0x2264>'.
15:10:31 $ pod2text test.pl
UNICODE CHARACTERS
    These are less-than-or-equals characters: '≤', '≤', '≤'.

15:10:36 $ perldoc test.pl | cat
TEST(1)               User Contributed Perl Documentation              TEST(1)



UNICODE CHARACTERS
       These are less‐than‐or‐equals characters: ’X’, ’X’, ’X’.



perl v5.10.1                      2009‐09‐08                           TEST(1)
15:10:41 $ perldoc -V
Perldoc v3.15, under perl v5.010001 for darwin
15:10:45 $