Làm cách nào để sử dụng các ký tự Unicode trong các trang người dùng có nguồn gốc từ Perl POD?

Question

Và nếu điều này là không thể, thực hành tốt nhất để xử lý các trang con người có nguồn gốc từ POD được mã hóa UTF-8 là gì?

Điều đầu tiên cần làm để làm việc với Unicode trong POD là sử dụng các chỉ thị

=encoding UTF-8 

(như đã thảo luận here). Các công cụ pod2text và pod2html sẽ hoạt động tốt và tạo ra đầu ra được mã hóa UTF-8 hoàn hảo.

Công cụ pod2man, tuy nhiên, không:

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

Cũng không perldoc. Các ký tự không phải ASCII đều bị xáo trộn hoặc X-ed. Có some inconclusive discussion trên perlbug về việc đây có phải là lỗi trong số pod2man hoặc ** roff *.

Vì mô-đun của tôi giao dịch với Unicode cụ thể và được thiết kế để phân phối trên CPAN, các trang người dùng hỗ trợ Unicode là phải.

Tôi đang sử dụng Perl 5.14.2, perldoc 3.15 và * roff 1.21.

Answer 1

Tất cả perldoc, pod2man, nroff có thể được thực hiện để xử lý Unicode UTF-8 ký tự chính xác. Rất tiếc, các trình cài đặt Perl như Build.PL và chương trình cpan vẫn chưa thể. Vì vậy, trừ khi bạn làm một số fiddling bằng tay trong quá trình cài đặt các trang người đàn ông được cài đặt sẽ bị hỏng.

Những tất cả công việc một cách chính xác cho tôi 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 chỉ hoạt động khi bạn vượt qua mã hóa đầu vào (-K) thông qua để groff cũng (source); bạn phải bảo vệ nó bằng công tắc - kết thúc.

Điều này thật tuyệt. Tuy nhiên, hầu hết người dùng sẽ muốn cài đặt tài liệu và sau đó tham khảo ý kiến ​​với man MyModule hoặc perldoc MyModule. Trong trường hợp của perldoc, các tùy chọn của bạn là sử dụng phiên bản rất gần đây (3.16) hoặc chuyển đổi -t.

Trong trường hợp của man, nếu bạn sử dụng Build.PL (Module :: Xây dựng) để cài đặt một module bạn có thể sửa chữa các tài liệu được tạo ra vỡ ngay trước khi quá trình cài đặt:

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

đáng yêu! Bây giờ bạn có thể xem trang người đàn ông với man MyModule.

Nếu bạn sử dụng cpan để cài đặt mô-đun, trang người đàn ông của bạn sẽ bị hỏng. (Bạn có thể thử cách giải quyết tương tự trên thư mục xây dựng CPAN cục bộ của bạn, ví dụ: ~/.cpan/build, cũng nên hoạt động.)

Answer 2

Bạn đang gặp may! This bug dường như đã được fixed in Pod::Perldoc 3.16. Vì vậy, chỉ cần cập nhật Pod :: Perldoc và một nửa vấn đề được giải quyết.

Tuy nhiên, pod2man xuất phát từ một số different distribution và là một cơ sở mã hoàn toàn khác. Nó vẫn bị hỏng cho UTF-8. Thật không may đó là những gì các trình cài đặt Perl sử dụng để tạo ra các trang người đàn ông.