How can I use Unicode characters in Perl POD-derived man pages?

风格不统一 提交于 2019-11-30 03:41:20

问题


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

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

=encoding UTF-8

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

The pod2man tool, however, does not:

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

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

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

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


回答1:


You're in luck! This bug appears to have been fixed in Pod::Perldoc 3.16. So just update Pod::Perldoc and half the problem is solved.

However, pod2man comes from a different distribution and is a wholly different code base. It is still broken for UTF-8. Unfortunately it's what the Perl installers use to generate man pages.




回答2:


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.

These all work correctly for my 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 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.

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.

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

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

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



来源:https://stackoverflow.com/questions/13065495/how-can-i-use-unicode-characters-in-perl-pod-derived-man-pages

易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!