README for Perl module Emacs::Lisp
last updated: 28 Mar 1999


WHAT
----
Perlmacs is a program based on GNU Emacs that has all the
functionality of both Perl and Emacs.  The Emacs::Lisp module allows
Perl code to call functions and access variables of Lisp.

This release uses features introduced in Perlmacs 0.9, which is based
on Emacs 20.3 and requires Perl 5.005.  The following table lists
which versions of the various packages work together:

   Emacs::Lisp	Emacs	Perl	Perlmacs
   ===========  =====   ====    ========
       0.71	20.2	5.004	0.6.2
       0.75	20.3	5.004	0.6.2.2
       0.80  	20.3	5.005	0.7.1
       0.88+ 	20.3	5.005	0.9.1+


WHY
---
The intent is to allow Emacs modules and customization code to be
written in Perl, and to give Emacs Lisp access to Perl.

My motives have mostly to do with becoming a better programmer,
familiarizing myself with Perl and Emacs, and indulging my fascination
with language translation.  See
http://www.tux.org/~niemi/opensource/developer-motivation.html for a
nice explanation by David Niemi.

As to why anyone would want to install Perlmacs, your guess is as good
as mine.  :-) One person emailed me to say that he had made Perlmacs
"a very important tool" for his y2k consulting work.  You can see his
code at http://john-edwin-tobey.org/perlmacs/.


HOW
---
This module does not work with ordinary Perl, you need to install
Perlmacs.  Follow the instructions in the Emacs::PerlmacsPatch module,
available in the same places as this module.

For programming Emacs (with or without Emacs::Lisp), I recommend The
Elisp Manual, which you can get from one of these places:

  ftp://metalab.unc.edu/pub/gnu/emacs/elisp-manual-20-2.5.tar.gz
  ftp://ftp.gnu.org/pub/gnu/emacs/elisp-manual-20-2.5.tar.gz

To build the Emacs::Lisp module, perform the usual module-building
incantation, but use perlmacs in place of perl, like this:

   gzip -dc Emacs-Lisp-*.tar.gz |tar xf -
   cd Emacs-Lisp-*
   perlmacs Makefile.PL
   make
   make test
   make install

Most of the documentation for both Perlmacs and this module is in
Lisp.pm and will be accessible after installation via

   perldoc Emacs::Lisp

Lisp functions, such as `perl-eval-expression', have Emacs docstrings
accessible through `C-h f'.  No texinfo docs yet, sorry.

For information on getting the latest source via anonymous CVS, see
http://john-edwin-tobey.org/perlmacs/.


LICENSE
-------
This software is licensed under the GNU General Public License.  See
the file COPYING for details.


WARRANTY
--------
What!  Are you kidding?  Let's see, where's a copy of that
disclaimer.... oh, here we go:

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


Send bug reports and inquiries to John <jtobey@channel1.com>.