-*- mode:outline; minor-mode:outl-mouse -*-

* Introduction
==============

This file presents some general information about XEmacs.  It is primarily
about the evolution of XEmacs and its release history.

There are five sections.

    Introduction................(this section) provides an introduction

    Using Outline Mode..........briefly explains how to use outline mode

    The History of XEmacs.......some historical notes

    What's Different?...........new or changed capabilities

    XEmacs Release Notes........details of the changes between releases

New users should look at the next section on "Using Outline Mode".  You will
be more efficient when you can navigate quickly through this file.  Users
interested in some of the details of how XEmacs differs from FSF GNU Emacs
should read the section "What's Different?".  Users who would to know which
capabilities have been introduced in each release should look at the
appropriate subsection of the "XEmacs Release Notes."

    N.B.  The term "FSF GNU Emacs" refers to any release of Emacs Version 19
    from the Free Software Foundation's GNU Project. (We do not say just
    "GNU Emacs" because Richard M. Stallman ["RMS"] thinks that this term
    is too generic; although we sometimes say e.g. "GNU Emacs 19.30" to refer
    to a specific version of FSF GNU Emacs.  We do not say merely "Emacs", as
    RMS prefers, because that is clearly an even more generic term.) The term
    "XEmacs" refers to this program or to its predecessors "Era" and
    "Lucid Emacs".  The predecessor of all these program is called "Emacs 18".
    When no particular version is implied, "Emacs" will be used.


* Using Outline Mode
====================

This file is in outline mode, a major mode for viewing (or editing)
outlines.  It allows you to make parts of the text temporarily invisible so
that you can see just the overall structure of the outline.

There are two ways of using outline mode:  with keys or with menus.  Using
outline mode with menus is the simplest and is just as effective as using
keystrokes.  There are menus for outline mode on the menubar as well as in
popup menus activated by pressing mouse button 3.

Experiment with the menu commands.  Menu items under "Headings" allow
you to navigate from heading to heading.  Menu items under "Show" make
visible portions of the outline while menu items under "Hide" do the
opposite.

A special minor mode called "outl-mouse" has been automatically enabled.  In
this minor mode, glyphs appear which, when clicked on, will alternately hide
or show sections of the outline.

You may at any time press `C-h m' to get a listing of the outline mode key
bindings.  They are reproduced here:

Commands:
C-c C-n   outline-next-visible-heading      move by visible headings
C-c C-p   outline-previous-visible-heading
C-c C-f   outline-forward-same-level        similar but skip subheadings
C-c C-b   outline-backward-same-level
C-c C-u   outline-up-heading		    move from subheading to heading

C-c C-t	make all text invisible (not headings).
M-x show-all	make everything in buffer visible.

The remaining commands are used when point is on a heading line.
They apply to some of the body or subheadings of that heading.
C-c C-d   hide-subtree	make body and subheadings invisible.
C-c C-s   show-subtree	make body and subheadings visible.
C-c tab   show-children	make direct subheadings visible.
		 No effect on body, or subheadings 2 or more levels down.
		 With arg N, affects subheadings N levels down.
C-c C-c	   make immediately following body invisible.
C-c C-e	   make it visible.
C-c C-l	   make body under heading and under its subheadings invisible.
		     The subheadings remain visible.
C-c C-k  make all subheadings at all levels visible.x1


* The History of XEmacs
=======================

This product is an extension of GNU Emacs, previously known to some as
"Lucid Emacs" or "ERA".  It was initially based on an early version of Emacs
Version 19 from the Free Software Foundation and has since been kept
up-to-date with recent versions of that product.  It stems from a
collaboration of Lucid, Inc. with SunSoft DevPro (a division of Sun
Microsystems, Inc.; formerly called SunPro) and the University of Illinois.

NOTE: Lucid, Inc. is currently out of business but development on XEmacs
continues strong.  Recently, Amdahl Corporation and INS Engineering have
both contributed significantly to the development of XEmacs.


** Why Haven't XEmacs and FSF GNU Emacs Merged?
===============================================

This question comes up again and again on comp.emacs.xemacs and other
newsgroups and mailing lists.  Recently in fact there was a long, heated
thread about this issue.

Here is what one XEmacs developer said about this issue.

DISCLAIMER: This is provided for informational purposes only and does
_NOT_ necessarily represent the opinions of any of the other XEmacs
developers or of any of the organizations involved.  Keep in mind
that this is a highly charged issue with differing and strongly-held
opinions held by the various parties involved.

   Subject: Re: elisp code in GNU Emacs/XEmacs
   From: wing@666.com (Ben Wing)
   Message-ID: <wingDqGwLH.K6w@netcom.com>
   Date: Fri, 26 Apr 1996 11:44:05 GMT
   
   In article <9xo91fmordx.fsf@bcarsf26.nortel.ca>, Stephane Boucher
   <sbo@bcarsf26.nortel.ca> wrote:
   
       Well, I don't think the number of volunteers is greater by having 2
       Emacsen. I think your affirmation holds true because of the
       inhability of the various parties involved to work together and
       compromise. If people could all work together, I don't think there
       would be any benifit in having 2 Emacsen. It may seem profitable
       right now, but in the long run, I think everyone looses. The time
       everyone spends porting back and forth, and imitating what the other
       has done is not spent to do new features. I've presonnally
       experienced a project split in the past, and in the end everyone
       lost. 
       
       I don't want to try to blame anybody for the current fiasco. But we do
       have a fiasco. That is unfortunate. There are so many contributors
       out there that if everyone worked together we might be looking
       forward to having, say, threads in Emacs. But instead, as someone
       told me not that long ago, maybe we'll soon see a new editor come out
       based on Java. Threads will be part of it at no extra cost, and those
       people still using Emacs will continue to curse at the fact that they
       can't start GNUS while typing an E-mail, and the various Emacs
       contributors will continue to argue among themselves, nitpicking
       about how to get the perfect solution, rather than try to move
       forward. Meanwhile, people will enjoy using a new state of the art
       editor. 
   
   Don't think we're just being needlessly perverse by continuing to have
   XEmacs. I'm well aware of the problems in having a project split, and
   don't think for a minute that we haven't tried (extremely hard, in
   fact) to come up with a merge.
   
   Unfortunately, as I have said before, the odds of this happening are
   quite low due to severe conflicts (both technical, procedural, and
   philosophical) between RMS and the XEmacs developers. If we were to
   assent to even half of what RMS wants in a merged Emacs, it would take
   years of work to produce the merged Emacs, and the result would be
   less powerful than the existing XEmacs.
   
   Since so many people seem so misinformed about this problem, I'll go
   ahead and state the fundamental dividing issues:
   
    1. RMS does not believe in data abstraction, and cannot be convinced
       of the folly of this. This by itself is such a huge division that
       it makes a merge basically unthinkable. Because of this, FSF Emacs
       is basically unmaintainable by anyone other than RMS. RMS has
       consented to all the data abstraction I want provided that I take
       sole responsibility for writing this code (which basically means
       I'd have to write almost all of the code or rewrite most of his
       code), and provided that he can use this issue as a bargaining
       chip to get concessions of his own.
    2. RMS sees the merge process as a series of mutual concessions
       traded back and forth. IMHO this is reasonable for a peace treaty
       but absurd for a piece of software -- we have to have technical
       agreement on the major issues involved, and the chance of that
       happening is basically nil.
    3. RMS has insisted in full backwards compatibility with all aspects
       of FSF Emacs, no matter how ugly; and furthermore, this backwards
       compatibility must work fast enough to make existing code run
       without problem. This basically means that there would have to be
       parallel C implementations of events, keymaps, and many other data
       structures. This not only will take months or years of extra work
       to implement, but poses some fundamental technical problems due to
       the non-abstractedness of FSF Emacs (e.g. in FSF Emacs keymaps are
       conses or vectors and a lot of code depends on this, and
       reconciling this with XEmacs's primitive keymap type is difficult
       to impossible).
    4. RMS will not even consent to neutral names for the two editors. He
       objects to call his editor FSF Emacs because for some unfathomable
       reason he finds it insulting. He suggests just Emacs, which I find
       not only insulting (XEmacs is just as much Emacs as is FSF Emacs)
       but also quite confusing. He will not even consent to calling his
       editor GNU Emacs without also referring to XEmacs as GNU XEmacs --
       basically a Borg-like assimilation attempt at making XEmacs a GNU
       product, which it is not. (None of the developers of Lucid Emacs
       and XEmacs were or are sanctioned by GNU, and none of us got the
       least bit of assistance or cooperation in doing our work. In fact,
       RMS actively made it harder by choosing to ignore all work
       previously done in XEmacs and adding his own incompatible
       interfaces for functionality already in XEmacs. This makes it
       quite difficult to track FSF Emacs and keep a sane API.) He has
       stated many times, and continues to assert, that most or all of
       the work done on Lucid Emacs and XEmacs was done primarily as a
       testing ground for potential features to be added to FSF Emacs.
       All of the developers of Lucid Emacs and XEmacs assert that this
       is patently false -- so why does RMS continue to insist that this
       is the case?

   ben
   --
   "... then the day came when the risk to remain tight in a bud was
   more painful than the risk it took to blossom." -- Anais Nin


** Why Another Version of Emacs?  (The Lucid, Inc. Point of View)
=================================================================

Lucid's latest product, Energize, is a C/C++ development environment.
Rather than invent (and force our users to learn) a new user-interface, we
chose to build part of our environment on top of the world's best editor,
GNU Emacs.  (Though our product is commercial, the work we did on is
free software, and is useful without having to purchase our product.)

We needed a version of Emacs with mouse-sensitive regions, multiple fonts,
the ability to mark sections of a buffer as read-only, the ability to detect
which parts of a buffer has been modified, and many other features.

*** Why Not Epoch or GNU Emacs?
-------------------------------

For our purposes, the existing version of Epoch was not sufficient; it did
not allow us to put arbitrary pixmaps/icons in buffers, `undo' did not
restore changes to regions, regions did not overlap and merge their
attributes in the way we needed, and several other things.

We could have devoted our time to making Epoch do what we needed (and, in
fact, we spent some time doing that in 1990) but, since the Free Software
Foundation planned to include Epoch-like features in their Version 19, we
decided that our efforts would be better spent improving GNU Emacs
instead of Epoch.

Our original hope was that our changes to GNU Emacs would be
incorporated into the "official" v19.  However, scheduling conflicts arose,
and we found that, given the amount of work still remaining to be done, we
didn't have the time or manpower to do the level of coordination that would
be necessary to get our changes accepted by the Free Software Foundation.
Consequently, we released our work as a forked branch of Emacs, instead of
delaying any longer.

Roughly a year after Lucid Emacs 19.0 was released, a beta version of the
Free Software Foundation branch of Emacs 19 was released.  This version
was better in some areas, and worse in others, as reflects the differing
focus of our development efforts.

We planned to continue developing and supporting Lucid Emacs, and merging in
bug fixes and new features from the Free Software Foundation branch as
appropriate; we did not plan to discard any of the functionality that we
implemented which Richard Stallman of the Free Software Foundation has
chosen not to include in his version.

However, events have overtaken us, and Lucid, Inc. has effectively ceased
doing business and is (September 1994) in the process of being sold.  Our
efforts on Lucid Emacs have also ceased and we've turned over the continued
enhancement of Lucid Emacs to the University of Illinois under Chuck
Thompson, a member of the Lucid Emacs team and a maintainer of Epoch.
At the same time, Lucid Emacs has been renamed XEmacs to reflect the
substantial contribution of the University of Illinois with the support of
Sun Microsystems.

Certain elements of Lucid Emacs, or derivatives of them, have been ported to
the FSF GNU Emacs.  We have not been doing work in this direction, because
we feel that Lucid Emacs has a cleaner and more extensible substrate, and
that any kind of merger between the two branches would be far easier by
merging the Free Software Foundation changes into our version than the other
way around.

We were working closely with the Epoch developers to merge in the
remaining Epoch functionality which Lucid Emacs does not yet have.  Epoch
and Lucid Emacs will soon be one and the same thing.  Work is being done on
a compatibility package which will allow Epoch 4 code to run in XEmacs with
little or no change.  (As of 19.8, Lucid Emacs is running a descendant of
the Epoch redisplay engine.)

** Why Another Version of Emacs?  (The SunPro Point of View)
============================================================

Emacs 18 has been around for a long, long time.  Version 19 was supposed to
be the successor to Emacs 18 with X support.  It was going to be available
"real soon" for a long time (some people remember hearing about v19 as early
as 1984!), but it never came out.  v19 development was going very, very
slowly, and from the outside it seemed that it was not moving at all.  In
the meantime other people gave up waiting for v19 and decided to build their
own X-aware Emacsen.  The most important of these was probably Epoch, which
came from the University of Illinois and was based on v18.

Around three years ago we decided that we wanted an integrated editor.  We
contracted with the University of Illinois to provide a number of basic
enhancements to the functionality in Epoch.  The University of Illinois
initially was planning to deliver this on top of Epoch code.

In the meantime (actually some time before we talked with the University of
Illinois) Lucid had decided that it also wanted to provide an integrated
environment with an integrated editor.  Lucid decided that the Version 19
basis was a better one than Version 18 and thus decided not to use Epoch but
instead work with Richard Stallman, the head of the Free Software Foundation
and principle author of Emacs, on getting Version 19 out.  At some point
Stallman and Lucid parted ways.  Lucid kept working and got a Version 19 out
that they called Lucid Emacs 19.

After Lucid's v19 came out it became clear to us (the University of Illinois
and SunPro) that the right thing to do was to push for an integration of
both Lucid Emacs and Epoch, and to get the deliverables that we were asking
from the University of Illinois on top of this integrated platform.  Through
the last two years, SunPro has been actively supporting this product and has
been investing a comparable amount of effort into it as Lucid has.
Substantial portions of the current code have originated under the support
of SunPro, either directly in SunPro, or in the University of Illinois but
paid for by us.  This code was kept away from Lucid for a while, but later
was made available to them.  Initially Lucid didn't know that we were
supporting UofI, but later we were open about it.

Eventually, all development source trees were synched up.  Currently, there
is basically no difference in the source trees between what is at the
University of Illinois and SunPro.

SunPro originally called the integrated product ERA, for "Emacs Rewritten
Again".  At some point, SunPro and Lucid came to an agreement to find a name
for the product that was not specific to either company.  An additional
constraint that Lucid placed on the name was that it must contain the word
"Emacs" in it -- thus "ERA" was not acceptable.  The agreed-upon name was
"XEmacs", and this is what the product has been called starting with the
19.11 release.


* What's Different?
===================


** Differences between XEmacs and FSF GNU Emacs 19
==================================================

In XEmacs, events are first-class objects.  FSF 19 represents them as
integers, which obscures the differences between a key gesture and the
ancient ASCII code used to represent a particular overlapping subset of them.

In XEmacs, keymaps are first-class opaque objects.  FSF 19 represents them as
complicated combinations of association lists and vectors.  If you use the
advertised functional interface to manipulation of keymaps, the same code
will work in XEmacs, Emacs 18, and and FSF GNU Emacs 19; if your code depends
on the underlying implementation of keymaps, it will not.

XEmacs uses "extents" to represent all non-textual aspects of buffers;
FSF 19 uses two distinct objects, "text properties" and "overlays",
which divide up the functionality between them.  Extents are a
superset of the functionality of the two FSF data types.  The full FSF
19 interface to text properties is supported in XEmacs (with extents
being the underlying representation).

Extents can be made to be copied into strings, and thus restored by kill
and yank.  Thus, one can specify this behavior on either "extents" or
"text properties", whereas in FSF 19 text properties always have this
behavior and overlays never do.

Many more packages are provided standard with XEmacs than with FSF 19.

Pixmaps of arbitrary size can be embedded in a buffer.

Variable width fonts work.

The height of a line is the height of the tallest font on that line, instead
of all lines having the same height.

XEmacs uses the MIT "Xt" toolkit instead of raw Xlib calls, which
makes it be a more well-behaved X citizen (and also improves
portability).  A result of this is that it is possible to include
other Xt "Widgets" in the XEmacs window.  Also, XEmacs understands the
standard Xt command-line arguments.

XEmacs provides support for ToolTalk on systems that have it.

XEmacs can ask questions using popup dialog boxes.  Any command executed from
a menu will ask yes/no questions with dialog boxes, while commands executed
via the keyboard will use the minibuffer.

XEmacs has a built-in toolbar.  Four toolbars can actually be configured:
top, bottom, left, and right toolbars.

XEmacs has vertical and horizontal scrollbars.  Unlike in FSF 19 (which
provides a primitive form of vertical scrollbar), these are true toolkit
scrollbars.  A look-alike Motif scrollbar is provided for those who
don't have Motif. (Even for those who do, the look-alike may be preferable
as it is faster.)

If you're running on a machine with audio hardware, you can specify sound 
files for XEmacs to play instead of the default X beep.  See the documentation
of the function load-sound-file and the variable sound-alist.

An XEmacs frame can be placed within an "external client widget" managed by
another application.  This allows an application to use an XEmacs frame as its
text pane rather than the standard Text widget that is provided with Motif or
Athena.  XEmacs supports Motif applications, generic Xt (e.g. Athena)
applications, and raw Xlib applications.

Here are some more specifics about the XEmacs implementation:

*** The Input Model
-------------------

The fundamental unit of input is an "event" instead of a character.  An
event is a new data type that contains several pieces of information.
There are several kinds of event, and corresponding accessor and utility
functions.  We tried to abstract them so that they would apply equally
well to a number of window systems.

NOTE: All timestamps are measured as milliseconds since Emacs started.

 key_press_event	
    event_channel	A token representing which keyboard generated it.
			For this kind of event, this is a frame object.
			(This is for eventual support of multiple displays.)
    timestamp		When it happened
    key			What keysym this is; an integer or a symbol.
			If this is an integer, it will be in the printing
			ASCII range: >32 and <127.
    modifiers		Bucky-bits on that key: control, meta, etc.
			For most keys, Shift is not a bit; that is implicit
			in the keyboard layout.

 button_press_event
 button_release_event
    event_channel	A token representing which mouse generated it.
			For this kind of event, this is a frame object.
    timestamp		When it happened
    button		What button went down or up.
    modifiers		Bucky-bits on that button: shift, control, meta, etc.
    x, y		Where it was at the button-state-change (in pixels).

 pointer_motion_event
    event_channel	A token representing which mouse generated it.
			For this kind of event, this is a frame object.
    timestamp		When it happened
    x, y		Where it was after it moved (in pixels).
    modifiers		Bucky-bits down when the motion was detected.
			(Possibly not all window systems will provide this?)

 process_event
    timestamp		When it happened
    process		the emacs "process" object in question

 timeout_event
    timestamp		Now (really, when the timeout was signaled)
    interval_id		The ID returned when the associated call to
			add_timeout_cb() was made
	------ the rest of the fields are filled in by Emacs -----
    id_number		The Emacs timeout ID for this timeout (more
			than one timeout event can have the same value
			here, since Emacs timeouts, as opposed to
			add_timeout_cb() timeouts, can resignal
			themselves)
    function		An elisp function to call when this timeout is
			processed.
    object		The object passed to that function.

 eval_event
    timestamp		When it happened
    function		An elisp function to call with this event object.
    object		Anything.
			This kind of event is used internally; sometimes the
			window system interface would like to inform emacs of
			some user action (such as focusing on another frame)
			but needs that to happen synchronously with the other
			user input, like keypresses.  This is useful when
			events are reported through callbacks rather
			than in the standard event stream.

 misc_user_event
    timestamp		When it happened
    function		An elisp function to call with this event object.
    object		Anything.
			This is similar to an eval_event, except that it is
			generated by user actions: selections in the
			menubar or scrollbar actions.  It is a "command"
			event, like key and mouse presses (and unlike mouse
			motion, process output, and enter and leave window
			hooks).  In many ways, eval_events are not the same
			as keypresses or misc_user_events.

 magic_event
			No user-serviceable parts within.  This is for things
			like KeymapNotify and ExposeRegion events and so on
			that emacs itself doesn't care about, but which it
			must do something with for proper interaction with
			the window system.

			Magic_events are handled somewhat asynchronously, just
			like subprocess filters.  However, occasionally a 
			magic_event needs to be handled synchronously; in that
			case, the asynchronous handling of the magic_event will
			push an eval_event back onto the queue, which will be 
			handled synchronously later.  This is one of the
			reasons why eval_events exist; I'm not entirely happy
			with this aspect of this event model.


The function `next-event' blocks and returns one of the above-described 
event objects.  The function `dispatch-event' takes an event and processes
it in the appropriate way.

For a process-event, dispatch-event calls the process's handler; for a
mouse-motion event, the mouse-motion-handler hook is called, and so on.
For magic-events, dispatch-event does window-system-dependent things,
including calling some non-window-system-dependent hooks: map-frame-hook,
unmap-frame-hook, mouse-enter-frame-hook, and mouse-leave-frame-hook.

The function `next-command-event' calls `next-event' until it gets a key or
button from the user (that is, not a process, motion, timeout, or magic
event).  If it gets an event that is not a key or button, it calls
`dispatch-event' on it immediately and reads another one.  The
next-command-event function could be implemented in Emacs Lisp, though it
isn't.  Generally one should call `next-command-event' instead of
`next-event'.

read-char calls next-command-event; if it doesn't get an event that can be
converted to an ASCII character, it signals an error.  Otherwise it returns
an integer.

The variable `last-command-char' always contains an integer, or nil (if the
last read event has no ASCII equivalent, as when it is a mouse-click or a
non-ASCII character chord.)

The new variable `last-command-event' holds an event object, that could be
a non-ASCII character, a button click, a menu selection, etc.

The variable `unread-command-char' no longer exists, and has been replaced
by `unread-command-events'.  With the new event model, it is incorrect for
code to do (setq unread-command-char (read-char)), because all user-input
can't be represented as ASCII characters.  *** This is an incompatible 
change.  Code which sets `unread-command-char' must be updated to use the
combination of `next-command-event' and `unread-command-events' instead.

The functions `this-command-keys' and `recent-keys' return a vector of
event objects, instead of a string of ASCII characters.  *** This also
is an incompatible change.

Almost nothing happens at interrupt level; the SIGIO handler simply sets a
flag, and later, the X event queue is scanned for KeyPress events which map
to ^G.  All redisplay happens in the main thread of the process.


*** Keymaps
-----------

Instead of keymaps being alists or obarrays, they are a new primary data
type.  The only user access to the contents of a keymap is through the
existing keymap-manipulation functions, and a new function, map-keymap.
This means that existing code that manipulates keymaps may need to 
be changed.

One of our goals with the new input and keymap code was to make more
character combinations available for binding, besides just ASCII and
function keys.  We want to be able bind different commands to Control-a 
and Control-Shift-a; we also want it to be possible for the keys Control-h
and Backspace (and Control-M and Return, and Control-I and Tab, etc) to
be distinct.

