Jak mogę używać znaków Unicode na stronach podręcznika podręcznika Perla POD?

Question

A jeśli nie jest to możliwe, jaka jest najlepsza praktyka postępowania ze stronami man pochodzącymi z POD zakodowanego w UTF-8?

Pierwszą rzeczą, którą należy zrobić, aby pracować z Unicode w POD jest użyć dyrektywy

=encoding UTF-8 

(omówione here). Narzędzia o numerach pod2text i pod2html będą działać bez zarzutu i będą zapewniać doskonałe wyniki kodowane w formacie UTF-8.

Narzędzie pod2man jednak nie:

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

ani nie perldoc. Znaki spoza ASCII są zmanipulowane lub X-out. Na perlbugu znajduje się some inconclusive discussion, czy może to być błąd w pod2man lub ** roff *.

Ponieważ mój moduł dotyczy w szczególności Unicode i jest przeznaczony do dystrybucji na CPAN, strony podręcznika z obsługą Unicode są koniecznością.

Używam Perl 5.14.2, perldoc 3.15 i * roff 1.21.

Answer 1

Wszystkie znaki perldoc, pod2man, nroff mogą być używane do poprawnego obsługi znaków Unicode UTF-8. Niestety instalatory Perla, takie jak Build.PL i program cpan, nie mogą jeszcze. Więc jeśli nie wykonasz jakiegoś manipulowania ręcznego podczas instalacji, zainstalowane strony podręcznika man zostaną zerwane.

To wszystko działa poprawnie z moim 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 działa tylko wtedy, gdy przechodzą kodowanie wejściowy (-K) aż do groffa jak również (source); musisz go zabezpieczyć przełącznikiem końca opcji -.

To jest miłe. Jednak większość użytkowników będzie chciała zainstalować dokumentację, a następnie skonsultować ją z man MyModule lub perldoc MyModule. W przypadku perldoc, masz do wyboru albo najnowszą wersję (3.16) albo przełącznik -t.

W przypadku man, jeśli używasz build.pl (moduł :: kompilacji), aby zainstalować moduł można naprawić złamane wygenerowane dokumenty tuż przed instalacją:

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

piękny! Teraz możesz wyświetlić stronę podręcznika pod numerem man MyModule.

Jeśli użyjesz cpan do zainstalowania modułu, twoje strony podręcznika będą zepsute. (Możesz wypróbować to samo obejście w lokalnym katalogu budowania CPAN, np. ~/.cpan/build, który również powinien działać).

Answer 2

Masz szczęście! This bug wydaje się być fixed in Pod::Perldoc 3.16. Po prostu zaktualizuj Pod :: Perldoc, a połowa problemu zostanie rozwiązana.

Jednak pod2man pochodzi z different distribution i jest całkowicie inną bazą kodu. Nadal jest zepsuty dla UTF-8. Niestety to właśnie instalatory Perla używają do generowania stron man.