[ELPA] New package: perl-doc

[ELPA] New package: perl-doc

[Harald Jörg]

Hello developers,

This is not yet a new ELPA package, but a proposal to create one.

the motivation to write this library came from two sources: In a Perl
online meeting an Emacs user noted that the usual function to read Perl
documentation in Emacs, cperl-perldoc, does not work on Platforms which
don't have 'man' (notably, Windows).  My own observation is that 'man'
(and also 'info') seem to be stuck at a fixed page width which is
particularly annoying if you want to use *less* than this width for a
documentation frame.

This is a copy from the file's header:

----------------------------------------------------------------------
Perl documentation is written in a markup format called POD ("Plain
Old Documentation") and is usually converted to other formats for
human consumption.  The documentation used to be available in Emacs
for a long time in 'info' or 'man' format.  However, Perl does no
longer ship 'info' files, and the software available from CPAN
never did.  'man' is not available on all platforms and allows only
rather restricted formatting, most notably linking between
documents does not work.

On the other hand, Perl provides a converter from POD to HTML.
HTML is well supported by Emacs and is well suited for presentation
of structured documents.

The user visible benefits over the other formats are:

 * Works nicely on platforms which do not have man

 * Unlike with 'man', Hyperlinks between POD documents work and
  resolve to POD documentation on your system, no web server
  required.

 * Makes use of Emacs faces: variable-pitch font for text,
   fixed-pitch for code, italics for, well, italics

 * Uses the buffer's full width and can also be used with
   narrow buffers

TODO list

 * Documentation on Perl variables is yet to be implemented.

 * The regex mechanism in `perl-doc--process-links` is a hack.  The
   author wrote this before he learned about rx and always meant to
   rewrite it in rx notation, but well, tuits.
----------------------------------------------------------------------

I would like to distribute the software under either GNU ELPA nor NonGNU
ELPA.  It works equally well with perl-mode.el and cperl-mode.el, and
functional enhancements can be triggered by new Perl features as well as
new Emacs features.

The current repository is at https://github.com/HaraldJoerg/emacs-perl-doc,

This is my first attempt to write a package: I am ready to move it
elsewhere, to provide the required metadata, as well as fix format and
style error as deemed appropriate by style guides and the Emacs
community.

Feedback is very welcome!
-- 
Cheers,
haj

Re: [ELPA] New package: perl-doc

[Akib Azmain Turja]

[-- Attachment #1: Type: text/plain, Size: 666 bytes --]

Harald Jörg <haj@posteo.de> writes:

> don't have 'man' (notably, Windows).  My own observation is that 'man'
> (and also 'info') seem to be stuck at a fixed page width which is
> particularly annoying if you want to use *less* than this width for a
> documentation frame.

Set "Man-width" to the width of documentation frame.  I don't know how
to do it Info, however there is a user option "Info-refill-paragraphs".
Any suggestion from Info hackers?

-- 
Akib Azmain Turja

Find me on Mastodon at @akib@hostux.social.

This message is signed by me with my GnuPG key.  It's fingerprint is:

    7001 8CE5 819F 17A3 BBA6  66AF E74F 0EFA 922A E7F5

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: [ELPA] New package: perl-doc

[Harald Jörg]

Akib Azmain Turja <akib@disroot.org> writes:

> Harald Jörg <haj@posteo.de> writes:
>
>> don't have 'man' (notably, Windows).  My own observation is that 'man'
>> (and also 'info') seem to be stuck at a fixed page width which is
>> particularly annoying if you want to use *less* than this width for a
>> documentation frame.
>
> Set "Man-width" to the width of documentation frame.  I don't know how
> to do it Info, however there is a user option "Info-refill-paragraphs".
> Any suggestion from Info hackers?

Ah, excellent.  Again and again I learn that it is wrong to say "Emacs
doesn't do X" but instead I should ask "How do I do X in Emacs"?
I also hadn't even noticed that man actually reformats the page when the
width changes.  I have failed to find a hook for a change of window
width, but man.el simply uses an idle timer to check for changes.  I'll
adopt that in my code.

-- 
Many Thanks!
haj

Re: [ELPA] New package: perl-doc

[Robert Pluim]

>>>>> On Wed, 27 Jul 2022 17:59:53 +0000, Harald Jörg <haj@posteo.de> said:

    Harald> I have failed to find a hook for a change of window
    Harald> width, but man.el simply uses an idle timer to check for changes.  I'll
    Harald> adopt that in my code.

It sounds like you want a buffer-local `window-size-change-functions' in
combination with `window-old-body-pixel-width'.

Robert
-- 

Re: [ELPA] New package: perl-doc

[Harald Jörg]

Robert Pluim writes:

>>>>>> On Wed, 27 Jul 2022 17:59:53 +0000, Harald Jörg <haj@posteo.de> said:
>
>     Harald> I have failed to find a hook for a change of window
>     Harald> width, but man.el simply uses an idle timer to check for changes.  I'll
>     Harald> adopt that in my code.
>
> It sounds like you want a buffer-local `window-size-change-functions' in
> combination with `window-old-body-pixel-width'.

Correct: I want exactly that!

In the meantime I had discovered window-state-change-functions (used in
man.el) which is not quite as good.  In my defense, I was smart enough
to write that I failed to find it instead of claiming that such a hook
does not exist :)

Many thanks!

-- 
Cheers,
haj

Re: [ELPA] New package: perl-doc

[Robert Pluim]

>>>>> On Thu, 28 Jul 2022 09:22:51 +0000, Harald Jörg <haj@posteo.de> said:

    Harald> Robert Pluim writes:
    >> It sounds like you want a buffer-local `window-size-change-functions' in
    >> combination with `window-old-body-pixel-width'.

    Harald> Correct: I want exactly that!

    Harald> In the meantime I had discovered window-state-change-functions (used in
    Harald> man.el) which is not quite as good.  In my defense, I was smart enough
    Harald> to write that I failed to find it instead of claiming that such a hook
    Harald> does not exist :)