One of the most common complaints that new Emacs users have is that backspace
is help.  The answer is to play around with the keyboard-translate-table, or
be lucky enough to have a system administrator who has done this for you
already; but if it were possible to bind backspace and C-h to different
things, then (under a window manager at least) both backspace and delete
aps/icons in buffers, `undo' did not
restore changes to regions, regions did not overlap and merge their
attributes in the way we needed, and several other things.

We could have devoted our time to making Epoch do what we needed (and, in
fact, we spent some time doing that in 1990) but, since the Free Software
Foundation planned to include Epoch-like features in their Version 19, we
decided that our efforts would be better spent improving GNU Emacs
instead of Epoch.

Our original hope was that our changes to GNU Emacs would be
incorporated into the "official" v19.  However, scheduling conflicts arose,
and we found that, given the amount of work still remaining to be done, we
didn't have the time or manpower to do the level of coordination that would
be necessary to get our changes accepted by the Free Software Foundation.
Consequently, we released our work as a forked branch of Emacs, instead of
delaying any longer.

Roughly a year after Lucid Emacs 19.0 was released, a beta version of the
Free Software Foundation branch of Emacs 19 was released.  This version
was better in some areas, and worse in others, as reflects the differing
focus of our development efforts.

We planned to continue developing and supporting Lucid Emacs, and merging in
bug fixes and new features from the Free Software Foundation branch as
appropriate; we did not plan to discard any of the functionality that we
implemented which Richard Stallman of the Free Software Foundation has
chosen not to include in his version.

However, events have overtaken us, and Lucid, Inc. has effectively ceased
doing business and is (September 1994) in the process of being sold.  Our
efforts on Lucid Emacs have also ceased and we've turned over the continued
enhancement of Lucid Emacs to the University of Illinois under Chuck
Thompson, a member of the Lucid Emacs team and a maintainer of Epoch.
At the same time, Lucid Emacs has been renamed XEmacs to reflect the
substantial contribution of the University of Illinois with the support of
Sun Microsystems.

Certain elements of Lucid Emacs, or derivatives of them, have been ported to
the FSF GNU Emacs.  We have not been doing work in this direction, because
we feel that Lucid Emacs has a cleaner and more extensible substrate, and
that any kind of merger between the two branches would be far easier by
merging the Free Software Foundation changes into our version than the other
way around.

We were working closely with the Epoch developers to merge in the
remaining Epoch functionality which Lucid Emacs does not yet have.  Epoch
and Lucid Emacs will soon be one and the same thing.  Work is being done on
a compatibility package which will allow Epoch 4 code to run in XEmacs with
little or no change.  (As of 19.8, Lucid Emacs is running a descendant of
the Epoch redisplay engine.)

** Why Another Version of Emacs?  (The SunPro Point of View)
============================================================

Emacs 18 has been around for a long, long time.  Version 19 was supposed to
be the successor to Emacs 18 with X support.  It was going to be available
"real soon" for a long time (some people remember hearing about v19 as early
as 1984!), but it never came out.  v19 development was going very, very
slowly, and from the outside it seemed that it was not moving at all.  In
the meantime other people gave up waiting for v19 and decided to build their
own X-aware Emacsen.  The most important of these was probably Epoch, which
came from the University of Illinois and was based on v18.

Around three years ago we decided that we wanted an integrated editor.  We
contracted with the University of Illinois to provide a number of basic
enhancements to the functionality in Epoch.  The University of Illinois
initially was planning to deliver this on top of Epoch code.

In the meantime (actually some time before we talked with the University of
Illinois) Lucid had decided that it also wanted to provide an integrated
environment with an integrated editor.  Lucid decided that the Version 19
basis was a better one than Version 18 and thus decided not to use Epoch but
instead work with Richard Stallman, the head of the Free Software Foundation
and principle author of Emacs, on getting Version 19 out.  At some point
Stallman and Lucid parted ways.  Lucid kept working and got a Version 19 out
that they called Lucid Emacs 19.

After Lucid's v19 came out it became clear to us (the University of Illinois
and SunPro) that the right thing to do was to push for an integration of
both Lucid Emacs and Epoch, and to get the deliverables that we were asking
from the University of Illinois on top of this integrated platform.  Through
the last two years, SunPro has been actively supporting this product and has
been investing a comparable amount of effort into it as Lucid has.
Substantial portions of the current code have originated under the support
of SunPro, either directly in SunPro, or in the University of Illinois but
paid for by us.  This code was kept away from Lucid for a while, but later
was made available to them.  Initially Lucid didn't know that we were
supporting UofI, but later we were open about it.

Eventually, all development source trees were synched up.  Currently, there
is basically no difference in the source trees between what is at the
University of Illinois and SunPro.

SunPro originally called the integrated product ERA, for "Emacs Rewritten
Again".  At some point, SunPro and Lucid came to an agreement to find a name
for the product that was not specific to either company.  An additional
constraint that Lucid placed on the name was that it must contain the word
"Emacs" in it -- thus "ERA" was not acceptable.  The agreed-upon name was
"XEmacs", and this is what the product has been called starting with the
19.11 release.


* What's Different?
===================


** Differences between XEmacs and FSF GNU Emacs 19
==================================================

In XEmacs, events are first-class objects.  FSF 19 represents them as
integers, which obscures the differences between a key gesture and the
ancient ASCII code used to represent a particular overlapping subset of them.

In XEmacs, keymaps are first-class opaque objects.  FSF 19 represents them as
complicated combinations of association lists and vectors.  If you use the
advertised functional interface to manipulation of keymaps, the same code
will work in XEmacs, Emacs 18, and and FSF GNU Emacs 19; if your code depends
on the underlying implementation of keymaps, it will not.

XEmacs uses "extents" to represent all non-textual aspects of buffers;
FSF 19 uses two distinct objects, "text properties" and "overlays",
which divide up the functionality between them.  Extents are a
superset of the functionality of the two FSF data types.  The full FSF
19 interface to text properties is supported in XEmacs (with extents
being the underlying representation).

Extents can be made to be copied into strings, and thus restored by kill
and yank.  Thus, one can specify this behavior on either "extents" or
"text properties", whereas in FSF 19 text properties always have this
behavior and overlays never do.

Many more packages are provided standard with XEmacs than with FSF 19.

Pixmaps of arbitrary size can be embedded in a buffer.

Variable width fonts work.

The height of a line is the height of the tallest font on that line, instead
of all lines having the same height.

XEmacs uses the MIT "Xt" toolkit instead of raw Xlib calls, which
makes it be a more well-behaved X citizen (and also improves
portability).  A result of this is that it is possible to include
other Xt "Widgets" in the XEmacs window.  Also, XEmacs understands the
standard Xt command-line arguments.

XEmacs provides support for ToolTalk on systems that have it.

XEmacs can ask questions using popup dialog boxes.  Any command executed from
a menu will ask yes/no questions with dialog boxes, while commands executed
via the keyboard will use the minibuffer.

XEmacs has a built-in toolbar.  Four toolbars can actually be configured:
top, bottom, left, and right toolbars.

XEmacs has vertical and horizontal scrollbars.  Unlike in FSF 19 (which
provides a primitive form of vertical scrollbar), these are true toolkit
scrollbars.  A look-alike Motif scrollbar is provided for those who
don't have Motif. (Even for those who do, the look-alike may be preferable
as it is faster.)

If you're running on a machine with audio hardware, you can specify sound 
files for XEmacs to play instead of the default X beep.  See the documentation
of the function load-sound-file and the variable sound-alist.

An XEmacs frame can be placed within an "external client widget" managed by
another application.  This allows an application to use an XEmacs frame as its
text pane rather than the standard Text widget that is provided with Motif or
Athena.  XEmacs supports Motif applications, generic Xt (e.g. Athena)
applications, and raw Xlib applications.

Here are some more specifics about the XEmacs implementation:

*** The Input Model
-------------------

The fundamental unit of input is an "event" instead of a character.  An
event is a new data type that contains several pieces of information.
There are several kinds of event, and corresponding accessor and utility
functions.  We tried to abstract them so that they would apply equally
well to a number of window systems.

NOTE: All timestamps are measured as milliseconds since Emacs started.

 key_press_event	
    event_channel	A token representing which keyboard generated it.
			For this kind of event, this is a frame object.
			(This is for eventual support of multiple displays.)
    timestamp		When it happened
    key			What keysym this is; an integer or a symbol.
			If this is an integer, it will be in the printing
			ASCII range: >32 and <127.
    modifiers		Bucky-bits on that key: control, meta, etc.
			For most keys, Shift is not a bit; that is implicit
			in the keyboard layout.

 button_press_event
 button_release_event
    event_channel	A token representing which mouse generated it.
			For this kind of event, this is a frame object.
    timestamp		When it happened
    button		What button went down or up.
    modifiers		Bucky-bits on that button: shift, control, meta, etc.
    x, y		Where it was at the button-state-change (in pixels).

 pointer_motion_event
    event_channel	A token representing which mouse generated it.
			For this kind of event, this is a frame object.
    timestamp		When it happened
    x, y		Where it was after it moved (in pixels).
    modifiers		Bucky-bits down when the motion was detected.
			(Possibly not all window systems will provide this?)

 process_event
    timestamp		When it happened
    process		the emacs "process" object in question

 timeout_event
    timestamp		Now (really, when the timeout was signaled)
    interval_id		The ID returned when the associated call to
			add_timeout_cb() was made
	------ the rest of the fields are filled in by Emacs -----
    id_number		The Emacs timeout ID for this timeout (more
			than one timeout event can have the same value
			here, since Emacs timeouts, as opposed to
			add_timeout_cb() timeouts, can resignal
			themselves)
    function		An elisp function to call when this timeout is
			processed.
    object		The object passed to that function.

 eval_event
    timestamp		When it happened
    function		An elisp function to call with this event object.
    object		Anything.
			This kind of event is used internally; sometimes the
			window system interface would like to inform emacs of
			some user action (such as focusing on another frame)
			but needs that to happen synchronously with the other
			user input, like keypresses.  This is useful when
			events are reported through callbacks rather
			than in the standard event stream.

 misc_user_event
    timestamp		When it happened
    function		An elisp function to call with this event object.
    object		Anything.
			This is similar to an eval_event, except that it is
			generated by user actions: selections in the
			menubar or scrollbar actions.  It is a "command"
			event, like key and mouse presses (and unlike mouse
			motion, process output, and enter and leave window
			hooks).  In many ways, eval_events are not the same
			as keypresses or misc_user_events.

 magic_event
			No user-serviceable parts within.  This is for things
			like KeymapNotify and ExposeRegion events and so on
			that emacs itself doesn't care about, but which it
			must do something with for proper interaction with
			the window system.

			Magic_events are handled somewhat asynchronously, just
			like subprocess filters.  However, occasionally a 
			magic_event needs to be handled synchronously; in that
			case, the asynchronous handling of the magic_event will
			push an eval_event back onto the queue, which will be 
			handled synchronously later.  This is one of the
			reasons why eval_events exist; I'm not entirely happy
			with this aspect of this event model.


The function `next-event' blocks and returns one of the above-described 
event objects.  The function `dispatch-event' takes an event and processes
it in the appropriate way.

For a process-event, dispatch-event calls the process's handler; for a
mouse-motion event, the mouse-motion-handler hook is called, and so on.
For magic-events, dispatch-event does window-system-dependent things,
including calling some non-window-system-dependent hooks: map-frame-hook,
unmap-frame-hook, mouse-enter-frame-hook, and mouse-leave-frame-hook.

The function `next-command-event' calls `next-event' until it gets a key or
button from the user (that is, not a process, motion, timeout, or magic
event).  If it gets an event that is not a key or button, it calls
`dispatch-event' on it immediately and reads another one.  The
next-command-event function could be implemented in Emacs Lisp, though it
isn't.  Generally one should call `next-command-event' instead of
`next-event'.

read-char calls next-command-event; if it doesn't get an event that can be
converted to an ASCII character, it signals an error.  Otherwise it returns
an integer.

The variable `last-command-char' always contains an integer, or nil (if the
last read event has no ASCII equivalent, as when it is a mouse-click or a
non-ASCII character chord.)

The new variable `last-command-event' holds an event object, that could be
a non-ASCII character, a button click, a menu selection, etc.

The variable `unread-command-char' no longer exists, and has been replaced
by `unread-command-events'.  With the new event model, it is incorrect for
code to do (setq unread-command-char (read-char)), because all user-input
can't be represented as ASCII characters.  *** This is an incompatible 
change.  Code which sets `unread-command-char' must be updated to use the
combination of `next-command-event' and `unread-command-events' instead.

The functions `this-command-keys' and `recent-keys' return a vector of
event objects, instead of a string of ASCII characters.  *** This also
is an incompatible change.

Almost nothing happens at interrupt level; the SIGIO handler simply sets a
flag, and later, the X event queue is scanned for KeyPress events which map
to ^G.  All redisplay happens in the main thread of the process.


*** Keymaps
-----------

Instead of keymaps being alists or obarrays, they are a new primary data
type.  The only user access to the contents of a keymap is through the
existing keymap-manipulation functions, and a new function, map-keymap.
This means that existing code that manipulates keymaps may need to 
be changed.

One of our goals with the new input and keymap code was to make more
character combinations available for binding, besides just ASCII and
function keys.  We want to be able bind different commands to Control-a 
and Control-Shift-a; we also want it to be possible for the keys Control-h
and Backspace (and Control-M and Return, and Control-I and Tab, etc) to
be distinct.

