What's new in perl-doc

Speedbar Display

Speedbar is an Emacs feature "which can be used to summarize information related to the current buffer" (that's a quote from the Speedbar manual). On the right is how it looks for the Perl module which implements File::Temp (click for larger view).

The narrow frame on the left shows the contents of the directory where that file is located, and can expand a a table of contents for the file (an imenu) if the major mode supports it.

In perl-doc-mode, the directory isn't all that relevant: Modules starting with File:: can be located in several different directories. So, instead of directories, perl-doc-mode offers to show all modules in the File:: namespace. In my installation there are nine files in the directory /usr/share/perl/5.34/File, but as the next picture shows, I have 26 File:: modules, plus a couple of subdirectories!

The image shows the formatted view for the module File::Temp in perl-doc style. Opening speedbar from a buffer in perl-doc mode automatically switches the display to perl-doc view. The expanded display takes quite a lot of space, therefore the initial display only shows the module hierarchy for the module you are reading (and for other modules you've been reading in the same session).

The view in this image is from Emacs 27. As of Emacs 28, each module also has a "+" sign in its icon. Clicking it expands the imenu index for the module documentation. The gallery has an image of Emacs 28 on Windows, showing the expanded table if contents for File::Temp.

Hovering with the mouse over a module name shows the file path which will be used to display the documentation (and the code by using the "v" key in perl-doc mode).

New or Improved Commands

perl-doc-function

Like perl-doc, but only provides documentation for functions from the perlfunc page. This provides a convenient way for disambiguation between the pragma (module) open and the Perl function open.

perl-doc-variable

Displays a section from the perlvar page for the variable given. Not very useful since the sigil of Perl variables is sufficient to tell them apart from modules, so a simple perl-doc should do the trick.

perl-doc-browser

Starts a speedbar in perl-doc view without needing a buffer in perl-doc mode. perl-doc view will stay active until manually switched off from the speedbar context menu or until the command perl-doc-browser-quit (bound to "q" in the speedbar frame) is given.

perl-doc-add-lib

Add an existing directory to be searched for Perl modules, for this session only. This is the equivalent of customizing perl-doc-extra-libs (see below) for the current session, but offers completion for the directory name.

perl-doc-refresh-libs

Clears the directory cache of the perl-doc browser. This is needed if you already visited a namespace in perl-doc view and then added a new directory.

perl-doc

This command now offers completion for module names according to your installation and a history.

New customization options

perl-doc-perl-program

The path to the Perl executable. This is used to find the built-in directories in @INC, needed for completion of module names.

perl-doc-extra-libs

A list of directories to be searched for Perl documentation in addition to those built-in and those in the environment variable PERL5LIB.

Fixed Bugs

• A page refresh no longer kills the imenu index in menubar.
• Refreshing doesn't happen as often as it did anyway.

Limitations and Todos

• The error handling is poor. If perl-doc does not find a POD, then it does not distinguish between a file which has no POD or ... a file which doesn't exist. The latter can happen if you follow a link to a module which you have not installed. perl-doc might offer to look on CPAN in that case.
• A completion of module names might also come handy in cperl-mode.