Question

如果无法做到这一点，那么处理源自UTF-8编码的POD的手册页的最佳做法是什么？

要在POD中使用Unicode，首先要做的是使用指令

=encoding UTF-8

（如here所述）。 pod2text和pod2html工具可以正常工作，并生成完美的UTF-8编码输出。

pod2man工具不会：

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

perldoc也没有。非ASCII字符都被破坏或X-ed输出。 perlbug上some inconclusive discussion是否可能是pod2man或** roff *中的错误。

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

我使用的是Perl 5.14.2，perldoc 3.15和* roff 1.21。

Answer 1

你很幸运！ This bug似乎是fixed in Pod::Perldoc 3.16。所以只需更新Pod :: Perldoc，问题就解决了一半。

然而，pod2man来自different distribution并且是完全不同的代码库。它仍然被UTF-8打破。不幸的是，这是Perl安装程序用来生成手册页的内容。

Answer 2

可以使perldoc，pod2man，nroff全部正确处理Unicode UTF-8字符。不幸的是，诸如Build.PL和 cpan 程序之类的Perl安装程序还不能。因此，除非您在安装过程中手动进行一些摆弄，否则已安装的手册页将被破坏。

这些都适用于我的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仅在将输入编码（-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，这也应该有效。）

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

2 个答案: