How can I use Unicode characters in Perl POD-derived man pages?

You're in luck! This bug appears to have been fixed in Pod::Perldoc 3.16. So just update Pod::Perldoc and half the problem is solved.

However, pod2man comes from a different distribution and is a wholly different code base. It is still broken for UTF-8. Unfortunately it's what the Perl installers use to generate man pages.

All of perldoc, pod2man, nroff can be made to handle Unicode UTF-8 characters correctly. Unfortunately the Perl installers such as Build.PL and the cpan program can't yet. So unless you do some fiddling by hand during the installation the installed man pages will be broken.

These all work correctly for my minimal example:

perldoc lib/MyModule.pm        # works as of 3.16 (@Schwern)
perldoc -t lib/MyModule.pm     # display with pod2text
pod2man -u lib/MyModule.pm     # produces UTF-8 man page
pod2man -u lib/MyModule.pm | nroff -Tutf8 -man - -Kutf8 | less

nroff only works when you pass the input encoding (-K) through to groff as well (source); you have to protect it with the end-of-options - switch.

This is nice. However, most users will want to install the documentation and later consult it with man MyModule or perldoc MyModule. In the case of perldoc, your options are to either use a very recent version (3.16) or the -t switch.

In the case of man, if you use Build.PL (Module::Build) to install a module you can repair the broken generated docs just before the installation:

perl Build.PL
./Build
# now overwrite the broken man pages:
pod2man -u -s 3pm lib/MyModule.pm blib/libdoc/MyModule.3pm
./Build install

Lovely! Now you can view the man page with man MyModule.

If you use cpan to install the module your man pages will be broken. (You can try the same workaround on your local CPAN build directory, eg. ~/.cpan/build, which should also work.)