Theyʼre both described in the same info node in the elisp manual:
(info "(elisp) Window Hooks"))

How did you find one without finding the other?

Robert
-- 

Re: [ELPA] New package: perl-doc

[Harald Jörg]

Robert Pluim writes:

>>>>>> On Thu, 28 Jul 2022 09:22:51 +0000, Harald Jörg <haj@posteo.de> said:
> [...]
>     Harald> In the meantime I had discovered window-state-change-functions (used in
>     Harald> man.el) which is not quite as good.  In my defense, I was smart enough
>     Harald> to write that I failed to find it instead of claiming that such a hook
>     Harald> does not exist :)
>
> Theyʼre both described in the same info node in the elisp manual:
> (info "(elisp) Window Hooks"))
>
> How did you find one without finding the other?

I found it being used in man.el.  That was *yesterday*.  I haven't
looked it up in the info pages before your mail hit me.

I also recall that I had investigated (info "(elisp) Standard Hooks") in
the past, but apparently I gave up before reaching the very last entry
of that page.  My bad.  I guess I got distracted and followed some
other link on that page....

Probably I'll continue to miss things Emacs can do for the next decade
or two, but eventually I plan to catch up :)
-- 
Cheers,
haj

Re: [ELPA] New package: perl-doc

[Robert Pluim]

>>>>> On Thu, 28 Jul 2022 12:17:20 +0000, Harald Jörg <haj@posteo.de> said:

    Harald> Probably I'll continue to miss things Emacs can do for the next decade
    Harald> or two, but eventually I plan to catch up :)

Weʼve all been saying that for decades ☺️

Robert
-- 

Re: [ELPA] New package: perl-doc

[Juri Linkov]

