unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* [ELPA] New package: perl-doc
@ 2022-07-27 16:16 Harald Jörg
  2022-07-27 17:32 ` Akib Azmain Turja
                   ` (2 more replies)
  0 siblings, 3 replies; 16+ messages in thread
From: Harald Jörg @ 2022-07-27 16:16 UTC (permalink / raw)
  To: Emacs Developer List

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



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [ELPA] New package: perl-doc
  2022-07-27 16:16 [ELPA] New package: perl-doc Harald Jörg
@ 2022-07-27 17:32 ` Akib Azmain Turja
  2022-07-27 17:59   ` Harald Jörg
  2022-07-28  4:17 ` Visuwesh
  2022-08-03 12:16 ` Alexander Adolf
  2 siblings, 1 reply; 16+ messages in thread
From: Akib Azmain Turja @ 2022-07-27 17:32 UTC (permalink / raw)
  To: Harald Jörg; +Cc: Emacs Developer List

[-- 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 --]

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [ELPA] New package: perl-doc
  2022-07-27 17:32 ` Akib Azmain Turja
@ 2022-07-27 17:59   ` Harald Jörg
  2022-07-28  7:24     ` Robert Pluim
  2022-07-28 11:19     ` Gregor Zattler
  0 siblings, 2 replies; 16+ messages in thread
From: Harald Jörg @ 2022-07-27 17:59 UTC (permalink / raw)
  To: Akib Azmain Turja; +Cc: Emacs Developer List

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



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [ELPA] New package: perl-doc
  2022-07-27 16:16 [ELPA] New package: perl-doc Harald Jörg
  2022-07-27 17:32 ` Akib Azmain Turja
@ 2022-07-28  4:17 ` Visuwesh
  2022-07-28  5:53   ` Eli Zaretskii
  2022-08-03 12:16 ` Alexander Adolf
  2 siblings, 1 reply; 16+ messages in thread
From: Visuwesh @ 2022-07-28  4:17 UTC (permalink / raw)
  To: Harald Jörg; +Cc: Emacs Developer List

