如何在Perl POD派生的手册页中使用Unicode字符？

Question

如果这是不可能的,处理从UTF-8编码的POD派生的手册页的最佳做法是什么？

要在POD中使用Unicode,要做的第一件事就是使用该指令

=encoding UTF-8

(如所讨论此处).该pod2text和pod2html工具将正常工作,并产生完美的UTF-8编码输出.

pod2man但是,该工具不会:

pod2man -u MyModule.pm | nroff -Tutf8 -man | less

也没有perldoc.非ASCII字符都被破坏或X-ed输出.关于perlbug是否可能是一个错误或**roff*,有一些不确定的讨论pod2man.

由于我的模块专门处理Unicode并且打算在CPAN上进行分发,因此必须使用支持Unicode的手册页.

我使用的是Perl 5.14.2,perldoc 3.15和*roff 1.21.

Answer 1

所有perldoc, pod2man,nroff都可以正确处理 Unicode UTF-8 字符。不幸的是，Perl 安装程序（例如 Build.PL 和cpan程序）还不能。因此，除非您在安装过程中手动进行一些修改，否则安装的手册页将会被破坏。

对于我的最小示例来说，这些都可以正常工作：

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仅当您将输入编码 ( -K) 传递给groff时才有效 ( source )；您必须使用选项结束-开关来保护它。

这很好。但是，大多数用户希望安装该文档，然后使用man MyModule或进行查阅perldoc MyModule。在 的情况下perldoc，您的选择是使用最新版本 (3.16) 或切换-t。

在这种情况下man，如果您使用 Build.PL (Module::Build) 安装模块，您可以在安装之前修复损坏的生成文档：

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

迷人的！现在您可以使用 查看手册页man MyModule。

如果您使用cpan安装模块，您的手册页将被破坏。（您可以在本地 CPAN 构建目录上尝试相同的解决方法，例如~/.cpan/build，这也应该有效。）