One of the most common complaints that new Emacs users have is that backspace
is help.  The answer is to play around with the keyboard-translate-table, or
be lucky enough to have a system administrator who has done this for you
already; but if it were possible to bind backspace and C-h to different
things, then (under a window manager at least) both backspace and delete
aps/icons in buffers, `undo' did not
restore changes to regions, regions did not overlap and merge their
attributes in the way we needed, and several other things.

We could have devoted our time to making Epoch do what we needed (and, in
fact, we spent some time doing that in 1990) but, since the Free Software
Foundation planned to include Epoch-like features in their Version 19, we
decided that our efforts would be better spent improving GNU Emacs
instead of Epoch.

Our original hope was that our changes to GNU Emacs would be
incorporated into the "official" v19.  However, scheduling conflicts arose,
and we found that, given the amount of work still remaining to be done, we
didn't have the time or manpower to do the level of coordination that would
be necessary to get our changes accepted by the Free Software Foundation.
Consequently, we released our work as a forked branch of Emacs, instead of
delaying any longer.

Roughly a year after Lucid Emacs 19.0 was released, a beta version of the
Free Software Foundation branch of Emacs 19 was released.  This version
was better in some areas, and worse in others, as reflects the differing
focus of our development efforts.

We planned to continue developing and supporting Lucid Emacs, and merging in
bug fixes and new features from the Free Software Foundation branch as
appropriate; we did not plan to discard any of the functionality that we
implemented which Richard Stallman of the Free Software Foundation has
chosen not to include in his version.

However, events have overtaken us, and Lucid, Inc. has effectively ceased
doing business and is (September 1994) in the process of being sold.  Our
efforts on Lucid Emacs have also ceased and we've turned over the continued
enhancement of Lucid Emacs to the University of Illinois under Chuck
Thompson, a member of the Lucid Emacs team and a maintainer of Epoch.
At the same time, Lucid Emacs has been renamed XEmacs to reflect the
substantial contribution of the University of Illinois with the support of
Sun Microsystems.

Certain elements of Lucid Emacs, or derivatives of them, have been ported to
the FSF GNU Emacs.  We have not been doing work in this direction, because
we feel that Lucid Emacs has a cleaner and more extensible substrate, and
that any kind of merger between the two branches would be far easier by
merging the Free Software Foundation changes into our version than the other
way around.

We were working closely with the Epoch developers to merge in the
remaining Epoch functionality which Lucid Emacs does not yet have.  Epoch
and Lucid Emacs will soon be one and the same thing.  Work is being done on
a compatibility package which will allow Epoch 4 code to run in XEmacs with
little or no change.  (As of 19.8, Lucid Emacs is running a descendant of
the Epoch redisplay engine.)

** Why Another Version of Emacs?  (The SunPro Point of View)
============================================================

Emacs 18 has been around for a long, long time.  Version 19 was supposed to
be the successor to Emacs 18 with X support.  It was going to be available
"real soon" for a long time (some people remember hearing about v19 as early
as 1984!), but it never came out.  v19 development was going very, very
slowly, and from the outside it seemed that it was not moving at all.  In
the meantime other people gave up waiting for v19 and decided to build their
own X-aware Emacsen.  The most important of these was probably Epoch, which
came from the University of Illinois and was based on v18.

Around three years ago we decided that we wanted an integrated editor.  We
contracted with the University of Illinois to provide a number of basic
enhancements to the functionality in Epoch.  The University of Illinois
initially was planning to deliver this on top of Epoch code.

In the meantime (actually some time before we talked with the University of
Illinois) Lucid had decided that it also wanted to provide an integrated
environment with an integrated editor.  Lucid decided that the Version 19
basis was a better one than Version 18 and thus decided not to use Epoch but
instead work with Richard Stallman, the head of the Free Software Foundation
and principle author of Emacs, on getting Version 19 out.  At some point
Stallman and Lucid parted ways.  Lucid kept working and got a Version 19 out
that they called Lucid Emacs 19.

After Lucid's v19 came out it became clear to us (the University of Illinois
and SunPro) that the right thing to do was to push for an integration of
both Lucid Emacs and Epoch, and to get the deliverables that we were asking
from the University of Illinois on top of this integrated platform.  Through
the last two years, SunPro has been actively supporting this product and has
been investing a comparable amount of effort into it as Lucid has.
Substantial portions of the current code have originated under the support
of SunPro, either directly in SunPro, or in the University of Illinois but
paid for by us.  This code was kept away from Lucid for a while, but later
was made available to them.  Initially Lucid didn't know that we were
supporting UofI, but later we were open about it.

Eventually, all development source trees were synched up.  Currently, there
is basically no difference in the source trees between what is at the
University of Illinois and SunPro.

SunPro originally called the integrated product ERA, for "Emacs Rewritten
Again".  At some point, SunPro and Lucid came to an agreement to find a name
for the product that was not specific to either company.  An additional
constraint that Lucid placed on the name was that it must contain the word
"Emacs" in it -- thus "ERA" was not acceptable.  The agreed-upon name was
"XEmacs", and this is what the product has been called starting with the
19.11 release.


* What's Different?
===================


** Differences between XEmacs and FSF GNU Emacs 19
==================================================

In XEmacs, events are first-class objects.  FSF 19 represents them as
integers, which obscures the differences between a key gesture and the
ancient ASCII code used to represent a particular overlapping subset of them.

In XEmacs, keymaps are first-class opaque objects.  FSF 19 represents them as
complicated combinations of association lists and vectors.  If you use the
advertised functional interface to manipulation of keymaps, the same code
will work in XEmacs, Emacs 18, and and FSF GNU Emacs 19; if your code depends
on the underlying implementation of keymaps, it will not.

XEmacs uses "extents" to represent all non-textual aspects of buffers;
FSF 19 uses two distinct objects, "text properties" and "overlays",
which divide up the functionality between them.  Extents are a
superset of the functionality of the two FSF data types.  The full FSF
19 interface to text properties is supported in XEmacs (with extents
being the underlying representation).

Extents can be made to be copied into strings, and thus restored by kill
and yank.  Thus, one can specify this behavior on either "extents" or
"text properties", whereas in FSF 19 text properties always have this
behavior and overlays never do.

Many more packages are provided standard with XEmacs than with FSF 19.

Pixmaps of arbitrary size can be embedded in a buffer.

Variable width fonts work.

The height of a line is the height of the tallest font on that line, instead
of all lines having the same height.

XEmacs uses the MIT "Xt" toolkit instead of raw Xlib calls, which
makes it be a more well-behaved X citizen (and also improves
portability).  A result of this is that it is possible to include
other Xt "Widgets" in the XEmacs window.  Also, XEmacs understands the
standard Xt command-line arguments.

XEmacs provides support for ToolTalk on systems that have it.

XEmacs can ask questions using popup dialog boxes.  Any command executed from
a menu will ask yes/no questions with dialog boxes, while commands executed
via the keyboard will use the minibuffer.

XEmacs has a built-in toolbar.  Four toolbars can actually be configured:
top, bottom, left, and right toolbars.

XEmacs has vertical and horizontal scrollbars.  Unlike in FSF 19 (which
provides a primitive form of vertical scrollbar), these are true toolkit
scrollbars.  A look-alike Motif scrollbar is provided for those who
don't have Motif. (Even for those who do, the look-alike may be preferable
as it is faster.)

If you're running on a machine with audio hardware, you can specify sound 
files for XEmacs to play instead of the default X beep.  See the documentation
of the function load-sound-file and the variable sound-alist.

An XEmacs frame can be placed within an "external client widget" managed by
another application.  This allows an application to use an XEmacs frame as its
text pane rather than the standard Text widget that is provided with Motif or
Athena.  XEmacs supports Motif applications, generic Xt (e.g. Athena)
applications, and raw Xlib applications.

Here are some more specifics about the XEmacs implementation:

*** The Input Model
-------------------

The fundamental unit of input is an "event" instead of a character.  An
event is a new data type that contains several pieces of information.
There are several kinds of event, and corresponding accessor and utility
functions.  We tried to abstract them so that they would apply equally
well to a number of window systems.

NOTE: All timestamps are measured as milliseconds since Emacs started.

 key_press_event	
    event_channel	A token representing which keyboard generated it.
			For this kind of event, this is a frame object.
			(This is for eventual support of multiple displays.)
    timestamp		When it happened
    key			What keysym this is; an integer or a symbol.
			If this is an integer, it will be in the printing
			ASCII range: >32 and <127.
    modifiers		Bucky-bits on that key: control, meta, etc.
			For most keys, Shift is not a bit; that is implicit
			in the keyboard layout.

 button_press_event
 button_release_event
    event_channel	A token representing which mouse generated it.
			For this kind of event, this is a frame object.
    timestamp		When it happened
    button		What button went down or up.
    modifiers		Bucky-bits on that button: shift, control, meta, etc.
    x, y		Where it was at the button-state-change (in pixels).

 pointer_motion_event
    event_channel	A token representing which mouse generated it.
			For this kind of event, this is a frame object.
    timestamp		When it happened
    x, y		Where it was after it moved (in pixels).
    modifiers		Bucky-bits down when the motion was detected.
			(Possibly not all window systems will provide this?)

 process_event
    timestamp		When it happened
    process		the emacs "process" object in question

 timeout_event
    timestamp		Now (really, when the timeout was signaled)
    interval_id		The ID returned when the associated call to
			add_timeout_cb() was made
	------ the rest of the fields are filled in by Emacs -----
    id_number		The Emacs timeout ID for this timeout (more
			than one timeout event can have the same value
			here, since Emacs timeouts, as opposed to
			add_timeout_cb() timeouts, can resignal
			themselves)
    function		An elisp function to call when this timeout is
			processed.
    object		The object passed to that function.

 eval_event
    timestamp		When it happened
    function		An elisp function to call with this event object.
    object		Anything.
			This kind of event is used internally; sometimes the
			window system interface would like to inform emacs of
			some user action (such as focusing on another frame)
			but needs that to happen synchronously with the other
			user input, like keypresses.  This is useful when
			events are reported through callbacks rather
			than in the standard event stream.

 misc_user_event
    timestamp		When it happened
    function		An elisp function to call with this event object.
    object		Anything.
			This is similar to an eval_event, except that it is
			generated by user actions: selections in the
			menubar or scrollbar actions.  It is a "command"
			event, like key and mouse presses (and unlike mouse
			motion, process output, and enter and leave window
			hooks).  In many ways, eval_events are not the same
			as keypresses or misc_user_events.

 magic_event
			No user-serviceable parts within.  This is for things
			like KeymapNotify and ExposeRegion events and so on
			that emacs itself doesn't care about, but which it
			must do something with for proper interaction with
			the window system.

			Magic_events are handled somewhat asynchronously, just
			like subprocess filters.  However, occasionally a 
			magic_event needs to be handled synchronously; in that
			case, the asynchronous handling of the magic_event will
			push an eval_event back onto the queue, which will be 
			handled synchronously later.  This is one of the
			reasons why eval_events exist; I'm not entirely happy
			with this aspect of this event model.


The function `next-event' blocks and returns one of the above-described 
event objects.  The function `dispatch-event' takes an event and processes
it in the appropriate way.

For a process-event, dispatch-event calls the process's handler; for a
mouse-motion event, the mouse-motion-handler hook is called, and so on.
For magic-events, dispatch-event does window-system-dependent things,
including calling some non-window-system-dependent hooks: map-frame-hook,
unmap-frame-hook, mouse-enter-frame-hook, and mouse-leave-frame-hook.

The function `next-command-event' calls `next-event' until it gets a key or
button from the user (that is, not a process, motion, timeout, or magic
event).  If it gets an event that is not a key or button, it calls
`dispatch-event' on it immediately and reads another one.  The
next-command-event function could be implemented in Emacs Lisp, though it
isn't.  Generally one should call `next-command-event' instead of
`next-event'.

read-char calls next-command-event; if it doesn't get an event that can be
converted to an ASCII character, it signals an error.  Otherwise it returns
an integer.

The variable `last-command-char' always contains an integer, or nil (if the
last read event has no ASCII equivalent, as when it is a mouse-click or a
non-ASCII character chord.)

The new variable `last-command-event' holds an event object, that could be
a non-ASCII character, a button click, a menu selection, etc.

The variable `unread-command-char' no longer exists, and has been replaced
by `unread-command-events'.  With the new event model, it is incorrect for
code to do (setq unread-command-char (read-char)), because all user-input
can't be represented as ASCII characters.  *** This is an incompatible 
change.  Code which sets `unread-command-char' must be updated to use the
combination of `next-command-event' and `unread-command-events' instead.

The functions `this-command-keys' and `recent-keys' return a vector of
event objects, instead of a string of ASCII characters.  *** This also
is an incompatible change.

Almost nothing happens at interrupt level; the SIGIO handler simply sets a
flag, and later, the X event queue is scanned for KeyPress events which map
to ^G.  All redisplay happens in the main thread of the process.


*** Keymaps
-----------

Instead of keymaps being alists or obarrays, they are a new primary data
type.  The only user access to the contents of a keymap is through the
existing keymap-manipulation functions, and a new function, map-keymap.
This means that existing code that manipulates keymaps may need to 
be changed.

One of our goals with the new input and keymap code was to make more
character combinations available for binding, besides just ASCII and
function keys.  We want to be able bind different commands to Control-a 
and Control-Shift-a; we also want it to be possible for the keys Control-h
and Backspace (and Control-M and Return, and Control-I and Tab, etc) to
be distinct.