[புதன் ஜூலை 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.



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [ELPA] New package: perl-doc
  2022-07-28  4:17 ` Visuwesh
@ 2022-07-28  5:53   ` Eli Zaretskii
  2022-07-28  8:57     ` Harald Jörg
  0 siblings, 1 reply; 16+ messages in thread
From: Eli Zaretskii @ 2022-07-28  5:53 UTC (permalink / raw)
  To: Visuwesh; +Cc: haj, emacs-devel

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



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [ELPA] New package: perl-doc
  2022-07-27 17:59   ` Harald Jörg
@ 2022-07-28  7:24     ` Robert Pluim
  2022-07-28  9:22       ` Harald Jörg
  2022-07-28 11:19     ` Gregor Zattler
  1 sibling, 1 reply; 16+ messages in thread
From: Robert Pluim @ 2022-07-28  7:24 UTC (permalink / raw)
  To: Harald Jörg; +Cc: Akib Azmain Turja, Emacs Developer List

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



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [ELPA] New package: perl-doc
  2022-07-28  5:53   ` Eli Zaretskii
@ 2022-07-28  8:57     ` Harald Jörg
  0 siblings, 0 replies; 16+ messages in thread
From: Harald Jörg @ 2022-07-28  8:57 UTC (permalink / raw)
  To: emacs-devel; +Cc: Visuwesh, Eli Zaretskii

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



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [ELPA] New package: perl-doc
  2022-07-28  7:24     ` Robert Pluim
@ 2022-07-28  9:22       ` Harald Jörg
  2022-07-28  9:39         ` Robert Pluim
  2022-07-28 19:34         ` Juri Linkov
  0 siblings, 2 replies; 16+ messages in thread
From: Harald Jörg @ 2022-07-28  9:22 UTC (permalink / raw)
  To: Robert Pluim; +Cc: Emacs Developer List

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



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [ELPA] New package: perl-doc
  2022-07-28  9:22       ` Harald Jörg
@ 2022-07-28  9:39         ` Robert Pluim
  2022-07-28 12:17           ` Harald Jörg
  2022-07-28 19:34         ` Juri Linkov
  1 sibling, 1 reply; 16+ messages in thread
From: Robert Pluim @ 2022-07-28  9:39 UTC (permalink / raw)
  To: Harald Jörg; +Cc: Emacs Developer List

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



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [ELPA] New package: perl-doc
  2022-07-27 17:59   ` Harald Jörg
  2022-07-28  7:24     ` Robert Pluim
@ 2022-07-28 11:19     ` Gregor Zattler
  2022-07-30  7:16       ` Akib Azmain Turja
  1 sibling, 1 reply; 16+ messages in thread
From: Gregor Zattler @ 2022-07-28 11:19 UTC (permalink / raw)
  To: Emacs Developer List

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 



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [ELPA] New package: perl-doc
  2022-07-28  9:39         ` Robert Pluim
@ 2022-07-28 12:17           ` Harald Jörg
  2022-07-28 12:34             ` Robert Pluim
  0 siblings, 1 reply; 16+ messages in thread
From: Harald Jörg @ 2022-07-28 12:17 UTC (permalink / raw)
  To: Robert Pluim; +Cc: Emacs Developer List

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



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [ELPA] New package: perl-doc
  2022-07-28 12:17           ` Harald Jörg
@ 2022-07-28 12:34             ` Robert Pluim
  0 siblings, 0 replies; 16+ messages in thread
From: Robert Pluim @ 2022-07-28 12:34 UTC (permalink / raw)
  To: Harald Jörg; +Cc: Emacs Developer List

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



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [ELPA] New package: perl-doc
  2022-07-28  9:22       ` Harald Jörg
  2022-07-28  9:39         ` Robert Pluim
@ 2022-07-28 19:34         ` Juri Linkov
  2022-07-28 20:58           ` Harald Jörg
  1 sibling, 1 reply; 16+ messages in thread
From: Juri Linkov @ 2022-07-28 19:34 UTC (permalink / raw)
  To: Harald Jörg; +Cc: Robert Pluim, Emacs Developer List

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



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [ELPA] New package: perl-doc
  2022-07-28 19:34         ` Juri Linkov
@ 2022-07-28 20:58           ` Harald Jörg
  0 siblings, 0 replies; 16+ messages in thread
From: Harald Jörg @ 2022-07-28 20:58 UTC (permalink / raw)
  To: Juri Linkov; +Cc: Emacs Developer List

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



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [ELPA] New package: perl-doc
  2022-07-28 11:19     ` Gregor Zattler
@ 2022-07-30  7:16       ` Akib Azmain Turja
  0 siblings, 0 replies; 16+ messages in thread
From: Akib Azmain Turja @ 2022-07-30  7:16 UTC (permalink / raw)
  To: Emacs Developer List; +Cc: Gregor Zattler, Harald Jörg

[-- 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 --]

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [ELPA] New package: perl-doc
  2022-07-27 16:16 [ELPA] New package: perl-doc Harald Jörg
  2022-07-27 17:32 ` Akib Azmain Turja
  2022-07-28  4:17 ` Visuwesh
@ 2022-08-03 12:16 ` Alexander Adolf
  2 siblings, 0 replies; 16+ messages in thread
From: Alexander Adolf @ 2022-08-03 12:16 UTC (permalink / raw)
  To: Harald Jörg, Emacs Developer List

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.



^ permalink raw reply	[flat|nested] 16+ messages in thread

end of thread, other threads:[~2022-08-03 12:16 UTC | newest]

Thread overview: 16+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-07-27 16:16 [ELPA] New package: perl-doc Harald Jörg
2022-07-27 17:32 ` Akib Azmain Turja
2022-07-27 17:59   ` Harald Jörg
2022-07-28  7:24     ` Robert Pluim
2022-07-28  9:22       ` Harald Jörg
2022-07-28  9:39         ` Robert Pluim
2022-07-28 12:17           ` Harald Jörg
2022-07-28 12:34             ` Robert Pluim
2022-07-28 19:34         ` Juri Linkov
2022-07-28 20:58           ` Harald Jörg
2022-07-28 11:19     ` Gregor Zattler
2022-07-30  7:16       ` Akib Azmain Turja
2022-07-28  4:17 ` Visuwesh
2022-07-28  5:53   ` Eli Zaretskii
2022-07-28  8:57     ` Harald Jörg
2022-08-03 12:16 ` Alexander Adolf

Code repositories for project(s) associated with this inbox:

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).