in reply to Reading Perl documentation in Emacs

Thanks for the Lightning Talk at GPW 2023. ++

Here the promised feedback, I'll try to keep it short. ;-)

Installation

Fetching from ELPA worked, (but installation failed on my old Emacs24 with a "version 27" requirement, like I've messaged you)

Installation on combination Emacs 28 / Windows/ Strawberry Perl was flawless.

I like the fact that it's a separate package from the huge cperl-mode.

Typing <M-x> perl-doc <RET> Moose <RET> showed me Moose in an extra buffer.

It also has heuristics to show the perldoc -f or -v if asked for function/var name (tho I hope you are aware of ambiguities like open )

Impression

The display is accurate. Code section (i.e. indented POD) is shown in an extra mono-spaced font.

Clicking on links let's me navigate to other jump-marks and new POD pages of other modules in a second buffer.

There is a noticeable short lag because every new POD means starting perdoc in the background

Using imenu to jump to internal headings/jump-marks (like SYNOPSIS ) is also possible.

I like the fact that dabbrev-expand is also automatically parsing the new buffer, i.e. when trying to expand a new method-name/sub-name in my code-buffer it will try to take advantage of the opened POD. ( one of the reasons why I prefer this over a separate browser)

I like the fact that one can navigate the POD now, i.e. to jump from one link to the next and reminds me in that way a bit of Pod::POM::Web or info mode inside emacs.

There is also the command perl-doc-view-source to see the original code generating the POD, very nice.

Bugs

Feature requests

Nice to Haves

HTH!!! :)

Cheers Rolf
(addicted to the 𐍀𐌴𐍂𐌻 Programming Language :)
Wikisyntax for the Monastery

Replies are listed 'Best First'.
Re^2: Reading Perl documentation in Emacs
by haj (Vicar) on Aug 05, 2023 at 21:20 UTC

    Some time has passed, and I've found some time to work in that stuff again. I haven't covered all of the points above, but at least some of them:

    • The redraw doesn't happen so often, and if it happens, it doesn't kill the imenu-add-menubar-index.
    • Speedbar now works for perl-doc mode.
    • Searching for a module name in perl-doc now offers completion.

    Version 0.81 will hit GNU ELPA within one or two days (wait for that, 0.8 has some nasty bugs).

    I have prepared a short article about the news (using some markup not available on PerlMonks).

[reply]
Re^2: Reading Perl documentation in Emacs
by haj (Vicar) on Mar 11, 2023 at 21:53 UTC

    Thanks for that feedback! I was sort of expecting that other users would try things I didn't even think of :)

    A few remarks:

    • The "redraw" bug: I have yet to find out why perl-doc-mode gets redraw notifications in some cases (other than e.g. resizing a window), but it didn't occur to me that redrawing loses the menubar index. I guess I can fix that.
    • speedbar support: Makes sense for "long" documents. Needs a bit of work, though.
    • Displaying the POD of the actual buffer: That's on my todo list, in particular display of an unsaved buffer. If the buffer is a saved file, than <M-x> perl-doc-file <RET> <RET> should do the trick (another known bug under Emacs 29: the "home" directory ~ isn't correctly expanded in that case). If you change the POD source, then save and hit g in the POD view to get an updated view.
    • Context menu / top menu: I hadn't thought about this because the mode doesn't have many features to go into a menu, but it makes sense.
    • Syntax highlighting of code sections: Ah, recursion alert! The code sections might contain POD... Just kidding. The verbatim blocks (that's how POD calls these sections) aren't necessarily Perl code, but in most cases they are. I'm waiting a bit with this one because Emacs 29 with its tree-sitter capabilities explicitly supports "embedded" blocks with different highlighting... and doing it before that's available might be too much effort.
    • Mouse-over tool tips: What tips should go there? POD doesn't provide much meta-information to use.
    • Option to open in external browser: I guess that's possible with some limitations (a browser doesn't know how to process a link to another POD file).
    • Completion/expansion when searching a POD: I must admit that I found completion for module names too slow to be actually useful - but that's probably because I have lots of CPAN stuff installed.
[reply]
      Using WoMan on Linux actually already showed me plenty of Perl pods, I think those were installed via apt for system perl and automatically converted to .3pm files. And tab completion is supported and fast, it's parsing and caching all man paths.

      FWIW, I looked into the code of woman-mode and I think it's possible to patch it to have a perlman-mode.

      But I have to delay that project till after the current ones.

      > Mouse-over tool tips

      cperl-toggle-autohelp (you need to set the timer too) - I combined it with tooltip.el to show a popup.

      > The "redraw" bug:

      I think it's a bug in 27 and 28, WoMan was only able to set the imenu-index if I set it at startup.

      the redraw bug is also effecting window-management, it will also split again to two POD windows even after I disabled it.

      > speedbar support:

      looking into the code of ECB might help, they have imenu to speedbar support

      > Syntax highlighting of code sections:

      Syntax-Highlighting is tricky in dynamic buffers which are actively edited. But POD is static.

      You might want to have a look into how org-mode is doing it for code section.

      polymode.el sounds promising too, but I wasn't able to see a working example.

      Cheers Rolf
      (addicted to the 𐍀𐌴𐍂𐌻 Programming Language :)
      Wikisyntax for the Monastery

[reply]
[d/l]

In Section Meditations