One of the most common complaints that new Emacs users have is that backspace
is help.  The answer is to play around with the keyboard-translate-table, or
be lucky enough to have a system administrator who has done this for you
already; but if it were possible to bind backspace and C-h to different
things, then (under a window manager at least) both backspace and delete
aps/icons in buffers, `undo' did not
restore changes to regions, regions did not overlap and merge their
attributes in the way we needed, and several other things.

We could have devoted our time to making Epoch do what we needed (and, in
fact, we spent some time doing that in 1990) but, since the Free Software
Foundation planned to include Epoch-like features in their Version 19, we
decided that our efforts would be better spent improving GNU Emacs
instead of Epoch.

Our original hope was that our changes to GNU Emacs would be
incorporated into the "official" v19.  However, scheduling conflicts arose,
and we found that, given the amount of work still remaining to be done, we
didn't have the time or manpower to do the level of coordination that would
be necessary to get our changes accepted by the Free Software Foundation.
Consequently, we released our work as a forked branch of Emacs, instead of
delaying any longer.

Roughly a year after Lucid Emacs 19.0 was released, a beta version of the
Free Software Foundation branch of Emacs 19 was released.  This version
was better in some areas, and worse in others, as reflects the differing
focus of our development efforts.

We planned to continue developing and supporting Lucid Emacs, and merging in
bug fixes and new features from the Free Software Foundation branch as
appropriate; we did not plan to discard any of the functionality that we
implemented which Richard Stallman of the Free Software Foundation has
chosen not to include in his version.

However, events have overtaken us, and Lucid, Inc. has effectively ceased
doing business and is (September 1994) in the process of being sold.  Our
efforts on Lucid Emacs have also ceased and we've turned over the continued
enhancement of Lucid Emacs to the University of Illinois under Chuck
Thompson, a member of the Lucid Emacs team and a maintainer of Epoch.
At the same time, Lucid Emacs has been renamed XEmacs to reflect the
substantial contribution of the University of Illinois with the support of
Sun Microsystems.

Certain elements of Lucid Emacs, or derivatives of them, have been ported to
the FSF GNU Emacs.  We have not been doing work in this direction, because
we feel that Lucid Emacs has a cleaner and more extensible substrate, and
that any kind of merger between the two branches would be far easier by
merging the Free Software Foundation changes into our version than the other
way around.

We were working closely with the Epoch developers to merge in the
remaining Epoch functionality which Lucid Emacs does not yet have.  Epoch
and Lucid Emacs will soon be one and the same thing.  Work is being done on
a compatibility package which will allow Epoch 4 code to run in XEmacs with
little or no change.  (As of 19.8, Lucid Emacs is running a descendant of
the Epoch redisplay engine.)

** Why Another Version of Emacs?  (The SunPro Point of View)
============================================================

Emacs 18 has been around for a long, long time.  Version 19 was supposed to
be the successor to Emacs 18 with X support.  It was going to be available
"real soon" for a long time (some people remember hearing about v19 as early
as 1984!), but it never came out.  v19 development was going very, very
slowly, and from the outside it seemed that it was not moving at all.  In
the meantime other people gave up waiting for v19 and decided to build their
own X-aware Emacsen.  The most important of these was probably Epoch, which
came from the University of Illinois and was based on v18.

Around three years ago we decided that we wanted an integrated editor.  We
contracted with the University of Illinois to provide a number of basic
enhancements to the functionality in Epoch.  The University of Illinois
initially was planning to deliver this on top of Epoch code.

In the meantime (actually some time before we talked with the University of
Illinois) Lucid had decided that it also wanted to provide an integrated
environment with an integrated editor.  Lucid decided that the Version 19
basis was a better one than Version 18 and thus decided not to use Epoch but
instead work with Richard Stallman, the head of the Free Software Foundation
and principle author of Emacs, on getting Version 19 out.  At some point
Stallman and Lucid parted ways.  Lucid kept working and got a Version 19 out
that they called Lucid Emacs 19.

After Lucid's v19 came out it became clear to us (the University of Illinois
and SunPro) that the right thing to do was to push for an integration of
both Lucid Emacs and Epoch, and to get the deliverables that we were asking
from the University of Illinois on top of this integrated platform.  Through
the last two years, SunPro has been actively supporting this product and has
been investing a comparable amount of effort into it as Lucid has.
Substantial portions of the current code have originated under the support
of SunPro, either directly in SunPro, or in the University of Illinois but
paid for by us.  This code was kept away from Lucid for a while, but later
was made available to them.  Initially Lucid didn't know that we were
supporting UofI, but later we were open about it.

Eventually, all development source trees were synched up.  Currently, there
is basically no difference in the source trees between what is at the
University of Illinois and SunPro.

SunPro originally called the integrated product ERA, for "Emacs Rewritten
Again".  At some point, SunPro and Lucid came to an agreement to find a name
for the product that was not specific to either company.  An additional
constraint that Lucid placed on the name was that it must contain the word
"Emacs" in it -- thus "ERA" was not acceptable.  The agreed-upon name was
"XEmacs", and this is what the product has been called starting with the
19.11 release.


* What's Different?
===================


** Differences between XEmacs and FSF GNU Emacs 19
==================================================

In XEmacs, events are first-class objects.  FSF 19 represents them as
integers, which obscures the differences between a key gesture and the
ancient ASCII code used to represent a particular overlapping subset of them.

In XEmacs, keymaps are first-class opaque objects.  FSF 19 represents them as
complicated combinations of association lists and vectors.  If you use the
advertised functional interface to manipulation of keymaps, the same code
will work in XEmacs, Emacs 18, and and FSF GNU Emacs 19; if your code depends
on the underlying implementation of keymaps, it will not.

XEmacs uses "extents" to represent all non-textual aspects of buffers;
FSF 19 uses two distinct objects, "text properties" and "overlays",
which divide up the functionality between them.  Extents are a
superset of the functionality of the two FSF data types.  The full FSF
19 interface to text properties is supported in XEmacs (with extents
being the underlying representation).

Extents can be made to be copied into strings, and thus restored by kill
and yank.  Thus, one can specify this behavior on either "extents" or
"text properties", whereas in FSF 19 text properties always have this
behavior and overlays never do.

Many more packages are provided standard with XEmacs than with FSF 19.

Pixmaps of arbitrary size can be embedded in a buffer.

Variable width fonts work.

The height of a line is the height of the tallest font on that line, instead
of all lines having the same height.

XEmacs uses the MIT "Xt" toolkit instead of raw Xlib calls, which
makes it be a more well-behaved X citizen (and also improves
portability).  A result of this is that it is possible to include
other Xt "Widgets" in the XEmacs window.  Also, XEmacs understands the
standard Xt command-line arguments.

XEmacs provides support for ToolTalk on systems that have it.

XEmacs can ask questions using popup dialog boxes.  Any command executed from
a menu will ask yes/no questions with dialog boxes, while commands executed
via the keyboard will use the minibuffer.

XEmacs has a built-in toolbar.  Four toolbars can actually be configured:
top, bottom, left, and right toolbars.

XEmacs has vertical and horizontal scrollbars.  Unlike in FSF 19 (which
provides a primitive form of vertical scrollbar), these are true toolkit
scrollbars.  A look-alike Motif scrollbar is provided for those who
don't have Motif. (Even for those who do, the look-alike may be preferable
as it is faster.)

If you're running on a machine with audio hardware, you can specify sound 
files for XEmacs to play instead of the default X beep.  See the documentation
of the function load-sound-file and the variable sound-alist.

An XEmacs frame can be placed within an "external client widget" managed by
another application.  This allows an application to use an XEmacs frame as its
text pane rather than the standard Text widget that is provided with Motif or
Athena.  XEmacs supports Motif applications, generic Xt (e.g. Athena)
applications, and raw Xlib applications.

Here are some more specifics about the XEmacs implementation:

*** The Input Model
-------------------

The fundamental unit of input is an "event" instead of a character.  An
event is a new data type that contains several pieces of information.
There are several kinds of event, and corresponding accessor and utility
functions.  We tried to abstract them so that they would apply equally
well to a number of window systems.

NOTE: All timestamps are measured as milliseconds since Emacs started.

 key_press_event	
    event_channel	A token representing which keyboard generated it.
			For this kind of event, this is a frame object.
			(This is for eventual support of multiple displays.)
    timestamp		When it happened
    key			What keysym this is; an integer or a symbol.
			If this is an integer, it will be in the printing
			ASCII range: >32 and <127.
    modifiers		Bucky-bits on that key: control, meta, etc.
			For most keys, Shift is not a bit; that is implicit
			in the keyboard layout.

 button_press_event
 button_release_event
    event_channel	A token representing which mouse generated it.
			For this kind of event, this is a frame object.
    timestamp		When it happened
    button		What button went down or up.
    modifiers		Bucky-bits on that button: shift, control, meta, etc.
    x, y		Where it was at the button-state-change (in pixels).

 pointer_motion_event
    event_channel	A token representing which mouse generated it.
			For this kind of event, this is a frame object.
    timestamp		When it happened
    x, y		Where it was after it moved (in pixels).
    modifiers		Bucky-bits down when the motion was detected.
			(Possibly not all window systems will provide this?)

 process_event
    timestamp		When it happened
    process		the emacs "process" object in question

 timeout_event
    timestamp		Now (really, when the timeout was signaled)
    interval_id		The ID returned when the associated call to
			add_timeout_cb() was made
	------ the rest of the fields are filled in by Emacs -----
    id_number		The Emacs timeout ID for this timeout (more
			than one timeout event can have the same value
			here, since Emacs timeouts, as opposed to
			add_timeout_cb() timeouts, can resignal
			themselves)
    function		An elisp function to call when this timeout is
			processed.
    object		The object passed to that function.

 eval_event
    timestamp		When it happened
    function		An elisp function to call with this event object.
    object		Anything.
			This kind of event is used internally; sometimes the
			window system interface would like to inform emacs of
			some user action (such as focusing on another frame)
			but needs that to happen synchronously with the other
			user input, like keypresses.  This is useful when
			events are reported through callbacks rather
			than in the standard event stream.

 misc_user_event
    timestamp		When it happened
    function		An elisp function to call with this event object.
    object		Anything.
			This is similar to an eval_event, except that it is
			generated by user actions: selections in the
			menubar or scrollbar actions.  It is a "command"
			event, like key and mouse presses (and unlike mouse
			motion, process output, and enter and leave window
			hooks).  In many ways, eval_events are not the same
			as keypresses or misc_user_events.

 magic_event
			No user-serviceable parts within.  This is for things
			like KeymapNotify and ExposeRegion events and so on
			that emacs itself doesn't care about, but which it
			must do something with for proper interaction with
			the window system.

			Magic_events are handled somewhat asynchronously, just
			like subprocess filters.  However, occasionally a 
			magic_event needs to be handled synchronously; in that
			case, the asynchronous handling of the magic_event will
			push an eval_event back onto the queue, which will be 
			handled synchronously later.  This is one of the
			reasons why eval_events exist; I'm not entirely happy
			with this aspect of this event model.


The function `next-event' blocks and returns one of the above-described 
event objects.  The function `dispatch-event' takes an event and processes
it in the appropriate way.

For a process-event, dispatch-event calls the process's handler; for a
mouse-motion event, the mouse-motion-handler hook is called, and so on.
For magic-events, dispatch-event does window-system-dependent things,
including calling some non-window-system-dependent hooks: map-frame-hook,
unmap-frame-hook, mouse-enter-frame-hook, and mouse-leave-frame-hook.

The function `next-command-event' calls `next-event' until it gets a key or
button from the user (that is, not a process, motion, timeout, or magic
event).  If it gets an event that is not a key or button, it calls
`dispatch-event' on it immediately and reads another one.  The
next-command-event function could be implemented in Emacs Lisp, though it
isn't.  Generally one should call `next-command-event' instead of
`next-event'.

read-char calls next-command-event; if it doesn't get an event that can be
converted to an ASCII character, it signals an error.  Otherwise it returns
an integer.

The variable `last-command-char' always contains an integer, or nil (if the
last read event has no ASCII equivalent, as when it is a mouse-click or a
non-ASCII character chord.)

The new variable `last-command-event' holds an event object, that could be
a non-ASCII character, a button click, a menu selection, etc.

The variable `unread-command-char' no longer exists, and has been replaced
by `unread-command-events'.  With the new event model, it is incorrect for
code to do (setq unread-command-char (read-char)), because all user-input
can't be represented as ASCII characters.  *** This is an incompatible 
change.  Code which sets `unread-command-char' must be updated to use the
combination of `next-command-event' and `unread-command-events' instead.

The functions `this-command-keys' and `recent-keys' return a vector of
event objects, instead of a string of ASCII characters.  *** This also
is an incompatible change.

Almost nothing happens at interrupt level; the SIGIO handler simply sets a
flag, and later, the X event queue is scanned for KeyPress events which map
to ^G.  All redisplay happens in the main thread of the process.


*** Keymaps
-----------

Instead of keymaps being alists or obarrays, they are a new primary data
type.  The only user access to the contents of a keymap is through the
existing keymap-manipulation functions, and a new function, map-keymap.
This means that existing code that manipulates keymaps may need to 
be changed.

One of our goals with the new input and keymap code was to make more
character combinations available for binding, besides just ASCII and
function keys.  We want to be able bind different commands to Control-a 
and Control-Shift-a; we also want it to be possible for the keys Control-h
and Backspace (and Control-M and Return, and Control-I and Tab, etc) to
be distinct.

