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.
-
Are you posting in the right place? Check out Where do I post X? to know for sure.
-
Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
<code> <a> <b> <big>
<blockquote> <br /> <dd>
<dl> <dt> <em> <font>
<h1> <h2> <h3> <h4>
<h5> <h6> <hr /> <i>
<li> <nbsp> <ol> <p>
<small> <strike> <strong>
<sub> <sup> <table>
<td> <th> <tr> <tt>
<u> <ul>
-
Snippets of code should be wrapped in
<code> tags not
<pre> tags. In fact, <pre>
tags should generally be avoided. If they must
be used, extreme care should be
taken to ensure that their contents do not
have long lines (<70 chars), in order to prevent
horizontal scrolling (and possible janitor
intervention).
-
Want more info? How to link
or How to display code and escape characters
are good places to start.
|