27 March 1999

This is version 0.11 of Perlmacs, a program based on GNU Emacs with
the Perl interpreter linked in.

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@channel1.com.  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).

For information about CVS updates, see
`http://john-edwin-tobey.org/perlmacs/'.


NEW IN 0.11
===========

    * The only significant changes since 0.10 are bugfixes.


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

Perlmacs requires Perl version 5.005 or higher.

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 source distribution in order to build
Perlmacs.  Find the file emacs-20.3.tar.gz in 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

`Makefile.PL' will search the current directory, its parent, and
possibly other locations for this file.  You can specify its location
by passing EMACS_SRC=/path/to/emacs-20.3.tar.gz as an argument to
Makefile.PL.  If all else fails, it will offer to download it from the
net for you.

When you have the Emacs source, cd into the top directory of the
Emacs::PerlmacsPatch distribution and run the usual commands for Perl
modules, namely:

    perl Makefile.PL
    make
    make install

(There are not any tests to run.)  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.3/configure --help

By default, the program will be installed in /usr/local/bin under the
names `pmacs' and `perlmacs'.  Invoke it as `pmacs' when you want it
to parse its command line as Emacs would; `perlmacs' behaves like
Perl.

Your Perl must have working ExtUtils::Embed capabilities.  If not, or
if Perl's version number is too low, `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 the
emacs-20.3/build/config.log file for clues, and mail me any
workarounds.


PERLMACS AND Emacs::Lisp
========================

Perlmacs can evaluate Perl code and pass arguments to Perl functions.
The code may use Perl modules, including DynaLoader modules.  However,
to call Emacs Lisp functions or access Lisp variables, you need the
Emacs::Lisp module.  The module is available in the same locations as
Perlmacs.  See the file README in the Emacs::Lisp distribution for
more information.

Although the separation of Emacs::Lisp from the main Perlmacs
distribution is intended to permit updates to either without requiring
the other to be upgraded, currently there is rather strict version
interdependency between the two packages, and also on Perl.  In the
following table, each row represents a supported combination of
versions:

   Emacs::Lisp  GNU Emacs  Perl    Perlmacs
   ===========  =========  ====    ========
       0.80       20.3     5.005   0.7.1
       0.84       20.3     5.005   0.8
       0.88+      20.3     5.005   0.9.2+

Of course, the most recent versions should be given preference
whenever possible.

Although I hope to master the use of Texinfo and/or SGML Tools one day
and add Perlmacs documentation to the standard Emacs set, so far the
best documentation is in the Emacs::Lisp module.


LICENSE
-------
Copyright (C) 1998-1999 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 not developed for profit, so its authors can provide 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.