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

Posted 2023-02-24

【中文标题】如何在 Perl POD 派生的手册页中使用 Unicode 字符？

【英文标题】：How can I use Unicode characters in Perl POD-derived man pages?

【发布时间】：2012-10-15 10:53:52

【问题描述】：

如果这不可能，那么处理源自 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。

【参考方案1】：

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

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

【讨论】：

我没有可用的 perldoc 3.16，但我会相信你的话，谢谢。此外，pod2man 确实有一个 --utf8 开关，它工作得很好。

我仍然遇到 Perl 5.18.2 的 Perlpod 3.19 的问题；不应该修吗？

@U.Windl 看起来像later versions have additional Unicode fixes。与往常一样，尝试升级。 5.18.2 是六岁。您可能还想尝试升级包含 pod2man 的 podlators。

【参考方案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 仅在您将 input 编码 (-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，它也应该可以工作。）