@setfilename ../info/basics
@node General Information, Screens, Introduction, top
@chapter General Information

@menu
* Getting Started::		Getting Started
* New Features::		New Features
* Key Bindings::		Key Bindings
* Conventions::			Conventions
* GWM::				GWM
@end menu

@node Getting Started, New Features, General Information, General Information
@section 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. It opens it own X windows, so it
should be run in background.  One immediately noticable difference is
that Epoch always creates @i{two} windows by default, one for the
minibuffer and one for the initial edit buffer.  More on this below
(@xref{New Features}).

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

@menu
* X Window Program Defaults::   X Window Program Defaults
* Command Line Options::	Command Line Options
@end menu

@node X Window Program Defaults, Command Line Options, Getting Started, Getting Started
@subsection X Window Program Defaults

@cindex X Window program defaults
@cindex default sets
Epoch reads the default values associated with X Window programs, or 
@dfn{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 
@dfn{default-set}, which is initially filled in with hard-wired defaults
(which are listed below).  

The resulting global @dfn{default-set} is stored, and remains static 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.)  @xref{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:

@findex app-defaults
@findex $HOME/.Xdefaults
@findex XENVIRONMENT
@findex $HOME/.Xdefaults-<hostname>
@findex xrdb
@cindex X resources database
@cindex defaults in command line options
@cindex XAPPLRESDIR

@enumerate
@item  
Hard-wired X defaults (see below).

@item
<resource-name> or <class-name> in either /usr/lib/X11/app-defaults or $XAPPLRESDIR

@item 
$HOME/.Xdefaults

@item 
File named by the environment variable $XENVIRONMENT

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

@item 
Resources database (see @file{xrdb})

@item 
Command line options

@end enumerate


@cindex X program or window resource name
@cindex X program or window class name

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 (@pxref{Command Line Options}).  

Furthermore, the @i{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.

@cindex X class 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.

@table @code

@item Option
Default Value,
Effect

@item .screen.background
@cindex screen background
White,
Edit screen background color

@item .minibuf.background
@cindex minibuffer background
White,
Minibuffer screen background color

@item .screen.border.color
@cindex screen border color
Black,
Edit screen border color

@item .minibuf.border.color
@cindex minibuffer border color
Black,
Minibuffer screen border color

@item .screen.border.width
@cindex screen border width
2,
Edit screen border width

@item .minibuf.border.width
@cindex minibuffer border width
2,
Minibuffer screen border width

@item .screen.cursor.background
@cindex screen cursor background
White,
Edit screen X cursor background color

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

@item .screen.cursor.color
@cindex screen cursor color
Black,
Edit screen text cursor color

@item .minibuf.cursor.color
@cindex minibuffer cursor color
Black,
Minibuffer screen text cursor color

@item .screen.cursor.foreground
@cindex screen cursor foreground
Black,
Edit screen X cursor foreground color

@item .minibuf.cursor.foreground
@cindex minibuffer cursor foreground
Black,
Minibuffer screen X cursor foreground color

@item .screen.cursor.glyph
@cindex screen cursor glyph
86,
Edit screen X cursor glyph

@item .minibuf.cursor.glyph
@cindex minibuffer cursor glyph
86,
Minibuffer screen X cursor glyph

@item .screen.internal.border.width
@cindex screen internal border width
2,
Edit screen internal border width

@item .minibuf.internal.border.width
@cindex minibuffer internal border width
2,
Minibuffer screen internal border width

@item .screen.class
@cindex screen class
<special>,
Resource class of the edit screen

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

@item .display
@cindex X Window display
"",
X Window display

@item .motion
@cindex motion events
Off,
Whether motion-hints should come through to elisp

@item .screen.font
@cindex screen font
"fixed",
Edit screen font

@item .minibuf.font
@cindex minibuffer font
"fixed",
Minibuffer screen font

@item .screen.foreground
@cindex screen foreground
Black,
Edit screen foreground color

@item .minibuf.foreground
@cindex minibuffer foreground
Black,
Minibuffer screen foreground color

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

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

@item .screen.name
@cindex screen name
@cindex screen title
"Edit",
Name of the edit screen

@item .minibuf.name
@cindex minibuffer name
@cindex minibuffer title
"Minibuffer",
Name of the minibuffer screen

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

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

@item .screen.reverse
@cindex screen reverse
False,
Reverse colors for edit screen

@item .minibuf.reverse
@cindex minibuffer reverse
False,
Reverse colors for minibuffer screen

@item .screen.icon.name
@cindex screen icon name
"",
Icon Name

@end table

@node Command Line Options,  , X Window Program Defaults, Getting Started
@subsection Command Line Options

@cindex command line options
Epoch also accepts command line options. These 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 (@pxref{X Window Program Defaults} for how the name
and class are used).


@group
@table @code

@item Option
Resource,
Effect

@item -bg
@cindex background color
*background,
Sets background colors

@item -background
*background,
Sets background colors

@item -fg
@cindex foreground color
*foreground,
Sets foreground color

@item -foreground
*foreground,
Sets foreground color

@item -geometry
@cindex screen geometry
*screen.geometry,
Sets X-window geometry

@item -fn
@cindex font
*font,
Sets the font

@item -font
*font,
Sets the font

@item -wn
@cindex window title
*name,
Sets the X-window title

@item -window
*name,
Sets the X-window title

@item -d
@cindex X window display
*display,
Sets the display to use

@item -display
*display,
Sets the display to use

@item -r
@cindex reverse colors
*reverse,
Reverses foreground / background colors (no argument)

@item -rn
@cindex resource name
NA,
Sets the resource name

@item -resource
NA,
Sets the resource name

@item -cn
@cindex resource class
NA,
Sets the resource class

@item -class
NA,
Sets the resource class

@item -motion
@cindex motion events
*motion,
Turns on passing motion events to elisp for all
screens

@item -xrm
@cindex resource manager
NA,
Overrides a resource manager value

@end table
@end group


@node New Features, Key Bindings, Getting Started, General Information
@section 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  @dfn{screen} will mean an X-window, and
@dfn{window} will refer to an editor window to avoid confusion.
In most cases, working within a screen works the same as in GNU Emacs.

Epoch supports two types of screens:  @dfn{edit screens} and
@dfn{minibuffer screens}. There is always exactly one minibuffer screen.
The number of edit screens can change, but there is always at least one.
A single edit screen and the minibuffer screen together act very similarly
to normal GNU Emacs.

At any time there is a single @dfn{selected screen}, similar to having
a selected window. This can also be called the @dfn{current screen}.
Standard window functions work, but only apply to the current screen.
E.g., @code{one-window-p} returns non-@code{nil} if there is only one
window on the current screen. Buffers are shared among all screens, so
any buffer in any window can be accessed, and will show up in buffer
lists.  Killing buffers removes them from all windows.

Buttons are regions of text in a buffer than can have data attached to
them and be displayed in different colors than surrounding text.
Buttons provide both the ability to do highlighting and also to
attach data to text regions that can be retrieved based on buffer
location.

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


@node Key Bindings, Conventions, New Features, General Information
@section Key Bindings

@cindex key bindings
We provide a large range of useful functions to create, delete and
change the attributes of screens (including changing colors, size, etc).
We provide a default set of key bindings to these functions, shown
below.  The basic idea was to take the @key{C-X} binding for Emacs
window and buffer operations, and provide analogs for screen operations
using @key{C-Z} as the prefix key.  (We use @key{C-Z} because a suspend
operator is not all that useful in a multi-window environment, and
anyway @key{C-X} @key{C-Z} still provides the same effect as the
standard.)  We do not believe we have a full set of bindings yet, and
look forward to user contributions.

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

@group

@kindex C-Z
@table @key
@item Key
Functionality

@item c-Z 4 F
@code{find-file-other-screen}
Find a file in another screen.  Prompts for a filename.  If it is
already in a window on a screen, warp the cursor there, otherwise create
a new screen and edit the file in it.

@item c-Z 4 b
@code{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, warp the cursor there, otherwise
create a new screen with one window for the buffer.

@item c-Z 0
@code{remove-screen}
Delete current screen.

@item c-Z o
@code{switch-screen}
Circulate through mapped screens in forwards direction.

@item C-Z p
@code{prev-switch-screen}
Circulate through mapped screens in reverse direction.

@item c-Z 2
@code{duplicate-screen}
Duplicate current screen.

@item c-Z r
@code{raise-current-screen}
Raise current screen

@item c-Z l
@code{lower-current-screen}
Lower current screen

@item c-Z m
@code{raise-minibuf}
Raise minibuffer screen

@item c-Z i
@code{iconify-screen}
Iconify current screen

@item C-z a
Force update of title bar for current screen

@item C-z e
@code{display-event-status}
Display event handler status

@end table
@end group


@node Conventions, GWM, Key Bindings, General Information
@section Conventions

Several conventions are used in the following chapters.

@itemize @bullet

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

@item 
@cindex screen ID or screen object
Any @var{screen} argument can be a screen ID or a screen object.
Optional screen arguments default to the current screen.

@item 
@cindex color vector or string
Any @var{color} argument can be an X Resource of type X-Cardinal
@xref{X Resources}, a vector or a string.  Strings and vectors are to 
X-Cardinals converted internally.

@end itemize

@findex epoch::
We wanted to keep the necessary modifications to the underlying C
substrate of GNU Emacs to a minimum.  Therefore, each epoch primitive 
has a leading @samp{@code{epoch::}} in a fashion reminiscent of Common 
Lisp packages, e.g., @code{epoch::create-screen}.  The point is that we 
want to build around these functions at the elisp level, so we deliberately 
make the primitives uncomfortable to use.  The files @file{wrapper.el} and 
@file{epoch.el} provide a full set of wrappers that remove the 
@samp{@code{epoch::}} leading characters and add additional 
functionality (e.g. there is a function @code{create-screen} that 
provides a higher-level interface to the primitives).  If you are going 
to write your own elisp code you should probably use these wrapper 
functions, not the raw primitives.


@node GWM,  , Conventions, General Information
@section GWM

@cindex GWM
@cindex generic window manager
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 up-to-date version is always available from
@file{expo.lcs.mit.edu}).

One can attach state machines to objects (such as X-windows) in GWM, and
these then receive and handle events.  GWM can receive and initiate
property change events, and so 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 not by the
client, but with communication allowing selections to be communicated.  

The effect of this is that we have not provided any widget facilities in
Epoch as we believe the desired effect can be gained more efficiently by
using the GWM approach.  

Fortunately, 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.
