Perl POD由来のmanページでUnicode文字を使用するにはどうすればよいですか？

Question

これができない場合、UTF-8エンコードされたPODから派生したマニュアルページを扱うためのベストプラクティスは何ですか？

PODにはUnicodeを使用するために最初に行うべきことは、（hereを議論したように）指示

=encoding UTF-8 

に使用することです。 pod2textとpod2htmlツールはうまく動作し、完璧なUTF-8エンコード出力を生成します。

pod2manツールは、しかし、しません：

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

どちらperldocを行います。 ASCII以外の文字はすべて文字化けしています。これがpod2manまたは** roff *のバグかどうかについてperlbugにはsome inconclusive discussionがあります。

私のモジュールはユニコードを特に扱い、CPANでの配布を意図しているので、ユニコード対応のマニュアルページは必須です。

私は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 

nroffあなたはのgroffだけでなく（source）に至るまで入力エンコーディング（-K）を通過したときにのみ動作します。オプションの末尾に-スイッチを使用して保護する必要があります。

これはいいですね。ただし、ほとんどのユーザーはドキュメントをインストールした後、man MyModuleまたはperldoc MyModuleと相談してください。 perldocの場合、最新のバージョン（3.16）または-tスイッチを使用することができます。 manの場合

、あなたはただインストールする前に壊れて生成されたドキュメントを修復することができるモジュールをインストールするBuild.PL（モジュール::ビルド）を使用する場合：

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インストーラがマニュアルページを生成するために使用するものです。