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.

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

• imenu-add-menubar-index or adding new panes ("windows") is often reversed by a timer trigger in your code forcing a redraw. That's kind of a PITA. (Not sure if this is related to some Emacs28 strangeness.)

Feature requests

• Via a side-bar (like speedbar) I'd like to display imenu's index for navigation. info has this.
• displaying the POD of the actual buffer would be nice
• context-menu and Top-bar entry for mode, alike info or wo/man-mode

Nice to Haves

• syntax-highlighting of code-sections in the POD using the cperl-mode logic
• mouse-over tool-tips like in cperl-mode
• option to open in external browser
• completion/expansion when searching a pod

HTH!!! :)

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).

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.

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}

No not necessarily, you can make perl build the nroff in a buffer and tell woman to render it

Here a minimal solution (I'm still an amateur with elisp)

to try:

• paste the function into *scratch*
• type C-x C-e behind the last bracket to eval it

• copy this code to your .emacs config
• create a keybinding if needed

• M-x perldoc-woman will ask for the Pod's name
• typing "Moose" + <RET> will display Moose

(defun perldoc-woman (target)
     "perldoc displayed via woman"
   (interactive "sPod: ")
   (let* (
         (buffer-name (concat "*perldoc-" target "*"))
         (perl-cmd
               (concat "perldoc -MPod::Man " target))
         )

     (require 'woman)
     (switch-to-buffer (get-buffer-create buffer-name))
     (erase-buffer)
     (shell-command perl-cmd 1)
     (woman-process-buffer)

     (list buffer-name perl-cmd) ;dbg
     )
   )
[download]

Caveat: navigation to other PODs like referenced Modules by clicking/return doesn't work yet, I'm ignorant about a way to hook into woman for that.

Agreed, man pages (nroff pages) can be built on-the-fly in the same way as I'm doing it with HTML right now. But then - it's still nroff. If I have to choose between nroff and HTML, then I'd say HTML is the way to go for structured documentation.

> then I'd say HTML is the way to go for structured documentation.

Could you please elaborate?

woman seems to render much faster than html.

POD was primarily designed for man, and the L<...> link format has it's ambiguities AFAIR.

I'd say HTML is the way to go if you supported more advanced features, like external links, embedded pics or special formatters in =for ... drectives. But those are sparsely used.

Of course if you decided to support an external document server like Pod::POM::Web , man wouldn't be an option.

Any other points I missed?

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

Bravo!

(... later more! :)