5 May 2000

This is version 0.16 of Perlmacs, a program based on GNU Emacs with
the Perl interpreter linked in.  Perlmacs has all the functionality of
both Perl and Emacs, and it lets Perl code call functions and access
variables of Lisp.

Perlmacs is still considered "beta" at this time, so if you use it for
day-to-day editing, I suggest you save your work often.  Send bug
reports to jtobey@john-edwin-tobey.org.  For the latest (semi-)stable
version, look in either of these locations

    http://www.perl.com/CPAN/authors/id/JTOBEY/
    http://john-edwin-tobey.org/perlmacs/src/

for a file named `Emacs-PerlmacsPatch-x.yy.tar.gz' (where x.yy is the
highest version number).

Perlmacs is available through anonymous CVS, but it's a little
complex.  Check http://john-edwin-tobey.org/perlmacs/ or contact me if
you would like instructions on setting up a CVS directory.


REQUIREMENTS
============

Perlmacs requires Perl version 5.005 or higher.  It has been known to
work on versions of Unix including Linux and Solaris.  On some Unix
machines (one FreeBSD and another Solaris) the program dies when run
in graphical mode (with DISPLAY set).  If you debug this, please let
me know right away.

Perlmacs has not been built on Windows, to my knowledge.


NEWS
====

New in Perlmacs 0.16:

    * Sync with Emacs 20.6.  Emacs 20.3 is no longer supported.

New in Perlmacs 0.15:

    * `perlmacs -d -MEmacs -emain' runs the interactive Perl debugger
      in Emacs mode.

    * Completed %ENV implementation.

New in Perlmacs 0.14:

    * Support Perl 5.6.0.  (Emacs 20.3 is still required.)

    * Bundle Emacs::Lisp with the distribution.

    * Fix behavior of special Perl variables STDOUT, %ENV, etc. when
      using Perl 5.6.0 ("print" inserts text in the buffer).

See the file `Changes' for older news.


INSTALLATION
============

The Emacs::PerlmacsPatch module is not a Perl module in the ordinary
sense.  It exists merely as a convenience for distribution purposes
and to take advantage of Perl's `Makefile.PL' interface.  Building and
installing Emacs::PerlmacsPatch really means building and installing
Perlmacs.

You will need the GNU Emacs 20.6 source distribution in order to build
Perlmacs.  Find the file emacs-20.6.tar.gz in a location such as
these:

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

Makefile.PL will search the current directory, its parent, and
possibly other locations for emacs-20.6.tar.gz.  You can specify its
location by passing EMACS_SRC=/path/to/emacs-20.6.tar.gz as an
argument to Makefile.PL.  Failing that, Makefile.PL will offer to
download it from the net for you.

cd into the top directory of the Emacs::PerlmacsPatch distribution and
run the standard command sequence for installing Perl modules:

    perl Makefile.PL
    make
    make test
    make install

Although Perlmacs supports Perl 5.005, one of the tests will fail.
This is due to a bug which has been fixed in 5.6.0.  It only affects
programs that destroy and recreate Perl interpreters, which you are
not likely to do without realizing it.

If you want to pass options to the Perlmacs `configure' script, give
them to Makefile.PL after a `--'.  For example:

    perl Makefile.PL -- --prefix=/opt

For a list of `configure' options, do this:

    perl Makefile.PL
    emacs-20.6/configure --help

By default, the program will be installed in the same directory as
perl under the names `pmacs' and `perlmacs'.  Invoke it as pmacs when
you want edit files as Emacs would; use perlmacs to run Perl scripts.

Your Perl must have working ExtUtils::Embed capabilities.  If not, or
if Perl's version number is below 5.005, `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 during `make'.
If they say that Perl is embeddable, good.  If not, have a peek at
emacs-20.6/build/config.log for clues, and mail me any workarounds.


LICENSE
=======

Copyright (C) 1998-2000 by John Tobey.  All rights reserved.
Copyright (C) 1998 Free Software Foundation, Inc.

This software is distributed under the GNU General Public License,
version 2 or higher.  See the file COPYING for details.


WARRANTY
========

Perlmacs is free software, so it comes with no warranty.

    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.