unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
From: "Harald Jörg" <haj@posteo.de>
To: Emacs Developer List <emacs-devel@gnu.org>
Subject: [ELPA] New package: perl-doc
Date: Wed, 27 Jul 2022 16:16:19 +0000	[thread overview]
Message-ID: <87a68upm3w.fsf@hajtower> (raw)

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



             reply	other threads:[~2022-07-27 16:16 UTC|newest]

Thread overview: 16+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-07-27 16:16 Harald Jörg [this message]
2022-07-27 17:32 ` [ELPA] New package: perl-doc 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

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.gnu.org/software/emacs/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87a68upm3w.fsf@hajtower \
    --to=haj@posteo.de \
    --cc=emacs-devel@gnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public 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).