This is Lucid GNU Emacs.  It is based on an early version of Emacs version 19
from the Free Software Foundation.

Why Another Version of Emacs?
=============================

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 GNU Emacs 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 FSF19?
=======================

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 FSF planned to 
include Epoch-like features in their version 19, we decided that our efforts
would be better spent improving Emacs 19 instead of Epoch.  

Our original hope was that our changes to 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 FSF.  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 FSF
branch of Emacs 19 was released.  The FSF version is better in some areas, and
worse in others, as reflects the differing focus of our development efforts.

We plan to continue developing and supporting Lucid Emacs, and merging in bug
fixes and new features from the FSF branch as appropriate; we do not plan to
discard any of the functionality that we implemented which RMS has chosen not
to include in his version.

Certain elements of Lucid Emacs, or derivatives of them, have been ported to
the FSF version.  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 FSF changes into our version than the other way around.

We have been 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 Lemacs with
little or no change.  (As of 19.8, Lucid Emacs is running a descendant of
the Epoch redisplay engine.)

No Warranty
===========

Lucid Emacs is distributed under exactly the same terms as GNU Emacs, and
thus has no warranty of any kind.

However, if you have received this version of Emacs with Energize, then it is
covered by your Energize support contract.  If you have received it through
some other means, then you may buy a support contract for it from Lucid.
Send mail to lucid-info@lucid.com for more information about Lucid Emacs or
Energize.

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

Unless otherwise noted, this file describes differences between Lucid Emacs
version 19.* and GNU Emacs version 18.57.

Lucid Emacs *currently* requires an X Window System environment to run,
though it will not be much work to make it run on dumb ttys again.  We plan
to do this eventually.  If you would like to volunteer to help, send us mail.

Because of our functionality requirements and manpower constraints, we have
not been able to spend as much time on portability issues as we would like;
consequently, Lucid Emacs is not necessarily as easy to bring up on other
systems as the other branches of Emacs are.  We are very eager to get feedback
about portability problems from those who compile it on other systems.

We have reimplemented the basic input model in a more general way; instead of
X input being a special-case of the normal ASCII input stream, Emacs has a
concept of "input events", and ASCII characters are a subset of that.  The
events that Emacs knows about are not X events, but are a generalization of
them, so that Emacs can eventually be ported to different window systems.

We have reimplemented keymaps so that sequences of events can be stored into
them instead of just ASCII codes; it is possible to, for example, bind
different commands to each of the chords Control-h, Control-H, Backspace,
Control-Backspace, and Super-Shift-Backspace.  Key bindings, function key
bindings, and mouse bindings live in the same keymaps.

Input and display of all ISO-8859-1 characters is supported.

You can have multiple X windows ("screens" in lemacs terminology).

Our Emacs has objects called "extents" and "faces", which are roughly
analogous to Epoch's "buttons," "zones," and "styles."  An extent is a region
of text (a start position and an end position) and a face is a collection of
textual attributes like fonts and colors.  Every extent is displayed in some
"face", so changing the properties of a face immediately updates the display 
of all associated extents.  Faces can be screen-local: you can have a region
of text which displays with completely different attributes when its buffer
is viewed from a different X window.

The display attributes of faces may be specified either in lisp or through
the X resource manager.

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.

Emacs use 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 Emacs
window.  Also, Emacs understands the standard Xt command-line arguments.

Emacs understands the X11 "Selection" mechanism; it's possible to define
and customize selection converter functions and new selection types from 
elisp, without having to recompile Emacs.

Emacs now supports the Zmacs/Lispm style of region highlighting, where the
region between the point and mark is highlighted when in its "active" state.

Emacs has a menubar, whose contents are customizable from emacs-lisp.
This menubar looks Motif-ish, but does not require Motif.  If you already
own Motif, however, you can configure Emacs to use a *real* Motif menubar
instead.  If you have OLIT ("OpenLook Intrinsics"), you can use an
OpenWindows-like menubar.

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

The initial load-path is computed at run-time, instead of at compile-time.
This means that if you move the Emacs executable and associated directories
to somewhere else, you don't have to recompile anything.

You can specify what the title of the Emacs windows and icons should be
with the variables `screen-title-format' and `screen-icon-title-format',
which have the same syntax as `mode-line-format'.

Emacs now supports floating-point numbers.

Emacs now knows about timers directly, instead of them being simulated by
a subprocess.

Emacs understands truenames, and can be configured to notice when you are
visiting two names of the same file.  See the variables find-file-use-truenames
and find-file-compare-truenames.

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

Random changes to the emacs-lisp library: (some of this was not written by
us, but is included because it's free software and we think it's good stuff)

  - there is a new optimizing byte-compiler
  - there is a new abbrev-based mail-alias mechanism
  - the -*- line can contain local-variable settings
  - there is a new TAGS package
  - there is a new VI-emulation mode (evi)
  - there is a new implementation of Dired
  - there is a new implementation of Isearch

There are many more specifics in the "Miscellaneous Changes" section, below.

The online Emacs Manual is relatively up-to-date, but the Emacs-Lisp Manual
is not.

Differences between Lucid Emacs 19 and FSF Emacs 19
===================================================

In Lucid Emacs, events are first-class objects.  FSF19 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 Lucid Emacs, keymaps are first-class opaque objects.  FSF19 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 Lucid Emacs, Emacs 18, and and FSF Emacs 19; if your code depends on
the underlying implementation of keymaps, it will not.

Lucid Emacs calls a top-level emacs X window a "screen," which is the
terminology that Epoch used.  FSF 19 calls these "frames."  We may adopt
the term "frame" as well, but we have not done so yet.

Lucid Emacs 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.  A large subset of the FSF 19 
interface to text properties is supported in lemacs (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.

Here are some more specifics about the Lucid Emacs 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.

 key_press_event	
    event_channel	A token representing which keyboard generated it.
			For this kind of event, this is a screen 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 screen 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 screen object.
    timestamp		When it happened
    x, y		Where it was after it moved (in pixels).

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

 timeout_event
    timestamp		Now (really, when the timeout was signalled)
    function		The elisp function to call for this timeout.  It is
    			called with one argument, the event.
    object		Some lisp object associated with this timeout, to
    			make it easier to tell them apart.

 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 screen)
			but needs that to happen synchronously with the other
			user input, like keypresses.

 menu_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 selections in the menubar.  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 key- or menu-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 why eval_events
			exist.

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-screen-hook,
unmap-screen-hook, mouse-enter-screen-hook, and mouse-leave-screen-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 elisp, 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-event'.  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-event' 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.

We envision the dumb-tty handler functions doing function-key handling at
the lowest level.  So the terminal-specific code would set up some data
structure that would cause the key sequences that some ttys generate for
function keys to be converted to 'f1 and so on before next-event saw them.
We haven't implemented dumb-tty handling yet, but we will soon.


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
would delete a character, and ^H would be help.  There's no need to deal 
with xmodmap, kbd-translate-table, etc.

Here are some more examples: suppose you want to bind one function to Tab, 
and another to Control-Tab.  This can't be done if Tab and Control-I are the
same thing.  What about control keys that have no ASCII equivalent, like
Control-< ?  One might want that to be bound to set-mark-at-point-min.  We
want M-C-Backspace to be kill-backward-sexp.  But we want M-Backspace to be
kill-backward-word.  Again, this can't be done if Backspace and C-h are
indistinguishable.

The user represents keys as a string of ASCII characters (when possible and
convenient), or as a vector of event objects, or as a vector of "key 
description lists", that looks like (control a), or (control meta delete) 
or (shift f1).  The order of the modifier-names is not significant, so
(meta control x) and (control meta x) are the same.

Define-key knows how to take any of the above representations and store them
into a keymap.  When Emacs wants to return a key sequence (this-command-keys,
recent-keys, keyboard-macros, and read-key-sequence, for example) it returns
a vector of event objects.  Keyboard macros can also be represented as ASCII
strings or as vectors of key description lists.  

*** This is an incompatible change: code which calls this-command-keys,
recent-keys, read-key-sequence, or manipulates keyboard-macros probably
needs to be changed so that it no longer assumes that the returned value
is a string.

Control-Shift-a is specified as (control A), not (control shift a), since A
is a two-case character.  But for keys that don't have an upper case
version, like F1, Backspace, and Escape, you use the (shift backspace) syntax.

See the docstring for our version of define-key, reproduced below in the
`Changed Functions' section.  Note that when the KEYS argument is a string,
it has the same semantics as the v18 define-key.


Xt Integration
==============

The heart of the event loop is implemented in terms of the XtNextEvent,
and uses Xt's concept of timeouts and file-descriptor callbacks,
eliminating a large amount of system-dependent code (Xt does it for you.)

If Emacs is compiled with support for X, we plan to have it use the Xt
event loop even when Emacs is not running on an X display (the Xt event
loop supports this.)  This will make it possible to run Emacs on a dumb
tty, and later connect it to one or more X servers.  We hope also to make
it possible to later connect an existing Emacs process to additional ttys.
(Our intent at this point is not to have an Emacs that is being used by
multiple people at the same time: it is to make it possible for someone to
go home, log in on a dialup line, and connect to the same Emacs process
that is running under X in their office without having to recreate their
buffer state and so on.)

If Emacs is not compiled with support for X, then it will instead use
more general code, something like what v18 does; but this way of doing
things is a lot more modular.

(Linking Emacs with Xt seems to only add about 300k to the executable size,
compared with an Emacs linked with Xlib only.)


X Selections
============

We have reimplemented X Selection handling to be more general than before.
Almost all of it is implemented in emacs-lisp now, so it's possible to 
define new selection data types without having to recompile Emacs.  See
the documentation of the variables `selection-converter-alist', 
`x-lost-selection-hooks', `x-sent-selection-hooks', and the file
.../lisp/x11/xselect.el for more specifics.


Region Highlighting
===================

If the variable `zmacs-regions' is true, then the region between point and
mark will be highlighted when "active".  Those commands which push a mark
(such as C-SPC, and ^X^X) make the region become "active" and thus
highlighted.  Most commands (all non-motion commands, basically) cause it to
become non-highlighted (non-"active").  Commands that operate on the region
(such as ^W, ^X^L, etc) only work if the region is in the highlighted state.

zmacs-activate-region-hook and zmacs-deactivate-region-hook are run at the
appropriate times; under X, zmacs-activate-region-hook makes the X selection
be the region between point and mark, thus doing two things at once: making
the region and the X selection be the same; and making the region highlight
in the same way as the X selection.

mark-marker: subr
Return this buffer's mark, as a marker object.
If `zmacs-regions' is true, then this returns nil unless the region is
currently in the active (highlighted) state.  With an argument of t, this
returns the mark (if there is one) regardless of the active-region state.
You should *generally* not use the mark unless the region is active, if
the user has expressed a preference for the active-region model.
Watch out!  Moving this marker changes the mark position.
If you set the marker not to point anywhere, the buffer will have no mark.

In this way, the primary selection is a fairly transitory entity; but
when something is copied to the kill ring, it is made the Clipboard
selection.  It is also stored into CUT_BUFFER0, for compatibility with
X applications that don't understand selections (like Emacs18).

*** Compatibility note: if you have code which uses (mark) or (mark-marker),
then you need to either: change those calls to (mark t) or (mark-marker t);
or simply bind `zmacs-regions' to nil around the call to mark or mark-marker.
This is probably the best solution, since it will work in Emacs 18 as well.


Menubars and Dialog Boxes
=========================

Here is an example of a menubar definition:

(defvar default-menubar
  '(("File"	["New Screen"		x-new-screen		t]
		["Open File..."		find-file		t]
		["Save Buffer"		save-buffer		t]
		["Save Buffer As..."	write-file		t]
		["Revert Buffer"	revert-buffer		t]
		"-----"
		["Print Buffer"		lpr-buffer		t]
		"-----"
		["Delete Screen"	delete-screen		t]
		["Kill Buffer..."	kill-buffer		t]
		["Exit Emacs"		save-buffers-kill-emacs	t]
		)
    ("Edit"	["Undo"			advertised-undo		t]
		["Cut"			kill-primary-selection	t]
		["Copy"			copy-primary-selection	t]
		["Paste"		yank-clipboard-selection t]
		["Clear"		delete-primary-selection t]
		)
    ...))

The first element of each menu item is the string to print on the menu.

The second element is the callback function; if it is a symbol, it is
invoked with `call-interactively.'  If it is a list, it is invoked with
`eval'.  

If the second element is a symbol, then the menu also displays the key that
is bound to that command (if any).

The third element of the menu items determines whether the item is selectable.
It may be t, nil, or a form to evaluate.  Also, a hook is run just before a
menu is exposed, which can be used to change the value of these slots. 
For example, there is a hook that makes the "undo" menu item be selectable
only in the cases when `advertised-undo' would not signal an error.  

Menus may have other menus nested within them; they will cascade.

There are utility functions for adding items to menus, deleting items,
disabling them, etc.

The function `popup-menu' takes a menu description and pops it up.  

The function `popup-dialog-box' takes a dialog-box description and pops 
it up.  Dialog box descriptions look a lot like menu descriptions.

The menubar, menu, and dialog-box code is implemented as a library, 
with an interface which hides the toolkit that implements it.  


Isearch Changes
===============

