GNU ELPA - perl-doc

perl-doc

Description
Read Perl documentation
Latest
perl-doc-0.81.tar (.sig), 2024-Mar-31, 70.0 KiB
Maintainer
Harald Jörg <haj@posteo.de>
Atom feed
perl-doc.xml
Website
https://github.com/HaraldJoerg/emacs-perl-doc
Browse ELPA's repository
CGit or Gitweb
Badge

To install this package from Emacs, use package-install or list-packages.

Full description

This file contains a command to read Perl documentation in Emacs.
It uses two external commands which come with Perl: `perldoc` to
locate the Perl documentation for the Perl modules installed on
your system, and `pod2html` to format the documentation to HTML.
This HTML version is then displayed using Emacs' "simple HTML
renderer" shr.

Motivation

Perl documentation is written in a markup format called POD ("Plain
Old Documentation") and is usually converted to other formats for
reading by humans.  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

Old versions

perl-doc-0.8.tar.lz2023-Aug-0217.2 KiB
perl-doc-0.6.tar.lz2022-Sep-298.23 KiB
perl-doc-0.4.tar.lz2022-Sep-278.23 KiB
perl-doc-0.2.tar.lz2022-Aug-077.25 KiB

News

perl-doc.el for GNU Emacs NEWS -- history of user-visible changes.

Copyright (C) 2023 Free Software Foundation, Inc.
See the end of the file for license conditions.

* Changes in perl-doc.el 0.8 - August 2023

** Speedbar Support

perl-doc now has its own display in speedbar.  It is accessible either
by starting <M-x> speedbar while looking at a buffer in perl-doc-mode
or by starting <M-x> perl-doc-browser.  In the latter case, which also
works if emacs is started in a terminal, you can leave perl-doc
display with the command <M-x> perl-doc-browser-quit (bound to "q" in
the speedbar frame).

** Completion of module names

The perl-doc command now offers completion for modules which are
installed on your system (fine print: The modules who are available to
the Perl executable customized as perl-doc-perl-program).

** New functions

Documentation for builtin functions and variables is now available via
the new commands perl-doc-function and perl-doc-variable.  They don't
do completion, though (I have no easily accessible authoritative
source for the completion candidates).

The commands perl-doc-browser and perl-doc-browser-quit start and
stop perl-doc view in speedbar.

The command perl-doc-add-lib allows to add an existing directory (with
completion) for the current session.  To add a directory permanently,
see the new customization option perl-doc-extra-libs below.

** New customization options

The option perl-doc-perl-program is the file name of the Perl
executable for which documentation is to be displayed.  perl-doc.el
runs the one-liner "perl -E 'say for @INC'" to get the list of
directories where Perl modules (and their documentation) reside.

The option perl-doc-extra-libs allows to add a list of directories, on
top of the builtin ones and those from PERL5LIB.

** Bugfixes

Refreshing the view doesn't happen quite as often (only if the width
of the window changes), and if it ever happens, it does no longer kill
imenu's menubar-index (errors reported by LanX on PerlMonks)

** Known bugs and limitations

The display of Perl documentation is done in a scratch buffer which is
not associated with a file.  This means that there's no point in
editing this buffer or saving it.

The error handling could be better.  If a Perl documentation buffer
shows "No documentation found for Your::Module", then you don't know
whether the file Your/Module.pm has no POD in it or whether it does
not exist at all.  In the former case, you can still use "v" to view
the source of Your/Module.pm (and add some POD, of course), the latter
should not happen if you let yourself be guided by the module name
completion.

* Changes in perl-doc.el 0.6

Bugfix: A vertical bar in markup is now processed correctly (seen in
perlport.pod).

* Changes in perl-doc.el 0.3

** New command `perl-doc-file'

Like `perl-doc', but prompt for a file name with completion.

** New command `perl-doc-view-source'

View the POD source for the Perl documentation shown in the current
buffer.  The command is bound to "v" in `perl-doc-mode'.



----------------------------------------------------------------------
perl-doc.el is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

perl-doc.el is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.


Local variables:
coding: utf-8
mode: outline
paragraph-separate: "[ 	]*$"
end: