Beefy Boxes and Bandwidth Generously Provided by pair Networks
Do you know where your variables are?

Reading Perl documentation in Emacs

by haj (Priest)
on Aug 08, 2022 at 17:53 UTC ( #11146029=perlmeditation: print w/replies, xml ) Need Help??

These days I came round to package an Emacs command which I am using since some time now: <M-x> perl-doc. It is a viewer for POD in Emacs, and it has been accepted in GNU ELPA, so it can be installed with <M-x> package-install.

But why? There are already plenty of ways to read POD. They work (sort of), but I was not totally happy with any of them:
  • The perldoc command in a shell is nice. It knows what I've installed in my Perl, and I can add own projects to its search path by adding to PERL5LIB. It is not so useful with documents like the Moose::Manual which contain many cross-references.
  • Pod::Webserver is a nice way to get the same information in your browser. But it needs you to run two extra programs and does not provide an equivalent of perldoc -f split.
  • Pod::Perldoc::ToTk is supposed to display POD in a GUI, but the command in the synopsis perldoc -o tk Some::Modulename & fails with Undefined subroutine &Pod::Perldoc::ToTk::MainLoop called. I have Tk::Pod and Pod::Perldoc installed and don't want to chase that error.
  • Emacs has <M-x>cperl-perldoc which per default tries to get information for the thing where your cursor is, and displays the document in another window. But internally it uses man which isn't available on Windows, and until now I was too lazy to install any of the replacements (man for Windows, or woman.el. Also, it needs man pages installed, so I need to build those when I want to read documentation from sources I'm working on.
  • Emacs::PodMode (available via CPAN, not ELPA) is targeted for writing POD, it shows all the markup.
  • The Perl menu in CPerl mode still refers to Perl documentation in info format, which is no longer shipped with Perl and never was available for CPAN modules. Eventually these items should be deleted from the menu.
  • Edited to add (2022-08-09): In the meantime I found perl-pod-preview.el which also provides a man formatted view of POD. I like the fact that it works on (unsaved) buffers and might add a similar feature to perl-doc.el.

So, trying to combine the good parts, <M-x>perl-doc defaults to the thing where the cursor is, respects PERL5LIB to find your POD (also accepts file names), does not need extra programs and has a decent formatting which allows to follow links between your documents.

Replies are listed 'Best First'.
Re: Reading Perl documentation in Emacs [Pod::Perldoc::ToTk error]
by kcott (Archbishop) on Aug 09, 2022 at 02:18 UTC

    G'day haj,

    I've never used Pod::Perldoc::ToTk and don't see myself rushing to use it now.

    From the error you reported, Undefined subroutine &Pod::Perldoc::ToTk::MainLoop called, I guessed at the problem and suspect that I'm probably right about that.

    Looking at the source, line 1 has "package Pod::Perldoc::ToTk;" and line 113 has "MainLoop();" — I'm reasonably certain that should be "Tk::MainLoop();".

    I don't have the time at the moment to follow that up, run tests, write a patch, write additional t/whatever.t tests, and so on; however, if you or someone else wanted to look into this, I'd say that's the place to start.

    — Ken

Re: Reading Perl documentation in Emacs
by LanX (Sage) on Aug 09, 2022 at 11:20 UTC

Log In?

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perlmeditation [id://11146029]
Front-paged by Corion
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others avoiding work at the Monastery: (6)
As of 2022-12-08 00:32 GMT
Find Nodes?
    Voting Booth?

    No recent polls found