One of the most common complaints that new Emacs users have is that backspace
is help.  The answer is to play around with the keyboard-translate-table, or
be lucky enough to have a system administrator who has done this for you
already; but if it were possible to bind backspace and C-h to different
things, then (under a window manager at least) both backspace and delete
aps/icons in buffers, `undo' did not
restore changes to regions, regions did not overlap and merge their
attributes in the way we needed, and several other things.

We could have devoted our time to making Epoch do what we needed (and, in
fact, we spent some time doing that in 1990) but, since the Free Software
Foundation planned to include Epoch-like features in their Version 19, we
decided that our efforts would be better spent improving GNU Emacs
instead of Epoch.

Our original hope was that our changes to GNU Emacs would be
incorporated into the "official" v19.  However, scheduling conflicts arose,
and we found that, given the amount of work still remaining to be done, we
didn't have the time or manpower to do the level of coordination that would
be necessary to get our changes accepted by the Free Software Foundation.
Consequently, we released our work as a forked branch of Emacs, instead of
delaying any longer.

Roughly a year after Lucid Emacs 19.0 was released, a beta version of the
Free Software Foundation branch of Emacs 19 was released.  This version
was better in some areas, and worse in others, as reflects the differing
focus of our development efforts.

We planned to continue developing and supporting Lucid Emacs, and merging in
bug fixes and new features from the Free Software Foundation branch as
appropriate; we did not plan to discard any of the functionality that we
implemented which Richard Stallman of the Free Software Foundation has
chosen not to include in his version.

However, events have overtaken us, and Lucid, Inc. has effectively ceased
doing business and is (September 1994) in the process of being sold.  Our
efforts on Lucid Emacs have also ceased and we've turned over the continued
enhancement of Lucid Emacs to the University of Illinois under Chuck
Thompson, a member of the Lucid Emacs team and a maintainer of Epoch.
At the same time, Lucid Emacs has been renamed XEmacs to reflect the
substantial contribution of the University of Illinois with the support of
Sun Microsystems.

Certain elements of Lucid Emacs, or derivatives of them, have been ported to
the FSF GNU Emacs.  We have not been doing work in this direction, because
we feel that Lucid Emacs has a cleaner and more extensible substrate, and
that any kind of merger between the two branches would be far easier by
merging the Free Software Foundation changes into our version than the other
way around.

We were working closely with the Epoch developers to merge in the
remaining Epoch functionality which Lucid Emacs does not yet have.  Epoch
and Lucid Emacs will soon be one and the same thing.  Work is being done on
a compatibility package which will allow Epoch 4 code to run in XEmacs with
little or no change.  (As of 19.8, Lucid Emacs is running a descendant of
the Epoch redisplay engine.)

** Why Another Version of Emacs?  (The SunPro Point of View)
============================================================

Emacs 18 has been around for a long, long time.  Version 19 was supposed to
be the successor to Emacs 18 with X support.  It was going to be available
"real soon" for a long time (some people remember hearing about v19 as early
as 1984!), but it never came out.  v19 development was going very, very
slowly, and from the outside it seemed that it was not moving at all.  In
the meantime other people gave up waiting for v19 and decided to build their
own X-aware Emacsen.  The most important of these was probably Epoch, which
came from the University of Illinois and was based on v18.

Around three years ago we decided that we wanted an integrated editor.  We
contracted with the University of Illinois to provide a number of basic
enhancements to the functionality in Epoch.  The University of Illinois
initially was planning to deliver this on top of Epoch code.

In the meantime (actually some time before we talked with the University of
Illinois) Lucid had decided that it also wanted to provide an integrated
environment with an integrated editor.  Lucid decided that the Version 19
basis was a better one than Version 18 and thus decided not to use Epoch but
instead work with Richard Stallman, the head of the Free Software Foundation
and principle author of Emacs, on getting Version 19 out.  At some point
Stallman and Lucid parted ways.  Lucid kept working and got a Version 19 out
that they called Lucid Emacs 19.

After Lucid's v19 came out it became clear to us (the University of Illinois
and SunPro) that the right thing to do was to push for an integration of
both Lucid Emacs and Epoch, and to get the deliverables that we were asking
from the University of Illinois on top of this integrated platform.  Through
the last two years, SunPro has been actively supporting this product and has
been investing a comparable amount of effort into it as Lucid has.
Substantial portions of the current code have originated under the support
of SunPro, either directly in SunPro, or in the University of Illinois but
paid for by us.  This code was kept away from Lucid for a while, but later
was made available to them.  Initially Lucid didn't know that we were
supporting UofI, but later we were open about it.

Eventually, all development source trees were synched up.  Currently, there
is basically no difference in the source trees between what is at the
University of Illinois and SunPro.

SunPro originally called the integrated product ERA, for "Emacs Rewritten
Again".  At some point, SunPro and Lucid came to an agreement to find a name
for the product that was not specific to either company.  An additional
constraint that Lucid placed on the name was that it must contain the word
"Emacs" in it -- thus "ERA" was not acceptable.  The agreed-upon name was
"XEmacs", and this is what the product has been called starting with the
19.11 release.


* What's Different?
===================


** Differences between XEmacs and FSF GNU Emacs 19
==================================================

In XEmacs, events are first-class objects.  FSF 19 represents them as
integers, which obscures the differences between a key gesture and the
ancient ASCII code used to represent a particular overlapping subset of them.

In XEmacs, keymaps are first-class opaque objects.  FSF 19 represents them as
complicated combinations of association lists and vectors.  If you use the
advertised functional interface to manipulation of keymaps, the same code
will work in XEmacs, Emacs 18, and and FSF GNU Emacs 19; if your code depends
on the underlying implementation of keymaps, it will not.

XEmacs uses "extents" to represent all non-textual aspects of buffers;
FSF 19 uses two distinct objects, "text properties" and "overlays",
which divide up the functionality between them.  Extents are a
superset of the functionality of the two FSF data types.  The full FSF
19 interface to text properties is supported in XEmacs (with extents
being the underlying representation).

Extents can be made to be copied into strings, and thus restored by kill
and yank.  Thus, one can specify this behavior on either "extents" or
"text properties", whereas in FSF 19 text properties always have this
behavior and overlays never do.

Many more packages are provided standard with XEmacs than with FSF 19.

Pixmaps of arbitrary size can be embedded in a buffer.

Variable width fonts work.

The height of a line is the height of the tallest font on that line, instead
of all lines having the same height.

XEmacs uses the MIT "Xt" toolkit instead of raw Xlib calls, which
makes it be a more well-behaved X citizen (and also improves
portability).  A result of this is that it is possible to include
other Xt "Widgets" in the XEmacs window.  Also, XEmacs understands the
standard Xt command-line arguments.

XEmacs provides support for ToolTalk on systems that have it.

XEmacs can ask questions using popup dialog boxes.  Any command executed from
a menu will ask yes/no questions with dialog boxes, while commands executed
via the keyboard will use the minibuffer.

XEmacs has a built-in toolbar.  Four toolbars can actually be configured:
top, bottom, left, and right toolbars.

XEmacs has vertical and horizontal scrollbars.  Unlike in FSF 19 (which
provides a primitive form of vertical scrollbar), these are true toolkit
scrollbars.  A look-alike Motif scrollbar is provided for those who
don't have Motif. (Even for those who do, the look-alike may be preferable
as it is faster.)

If you're running on a machine with audio hardware, you can specify sound 
files for XEmacs to play instead of the default X beep.  See the documentation
of the function load-sound-file and the variable sound-alist.

An XEmacs frame can be placed within an "external client widget" managed by
another application.  This allows an application to use an XEmacs frame as its
text pane rather than the standard Text widget that is provided with Motif or
Athena.  XEmacs supports Motif applications, generic Xt (e.g. Athena)
applications, and raw Xlib applications.

Here are some more specifics about the XEmacs implementation:

*** The Input Model
-------------------

The fundamental unit of input is an "event" instead of a character.  An
event is a new data type that contains several pieces of information.
There are several kinds of event, and corresponding accessor and utility
functions.  We tried to abstract them so that they would apply equally
well to a number of window systems.

NOTE: All timestamps are measured as milliseconds since Emacs started.

 key_press_event	
    event_channel	A token representing which keyboard generated it.
			For this kind of event, this is a frame object.
			(This is for eventual support of multiple displays.)
    timestamp		When it happened
    key			What keysym this is; an integer or a symbol.
			If this is an integer, it will be in the printing
			ASCII range: >32 and <127.
    modifiers		Bucky-bits on that key: control, meta, etc.
			For most keys, Shift is not a bit; that is implicit
			in the keyboard layout.

 button_press_event
 button_release_event
    event_channel	A token representing which mouse generated it.
			For this kind of event, this is a frame object.
    timestamp		When it happened
    button		What button went down or up.
    modifiers		Bucky-bits on that button: shift, control, meta, etc.
    x, y		Where it was at the button-state-change (in pixels).

 pointer_motion_event
    event_channel	A token representing which mouse generated it.
			For this kind of event, this is a frame object.
    timestamp		When it happened
    x, y		Where it was after it moved (in pixels).
    modifiers		Bucky-bits down when the motion was detected.
			(Possibly not all window systems will provide this?)

 process_event
    timestamp		When it happened
    process		the emacs "process" object in question

 timeout_event
    timestamp		Now (really, when the timeout was signaled)
    interval_id		The ID returned when the associated call to
			add_timeout_cb() was made
	------ the rest of the fields are filled in by Emacs -----
    id_number		The Emacs timeout ID for this timeout (more
			than one timeout event can have the same value
			here, since Emacs timeouts, as opposed to
			add_timeout_cb() timeouts, can resignal
			themselves)
    function		An elisp function to call when this timeout is
			processed.
    object		The object passed to that function.

 eval_event
    timestamp		When it happened
    function		An elisp function to call with this event object.
    object		Anything.
			This kind of event is used internally; sometimes the
			window system interface would like to inform emacs of
			some user action (such as focusing on another frame)
			but needs that to happen synchronously with the other
			user input, like keypresses.  This is useful when
			events are reported through callbacks rather
			than in the standard event stream.

 misc_user_event
    timestamp		When it happened
    function		An elisp function to call with this event object.
    object		Anything.
			This is similar to an eval_event, except that it is
			generated by user actions: selections in the
			menubar or scrollbar actions.  It is a "command"
			event, like key and mouse presses (and unlike mouse
			motion, process output, and enter and leave window
			hooks).  In many ways, eval_events are not the same
			as keypresses or misc_user_events.

 magic_event
			No user-serviceable parts within.  This is for things
			like KeymapNotify and ExposeRegion events and so on
			that emacs itself doesn't care about, but which it
			must do something with for proper interaction with
			the window system.

			Magic_events are handled somewhat asynchronously, just
			like subprocess filters.  However, occasionally a 
			magic_event needs to be handled synchronously; in that
			case, the asynchronous handling of the magic_event will
			push an eval_event back onto the queue, which will be 
			handled synchronously later.  This is one of the
			reasons why eval_events exist; I'm not entirely happy
			with this aspect of this event model.


The function `next-event' blocks and returns one of the above-described 
event objects.  The function `dispatch-event' takes an event and processes
it in the appropriate way.

For a process-event, dispatch-event calls the process's handler; for a
mouse-motion event, the mouse-motion-handler hook is called, and so on.
For magic-events, dispatch-event does window-system-dependent things,
including calling some non-window-system-dependent hooks: map-frame-hook,
unmap-frame-hook, mouse-enter-frame-hook, and mouse-leave-frame-hook.

The function `next-command-event' calls `next-event' until it gets a key or
button from the user (that is, not a process, motion, timeout, or magic
event).  If it gets an event that is not a key or button, it calls
`dispatch-event' on it immediately and reads another one.  The
next-command-event function could be implemented in Emacs Lisp, though it
isn't.  Generally one should call `next-command-event' instead of
`next-event'.

read-char calls next-command-event; if it doesn't get an event that can be
converted to an ASCII character, it signals an error.  Otherwise it returns
an integer.

The variable `last-command-char' always contains an integer, or nil (if the
last read event has no ASCII equivalent, as when it is a mouse-click or a
non-ASCII character chord.)

The new variable `last-command-event' holds an event object, that could be
a non-ASCII character, a button click, a menu selection, etc.

The variable `unread-command-char' no longer exists, and has been replaced
by `unread-command-events'.  With the new event model, it is incorrect for
code to do (setq unread-command-char (read-char)), because all user-input
can't be represented as ASCII characters.  *** This is an incompatible 
change.  Code which sets `unread-command-char' must be updated to use the
combination of `next-command-event' and `unread-command-events' instead.

The functions `this-command-keys' and `recent-keys' return a vector of
event objects, instead of a string of ASCII characters.  *** This also
is an incompatible change.

Almost nothing happens at interrupt level; the SIGIO handler simply sets a
flag, and later, the X event queue is scanned for KeyPress events which map
to ^G.  All redisplay happens in the main thread of the process.


*** Keymaps
-----------

Instead of keymaps being alists or obarrays, they are a new primary data
type.  The only user access to the contents of a keymap is through the
existing keymap-manipulation functions, and a new function, map-keymap.
This means that existing code that manipulates keymaps may need to 
be changed.

One of our goals with the new input and keymap code was to make more
character combinations available for binding, besides just ASCII and
function keys.  We want to be able bind different commands to Control-a 
and Control-Shift-a; we also want it to be possible for the keys Control-h
and Backspace (and Control-M and Return, and Control-I and Tab, etc) to
be distinct.

