XEmacs 21.2.39 "Millennium".

[chise/xemacs-chise.git.1] / info / xemacs.info-2

This is ../info/xemacs.info, produced by makeinfo version 4.0 from
xemacs/xemacs.texi.

INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
* XEmacs: (xemacs).             XEmacs Editor.
END-INFO-DIR-ENTRY

   This file documents the XEmacs editor.

   Copyright (C) 1985, 1986, 1988 Richard M. Stallman.  Copyright (C)
1991, 1992, 1993, 1994 Lucid, Inc.  Copyright (C) 1993, 1994 Sun
Microsystems, Inc.  Copyright (C) 1995 Amdahl Corporation.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
General Public License" are included exactly as in the original, and
provided that the entire resulting derived work is distributed under the
terms of a permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the sections entitled "The GNU Manifesto",
"Distribution" and "GNU General Public License" may be included in a
translation approved by the author instead of in the original English.

\1f
File: xemacs.info,  Node: Mode Line,  Next: GUI Components,  Prev: Echo Area,  Up: Frame

The Mode Line
=============

   Each text window's last line is a "mode line" which describes what is
going on in that window.  When there is only one text window, the mode
line appears right above the echo area.  The mode line is in inverse
video if the terminal supports that, starts and ends with dashes, and
contains text like `XEmacs: SOMETHING'.

   If a mode line has something else in place of `XEmacs: SOMETHING',
the window above it is in a special subsystem such as Dired.  The mode
line then indicates the status of the subsystem.

   Normally, the mode line has the following appearance:

     --CH-XEmacs: BUF      (MAJOR MINOR)----POS------

