--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/xemacs/frame.texi	Mon Aug 13 08:45:50 2007 +0200
@@ -0,0 +1,340 @@
+@node Frame, Keystrokes, Concept Index, Top
+@comment  node-name,  next,  previous,  up
+@chapter The XEmacs Frame
+@cindex frame
+@cindex window
+@cindex buffer
+
+@table @asis
+@item Frame
+In many environments, such as a tty terminal, an XEmacs frame
+literally takes up the whole screen.  If you are
+running XEmacs in a multi-window system like the X Window System, the
+XEmacs frame takes up one X window.  @xref{XEmacs under X}, for more
+information.@refill
+
+@item Window
+No matter what environment you are running in, XEmacs allows you to look
+at several buffers at the same time by having several windows be part of
+the frame.  Often, the whole frame is taken up by just one window, but
+you can split the frame into two or more subwindows.  If you are
+running XEmacs under the X window system, that means you can have several
+@dfn{XEmacs windows} inside the X window that contains the XEmacs frame.
+You can even have multiple frames in different X windows, each with
+their own set of subwindows. 
+@refill
+@end table
+
+Each XEmacs frame displays a variety of information: 
+@itemize @bullet
+@item
+The biggest area usually displays the text you are editing.  It may
+consist of one window or of two or more windows if you need to look at two
+buffers a the same time. 
+@item
+Below each text window's last line is a @dfn{mode line} (@pxref{Mode
+Line}), which describes what is going on in that window.  The mode line
+is in inverse video if the terminal supports that.  If there are several
+XEmacs windows in one frame, each window has its own mode line.
+@item
+At the bottom of each XEmacs frame is the @dfn{echo area} or @dfn{minibuffer
+window}(@pxref{Echo Area}).  It is used by XEmacs to exchange information
+with the user.  There is only one echo area per XEmacs frame.
+@item
+If you are running XEmacs under the X Window System, a
+menu bar at the top of the frame makes shortcuts to several of the
+commands available (@pxref{Pull-down Menus}).
+@end itemize
+
+  You can subdivide the XEmacs frame into multiple text windows, and use
+each window for a different file (@pxref{Windows}).  Multiple XEmacs
+windows are tiled vertically on the XEmacs frame.  The upper XEmacs window
+is separated from the lower window by its mode line.
+
+  When there are multiple, tiled XEmacs windows on a single XEmacs frame,
+the XEmacs window receiving input from the keyboard has the @dfn{keyboard
+focus} and is called the @dfn{selected window}.  The selected window
+contains the cursor, which indicates the insertion point.  If you are
+working in an environment that permits multiple XEmacs frames, and you
+move the focus from one XEmacs frame into another, the
+selected window is the one that was last selected in that frame.
+
+  The same text can be displayed simultaneously in several XEmacs
+windows, which can be in different XEmacs frames.  If you alter the text
+in an XEmacs buffer by editing it in one XEmacs window, the changes are
+visible in all XEmacs windows containing that buffer.
+
+
+@menu
+* Point::	        The place in the text where editing commands operate.  
+* Echo Area::           Short messages appear at the bottom of the frame.  
+* Mode Line::	        Interpreting the mode line.  
+* XEmacs under X::      Some information on using XEmacs under the X 
+                        Window System. 
+@end menu
+
+@node Point, Echo Area, Frame, Frame
+@comment  node-name,  next,  previous,  up
+@section Point
+@cindex point
+@cindex cursor
+
+  When XEmacs is running, the cursor shows the location at which editing
+commands will take effect.  This location is called @dfn{point}.  You
+can use keystrokes or the mouse cursor to move point through the text
+and edit the text at different places.
+
+  While the cursor appears to point @var{at} a character, you should
+think of point as @var{between} two characters: it points @var{before}
+the character on which the cursor appears.  Sometimes people speak
+of ``the cursor'' when they mean ``point,'' or speak of commands that
+move point as ``cursor motion'' commands.
+
+ Each XEmacs frame has only one cursor.  When output is in progress, the cursor
+must appear where the typing is being done.  This does not mean that
+point is moving.  It is only that XEmacs has no way to show you the
+location of point except when the terminal is idle.
+
+  If you are editing several files in XEmacs, each file has its own point
+location.  A file that is not being displayed remembers where point is.
+Point becomes visible at the correct location when you look at the file again.
+
+  When there are multiple text windows, each window has its own point
+location.  The cursor shows the location of point in the selected
+window.  The visible cursor also shows you which window is selected.  If
+the same buffer appears in more than one window, point can be moved in
+each window independently.
+
+  The term `point' comes from the character @samp{.}, which was the
+command in TECO (the language in which the original Emacs was written)
+for accessing the value now called `point'.
+
+@node Echo Area, Mode Line, Point, Frame
+@section The Echo Area
+@cindex echo area
+
+  The line at the bottom of the frame (below the mode line) is the
+@dfn{echo area}.  XEmacs uses this area to communicate with the user:
+
+@itemize @bullet
+@item
+  @dfn{Echoing} means printing out the characters that the user types.  XEmacs
+never echoes single-character commands.  Multi-character commands are
+echoed only if you pause while typing them: As soon as you pause for more
+than one second in the middle of a command, all the characters of the command
+so far are echoed.  This is intended to @dfn{prompt} you for the rest of
+the command.  Once echoing has started, the rest of the command is echoed
+immediately as you type it.  This behavior is designed to give confident
+users fast response, while giving hesitant users maximum feedback.  You
+can change this behavior by setting a variable (@pxref{Display Vars}).
+@item
+  If you issue a command that cannot be executed, XEmacs may print an
+@dfn{error message} in the echo area.  Error messages are accompanied by
+a beep or by flashing the frame.  Any input you have typed ahead is
+thrown away when an error happens.
+@item
+  Some commands print informative messages in the echo area.  These
+messages look similar to error messages, but are not announced with a
+beep and do not throw away input.  Sometimes a message tells you what the
+command has done, when this is not obvious from looking at the text being
+edited.  Sometimes the sole purpose of a command is to print a message
+giving you specific information.  For example, the command @kbd{C-x =} is
+used to print a message describing the character position of point in the
+text and its current column in the window.  Commands that take a long time
+often display messages ending in @samp{...} while they are working, and
+add @samp{done} at the end when they are finished.
+@item
+  The echo area is also used to display the @dfn{minibuffer}, a window
+that is used for reading arguments to commands, such as the name of a
+file to be edited.  When the minibuffer is in use, the echo area displays
+with a prompt string that usually ends with a colon.  The cursor
+appears after the prompt.  You can always get out of the minibuffer by
+typing @kbd{C-g}.  @xref{Minibuffer}.
+@end itemize
+
+@node Mode Line, XEmacs under X, Echo Area, Frame
+@comment  node-name,  next,  previous,  up
+@section The Mode Line
+@cindex mode line
+@cindex top level
+
+  Each text window's last line is a @dfn{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 @samp{XEmacs:@: @var{something}}.
+
+  If a mode line has something else in place of @samp{XEmacs:@:
+@var{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:
+
+@example
+--@var{ch}-XEmacs: @var{buf}      (@var{major} @var{minor})----@var{pos}------
+@end example
+
+@noindent
+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.
+
+  @var{ch} contains two stars (@samp{**}) if the text in the buffer has been
+edited (the buffer is ``modified''), or two dashes (@samp{--}) if the
+buffer has not been edited.  Exception: for a read-only buffer, it is 
+@samp{%%}.
+
+  @var{buf} is the name of the window's chosen @dfn{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.  @xref{Buffers}.
+
+  @var{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, @var{pos} is @samp{All}.  Otherwise, 
+@var{pos} is @samp{Top} if you are looking at the beginning of the file,
+@samp{Bot} if you are looking at the end of the file, or
+@samp{@var{nn}%}, where @var{nn} is the percentage of the file above the
+top of the screen.@refill
+
+  @var{major} is the name of the @dfn{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.  @xref{Major Modes}, for details
+on how the modes differ and how you select one.@refill
+
+  @var{minor} is a list of some of the @dfn{minor modes} that are turned on
+in the window's chosen buffer.  For example, @samp{Fill} means that Auto
+Fill mode is on.  @code{Abbrev} means that Word Abbrev mode is on.
+@code{Ovwrt} means that Overwrite mode is on.  @xref{Minor Modes}, for more
+information.  @samp{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.  @xref{Narrowing}.  @code{Def} means that a
+keyboard macro is being defined.  @xref{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 (@samp{[@dots{}]}) 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.  @xref{Recursive Edit}.@refill
+
+@findex display-time
+  XEmacs can optionally display the time and system load in all mode lines.
+To enable this feature, type @kbd{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:
+
+@example
+@var{hh}:@var{mm}pm @var{l.ll} [@var{d}]
+@end example
+
+@noindent
+(Some fields may be missing if your operating system cannot support them.)
+@var{hh} and @var{mm} are the hour and minute, followed always by @samp{am}
+or @samp{pm}.  @var{l.ll} is the average number of running processes in the
+whole system recently.  @var{d} is an approximate index of the ratio of
+disk activity to CPU activity for all users.
+
+The word @samp{Mail} appears after the load level if there is mail for
+you that you have not read yet.
+
+@vindex mode-line-inverse-video
+  Customization note: the variable @code{mode-line-inverse-video}
+controls whether the mode line is displayed in inverse video (assuming
+the terminal supports it); @code{nil} means no inverse video.  The
+default is @code{t}.  For X frames, simply set the foreground and
+background colors appropriately.
+  
+@node XEmacs under X, , Mode Line, Frame
+@section Using XEmacs Under the X Window System
+@comment  node-name,  next,  previous,  up
+
+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 (@pxref{Pull-down Menus}).
+
+@cindex multi-frame XEmacs
+@findex make-frame
+XEmacs under X is also a multi-frame XEmacs.  You can use the @b{New
+Frame} menu item from the @b{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.
+
+@findex find-file-other-frame
+The function @code{find-file-other-frame} is just like @code{find-file},
+but creates a new frame to display the buffer in first.  This is
+normally bound to @kbd{C-x 5 C-f}, and is what the @b{Open File, New
+Frame} menu item does.
+
+@findex switch-to-buffer-other-frame
+The function @code{switch-to-buffer-other-frame} is just like
+@code{switch-to-buffer}, but creates a new frame to display the buffer
+in first.  This is normally bound to @kbd{C-x 5 b}.
+
+@vindex default-frame-alist
+You can specify a different default frame size other than the one provided.
+Use the variable @code{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:  
+
+@example
+  (setq default-frame-alist '((width . 80) (height . 55)))
+@end example
+
+@vindex x-frame-defaults
+For values specific to the first XEmacs frame, you must use X resources.
+The variable @code{x-frame-defaults} takes an alist of default frame
+creation parameters for X window frames.  These override what is
+specified in @file{~/.Xdefaults} but are overridden by the arguments to
+the particular call to @code{x-create-frame}.
+
+@vindex create-frame-hook
+When you create a new frame, the variable @code{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
+@b{New Frame}, use the @b{Delete Frame} menu item from the @b{File} menu.  
+
+@vindex frame-title-format
+@vindex frame-icon-title-format
+If you are working with multiple frames, some special information
+applies:
+@itemize @bullet
+@item
+Two variables, @code{frame-title-format} and
+@code{frame-icon-title-format} determine the title of the frame and
+the title of the icon that results if you shrink the frame.
+
+@vindex auto-lower-frame
+@vindex auto-raise-frame
+@item
+The variables @code{auto-lower-frame} and @code{auto-raise-frame}
+position a frame. If true, @code{auto-lower-frame} lowers a frame to
+the bottom when it is no longer selected. If true,
+@code{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.
+
+@item
+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.)
+@end itemize