[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[ELPA] New package: perl-doc

From: Harald Jörg
Subject: [ELPA] New package: perl-doc
Date: Wed, 27 Jul 2022 16:16:19 +0000

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

 * 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

Feedback is very welcome!

reply via email to

[Prev in Thread] Current Thread [Next in Thread]