This gives information about the buffer being displayed in the window:
the buffer's name, what major and minor modes are in use, whether the
buffer's text has been changed, and how far down the buffer you are
currently looking.

   CH contains two stars (`**') if the text in the buffer has been
edited (the buffer is "modified"), or two dashes (`--') if the buffer
has not been edited.  Exception: for a read-only buffer, it is `%%'.

   BUF is the name of the window's chosen "buffer".  The chosen buffer
in the selected window (the window that the cursor is in) is also
XEmacs's selected buffer, the buffer in which editing takes place.  When
we speak of what some command does to "the buffer", we mean the
currently selected buffer.  *Note Buffers::.

   POS tells you whether there is additional text above the top of the
screen or below the bottom.  If your file is small and it is completely
visible on the screen, POS is `All'.  Otherwise, POS is `Top' if you
are looking at the beginning of the file, `Bot' if you are looking at
the end of the file, or `NN%', where NN is the percentage of the file
above the top of the screen.

   MAJOR is the name of the "major mode" in effect in the buffer.  At
any time, each buffer is in one and only one major mode.  The available
major modes include Fundamental mode (the least specialized), Text
mode, Lisp mode, and C mode.  *Note Major Modes::, for details on how
the modes differ and how you select one.

   MINOR is a list of some of the "minor modes" that are turned on in
the window's chosen buffer.  For example, `Fill' means that Auto Fill
mode is on.  `Abbrev' means that Word Abbrev mode is on.  `Ovwrt' means
that Overwrite mode is on.  *Note Minor Modes::, for more information.
`Narrow' means that the buffer being displayed has editing restricted
to only a portion of its text.  This is not really a minor mode, but is
like one.  *Note Narrowing::.  `Def' means that a keyboard macro is
being defined.  *Note Keyboard Macros::.

   Some buffers display additional information after the minor modes.
For example, Rmail buffers display the current message number and the
total number of messages.  Compilation buffers and Shell mode display
the status of the subprocess.

   If XEmacs is currently inside a recursive editing level, square
brackets (`[...]') appear around the parentheses that surround the
modes.  If XEmacs is in one recursive editing level within another,
double square brackets appear, and so on.  Since information on
recursive editing applies to XEmacs in general and not to any one
buffer, the square brackets appear in every mode line on the screen or
not in any of them.  *Note Recursive Edit::.

   XEmacs can optionally display the time and system load in all mode
lines.  To enable this feature, type `M-x display-time'.  The
information added to the mode line usually appears after the file name,
before the mode names and their parentheses.  It looks like this:

     HH:MMpm L.LL [D]

(Some fields may be missing if your operating system cannot support
them.)  HH and MM are the hour and minute, followed always by `am' or
`pm'.  L.LL is the average number of running processes in the whole
system recently.  D is an approximate index of the ratio of disk
activity to CPU activity for all users.

   The word `Mail' appears after the load level if there is mail for
you that you have not read yet.

   Customization note: the variable `mode-line-inverse-video' controls
whether the mode line is displayed in inverse video (assuming the
terminal supports it); `nil' means no inverse video.  The default is
`t'.  For X frames, simply set the foreground and background colors
appropriately.

\1f
File: xemacs.info,  Node: GUI Components,  Next: XEmacs under X,  Prev: Mode Line,  Up: Frame

GUI Components
==============

   When executed in a graphical windowing environment such as the X
Window System or Microsoft Windows, XEmacs displays several graphical
user interface components such as scrollbars, menubars, toolbars, and
gutters.  By default there is a vertical scrollbar at the right of each
frame, and at the top of the frame there is a menubar, a toolbar, and a
gutter, in that order.  Gutters can contain any of several widgets, but
the default configuration puts a set of "notebook tabs" which you can
use as a shortcut for selecting any of several related buffers in a
given frame.  Operating the GUI components is "obvious":  click on the
menubar to pull down a menu, on a button in the toolbar to invoke a
function, and on a tab in the gutter to switch buffers.

* Menu:

* Menubar Basics::      How XEmacs uses the menubar.
* Scrollbar Basics::    How XEmacs uses scrollbars.
* Toolbar Basics::      How XEmacs uses toolbars.
* Gutter Basics::       How XEmacs uses gutters.
* Inhibiting::          What if you don't like GUI?
* Customizing::         Position, orientation, and appearance of GUI objects.

\1f
File: xemacs.info,  Node: Menubar Basics,  Next: Scrollbar Basics,  Up: GUI Components

The XEmacs Menubar
==================

   The XEmacs menubar is intended to be conformant to the usual
conventions for menubars, although conformance is not yet perfect.  The
menu at the extreme right is the `Help' menu, which should always be
available.  It provides access to all the XEmacs help facilities
available through `C-h', as well as samples of various configuration
files like `~/.Xdefaults' and `~/.emacs'.  At the extreme left is the
`Files' menu, which provides the usual file reading, writing, and
printing operations, as well as operations like revert buffer from most
recent save.  The next menu from the left is the `Edit' menu, which
provides the `Undo' operation as well as cutting and pasting,
searching, and keyboard macro definition and execution.

   XEmacs provides a very dynamic environment, and the Lisp language
makes for highly flexible applications.  The menubar reflects this:
many menus (eg, the `Buffers' menu, *note Buffers Menu::) contain items
determined by the current state of XEmacs, and most major modes and many
minor modes add items to menus and even whole menus to the menubar.  In
fact, some applications like w3.el and VM provide so many menus that
they define a whole new menubar and add a button that allows convenient
switching between the "XEmacs menubar" and the "application menubar".
Such applications normally bind themselves to a particular frame, and
this switching only takes place on frames where such an application is
active (ie, the current window of the frame is displaying a buffer in
the appropriate major mode).

   Other menus which are typically available are the `Options',
`Tools', `Buffers', `Apps', and `Mule' menus.  For detailed
descriptions of these menus, *Note Pull-down Menus::.  (In 21.2
XEmacsen, the `Mule' menu will be moved under `Options'.)

\1f
File: xemacs.info,  Node: Scrollbar Basics,  Next: Toolbar Basics,  Prev: Menubar Basics,  Up: GUI Components

XEmacs Scrollbars
=================

   XEmacs scrollbars provide the usual interface.  Arrow buttons at
either end allow for line by line scrolling, including autorepeat.
Clicking in the scrollbar itself provides scrolling by windowsfull,
depending on which side of the slider is clicked.  The slider itself
may be dragged for smooth scrolling.

   The position of the slider corresponds to the position of the window
in the buffer.  In particular, the length of the slider is proportional
to the fraction of the buffer which appears in the window.

   The presence of the scrollbars is under control of the application or
may be customized by the user.  By default a vertical scrollbar is
present in all windows (except the minibuffer), and there is no
horizontal scrollbar.

\1f
File: xemacs.info,  Node: Toolbar Basics,  Next: Gutter Basics,  Prev: Scrollbar Basics,  Up: GUI Components

XEmacs Toolbars
===============

   XEmacs has a default toolbar which provides shortcuts for some of the
commonly used operations (such as opening files) and applications (such
as the Info manual reader).  Operations which require arguments will pop
up dialogs to get them.

   The position of the default toolbar can be customized.  Also, several
toolbars may be present simultaneously (in different positions).  VM,
for example, provides an application toolbar which shortcuts for
mail-specific operations like sending, saving, and deleting messages.

\1f
File: xemacs.info,  Node: Gutter Basics,  Next: Inhibiting,  Prev: Toolbar Basics,  Up: GUI Components

XEmacs Gutters
==============

   Gutters are the most flexible of the GUI components described in this
section.  In theory, the other GUI components could be implemented by
customizing a gutter, but in practice the other components were
introduced earlier and have their own special implementations.  Gutters
tend to be more transient than the other components.  Buffer tabs, for
example, change every time the selected buffer in the frame changes.
And for progress gauges a gutter to contain the gauge is typically
created on the fly when needed, then destroyed when the operation whose
staus is being displayed is completed.

   Buffer tabs, having somewhat complex behavior, deserve a closer look.
By default, a row of buffer tabs is displayed at the top of every frame.
(The tabs could be placed in the bottom gutter, but would be oriented
the same way and look rather odd.  The horizontal orientation makes
putting them in a side gutter utterly impractical.)  The buffer
displayed in the current window of a frame can be changed to a specific
buffer by clicking [mouse-1] on the corresponding tab in the gutter.

   Each tab contains the name of its buffer.  The tab for the current
buffer in each frame is displayed in raised relief.  The list of buffers
chosen for display in the buffer tab row is derived by filtering the
buffer list (like the `Buffers' menu).  The list starts out with all
existing buffers, with more recently selected buffers coming earlier in
the list.

   Then "uninteresting" buffers, like internal XEmacs buffers, the
`*Message Log*' buffer, and so on are deleted from the list.  Next, the
frame's selected buffer is determined.  Buffers with a different major
mode from the selected buffer are removed from the list.  Finally, if
the list is too long, the least recently used buffers are deleted from
the list.  By default up to 6 most recently used buffers with the same
mode are displayed on tabs in the gutter.

\1f
File: xemacs.info,  Node: Inhibiting,  Next: Customizing,  Prev: Gutter Basics,  Up: GUI Components

Inhibiting Display of GUI Components
====================================

   Use of GUI facilities is a personal thing.  Almost everyone agrees
that drawing via keyboard-based "turtle graphics" is acceptable to
hardly anyone if a mouse is available, but conversely emulating a
keyboard with a screenful of buttons is a painful experience.  But
between those extremes the complete novice will require a fair amount
of time before toolbars and menus become dispensable, but many an
"Ancien Haquer" sees them as a complete waste of precious frame space
that could be filled with text.

   Display of all of the GUI components created by XEmacs can be
inhibited through the use of Customize.  Customize can be accessed
through `Options | Customize' in the menu bar, or via `M-x customize'.
Then navigate through the Customize tree to `Emacs | Environment'.
Scrollbar and toolbar visibility is controlled via the `Display' group,
options `Scrollbars visible' and  `Toolbar visible' respectively.
Gutter visibility is controlled by group `Gutter', option `Visible'.

   Or they can be controlled directly by `M-x customize-variable', by
changing the values of the variables `menubar-visible-p',
`scrollbars-visible-p', `toolbar-visible-p', or
`gutter-buffers-tab-visible-p' respectively.  (The strange form of the
last variable is due to the fact that gutters are often used to display
transient widgets like progress gauges, which you probably don't want
to inhibit.  It is more likely that you want to inhibit the default
display of the buffers tab widget, which is what that variable controls.
This interface is subject to change depending on developer experience
and user feedback.)

   Control of frame configuration can controlled automatically
according to various parameters such as buffer or frame because these
are "specifiers" *Note Specifiers: (lispref)Specifiers.  Using these
features requires programming in Lisp; Customize is not yet that
sophisticated.  Also, components that appear in various positions and
orientations can have display suppressed according to position.  `C-h a
visible-p' gives a list of variables which can be customized.  E.g., to
control the visibility of specifically the left-side toolbar only,
customize `left-toolbar-visible-p'.

\1f
File: xemacs.info,  Node: Customizing,  Prev: Inhibiting,  Up: GUI Components

Changing the Position, Orientation, and Appearance of GUI Components
====================================================================

   #### Not documented yet.

\1f
File: xemacs.info,  Node: XEmacs under X,  Next: XEmacs under MS Windows,  Prev: GUI Components,  Up: Frame

Using XEmacs Under the X Window System
======================================

   XEmacs can be used with the X Window System and a window manager like
MWM or TWM.  In that case, the X window manager opens, closes, and
resizes XEmacs frames.  You use the window manager's mouse gestures to
perform the operations.  Consult your window manager guide or reference
manual for information on manipulating X windows.

   When you are working under X, each X window (that is, each XEmacs
frame) has a menu bar for mouse-controlled operations (*note Pull-down
Menus::).

   XEmacs under X is also a multi-frame XEmacs.  You can use the New
Frame menu item from the File menu to create a new XEmacs frame in a
new X window from the same process.  The different frames will share the
same buffer list, but you can look at different buffers in the different
frames.

   The function `find-file-other-frame' is just like `find-file', but
creates a new frame to display the buffer in first.  This is normally
bound to `C-x 5 C-f', and is what the Open File, New Frame menu item
does.

   The function `switch-to-buffer-other-frame' is just like
`switch-to-buffer', but creates a new frame to display the buffer in
first.  This is normally bound to `C-x 5 b'.

   You can specify a different default frame size other than the one
provided.  Use the variable `default-frame-alist', which is an alist of
default values for frame creation other than the first one.  These may
be set in your init file, like this:

       (setq default-frame-alist '((width . 80) (height . 55)))

   For values specific to the first XEmacs frame, you must use X
resources.  The variable `x-frame-defaults' takes an alist of default
frame creation parameters for X window frames.  These override what is
specified in `~/.Xdefaults' but are overridden by the arguments to the
particular call to `x-create-frame'.

   When you create a new frame, the variable `create-frame-hook' is
called with one argument, the frame just created.

   If you want to close one or more of the X windows you created using
New Frame, use the Delete Frame menu item from the File menu.

   If you are working with multiple frames, some special information
applies:
   * Two variables, `frame-title-format' and `frame-icon-title-format'
     determine the title of the frame and the title of the icon that
     results if you shrink the frame.

   * The variables `auto-lower-frame' and `auto-raise-frame' position a
     frame. If true, `auto-lower-frame' lowers a frame to the bottom
     when it is no longer selected. If true, `auto-raise-frame' raises
     a frame to the top when it is selected. Under X, most
     ICCCM-compliant window managers will have options to do this for
     you, but these variables are provided in case you are using a
     broken window manager.

   * There is a new frame/modeline format directive, %S, which expands
     to the name of the current frame (a frame's name is distinct from
     its title; the name is used for resource lookup, among other
     things, and the title is simply what appears above the window.)

\1f
File: xemacs.info,  Node: XEmacs under MS Windows,  Prev: XEmacs under X,  Up: Frame

Using XEmacs Under Microsoft Windows
====================================

   Use of XEmacs under MS Windows is not separately documented here, but
most operations available under the X Window System are also available
with MS Windows.

   Where possible, native MS Windows GUI components and capabilities are
used in XEmacs.

\1f
File: xemacs.info,  Node: Keystrokes,  Next: Pull-down Menus,  Prev: Frame,  Up: Top

Keystrokes, Key Sequences, and Key Bindings
*******************************************

* Menu:

* Intro to Keystrokes::      Keystrokes as building blocks of key sequences.
* Representing Keystrokes::  Using lists of modifiers and keysyms to
                             represent keystrokes.
* Key Sequences::            Combine key strokes into key sequences you can
                             bind to commands.
* String Key Sequences::     Available for upward compatibility.
* Meta Key::                 Using <ESC> to represent <Meta>
* Super and Hyper Keys::     Adding modifier keys on certain keyboards.
* Character Representation:: How characters appear in Emacs buffers.
* Commands::                 How commands are bound to key sequences.

\1f
File: xemacs.info,  Node: Intro to Keystrokes,  Next: Representing Keystrokes,  Prev: Keystrokes,  Up: Keystrokes

Keystrokes as Building Blocks of Key Sequences
==============================================

   Earlier versions of Emacs used only the ASCII character set, which
defines 128 different character codes.  Some of these codes are
assigned graphic symbols like `a' and `='; the rest are control
characters, such as `Control-a' (also called `C-a').  `C-a' means you
hold down the <CTRL> key and then press `a'.

   Keybindings in XEmacs are not restricted to the set of keystrokes
that can be represented in ASCII.  XEmacs can tell the difference
between, for example, `Control-h', `Control-Shift-h', and `Backspace'.

   A keystroke is like a piano chord: you get it by simultaneously
striking several keys.  To be more precise, a keystroke consists of a
possibly empty set of modifiers followed by a single "keysym".  The set
of modifiers is small; it consists of `Control', `Meta', `Super',
`Hyper', and `Shift'.

   The rest of the keys on your keyboard, along with the mouse buttons,
make up the set of keysyms.  A keysym is usually what is printed on the
keys on your keyboard.  Here is a table of some of the symbolic names
for keysyms:
`a,b,c...'
     alphabetic keys

`f1,f2...'
     function keys

`button1'
     left mouse button

`button2'
     middle mouse button

`button3'
     right mouse button

`button1up'
     upstroke on the left mouse button

`button2up'
     upstroke on the middle mouse button

`button3up'
     upstroke on the right mouse button

`return'
     Return key

   Use the variable `keyboard-translate-table' only if you are on a
dumb tty, as it cannot handle input that cannot be represented as ASCII.
The value of this variable is a string used as a translate table for
keyboard input or `nil'.  Each character is looked up in this string
and the contents used instead.  If the string is of length `n',
character codes `N' and up are untranslated.  If you are running Emacs
under X, you should do the translations with the `xmodmap' program
instead.

\1f
File: xemacs.info,  Node: Representing Keystrokes,  Next: Key Sequences,  Prev: Intro to Keystrokes,  Up: Keystrokes

Representing Keystrokes
-----------------------

   XEmacs represents keystrokes as lists. Each list consists of an
arbitrary combination of modifiers followed by a single keysym at the
end of the list.  If the keysym corresponds to an ASCII character, you
can use its character code.  (A keystroke may also be represented by an
event object, as returned by the `read-key-sequence' function;
non-programmers need not worry about this.)

   The following table gives some examples of how to list
representations for keystrokes.  Each list consists of sets of
modifiers followed by keysyms:

`(control a)'
     Pressing <CTRL> and `a' simultaneously.

`(control ?a)'
     Another way of writing the keystroke `C-a'.

`(control 65)'
     Yet another way of writing the keystroke `C-a'.

`(break)'
     Pressing the <BREAK> key.

`(control meta button2up)'
     Release the middle mouse button, while pressing <CTRL> and <META>.
 Note: As you define keystrokes, you can use the `shift' key only as a
modifier with characters that do not have a second keysym on the same
key, such as `backspace' and `tab'.  It is an error to define a
keystroke using the <shift> modifier with keysyms such as `a' and `='.
The correct forms are `A' and `+'.

\1f
File: xemacs.info,  Node: Key Sequences,  Next: String Key Sequences,  Prev: Representing Keystrokes,  Up: Keystrokes

Representing Key Sequences
--------------------------

   A "complete key sequence" is a sequence of keystrokes that Emacs
understands as a unit.  Key sequences are significant because you can
bind them to commands.  Note that not all sequences of keystrokes are
possible key sequences.  In particular, the initial keystrokes in a key
sequence must make up a "prefix key sequence".

   Emacs represents a key sequence as a vector of keystrokes.  Thus, the
schematic representation of a complete key sequence is as follows:

       [(modifier .. modifier keysym) ... (modifier .. modifier keysym)]

   Here are some examples of complete key sequences:

`[(control c) (control a)]'
     Typing `C-c' followed by `C-a'

`[(control c) (control 65)]'
     Typing `C-c' followed by `C-a'. (Using the ASCII code for the
     character `a')

`[(control c) (break)]'
     Typing `C-c' followed by the `break' character.

   A "prefix key sequence" is the beginning of a series of longer
sequences that are valid key sequences; adding any single keystroke to
the end of a prefix results in a valid key sequence.  For example,
`control-x' is standardly defined as a prefix.  Thus there is a
two-character key sequence starting with `C-x' for each valid
keystroke, giving numerous possibilities.  Here are some samples:

   * `[(control x) (c)]'

   * `[(control x) (control c)]'

   Adding one character to a prefix key does not have to form a complete
key.  It could make another, longer prefix.  For example, `[(control x)
(\4)]' is itself a prefix that leads to any number of different
three-character keys, including `[(control x) (\4) (f)]', `[(control x)
(\4) (b)]' and so on.  It would be possible to define one of those
three-character sequences as a prefix, creating a series of
four-character keys, but we did not define any of them this way.

   By contrast, the two-character sequence `[(control f) (control k)]'
is not a key, because the `(control f)' is a complete key sequence in
itself.  You cannot give `[(control f (control k)]' an independent
meaning as a command while `(control f)' is a complete sequence,
because Emacs would understand <C-f C-k> as two commands.

   The predefined prefix key sequences in Emacs are `(control c)',
`(control x)', `(control h)', `[(control x) (\4)]', and `escape'.  You
can customize Emacs and could make new prefix keys or eliminate the
default key sequences.  *Note Key Bindings::.  For example, if you
redefine `(control f)' as a prefix, `[(control f) (control k)]'
automatically becomes a valid key sequence (complete, unless you define
it as a prefix as well).  Conversely, if you remove the prefix
definition of `[(control x) (\4)]', `[(control x) (\4) (f)]' (or
`[(control x) (\4) ANYTHING]') is no longer a valid key sequence.

   Note that the above paragraphs uses \4 instead of simply 4, because
\4 is the symbol whose name is "4", and plain 4 is the integer 4, which
would have been interpreted as the ASCII value.  Another way of
representing the symbol whose name is "4" is to write ?4, which would be
interpreted as the number 52, which is the ASCII code for the character
"4".  We could therefore actually have written 52 directly, but that is
far less clear.

\1f
File: xemacs.info,  Node: String Key Sequences,  Next: Meta Key,  Prev: Key Sequences,  Up: Keystrokes

String Key Sequences
--------------------

   For backward compatibility, you may also represent a key sequence
using strings.  For example, we have the following equivalent
representations:

`"\C-c\C-c"'
     `[(control c) (control c)]'

`"\e\C-c"'
     `[(meta control c)]'

\1f
File: xemacs.info,  Node: Meta Key,  Next: Super and Hyper Keys,  Prev: String Key Sequences,  Up: Keystrokes

Assignment of the <META> Key
----------------------------

   Not all terminals have the complete set of modifiers.  Terminals
that have a <Meta> key allow you to type Meta characters by just
holding that key down.  To type `Meta-a', hold down <META> and press
`a'.  On those terminals, the <META> key works like the <SHIFT> key.
Such a key is not always labeled <META>, however, as this function is
often a special option for a key with some other primary purpose.

   If there is no <META> key, you can still type Meta characters using
two-character sequences starting with <ESC>.  To enter `M-a', you could
type `<ESC> a'.  To enter `C-M-a', you would type `ESC C-a'.  <ESC> is
allowed on terminals with Meta keys, too, in case you have formed a
habit of using it.

   If you are running under X and do not have a <META> key, it is
possible to reconfigure some other key to be a <META> key.  *Note Super
and Hyper Keys::.

   Emacs believes the terminal has a <META> key if the variable
`meta-flag' is non-`nil'.  Normally this is set automatically according
to the termcap entry for your terminal type.  However, sometimes the
termcap entry is wrong, and then it is useful to set this variable
yourself.  *Note Variables::, for how to do this.

   Note: If you are running under the X window system, the setting of
the `meta-flag' variable is irrelevant.

\1f
File: xemacs.info,  Node: Super and Hyper Keys,  Next: Character Representation,  Prev: Meta Key,  Up: Keystrokes

Assignment of the <SUPER> and <HYPER> Keys
------------------------------------------

   Most keyboards do not, by default, have <SUPER> or <HYPER> modifier
keys.  Under X, you can simulate the <SUPER> or <HYPER> key if you want
to bind keys to sequences using `super' and `hyper'.  You can use the
`xmodmap' program to do this.

   For example, to turn your <CAPS-LOCK> key into a <SUPER> key, do the
following:

   Create a file called `~/.xmodmap'.  In this file, place the lines

             remove Lock = Caps_Lock
             keysym Caps_Lock = Super_L
             add Mod2 = Super_L

   The first line says that the key that is currently called `Caps_Lock'
should no longer behave as a "lock" key.  The second line says that
this should now be called `Super_L' instead.  The third line says that
the key called `Super_L' should be a modifier key, which produces the
`Mod2' modifier.

   To create a <META> or <HYPER> key instead of a <SUPER> key, replace
the word `Super' above with `Meta' or `Hyper'.

   Just after you start up X, execute the command `xmodmap /.xmodmap'.
You can add this command to the appropriate initialization file to have
the command executed automatically.

   If you have problems, see the documentation for the `xmodmap'
program.  The X keyboard model is quite complicated, and explaining it
is beyond the scope of this manual.  However, we reprint the following
description from the X Protocol document for your convenience:

   A list of keysyms is associated with each keycode. If that list
(ignoring trailing `NoSymbol' entries) is a single keysym `K', then the
list is treated as if it were the list ```K NoSymbol K NoSymbol'''. If
the list (ignoring trailing `NoSymbol' entries) is a pair of keysyms
`K1 K2', then the list is treated as if it were the list ```K1 K2 K1
K2'''. If the list (ignoring trailing `NoSymbol' entries) is a triple
of keysyms `K1 K2 K3', then the list is treated as if it were the list
```K1 K2 K3 NoSymbol'''.

   The first four elements of the list are split into two groups of
keysyms. Group 1 contains the first and second keysyms; Group 2 contains
third and fourth keysyms. Within each group, if the second element of
the group is NoSymbol, then the group should be treated as if the second
element were the same as the first element, except when the first
element is an alphabetic keysym `K' for which both lowercase and
uppercase forms are defined. In that case, the group should be treated
as if the first element were the lowercase form of `K' and the second
element were the uppercase form of `K'.

   The standard rules for obtaining a keysym from a KeyPress event make
use of only the Group 1 and Group 2 keysyms; no interpretation of other
keysyms in the list is given here. (That is, the last four keysyms are
unused.)

   Which group to use is determined by modifier state. Switching between
groups is controlled by the keysym named `Mode_switch'. Attach that
keysym to some keycode and attach that keycode to any one of the
modifiers Mod1 through Mod5. This modifier is called the "group
modifier". For any keycode, Group 1 is used when the group modifier is
off, and Group 2 is used when the group modifier is on.

   Within a group, which keysym to use is also determined by modifier
state. The first keysym is used when the `Shift' and `Lock' modifiers
are off. The second keysym is used when the `Shift' modifier is on, or
when the `Lock' modifier is on and the second keysym is uppercase
alphabetic, or when the `Lock' modifier is on and is interpreted as
`ShiftLock'. Otherwise, when the `Lock' modifier is on and is
interpreted as `CapsLock', the state of the `Shift' modifier is applied
first to select a keysym, but if that keysym is lower-case alphabetic,
then the corresponding upper-case keysym is used instead.

   In addition to the above information on keysyms, we also provide the
following description of modifier mapping from the InterClient
Communications Conventions Manual:

   X11 supports 8 modifier bits, of which 3 are pre-assigned to
`Shift', `Lock', and `Control'. Each modifier bit is controlled by the
state of a set of keys, and these sets are specified in a table
accessed by `GetModifierMapping()' and `SetModifierMapping()'.

   A client needing to use one of the pre-assigned modifiers should
assume that the modifier table has been set up correctly to control
these modifiers. The `Lock' modifier should be interpreted as `Caps
Lock' or `Shift Lock' according to whether the keycodes in its
controlling set include `XK_Caps_Lock' or `XK_Shift_Lock'.

   Clients should determine the meaning of a modifier bit from the
keysyms being used to control it.

   A client needing to use an extra modifier, for example `Meta',
should:

  1. Scan the existing modifier mappings.

       1. If it finds a modifier that contains a keycode whose set of
          keysyms includes `XK_Meta_L' or `XK_Meta_R', it should use
          that modifier bit.

       2. If there is no existing modifier controlled by `XK_Meta_L' or
          `XK_Meta_R', it should select an unused modifier bit (one with
          an empty controlling set) and:

  2. If there is a keycode with `XL_Meta_L' in its set of keysyms, add
     that keycode to the set for the chosen modifier, and then:

       1. If there is a keycode with `XL_Meta_R' in its set of keysyms,
          add that keycode to the set for the chosen modifier, and then:

       2. If the controlling set is still empty, interact with the user
          to select one or more keys to be `Meta'.

  3. If there are no unused modifier bits, ask the user to take
     corrective action.

   This means that the `Mod1' modifier does not necessarily mean
`Meta', although some applications (such as twm and emacs 18) assume
that. Any of the five unassigned modifier bits could mean `Meta'; what
matters is that a modifier bit is generated by a keycode which is bound
to the keysym `Meta_L' or `Meta_R'.

   Therefore, if you want to make a <META> key, the right way is to
make the keycode in question generate both a `Meta' keysym and some
previously-unassigned modifier bit.

\1f
File: xemacs.info,  Node: Character Representation,  Next: Commands,  Prev: Super and Hyper Keys,  Up: Keystrokes

Representation of Characters
============================

   This section briefly discusses how characters are represented in
Emacs buffers.  *Note Key Sequences::, for information on representing
key sequences to create key bindings.

   ASCII graphic characters in Emacs buffers are displayed with their
graphics.  <LFD> is the same as a newline character; it is displayed by
starting a new line.  <TAB> is displayed by moving to the next tab stop
column (usually every 8 spaces).  Other control characters are
displayed as a caret (`^') followed by the non-control version of the
character; thus, `C-a' is displayed as `^A'.  Non-ASCII characters 128
and up are displayed with octal escape sequences; thus, character code
243 (octal), also called `M-#' when used as an input character, is
displayed as `\243'.

   The variable `ctl-arrow' may be used to alter this behavior.  *Note
Display Vars::.

\1f
File: xemacs.info,  Node: Commands,  Prev: Character Representation,  Up: Keystrokes

Keys and Commands
=================

   This manual is full of passages that tell you what particular keys
do.  But Emacs does not assign meanings to keys directly.  Instead,
Emacs assigns meanings to "functions", and then gives keys their
meanings by "binding" them to functions.

   A function is a Lisp object that can be executed as a program.
Usually it is a Lisp symbol that has been given a function definition;
every symbol has a name, usually made of a few English words separated
by dashes, such as `next-line' or `forward-word'.  It also has a
"definition", which is a Lisp program.  Only some functions can be the
bindings of keys; these are functions whose definitions use
`interactive' to specify how to call them interactively.  Such
functions are called "commands", and their names are "command names".
More information on this subject will appear in the XEmacs Lisp
Reference Manual.

   The bindings between keys and functions are recorded in various
tables called "keymaps".  *Note Key Bindings::, for more information on
key sequences you can bind commands to.  *Note Keymaps::, for
information on creating keymaps.

   When we say  "`C-n' moves down vertically one line" we are glossing
over a distinction that is irrelevant in ordinary use but is vital in
understanding how to customize Emacs.  The function `next-line' is
programmed to move down vertically.  `C-n' has this effect because it
is bound to that function.  If you rebind `C-n' to the function
`forward-word' then `C-n' will move forward by words instead.
Rebinding keys is a common method of customization.

   The rest of this manual usually ignores this subtlety to keep things
simple.  To give the customizer the information needed, we often state
the name of the command that really does the work in parentheses after
mentioning the key that runs it.  For example, we will say that "The
command `C-n' (`next-line') moves point vertically down," meaning that
`next-line' is a command that moves vertically down and `C-n' is a key
that is standardly bound to it.

   While we are on the subject of information for customization only,
it's a good time to tell you about "variables".  Often the description
of a command will say, "To change this, set the variable `mumble-foo'."
A variable is a name used to remember a value.  Most of the variables
documented in this manual exist just to facilitate customization: some
command or other part of Emacs uses the variable and behaves
differently depending on its setting.  Until you are interested in
customizing, you can ignore the information about variables.  When you
are ready to be interested, read the basic information on variables, and
then the information on individual variables will make sense.  *Note
Variables::.

\1f
File: xemacs.info,  Node: Pull-down Menus,  Next: Entering Emacs,  Prev: Keystrokes,  Up: Top

XEmacs Pull-down Menus
======================

   If you are running XEmacs under X, a menu bar on top of the Emacs
frame provides access to pull-down menus of file, edit, and
help-related commands. The menus provide convenient shortcuts and an
easy interface for novice users.  They do not provide additions to the
functionality available via key commands; you can still invoke commands
from the keyboard as in previous versions of Emacs.

File
     Perform file and buffer-related operations, such as opening and
     closing files, saving and printing buffers, as well as exiting
     Emacs.

Edit
     Perform standard editing operations, such as cutting, copying,
     pasting, and killing selected text.

Apps
     Access to sub-applications implemented within XEmacs, such as the
     mail reader, the World Wide Web browser, the spell-checker, and
     the calendar program.

Options
     Control various options regarding the way XEmacs works, such as
     controlling which elements of the frame are visible, selecting the
     fonts to be used for text, specifying whether searches are
     case-sensitive, etc.

Buffers
     Present a menu of buffers for selection as well as the option to
     display a buffer list.

Tools
     Perform various actions designed to automate software development
     and similar technical work, such as searching through many files,
     compiling a program, and comparing or merging two or three files.

Help
     Access to Emacs Info.

   There are two ways of selecting an item from a pull-down menu:

   * Select an item in the menu bar by moving the cursor over it and
     click the left mouse-button.  Then move the cursor over the menu
     item you want to choose and click left again.

   * Select an item in the menu bar by moving the cursor over it and
     click and hold the left mouse-button.  With the mouse-button
     depressed, move the cursor over the menu item you want, then
     release it to make your selection.

   If a command in the pull-down menu is not applicable in a given
situation, the command is disabled and its name appears faded.  You
cannot invoke items that are faded.  For example, many commands on the
Edit menu appear faded until you select text on which they are to
operate; after you select a block of text, edit commands are enabled.
*Note Mouse Selection::, for information on using the mouse to select
text.  *Note Using X Selections::, for related information.

   There are also `M-x' equivalents for each menu item.  To find the
equivalent for any left-button menu item, do the following:

  1. Type `C-h k' to get the `Describe Key' prompt.

  2. Select the menu item and click.

   Emacs displays the function associated with the menu item in a
separate window, usually together with some documentation.

* Menu:

* File Menu::           Items on the File menu.
* Edit Menu::           Items on the Edit menu.
* Apps Menu::           Items on the Apps menu.
* Options Menu::        Items on the Options menu.
* Buffers Menu::        Information about the Buffers menu.
* Tools Menu::          Items on the Tools menu.
* Help Menu::           Items on the Help menu.
* Menu Customization::  Adding and removing menu items and related
                        operations.

\1f
File: xemacs.info,  Node: File Menu,  Next: Edit Menu,  Up: Pull-down Menus

The File Menu
-------------

   The File menu bar item contains the items New Frame, Open File...,
Save Buffer, Save Buffer As..., Revert Buffer, Print Buffer, Delete
Frame, Kill Buffer and Exit Emacs on the pull-down menu.  If you select
a menu item, Emacs executes the equivalent command.

Open File, New Frame...
     Prompts you for a filename and loads that file into a new buffer
     in a new Emacs frame, that is, a new X window running under the
     same Emacs process.  You can remove the frame using the Delete
     Frame menu item.  When you remove the last frame, you exit Emacs
     and are prompted for confirmation.

Open File...
     Prompts you for a filename and loads that file into a new buffer.
     Open File... is equivalent to the Emacs command `find-file' (`C-x
     C-f').

Insert File...
     Prompts you for a filename and inserts the contents of that file
     into the current buffer.  The file associated with the current
     buffer is not changed by this command.  This is equivalent to the
     Emacs command `insert-file' (`C-x i').

Save Buffer
     Writes and saves the current Emacs buffer as the latest version of
     the current visited file.  Save Buffer is equivalent to the Emacs
     command `save-buffer' (`C-x C-s').

Save Buffer As...
     Writes and saves the current Emacs buffer to the filename you
     specify.  Save Buffer As... is equivalent to the Emacs command
     `write-file' (`C-x C-w').

Revert Buffer
     Restores the last saved version of the file to the current buffer.
     When you edit a buffer containing a text file, you must save the
     buffer before your changes become effective.  Use Revert Buffer if
     you do not want to keep the changes you have made in the buffer.
     Revert Buffer is equivalent to the Emacs command `revert-file'
     (`M-x revert-buffer').

Kill Buffer
     Kills the current buffer, prompting you first if there are unsaved
     changes.  This is roughly equivalent to the Emacs command
     `kill-buffer' (`C-x k'), except that `kill-buffer' prompts for the
     name of a buffer to kill.

Print Buffer
     Prints a hardcopy of the current buffer.  Equivalent to the Emacs
     command `print-buffer' (`M-x print-buffer').

New Frame
     Creates a new Emacs frame displaying the `*scratch*' buffer.  This
     is like the Open File, New Frame... menu item, except that it does
     not prompt for or load a file.

Delete Frame
     Allows you to close all but one of the frames created by New Frame.
     If you created several Emacs frames belonging to the same Emacs
     process, you can close all but one of them.  When you attempt to
     close the last frame, Emacs informs you that you are attempting to
     delete the last frame.  You have to choose Exit Emacs for that.

Split Frame
     Divides the current window on the current frame into two
     equal-sized windows, both displaying the same buffer.  Equivalent
     to the Emacs command `split-window-vertically' (`C-x 2').

Un-split (Keep This)
     If the frame is divided into multiple windows, this removes all
     windows other than the selected one.  Equivalent to the Emacs
     command `delete-other-windows' (`C-x 1').

Un-split (Keep Others)
     If the frame is divided into multiple windows, this removes the
     selected window from the frame, giving the space back to one of the
     other windows.  Equivalent to the Emacs command `delete-window'
     (`C-x 0').

Exit Emacs
     Shuts down (kills) the Emacs process.  Equivalent to the Emacs
     command `save-buffers-kill-emacs' (`C-x C-c').  Before killing the
     Emacs process, the system asks which unsaved buffers to save by
     going through the list of all buffers in that Emacs process.

\1f
File: xemacs.info,  Node: Edit Menu,  Next: Apps Menu,  Prev: File Menu,  Up: Pull-down Menus

The Edit Menu
-------------

   The Edit pull-down menu contains the Undo, Cut, Copy, Paste, and
Clear menu items.  When you select a menu item, Emacs executes the
equivalent command.  Most commands on the Edit menu work on a block of
text, the X selection.  They appear faded until you select a block of
text (activate a region) with the mouse.  *Note Using X Selections::,
*note Killing::, and *note Yanking:: for more information.

Undo
     Undoes the previous command.  Undo is equivalent to the Emacs
     command `undo' (`C-x u').

Cut
     Removes the selected text block from the current buffer, makes it
     the X clipboard selection, and places it in the kill ring.  Before
     executing this command, you have to select a region using Emacs
     region selection commands or with the mouse.

Copy
     Makes a selected text block the X clipboard selection, and places
     it in the kill ring.  You can select text using one of the Emacs
     region selection commands or by selecting a text region with the
     mouse.

Paste
     Inserts the current value of the X clipboard selection in the
     current buffer.  Note that this is not necessarily the same as the
     Emacs `yank' command, because the Emacs kill ring and the X
     clipboard selection are not the same thing.  You can paste in text
     you have placed in the clipboard using Copy or Cut.  You can also
     use Paste to insert text that was pasted into the clipboard from
     other applications.

Clear
     Removes the selected text block from the current buffer but does
     not place it in the kill ring or the X clipboard selection.

Start Macro Recording
     After selecting this, Emacs will remember every keystroke you type
     until End Macro Recording is selected.  This is the same as the
     Emacs command `start-kbd-macro' (`C-x (').

End Macro Recording
     Selecting this tells emacs to stop remembering your keystrokes.
     This is the same as the Emacs command `end-kbd-macro' (`C-x )').

Execute Last Macro
     Selecting this item will cause emacs to re-interpret all of the
     keystrokes which were saved between selections of the Start Macro
     Recording and End Macro Recording menu items.  This is the same as
     the Emacs command `call-last-kbd-macro' (`C-x e').

\1f
File: xemacs.info,  Node: Apps Menu,  Next: Options Menu,  Prev: Edit Menu,  Up: Pull-down Menus

The Apps Menu
-------------

   The Apps pull-down menu contains the Read Mail (VM)..., Read Mail
(MH)..., Send Mail..., Usenet News, Browse the Web, Gopher, Spell-Check
Buffer and Emulate VI menu items, and the Calendar and Games sub-menus.
When you select a menu item, Emacs executes the equivalent command.
For some of the menu items, there are sub-menus which you will need to
select.