>>     Harald> I have failed to find a hook for a change of window
>>     Harald> width, but man.el simply uses an idle timer to check for changes.  I'll
>>     Harald> adopt that in my code.
>>
>> It sounds like you want a buffer-local `window-size-change-functions' in
>> combination with `window-old-body-pixel-width'.
>
> Correct: I want exactly that!
>
> In the meantime I had discovered window-state-change-functions (used in
> man.el) which is not quite as good.

Why do you think it's not quite good?  It's called when the window
is resized too.

Re: [ELPA] New package: perl-doc

[Harald Jörg]

Juri Linkov <juri@linkov.net> writes:

>>>     Harald> I have failed to find a hook for a change of window
>>>     Harald> width, but man.el simply uses an idle timer to check for changes.  I'll
>>>     Harald> adopt that in my code.
>>>
>>> It sounds like you want a buffer-local `window-size-change-functions' in
>>> combination with `window-old-body-pixel-width'.
>>
>> Correct: I want exactly that!
>>
>> In the meantime I had discovered window-state-change-functions (used in
>> man.el) which is not quite as good.
>
> Why do you think it's not quite good?  It's called when the window
> is resized too.

I should clarify: Using window-state-change-functions works fine!

I meant it is not quite as good as window-size-change-functions because
a function in windows-state-change-functions is also called in
situations where I don't need it to be called (e.g. after a M-x
other-window command, or when the window loses focus).  So it is a small
improvement to use window-size-change-functions.
-- 
Cheers,
haj

Re: [ELPA] New package: perl-doc

[Gregor Zattler]

Hi Harald, Akib, 
* Harald Jörg <haj@posteo.de> [2022-07-27; 17:59]:
> Akib Azmain Turja <akib@disroot.org> writes:
>> Set "Man-width" to the width of documentation frame.  I don't know how
>> to do it Info, however there is a user option "Info-refill-paragraphs".
>> Any suggestion from Info hackers?
>
> Ah, excellent.  Again and again I learn that it is wrong to say "Emacs
> doesn't do X" but instead I should ask "How do I do X in
> Emacs"?

I used to setq Info-refill-paragraphs to t, but as the
documentation says, "this only has an effect if
Info-hide-note-references is non-nil" and then one should
"be prepared for a few surprises if you enable this
feature".

For me the refilling of info was not worth these surprises.
And nowadays my display is wide enough anyway.

Ciao; Gregor 

Re: [ELPA] New package: perl-doc

[Akib Azmain Turja]

