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

##################################################################
###### CAUTION ###### CAUTION ###### CAUTION ###### CAUTION ######
##################################################################
#######                                                    #######
#######   THIS IS ALPHA SOFTWARE.  USE AT YOUR OWN RISK!   #######
#######   NOT RESPONSIBLE FOR CRASHES OR LOST DATA!!!!!!!  #######
#######                                                    #######
##################################################################
###### CAUTION ###### CAUTION ###### CAUTION ###### CAUTION ######
##################################################################


WHAT
----
Perlmacs is a patch of GNU Emacs.  It creates a program 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 (Emacs::Lisp 0.78) uses features introduced in Perlmacs
0.7, which requires Emacs 20.3 and 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.79  	20.3	5.005	0.7


WHY
---
The intent is to allow Emacs modules and customization code to be
written in Perl, as well as Emacs Lisp.  Because we can.  :-)

Actually, my motives have mostly to do with becoming a better
programmer and familiarizing myself with Perl and Emacs, two very
important programs.  See
http://www.tux.org/~niemi/opensource/developer-motivation.html for a
nice explanation by David Niemi.


HOW
---
You must first install PERL VERSION 5.005 or higher.  If you get core
dumps during Perlmacs process termination, I recommend you configure
Perl with -Dusemymalloc=y.  So far, I have seen this problem only with
the Emacs::Lisp test script, and using Perl's malloc seems to cure it.

Your Perl must have working ExtUtils::Embed capabilities.  If not,
`configure' will exclude Perl support, and you will have something
close to standard GNU Emacs.  If you are unsure about this, watch the
messages printed by `configure'.  If they say that Perl is embeddable,
good.  If not, make sure your Perl is at least version 5.005.  If it
is, have a peek at the generated config.log file for clues, and mail
me any workarounds.

Retrieve the Emacs 20.3 distribution from a location such as one of
these:

   ftp://ftp.gnu.org/pub/gnu/emacs/emacs-20.3.tar.gz
   ftp://metalab.unc.edu/pub/gnu/emacs/emacs-20.3.tar.gz

You may want to grab the Elisp Manual, elisp-manual-20-2.5.tar.gz,
while you're there.  (At this time, knowledge of Elisp is very helpful
for programming with Emacs::Lisp.)

Retrieve the latest Perlmacs patch from one of these locations:

   http://www.perl.com/CPAN/authors/id/JTOBEY/emacs-20.3-perlmacs-*.pl.gz
   http://john-edwin-tobey.org/perlmacs/src/emacs-20.3-perlmacs-*.pl.gz

(Substitute the highest version number, at least 0.7, for `*'.)  Then
do

   gzip -dc emacs-20.3.tar.gz |tar xf -
   cd emacs-20.3
   gzip -dc ../emacs-20.3-perlmacs-*.pl.gz |perl

Have a look at the patched README file for further information.  The
basic procedure should be familiar:

   ./configure
   make
   make install

This will, by default, install the program in /usr/local/bin under the
names `pmacs' and `perlmacs'.  The program can parse its command line
as either Perl or Emacs would, dependent on whether "perl" appears in
its name.  (Using `--perl' or `--emacs' as the first arg overrides
this.)

If you wish to use an installed version of perl other than the one
that's in your $PATH, set the environment variable $PERL to the
desired program when running configure.  For example, under bash or
sh:

   PERL=perl5.005 ./configure

Next, build the Emacs::Lisp module in the usual way, but use perlmacs
in place of perl.

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

If `make test' prints all ok but dumps core at the end, read the
paragraph under "HOW" above.

Most of the documentation for both the patch and the module is in
perl/Emacs/Lisp/Lisp.pm and will be accessible after installation via

   perldoc Emacs::Lisp

Lisp functions, such as `perl-eval', also 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/.


CAVEATS
-------
As of this ALPHA version, crashes may occur, resulting in the loss of
unsaved editing changes.

This is not meant to be tried on anything other than Unix-like
systems.  However, if you get it to work on non-unix, I would be
delighted to hear about it!


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