One of the most common complaints that new Emacs users have is that backspace
is help.  The answer is to play around with the keyboard-translate-table, or
be lucky enough to have a system administrator who has done this for you
already; but if it were possible to bind backspace and C-h to different
things, then (under a window manager at least) both backspace and delete
aps/icons in buffers, `undo' did not
restore changes to regions, regions did not overlap and merge their
attributes in the way we needed, and several other things.

We could have devoted our time to making Epoch do what we needed (and, in
fact, we spent some time doing that in 1990) but, since the Free Software
Foundation planned to include Epoch-like features in their Version 19, we
decided that our efforts would be better spent improving GNU Emacs
instead of Epoch.

Our original hope was that our changes to GNU Emacs would be
incorporated into the "official" v19.  However, scheduling conflicts arose,
and we found that, given the amount of work still remaining to be done, we
didn't have the time or manpower to do the level of coordination that would
be necessary to get our changes accepted by the Free Software Foundation.
Consequently, we released our work as a forked branch of Emacs, instead of
delaying any longer.

Roughly a year after Lucid Emacs 19.0 was released, a beta version of the
Free Software Foundation branch of Emacs 19 was released.  This version
was better in some areas, and worse in others, as reflects the differing
focus of our development efforts.

We planned to continue developing and supporting Lucid Emacs, and merging in
bug fixes and new features from the Free Software Foundation branch as
appropriate; we did not plan to discard any of the functionality that we
implemented which Richard Stallman of the Free Software Foundation has
chosen not to include in his version.

However, events have overtaken us, and Lucid, Inc. has effectively ceased
doing business and is (September 1994) in the process of being sold.  Our
efforts on Lucid Emacs have also ceased and we've turned over the continued
enhancement of Lucid Emacs to the University of Illinois under Chuck
Thompson, a member of the Lucid Emacs team and a maintainer of Epoch.
At the same time, Lucid Emacs has been renamed XEmacs to reflect the
substantial contribution of the University of Illinois with the support of
Sun Microsystems.

Certain elements of Lucid Emacs, or derivatives of them, have been ported to
the FSF GNU Emacs.  We have not been doing work in this direction, because
we feel that Lucid Emacs has a cleaner and more extensible substrate, and
that any kind of merger between the two branches would be far easier by
merging the Free Software Foundation changes into our version than the other
way around.

We were working closely with the Epoch developers to merge in the
remaining Epoch functionality which Lucid Emacs does not yet have.  Epoch
and Lucid Emacs will soon be one and the same thing.  Work is being done on
a compatibility package which will allow Epoch 4 code to run in XEmacs with
little or no change.  (As of 19.8, Lucid Emacs is running a descendant of
the Epoch redisplay engine.)

** Why Another Version of Emacs?  (The SunPro Point of View)
============================================================

Emacs 18 has been around for a long, long time.  Version 19 was supposed to
be the successor to Emacs 18 with X support.  It was going to be available
"real soon" for a long time (some people remember hearing about v19 as early
as 1984!), but it never came out.  v19 development was going very, very
slowly, and from the outside it seemed that it was not moving at all.  In
the meantime other people gave up waiting for v19 and decided to build their
own X-aware Emacsen.  The most important of these was probably Epoch, which
came from the University of Illinois and was based on v18.

Around three years ago we decided that we wanted an integrated editor.  We
contracted with the University of Illinois to provide a number of basic
enhancements to the functionality in Epoch.  The University of Illinois
initially was planning to deliver this on top of Epoch code.

In the meantime (actually some time before we talked with the University of
Illinois) Lucid had decided that it also wanted to provide an integrated
environment with an integrated editor.  Lucid decided that the Version 19
basis was a better one than Version 18 and thus decided not to use Epoch but
instead work with Richard Stallman, the head of the Free Software Foundation
and principle author of Emacs, on getting Version 19 out.  At some point
Stallman and Lucid parted ways.  Lucid kept working and got a Version 19 out
that they called Lucid Emacs 19.

After Lucid's v19 came out it became clear to us (the University of Illinois
and SunPro) that the right thing to do was to push for an integration of
both Lucid Emacs and Epoch, and to get the deliverables that we were asking
from the University of Illinois on top of this integrated platform.  Through
the last two years, SunPro has been actively supporting this product and has
been investing a comparable amount of effort into it as Lucid has.
Substantial portions of the current code have originated under the support
of SunPro, either directly in SunPro, or in the University of Illinois but
paid for by us.  This code was kept away from Lucid for a while, but later
was made available to them.  Initially Lucid didn't know that we were
supporting UofI, but later we were open about it.

Eventually, all development source trees were synched up.  Currently, there
is basically no difference in the source trees between what is at the
University of Illinois and SunPro.

SunPro originally called the integrated product ERA, for "Emacs Rewritten
Again".  At some point, SunPro and Lucid came to an agreement to find a name
for the product that was not specific to either company.  An additional
constraint that Lucid placed on the name was that it must contain the word
"Emacs" in it -- thus "ERA" was not acceptable.  The agreed-upon name was
"XEmacs", and this is what the product has been called starting with the
19.11 release.


* What's Different?
===================


** Differences between XEmacs and FSF GNU Emacs 19
==================================================

In XEmacs, events are first-class objects.  FSF 19 represents them as
integers, which obscures the differences between a key gesture and the
ancient ASCII code used to represent a particular overlapping subset of them.

In XEmacs, keymaps are first-class opaque objects.  FSF 19 represents them as
complicated combinations of association lists and vectors.  If you use the
advertised functional interface to manipulation of keymaps, the same code
will work in XEmacs, Emacs 18, and and FSF GNU Emacs 19; if your code depends
on the underlying implementation of keymaps, it will not.

XEmacs uses "extents" to represent all non-textual aspects of buffers;
FSF 19 uses two distinct objects, "text properties" and "overlays",
which divide up the functionality between them.  Extents are a
superset of the functionality of the two FSF data types.  The full FSF
19 interface to text properties is supported in XEmacs (with extents
being the underlying representation).

Extents can be made to be copied into strings, and thus restored by kill
and yank.  Thus, one can specify this behavior on either "extents" or
"text properties", whereas in FSF 19 text properties always have this
behavior and overlays never do.

Many more packages are provided standard with XEmacs than with FSF 19.

Pixmaps of arbitrary size can be embedded in a buffer.

Variable width fonts work.

The height of a line is the height of the tallest font on that line, instead
of all lines having the same height.

XEmacs uses the MIT "Xt" toolkit instead of raw Xlib calls, which
makes it be a more well-behaved X citizen (and also improves
portability).  A result of this is that it is possible to include
other Xt "Widgets" in the XEmacs window.  Also, XEmacs understands the
standard Xt command-line arguments.

XEmacs provides support for ToolTalk on systems that have it.

XEmacs can ask questions using popup dialog boxes.  Any command executed from
a menu will ask yes/no questions with dialog boxes, while commands executed
via the keyboard will use the minibuffer.

XEmacs has a built-in toolbar.  Four toolbars can actually be configured:
top, bottom, left, and right toolbars.

XEmacs has vertical and horizontal scrollbars.  Unlike in FSF 19 (which
provides a primitive form of vertical scrollbar), these are true toolkit
scrollbars.  A look-alike Motif scrollbar is provided for those who
don't have Motif. (Even for those who do, the look-alike may be preferable
as it is faster.)

If you're running on a machine with audio hardware, you can specify sound 
files for XEmacs to play instead of the default X beep.  See the documentation
of the function load-sound-file and the variable sound-alist.

An XEmacs frame can be placed within an "external client widget" managed by
another application.  This allows an application to use an XEmacs frame as its
text pane rather than the standard Text widget that is provided with Motif or
Athena.  XEmacs supports Motif applications, generic Xt (e.g. Athena)
applications, and raw Xlib applications.

Here are some more specifics about the XEmacs implementation:

*** The Input Model
-------------------

The fundamental unit of input is an "event" instead of a character.  An
event is a new data type that contains several pieces of information.
There are several kinds of event, and corresponding accessor and utility
functions.  We tried to abstract them so that they would apply equally
well to a number of window systems.

NOTE: All timestamps are measured as milliseconds since Emacs started.

 key_press_event	
    event_channel	A token representing which keyboard generated it.
			For this kind of event, this is a frame object.
			(This is for eventual support of multiple displays.)
    timestamp		When it happened
    key			What keysym this is; an integer or a symbol.
			If this is an integer, it will be in the printing
			ASCII range: >32 and <127.
    modifiers		Bucky-bits on that key: control, meta, etc.
			For most keys, Shift is not a bit; that is implicit
			in the keyboard layout.

 button_press_event
 button_release_event
    event_channel	A token representing which mouse generated it.
			For this kind of event, this is a frame object.
    timestamp		When it happened
    button		What button went down or up.
    modifiers		Bucky-bits on that button: shift, control, meta, etc.
    x, y		Where it was at the button-state-change (in pixels).

 pointer_motion_event
    event_channel	A token representing which mouse generated it.
			For this kind of event, this is a frame object.
    timestamp		When it happened
    x, y		Where it was after it moved (in pixels).
    modifiers		Bucky-bits down when the motion was detected.
			(Possibly not all window systems will provide this?)

 process_event
    timestamp		When it happened
    process		the emacs "process" object in question

 timeout_event
    timestamp		Now (really, when the timeout was signaled)
    interval_id		The ID returned when the associated call to
			add_timeout_cb() was made
	------ the rest of the fields are filled in by Emacs -----
    id_number		The Emacs timeout ID for this timeout (more
			than one timeout event can have the same value
			here, since Emacs timeouts, as opposed to
			add_timeout_cb() timeouts, can resignal
			themselves)
    function		An elisp function to call when this timeout is
			processed.
    object		The object passed to that function.

 eval_event
    timestamp		When it happened
    function		An elisp function to call with this event object.
    object		Anything.
			This kind of event is used internally; sometimes the
			window system interface would like to inform emacs of
			some user action (such as focusing on another frame)
			but needs that to happen synchronously with the other
			user input, like keypresses.  This is useful when
			events are reported through callbacks rather
			than in the standard event stream.

 misc_user_event
    timestamp		When it happened
    function		An elisp function to call with this event object.
    object		Anything.
			This is similar to an eval_event, except that it is
			generated by user actions: selections in the
			menubar or scrollbar actions.  It is a "command"
			event, like key and mouse presses (and unlike mouse
			motion, process output, and enter and leave window
			hooks).  In many ways, eval_events are not the same
			as keypresses or misc_user_events.

 magic_event
			No user-serviceable parts within.  This is for things
			like KeymapNotify and ExposeRegion events and so on
			that emacs itself doesn't care about, but which it
			must do something with for proper interaction with
			the window system.

			Magic_events are handled somewhat asynchronously, just
			like subprocess filters.  However, occasionally a 
			magic_event needs to be handled synchronously; in that
			case, the asynchronous handling of the magic_event will
			push an eval_event back onto the queue, which will be 
			handled synchronously later.  This is one of the
			reasons why eval_events exist; I'm not entirely happy
			with this aspect of this event model.


The function `next-event' blocks and returns one of the above-described 
event objects.  The function `dispatch-event' takes an event and processes
it in the appropriate way.

For a process-event, dispatch-event calls the process's handler; for a
mouse-motion event, the mouse-motion-handler hook is called, and so on.
For magic-events, dispatch-event does window-system-dependent things,
including calling some non-window-system-dependent hooks: map-frame-hook,
unmap-frame-hook, mouse-enter-frame-hook, and mouse-leave-frame-hook.

The function `next-command-event' calls `next-event' until it gets a key or
button from the user (that is, not a process, motion, timeout, or magic
event).  If it gets an event that is not a key or button, it calls
`dispatch-event' on it immediately and reads another one.  The
next-command-event function could be implemented in Emacs Lisp, though it
isn't.  Generally one should call `next-command-event' instead of
`next-event'.

read-char calls next-command-event; if it doesn't get an event that can be
converted to an ASCII character, it signals an error.  Otherwise it returns
an integer.

The variable `last-command-char' always contains an integer, or nil (if the
last read event has no ASCII equivalent, as when it is a mouse-click or a
non-ASCII character chord.)

The new variable `last-command-event' holds an event object, that could be
a non-ASCII character, a button click, a menu selection, etc.

The variable `unread-command-char' no longer exists, and has been replaced
by `unread-command-events'.  With the new event model, it is incorrect for
code to do (setq unread-command-char (read-char)), because all user-input
can't be represented as ASCII characters.  *** This is an incompatible 
change.  Code which sets `unread-command-char' must be updated to use the
combination of `next-command-event' and `unread-command-events' instead.

The functions `this-command-keys' and `recent-keys' return a vector of
event objects, instead of a string of ASCII characters.  *** This also
is an incompatible change.

Almost nothing happens at interrupt level; the SIGIO handler simply sets a
flag, and later, the X event queue is scanned for KeyPress events which map
to ^G.  All redisplay happens in the main thread of the process.


*** Keymaps
-----------

Instead of keymaps being alists or obarrays, they are a new primary data
type.  The only user access to the contents of a keymap is through the
existing keymap-manipulation functions, and a new function, map-keymap.
This means that existing code that manipulates keymaps may need to 
be changed.

One of our goals with the new input and keymap code was to make more
character combinations available for binding, besides just ASCII and
function keys.  We want to be able bind different commands to Control-a 
and Control-Shift-a; we also want it to be possible for the keys Control-h
and Backspace (and Control-M and Return, and Control-I and Tab, etc) to
be distinct.