[-- Attachment #1: Type: text/plain, Size: 1834 bytes --]

Gregor Zattler <telegraph@gmx.net> writes:

> Hi Harald, Akib, 
> * Harald Jörg <haj@posteo.de> [2022-07-27; 17:59]:
>> Akib Azmain Turja <akib@disroot.org> writes:
>>> Set "Man-width" to the width of documentation frame.  I don't know how
>>> to do it Info, however there is a user option "Info-refill-paragraphs".
>>> Any suggestion from Info hackers?

I just found how to do this, just set "Info-refill-paragraphs" and
"Info-hide-note-references" to non-nil and set "fill-column" to the
desired text width.

>>
>> Ah, excellent.  Again and again I learn that it is wrong to say "Emacs
>> doesn't do X" but instead I should ask "How do I do X in
>> Emacs"?
>
> I used to setq Info-refill-paragraphs to t, but as the
> documentation says, "this only has an effect if
> Info-hide-note-references is non-nil"

That's non-nil by default.

> and then one should
> "be prepared for a few surprises if you enable this
> feature".

Yeah, sometimes you'll be surprised seeing a few too long or too short
lines, but these aren't so big problems IMHO.

>
> For me the refilling of info was not worth these surprises.
> And nowadays my display is wide enough anyway.

Yeah, now almost all computers have a wide enough display.  But that
doesn't mean that someone will use the full display for a single task.
For example, I often have a Info window on the right side of my display
when I new try something new, and I want it to be as small as possible
while still allowing me to read text on that window without scrolling,
to give me more space for writing and other tasks.

>
> Ciao; Gregor 
>

-- 
Akib Azmain Turja

Find me on Mastodon at @akib@hostux.social.

This message is signed by me with my GnuPG key.  It's fingerprint is:

    7001 8CE5 819F 17A3 BBA6  66AF E74F 0EFA 922A E7F5

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: [ELPA] New package: perl-doc

[Visuwesh]

[புதன் ஜூலை 27, 2022] Harald Jörg wrote:

> the motivation to write this library came from two sources: In a Perl
> online meeting an Emacs user noted that the usual function to read Perl
> documentation in Emacs, cperl-perldoc, does not work on Platforms which
> don't have 'man' (notably, Windows).

What about woman?  It should be reasonably fast for most manpages.

Re: [ELPA] New package: perl-doc

[Eli Zaretskii]

> From: Visuwesh <visuweshm@gmail.com>
> Cc: Emacs Developer List <emacs-devel@gnu.org>
> Date: Thu, 28 Jul 2022 09:47:53 +0530
> 
> [புதன் ஜூலை 27, 2022] Harald Jörg wrote:
> 
> > the motivation to write this library came from two sources: In a Perl
> > online meeting an Emacs user noted that the usual function to read Perl
> > documentation in Emacs, cperl-perldoc, does not work on Platforms which
> > don't have 'man' (notably, Windows).
> 
> What about woman?  It should be reasonably fast for most manpages.

It cannot format many modern man pages because it wasn't extended to
support the roff directives added in recent years.  Patches to add
that are welcome.

P.S. A simple clone of 'man' for Windows is available from ezwinports
site.

Re: [ELPA] New package: perl-doc

[Harald Jörg]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Visuwesh <visuweshm@gmail.com>
>> Cc: Emacs Developer List <emacs-devel@gnu.org>
>> Date: Thu, 28 Jul 2022 09:47:53 +0530
>> 
>> [புதன் ஜூலை 27, 2022] Harald Jörg wrote:
>> 
>> > the motivation to write this library came from two sources: In a Perl
>> > online meeting an Emacs user noted that the usual function to read Perl
>> > documentation in Emacs, cperl-perldoc, does not work on Platforms which
>> > don't have 'man' (notably, Windows).
>> 
>> What about woman?  It should be reasonably fast for most manpages.
>
> It cannot format many modern man pages because it wasn't extended to
> support the roff directives added in recent years.  Patches to add
> that are welcome.

The troubles start before that: The POD to man converter (pod2man) is
lossy.  It is suited for character terminals or printing, but not so
much for interactive viewing in Emacs.  What I miss most is clickable
links between POD documents.

> P.S. A simple clone of 'man' for Windows is available from ezwinports
> site.

Sure, but the chase doesn't end here!  When I tried yesterday on a
Windows 11 system and Emacs 27.2, <M-x> cperl-perldoc <RET> perlrun
<RET> complained that it can't find sed.

But the actual problem is "read POD documents" rather than "run man".
In my opinion the quality of POD->HTML is better than POD->man.  Here's
a screenshot with a comparison (Linux, Emacs built from git):
https://raw.githubusercontent.com/HaraldJoerg/HaraldJoerg.github.io/main/emacs_perldoc.png

So, as a second step, I consider adding it to cperl-mode.el itself
(protected by an (if (fboundp perl-doc ...)) clause) which can improve
the user's experience if they decide to install the package, or simply
make it work on Windows.

Side note: There's also pod-mode.el at
https://github.com/renormalist/emacs-pod-mode.  This mode is geared
towards _authoring_ POD rather than browsing it.

-- 
Cheers,
haj

Re: [ELPA] New package: perl-doc

[Alexander Adolf]

Harald Jörg <haj@posteo.de> writes:

> [...]
>  * Unlike with 'man', Hyperlinks between POD documents work and
>   resolve to POD documentation on your system, no web server
>   required.
> [...]

I'm sold, this looks like something worth having, IMHO.