Wie kann ich Unicode-Zeichen in Perl POD-abgeleiteten Manpages verwenden?

Question

Und wenn dies nicht möglich ist, was ist die beste Vorgehensweise für den Umgang mit man-Seiten aus UTF-8-codierten POD abgeleitet?

Das erste, was zu tun, um mit Unicode in POD zu arbeiten, ist die Richtlinie verwenden

=encoding UTF-8 

(als here diskutiert). Die Werkzeuge pod2text und pod2html funktionieren einwandfrei und erzeugen eine perfekte UTF-8-kodierte Ausgabe. jedoch

Das pod2man Werkzeug, tut, nicht:

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

Genauso wenig wie perldoc. Nicht-ASCII-Zeichen sind alle fehlerhaft oder X-out. Es gibt some inconclusive discussion auf Perlbug auf, ob dies ein Fehler in pod2man oder ** Roff * sein könnte.

Da mein Modul speziell mit Unicode arbeitet und für die Verteilung auf CPAN gedacht ist, sind Unicode-fähige Manpages ein Muss.

Ich benutze Perl 5.14.2, perldoc 3.15 und * roff 1.21.

Answer 1

Alle perldoc, pod2man, nroff können gemacht werden, um Unicode UTF-8 Zeichen richtig zu behandeln. Leider können die Perl-Installer wie Build.PL und das cpan Programm noch nicht. Wenn Sie also während der Installation nicht mit der Hand fiedeln, werden die installierten Manpages beschädigt.

Diese arbeiten alle richtig für meine 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 funktioniert nur, wenn Sie die Eingang Codierung (-K) bis hin zu groff sowie (source) passieren; Sie müssen es mit dem Ende der Optionen - Schalter schützen.

Das ist nett. Die meisten Benutzer werden jedoch die Dokumentation installieren und später mit man MyModule oder perldoc MyModule konsultieren. Im Fall von perldoc können Sie entweder eine sehr aktuelle Version (3.16) oder den Schalter -t verwenden.

Im Fall man, wenn Sie Build.PL verwenden (Modul :: Build), ein Modul zu installieren, die Sie kurz vor der Installation der gebrochenen erzeugten Dokumente reparieren können:

perl Build.PL 
./Build 
# now overwrite the broken man pages: 
pod2man -u -s 3pm lib/MyModule.pm blib/libdoc/MyModule.3pm 
./Build install 

Lovely! Jetzt können Sie die Manpage mit man MyModule anzeigen.

Wenn Sie cpan verwenden, um das Modul zu installieren, werden Ihre Manpages beschädigt. (Sie können die gleiche Problemumgehung in Ihrem lokalen CPAN-Build-Verzeichnis versuchen, zB ~/.cpan/build, das auch funktionieren sollte.)

Answer 2

Sie haben Glück! This bug scheint fixed in Pod::Perldoc 3.16 gewesen zu sein. Also einfach update Pod :: Perldoc und das halbe Problem ist gelöst.

Allerdings kommt pod2man von einem different distribution und ist eine völlig andere Code-Basis. Es ist immer noch für UTF-8 gebrochen. Leider verwenden die Perl-Installer Manpages.