One of the most common complaints that new Emacs users have is that backspace
is help.  The answer is to play around with the keyboard-translate-table, or
be lucky enough to have a system administrator who has done this for you
already; but if it were possible to bind backspace and C-h to different
things, then (under a window manager at least) both backspace and delete
aps/icons in buffers, `undo' did not
restore changes to regions, regions did not overlap and merge their
attributes in the way we needed, and several other things.

We could have devoted our time to making Epoch do what we needed (and, in
fact, we spent some time doing that in 1990) but, since the Free Software
Foundation planned to include Epoch-like features in their Version 19, we
decided that our efforts would be better spent improving GNU Emacs
instead of Epoch.

Our original hope was that our changes to GNU Emacs would be
incorporated into the "official" v19.  However, scheduling conflicts arose,
and we found that, given the amount of work still remaining to be done, we
didn't have the time or manpower to do the level of coordination that would
be necessary to get our changes accepted by the Free Software Foundation.
Consequently, we released our work as a forked branch of Emacs, instead of
delaying any longer.

Roughly a year after Lucid Emacs 19.0 was released, a beta version of the
Free Software Foundation branch of Emacs 19 was released.  This version
was better in some areas, and worse in others, as reflects the differing
focus of our development efforts.

We planned to continue developing and supporting Lucid Emacs, and merging in
bug fixes and new features from the Free Software Foundation branch as
appropriate; we did not plan to discard any of the functionality that we
implemented which Richard Stallman of the Free Software Foundation has
chosen not to include in his version.

However, events have overtaken us, and Lucid, Inc. has effectively ceased
doing business and is (September 1994) in the process of being sold.  Our
efforts on Lucid Emacs have also ceased and we've turned over the continued
enhancement of Lucid Emacs to the University of Illinois under Chuck
Thompson, a member of the Lucid Emacs team and a maintainer of Epoch.
At the same time, Lucid Emacs has been renamed XEmacs to reflect the
substantial contribution of the University of Illinois with the support of
Sun Microsystems.

Certain elements of Lucid Emacs, or derivatives of them, have been ported to
the FSF GNU Emacs.  We have not been doing work in this direction, because
we feel that Lucid Emacs has a cleaner and more extensible substrate, and
that any kind of merger between the two branches would be far easier by
merging the Free Software Foundation changes into our version than the other
way around.

We were working closely with the Epoch developers to merge in the
remaining Epoch functionality which Lucid Emacs does not yet have.  Epoch
and Lucid Emacs will soon be one and the same thing.  Work is being done on
a compatibility package which will allow Epoch 4 code to run in XEmacs with
little or no change.  (As of 19.8, Lucid Emacs is running a descendant of
the Epoch redisplay engine.)

** Why Another Version of Emacs?  (The SunPro Point of View)
============================================================

Emacs 18 has been around for a long, long time.  Version 19 was supposed to
be the successor to Emacs 18 with X support.  It was going to be available
"real soon" for a long time (some people remember hearing about v19 as early
as 1984!), but it never came out.  v19 development was going very, very
slowly, and from the outside it seemed that it was not moving at all.  In
the meantime other people gave up waiting for v19 and decided to build their
own X-aware Emacsen.  The most important of these was probably Epoch, which
came from the University of Illinois and was based on v18.

Around three years ago we decided that we wanted an integrated editor.  We
contracted with the University of Illinois to provide a number of basic
enhancements to the functionality in Epoch.  The University of Illinois
initially was planning to deliver this on top of Epoch code.

In the meantime (actually some time before we talked with the University of
Illinois) Lucid had decided that it also wanted to provide an integrated
environment with an integrated editor.  Lucid decided that the Version 19
basis was a better one than Version 18 and thus decided not to use Epoch but
instead work with Richard Stallman, the head of the Free Software Foundation
and principle author of Emacs, on getting Version 19 out.  At some point
Stallman and Lucid parted ways.  Lucid kept working and got a Version 19 out
that they called Lucid Emacs 19.

After Lucid's v19 came out it became clear to us (the University of Illinois
and SunPro) that the right thing to do was to push for an integration of
both Lucid Emacs and Epoch, and to get the deliverables that we were asking
from the University of Illinois on top of this integrated platform.  Through
the last two years, SunPro has been actively supporting this product and has
been investing a comparable amount of effort into it as Lucid has.
Substantial portions of the current code have originated under the support
of SunPro, either directly in SunPro, or in the University of Illinois but
paid for by us.  This code was kept away from Lucid for a while, but later
was made available to them.  Initially Lucid didn't know that we were
supporting UofI, but later we were open about it.

Eventually, all development source trees were synched up.  Currently, there
is basically no difference in the source trees between what is at the
University of Illinois and SunPro.

SunPro originally called the integrated product ERA, for "Emacs Rewritten
Again".  At some point, SunPro and Lucid came to an agreement to find a name
for the product that was not specific to either company.  An additional
constraint that Lucid placed on the name was that it must contain the word
"Emacs" in it -- thus "ERA" was not acceptable.  The agreed-upon name was
"XEmacs", and this is what the product has been called starting with the
19.11 release.


* What's Different?
===================


** Differences between XEmacs and FSF GNU Emacs 19
==================================================

In XEmacs, events are first-class objects.  FSF 19 represents them as
integers, which obscures the differences between a key gesture and the
ancient ASCII code used to represent a particular overlapping subset of them.

In XEmacs, keymaps are first-class opaque objects.  FSF 19 represents them as
complicated combinations of association lists and vectors.  If you use the
advertised functional interface to manipulation of keymaps, the same code
will work in XEmacs, Emacs 18, and and FSF GNU Emacs 19; if your code depends
on the underlying implementation of keymaps, it will not.

XEmacs uses "extents" to represent all non-textual aspects of buffers;
FSF 19 uses two distinct objects, "text properties" and "overlays",
which divide up the functionality between them.  Extents are a
superset of the functionality of the two FSF data types.  The full FSF
19 interface to text properties is supported in XEmacs (with extents
being the underlying representation).

Extents can be made to be copied into strings, and thus restored by kill
and yank.  Thus, one can specify this behavior on either "extents" or
"text properties", whereas in FSF 19 text properties always have this
behavior and overlays never do.

Many more packages are provided standard with XEmacs than with FSF 19.

Pixmaps of arbitrary size can be embedded in a buffer.

Variable width fonts work.

The height of a line is the height of the tallest font on that line, instead
of all lines having the same height.

XEmacs uses the MIT "Xt" toolkit instead of raw Xlib calls, which
makes it be a more well-behaved X citizen (and also improves
portability).  A result of this is that it is possible to include
other Xt "Widgets" in the XEmacs window.  Also, XEmacs understands the
standard Xt command-line arguments.

XEmacs provides support for ToolTalk on systems that have it.

XEmacs can ask questions using popup dialog boxes.  Any command executed from
a menu will ask yes/no questions with dialog boxes, while commands executed
via the keyboard will use the minibuffer.

XEmacs has a built-in toolbar.  Four toolbars can actually be configured:
top, bottom, left, and right toolbars.

XEmacs has vertical and horizontal scrollbars.  Unlike in FSF 19 (which
provides a primitive form of vertical scrollbar), these are true toolkit
scrollbars.  A look-alike Motif scrollbar is provided for those who
don't have Motif. (Even for those who do, the look-alike may be preferable
as it is faster.)

If you're running on a machine with audio hardware, you can specify sound 
files for XEmacs to play instead of the default X beep.  See the documentation
of the function load-sound-file and the variable sound-alist.

An XEmacs frame can be placed within an "external client widget" managed by
another application.  This allows an application to use an XEmacs frame as its
text pane rather than the standard Text widget that is provided with Motif or
Athena.  XEmacs supports Motif applications, generic Xt (e.g. Athena)
applications, and raw Xlib applications.

Here are some more specifics about the XEmacs implementation:

*** The Input Model
-------------------

The fundamental unit of input is an "event" instead of a character.  An
event is a new data type that contains several pieces of information.
There are several kinds of event, and corresponding accessor and utility
functions.  We tried to abstract them so that they would apply equally
well to a number of window systems.

NOTE: All timestamps are measured as milliseconds since Emacs started.

 key_press_event	
    event_channel	A token representing which keyboard generated it.
			For this kind of event, this is a frame object.
			(This is for eventual support of multiple displays.)
    timestamp		When it happened
    key			What keysym this is; an integer or a symbol.
			If this is an integer, it will be in the printing
			ASCII range: >32 and <127.
    modifiers		Bucky-bits on that key: control, meta, etc.
			For most keys, Shift is not a bit; that is implicit
			in the keyboard layout.

 button_press_event
 button_release_event
    event_channel	A token representing which mouse generated it.
			For this kind of event, this is a frame object.
    timestamp		When it happened
    button		What button went down or up.
    modifiers		Bucky-bits on that button: shift, control, meta, etc.
    x, y		Where it was at the button-state-change (in pixels).

 pointer_motion_event
    event_channel	A token representing which mouse generated it.
			For this kind of event, this is a frame object.
    timestamp		When it happened
    x, y		Where it was after it moved (in pixels).
    modifiers		Bucky-bits down when the motion was detected.
			(Possibly not all window systems will provide this?)

 process_event
    timestamp		When it happened
    process		the emacs "process" object in question

 timeout_event
    timestamp		Now (really, when the timeout was signaled)
    interval_id		The ID returned when the associated call to
			add_timeout_cb() was made
	------ the rest of the fields are filled in by Emacs -----
    id_number		The Emacs timeout ID for this timeout (more
			than one timeout event can have the same value
			here, since Emacs timeouts, as opposed to
			add_timeout_cb() timeouts, can resignal
			themselves)
    function		An elisp function to call when this timeout is
			processed.
    object		The object passed to that function.

 eval_event
    timestamp		When it happened
    function		An elisp function to call with this event object.
    object		Anything.
			This kind of event is used internally; sometimes the
			window system interface would like to inform emacs of
			some user action (such as focusing on another frame)
			but needs that to happen synchronously with the other
			user input, like keypresses.  This is useful when
			events are reported through callbacks rather
			than in the standard event stream.

 misc_user_event
    timestamp		When it happened
    function		An elisp function to call with this event object.
    object		Anything.
			This is similar to an eval_event, except that it is
			generated by user actions: selections in the
			menubar or scrollbar actions.  It is a "command"
			event, like key and mouse presses (and unlike mouse
			motion, process output, and enter and leave window
			hooks).  In many ways, eval_events are not the same
			as keypresses or misc_user_events.

 magic_event
			No user-serviceable parts within.  This is for things
			like KeymapNotify and ExposeRegion events and so on
			that emacs itself doesn't care about, but which it
			must do something with for proper interaction with
			the window system.

			Magic_events are handled somewhat asynchronously, just
			like subprocess filters.  However, occasionally a 
			magic_event needs to be handled synchronously; in that
			case, the asynchronous handling of the magic_event will
			push an eval_event back onto the queue, which will be 
			handled synchronously later.  This is one of the
			reasons why eval_events exist; I'm not entirely happy
			with this aspect of this event model.


The function `next-event' blocks and returns one of the above-described 
event objects.  The function `dispatch-event' takes an event and processes
it in the appropriate way.

For a process-event, dispatch-event calls the process's handler; for a
mouse-motion event, the mouse-motion-handler hook is called, and so on.
For magic-events, dispatch-event does window-system-dependent things,
including calling some non-window-system-dependent hooks: map-frame-hook,
unmap-frame-hook, mouse-enter-frame-hook, and mouse-leave-frame-hook.

The function `next-command-event' calls `next-event' until it gets a key or
button from the user (that is, not a process, motion, timeout, or magic
event).  If it gets an event that is not a key or button, it calls
`dispatch-event' on it immediately and reads another one.  The
next-command-event function could be implemented in Emacs Lisp, though it
isn't.  Generally one should call `next-command-event' instead of
`next-event'.

read-char calls next-command-event; if it doesn't get an event that can be
converted to an ASCII character, it signals an error.  Otherwise it returns
an integer.

The variable `last-command-char' always contains an integer, or nil (if the
last read event has no ASCII equivalent, as when it is a mouse-click or a
non-ASCII character chord.)

The new variable `last-command-event' holds an event object, that could be
a non-ASCII character, a button click, a menu selection, etc.

The variable `unread-command-char' no longer exists, and has been replaced
by `unread-command-events'.  With the new event model, it is incorrect for
code to do (setq unread-command-char (read-char)), because all user-input
can't be represented as ASCII characters.  *** This is an incompatible 
change.  Code which sets `unread-command-char' must be updated to use the
combination of `next-command-event' and `unread-command-events' instead.

The functions `this-command-keys' and `recent-keys' return a vector of
event objects, instead of a string of ASCII characters.  *** This also
is an incompatible change.

Almost nothing happens at interrupt level; the SIGIO handler simply sets a
flag, and later, the X event queue is scanned for KeyPress events which map
to ^G.  All redisplay happens in the main thread of the process.


*** Keymaps
-----------

Instead of keymaps being alists or obarrays, they are a new primary data
type.  The only user access to the contents of a keymap is through the
existing keymap-manipulation functions, and a new function, map-keymap.
This means that existing code that manipulates keymaps may need to 
be changed.

One of our goals with the new input and keymap code was to make more
character combinations available for binding, besides just ASCII and
function keys.  We want to be able bind different commands to Control-a 
and Control-Shift-a; we also want it to be possible for the keys Control-h
and Backspace (and Control-M and Return, and Control-I and Tab, etc) to
be distinct.

One of the most common complaints that new Emacs users have is that backspace
is help.  The answer is to play around with the keyboard-translate-table, or
be lucky enough to have a system administrator who has done this for you
already; but if it were possible to bind backspace and C-h to different
things, then (under a window manager at least) both backspace and delete
aps/icons in buffers, `undo' did not
restore changes to regions, regions did not overlap and merge their
attributes in the way we needed, and several other things.

We could have devoted our time to making Epoch do what we needed (and, in
fact, we spent some time doing that in 1990) but, since the Free Software
Foundation planned to include Epoch-like features in their Version 19, we
decided that our efforts would be better spent improving GNU Emacs
instead of Epoch.

Our original hope was that our changes to GNU Emacs would be
incorporated into the "official" v19.  However, scheduling conflicts arose,
and we found that, given the amount of work still remaining to be done, we
didn't have the time or manpower to do the level of coordination that would
be necessary to get our changes accepted by the Free Software Foundation.
Consequently, we released our work as a forked branch of Emacs, instead of
delaying any longer.

Roughly a year after Lucid Emacs 19.0 was released, a beta version of the
Free Software Foundation branch of Emacs 19 was released.  This version
was better in some areas, and worse in others, as reflects the differing
focus of our development efforts.

We planned to continue developing and supporting Lucid Emacs, and merging in
bug fixes and new features from the Free Software Foundation branch as
appropriate; we did not plan to discard any of the functionality that we
implemented which Richard Stallman of the Free Software Foundation has
chosen not to include in his version.

However, events have overtaken us, and Lucid, Inc. has effectively ceased
doing business and is (September 1994) in the process of being sold.  Our
efforts on Lucid Emacs have also ceased and we've turned over the continued
enhancement of Lucid Emacs to the University of Illinois under Chuck
Thompson, a member of the Lucid Emacs team and a maintainer of Epoch.
At the same time, Lucid Emacs has been renamed XEmacs to reflect the
substantial contribution of the University of Illinois with the support of
Sun Microsystems.

Certain elements of Lucid Emacs, or derivatives of them, have been ported to
the FSF GNU Emacs.  We have not been doing work in this direction, because
we feel that Lucid Emacs has a cleaner and more extensible substrate, and
that any kind of merger between the two branches would be far easier by
merging the Free Software Foundation changes into our version than the other
way around.

We were working closely with the Epoch developers to merge in the
remaining Epoch functionality which Lucid Emacs does not yet have.  Epoch
and Lucid Emacs will soon be one and the same thing.  Work is being done on
a compatibility package which will allow Epoch 4 code to run in XEmacs with
little or no change.  (As of 19.8, Lucid Emacs is running a descendant of
the Epoch redisplay engine.)

** Why Another Version of Emacs?  (The SunPro Point of View)
============================================================

Emacs 18 has been around for a long, long time.  Version 19 was supposed to
be the successor to Emacs 18 with X support.  It was going to be available
"real soon" for a long time (some people remember hearing about v19 as early
as 1984!), but it never came out.  v19 development was going very, very
slowly, and from the outside it seemed that it was not moving at all.  In
the meantime other people gave up waiting for v19 and decided to build their
own X-aware Emacsen.  The most important of these was probably Epoch, which
came from the University of Illinois and was based on v18.

Around three years ago we decided that we wanted an integrated editor.  We
contracted with the University of Illinois to provide a number of basic
enhancements to the functionality in Epoch.  The University of Illinois
initially was planning to deliver this on top of Epoch code.

In the meantime (actually some time before we talked with the University of
Illinois) Lucid had decided that it also wanted to provide an integrated
environment with an integrated editor.  Lucid decided that the Version 19
basis was a better one than Version 18 and thus decided not to use Epoch but
instead work with Richard Stallman, the head of the Free Software Foundation
and principle author of Emacs, on getting Version 19 out.  At some point
Stallman and Lucid parted ways.  Lucid kept working and got a Version 19 out
that they called Lucid Emacs 19.

After Lucid's v19 came out it became clear to us (the University of Illinois
and SunPro) that the right thing to do was to push for an integration of
both Lucid Emacs and Epoch, and to get the deliverables that we were asking
from the University of Illinois on top of this integrated platform.  Through
the last two years, SunPro has been actively supporting this product and has
been investing a comparable amount of effort into it as Lucid has.
Substantial portions of the current code have originated under the support
of SunPro, either directly in SunPro, or in the University of Illinois but
paid for by us.  This code was kept away from Lucid for a while, but later
was made available to them.  Initially Lucid didn't know that we were
supporting UofI, but later we were open about it.

Eventually, all development source trees were synched up.  Currently, there
is basically no difference in the source trees between what is at the
University of Illinois and SunPro.

SunPro originally called the integrated product ERA, for "Emacs Rewritten
Again".  At some point, SunPro and Lucid came to an agreement to find a name
for the product that was not specific to either company.  An additional
constraint that Lucid placed on the name was that it must contain the word
"Emacs" in it -- thus "ERA" was not acceptable.  The agreed-upon name was
"XEmacs", and this is what the product has been called starting with the
19.11 release.


* What's Different?
===================


** Differences between XEmacs and FSF GNU Emacs 19
==================================================

In XEmacs, events are first-class objects.  FSF 19 represents them as
integers, which obscures the differences between a key gesture and the
ancient ASCII code used to represent a particular overlapping subset of them.

In XEmacs, keymaps are first-class opaque objects.  FSF 19 represents t