all messages for Emacs-related lists mirrored at yhetil.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

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

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

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.