如何在 Perl POD 派生的手册页中使用 Unicode 字符? [英] How can I use Unicode characters in Perl POD-derived man pages?

问题描述

如果这不可能，那么处理源自 UTF-8 编码 POD 的手册页的最佳做法是什么?

And if this isn't possible, what is the best practice for dealing with man pages derived from UTF-8-encoded POD?

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

The first thing to do in order to work with Unicode in POD is to use the directive

=encoding UTF-8

(如 此处所述).pod2text 和 pod2html 工具可以正常工作并产生完美的 UTF-8 编码输出.

(as discussed here). The pod2text and pod2html tools will work fine and produce perfect UTF-8-encoded output.

pod2man 工具却没有:

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

perldoc 也没有.非 ASCII 字符全部被损坏或 X-ed.关于 perlbug 关于是否这可能是 pod2man 或 **roff* 中的错误.

Neither does perldoc. Non-ASCII characters are all mangled or X-ed out. There is some inconclusive discussion on perlbug on whether this might be a bug in pod2man or **roff*.

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

Since my module deals with Unicode specifically and is intended for distribution on CPAN, Unicode-enabled man pages are a must.

我正在使用 Perl 5.14.2、perldoc 3.15 和 *roff 1.21.

I am using Perl 5.14.2, perldoc 3.15, and *roff 1.21.

推荐答案

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

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.

这些都适用于我的最小示例:

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 时才有效(来源);您必须使用 end-of-options - 开关来保护它.

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.

这很好.但是，大多数用户都希望安装文档，然后使用 man MyModule 或 perldoc MyModule 进行查阅.对于 perldoc，您可以选择使用最新版本 (3.16) 或 -t 开关.

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.

对于man，如果您使用Build.PL (Module::Build) 安装模块，您可以在安装前修复损坏的生成文档:

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

可爱！现在您可以使用 man MyModule 查看手册页.

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

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

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.)

这篇关于如何在 Perl POD 派生的手册页中使用 Unicode 字符?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！