General Information
*******************

Getting Started
===============

We assume you are reasonably familiar with GNU Emacs.  You can essentially use Epoch just like GNU Emacs.

Epoch is started just like GNU Emacs: type epoch on the command line.  Epoch opens its own X window(s), so it can be run as a background job.

Depending on its mode of operation, Epoch will create one or two windows by default.  The first will contain the initial edit buffer; if created, the second will contain the minibuffer.  More on this below (see New Features).

If you wish to use Epoch without having to do any Elisp programming while still being able to specify window properties, the following sections are for you.

X Window Program Defaults
-------------------------

Epoch reads the default values associated with X Window System programs, or X defaults, set up by the user.  The possible sources of these defaults are listed below in the order in which Epoch will discover them.  These values are loaded into an internal database, called the global default-set, which is initially filled in with hard-wired defaults (which are listed below).

The resulting global default-set is stored, and remains constant for the rest of the program execution.  It serves as a basis for all screen creation, in order to guarantee a value for every property.  (The minibuffer has its own default-set, which is used once, to create the minibuffer screen.)  See Screen Properties for more background on how X defaults are used.

The X default specifications are determined in the following order, with later specifications superceding earlier values for the same options:

 1. Hard-wired X defaults (see below).

 2. <resource-name> or <class-name> in either $XAPPLRESDIR or the appropriate app-defaults directory.

 3. $HOME/.Xdefaults if the "-ud" command line flag is used.

 4. File named by the environment variable $XENVIRONMENT.

 5. If $XENVIRONMENT is not set, $HOME/.Xdefaults-<hostname>.

 6. Resources database (see xrdb).

 7. Command line options.

The X default options recognized by Epoch are listed in the table below. The window resource name/class defaults are special; they default to the program resource name/class respectively (see Command Line Options).

Furthermore, the program resource name/class command line options are special.  They are not put into the internal database - they affect how the database is queried for X default values.  When searching for names and classes, the leftmost qualifier is the resource name/class name.  The default for the name is the name of the program (normally "epoch") and the default for the class is "Emacs".  If these are set by command line options, the new values become the X defaults.

Epoch also accepts class defaults (as distinct from resource defaults), which are exactly as below except that the first letter of each field is capitalized.

Option
     Default Value, Effect

.screen.background
     White, Edit screen background color

.minibuf.background
     White, Minibuffer screen background color

.screen.border.color
     Black, Edit screen border color

.minibuf.border.color
     Black, Minibuffer screen border color

.screen.border.width
     2, Edit screen border width

.minibuf.border.width
     2, Minibuffer screen border width

.screen.cursor.background
     White, Edit screen X cursor background color

.minibuf.cursor.background
     White, Minibuffer screen X cursor background color

.screen.cursor.color
     Black, Edit screen text cursor color

.minibuf.cursor.color
     Black, Minibuffer screen text cursor color

.screen.cursor.foreground
     Black, Edit screen X cursor foreground color

.minibuf.cursor.foreground
     Black, Minibuffer screen X cursor foreground color

.screen.cursor.glyph
     86, Edit screen X cursor glyph

.minibuf.cursor.glyph
     86, Minibuffer screen X cursor glyph

.screen.internal.border.width
     2, Edit screen internal border width

.minibuf.internal.border.width
     2, Minibuffer screen internal border width

.screen.class
     <special>, Resource class of the edit screen

.minibuf.class
     <special>, Resource class of the minibuffer screen

.nonlocal.minibuf
     false, Minibuffer location (local or non-local)

.display
     "", X Window display

.motion
     Off, Whether motion-hints should come through to Elisp

.screen.font
     "fixed", Edit screen font

.minibuf.font
     "fixed", Minibuffer screen font

.screen.foreground
     Black, Edit screen foreground color

.minibuf.foreground
     Black, Minibuffer screen foreground color

.screen.geometry
     "80x24", Geometry of the initial edit screen

