如何在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 (

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屋！