Come posso utilizzare i caratteri Unicode nelle pagine man derivate da Perl POD?

Question

E se ciò non è possibile, qual è la migliore pratica per trattare pagine man derivate da POD con codifica UTF-8?

La prima cosa da fare per lavorare con Unicode in POD è quello di utilizzare la direttiva

=encoding UTF-8 

(come discusso here). Gli strumenti pod2text e funzioneranno correttamente e produrranno un output con codifica UTF-8 perfetta.

Lo strumento pod2man, tuttavia, non:

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

Nemmeno perldoc. I caratteri non ASCII sono tutti storpiati o tagliati fuori. C'è some inconclusive discussion su perlbug su se questo potrebbe essere un bug in pod2man o ** roff *.

Poiché il mio modulo si occupa specificamente di Unicode ed è destinato alla distribuzione su CPAN, le pagine man con Unicode sono un must.

Sto usando Perl 5.14.2, perldoc 3.15 e * roff 1.21.

Answer 1

Tutti perldoc, pod2man, nroff possono essere gestiti per gestire correttamente i caratteri Unicode UTF-8. Sfortunatamente gli installer Perl come Build.PL e il cpan programma non possono ancora. Quindi, a meno che non si agiti a mano durante l'installazione, le pagine man installate verranno interrotte.

Questi tutti i lavori in modo corretto per il mio 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 funziona solo quando si passa il ingresso codifica (-K) fino a groff così (source); devi proteggerlo con lo switch di fine opzione -.

Questo è bello. Tuttavia, la maggior parte degli utenti vorranno installare la documentazione e in seguito consultarla con man MyModule o perldoc MyModule. Nel caso di perldoc, è possibile utilizzare una versione molto recente (3.16) o lo switch -t.

Nel caso di man, se si utilizza Build.PL (Modulo :: build) per l'installazione di un modulo è possibile riparare i documenti generati rotto poco prima dell'installazione:

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

Lovely! Ora puoi visualizzare la pagina man con man MyModule.

Se si utilizza cpan per installare il modulo, le pagine man verranno interrotte. (Puoi provare la stessa soluzione sulla tua directory di build CPAN locale, ad esempio ~/.cpan/build, che dovrebbe anche funzionare.)

Answer 2

Sei fortunato! This bug sembra essere stato fixed in Pod::Perldoc 3.16. Quindi aggiorna Pod :: Perldoc e metà del problema è risolto.

Tuttavia, pod2man proviene da un different distribution ed è una base di codice completamente diversa. È ancora rotto per UTF-8. Sfortunatamente è ciò che gli installatori Perl usano per generare pagine man.