.minibuf.geometry
     "80x1", Geometry of the minibuffer screen

.screen.name
     "Edit", Name of the edit screen

.minibuf.name
     "Minibuffer", Name of the minibuffer screen

.screen.resource
     <special>, Resource name of the edit screen

.minibuf.resource
     <special>, Resource name of the minibuffer screen

.screen.reverse
     False, Reverse colors for edit screen

.minibuf.reverse
     False, Reverse colors for minibuffer screen

.screen.icon.name
     "", Icon Name

Command Line Options
--------------------

Epoch also accepts command line options.  These options override values in the X defaults.  A complete list is in the table below.  Note that the program resource name/class can be overridden by specifying different values on the command line (see X Window Program Defaults for how the name and class are used).

Option
     Resource, Effect

-bg
     *background, Sets background colors.

-background
     *background, Sets background colors.

-fg
     *foreground, Sets foreground color.

-foreground
     *foreground, Sets foreground color.

-geometry
     *screen.geometry, Sets X window geometry.

-fn
     *font, Sets the font.

-font
     *font, Sets the font.

-nm
     *nonlocal.minibuf, Selects local minibuffer to each edit screen.

-wn
     *name, Sets the X window title.

-window
     *name, Sets the X window title.

-d
     *display, Sets the display to use.

-display
     *display, Sets the display to use.

-r
     *reverse, Reverses foreground/background colors (no argument).

-rn
     NA, Sets the resource name.

-resource
     NA, Sets the resource name.

-name
     NA, Sets the resource name.

-cn
     NA, Sets the resource class.

-class
     NA, Sets the resource class.

-ud
     NA, Looks at $HOME/.Xdefaults for program defaults.

-motion
     *motion, Turns on passing of motion events to Elisp for all screens.

-xrm
     NA, Overrides a resource manager value.

New Features
============

This section provides a brief overview of the new features in Epoch. More detail is provided in subsequent chapters.

In this document, the term screen will mean an X window created and managed by Epoch, and window will refer to an Emacs editor window.  In most cases, working within a screen is the same as working within a GNU Emacs session.

At any time, there is a single selected screen; this is similar to having a selected window.  The selected screen is also called the current screen.  Standard window functions work, but only apply to the current screen; e.g., one-window-p returns non-nil if there is only one window on the current screen.  Buffers are shared among all screens, so any buffer can be accessed in any window, and will show up in the buffer list.  Killing a buffer removes it from all windows and all screens.

Epoch supports two different kinds of minibuffers.  The default is a non-local minibuffer, which is displayed in its own distinct screen; this is what Epoch has traditionally done.  The alternative is to have minibuffer windows local to each edit screen; this is similar to traditional GNU Emacs.  In the case of non-local minibuffers, there will always be exactly one minibuffer screen, and one or more edit screens; a single edit screen and minibuffer screen together act similarly to normal GNU Emacs.  For local minibuffers, the real minibuffer will be located at the bottom of the current edit screen.

Zones are regions of text in a buffer that can have data attached to them and be displayed in different styles (background/foreground color, stipple pattern, font, underlining) than surrounding text.  Zones provide both the ability to do highlighting and to attach data to text regions that can be retrieved based on buffer location.

Epoch supports the use of either fixed-size or variable-sized (proportional) fonts for display.  This includes support for mixtures of fonts (using zones) which feature potentially different attributes (default or quad width, ascent, descent, etc.).

Epoch supports event sending and receiving, including client messages and X Window properties, and asynchronous reception of client and property change events.  This allows Epoch to communicate with other X clients and the window manager.

Key Bindings
============

Epoch provides a large range of useful functions to create, delete and change the attributes of screens (e.g., changing colors, sizes, etc). We provide a default set of key bindings for these functions, shown below.

The basic idea was to take the C-x binding for Emacs window and buffer operations, and provide analogs for screen operations using C-z as the prefix key.  (We use C-z because a suspend operator is not all that useful in a multi-window environment, and in any case C-x C-z still provides the same effect as the standard.)  We do not believe we have a full set of bindings yet, and we look forward to user contributions.

