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

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输出。关于这可能是pod2man中的错误还是**roff*中的错误，perlbug上有some inconclusive discussion。

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

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

Answer 1

所有的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

只有当您将输入编码(-K)传递给groff (source)时，nroff才有效；您必须使用选项末尾-开关来保护它。

这个真不错。但是，大多数用户都希望安装文档，并在以后使用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，它也应该可以工作。)

Answer 2

你走运了！This bug看起来是fixed in Pod::Perldoc 3.16了。因此，只需更新Pod::Perldoc，问题就解决了一半。

但是，pod2man来自different distribution，是一个完全不同的代码库。对于UTF-8，它仍然是不可用的。不幸的是，Perl安装程序使用它来生成手册页。