Isearch has been reimplemented in a different way, adding some new features,
and causing a few incompatible changes.

 -  the old isearch-*-char variables are no longer supported.  In the old
    system, one could make ^A mean "repeat the search" by doing something
    like (setq search-repeat-char ?C-a).  In the new system, this is 
    accomplished with 

       (define-key isearch-mode-map "\C-a" 'isearch-repeat-forward)

 -  The advantage of using the normal keymap mechanism for this is that you
    can bind more than one key to an isearch command: for example, both C-a
    and C-s could do the same thing inside isearch mode.  You can also bind
    multi-key sequences inside of isearch mode, and bind non-ASCII keys.
    For example, to use the F1 key to terminate a search:

       (define-key isearch-mode-map 'f1 'isearch-exit)

    or to make ``C-c C-c'' terminate a search:

       (define-key isearch-mode-map "\C-c\C-c" 'isearch-exit)

 -  If isearch is behaving case-insensitively (the default) and you type an
    upper case character, then the search will become case-sensitive.  This
    can be disabled by setting `search-caps-disable-folding' to nil.

 -  There is a history ring of the strings previously searched for; typing
    M-p or M-n while searching will cycle through this ring.  Typing M-TAB
    will do completion across the set of items in the history ring.

 -  The ESC key is no longer used to terminate an incremental search.  The
    RET key should be used instead.  This change is necessary for it to be
    possible to bind "meta" characters to isearch commands.


Startup Code Changes
====================

The initial X screen is mapped before the user's .emacs file is executed.
Without this, there is no way for the user to see any error messages
generated by their .emacs file, any windows created by the .emacs file
don't show up, and the copyleft notice isn't shown.

The default values for load-path, exec-path, lock-directory, and
Info-directory-list are not (necessarily) built into Emacs, but are
computed at startup time.  

First, Emacs looks at the directory in which its executable file resides:

  o  If that directory contains subdirectories named "lisp" and "etc", then
     those directories are used as the lisp library and exec directory.

  o  If the parent of the directory in which the emacs executable is located
     contains "lisp" and "etc" subdirectories, then those are used.

  o  If the emacs executable that was run is a symbolic link, then the link
     is chased, and the resultant directory is checked as above.

(Actually, it doesn't just look for "lisp/", it looks for "lisp/prim/",
which reduces the chances of a false positive.)

Finally, if the lisp directory contains subdirectories, they are added to
the default load-path as well.  Subdirectories whose names begin with a dot
or a hyphen are not added to the load-path.

These heuristics fail if the Emacs binary was copied from the main Emacs
tree to some other directory, and links for the lisp directory were not put
in.  This isn't much of a restriction: either make there be subdirectories
(or symbolic links) of the directory of the emacs executable, or make the
"installed" emacs executable be a symbolic link to an executable in a more
appropriate directory structure.  For example, this setup works:

    /usr/local/lemacs/lemacs*		; The executable.
    /usr/local/lemacs/lisp/		; The associated directories.
    /usr/local/lemacs/etc/		; Any of the files in this list
    /usr/local/lemacs/lock/		; could be symbolic links as well.
    /usr/local/lemacs/info/

As does this:

    /usr/local/bin/lemacs -> ../lemacs/src/lemacs-19.8	; A link...
    /usr/local/lemacs/src/lemacs-19.8*			; The executable,
    /usr/local/lemacs/lisp/				; and the rest of
    /usr/local/lemacs/etc/				; the the source
    /usr/local/lemacs/lock/				; tree.
    /usr/local/lemacs/info/

This configuration might be used for a multi-architecture installation; assume
that $LOCAL refers to a directory which contains only files specific to a 
particular architecture (i.e., executables) and $SHARED refers to those files 
which are not machine specific (i.e., lisp code and documentation.)

    $LOCAL/bin/lemacs@ -> $LOCAL/lemacs-19.8/lemacs*
    $LOCAL/lemacs-19.8/lisp@ -> $SHARED/lemacs-19.8/lisp/
    $LOCAL/lemacs-19.8/etc@  -> $SHARED/lemacs-19.8/etc/
    $LOCAL/lemacs-19.8/info@ -> $SHARED/lemacs-19.8/info/

The following would also work, but the above is probably more attractive:

    $LOCAL/bin/lemacs*
    $LOCAL/bin/lisp@ -> $SHARED/lemacs-19.8/lisp/
    $LOCAL/bin/etc@  -> $SHARED/lemacs-19.8/etc/
    $LOCAL/bin/info@ -> $SHARED/lemacs-19.8/info/

If Emacs can't find the requisite directories, it writes a message like this
(or some appropriate subset of it) to stderr:

  WARNING:
  couldn't find an obvious default for load-path, exec-directory, and
  lock-directory, and there were no defaults specified in paths.h when
  Emacs was built.  Perhaps some directories don't exist, or the Emacs
  executable, /cadillac-th/jwz/somewhere/lemacs is in a strange place?

  Without both exec-directory and load-path, Emacs will be very broken.
  Consider making a symbolic link from /cadillac-th/jwz/somewhere/etc
  to wherever the appropriate Emacs etc/ directory is, and from
  /cadillac-th/jwz/somewhere/lisp/ to wherever the appropriate Emacs
  lisp library is.

  Without lock-directory set, file locking won't work.  Consider
  creating /cadillac-th/jwz/somewhere/lock as a directory or symbolic
  link for use as the lock directory.


X Resources
===========

The Emacs resources are generally per-screen.  Each Emacs screen can have its
own name, or the same name as another, depending on the name passed to the
x-create-screen function.  

You can specify resources for all screens with the syntax

	Emacs*parameter: value
or
	Emacs*EmacsScreen.parameter: value

You can specify resources for a particular screen with the syntax

	Emacs*SCREEN-NAME.parameter: value


To make the default size of all emacs be 80 columns by 55 lines, do this:

	Emacs*EmacsScreen.geometry: 80x55

To set the geometry of a particular screen named, "foo", do this:

	Emacs*foo.geometry: 80x55

In particular, do --NOT-- use this syntax:

	Emacs*geometry: 80x55

One should never use "*geometry" with any X application.  It does not say
"make the geometry of emacs be 80 columns by 55 lines."  It really says,
"make emacs and all subwindows thereof be 80x35 in whatever units they care
to measure in."  In particular, that is both telling the emacs text pane
to be 80x55 in characters, and telling the menubar pane to be 80x55 pixels,
which is surely not what you want.


Generally, all of the interesting resources are on the EmacsScreen widget.
However, the `geometry' and `iconic' resources on the unmapped ApplicationShell
(the topmost widget, the parent of the WM shell widgets, named `Emacs') are a
special case.  

The simple explanation is, -geometry overrides the resources of only the first 
screen created, otherwise "Emacs*SCREEN-NAME.geometry" is used.

The complicated explanation is:

  - The -geometry command line option sets the "Emacs.geometry" resource, that
    is, the geometry of the ApplicationShell.

  - For the first screen created, the size of the screen is taken from the 
    AppShell if it is specified, otherwise from the geometry of the screen.  

  - For subsequent screens, the order is reversed: first the screen, and then
    the AppShell.

  - For the first screen created, the position of the screen is taken from the
    AppShell ("Emacs.geometry") if it is specified, otherwise from the geometry
    of the screen.  

  - For subsequent screens, the position is taken only from the screen, and 
    never from the AppShell.

  This is rather complicated, but it does seem to provide the most intiutive
  behavior with respect to the default sizes and positions of screens created
  in various ways.

Analagous to -geometry, the -iconic command line option sets the iconic flag
of the AppShell ("Emacs.iconic") and always applies to the first screen created
regardless of its name.  However, it is possible to set the iconic flag on 
particular screens (by name) by using the "Emacs*SCREEN-NAME.iconic" resource.


Emacs screens accept the following resources:

  iconic (class Iconic): boolean

	Whether this screen should appear in the iconified state.

  internalBorderWidth (class InternalBorderWidth): int

	How many blank pixels to leave between the text and the edge of the
	window.

  interline (class Interline): int

	How many pixels to leave between each line.

  cursorColor (class CursorColor): color

	The color of the text cursor.

  textPointer (class Cursor): cursor-name

	The cursor to use when the mouse is over text.  This resource is
	used to initialize the variable `x-pointer-shape'.

  spacePointer (class Cursor): cursor-name

	The cursor to use when the mouse is over a blank space in a buffer
	(that is, after the end of a line or after the end-of-file).  This
	resource is used to initialize the variable `x-nontext-pointer-shape'.

  modePointer (class Cursor): cursor-name

	The cursor to use when the mouse is over a modeline.  This resource
	is used to initialize the variable `x-mode-pointer-shape'.

  gcPointer (class Cursor): cursor-name

	The cursor to display when a garbage-collection is in progress.  This
	resource is used to initialize the variable `x-gc-pointer-shape'.

  pointerColor (class Foreground): color-name

	The foreground and background colors of the mouse cursors.  
	These resources are used to initialize the variables 
	`x-pointer-foreground-color' and `x-pointer-background-color'.


The attributes of faces are also per-screen.  They may be specified as

	Emacs*FACE-NAME.parameter: value
or
	Emacs*SCREEN-NAME.FACE-NAME.parameter: value

Faces accept the following resources:

  attributeFont (class AttributeFont): font-name

	The font of this face.

  attributeForeground (class AttributeForeground): color-name
  attributeBackground (class AttributeBackground): color-name

	The foreground and background colors of this face.

  attributeBackgroundPixmap (class attributeBackgroundPixmap): file-name

	The name of an XBM file, to use as a background stipple.

  attributeUnderline (class AttributeUnderline): boolean

	Whether text in this face should be underlined.

All text is displayed in some face, defaulting to the face named "default".
So to set the font of normal text, use "Emacs*default.attributeFont".
To set it in the screen named "foo", use "Emacs*foo.default.attributeFont".

These are the names of the predefined faces:

	default			Everything inherits from this.

	highlight		This is used to highlight certain extents 
				when the mouse passes over them.

	bold			If this is not specified in the resource
				database, Emacs tries to find a "bold" 
				version of the font of the "default" face.

	italic			ditto.

	bold-italic		ditto.

	primary-selection	This is the face that mouse-selections are
				displayed in.

	isearch			This is the face that the matched text being
				searched for is displayed in.

	info-node		This is the face of info menu items.  If
				unspecified, it is copied from "bold-italic".

	info-xref		This is the face of info cross-references.
				If unspecified, it is copied from "bold".

Other packages might define their own faces; to see a list of all faces, use
any of the interactive face-manipulation commands such as `set-face-font') and
type `?' when you are prompted for the name of a face.

If the bold, italic, and bold-italic faces are not specified in the resource
database, then emacs attempts to derive them from the font of the default face.
It can only succeed at this if you have specified the default font using the
XLFD (X Logical Font Description) format, which looks like

	*-courier-medium-r-*-*-*-120-*-*-*-*-*-*

if you use any of the other, less strict font name formats, some of which
look like
		lucidasanstypewriter-12
and		fixed
and		9x13

then emacs won't be able to guess the names of the bold and italic versions.
All X fonts can be referred to via XLFD-style names, so you should use those
forms.  See the man pages for X(1), xlsfonts(1), and xfontsel(1).


There are several structural widgets between the terminal EmacsScreen widget
and the top level ApplicationShell; the exact names and types of these widgets
are subject to change in the future, so you should avoid mentioning them in
your resource database.  The above-mentioned syntaxes should be forward-
compatible.  As of 19.9, the exact widget hierarchy is as follows:

For Motif:
-----------
   invocation-name            "shell"          "pane"          screen-name
   x-emacs-application-class  "TopLevelShell"  "XmMainWindow"  "EmacsScreen"

For Athena:
-----------
   invocation-name            "shell"          "pane"   "pane"   screen-name
   x-emacs-application-class  "TopLevelShell"  "Paned"  "Paned"  "EmacsScreen"

where `invocation-name' is the terminal component of the name of the emacs
executable, and `x-emacs-application-class' is generally "Emacs".

Since, as you see, the exact widget hierarchy depends on the toolkit in use,
and is subject to change in the future, it is best to use wildcards instead of
fully specifying the path of the resource you want to st.

Here is the hierarchy including the other widgets:

	Widget Name:            Athena Class:       Motif Class:
	------------            -------------       ------------
	lemacs                  Emacs               Emacs
	  shell                 TopLevelShell       TopLevelShell
	    pane                Paned               XmMainWindow
	      menubar           XlwMenu             XmMenuBar
	      lower_pane        Paned               *
	        screen-name     EmacsScreen         EmacsScreen
	        sb_container    Paned               XmPanedWindow
	          scrollbar     Scrollbar           XmScrollBar
	    dialog              XtPopupShell        XmDialogShell
              label             Label               XmLabel
              button1 ...       Command             XmPushbutton

  * Note that the "lower_pane" widget exists only in Athena versions;
    in Motif versions, both the "menubar" and `screen-name' widgets
    are children of the "pane".

As the menubar is implemented as a widget which is not a part of emacs proper,
it does not use the "face" mechanism for specifying fonts and colors: it uses
whatever resources are appropriate to the type of widget which is used to
implement it.

If Emacs was compiled to use only the Motif-lookalike menu widgets, then one
way to specify the font of the menubar would be

	Emacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*

If the Motif library is being used, then one would have to use 

	Emacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*

because the Motif library uses the "fontList" resource name instead of "font",
which has subtly different semantics.

The same is true of the scrollbars: they accept whichever resources are 
appropriate to the toolkit in use.


Source Code Highlighting
========================

It's possible to have your buffers "decorated" with fonts or colors indicating
syntactic structures (such as strings, comments, function names, "reserved
words", etc.)  In Lucid Emacs, the preferred way to do this is with 
font-lock-mode; activate it by adding the following code to your .emacs file:

	(add-hook 'emacs-lisp-mode-hook	'turn-on-font-lock)
	(add-hook 'c-mode-hook		'turn-on-font-lock)
	(add-hook 'c++-mode-hook	'turn-on-font-lock)
	(add-hook 'dired-mode-hook	'turn-on-font-lock)
	...etc...

To customize it, see the descriptions of the function `font-lock-mode' and
the variables `font-lock-keywords', `c-font-lock-keywords', etc.

There exist several other source code highlighting packages, but font-lock
does does one thing that most others don't do: highlights as you type new
text; and one thing that no others do: bases part of its decoration on the
syntax table of the major mode.  Font-lock has C-level support to do this
efficiently, so it should also be significantly faster than the others.

If there's something that another highlighting package does that you can't
make font-lock do, let us know.  We would prefer to consolidate all of the
desired functionality into one package rather than ship several different
packages which do essentially the same thing in different ways.


Known Problems / TODO List
==========================

There are a number of minor redisplay glitches involving the echo area and
minibuffer.  These will be fixed soon.  

Many of the `screen-parameters' don't work.  I'm not convinced that the
screen-parameters/modify-screen-parameters functions are the best interface
anyway.

The Motif-like menubar that xlwmenu.c defines should use the same resources
that real Motif menubars use (as much as possible, anyway.)

The `mouse-motion-hook' should be called whenever a buffer scrolls or the
sizes of windows change, so that it can correctly frob the mouse-cursor based
on the text that the mouse is now over.

We should use the configure system for emacs and lwlib, and should not use
imake.  (Won't someone please volunteer to do this?)

We need to implement a non-Xt event_stream, based on select() and/or timer
signals, so that emacs can be *compiled* without support for X.  (Note that
this is different than emacs *running* without X.)

It should be possible to open emacs screens on multiple X displays and 
multiple dumb-ttys simultaneously.

It should be possible to have a process-filter-function that doesn't get 
called with a string; rather, the output is simply put in a buffer.  This
is like a process having both a buffer and a filter-function.  This would
be a good thing because it would mean that a string need not be consed every
time a process generated output, and yet you could be signalled that output
had arrived.


Miscellaneous Changes
=====================

What follows is a semi-automatically generated list of the new functions and
variables included with Lucid Emacs, and those functions and variables whose
semantics have changed since Emacs 18.57.

New Functions:
==============

abbreviate-file-name: (filename &optional hack-homedir)
Return a version of FILENAME shortened using `directory-abbrev-alist'.
See C-h v directory-abbrev-alist RET for more information.
If optional argument HACK-HOMEDIR is non-nil, then This also substitutes
"~" for the user's home directory.

------------------------------
abs: (arg)
Return the absolute value of ARG.

------------------------------
acos: (arg)
Return the inverse cosine of ARG.

------------------------------
asin: (arg)
Return the inverse sine of ARG.

------------------------------
atan: (arg1 &optional arg2)
Return the inverse tangent of ARG.

------------------------------
add-hook: (hook function &optional append)

Add to the value of HOOK the function FUNCTION.
FUNCTION is not added if already present.
FUNCTION is added (if necessary) at the beginning of the hook list
unless the optional argument APPEND is non-nil, in which case
FUNCTION is added at the end.

HOOK should be a symbol, and FUNCTION may be any valid function.  If
HOOK is void, it is first set to nil.  If HOOK's value is a single
function, it is changed to a list of functions.

------------------------------
add-menu-item: (menu-path item-name function enabled-p &optional before)

Add a menu item to some menu, creating the menu first if necessary.
If the named item exists already, it is changed.
MENU-PATH identifies the menu under which the new menu item should be inserted.
 It is a list of strings; for example, ("File") names the top-level "File"
 menu.  ("File" "Foo") names a hypothetical submenu of "File".
ITEM-NAME is the string naming the menu item to be added.
FUNCTION is the command to invoke when this menu item is selected.
 If it is a symbol, then it is invoked with `call-interactively', in the same
 way that functions bound to keys are invoked.  If it is a list, then the 
 list is simply evaluated.
ENABLED-P controls whether the item is selectable or not.  It may be t, nil,
 or a form to evaluate.  It will be evaluated each time the menubar is 
 activated.
BEFORE, if provided, is the name of a menu item before which this item should
 be added, if this item is not on the menu already.  If the item is already
 present, it will not be moved.

------------------------------
add-menu: (menu-path menu-name menu-items &optional before)

Add a menu to the menubar or one of its submenus.
If the named menu exists already, it is changed.
MENU-PATH identifies the menu under which the new menu should be inserted.
 It is a list of strings; for example, ("File") names the top-level "File"
 menu.  ("File" "Foo") names a hypothetical submenu of "File".
 If MENU-PATH is nil, then the menu will be added to the menubar itself.
MENU-NAME is the string naming the menu to be added.
MENU-ITEMS is a list of menu item descriptions.
 Each menu item should be a vector of three elements:
   - a string, the name of the menu item;
   - a symbol naming a command, or a form to evaluate;
   - and t or nil, whether this item is selectable.
BEFORE, if provided, is the name of a menu before which this menu should
 be added, if this menu is not on its parent already.  If the menu is already
 present, it will not be moved.

------------------------------
add-timeout: (secs function object &optional resignal)

SECS is a number of seconds, expressed as an integer or a float.
FUNCTION will be called after that many seconds have elapsed, with one
argument, the given OBJECT.  If the optional RESIGNAL argument is provided,
then after this timeout expires, `add-timeout' will automatically be called
again with RESIGNAL as the first argument.

This function returns an object which is the `id' of this particular timeout.
You can pass that object to `disable-timeout' to turn off the timeout before
it has been signalled.

The number of seconds may be expressed as a floating-point number, in which
case some fractional part of a second will be used.  Caveat: the usable
timeout granularity will vary from system to system.

Adding a timeout causes a timeout event to be returned by `next-event', and
the function will be invoked by `dispatch-event,' so if emacs is in a tight
loop, the function will not be invoked until the next call to sit-for or
until the return to top-level (the same is true of process filters.)

WARNING: if you are thinking of calling add-timeout from inside of a
callback function as a way of resignalling a timeout, think again.  There
is a race condition.  That's why the RESIGNAL argument exists.

------------------------------
allocate-event: ()

Returns an empty event structure.
WARNING, the event object returned may be a reused one; see the function
`deallocate-event'.

------------------------------
backtrace-frame: (nframes)

Return the function and arguments N frames up from current execution point.
If that frame has not evaluated the arguments yet (or is a special form),
the value is (nil FUNCTION ARG-FORMS...).
If that frame has evaluated its arguments and called its function already,
the value is (t FUNCTION ARG-VALUES...).
A &rest arg is represented as the tail of the list ARG-VALUES.
FUNCTION is whatever was supplied as car of evaluated list,
or a lambda expression for macro calls.
If N is more than the number of frames, the value is nil.

------------------------------
buffer-list: (&optional screen)

Return a list of all existing live buffers.
The order is specific to the selected screen; if the optional SCREEN
argument is provided, the ordering for that screen is returned instead.
If the SCREEN argument is t, then the global (non-screen) ordering is
returned instead.

------------------------------
buffer-modified-tick: (&optional buffer)

Return BUFFER's tick counter, incremented for each change in text.
Each buffer has a tick counter which is incremented each time the text in
that buffer is changed.  It wraps around occasionally.
No argument or nil as argument means use current buffer as BUFFER.

------------------------------
button-press-event-p: (obj)
True if the argument is a mouse-button-press event object.

------------------------------
button-release-event-p: (obj)
True if the argument is a mouse-button-release event object.

------------------------------
byte-compile-and-load-file: (filename)

Compile a file of Lisp code named FILENAME into a file of byte code,
and then load it.  The output file's name is made by appending "c" to 
the end of FILENAME.

------------------------------
byte-compile-buffer: (&optional buffer)
Byte-compile and evaluate contents of BUFFER (default: the current buffer).

------------------------------
byte-compiler-options: (&rest args)

Set some compilation-parameters for this file.  This will affect only the
file in which it appears; this does nothing when evaluated, and when loaded
from a .el file.

Each argument to this macro must be a list of a key and a value.

  Keys:		  Values:		Corresponding variable:

  verbose	  t, nil		byte-compile-verbose
  optimize	  t, nil, source, byte	byte-compile-optimize
  warnings	  list of warnings	byte-compile-warnings
		      Legal elements: (callargs redefine free-vars unresolved)
  file-format	  emacs18, emacs19	byte-compile-emacs18-compatibility
  new-bytecodes	  t, nil		byte-compile-generate-emacs19-bytecodes

For example, this might appear at the top of a source file:

    (byte-compiler-options
      (optimize t)
      (warnings (- free-vars))		; Don't warn about free variables
      (file-format emacs19))

------------------------------
case-table-p: (table)
Return t iff ARG is a case table.
See `set-case-table' for more information on these data structures.

------------------------------
ceiling: (arg)
Return the smallest integer no less than ARG.  (Round toward +inf.)

------------------------------
character-to-event: (ch &optional event)

Converts a numeric ASCII value to an event structure, replete with
bucky bits.  The character is the first argument, and the event to fill
in is the second.  This function contains knowledge about what the codes
``mean'' -- for example, the number 9 is converted to the character ``Tab'',
not the distinct character ``Control-I''.

If the optional second argument is an event, it is modified; otherwise, a
new event object is created.

Beware that character-to-event and event-to-character are not strictly 
inverse functions, since events contain much more information than the 
ASCII character set can encode.

------------------------------
clrhash: (table)
Flush TABLE.

------------------------------
compile-defun: ()
Compile and evaluate the current top-level form.
Print the result in the minibuffer.
With argument, insert value in current buffer after the form.

------------------------------
compiled-function-arglist: (function)
Returns the argument list of the compiled-function object.

------------------------------
compiled-function-constants: (function)
Returns the constants vector of the compiled-function object.

------------------------------
compiled-function-instructions: (function)
Returns the byte-opcode string of the compiled-function object.

------------------------------
compiled-function-interactive: (function)
Returns the interactive spec of the compiled-function object, or nil.

------------------------------
compiled-function-p: (obj)
T if OBJECT is a byte-compiled function object.

------------------------------
compiled-function-stack-depth: (function)
Returns the max stack depth of the compiled-function object.

------------------------------
conx: ()

Generate some random sentences in the *conx* buffer.
Output will be continuously generated until you type ^G.
Before running this function, you must snarf some text into the CONX 
database with the M-x conx-buffer or M-x conx-region commands.

------------------------------
copy-event: (event1 &optional event2)

Make a copy of the given event object.  If a second argument is given,
the first event is copied into the second and the second is returned.
If the second argument is not supplied (or is nil) then a new event will
be made as with `allocate-event.'  See also the function `deallocate-event'.

------------------------------
copy-extent: (extent &optional buffer)

Make a copy of EXTENT.  It is initially detached.
The optional BUFFER argument defaults to EXTENT's buffer.

------------------------------
copy-face: (old-face new-name &optional screen)

Defines and returns a new face which is a copy of an existing one,
or makes an already-existing face be exactly like another.

------------------------------
copy-tree: (arg &optional vecp)

Return a copy of a list and substructures.
The argument is copied, and any lists contained within it are copied
recursively.  Circularities and shared substructures are not preserved.
Second arg VECP causes vectors to be copied, too.  Strings are not copied.

------------------------------
cos: (arg)
Return the cosine of ARG.

------------------------------
cosh: (arg)
Return the hyperbolic cosine of ARG.

------------------------------
colorize-pixmap: (pixmap foreground background)

Make the pixmap be displayed in the given colors.
Pixmaps come in two varieties: bitmaps, which are 1 bit deep which are
rendered in the prevailing foreground and background colors; and pixmaps,
which are of arbitrary depth (including 1) and which have the colors
explicitly specified.  This function converts a bitmap to a pixmap.
If the pixmap was a pixmap already, nothing is done (and nil is returned.)
Otherwise t is returned.

------------------------------
current-case-table: ()
Return the case table of the current buffer.

------------------------------
current-time: ()

Return the current time, as the number of seconds since 12:00 AM January 1970.
The time is returned as a list of three integers.  The first has the
most significant 16 bits of the seconds, while the second has the
least significant 16 bits.  The third integer gives the microsecond
count.

The microsecond count is zero on systems that do not provide
resolution finer than a second.

------------------------------
deallocate-event: (event)

Allow the given event structure to be reused.  You MUST NOT use this 
event object after calling this function with it.  You will lose.
It is not necessary to call this function, as event objects are garbage-
collected like all other objects; however, it may be more efficient to
explicitly deallocate events when you are sure that that is safe.

------------------------------
deiconify-screen: (screen)
Open (de-iconify) the iconified screen SCREEN.

------------------------------
delete-extent: (extent)

Remove EXTENT from its buffer; this does not modify the buffer's text,
only its display properties.  The extent cannot be used thereafter.

------------------------------
delete-menu-item: (path)

Remove the named menu item from the menu hierarchy.
PATH is a list of strings which identify the position of the menu item in 
the menu hierarchy.  ("File" "Save") means the menu item called "Save"
under the toplevel "File" menu.  ("Menu" "Foo" "Item") means the 
menu item called "Item" under the "Foo" submenu of "Menu".

------------------------------
delete-screen: (&optional screen)

Delete SCREEN, permanently eliminating it from use.
Default is current screen.
A screen may not be deleted if its minibuffer is used by other screens.

------------------------------
delete-window: (&optional window)

Remove WINDOW from the display.  Default is selected window.
If window is the only one on the screen, the screen is destroyed.

------------------------------
detach-extent: (extent_obj)

Remove EXTENT from its buffer in such a way that it can be re-inserted.
An extent is also detached when all of its characters are all killed by a
deletion.

Extents which have the `duplicable' attribute are tracked by the undo
mechanism.  Detachment via `detach-extent' and string deletion is recorded,
as is attachment via `insert-extent', `update-extent', and string insertion.
Extent motion, face changes, and attachment via `make-extent' are not
recorded.  This means that extent changes which are to be undo-able must be
performed by character editing, or by insertion and detachment of duplicable
extents.

------------------------------
disable-menu-item: (path)

Make the named menu item be unselectable.
PATH is a list of strings which identify the position of the menu item in 
the menu hierarchy.  ("File" "Save") means the menu item called "Save"
under the toplevel "File" menu.  ("Menu" "Foo" "Item") means the 
menu item called "Item" under the "Foo" submenu of "Menu".

------------------------------
disable-timeout: (id)

Given a timeout id number as returned by `add-timeout', this function
will cause that timeout to not be signalled if it hasn't been already.

------------------------------
dispatch-event: (event)
Given an event object returned by next-event, execute it.

------------------------------
enable-menu-item: (path)

Make the named menu item be selectable.
PATH is a list of strings which identify the position of the menu item in 
the menu hierarchy.  ("File" "Save") means the menu item called "Save"
under the toplevel "File" menu.  ("Menu" "Foo" "Item") means the 
menu item called "Item" under the "Foo" submenu of "Menu".

------------------------------
enqueue-eval-event: (function object)

Add an eval event to the back of the queue.
The eval-event will be the next event read after all pending events.

------------------------------
eval-and-compile: (&rest body)
Like `progn', but evaluates the body at compile time and at load time.

------------------------------
eval-event-p: (obj)
True if the argument is an `eval' or `menu' event object.

------------------------------
eval-when-compile: ()

Like `progn', but evaluates the body at compile time.
The result of the body appears to the compiler as a quoted constant.

------------------------------
event-button: (event)

Returns the button-number of the given mouse-button-press event.

------------------------------
event-function: (event)
Returns the callback function of the given timeout, menu, or eval event.

------------------------------
event-glyph: (event)

If the given mouse-motion, button-press, or button-release event happened
on top of a glyph, this returns it; else nil.

------------------------------
event-key: (event)

Returns the KeySym of the given key-press event.  This will be the
ASCII code of a printing character, or a symbol.

------------------------------
event-modifier-bits: (event)

Returns a number representing the modifier keys which were down 
when the given mouse or keyboard event was produced.  See also the function
event-modifiers.

------------------------------
event-modifiers: (event)

Returns a list of symbols, the names of the modifier keys which 
were down when the given mouse or keyboard event was produced.
See also the function event-modifier-bits.

------------------------------
event-object: (event)

Returns the callback function argument of the given timeout, menu, or
eval event.

------------------------------
event-point: (event)

Returns the character position of the given mouse-motion, button-press,
or button-release event.  If the event did not occur over a window, or did
not occur over text, then this returns nil.  Otherwise, it returns an index
into the buffer visible in the event's window.

------------------------------
event-process: (event)
Returns the process of the given proces-output event.

------------------------------
event-screen: (event)
Given a mouse motion, button press, or button release event, return
the screen on which that event occurred.  This will be nil for non-mouse
events.

------------------------------
event-timestamp: (event)
Returns the timestamp of the given event object.

------------------------------
event-to-character: (event &optional allow-extra-modifiers allow-meta
                     allow-non-ascii)

Returns the closest ASCII approximation to the given event object.
If the event isn't a keypress, this returns nil.
If the ALLOW-EXTRA-MODIFIERS argument is non-nil, then this is lenient in
 its translation; it will ignore modifier keys other than control and meta,
 and will ignore the shift modifier on those characters which have no
 shifted ASCII equivalent (Control-Shift-A for example, will be mapped to
 the same ASCII code as Control-A.)

If the ALLOW-META argument is non-nil, then the Meta modifier will be
 represented by turning on the high bit of the byte returned; otherwise, nil
 will be returned for events containing the Meta modifier.
If the ALLOW-NON-ASCII argument is non-nil, then characters which are
 present in the prevailing character set (see the `character-set-property'
 variable) will be returned as their code in that character set, instead of
 the return value being restricted to ASCII.
Note that specifying both ALLOW-META and ALLOW-NON-ASCII is ambiguous, as
 both use the high bit; `M-x' and `oslash' will be indistinguishable.

------------------------------
event-window: (event)

Given a mouse motion, button press, or button release event, compute
and return the window on which that event occurred.  This may be nil if
the event did not occur in an emacs window (in the border or modeline.)

------------------------------
event-x: (event)
Returns the X position of the given mouse-motion, button-press, or
button-release event in characters.

------------------------------
event-x-pixel: (event)
Returns the X position of the given mouse-motion, button-press, or
button-release event in pixels.

------------------------------
event-y: (event)
Returns the Y position of the given mouse-motion, button-press, or
button-release event in characters.

------------------------------
event-y-pixel: (event)
Returns the Y position of the given mouse-motion, button-press, or
button-release event in pixels.

------------------------------
eventp: (obj)
True if the argument is an event object.

------------------------------
events-to-keys: (events &optional no-mice)

Given a vector of event objects, returns a vector of key descriptors,
or a string (if they all fit in the ASCII range.)
Optional arg NO-MICE means that button events are not allowed.

------------------------------
exp: (arg)
Return the exponential base e of ARG.

------------------------------
expt: (x y)
Return the exponential x ** y.

------------------------------
extent-at: (pos &optional buffer property before)

Find "smallest" extent at POS in BUFFER having PROPERTY set.
BUFFER defaults to the current buffer.
PROPERTY defaults to nil, meaning that any extent will do.
Properties are attached to extents with `set-extent-property', which see.
Returns nil if there is no matching extent at POS.
If the fourth argument BEFORE is not nil, it must be an extent; any returned
extent will precede that extent.  This feature allows `extent-at' to be used
by a loop over extents.

------------------------------
extent-buffer: (extent_obj)
Return buffer of EXTENT.

------------------------------
extent-end-position: (extent)
Return first position after EXTENT.

------------------------------
extent-face: (extent)
Returns the name of the face in which EXTENT is displayed, or nil
if the extent's face is unspecified.

------------------------------
extent-glyph: (extent)

Return the glyph object associated with EXTENT.
Returns nil, a pixmap, or a string.

------------------------------
extent-in-region-p: (extent &optional from to closed-end)

Whether map-extents would visit EXTENT when called with these args.

------------------------------
extent-length: (extent)
Return length of EXTENT in characters.

------------------------------
extent-priority: (extent)
Returns the display priority of EXTENT; see `set-extent-priority'.

------------------------------
extent-properties: (extent)

Return a property list of the attributes of the given extent.
Do not modify this list; use `set-extent-property' instead.

------------------------------
extent-property: (extent property)

Returns the extent's value of the given property.
See `set-extent-property' for builtin property names.

------------------------------
extent-start-position: (extent)
Return start position of EXTENT.

------------------------------
extentp: (extent)
T if OBJECT is an extent..

------------------------------
face-background: (face &optional screen)
Returns the background color name of the given face, or nil if unspecified.

------------------------------
face-background-pixmap: (face &optional screen)
Returns the background pixmap of the given face, or nil if unspecified.

------------------------------
face-differs-from-default-p: (face &optional screen)

True if the given face will display differently from the default face.
A face is considered to be ``the same'' as the default face if it is 
actually specified in the same way (equivalent fonts, etc) or if it is 
fully unspecified, and thus will inherit the attributes of any face it 
is displayed on top of.

------------------------------
face-equal: (face1 face2 &optional screen)
True if the given faces will display in the the same way.

------------------------------
face-font: (face &optional screen)
Returns the font of the given face, or nil if it is unspecified.

------------------------------
face-font-name: (face &optional screen)
Returns the font name of the given face, or nil if it is unspecified.

------------------------------
face-foreground: (face &optional screen)
Returns the foreground color of the given face, or nil if unspecified.

------------------------------
face-id: (face)
Returns the internal ID number of the given face.

------------------------------
face-underline-p: (face &optional screen)
Returns whether the given face is underlined.

------------------------------
fceiling: (arg)
Return the smallest integer no less than ARG, as a float.
(Round toward +inf.)

------------------------------
ffloor: (arg)
Return the largest integer no greater than ARG, as a float.
(Round towards -inf.)

------------------------------
font-name: (font)
Returns the name used to allocate the given font.

------------------------------
font-truename: (font)
Returns the canonical name of the given font.
Font names are patterns which may match any number of fonts, of which
the first found is used.  This returns an unambiguous name for that font
(but not necessarily its only unambiguous name.)

------------------------------
fontp: (obj)
Whether the given object is a font.

------------------------------
fround: (arg)
Return the nearest integer to ARG, as a float.

------------------------------
ftruncate: (arg)
Truncate a floating point number to an integral float value.
Rounds the value toward zero.

------------------------------
file-executable-p: (filename)
Return t if FILENAME can be executed by you.
For a directory, this means you can access files in that directory.

------------------------------
find-face: (name &optional screen)

Retrieve the face of the given name.
If NAME is a symbol and SCREEN is provided, the face is looked up on
that screen; otherwise, the selected screen is used.
If there is no such face, returns nil.
If SCREEN is the symbol t, then the global, non-screen face is returned.
If NAME is already a face, it is simply returned.

------------------------------
find-file-new-screen: (filename)

Just like find-file, but creates a new screen for it first.

------------------------------
float: (arg)
Return the floating point number equal to ARG.

------------------------------
floor: (arg)
Return the largest integer no greater than ARG.  (Round towards -inf.)

------------------------------
force-highlight-extent: (extent &optional flag)

Highlight any EXTENT if FLAG is not nil, else unhighlight it.
This is the same as `highlight-extent', except that it will work even
on extents without the 'highlight property.

------------------------------
forward-comment: (n)

Move forward across up to N comments.  If N is negative, move backward.
Stop scanning if we find something other than a comment or whitespace.
Set point to where scanning stops.
If N comments are found as expected, with nothing except whitespace
between them, return t; otherwise return nil.
Point is set in either case.

------------------------------
get-face: (name &optional screen)

Retrieve the face of the given name.
If NAME is a symbol and SCREEN is provided, the face is looked up on
that screen; otherwise, the selected screen is used.
If there is no such face, an error is signalled.  See also `find-face'.
If SCREEN is the symbol t, then the global, non-screen face is returned.
If NAME is already a face, it is simply returned.

------------------------------
get-screen-for-buffer: (buffer &optional not-this-window-p on-screen)

Select and return a screen in which to display BUFFER.
Normally, the buffer will simply be displayed in the current screen.
But if the symbol naming the major-mode of the buffer has a 'screen-name
property (which should be a symbol), then the buffer will be displayed in
a screen of that name.  If there is no screen of that name, then one is
created.  

If the major-mode doesn't have a 'screen-name property, then the screen
named by `get-screen-for-buffer-default-screen-name' will be used.  If
that is nil (the default) then the currently selected screen will used.

If the screen-name symbol has an 'instance-limit property (an integer)
then each time a buffer of the mode in question is displayed, a new screen
with that name will be created, until there are `instance-limit' of them.
If instance-limit is 0, then a new screen will be created each time.

If a buffer is already displayed in a screen, then `instance-limit' is 
ignored, and that screen is used.

If the screen-name symbol has a 'screen-defaults property, then that is
prepended to the `screen-default-alist' when creating a screen for the
first time.

This function may be used as the value of `pre-display-buffer-function', 
to cause the display-buffer function and its callers to exhibit the above
behavior.

------------------------------
getf: (plist prop &optional defalt)
Search PROPLIST for property PROPNAME; return its value or DEFAULT.
PROPLIST is a list of the sort returned by `symbol-plist'.

------------------------------
gethash: (key table &optional default)
Find hash value for KEY in TABLE.
If there is no corresponding value, return DEFAULT (default nil)

------------------------------
hashtable-fullness: (table)
Returns number of entries in TABLE.

------------------------------
hashtablep: (obj)
Returns t if OBJ is a hashtable, else nil.

------------------------------
highlight-extent: (extent &optional flag)

If EXTENT is `highlightable' (has the 'highlight property) then highlight
it (by using merging it with 'highlight face.)  If FLAG is nil, then
unhighlight it instead.

------------------------------
iconify-screen: (screen)
Make the screen SCREEN into an icon, if the window manager supports icons.

------------------------------
invert-face: (face &optional screen)

Swap the foreground and background colors of the given face.
If the face doesn't specify both foreground and background, then
its foreground and background are set to the background and
foreground of the default face.

------------------------------
key-press-event-p: (obj)
True if the argument is a key-press event object.

------------------------------
keymap-parent: (keymap)

Returns the `parent' keymap of the given keymap, or nil.
The parent of a keymap is searched for keybindings when a key sequence
isn't bound in this one.  The (current-global-map) is the default parent
of all keymaps.

------------------------------
keymapp: (object)
Return t if ARG is a keymap object.

------------------------------
list-faces: ()
Returns a list of the names of all of the defined faces.

------------------------------
live-screen-p: (object)

Return non-nil if OBJECT is a screen which has not been deleted.
Value is nil if OBJECT is not a live screen.  If object is a live
screen, the return value indicates what sort of output device it is
displayed on.  Value is t for a termcap screen (a character-only
terminal), `x' for an Emacs screen being displayed in an X window.

------------------------------
load-average: ()

Return list of 1 minute, 5 minute and 15 minute load averages.
Each of the three load averages is multiplied by 100,
then converted to integer.

If the 5-minute or 15-minute load averages are not available, return a
shortened list, containing only those averages which are available.

On most systems, this won't work unless the emacs executable is installed
as setgid kmem (assuming that /dev/kmem is in the group kmem.)

------------------------------
load-default-sounds: ()

Load and install some sound files as beep-types.
This only works if you're on display 0 of a Sun SparcStation, SGI machine,
or HP9000s700.

------------------------------
load-sound-file: (filename sound-name &optional volume)
Read in an audio-file and add it to the sound-alist.

------------------------------
locate-library: (library &optional nosuffix)

Show the full path name of Emacs library LIBRARY.
This command searches the directories in `load-path' like `M-x load-library'
to find the file that `M-x load-library RET LIBRARY RET' would load.
Optional second arg NOSUFFIX non-nil means don't add suffixes `.elc' or `.el'
to the specified name LIBRARY (a la calling `load' instead of `load-library').

------------------------------
log: (arg1 &optional arg2)
Return the natural logarithm of ARG.
With two arguments, return the logarithm of ARG to the base ARG2.

------------------------------
log10: (arg)
Return the logarithm base 10 of ARG.

------------------------------
make-cursor: (name &optional fg bg screen)

Creates a new `cursor' object of the specified name.
The optional second and third arguments are the foreground and background
 colors.  They may be color name strings or `pixel' objects.
The optional fourth argument is the screen on which to allocate the cursor
 (in case some screens are running on different X servers.)
This allocates a new cursor in the X server, and signals an error if the
 cursor is unknown or cannot be allocated.

A cursor name can take many different forms.  It can be:
 - any of the standard cursor names from appendix B of the Xlib manual
   (also known as the file <X11/cursorfont.h>) minus the XC_ prefix;
 - the name of a font, and glyph index into it of the form
   "FONT fontname index [[mask-font] mask-index]";
 - the name of a bitmap or pixmap file;
 - or a pixmap object, as returned by `make-pixmap'.

If it is a pixmap or pixmap file, and that pixmap comes with a mask, then
 that mask will be used.  If it is a pixmap, it must have only one plane,
 since X cursors may only have two colors.  If it is a pixmap file, then
 the file will be read in monochrome.

If it is a bitmap file, and if a bitmap file whose name is the name of the
 cursor with "msk" or "Mask" appended exists, then that second bitmap
 will be used as the mask.  For example, a pair of files might be named
 "cursor.xbm" and "cursor.xbmmsk".

The returned object is a normal, first-class lisp object.  The way you
`deallocate' the cursor is the way you deallocate any other lisp object:
you drop all pointers to it and allow it to be garbage collected.  When
these objects are GCed, the underlying X data is deallocated as well.

------------------------------
make-directory: (dir)
Create the directory DIR and any nonexistent parent dirs.

------------------------------
make-extent: (from to &optional buffer)

Make extent for range [FROM, TO) in BUFFER -- BUFFER defaults to 
current buffer.  Insertions at point TO will be outside of the extent;
insertions at FROM will be inside the extent (and the extent will grow.)
The extent is initially detached if if both FROM and TO are null, and
in this case BUFFER defaults to NIL, meaning the extent is in no buffer.
The initial attributes are (end-open), meaning that start and end points
behave like markers.

------------------------------
make-face: (name)

Defines and returns a new FACE on all screens.  
You can modify the font, color, etc of this face with the set-face- functions.
If the face already exists, it is unmodified.

------------------------------
make-face-bold: (face &optional screen)

Make the font of the given face be bold, if possible.  
Returns nil on failure.

------------------------------
make-face-bold-italic: (face &optional screen)

Make the font of the given face be bold and italic, if possible.  
Returns nil on failure.

------------------------------
make-face-italic: (face &optional screen)

Make the font of the given face be italic, if possible.  
Returns nil on failure.

------------------------------
make-face-larger: (face &optional screen)
Make the font of the given face be larger, if possible.  
Returns nil on failure.

------------------------------
make-face-smaller: (face &optional screen)
Make the font of the given face be smaller, if possible.  
Returns nil on failure.

------------------------------
make-face-unbold: (face &optional screen)

Make the font of the given face be non-bold, if possible.  
Returns nil on failure.

------------------------------
make-face-unitalic: (face &optional screen)

Make the font of the given face be non-italic, if possible.  
Returns nil on failure.

------------------------------
make-font: (name &optional screen)

Creates a new `font' object of the specified name.
The optional second argument is the screen on which to allocate the font
 (in case some screens are running on different X servers.)
This allocates a font in the X server, and signals an error if the font is
 unknown or cannot be allocated.

The returned object is a normal, first-class lisp object.  The way you
`deallocate' the font is the way you deallocate any other lisp object:
you drop all pointers to it and allow it to be garbage collected.  When
these objects are GCed, the underlying X data is deallocated as well.

------------------------------
make-hashtable: (size)
Make a hashtable of initial size SIZE.

------------------------------
make-keymap: ()

Construct and return a new keymap object.  All entries in it are nil,
meaning "command undefined".

------------------------------
make-obsolete: (fn new)

Make the byte-compiler warn that FUNCTION is obsolete.
The warning will say that NEW should be used instead.
If NEW is a string, that is the `use instead' message.

------------------------------
make-obsolete-variable: (var new)

Make the byte-compiler warn that VARIABLE is obsolete,
and NEW should be used instead.  If NEW is a string, then that is the
`use instead' message.

------------------------------
make-pixel: (name &optional screen)

Creates a new `pixel' object of the specified color.
The optional second argument is the screen on which to allocate the pixel
 (in case some screens are running on different X servers.)
This allocates a new color cell in the X server, and signals an error
if the color is unknown or cannot be allocated.

The returned object is a normal, first-class lisp object.  The way you
`deallocate' the color is the way you deallocate any other lisp object:
you drop all pointers to it and allow it to be garbage collected.  When
these objects are GCed, the underlying X data is deallocated as well.

------------------------------
make-pixmap: (name &optional screen)

Loads a new `pixmap' object from the specified file.
The file should be in `XBM' or `XPM' format.
If the XBMLANGPATH environment variable is set, it will be searched for
 matching files.  Next, the directories listed in the `x-bitmap-file-path'
 variable will be searched (this variable is initialized from the
 "*bitmapFilePath" resource.)
The file argument may also be a list of the form (width height data) where
 width and height are the size in pixels, and data is a string, containing
 the raw bits of the bitmap.  (Bitmaps specified this way can only be one bit
 deep.)
If compiled with support for XPM, the file argument may also be a string
 which is the contents of an XPM file (that is, a string beginning with the
 characters "/* XPM */"; see the XPM documentation.)
The optional second argument is the screen on which to allocate the pixmap
 (in case some screens are running on different X servers.)
This allocates a new Pixmap in the X server, and signals an error if the
 file can't be found, or the Pixmap cannot be allocated.

The returned object is a normal, first-class lisp object.  The way you
`deallocate' the pixmap is the way you deallocate any other lisp object:
you drop all pointers to it and allow it to be garbage collected.  When
these objects are GCed, the underlying X data is deallocated as well.

------------------------------
make-screen-invisible: (screen)

Unconditionally removes screen from the display (assuming it is an X-window).
If what you want to do is iconify the screen (if the window manager uses
icons) then you should call `iconify-screen' instead.

------------------------------
make-screen-visible: (screen)

Make the screen SCREEN visible (assuming it is an X-window).
Also raises the screen so that nothing obscures it.

------------------------------
make-temp-name: (prefix)

Generate temporary file name (string) starting with PREFIX (a string).
The Emacs process number forms part of the result,
so there is no danger of generating a name being used by another process.

------------------------------
make-weak-hashtable: (size)

Make a weak hashtable of initial size SIZE.
A weak hashtable is one whose pointers do not count as GC referents:
if the only remaining pointer to an object is in a weak hash table,
then that object will be removed from the table, and collected.  A
non-weak hash table (or any other pointer) would prevent the object
from being collected.

------------------------------
map-extents: (function &optional buffer from to maparg closed-end)

Map FUNCTION over the extents which overlap region in BUFFER,
starting at FROM and ending at TO.  FUNCTION is called with the arguments
 (extent, MAPARG).
The arguments FROM, TO, MAPARG, and BUFFER default to the beginning of
 BUFFER, the end of BUFFER, nil, and (current-buffer), respectively.
MAP-EXTENTS returns the first non-null result produced by FUNCTION,
and no more calls to FUNCTION are made after it returns non-null.
If BUFFER is an extent, FROM and TO default to the extent's endpoints,
and the mapping omits that extent and its predecessors.
This feature supports restarting a loop based on `map-extents'.

------------------------------
map-extent-children: (function &optional buffer from to maparg closed_end)

Map FUNCTION over the extents in the region from FROM to TO.
FUNCTION is called with arguments (extent, MAPARG).
The arguments are the same as for `map-extents', but this function differs
in that it only visits extents which start in the given region, and also
in that, after visiting an extent E, it skips all other extents which start
inside E but end before E's end.

Thus, this function may be used to walk a tree of extents in a buffer:
	(defun walk-extents (buffer &optional ignore)
	  (map-extent-children 'walk-extents buffer))

------------------------------
map-keymap: (function keymap &optional sort_first)

Apply FUNCTION to each element of KEYMAP.  FUNCTION will be called with
two arguments: a key-description list, and the binding.  The order in which
the elements of the keymap are passed to the function is unspecified.  If
the function inserts new elements into the keymap, it may or may not
be called with them later.  No element of the keymap will ever be passed to
the function more than once.

The function will not be called on elements of this keymap's parent (see the
function `keymap-parent') or upon keymaps which are contained within this
keymap (multi-character definitions).  It will be called on "meta"
characters, however, since they are not really two-character sequences.

If the optional third argument SORT-FIRST is non-nil, then the elements of
the keymap will be passed to the mapper function in a canonical order.
Otherwise, they will be passed in hash (that is, random) order, which is
faster.

------------------------------
maphash: (function table)

Map FUNCTION over entries in TABLE, calling it with two args,
each key and value in the table.

------------------------------
mark-bob: (&optional arg)					bound to C-<

Push a mark at the beginning of the buffer; leave point where it is.
With arg N, push mark N/10 of the way from the true beginning.

------------------------------
mark-eob: (&optional arg)					bound to C->

Push a mark at the end of the buffer; leave point where it is.
With arg N, push mark N/10 of the way from the true end.

------------------------------
member: (elt list)

Return non-nil if ELT is an element of LIST.  Comparison done with EQUAL.
The value is actually the tail of LIST whose car is ELT.

------------------------------
menu-event-p: (obj)
True if the argument is a menu event object.

------------------------------
modify-screen-parameters: (screen alist)

Modify the parameters of screen SCREEN according to ALIST.
ALIST is an alist of parameters to change and their new values.
Each element of ALIST has the form (PARM . VALUE), where PARM is a symbol.
The meaningful PARMs depend on the kind of screen; undefined PARMs are ignored.

------------------------------
motion-event-p: (obj)
True if the argument is a mouse-motion event object.

------------------------------
mouse-del-char: (event)
Delete the char pointed to by the mouse.

------------------------------
mouse-delete-window: ()
Delete the Emacs window the mouse is on.

------------------------------
mouse-drag-modeline: (event)

Resize the window by dragging the modeline.
This should be bound to a mouse button in `mode-line-map'.

------------------------------
mouse-keep-one-window: ()
Select Emacs window mouse is on, then kill all other Emacs windows.

------------------------------
mouse-kill-line: (event)
Kill the line pointed to by the mouse.

------------------------------
mouse-line-length: (event)
Print the length of the line indicated by the pointer.

------------------------------
mouse-scroll: (event)
Scroll point to the mouse position.

------------------------------
mouse-select: ()
Select Emacs window the mouse is on.

------------------------------
mouse-select-and-split: ()
Select Emacs window mouse is on, then split it vertically in half.

------------------------------
mouse-set-mark: (event)

Select Emacs window mouse is on, and set mark at mouse position.
Display cursor at that position for a second.

------------------------------
mouse-set-point: (event)
Select Emacs window mouse is on, and move point to mouse position.

------------------------------
mouse-track: (event)

Make a selection with the mouse.  This should be bound to a mouse button.
If you click-and-drag, the selection will be set to the region between the
point of the initial click and the point at which you release the button.
These positions need not be ordered.

If you click-and-release without moving the mouse, then the point is moved,
and the selection is disowned (there will be no selection owner.)  The mark
will be set to the previous position of point.

If you double-click, the selection will extend by symbols instead of by
characters.  If you triple-click, the selection will extend by lines.

If you drag the mouse off the top or bottom of the window, you can select
pieces of text which are larger than the visible part of the buffer; the 
buffer will scroll as necessary.

The selected text becomes the current X Selection, and is also copied to the
top of the kill ring.  The point will be left at the position at which you
released the button, and the mark will be left at the initial click position.

See also the `mouse-track-adjust' command, on Sh-button1.

------------------------------
mouse-track-adjust: (event)

Extend the existing selection.  This should be bound to a mouse button.
The selection will be enlarged or shrunk so that the point of the mouse
click is one of its endpoints.  This is only really meaningful after the
`mouse-track' command (button1) has been executed.

------------------------------
mouse-track-and-copy-to-cutbuffer: (event)
Makes a selection like `mouse-track', but also copies it to the cutbuffer.

------------------------------
mouse-track-delete-and-insert: (event)

Make a selection with the mouse and insert it at point.
This is exactly the same as the `mouse-track' command on button1, 
except that point is not moved; the selected text is immediately inserted
after being selected; and the text of the selection is deleted.

------------------------------
mouse-track-insert: (event)

Make a selection with the mouse and insert it at point.
This is exactly the same as the `mouse-track' command on button1, 
except that point is not moved; the selected text is immediately inserted
after being selected; and the selection is immediately disowned afterwards.

------------------------------
mouse-window-to-region: (event)
Narrow window to region between cursor and mouse pointer.

------------------------------
next-command-event: (&optional event)

Returns the next available "user" event from the window system or terminal
driver.  Pass this object to dispatch-event to handle it.  If an event object
is supplied, it is filled in and returned, otherwise a new event object will
be created.

The event returned will be a keyboard, mouse press, or mouse release event.
If there are non-command events available (mouse motion, sub-process output,
etc) then these will be executed (with `dispatch-event') and discarded.  This
function is provided as a convenience; it is equivalent to the lisp code

	(while (progn
		 (next-event event)
	         (not (or (key-press-event-p event)
	                  (button-press-event-p event)
	                  (button-release-event-p event)
	                  (menu-event-p event))))
	   (dispatch-event event))

------------------------------
next-event: (&optional event prompt)

Returns the next available event from the window system or terminal driver.
Pass this object to dispatch-event to handle it.  See also the function
next-command-event, which is often more appropriate.
If an event object is supplied, it is filled in and returned, otherwise a
new event object will be created.

------------------------------
next-extent: (extent_obj)

Find next extent after EXTENT. If EXTENT is a buffer
return the first extent in the buffer.

------------------------------
next-screen: (&optional screen miniscreen visible-only-p)

Return the next screen in the screen list after SCREEN.
If MINISCREEN is non-nil, include the global-minibuffer-screen if it
has its own screen.
If VISIBLE-ONLY-P is non-nil, then cycle through the visible screens,
instead of all screens.

------------------------------
other-window-any-screen: (n)

Select the ARG'th different window on any screen.
All windows on current screen are arranged in a cyclic order.
This command selects the window ARG steps away in that order.
A negative ARG moves in the opposite order.  However, unlike
`other-window', this command will select a window on the next
(or previous) screen instead of wrapping around to the top
(or bottom) of this screen, when there are no more windows.

------------------------------
pixel-name: (pixel)
Returns the name used to allocate the given pixel.

------------------------------
pixelp: (obj)
Whether the given object is a pixel.

------------------------------
pixmap-file-name: (pixmap)

Returns the file name from which the given pixmap was read, or nil
if the pixmap was created from Lisp data (the lisp data is not retained,
since it usually won't be needed again might be quite large.)

------------------------------
pixmap-depth: (pixmap)

Return the depth of the pixmap.
This is 0 for a bitmap, or a positive integer for a pixmap.

------------------------------
pixmap-file-name: (pixmap)

Returns the file name from which the given pixmap was read, or nil
if the pixmap was created from Lisp data (the lisp data is not retained,
since it usually won't be needed again might be quite large.)

------------------------------
pixmap-height: (pixmap)
Return the height of the pixmap, in pixels.

------------------------------
pixmap-hotspot-x: (pixmap)

Returns the X coordinate of the pixmap's hotspot.
See `set-pixmap-hotspot'.

------------------------------
pixmap-hotspot-y: (pixmap)

Returns the Y coordinate of the pixmap's hotspot.
See `set-pixmap-hotspot'.

------------------------------
pixmap-width: (pixmap)
Return the width of the pixmap, in pixels.

------------------------------
pixmapp: (obj)
Whether the given object is a pixmap.

------------------------------
play-sound: (sound &optional volume)

Play a sound of the provided type.
See the variable sound-alist.

------------------------------
popup-dialog-box: (dbox_desc)

Pop up a dialog box.
A dialog box description is a list.

 - The first element of the list is a string to display in the dialog box.
 - The rest of the elements are descriptions of the dialog box's buttons.
   Each one is a vector of three elements:
   - The first element is the text of the button.
   - The second element is the `callback'.
   - The third element is t or nil, whether this button is selectable.

If the `callback' of a button is a symbol, then it must name a command.
It will be invoked with `call-interactively'.  If it is a list, then it is
evaluated with `eval'.

One (and only one) of the buttons may be `nil'.  This marker means that all
following buttons should be flushright instead of flushleft.

The syntax, more precisely:

   form		:=  <something to pass to `eval'>
   command	:=  <a symbol or string, to pass to `call-interactively'>
   callback 	:=  command | form
   active-p	:=  <t, nil, or a form to evaluate to decide whether this
		    button should be selectable>
   name		:=  <string>
   partition	:=  'nil'
   button	:=  '['  name callback active-p ']'
   dialog	:=  '(' name [ button ]+ [ partition [ button ]+ ] ')'

------------------------------
popup-menu: (menu_desc)

Pop up the given menu.
A menu description is a list of menu items, strings, and submenus.

The first element of a menu must be a string, which is the name of the
menu.  This is the string that will be displayed in the parent menu, if
any.  For toplevel menus, it is ignored.  This string is not displayed
in the menu itself.

A menu item is a vector of three or four elements:

 - the name of the menu item (a string);
 - the `callback' of that item;
 - whether this item is active (selectable);
 - and an optional string to append to the name.

If the `callback' of a menu item is a symbol, then it must name a command.
It will be invoked with `call-interactively'.  If it is a list, then it is
evaluated with `eval'.

The fourth element of a menu item is a convenient way of adding the name
of a command's ``argument'' to the menu, like ``Kill Buffer NAME''.

If an element of a menu is a string, then that string will be presented in
the menu as unselectable text.

If an element of a menu is a string consisting solely of hyphens, then that
item will be presented as a solid horizontal line.

If an element of a menu is a list, it is treated as a submenu.  The name of
that submenu (the first element in the list) will be used as the name of the
item representing this menu on the parent.

The syntax, more precisely:

   form		:=  <something to pass to `eval'>
   command	:=  <a symbol or string, to pass to `call-interactively'>
   callback 	:=  command | form
   active-p	:=  <t, nil, or a form to evaluate to decide whether this
		    item should be selectable>
   text		:=  <string, non selectable>
   name		:=  <string>
   argument	:=  <string>
   menu-item	:=  '['  name callback active-p [ argument ]  ']'
   menu		:=  '(' name [ menu-item | menu | text ]+ ')'

------------------------------
process-event-p: (obj)
True if the argument is a process-output event object.

------------------------------
proclaim-inline: (&rest fns)

Cause the named functions to be open-coded when called from compiled code.
They will only be compiled open-coded when byte-compile-optimize is true.

------------------------------
proclaim-notinline: (&rest fns)
Cause the named functions to no longer be open-coded.

------------------------------
puthash: (key val table)
Hash KEY to VAL in TABLE.

------------------------------
raise-screen: (screen)
Make the window of SCREEN be the uppermost one (fully visible).

------------------------------
round: (arg)
Return the nearest integer to ARG.

------------------------------
lower-screen: (screen)
Make the window of SCREEN be the bottommost one.

------------------------------
read-mouse-position: (screen)
Return a cons (x . y) which represents the position of the mouse.

------------------------------
register-to-window-config: (name)

Restore (make current) the window configuration in register REG (a letter).
Use with a register previously set with C-x 6.

------------------------------
relabel-menu-item: (path new-name)

Change the string of the specified menu item.
PATH is a list of strings which identify the position of the menu item in 
the menu hierarchy.  ("File" "Save") means the menu item called "Save"
under the toplevel "File" menu.  ("Menu" "Foo" "Item") means the 
menu item called "Item" under the "Foo" submenu of "Menu".
NEW-NAME is the string that the menu item will be printed as from now on.

------------------------------
remhash: (key table)
Remove hash value for KEY in TABLE.

------------------------------
remove-directory: (dir)
Delete a directory.  One argument, a file name string.

------------------------------
remove-hook: (hook function)

Remove a function from a hook, if it is present.
First argument HOOK (a symbol) is the name of a hook, second
 argument FUNCTION is the function to remove (compared with `eq').

------------------------------
remprop: (symbol property)
Remove from SYMBOL's plist the property PROP and its value.

------------------------------
screen-iconified-p: (screen)

Return t if SCREEN is iconified.
Not all window managers use icons; some merely unmap the window, so this
function is not the inverse of `screen-visible-p'.  It is possible for a
screen to not be visible and not be iconified either.  However, if the
screen is iconified, it will not be visible.

------------------------------
screen-list: ()
Return a list of all screens.

------------------------------
screen-name: (&optional screen)

Returns the name of SCREEN (defaulting to the selected screen).
This is not the same as the `title' of the screen.

------------------------------
screen-parameters: (&optional screen)

Return the parameters-alist of screen SCREEN.
It is a list of elements of the form (PARM . VALUE), where PARM is a symbol.
The meaningful PARMs depend on the kind of screen.

------------------------------
screen-root-window: (&optional screen)
Returns the root-window of SCREEN.

------------------------------
screen-selected-window: (&optional screen)
Return the selected window of screen SCREEN.

------------------------------
screen-totally-visible-p: (&optional screen)
Return T if screen is not obscured by any other X windows, NIL otherwise

------------------------------
screen-visible-p: (screen)

Return t if SCREEN is now "visible" (actually in use for display).
A screen that is not visible is not updated, and, if it works through a
window system, may not show at all.

------------------------------
screenp: (screen)

Return non-nil if OBJECT is a screen.
Value is t for a termcap screen (a character-only terminal),
`x' for an Emacs screen that is really an X window.

------------------------------
select-screen: (screen)

Select the screen S.
S's selected window becomes the selected window.

------------------------------
selected-screen: ()
Return the screen that is now selected.

------------------------------
set-buffer-dedicated-screen: (buffer screen)

For this BUFFER, set the SCREEN dedicated to it.
SCREEN must be a screen or nil.

------------------------------
set-buffer-modtime: (buf &optional time)

Update BUFFER's recorded modification time from the associated 
file's modtime, if there is an associated file. If not, use the 
current time. In either case, if the optional arg TIME is supplied, use 
that is it is either an integer or a cons of two integers.

------------------------------
set-case-table: (table)

Select a new case table for the current buffer.
A case table is a list (DOWNCASE UPCASE CANONICALIZE EQUIVALENCES)
 where each element is either nil or a string of length 256.
DOWNCASE maps each character to its lower-case equivalent.
UPCASE maps each character to its upper-case equivalent;
 if lower and upper case characters are in 1-1 correspondence,
 you may use nil and the upcase table will be deduced from DOWNCASE.
CANONICALIZE maps each character to a canonical equivalent;
 any two characters that are related by case-conversion have the same
 canonical equivalent character.
EQUIVALENCES is a map that cyclicly permutes each equivalence class
 (of characters with the same canonical equivalent).
Both CANONICALIZE and EQUIVALENCES may be nil, in which case
 both are deduced from DOWNCASE and UPCASE.

------------------------------
set-default-file-modes: (mode)

Set the file permission bits for newly created files.
MASK should be an integer; if a permission's bit in MASK is 1,
subsequently created files will not have that permission enabled.
Only the low 9 bits are used.
This setting is inherited by subprocesses.

------------------------------
set-extent-begin-glyph: (extent begin_glyph &optional layout)

Display a bitmap or string at the beginning of the given extent.
The begin-glyph should either be a pixmap object or the string to
display.  The layout policy defaults to `text'.

------------------------------
set-extent-end-glyph: (extent end_glyph &optional layout)

Display a bitmap or string at the end of the given extent.
The end-glyph should either be a pixmap object or the string to
display.  The layout policy defaults to `text'.

------------------------------
set-extent-endpoints: (extent start end)

Set the endpoints of EXTENT to START, END.
If START and END are null, call detach-extent on EXTENT.
See documentation on `detach-extent' for a discussion of undo recording.

------------------------------
set-extent-face: (extent face)

Make the given EXTENT have the graphic attributes specified by FACE.

------------------------------
set-extent-priority: (extent pri)

Changes the display priority of EXTENT.
When the extent attributes are being merged for display, the priority
is used to determine which extent takes precedence in the event of a
conflict (two extents whose faces both specify font, for example: the
font of the extent with the higher priority will be used.)
Extents are created with priority 0; priorities may be negative.

------------------------------
set-extent-property: (extent property value)

Change a property of an extent.
PROPERTY may be any symbol; the value stored may be accessed with
 the `extent-property' function.
The following symbols have predefined meanings:

 detached	Removes the extent from its buffer; setting this is the same
		as calling `detach-extent'.

 destroyed	Removes the extent from its buffer, and makes it unusable in
		the future; this is the same calling `delete-extent'.

 priority	Change redisplay priority; same as `set-extent-priority'.

 start-open	Whether the set of characters within the extent is treated
		being open on the left, that is, whether the start position
		is an exclusive, rather than inclusive, boundary.  If true,
		then characters inserted exactly at the beginning of the
		extent will remain outside of the extent; otherwise they
		will go into the extent, extending it.

 end-open	Whether the set of characters within the extent is treated
		being open on the right, that is, whether the end position
		is an exclusive, rather than inclusive, boundary.  If true,
		then characters inserted exactly at the end of the extent
		will remain outside of the extent; otherwise they will go
		into the extent, extending it.

 read-only	Text within this extent will be unmodifiable.

 face		The face in which to display the text.  Setting this is the
		same as calling `set-extent-face'.

 highlight	Highlight the extent when the mouse moves over it.

 duplicable	Whether this extent should be copied into strings, so that
		kill, yank, and undo commands will restore or copy it.

 unique		Meaningful only in conjunction with `duplicable'.  When this
		is set, there may be only one instance of this extent
		attached at a time: if it is copied to the kill ring and
		then yanked, the extent is not copied.  If, however, it is
		killed (removed from the buffer) and then yanked, it will
		be re-attached at the new position.

 invisible	Text under this extent is elided (not yet implemented).

 keymap		This keymap is consulted for mouse clicks on this extent, or
		keypresses made while point is within the extent.

 copy-function	This is a hook that is run when a duplicable extent is about
		to be copied from a buffer to a string (or the kill ring.)
		It is called with three arguments, the extent, and the
		buffer-positions within it which are being copied.  If this
		function returns nil, then the extent will not be copied;
		otherwise it will.

 paste-function This is a hook that is run when a duplicable extent is
		about to be copied from a string (or the kill ring) into a
		buffer.  It is called with three arguments, the original
		extent, and the buffer positions which the copied extent
		will occupy.  (This hook is run after the corresponding text
		has already been inserted into the buffer.)  Note that the
		extent argument may be detached when this function is run.
		If this function returns nil, no extent will be inserted.
		Otherwise, there will be an extent covering the range in
		question.

		If the original extent is not attached to a buffer, then it
		will be re-attached at this range.  Otherwise, a copy will
		be made, and that copy attached here.

		The copy-function and paste-function are meaningful only for
		extents with the `duplicable' flag set, and if they are not
		specified, behave as if `t' was the returned value.  When
		these hooks are invoked, the current buffer is the buffer
		which the extent is being copied from/to, respectively.

------------------------------
set-face-background: (face color &optional screen)

Change the background color of the given face.  The color should be a 
string, the name of a color.  If the optional SCREEN argument is provided, 
this face will be changed only in that screen; otherwise it will be changed 
in all screens.

------------------------------
set-face-background-pixmap: (face name &optional screen)

Change the background pixmap of the given face.  The pixmap name should be
a string, the name of a file of pixmap data.  The directories listed in the
x-bitmap-file-path variable will be searched.  The bitmap may also be a list
of the form (width height data) where width and height are the size in pixels,
and data is a string, containing the raw bits of the bitmap.  
If the optional SCREEN argument is provided, this face will be changed only
in that screen; otherwise it will be changed in all screens.

------------------------------
set-face-font: (face font &optional screen)

Change the font of the given face.  The font should be a string, the name
string, the name of the font.  If the optional SCREEN argument is provided, 
this face will be changed only in that screen; otherwise it will be changed
in all screens.

------------------------------
set-face-foreground: (face color &optional screen)

Change the foreground color of the given face.  The color should be a 
string, the name of a color.  If the optional SCREEN argument is provided, 
this face will be changed only in that screen; otherwise it will be changed 
in all screens.

------------------------------
set-face-underline-p: (face underline-p &optional screen)

Change whether the given face is underlined.  
If the optional SCREEN argument is provided, this face will be changed only
in that screen; otherwise it will be changed in all screens.

------------------------------
set-keymap-parent: (keymap parent)

Sets the `parent' keymap of the given keymap.
The parent of a keymap is searched for keybindings when a key sequence
isn't bound in this one.  The (current-global-map) is the default parent
of all keymaps.

------------------------------
set-keymap-prompt: (keymap new_prompt)

Sets the `prompt' of KEYMAP to string NEW-PROMPT, or `nil'
if no prompt is desired.  The prompt is shown in the echo-area
when reading a key-sequence to be looked-up in this keymap.

------------------------------
set-mouse-position: (screen x y)
Move the mouse pointer to the center of character cell (X,Y) in SCREEN.

------------------------------
set-pixmap-data: (pixmap data)

Set the pixmap's data.  The data must be in the form of a list;
currently only the format (width height data) is supported.  See
`make-pixmap'.

------------------------------
set-pixmap-hotspot: (pixmap x y)

Set the pixmap's hotspot.
This is a point relative to the origin of the pixmap.  When a pixmap is
used as a cursor or similar pointing indicator, the hotspot is the point
on the pixmap that sits over the location that the pointer points to.
This is, for example, the tip of the arrow or the center of the crosshairs.

------------------------------
set-pixmap-mask: (pixmap data)

Set the pixmap's mask according to the specified data.
The data must be in XY format and must be at least (width * height)
bits long, one bit per pixel in the pixmap.  When the pixmap is used
as a cursor or similar pointing indicator, the mask indicates which
pixels in the pixmap's rectangular outline are to be taken from the
pixmap and which from the background.

------------------------------
set-screen-position: (screen xoffset yoffset)
Sets position of SCREEN in pixels to XOFFSET by YOFFSET.
If XOFFSET or YOFFSET are negative, they are interpreted relative to
the leftmost or bottommost position SCREEN could occupy without going
off the screen.

------------------------------
set-screen-size: (screen cols rows &optional pretend)

Sets size of SCREEN to COLS by ROWS.
Optional fourth arg non-nil means that redisplay should use COLS by ROWS
but that the idea of the actual size of the screen should not be changed.

------------------------------
set-standard-case-table: (table)

Select a new standard case table for new buffers.
See `set-case-table' for more info on case tables.

------------------------------
set-visited-file-modtime: (&optional time-list)

Update buffer's recorded modification time from the visited file's time.
Useful if the buffer was not read from the file normally
or if the file itself has been changed for some known benign reason.
An argument specifies the modification time value to use
(instead of that of the visited file), in the form of a list
(HIGH . LOW) or (HIGH LOW).

------------------------------
set-window-buffer-dedicated: (window arg)

Make WINDOW display BUFFER and be dedicated to that buffer.
Then Emacs will not automatically change which buffer appears in WINDOW.
If BUFFER is nil, make WINDOW not be dedicated (but don't change which
buffer appears in it currently).

------------------------------
sin: (arg)
Return the sine of ARG.

------------------------------
sinh: (arg)
Return the hyperbolic sine of ARG.

------------------------------
standard-case-table: ()

Return the standard case table.
This is the one used for new buffers.

------------------------------
sqrt: (arg)
Return the square root of ARG.

------------------------------
start-itimer: (name function value &optional restart)

Start an itimer.
Args are NAME, FUNCTION, VALUE &optional RESTART.
NAME is an identifier for the itimer.  It must be a string.  If an itimer
  already exists with this name, NAME will be modified slightly to until
  it is unique.
FUNCTION should be a function (or symbol naming one) of no arguments.  It
  will be called each time the itimer expires.  The function can access
  itimer that invoked it through the variable `current-itimer'.
VALUE is the number of seconds until this itimer expires.
Optional fourth arg RESTART non-nil means that this itimer should be
  restarted automatically after its function is called.  Normally an itimer
  is deleted at expiration after its function has returned. 
  If non-nil RESTART should be a number indicating the value at which the
  itimer should be set at restart time.
Returns the newly created itimer.

------------------------------
switch-to-buffer-new-screen: (buffer)

Just like switch-to-buffer, but creates a new screen for it first.

------------------------------
switch-to-other-buffer: (arg)

Switch to the previous buffer.  With a numeric arg, n, switch to the nth
most recent buffer.  With an arg of 0, buries the current buffer at the
bottom of the buffer stack.

------------------------------
tan: (arg)
Return the tangent of ARG.

------------------------------
tanh: (arg)
Return the hyperbolic tangent of ARG.

------------------------------
truename: (name &optional defalt)

Returns the canonical name of the given FILE.
Second arg DEFAULT is directory to start with if FILE is relative
 (does not start with slash); if DEFAULT is nil or missing,
 the current buffer's value of default-directory is used.
No component of the resulting pathname will be a symbolic link, as
 in the realpath() function.
If the file does not exist, or is otherwise unable to be resolved,
 nil is returned.

------------------------------
truncate: (arg)
Truncate a floating point number to an integer.
Rounds the value toward zero.

------------------------------
timeout-event-p: (obj)
True if the argument is a timeout event object.

------------------------------
try-face-font: (face font &optional screen)
Like set-face-font, but returns nil on failure instead of an error.

------------------------------
user-login-name: ()

Return the name under which the user logged in, as a string.
This is based on the effective uid, not the real uid.
Also, if the environment variable USER or LOGNAME is set,
that determines the value of this function.

------------------------------
user-original-login-name: ()

Return user's login name from original login.
This tries to remain unaffected by `su', by looking in environment variables.

------------------------------
visible-screen-list: ()
Return a list of all screens now "visible" (being updated).

------------------------------
walk-windows: (proc &optional minibuf all-screens)

Cycle through all visible windows, calling PROC for each one.
PROC is called with a window as argument.
Optional second arg MINIBUF t means count the minibuffer window
even if not active.  If MINIBUF is neither t nor nil it means
not to count the minibuffer even if it is active.

Optional third arg ALL-SCREENS t means include all windows in all screens;
otherwise cycle within the selected screen.

------------------------------
window-config-to-register: (name)

Save the current window configuration in register REG (a letter).
It can be later retrieved using M-x register-to-window-config.

------------------------------
window-dedicated-p: (window)

Return WINDOW's dedicated object, usually t or nil.
See also `set-window-buffer-dedicated'.

------------------------------
window-end: (&optional window)
Return position at which display currently ends in WINDOW.

------------------------------
window-minibuffer-p: (window)
Returns non-nil if WINDOW is a minibuffer window.

------------------------------
window-screen: (window)
Return the screen that window WINDOW is on.

------------------------------
x-color-display-p: (&optional screen)
Returns t if the X display of the given screen supports color.

------------------------------
x-copy-primary-selection: ()
Copy the selection to the Clipboard and the kill ring.

------------------------------
x-create-screen: (parms)

Make a new X window, which is considered a "screen" in Emacs terms.
Return an Emacs screen object representing the X window.
ALIST is an alist of screen parameters.
The value of `x-screen-defaults' is an additional alist
of default parameters which apply when not overridden by ALIST.

------------------------------
x-debug-mode: (arg)

With a true arg, put the connection to the X server in synchronous
mode; this is slower.  False turns it off.
Do not simply call XSynchronize() from gdb; that won't work.

------------------------------
x-delete-primary-selection: ()

Delete the selection without copying it to the Clipboard or the kill ring.

------------------------------
x-disown-selection: (&optional secondary-p)

Assuming we own the selection, disown it.  With an argument, discard the
secondary selection instead of the primary selection.

------------------------------
x-display-color-cells: (&optional screen)
Returns the number of color cells of the display `screen' is on.

------------------------------
x-display-pixel-width: (&optional screen)
Returns the width in pixels of the display `screen' is on.

------------------------------
x-display-pixel-height: (&optional screen)
Returns the height in pixels of the display `screen' is on.

------------------------------
x-display-planes: (&optional screen)
Returns the number of bitplanes of the display `screen' is on.

------------------------------
x-display-visual-class: (&optional screen)

Returns the visual class of the display `screen' is on.
The returned value will be one of the symbols StaticGray, GrayScale,
StaticColor, PseudoColor, TrueColor, or DirectColor.

------------------------------
x-font-properties (font)
Returns the properties (an alist) of the given font.

------------------------------
x-get-clipboard: ()
Return text pasted to the clipboard.

------------------------------
x-get-cutbuffer: (&optional which-one)

Returns the value of one of the 8 X server cut-buffers.  Optional arg
WHICH-ONE should be a number from 0 to 7, defaulting to 0.
Cut buffers are considered obsolete; you should use selections instead.

------------------------------
x-get-resource: (name class type &optional screen)

Retrieve an X resource from the resource manager.
The first arg is the name of the resource to retrieve, such as "font".
The second arg is the class of the resource to retrieve, like "Font".
The third arg should be one of the symbols string, integer, or boolean,
specifying the type of object that the database is searched for.
The fourth arg is the screen to search for the resources on, defaulting
to the selected screen.

The call
    (x-get-resource "font" "Font" 'string)

is an interface to the C call

    XrmGetResource (db, "emacs.this_screen_name.font",
			"Emacs.EmacsScreen.Font",
			"String");

Therefore if you want to retrieve a deeper resource, for example,
"Emacs.foo.foreground", you need to specify the same number of links
in the class path:
    (x-get-resource "foo.foreground" "Thing.Foreground" 'string)

which is equivalent to 

    XrmGetResource (db, "emacs.screen_name.foo.foreground",
			"Emacs.EmacsScreen.Thing.Foreground",
			"String");

The returned value of this function is nil if the queried resource is not
found.  If the third arg is `string', a string is returned, and if it is
`integer', an integer is returned.  If the third arg is `boolean', then the
returned value is the list (t) for true, (nil) for false, and is nil to
mean ``unspecified.''

------------------------------
x-get-secondary-selection: ()
Return text selected from some X window.

------------------------------
x-get-selection: ()
Return text selected from some X window.

------------------------------
x-get-selection-internal: (selection_symbol target_type)

Return text selected from some X window.
SELECTION is a symbol, typically PRIMARY, SECONDARY, or CLIPBOARD.
TYPE is the type of data desired, typically STRING.

------------------------------
x-grab-pointer: (&optional cursor ignore-keyboard)

Grab the pointer and restrict it to its current window.
If optional CURSOR argument is non-nil, change the pointer shape to that
 until `x-ungrab-pointer' is called (it should be an object returned by the
 `make-cursor' function.)
If the second optional argument MOUSE-ONLY is non-nil, ignore all keyboard
 events during the grab.
Returns t if the grab is successful, nil otherwise.

------------------------------
x-insert-selection: (&optional check-cutbuffer-p move-point-event)
Insert the current selection into buffer at point.

------------------------------
x-kill-primary-selection: ()

Copy the selection to the Clipboard and the kill ring, then delete it.

------------------------------
x-list-fonts: (pattern &optional screen)
Returns a list of font names matching the given pattern.

------------------------------
x-mouse-kill: (event)

Kill the text between the point and mouse and copy it to the clipboard and
to the cut buffer

------------------------------
x-new-screen: (&optional screen-name)
Creates a new Emacs screen (that is, a new X window.)

------------------------------
x-own-clipboard: (string)
Paste the given string to the X Clipboard.

------------------------------
x-own-secondary-selection: (selection &optional type)

Make a secondary X Selection of the given argument.  The argument may be a 
string or a cons of two markers (in which case the selection is considered to
be the text between those markers.)

------------------------------
x-own-selection: (selection &optional type)

Make a primary X Selection of the given argument.  
The argument may be a string, a cons of two markers, or an extent.  
In the latter cases the selection is considered to be the text 
between the markers, or the between extents endpoints.

------------------------------
x-server-vendor: (&optional screen)
Returns the vendor ID string of the X server `screen' is on.

------------------------------
x-server-version: (&optional screen)

Returns the version numbers of the X server `screen' is on.
The returned value is a list of three integers: the major and minor
version numbers of the X Protocol in use, and the vendor-specific release
number.  See also `x-server-vendor'.

------------------------------
x-selection-exists-p: (&optional selection)

Whether there is an owner for the given X Selection.
The arg should be the name of the selection in question, typically one of
the symbols PRIMARY, SECONDARY, or CLIPBOARD.  (For convenience, the symbol
nil is the same as PRIMARY, and t is the same as SECONDARY.)

------------------------------
x-selection-owner-p: (&optional selection)

Whether the current Emacs process owns the given X Selection.
The arg should be the name of the selection in question, typically one of
the symbols PRIMARY, SECONDARY, or CLIPBOARD.  (For convenience, the symbol
nil is the same as PRIMARY, and t is the same as SECONDARY.)

------------------------------
x-set-point-and-insert-selection: (event)
Sets point where clicked and insert the primary selection or the cut buffer.

------------------------------
x-set-screen-icon-pixmap: (screen pixmap &optional mask)

Set the icon of the given screen to the given pixmap,
which should be an object returned by `make-pixmap', or nil.
If the given pixmap has a mask, that will be used as the icon mask;
 however, not all window managers support this.
The window manager is also not required to support color pixmaps,
 only bitmaps (one plane deep.)
If the second argument is a pixmap without a mask, then the optional
 third argument may be the pixmap to use as the mask (it must be one
 plane deep.)

------------------------------
x-set-screen-pointer: (screen cursor)

Set the mouse cursor of SCREEN to the given cursor,
which should be an object returned by `make-cursor'.

------------------------------
x-store-cutbuffer: (string)

Store the given string into the X server's primary cut buffer.
The previous value of the primary cut buffer is rotated to the secondary
cut buffer, and the second to the third, and so on (there are 8 buffers.)
Cut buffers are considered obsolete; you should use selections instead.

------------------------------
x-ungrab-pointer: ()
Release a pointer grab made with `x-grab-pointer.'

------------------------------
x-yank-clipboard-selection: ()
Insert the current Clipboard selection at point.

------------------------------
y-or-n-p-with-timeout: (timeout prompt &optional default-value)

Just like y-or-n-p, but will time out after TIMEOUT seconds
if the user has not yes answered, returning DEFAULT-VALUE.

------------------------------
yes-or-no-p-with-timeout: (timeout prompt &optional default-value)

Just like yes-or-no-p, but will time out after TIMEOUT seconds
if the user has not yes answered, returning DEFAULT-VALUE.

------------------------------
zmacs-activate-region: ()

Make the region between `point' and `mark' be in the active (highlighted)
state, if `zmacs-regions' is true.  Only a very small number of commands
should ever do this.

------------------------------
zmacs-deactivate-region: ()

Make the region between `point' and `mark' no longer be in the active
(highlighted) state, if `zmacs-regions' is true.  You shouldn't need to call
this; the command loop calls it when appropriate.
Returns t if the region had been active, nil otherwise.


New Variables:
==============

------------------------------
activate-menubar-hook

Function or functions called before a menubar menu is pulled down.
These functions are called with no arguments, and should interrogate and
modify the value of `current-menubar' as desired.

The functions on this hook are invoked after the mouse goes down, but before
the menu is mapped, and may be used to activate, deactivate, add, or delete
items from the menus.

These functions may return the symbol `t' to assert that they have made
no changes to the menubar.  If any other value is returned, the menubar is
recomputed.  If `t' is returned but the menubar has been changed, then the
changes may not show up right away.  Returning `nil' when the menubar has
not changed is not so bad; more computation will be done, but redisplay of
the menubar will still be performed optimally.

------------------------------
after-change-function

Function to call after each text change.
Three arguments are passed to the function: the positions of
the beginning and end of the range of changed text,
and the length of the pre-change text replaced by that range.
(For an insertion, the pre-change length is zero;
for a deletion, that length is the number of characters deleted,
and the post-change beginning and end are at the same place.)

While executing the `after-change-function', changes to buffers do not
cause calls to any `before-change-function' or `after-change-function'.

------------------------------
after-init-hook

Functions to call after loading the init file (`~/.emacs').
The call is not protected by a condition-case, so you can set `debug-on-error'
in `.emacs', and put all the actual code on `after-init-hook'.

------------------------------
after-load-alist

An alist of expressions to be evalled when particular files are loaded.
Each element looks like (FILENAME FORMS...).
When `load' is run and the file-name argument is FILENAME,
the FORMS in the corresponding element are executed at the end of loading.

FILENAME must match exactly!  Normally FILENAME is the name of a library,
with no directory specified, since that is how `load' is normally called.
An error in FORMS does not undo the load,
but does prevent execution of the rest of the FORMS.

------------------------------
after-save-hook

List of functions to be called after writing out a buffer to a file.
These hooks are considered to pertain to the visited file.
So this list is cleared if you change the visited file name.

------------------------------
allow-deletion-of-last-visible-screen

*If nil, the last visible screen may not be deleted by `delete-window'
You can never delete the last screen, but setting this to t will allow you
to delete the last non-iconified screen.

------------------------------
auto-fill-inhibit-regexp
*Regexp to match lines which should not be auto-filled.

------------------------------
auto-gc-threshold

*GC when this many bytes have been consed since the last GC, 
and the user has been idle for `auto-save-timeout' seconds.

------------------------------
auto-lower-screen

*If true, screens will be lowered to the bottom when no longer selected.
Under X, most ICCCM-compliant window managers will have an option to do this
for you, but this variable is provided in case you're using a broken WM.

------------------------------
auto-raise-screen

*If true, screens will be raised to the top when selected.
Under X, most ICCCM-compliant window managers will have an option to do this
for you, but this variable is provided in case you're using a broken WM.

------------------------------
auto-save-timeout

*Number of seconds idle time before auto-save.
Zero or nil means disable auto-saving due to idleness.

The actual amount of idle time between auto-saves is logarithmically related
to the size of the current buffer.  This variable is the number of seconds
after which an auto-save will happen when the current buffer is 50k or less;
the timeout will be 2 1/4 times this in a 200k buffer, 3 3/4 times this in a
1000k buffer, and 4 1/2 times this in a 2000k buffer.

See also the variable `auto-save-interval', which controls auto-saving based
on the number of characters typed.

------------------------------
baud-rate

The output baud rate of the terminal.
On most systems, changing this value will affect the amount of padding
and the other strategic decisions made during redisplay.

------------------------------
before-change-function

Function to call before each text change.
Two arguments are passed to the function: the positions of
the beginning and end of the range of old text to be changed.
(For an insertion, the beginning and end are at the same place.)
No information is given about the length of the text after the change.
position of the change

While executing the `before-change-function', changes to buffers do not
cause calls to any `before-change-function' or `after-change-function'.

------------------------------
before-init-hook's value is nil

Functions to call after handling urgent options but before loading init file.
The window system interface uses this to open screens to display messages while
Emacs loads the user's initialization file.

------------------------------
buffer-file-number's value is nil

The device number and file number of the file visited in the current buffer.
The value is a list of the form (FILENUM DEVNUM).
This pair of numbers uniquely identifies the file.
If the buffer is visiting a new file, the value is nil.

------------------------------
buffer-file-truename

The real name of the file visited in the current buffer, 
or nil if not visiting a file.  This is the result of passing 
buffer-file-name to the `truename' function.  Every buffer has 
its own value of this variable.  This variable is automatically 
maintained by the functions that change the file name associated 
with a buffer.

------------------------------
buffers-menu-max-size

*Maximum number of entries which may appear on the "Buffers" menu.
If this is 10, then only the ten most-recently-selected buffers will be
shown.  If this is nil, then all buffers will be shown.  Setting this to
a large number or nil will slow down menu responsiveness.

------------------------------
buffers-menu-switch-to-buffer-function

*The function to call to select a buffer from the buffers menu.
`switch-to-buffer' is a good choice, as is `pop-to-buffer'.

------------------------------
complex-buffers-menu-p

*If true, the buffers menu will contain several commands, as submenus
of each buffer line.  If this is false, then there will be only one command:
select that buffer.

------------------------------
create-screen-hook

Function or functions of one argument, called with each newly-created screen.

------------------------------
current-menubar

The current menubar.  This may be buffer-local.

When the menubar is changed, the function `set-menubar-dirty-flag' has to
be called for the menubar to be updated on the screen.  See `set-menubar'
and `set-buffer-menubar'.

A menubar is a list of menus and menu-items.
A menu is a list of menu items, strings, and submenus.

The first element of a menu must be a string, which is the name of the
menu.  This is the string that will be displayed in the menubar, or in
the parent menu.  This string is not displayed in the menu itself.

A menu item is a vector of three or four elements:

 - the name of the menu item (a string);
 - the `callback' of that item;
 - whether this item is active (selectable);
 - and an optional string to append to the name.

If the `callback' of a menu item is a symbol, then it must name a command.
It will be invoked with `call-interactively'.  If it is a list, then it is
evaluated with `eval'.

The fourth element of a menu item is a convenient way of adding the name
of a command's ``argument'' to the menu, like ``Kill Buffer NAME''.

If an element of a menu (or menubar) is a string, then that string will be
presented in the menu (or menubar) as unselectable text.

If an element of a menu is a string consisting solely of hyphens, then that
item will be presented as a solid horizontal line.

If an element of a menu is a list, it is treated as a submenu.  The name of
that submenu (the first element in the list) will be used as the name of
the item representing this menu on the parent.

If an element of a menubar is `nil', then it is used to represent the
division between the set of menubar-items which are flushleft and those
which are flushright.  (Note: this isn't completely implemented yet.)

After the menubar is clicked upon, but before any menus are popped up,
the functions on the `activate-menubar-hook' are invoked to make changes
to the menus and menubar.  This is intended to implement lazy alteration
of the sensitivity of menu items.

The syntax, more precisely:

   form		:=  <something to pass to `eval'>
   command	:=  <a symbol or string, to pass to `call-interactively'>
   callback 	:=  command | form
   active-p	:=  <t, nil, or a form to evaluate to decide whether this
		    item should be selectable>
   text		:=  <string, non selectable>
   name		:=  <string>
   argument	:=  <string>
   menu-item	:=  '['  name callback active-p [ argument ]  ']'
   menu		:=  '(' name [ menu-item | menu | text ]+ ')'
   partition	:=  'nil'
   menubar	:=  '(' [ menu-item | menu | text ]* [ partition ]
		        [ menu-item | menu | text ]*
		     ')'

------------------------------
current-mouse-event

The mouse-button event which invoked this command, or nil.
This is what `(interactive "e")' returns.

------------------------------
default-directory-alist

Alist of major modes and their opinion on default-directory, as a
lisp expression to evaluate.  A resulting value of nil is ignored in
favor of default-directory.

------------------------------
default-screen-name

The default name to assign to newly-created screens.
This can be overridden by arguments to `x-create-screen'.
This must be a string.

------------------------------
delete-screen-hook
Function or functions of one argument, called with each to-be-deleted screen.

------------------------------
describe-function-show-arglist

*If true, then describe-function will show its arglist if the function is
not an autoload.

------------------------------
directory-abbrev-alist

*Alist of abbreviations for file directories.
A list of elements of the form (FROM . TO), each meaning to replace
FROM with TO when it appears in a directory name.
This replacement is done when setting up the default directory of a
newly visited file.  *Every* FROM string should start with \\` or ^.

Use this feature when you have directories which you normally refer to
via absolute symbolic links.  Make TO the name of the link, and FROM
the name it is linked to.

------------------------------
display-buffer-function

If non-nil, function to call to handle `display-buffer'.
It will receive three args: the same as those to `display-buffer'.

------------------------------
enable-local-variables

*Control use of local-variables lists in files you visit.
The value can be t, nil or something else.
A value of t means local-variables lists are obeyed;
nil means they are ignored; anything else means query.

The command M-x normal-mode always obeys local-variables lists
and ignores this variable.

Note: this variable has replaced `inhibit-local-variables'.

------------------------------
execution-path
Pathname of executable emacs program now running.

------------------------------
find-file-compare-truenames

If this is true, then the find-file command will check the truenames
of all visited files when deciding whether a given file is already in
a buffer, instead of just the buffer-file-name.  This means that if you
attempt to visit another file which is a symbolic-link to a file which is
already in a buffer, the existing buffer will be found instead of a newly-
created one.  This works if any component of the pathname (including a non-
terminal component) is a symbolic link as well, but doesn't work with hard
links (nothing does.)

See also the variable find-file-use-truenames.

------------------------------
find-file-use-truenames

If this is true, then a buffer's visited file-name will always be
chased back to the real file; it will never be a symbolic link, and there
will never be a symbolic link anywhere in its directory path.
That is, the buffer-file-name and buffer-file-truename will be equal.
This doesn't work with hard links.

See also the variable find-file-compare-truenames.

------------------------------
first-change-hook

A list of functions to call before changing a buffer which is unmodified.
The functions are run using the `run-hooks' function.

------------------------------
float-output-format

The format descriptor string that lisp uses to print floats.
This is a %-spec like those accepted by `printf' in C,
but with some restrictions.  It must start with the two characters `%.'.
After that comes an integer precision specification,
and then a letter which controls the format.
The letters allowed are `e', `f' and `g'.
Use `e' for exponential notation "DIG.DIGITSeEXPT"
Use `f' for decimal point notation "DIGITS.DIGITS".
Use `g' to choose the shorter of those two formats for the number at hand.
The precision in any of these cases is the number of digits following
the decimal point.  With `f', a precision of 0 means to omit the
decimal point.  0 is not allowed with `f' or `g'.

A value of nil means to use `%.16g'.

Regardless of the value of `float-output-format', a floating point number
will never be printed in such a way that it is ambiguous with an integer;
that is, a floating-point number will always be printed with a decimal
point and/or an exponent, even if the digits following the decimal point
are all zero.  This is to preserve read-equivalence.

------------------------------
get-screen-for-buffer-default-screen-name
The default screen to select; see doc of `get-screen-for-buffer'.

------------------------------
inhibit-read-only

*Non-nil means disregard read-only status of buffers or characters.
If the value is t, disregard `buffer-read-only' and all `read-only'
text properties.  If the value is a list, disregard `buffer-read-only'
and disregard a `read-only' text property if the property value
is a member of the list.

------------------------------
init-file-user

Identity of user whose `.emacs' file is or was read.
The value may be the null string or a string containing a user's name.
If the value is a null string, it means that the init file was taken from
the user that originally logged in.

In all cases, `(concat "~" init-file-user "/")' evaluates to the
directory name of the directory where the `.emacs' file was looked for.

------------------------------
internal-doc-file-name
Name of file containing documentation strings of built-in symbols.

------------------------------
interrupt-char

Character which interrupts Emacs.
Do not setq this variable: use the function `set-interrupt-character' instead.
Depending on the system you are on, this may need to do magic like changing
interrupt handlers.

------------------------------
invocation-name

Name of file used to invoke editing session.
This is the same as `(file-name-nondirectory execution-path)'.

------------------------------
keymap-tick
Incremented for each change to any keymap.

------------------------------
kill-emacs-hook

A list of functions (of no args) for `kill-emacs' to call before emacs is
actually killed.

------------------------------
kill-hooks

Functions run when something is added to the Emacs kill ring.
These functions are called with one argument, the string most recently
cut or copied.  You can use this to, for example, make the most recent 
kill become the X Clipboard selection.

------------------------------
last-command-event

Last keyboard or mouse button event that was part of a command.  This
variable is off limits: you may not set its value or modify the event that
is its value, as it is destructively modified by `read-key-sequence'.  If
you want to keep a pointer to this value, you must use `copy-event'.

------------------------------
last-input-event

Last keyboard or mouse button event recieved.  This variable is off
limits: you may not set its value or modify the event that is its value, as
it is destructively modified by `next-event'.  If you want to keep a pointer
to this value, you must use `copy-event'.

------------------------------
last-input-time

The time (in seconds since Jan 1, 1970) of the last-command-event,
represented as a cons of two 16-bit integers.  This is destructively
modified, so copy it if you want to keep it.

------------------------------
list-buffers-identification

String used to identify this buffer, or a function of one argument
to generate such a string.  This variable is always buffer-local.

------------------------------
local-write-file-hooks

Just like `write-file-hooks', except intended for per-buffer use.
The functions in this list are called before the ones in
`write-file-hooks'.

------------------------------
mail-abbrev-mailrc-file
Name of file with mail aliases.   If nil, ~/.mailrc is used.

------------------------------
map-screen-hook
Function or functions to call when screen is mapped.
One arg, the screen.

------------------------------
menubar-show-keybindings

If true, the menubar will display keyboard equivalents.
If false, only the command names will be displayed.

------------------------------
menu-no-selection-hook

Function or functions to call when a menu or dialog box is dismissed
without a selecting having been made.

------------------------------
minibuffer-confirm-incomplete

If true, then in contexts where completing-read allows answers which
are not valid completions, an extra RET must be typed to confirm the
response.  This is helpful for catching typos, etc.

------------------------------
minibuffer-max-depth

*Global maximum number of minibuffers allowed;
compare to enable-recursive-minibuffers, which is only consulted when the
minibuffer is reinvoked while it is the selected window.

------------------------------
mode-line-map

Keymap consulted for mouse-clicks on the modeline of a window.
This variable may be buffer-local; its value will be looked up in
the buffer of the window whose modeline was clicked upon.

------------------------------
mode-motion-hook

Function or functions which are called whenever the mouse moves.
You should normally use this rather than `mouse-motion-handler', which 
does some additional window-system-dependent things.  This hook is local
to every buffer, and should normally be set up by major-modes which want
to use special highlighting.  Every time the mouse moves over a window,
the mode-motion-hook of the buffer of that window is run.

------------------------------
mouse-enter-screen-hook

Function or functions to call when mouse enters a screen.  One arg, the screen.
Be careful not to make assumptions about the window manger's focus model.
In most cases, the `deselect-screen-hook' is more appropriate.

------------------------------
mouse-leave-screen-hook

Function or functions to call when mouse leaves screen.  One arg, the screen.
Be careful not to make assumptions about the window manger's focus model.
In most cases, the `select-screen-hook' is more appropriate.

------------------------------
mouse-motion-handler
Handler for motion events.  One arg, the event.
For most applications, you should use `mode-motion-hook' instead of this.

------------------------------
mouse-track-rectangle-p

*If true, then dragging out a region with the mouse selects rectangles
instead of simple start/end regions.

------------------------------
next-line-add-newlines

*If non-nil, when C-n is invoked on the last line of a buffer,
a newline character is inserted to create a new line.
If nil, C-n signals an `end-of-buffer' in that situation.

------------------------------
popup-menu-titles
If true, popup menus will have title bars at the top.

------------------------------
post-command-hook

Function or functions to run after every command.
This may examine the `this-command' variable to find out what command
was just executed.

------------------------------
post-gc-hook

Function or functions to be run just after each garbage collection.
Interrupts, garbage collection, and errors are inhibited while this hook
runs, so be extremely careful in what you add here.  In particular, avoid
consing, and do not interact with the user.

------------------------------
pre-abbrev-expand-hook

Function or functions to be called before abbrev expansion is done.
This is the first thing that `expand-abbrev' does, and so this may change
the current abbrev table before abbrev lookup happens.

------------------------------
pre-display-buffer-function

If non-nil, function that will be called from `display-buffer'
as the first action.  It will receive three args: the same as those
to `display-buffer'.
This function may be used to select an appropriate screen for the buffer,
for example.  See also the variable `display-buffer-function', which may
be used to completely replace the `display-buffer' function.

------------------------------
pre-command-hook

Function or functions to run before every command.
This may examine the `this-command' variable to find out what command
is about to be run, or may change it to cause a different command to run.
Function on this hook must be careful to avoid signalling errors!

------------------------------
pre-gc-hook

Function or functions to be run just before each garbage collection.
Interrupts, garbage collection, and errors are inhibited while this hook
runs, so be extremely careful in what you add here.  In particular, avoid
consing, and do not interact with the user.

------------------------------
print-level

Maximum depth of list nesting to print before abbreviating.
A value of nil means no limit.

------------------------------
print-readably

If non-nil, then all objects will be printed in a readable form.
If an object has no readable representation, then an error is signalled.
When print-readably is true, compiled-function objects will be written in
 #[...] form instead of in #<byte-code [...]> form, and two-element lists
 of the form (quote object) will be written as the equivalent 'object.
Do not SET this variable; bind it instead.

------------------------------
print-gensym

If non-nil, then uninterned symbols will be printed specially.
Uninterned symbols are those which are not present in `obarray', that is,
those which were made with `make-symbol' or by calling `intern' with a
second argument.

When print-gensym is true, such symbols will be preceeded by "#:", which
causes the reader to create a new symbol instead of interning and returning
an existing one.  Beware: the #: syntax creates a new symbol each time it is
seen, so if you print an object which contains two pointers to the same
uninterned symbol, `read' will not duplicate that structure.

Also, since emacs has no real notion of packages, there is no way for the
printer to distinguish between symbols interned in no obarray, and symbols
interned in an alternate obarray.

------------------------------
revert-buffer-insert-file-contents-function

Function to use to insert contents when reverting this buffer.
Gets two args, first the nominal file name to use,
and second, t if reading the auto-save file.

------------------------------
screen-default-alist

Alist of default values for screen creation, other than the first one.
These may be set in your init file, like this:
  (setq screen-default-alist '((width . 80) (height . 55)))
For values specific to the first Emacs screen, you must use X resources.

------------------------------
screen-icon-title-format

Controls the title of the icon corresponding to the selected screen.
See also the variable `screen-title-format'

------------------------------
screen-title-format

Controls the title of the X window corresponding to the selected screen.
This is the same format as `mode-line-format'.

------------------------------
scrollbar-width

The width (in pixels) of the scrollbars.

------------------------------
search-caps-disable-folding

*If non-nil, upper case chars disable case fold searching.
This does not apply to "yanked" strings.  Default t.

------------------------------
selection-converter-alist

An alist associating selection-types (such as STRING and TIMESTAMP) with
functions.  These functions will be called with three args: the name of the
selection (typically PRIMARY, SECONDARY, or CLIPBOARD); a desired type to
which the selection should be converted; and the local selection value
(whatever had been passed to `x-own-selection').  These functions should
return the value to send to the X server (typically a string).  A return
value of nil means that the conversion could not be done.  A return value
which is the symbol NULL means that a side-effect was executed, and there
is no meaningful return value.

------------------------------
shared-lisp-mode-map
Keymap for commands shared by all sorts of Lisp modes.

------------------------------
sound-alist

An alist associating symbols with strings of audio-data.
When `beep' or `ding' is called with one of the symbols, the associated
sound data will be played instead of the standard beep.  This only works
if you are running emacs on the console of a Sun SparcStation, SGI machine,
or HP9000s700.

Elements of this list should be of one of the following forms:

   ( symbol . string-or-symbol )
   ( symbol integer string-or-symbol )

If the `string-or-symbol' is a string, then it should contain raw sound data,
the contents of a `.au' file.  If it is a symbol, then that means that this
element is an alias for some other element, and the sound-player will look
for that next.  If the integer is provided, it is the volume at which the
sound should be played, from 0 to 100.  

If an element of this alist begins with the symbol `default', then that sound
will be used when no other sound is appropriate.

The symbol `t' in place of a sound-string means to use the default X beep.
In this way, you can define beep-types to have different volumes even when
not running on the console.

You should probably add things to this list by calling the function
load-sound-file.

The following beep-types are used by emacs itself:

    auto-save-error	when an auto-save does not succeed
    command-error	when the emacs command loop catches an error
    undefined-key	when you type a key that is undefined
    undefined-click	when you use an undefined mouse-click combination
    no-completion	during completing-read
    y-or-n-p		when you type something other than 'y' or 'n'
    yes-or-no-p  	when you type something other than 'yes' or 'no'

Other lisp packages may use other beep types, but these are the ones that
the C kernel of Emacs uses.

------------------------------
split-window-keep-point

*If non-nil, split windows keeps the original point in both children.
This is often more convenient for editing.
If nil, adjust point in each of the two windows to minimize redisplay.
This is convenient on slow terminals, but point can move strangely.

------------------------------
tag-table-alist

*A list which determines which tags files should be active for a 
given buffer.  This is not really an association list, in that all 
elements are checked.  The CAR of each element of this list is a 
pattern against which the buffer's file name is compared; if it 
matches, then the CDR of the list should be the name of the tags
table to use.  If more than one element of this list matches the
buffer's file name, then all of the associated tags tables will be
used.  Earlier ones will be searched first.

If the CAR of elements of this list are strings, then they are treated
as regular-expressions against which the file is compared (like the
auto-mode-alist).  If they are not strings, then they are evaluated.
If they evaluate to non-nil, then the current buffer is considered to
match.

If the CDR of the elements of this list are strings, then they are
assumed to name a TAGS file.  If they name a directory, then the string
"TAGS" is appended to them to get the file name.  If they are not 
strings, then they are evaluated, and must return an appropriate string.

For example:
  (setq tag-table-alist
	'(("/usr/src/public/perl/" . "/usr/src/public/perl/perl-3.0/")
	 ("\\.el$" . "/usr/local/emacs/src/")
	 ("/jbw/gnu/" . "/usr15/degree/stud/jbw/gnu/")
	 ("" . "/usr/local/emacs/src/")
	 ))

This means that anything in the /usr/src/public/perl/ directory should use
the TAGS file /usr/src/public/perl/perl-3.0/TAGS; and file ending in .el should
use the TAGS file /usr/local/emacs/src/TAGS; and anything in or below the
directory /jbw/gnu/ should use the TAGS file /usr15/degree/stud/jbw/gnu/TAGS.
A file called something like "/usr/jbw/foo.el" would use both the TAGS files
/usr/local/emacs/src/TAGS and /usr15/degree/stud/jbw/gnu/TAGS (in that order)
because it matches both patterns.

If the buffer-local variable `buffer-tag-table' is set, then it names a tags
table that is searched before all others when find-tag is executed from this
buffer.

If there is a file called "TAGS" in the same directory as the file in 
question, then that tags file will always be used as well (after the
`buffer-tag-table' but before the tables specified by this list.)

If the variable tags-file-name is set, then the tags file it names will apply
to all buffers (for backwards compatibility.)  It is searched first.

------------------------------
tags-always-build-completion-table

*If t, tags files will always be added to the completion table without 
asking first, regardless of the size of the tags file.

------------------------------
teach-extended-commands-p

*If true, then `M-x' will teach you keybindings.
Any time you execute a command with M-x which has a shorter keybinding,
you will be shown the alternate binding before the command executes.

------------------------------
terminal-screen
The initial screen-object, which represents Emacs's stdout.

------------------------------
unmap-screen-hook
Function or functions to call when screen is unmapped.
One arg, the screen.

------------------------------
unread-command-event

Set this to an event object to simulate the reciept of an event from
the user.  Normally this is nil.

------------------------------
write-contents-hooks

List of functions to be called before writing out a buffer to a file.
If one of them returns non-nil, the file is considered already written
and the rest are not called.
These hooks are considered to pertain to the buffer's contents,
not to the particular visited file; thus, `set-visited-file-name' does
not clear this variable, but changing the major mode does clear it.
See also `write-file-hooks'.

------------------------------
x-allow-sendevents

*Non-nil means to allow synthetic events.  Nil means they are ignored.
Beware: allowing Emacs to process SendEvents opens a big security hole.

------------------------------
x-bitmap-file-path

A list of the directories in which X bitmap files may be found.
If nil, this is initialized from the "*bitmapFilePath" resource.
This is used by the `make-pixmap' function (however, note that if the
environment variable XBMLANGPATH is set, it is consulted first.)

------------------------------
x-emacs-application-class

The X application class of the Emacs process.
This controls, among other things, the name of the `app-defaults' file
that emacs will use.  For changes to this variable to take effect, they
must be made before the connection to the X server is initialized, that is,
this variable may only be changed before emacs is dumped, or by setting it
in the file lisp/term/x-win.el.

------------------------------
x-lost-selection-hooks

A function or functions to be called after the X server has notified us
that we have lost the selection.  The function(s) will be called with one
argument, a symbol naming the selection (typically PRIMARY, SECONDARY, or
CLIPBOARD.)

------------------------------
x-mode-pointer-shape

*The shape of the mouse-pointer when over the modeline.
If this is nil, then either `x-nontext-pointer-shape' or `x-pointer-shape'
will be used.

------------------------------
x-nontext-pointer-shape

*The shape of the mouse-pointer when over a buffer, but not over text.  
If this is nil, then `x-pointer-shape' is used.

------------------------------
x-pointer-background-color
*The background color of the mouse pointer.

------------------------------
x-pointer-foreground-color
*The foreground color of the mouse pointer.

------------------------------
x-pointer-shape
*The shape of the mouse-pointer when over text.

This string may be any of the standard cursor names from appendix B 
of the Xlib manual (also known as the file <X11/cursorfont.h>) minus 
the XC_ prefix, or it may be a font name and glyph index of the form 
"FONT fontname index [[font] index]", or it may be the name of a
bitmap file acceptable to XmuLocateBitmapFile().  If it is a bitmap
file, and if a bitmap file whose name is the name of the cursor with
"msk" exists, then it is used as the mask.  For example, a pair of
files may be named "cursor.xbm" and "cursor.xbmmsk".

------------------------------
x-screen-defaults

Alist of default screen-creation parameters for X-window screens.
These override what is specified in `~/.Xdefaults' but are overridden
by the arguments to the particular call to `x-create-screen'.

------------------------------
x-scrollbar-pointer-shape
The shape of the mouse pointer when over a scrollbar.

------------------------------
x-selection-pointer-shape
*The shape of the mouse-pointer when over a selectable text region.

------------------------------
x-sent-selection-hooks

A function or functions to be called after we have responded to some
other client's request for the value of a selection that we own.  The
function(s) will be called with four arguments:
  - the name of the selection (typically PRIMARY, SECONDARY, or CLIPBOARD);
  - the name of the selection-type which we were requested to convert the
    selection into before sending (for example, STRING or LENGTH);
  - and whether we successfully transmitted the selection.
We might have failed (and declined the request) for any number of reasons,
including being asked for a selection that we no longer own, or being asked
to convert into a type that we don't know about or that is inappropriate.
This hook doesn't let you change the behavior of Emacs's selection replies,
it merely informs you that they have happened.

------------------------------
xpm-color-symbols

Definitions of logical color-names used when reading XPM files.
Elements of this list should be of the form (COLOR-NAME FORM-TO-EVALUATE).
The COLOR-NAME should be a string, which is the name of the color to define;
the FORM should evaluate to a `pixel' object, or a string to be passed to
`make-pixel'.  If a loaded XPM file references a symbolic color called
COLOR-NAME, it will display as the computed pixel instead.

The default value of this variable defines the logical color names
"foreground" and "background" to be the colors of the `default' face.

------------------------------
zmacs-activate-region-hook

Function or functions called when the region becomes active;
see the variable `zmacs-regions'.

------------------------------
zmacs-region-stays

Commands which do not wish to affect whether the region is currently
highlighted should set this to t.  Normally, the region is turned off after
executing each command that did not explicitly turn it on with the function
zmacs-activate-region. Setting this to true lets a command be non-intrusive.
See the variable `zmacs-regions'.

------------------------------
zmacs-regions

*Whether LISPM-style active regions should be used.
This means that commands which operate on the region (the area between the
point and the mark) will only work while the region is in the ``active''
state, which is indicated by highlighting.  Executing most commands causes
the region to not be in the active state, so (for example) C-w will only
work immediately after activating the region.

More specifically:

 - Commands which operate on the region only work if the region is active.
 - Only a very small set of commands cause the region to become active:
   Those commands whose semantics are to mark an area, like mark-defun.
 - The region is deactivated after each command that is executed, except that:
 - "Motion" commands do not change whether the region is active or not.

set-mark-command (C-SPC) pushes a mark and activates the region.  Moving the
cursor with normal motion commands (C-n, C-p, etc) will cause the region
between point and the recently-pushed mark to be highlighted.  It will
remain highlighted until some non-motion comand is executed.

exchange-point-and-mark (C-x C-x) activates the region.  So if you mark a
region and execute a command that operates on it, you can reactivate the
same region with C-x C-x (or perhaps C-x C-x C-x C-x) to operate on it
again.

Generally, commands which push marks as a means of navigation (like
beginning-of-buffer and end-of-buffer (M-< and M->)) do not activate the
region.  But commands which push marks as a means of marking an area of
text (like mark-defun (M-C-h), mark-word (M-@) or mark-whole-buffer (C-x h))
do activate the region.

------------------------------
zmacs-deactivate-region-hook

Function or functions called when the region becomes inactive;
see the variable `zmacs-regions'.

------------------------------
zmacs-update-region-hook

Function or functions called when the active region changes.
This is called after each command that sets `region-stays' to t.
See the variable `zmacs-regions'.


Changed Functions:
==================

accept-process-output: (proc &optional timeout-secs timeout-msecs)

Allow any pending output from subprocesses to be read by Emacs.
It is read into the process' buffers or given to their filter functions.
Non-nil arg PROCESS means do not return until some output has been received
 from PROCESS.
If the second arg is non-nil, it is the maximum number of seconds to wait:
 this function will return after that much time even if no input has arrived
 from PROCESS.  This argument may be a float, meaning wait some fractional
 part of a second.
If the third arg is non-nil, it is a number of microseconds that is added
 to the first arg.  (This exists only for compatibility.)
Return non-nil ifn we received any output before the timeout expired.

------------------------------
baud-rate: ()
Obsolete function returning the value of the `baud-rate' variable.

------------------------------
beep: (&optional arg sound)

Beep, or flash the screen.
Also, unless an argument is given,
terminate any keyboard macro currently executing.
When called from lisp, the second argument is what sound to make.

------------------------------
compare-windows: (&optional ignore-whitespace)

Compare text in current window with text in next window.
Compares the text starting at point in each window,
moving over text in each one as far as they match.

A prefix arg means ignore changes in whitespace.
The variable `compare-windows-whitespace' controls how whitespace is skipped.

If `compare-ignore-case' is non-nil, changes in case are also ignored.

------------------------------
current-time-string: (&optional specified-time)

Return the current time, as a human-readable string.
Programs can use this function to decode a time,
since the number of columns in each field is fixed.
The format is `Sun Sep 16 01:03:52 1973'.
If an argument is given, it specifies a time to format
instead of the current time.  The argument should have the form:
  (HIGH . LOW)
or the form:
  (HIGH LOW . IGNORED).
Thus, you can use times obtained from `current-time'
and from `file-attributes'.

------------------------------
define-key: (keymap keys def)

Args KEYMAP, KEYS, DEF.  Define key sequence KEYS, in KEYMAP, as DEF.
KEYMAP is a keymap object.
KEYS is the sequence of keystrokes to bind, described below.
DEF is anything that can be a key's definition:
 nil (means key is undefined in this keymap);
 a command (a Lisp function suitable for interactive calling);
 a string or key sequence vector (treated as a keyboard macro);
 a keymap (to define a prefix key);
 a symbol; when the key is looked up, the symbol will stand for its
    function definition, that should at that time be one of the above,
    or another symbol whose function definition is used, and so on.
 a cons (STRING . DEFN), meaning that DEFN is the definition
    (DEFN should be a valid definition in its own right);
 or a cons (KEYMAP . CHAR), meaning use definition of CHAR in map KEYMAP.

Contrary to popular belief, the world is not ASCII.  When running under a
window manager, Emacs can tell the difference between, for example, the
keystrokes control-h, control-shift-h, and backspace.  You can, in fact,
bind different commands to each of these.

A `key sequence' is a set of keystrokes.  A `keystroke' is a keysym and some
set of modifiers (such as control and meta).  A `keysym' is what is printed
on the keys on your keyboard.

A keysym may be represented by a symbol, or (if and only if it is equivalent
to a printing ASCII character) by its ASCII code.  The `A' key may be
represented by the symbol `A' or by the number 65.  The `break' key may be
represented only by the symbol `break'.

A keystroke may be represented by a list: the last element of the list is
the key (a symbol or number, as above) and the preceding elements are the
symbolic names of modifier keys (control, meta, super, hyper, and shift.)
Thus, the sequence control-b is represented by the forms `(control b)' 
and `(control 98)'.  A keystroke may also be represented by an event object,
as returned by the `next-command-event' and `read-key-sequence' functions.

Note that in this context, the keystroke `control-b' is *not* represented
by the number 2 (the ASCII code for ^B).  See below.

The `shift' modifier is somewhat of a special case.  You should not (and
cannot) use `(meta shift a)' to mean `(meta A)', since for characters that
have printing ASCII equivalents, the state of the shift key is implicit in
the keysym (a vs. A).  You also cannot say `(shift =)' to mean `+', as that
sort of thing varies from keyboard to keyboard.  The shift modifier is for
use only with characters that do not have a second keysym on the same key,
such as `backspace' and `tab'.

A key sequence is a vector of keystrokes.  As a degenerate case, elements
of this vector may also be keysyms if they have no modifiers.  That is,
the `A' keystroke is represented by all of these forms:
	A	65	(A)	(65)	[A]	[65]	[(A)]	[(65)]
the `control-a' keystroke is represented by these forms:
	(control A)	(control 65)	[(control A)]	[(control 65)]
the key sequence `control-c control-a' is represented by these forms:
	[(control c) (control a)]	[(control 99) (control 65)]

Mouse button clicks work just like keypresses: (control button1) means
pressing the left mouse button while holding down the control key.
[(control c) (shift button3)] means control-c, hold shift, click right.

Commands may be bound to the mouse-button up-stroke rather than the down-
stroke as well.  `button1' means the down-stroke, and `button1up' means the
up-stroke.  Different commands may be bound to the up and down strokes,
though that is probably not what you want, so be careful.

For backward compatibility, a key sequence may also be represented by a
string.  In this case, it represents the key sequence(s) that would
produce that sequence of ASCII characters in a purely ASCII world.  For
example, a string containing the ASCII backspace character, "\^H", would
represent two key sequences: `(control h)' and `backspace'.  Binding a
command to this will actually bind both of those key sequences.  Likewise
for the following pairs:

		control h	backspace
		control i   	tab
		control m   	return
		control j   	linefeed
		control [   	escape
		control @	control space

After binding a command to two key sequences with a form like

	(define-key global-map "\^X\^I" 'command-1)

it is possible to redefine only one of those sequences like so:

	(define-key global-map [(control x) (control i)] 'command-2)
	(define-key global-map [(control x) tab] 'command-3)

Of course, all of this applies only when running under a window system.  If
you're talking to Emacs through an ASCII-only channel, you don't get any of
these features.

------------------------------
describe-key: (key)

Display documentation of the function invoked by KEY.
KEY is a string, or vector of events.
When called interactvely, KEY may also be a menu selection.

------------------------------
directory-files: (dirname &optional full match nosort files-only)

Return a list of names of files in DIRECTORY.
There are four optional arguments:
If FULL is non-nil, absolute pathnames of the files are returned.
If MATCH is non-nil, only pathnames containing that regexp are returned.
If NOSORT is non-nil, the list is not sorted--its order is unpredictable.
 NOSORT is useful if you plan to sort the result yourself.
If FILES-ONLY is the symbol t, then only the "files" in the directory
 will be returned; subdirectories will be excluded.  If FILES-ONLY is not
 nil and not t, then only the subdirectories will be returned.  Otherwise,
 if FILES-ONLY is nil (the default) then both files and subdirectories will
 be returned.

------------------------------
display-buffer: (buffer &optional not_this_window_p override_screen)

Make BUFFER appear in some window on the current screen, but don't
select it.
Arguments are BUFFER &optional NOT-THIS-WINDOW-P, OVERRIDE-SCREEN.
BUFFER can be a buffer or a buffer name.
If BUFFER is shown already in some window in the current screen,
just uses that one, unless the window is the selected window and
NOT-THIS-WINDOW-P is non-nil.

If BUFFER has a dedicated screen, display on that screen instead of
the current screen, unless OVERRIDE-SCREEN is non-nil.

If OVERRIDE-SCREEN is non-nil, display on that screen instead of
the current screen (or the dedicated screen).

If `pop-up-windows' is non-nil, always use the
current screen and create a new window regardless of whether the
buffer has a dedicated screen, and regardless of whether
OVERRIDE-SCREEN was specified.

Returns the window displaying BUFFER.

------------------------------
exit-minibuffer: ()

Terminate this minibuffer argument.
If minibuffer-confirm-incomplete is true, and we are in a completing-read
of some kind, and the contents of the minibuffer is not an existing
completion, requires an additional RET before the minibuffer will be exited
(assuming that RET was the character that invoked this command:
the character in question must be typed again).

------------------------------
The function `expand-mail-aliases' is obsolete and has been removed.

------------------------------
find-tag: (tagname &optional other-window)

*Find tag whose name contains TAGNAME.
Selects the buffer that the tag is contained in and puts
 point at its definition.
If TAGNAME is a null string, the expression in the buffer
 around or before point is used as the tag name.
If second arg NEXT is non-nil (interactively, with prefix arg),
 searches for the next tag in the tag table that matches the
 tagname used in the previous find-tag.

Multiple active tags tables and completion are supported.

Variables of note:

  tag-table-alist		controls which tables apply to which buffers
  tags-file-name		a default tags table
  tags-build-completion-table   controls completion behavior
  buffer-tag-table		another way of specifying a buffer-local table
  make-tags-files-invisible	whether tags tables should be very hidden
  tag-mark-stack-max		how many tags-based hops to remember
  buffer-tag-table		another way of specifying a buffer-local table
  make-tags-files-invisible	whether tags tables should be very hidden
  tag-mark-stack-max		how many tags-based hops to remember

------------------------------
format: (arg1 &rest args)
...
%s means print strings using `princ' and other objects using `prin1'.
%S means print all objects using `prin1' (including strings.)
%$ means reposition to read a specific numbered argument;
 for example, %3$%s would apply the `%s' and all following format directives
 to the third argument after the control string.  (There must be a positive
 integer between the % and the $.)
...
[%s retains the (undocumented) behavior of v18.  %S is new.]

------------------------------
get: (sym prop &optional defalt)

Return the value of SYMBOL's PROPNAME property.
This is the last VALUE stored with `(put SYMBOL PROPNAME VALUE)'.
If there is no such property, return optional third arg DEFAULT
  (which defaults to `nil'.)

------------------------------
get-buffer-window: (buffer &optional screen invisible-too)

Return a window currently displaying BUFFER, or nil if none.
If optional argument SCREEN is t, search all visible screens.
If SCREEN is a screen, search only that screen.
If INVISIBLE-TOO is t invisible screens are searched too.

------------------------------
interactive: (args)

There are some new `interactive' codes:

e -- Last mouse event.

In addition, if the string begins with `*'
 then an error is signaled if the buffer is read-only.
 This happens before reading any arguments.
If the string begins with `@', then the window the mouse is over is selected
 before anything else is done.
If the string begins with `_', then this command will not cause the region
 to be deactivated when it completes; that is, `zmacs-region-stays' will be
 set to t when the command exits successfully.
You may use any of `@', `*' and `_' at the beginning of the string;
 they are processed in the order that they appear.

------------------------------
isearch-forward: (&optional regexp-p)

Do incremental search forward.
With a prefix argument, do an incremental regular expression search instead.

As you type characters, they add to the search string and are found.
The following non-printing keys are bound in `isearch-mode-map'.  

Type DEL to cancel characters from end of search string.
Type RET to exit, leaving point at location found.
Type LFD (C-j) to match end of line.
Type C-s to search again forward, C-r to search again backward.
Type C-w to yank word from buffer onto end of search string and search for it.
Type C-y to yank rest of line onto end of search string and search for it.
Type C-q to quote control character to search for it.
Type M-SPC to match all whitespace chars in regexp.
C-g while searching or when search has failed cancels input back to what has
 been found successfully.
C-g when search is successful aborts and moves point to starting point.

Also supported is a search ring of the previous 16 search strings.
Type M-n to search for the next item in the search ring.
Type M-p to search for the previous item in the search ring.
Type M-TAB to complete the search string using the search ring.

The above keys are bound in the isearch-mode-map.  To change the keys which
 are special to isearch-mode, simply change the bindings in that map.

Other control and meta characters terminate the search
 and are then executed normally (depending on `search-exit-option').

If this function is called non-interactively, it does not return to
the calling function until the search is done.

------------------------------
key-binding: (keys)

Return the binding for command KEYS in current keymaps.
KEYS is a string, a vector of events, or a vector of key-description lists
as described in the documentation for the `define-key' function.
The binding is probably a symbol with a function definition; see
the documentation for `lookup-key' for more information.

For key-presses, the order of keymaps searched is:
  - the `keymap' property of any extent(s) at point;
  - the current-local-map of the current-buffer;
  - the current global map.

For mouse-clicks, the order of keymaps searched is:
  - the current-local-map of the `mouse-grabbed-buffer' if any;
  - the `keymap' property of any extent(s) at the position of the click;
  - the mode-line-map of the buffer corresponding to the mode-line under
    the mouse (if the click happened over a mode line);
  - the current-local-map of the buffer under the mouse;
  - the current global map.

------------------------------
kill-emacs: (&optional arg)

Exit the Emacs job and kill it.  Ask for confirmation, without argument.
If ARG is an integer, return ARG as the exit program code.
If ARG is a  string, stuff it as keyboard input.

The value of `kill-emacs-hook', if not void,
is a list of functions (of no args),
all of which are called before Emacs is actually killed.

------------------------------
local-key-binding: (keys)

Return the binding for command KEYS in current local keymap only.
KEYS is a string, a vector of events, or a vector of key-description lists
as described in the documentation for the `define-key' function.
The binding is probably a symbol with a function definition; see
the documentation for `lookup-key' for more information.

------------------------------
local-set-key: (keys function)

Give KEY a local binding as COMMAND.
COMMAND is a symbol naming an interactively-callable function.
KEYS is a string, a vector of events, or a vector of key-description lists
as described in the documentation for the `define-key' function.
The binding goes in the current buffer's local map,
which is shared with other buffers in the same major mode.

------------------------------
local-unset-key: (keys)

Remove local binding of KEY.
KEYS is a string, a vector of events, or a vector of key-description lists
as described in the documentation for the `define-key' function.

------------------------------
lookup-key: (keymap keys)

In keymap KEYMAP, look up key sequence KEYS.  Return the definition.
nil means undefined.  See doc of `define-key' for kinds of definitions
and key-sequence specifications.
Number as value means KEYS is "too long";
that is, characters in it except for the last one
fail to be a valid sequence of prefix characters in KEYMAP.
The number is how many characters at the front of KEYS
it takes to reach a non-prefix command.

------------------------------
make-sparse-keymap: ()

Construct and return a new keymap object.  All entries in it are nil,
meaning "command undefined".  The only difference between this function
and make-keymap is that this function returns a "smaller" keymap (one
that is expected to contain less entries.)  As keymaps dynamically resize,
the distinction is not great.

------------------------------
mark: (&optional inactive-p)

Return this buffer's mark value as integer, or nil if no mark.

If `zmacs-regions' is true, then this returns nil unless the region is
currently in the active (highlighted) state.  With an argument of t, this
returns the mark (if there is one) regardless of the active-region state.
You should *generally* not use the mark unless the region is active, if
the user has expressed a preference for the active-region model.

If you are using this in an editing command, you are most likely making
a mistake; see the documentation of `set-mark'.

------------------------------
mark-marker: (&optional inactive-p)

Return this buffer's mark, as a marker object.
If `zmacs-regions' is true, then this returns nil unless the region is
currently in the active (highlighted) state.  With an argument of t, this
returns the mark (if there is one) regardless of the zmacs-region state.
You should *generally* not use the mark unless the region is active, if
the user has expressed a preference for the zmacs-region model.
Watch out!  Moving this marker changes the mark position.
If you set the marker not to point anywhere, the buffer will have no mark.

------------------------------
next-window: (&optional window mini all-screens invisible-too)

Return next window after WINDOW in canonical ordering of windows.
Optional second arg MINIBUF t means count the minibuffer window
even if not active.  If MINIBUF is neither t nor nil it means
not to count the minibuffer even if it is active.
Optional third arg ALL-SCREENS t means include all windows in all visible
screens; otherwise cycle within the selected screen, with the exception that
if a global minibuffer screen is in use, all screens are used.
Optional fourth argument INVISIBLE-TOO t means also visit invisible screens.

------------------------------
other-buffer: (&optional buffer screen)

Return most recently selected buffer other than BUFFER.
Buffers not visible in windows are preferred to visible buffers.
If no other buffer exists, the buffer `*scratch*' is returned.
If BUFFER is omitted or nil, some interesting buffer is returned.

The ordering is for this screen; If second optional argument SCREEN
is provided, then the ordering is for that screen.  If the second arg
is t, then the global ordering is returned.

------------------------------
other-window: (n &optional all-screens invisible-too)

Select the ARG'th different window on this screen.
All windows on current screen are arranged in a cyclic order.
This command selects the window ARG steps away in that order.
A negative ARG moves in the opposite order.  If the optional second
argument ALL-SCREENS is non-nil, cycle through all visible screens.
If optional third argument INVISIBLE-TOO is t also search invisible screens.

------------------------------
point-marker: (&optional dont_copy_p)

Return value of point, as a marker object.
This marker is a copy; you may modify it with reckless abandon.
If the argument to this function is non-nil, then it returns the real
point-marker; modifying the position of this marker willl move point.
It is illegal to change the buffer of it, or make it point nowhere.

------------------------------
previous-screen: (&optional screen miniscreen visible-only-p)

Return the previous screen in the screen list after SCREEN.
If MINISCREEN is non-nil, include the global-minibuffer-screen if it
has its own screen.
If VISIBLE-ONLY-P is non-nil, then cycle through the visible screens,
instead of all screens.

------------------------------
read: (&optional readcharfun)

The `read' function no longer consumes the whitespace following an expression
after reading it.  Point will be left immediately after the last character of
the token that was read, instead of after any whitespace following the last
character of the token.

------------------------------
read-char: ()

Read a character from the command input (keyboard or macro).
If a mouse click is detected, an error is signalled.  The character typed
is returned as an ASCII value.  This is most likely the wrong thing for you
to be using: consider using the `next-command-event' function instead.

------------------------------
read-key-sequence: (prompt)

Read a sequence of keystrokes or mouse clicks and return a vector of the
event objects read.  The vector and the event objects it contains are
freshly created (and will not be side-effected by subsequent calls
to this function.)

The sequence read is sufficient to specify a non-prefix command starting
from the current local and global keymaps.  A C-g typed while in this
function is treated like any other character, and `quit-flag' is not set.

First arg PROMPT is a prompt string.  If nil, do not prompt specially.

If the user selects a menu item while we are prompting for a key-sequence,
the returned value will be a vector of a single menu-selection event.
An error will be signalled if you pass this value to `lookup-key' or a
related function.

------------------------------
recent-keys: ()

Return vector of last 100 keyboard or mouse button events read.
This copies 100 event objects and a vector; it is safe to keep and modify
them.

------------------------------
redraw-screen: (screen)
Clear screen SCREEN and output again what is supposed to appear on it.

------------------------------
this-command-keys: ()

Returns a vector of the keyboard or mouse button events that were used
to invoke this command.  This copies the vector and the events; it is safe
to keep and modify them.

------------------------------
visit-tags-table: (file)

Tell tags commands to use tags table file FILE first.
FILE should be the name of a file created with the `etags' program.
A directory name is ok too; it means file TAGS in that directory.
This function is largely obsoleted by the variable tag-table-alist.

------------------------------
write-region: (start end filename &optional append visit)

Write current region into specified file.
When called from a program, takes three arguments:
START, END and FILENAME.  START and END are buffer positions.
Optional fourth argument APPEND if non-nil means
  append to existing file contents (if any).
Optional fifth argument VISIT if t means
  set the last-save-file-modtime of buffer to this file's modtime
  and mark buffer not modified.
If VISIT is a string, it is a second file name;
  the output goes to FILENAME, but the buffer is marked as visiting VISIT.
  VISIT is also the file name to lock and unlock for clash detection.
If VISIT is neither t nor nil nor a string,
  that means do not print the "Wrote file" message.
Kludgy feature: if START is a string, then that string is written
to the file, instead of any buffer contents, and END is ignored.


Changed Variables:
==================

auto-fill-hook
The variable `auto-fill-hook' has been renamed `auto-fill-function'

------------------------------
blink-paren-hook
The variable `blink-paren-hook' has been renamed `blink-paren-function'

------------------------------
ctl-arrow

*Non-nil means display control chars with uparrow.
Nil means use backslash and octal digits.
An integer means characters >= ctl-arrow are assumed to be printable, and
will be displayed as a single glyph.
Any other value is the same as 160 - the code SPC with the high bit on.

The interpretation of this variable is likely to change in the future.

Automatically becomes buffer-local when set in any fashion.
This variable does not apply to characters whose display is specified
in the current display table (if there is one).

------------------------------
default-directory

Name of default directory of current buffer.  Should end with slash.
Each buffer has its own value of this variable.

------------------------------
`inhibit-local-variables' has been replaced with `enable-local-variables',
with the reversed sense.

------------------------------
executing-kbd-macro

Currently executing keyboard macro (a vector of events);
nil if none executing.

------------------------------
executing-macro

Currently executing keyboard macro (a vector of events);
nil if none executing.

------------------------------
inverse-video

The variable `inverse-video' is currently ignored; this will eventually be
a parameter of the `default' face on tty screens.  For X screens, simply set
the foreground and background colors appropriately.

------------------------------
keyboard-translate-table

String used as translate table for keyboard input, or nil.
Each character is looked up in this string and the contents used instead.
If string is of length N, character codes N and up are untranslated.
This is the right thing to use only if you are on a dumb tty, as it cannot
handle input which cannot be represented as ASCII.  If you are running Emacs
under X, you should do the translations with the `xmodmap' program instead.

------------------------------
last-command-char

If the value of `last-command-event' is a keyboard event, then
this is the nearest ASCII equivalent to it.  This the the value that
`self-insert-command' will put in the buffer.  Remember that there is
NOT a 1:1 mapping between keyboard events and ASCII characters: the set
of keyboard events is much larger, so writing code that examines this
variable to determine what key has been typed is bad practice, unless
you are certain that it will be one of a small set of characters.

------------------------------
last-input-char

If the value of `last-input-event' is a keyboard event, then
this is the nearest ASCII equivalent to it.  Remember that there is
NOT a 1:1 mapping between keyboard events and ASCII characters: the set
of keyboard events is much larger, so writing code that examines this
variable to determine what key has been typed is bad practice, unless
you are certain that it will be one of a small set of characters.

------------------------------
last-kbd-macro
Last kbd macro defined, as a vector of events; nil if none defined.

------------------------------
lisp-indent-hook
The variable `lisp-indent-hook' has been renamed `lisp-indent-function'

------------------------------
load-path
*List of directories to search for files to load.
Each element is a string (directory name) or nil (try default directory).

Note that the elements of this list *may not* begin with "~", so you must
call `expand-file-name' on them before adding them to this list.

Initialized based on EMACSLOADPATH environment variable, if any,
otherwise to default specified in by file `paths.h' when Emacs was built.
If there were no paths specified in `paths.h', then emacs chooses a default
value for this variable by looking around in the file-system near the
directory in which the emacs executable resides.

------------------------------
mail-aliases

Word-abbrev table of mail address aliases.
If this is nil, it means the aliases have not yet been initialized and
should be read from the .mailrc file.  (This is distinct from there being
no aliases, which is represented by this being a table with no entries.)

------------------------------
mode-line-format

The `mode-line-format' and similar strings accept a new format directive:

  %S -- print name of selected screen (only meaningful under X Windows).

------------------------------
mode-line-inverse-video

The variable `mode-line-inverse-video' is currently ignored; this will
eventually be a parameter of the `modeline' face on tty screens.  For X
screens, simply set the foreground and background colors appropriately.

------------------------------
tags-file-name

*The name of the tags-table used by all buffers.
This is for backward compatibility, and is largely supplanted by the
variable tag-table-alist.

------------------------------
temp-buffer-show-hook

The variable `temp-buffer-show-hook' has been renamed
`temp-buffer-show-function'.

------------------------------
write-file-hooks

List of functions to be called before writing out a buffer to a file.
If one of them returns non-nil, the file is considered already written
and the rest are not called.
These hooks are considered to pertain to the visited file.
So this list is cleared if you change the visited file name.
See also `write-contents-hooks'.


Major Differences Between 19.8 and 19.9
=======================================

Scrollbars!  If you have Motif, these are real Motif scrollbars; otherwise,
Athena scrollbars are used.  They obey all the usual resources of their
respective toolkits.

There is now an implementation of dialog boxes based based on the Athena
widgets, as well as the existing Motif implementation.

This release works with Motif 1.2 as well as 1.1.  If you link with Motif, 
you do not also need to link with Athena.

If you compile lwlib with both USE_MOTIF and USE_LUCID defined (which is the
recommended configuration) then the Lucid menus will draw text using the Motif
string-drawing library, instead of the Xlib one.  The reason for this is that
one can take advantage of the XmString facilities for including non-Latin1
characters in resource specifications.  However, this is a user-visible change
in that, in this configuration, the menubar will use the "*fontList" resource 
in preference to the "*font" resource, if it is set.

It's possible to make extents which are copied/pasted by kill and undo.
There is an implementation of FSF19-style text properties based on this.

There is a new variable, minibuffer-max-depth, which is intended to circumvent
a common source of confusion among new Emacs users.  Since, under a window
system, it's easy to jump out of the minibuffer (by doing M-x, then getting
distracted, and clicking elsewhere) many, many novice users have had the
problem of having multiple minibuffers build up, even to the point of
exhausting the lisp stack.  So the default behavior is to disallow the
minibuffer to ever be reinvoked while active; if you attempt to do so, you
will be prompted about it.

There is a new variable, teach-extended-commands-p, which if set, will cause
`M-x' to remind you of any keybindings of the command you just invoked the
"long way."

There are menus in Dired, Tar, Comint, Compile, and Grep modes.

There is a menu of window management commands on the right mouse button over
the modelines.

Popup menus now have titles at the top; this is controlled by the new 
variable `popup-menu-titles'.

The `Find' key on Sun keyboards will search for the next (or previous)
occurrence of the selected text, as in OpenWindows programs.

The `timer' package has been renamed to `itimer' to avoid a conflict with
a different package called `timer'.

VM 5.40 is included.

W3, the emacs interface to the World Wide Web, is included.

Felix Lee's GNUS speedups have been installed, including his new version of
nntp.el which makes GNUS efficiently utilize the NNTP XOVER command if
available (which is much faster.)  

GNUS should also be much friendlier to new users: it starts up much faster,
and doesn't (necessarily) subscribe you to every single newsgroup.

The byte-compiler issues a new class of warnings: variables which are
bound but not used.  This is merely an advisory, and does not mean the
code is incorrect; you can disable these warnings in the usual way with
the `byte-compiler-options' macro.

the `start-open' and `end-open' extent properties, for specifying whether
characters inserted exactly at a boundary of an extent should go into the
extent or out of it, now work correctly.

The `extent-data' slot has been generalized/replaced with a property list,
so it's easier to attach arbitrary data to extent objects.

The `event-modifiers' and `event-modifier-bits' functions work on motion
events as well as other mouse and keyboard events.

Forms-mode uses fonts and read-only regions.

The behavior of the -geometry command line option should be correct now.

The `iconic' screen parameter works when passed to x-create-screen.

The user's manual now documents Lucid Emacs 19.9.

The relocating buffer allocator is turned on by default; this means that when
buffers are killed, their storage will be returned to the operating system, 
and the size of the emacs process will shrink.

CAVEAT: code which contains calls to certain `face' accessor functions will
need to be recompiled by version 19.9 before it will work.  The functions
whose callers must be recompiled are: face-font, face-foreground,
face-background, face-background-pixmap, and face-underline-p.  The symptom
of this problem is the error "Wrong type argument, arrayp, #<face ... >".
The .elc files generated by version 19.9 will work in 19.6 and 19.8, but
older .elc files which contain calls to these functions will not work in 19.9.

Work In Progress:

 - We have been in the process of internationalizing Lucid Emacs.  This code
   is ***not*** ready for general use yet.  However, the code is included (and
   turned off by default) in this release.

   - If you define I18N2 at compile-time, then sorting/collation will be done
     according to the locale returned by setlocale().

   - If you define I18N3 at compile-time, then all messages printed by lemacs
     will be filtered through the gettext() library routine, to enable the use
     of locale-specific translation catalogues.  The current implementation of
     this is quite dependent on Solaris 2, and has a very large impact on 
     existing code, therefore we are going to be making major changes soon.
     (You'll notice calls to `gettext' and `GETTEXT' scattered around much of
     the lisp and C code; ignore it, this will be going away.)

   - If you define I18N4 at compile-time, then lemacs will internally use a
     wide representation of characters, enabling the use of large character
     sets such as Kanji.  This code is very OS dependent: it requires X11R5, 
     and several OS-supplied library routines for reading and writing wide
     characters (getwc(), putwc(), and a few others.)  Performance is also a
     problem.  This code is also scheduled for a major overhaul, with the
     intent of improving performance and portability.  

     Our eventual goal is to merge with MULE, or at least provide the same base
     level of functionality.  If you would like to help out with this, let us 
     know.

 - Other work-in-progress includes Motif drag-and-drop support, ToolTalk 
   support, and support for embedding an Emacs widget inside another 
   application (where it can function as that other application's text-entry
   area).  This code has not been extensively tested, and may (or may not)
   have portability problems, but it's there for the adventurous.  Comments, 
   suggestions, bug reports, and especially fixes are welcome.  But have no
   expectations that this experimental code will work at all.


Major Differences Between 19.6 and 19.8
=======================================

There were almost no differences between versions 19.6 and 19.7; version 19.7
was a bug-fix release that was distributed with Energize 2.1.

Lucid Emacs 19.8 represents the first stage of the Lucid Emacs/Epoch merger.
The redisplay engine now in lemacs is an improved descendant of the Epoch
redisplay.  As a result, many bugs have been eliminated, and several disabled
features have been re-enabled.  Notably:

Selective display (and outline-mode) work.

Horizontally split windows work.

The height of a line is the height of the tallest font displayed on that line;
it is possible for a screen to display lines of differing heights. (Previously,
the height of all lines was the height of the tallest font loaded.)

There is lisp code to scale fonts up and down, for example, to load the next-
taller version of a font.

There is a new internal representation for lisp objects, giving emacs-lisp 28
bit integers and a 28 bit address space, up from the previous maximum of 26.
We expect eventually to increase this to 30 bit integers and a 32 bit address
space, eliminating the need for DATA_SEG_BITS on some architectures.  (On 64
bit machines, add 32 to all of these numbers.)

GC performance is improved.

Various X objects (fonts, colors, cursors, pixmaps) are accessible as first-
class lisp objects, with finalization.

When using XPM files, one can specify the values of logical color names to be
used when loading the files.

It is possible to resize windows by dragging their modelines up and down.  More
generally, it is possible to add bindings for mouse gestures on the modelines.

There is support for playing sound files on HP machines.

ILISP version 5.5 is included.

The Common Lisp #' read syntax is supported (#' is to "function" as ' is to
"quote".)

The `active-p' slot of menu items is now evaluated, so one can put arbitrary
lisp code in a menu to decide whether that item should be selectable, rather
than doing this with an `activate-menubar-hook'.

The X resource hierarchy has changed slightly, to be more consistent.  It used
to be
 	argv[0]			SCREEN-NAME	pane	screen
  	ApplicationShell	EmacsShell	Paned	EmacsScreen

   now it is

	argv[0]			shell		pane	SCREEN-NAME
	ApplicationShell	EmacsShell	Paned	EmacsScreen

The Lucid Emacs sources have been largely merged with FSF version 19; this
means that the lisp library contains the most recent releases of various
packages, and many new features of FSF 19 have been incorporated.

Because of this, the lemacs sources should also be substantially more portable.


Major Differences Between 19.4 and 19.6
=======================================

There were almost no differences between versions 19.4 and 19.5; we fixed
a few minor bugs and repacked 19.4 as 19.5 for a CD-ROM that we gave away
as a trade show promotion.

The primary goal of the 19.6 release is stability, rather than improved
functionality, so there aren't many user-visible changes.  The most notable
changes are:

 - The -geometry command-line option now correctly overrides geometry
   specifications in the resource database.
 - The `width' and `height' screen-parameters work.
 - Font-lock-mode considers the comment start and end characters to be
   a part of the comment.
 - The lhilit package has been removed.  Use font-lock-mode instead.
 - vm-isearch has been fixed to work with isearch-mode.
 - new versions of ispell and calendar.
 - sccs.el has menus.

Lots of bugs were fixed, including the problem that lemacs occasionally
grabbed the keyboard focus.

Also, as of Lucid Emacs 19.6 and Energize 2.0 (shipping now) it is possible
to compile the public release of Lucid Emacs with support for Energize; so
now Energize users will be able to build their own Energize-aware versions
of lemacs, and will be able to use newer versions of lemacs as they are
released to the net.  (Of course, this is not behavior covered by your
Energize support contract; you do it at your own risk.)

I have not incorporated all portability patches that I have been sent since
19.4; I will try to get to them soon.  However, if you need to make any
changes to lemacs to get it to compile on your system, it would be quite
helpful if you would send me context diffs (diff -c) against version 19.6.


Major Differences Between 19.3 and 19.4
=======================================

Prototypes have been added for all functions.  Emacs compiles in the strict
ANSI modes of lcc and gcc, so portability should be vastly improved.

Many many many many core leaks have been plugged, especially in screen 
creation and deletion.

The float support reworked to be more portable and ANSI conformant.  This
resulted in these new configuration parameters: HAVE_INVERSE_HYPERBOLIC, 
HAVE_CBRT, HAVE_RINT, FLOAT_CHECK_ERRNO, FLOAT_CATCH_SIGILL, 
FLOAT_CHECK_DOMAIN.  Let us know if you had to change the defaults on your
architecture.

The SunOS unexec has been rewritten, and now works with either static or 
dynamic libraries, depending on whether -Bstatic or -Bdynamic were specified
at link-time.

Small (character-sized) bitmaps can be mixed in with buffer text via the new
functions set-extent-begin-glyph and set-extent-end-glyph.  (This is actually
a piece of functionality that Energize has been using for a while, but we've
just gotten around to making it possible to use it without Energize.  See how
nice we are?  Go buy our product.)

If compiled with Motif support, one can pop up dialog boxes from emacs lisp.
We encourage someone to contribute Athena an version of this code; it
shouldn't be much work.  

If dialog boxes are available, then y-or-n-p and yes-or-no-p use dialog boxes
instead of the minibuffer if invoked as a result of a command that was 
executed from a menu instead of from the keyboard.

Multiple screen support works better; check out doc of get-screen-for-buffer.

The default binding of backspace is the same as delete.  (C-h is still help.)

A middle click while the minibuffer is active does completion if you click on 
a highlighted completion, otherwise it executes the global binding of button2.

New versions of Barry Warsaw's c++-mode and syntax.c.  Font-lock-mode works
with C++ mode now.

The semantics of activate-menubar-hook has changed; the functions are called
with no arguments now.

`truename' no longer hacks the automounter; use directory-abbrev-alist instead.

Most minibuffer handling has been reimplemented in emacs-lisp.

There is now a builtin minibuffer history mechanism which replaces gmhist.


Major Differences Between 19.2 and 19.3
=======================================

The ISO characters have correct case and syntax tables now, so the word-motion
and case-converting commands work sensibly on them.

If you set ctl-arrow to an integer, you can control exactly which characters
are printable.  (There will be a less crufty way to do this eventually.)

Menubars can now be buffer local; the function set-screen-menubar no longer
exists.  Look at GNUS and VM for examples of how to do this, or read 
menubar.el.

When emacs is reading from the minibuffer with completions, any completions
which are visible on the screen will highlight when the mouse moves over them;
clicking middle on a completion is the same as typing it at the minibuffer.
Some implications of this:  The *Completions* buffer is always mousable.  If
you're using the completion feature of find-tag, your source code will be
mousable when you type M-.  Dired buffers will be mousable as soon as you 
type ^X^F.  And so on.

The old isearch code has been replaced with a descendant of Dan LaLiberte's
excellent isearch-mode; it is more customizable, and generally less bogus.
You can search for "composed" characters.  There are new commands, too; see
the doc for ^S, or the NEWS file.

A patched GNUS 3.14 is included.

The user's manual now documents Lucid Emacs 19.3.

A few more modes have mouse and menu support.

The startup code should be a little more robust, and give you more reasonable
error messages when things aren't installed quite right (instead of the
ubiquitous "cannot open DISPLAY"...)

Subdirectories of the lisp directory whose names begin with a hyphen or dot
are not automatically added to the load-path, so you can use this to avoid
accidentally inflicting experimental software on your users.

I've tried to incorporate all of the portability patches that were sent to
me; I tried to solve some of the problems in different ways than the 
patches did, so let me know if I missed something.

Some systems will need to define NEED_STRDUP, NEED_REALPATH, HAVE_DREM, or
HAVE_REMAINDER in config.h.  Really this should be done in the appropriate
s- or m- files, but I don't know which systems need these and which don't.
If yours does, let me know which file it should be in.

Check out these new packages:

blink-paren.el:	causes the matching parenthesis to flash on and off whenever
		the cursor is sitting on a paren-syntax character.

pending-del.el:	Certain commands implicitly delete the highlighted region:
		Typing a character when there is a highlighted region replaces
		that region with the typed character.

lhilit.el:	Attaches fonts/colors to patterns matching regular expressions.

font-lock.el:	Yet Another code-highlighting package, but this one is driven
		off of syntax tables, so that it understands block comments,
		strings, etc.  The insertion hook is used to fontify text as
		you type it in.  (This is fast now.)

shell-font.el:	Displays your shell-buffer prompt in boldface.