We supply a standard set of Elisp files (see Packages).  They provide a good introduction to using the primitive Epoch facilities described in this document.  The file epoch.el installs the basic Epoch key bindings.  See below for more information.

Key
     Functionality

C-z 4 f
     find-file-other-screen Finds a file in another screen.  Prompts for a filename.  If it is already in a window on a screen, warps the cursor there, otherwise creates a new screen and edits the file in it.

C-z 4 b
     find-buffer-other-screen Selects a buffer in another screen.  Prompts for a buffer name.  If it is already in a window on a screen, warps the cursor there, otherwise creates a new screen with one window for the buffer.

C-z 0
     remove-screen Deletes the current screen.

C-z o
     switch-screen Circulates through mapped screens in forward direction.

C-z p
     prev-switch-screen Circulates through mapped screens in reverse direction.

C-z 2
     duplicate-screen Duplicates current screen.

C-z r
     raise-current-screen Raises current screen.

C-z l
     lower-current-screen Lowers current screen.

C-z m
     raise-minibuf Raises minibuffer screen.

C-z i
     iconify-screen Iconifies current screen.

C-z e
     display-event-status Displays event handler status.

Conventions
===========

Several conventions are used in the following chapters.

  * Functions and variables are described with the format used in the Emacs Lisp Reference Manual.

  * Any SCREEN argument can be a screen ID or a screen object. Optional screen arguments default to the current screen.

  * Any COLOR argument can be an X Resource of type X-Cardinal (see X Resources), a vector or a string.  Strings and vectors are converted to X-Cardinals internally.

Each Epoch primitive has a leading epoch:: in a fashion reminiscent of Common Lisp packages; e.g., epoch::create-screen. The reason is that we want to build around these functions at the Elisp level, so we deliberately make the primitives uncomfortable to use.  The files wrapper.el and epoch.el provide a full set of wrappers that remove the epoch:: leading characters and add additional functionality (e.g., there is a function create-screen that provides a higher-level interface to epoch::create-screen).  If you are going to write your own Elisp code, you should probably use these wrapper functions, not the raw primitives.

Menus
=====

Unlike GNU Emacs and some other X applications, Epoch provides no internal support for pop-up menus or menu bar facilities.  We feel that it is more appropriate for X11 clients to depend on the window manager (or some sort of widget server) for menu support.

Two primary options exist for creating pop-up menus under Epoch: requesting the window manager (e.g., GWM) to supply them, or using an external X client (e.g., XMENU) to provide them.  Examples of each method are available in contributed Elisp code (see Packages).

GWM
---

GWM (Generic Window Manager) is an Emacs-like window manager in that it provides a basic kernel of window-managing facilities written in C and a Lisp level for extensive user customization.  GWM is part of the X11 release (the most recent version is always available via anonymous ftp from export.lcs.mit.edu).

In GWM, one can attach state machines to objects (such as X windows) in GWM, and these can then receive and handle events.  GWM can receive and initiate property change events, as can Epoch, so this provides the basis for communication between the two.

GWM also provides the ability to decorate windows with up to four bars (one on each side, top and bottom).  Each bar can have ``plugs'' (icons) which can have specialized state machines attached.  This allows one to have title bars, bars with pulldown menus, etc., all maintained by GWM, but with communication to Epoch allowing selections to be communicated.

GWM is easily tailored to emulate other window managers and comes with reasonable emulations of MWM and TWM as well as a ``home-grown'' look-and-feel, so most users can use it as a replacement for previous managers quite easily.

The interested reader should see the GWM documentation for more details.

XMENU
-----

XMENU is a toolkit program which produces a popup menu taking command-line arguments as menu entries.  It is possible to execute XMENU as a process from Epoch (or GNU Emacs) and wait for the process output.