code:
@node Mark, Mouse Selection, Help, Top
@chapter Selecting Text
@cindex mark
@cindex region

  Many Emacs commands operate on an arbitrary contiguous
part of the current buffer. You can select text in two ways:

@itemize @bullet
@item
You use special keys to select text by defining a region between point
and the mark.
@item
If you are running XEmacs under X, you can also select text
with the mouse.
@end itemize

@section The Mark and the Region
 To specify the text for a command to operate on, set @dfn{the
mark} at one end of it, and move point to the other end.  The text
between point and the mark is called @dfn{the region}.  You can move
point or the mark to adjust the boundaries of the region.  It doesn't
matter which one is set first chronologically, or which one comes
earlier in the text.

  Once the mark has been set, it remains until it is set again at
another place.  The mark remains fixed with respect to the preceding
character if text is inserted or deleted in a buffer.  Each Emacs
buffer has its own mark; when you return to a buffer that had been
selected previously, it has the same mark it had before.

  Many commands that insert text, such as @kbd{C-y} (@code{yank}) and
@kbd{M-x insert-buffer}, position the mark at one end of the inserted
text---the opposite end from where point is positioned, so that the region
contains the text just inserted.

  Aside from delimiting the region, the mark is useful for marking
a spot that you may want to go back to.  To make this feature more useful,
Emacs remembers 16 previous locations of the mark in the @code{mark ring}.

@menu
* Setting Mark::	Commands to set the mark.
* Using Region::	Summary of ways to operate on contents of the region.
* Marking Objects::	Commands to put region around textual units.
* Mark Ring::   	Previous mark positions saved so you can go back there.
@end menu

@node Setting Mark, Using Region, Mark, Mark
@subsection Setting the Mark

  Here are some commands for setting the mark:

@c WideCommands
@table @kbd
@item C-@key{SPC}
Set the mark where point is (@code{set-mark-command}).
@item C-@@
The same.
@item C-x C-x
Interchange mark and point (@code{exchange-point-and-mark}).
@item C-<
Pushes a mark at the beginning of the buffer.
@item C->
Pushes a mark at the end of the buffer.
@end table

  For example, to convert part of the buffer to all
upper-case, you can use the @kbd{C-x C-u} (@code{upcase-region})
command, which operates on the text in the region.  First go to the
beginning of the text you want to capitalize and type @kbd{C-@key{SPC}} to
put the mark there, then move to the end, and then type @kbd{C-x C-u} to
capitalize the selected region.  You can also set the mark at the end of the
text, move to the beginning, and then type @kbd{C-x C-u}.  Most commands
that operate on the text in the region have the word @code{region} in
their names.

@kindex C-SPC
@findex set-mark-command
  The most common way to set the mark is with the @kbd{C-@key{SPC}}
command (@code{set-mark-command}).  This command sets the mark where
point is. You can then move point away, leaving the mark behind.  It is
actually incorrect to speak of the character @kbd{C-@key{SPC}}; there is
no such character.  When you type @key{SPC} while holding down
@key{CTRL}, you get the character @kbd{C-@@} on most terminals. This
character is actually bound to @code{set-mark-command}.  But unless you are
unlucky enough to have a terminal where typing @kbd{C-@key{SPC}} does
not produce @kbd{C-@@}, you should think of this character as
@kbd{C-@key{SPC}}.

@kindex C-x C-x
@findex exchange-point-and-mark
  Since terminals have only one cursor, Emacs cannot show you where the
mark is located. Most people use the mark soon after they set it, before
they forget where it is. But you can see where the mark is with the
command @kbd{C-x C-x} (@code{exchange-point-and-mark}) which puts the
mark where point was and point where the mark was.  The extent of the
region is unchanged, but the cursor and point are now at the previous
location of the mark.

@kindex C-<
@kindex C->
@findex mark-beginning-of-buffer
@findex mark-end-of-buffer
 Another way to set the mark is to push the mark to the beginning of a
buffer while leaving point at its original location. If you supply an
argument to @kbd{C-<} (@code{mark-beginning-of-buffer}), the mark is pushed
@var{n}/10 of the way from the true beginning of the buffer. You can
also set the mark at the end of a buffer with @kbd{C->}
(@code{mark-end-of-buffer}). It pushes the mark to the end of the buffer,
leaving point alone. Supplying an argument to the command pushes the mark
@var{n}/10 of the way from the true end of the buffer.

If you are using XEmacs under the X window system, you can set
the variable @code{zmacs-regions} to @code{t}. This makes the current
region (defined by point and mark) highlight and makes it available as
the X clipboard selection, which means you can use the menu bar items on
it.  @xref{Active Regions}, for more information.

  @kbd{C-x C-x} is also useful when you are satisfied with the location of
point but want to move the mark; do @kbd{C-x C-x} to put point there and
then you can move it.  A second use of @kbd{C-x C-x}, if necessary, puts
the mark at the new location with point back at its original location.

@node Using Region, Marking Objects, Setting Mark, Mark
@subsection Operating on the Region

  Once you have created an active region, you can do many things to
the text in it:
@itemize @bullet
@item
Kill it with @kbd{C-w} (@pxref{Killing}).
@item
Save it in a register with @kbd{C-x r s} (@pxref{Registers}).
@item
Save it in a buffer or a file (@pxref{Accumulating Text}).
@item
Convert case with @kbd{C-x C-l} or @kbd{C-x C-u} @*(@pxref{Case}).
@item
Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}).
@item
Fill it as text with @kbd{M-q} (@pxref{Filling}).
@item
Print hardcopy with @kbd{M-x print-region} (@pxref{Hardcopy}).
@item
Indent it with @kbd{C-x @key{TAB}} or @kbd{C-M-\} (@pxref{Indentation}).
@end itemize

@node Marking Objects, Mark Ring, Using Region, Mark
@subsection Commands to Mark Textual Objects

  There are commands for placing point and the mark around a textual
object such as a word, list, paragraph or page.

@table @kbd
@item M-@@
Set mark after end of next word (@code{mark-word}).  This command and
the following one do not move point.
@item C-M-@@
Set mark after end of next Lisp expression (@code{mark-sexp}).
@item M-h
Put region around current paragraph (@code{mark-paragraph}).
@item C-M-h
Put region around current Lisp defun (@code{mark-defun}).
@item C-x h
Put region around entire buffer (@code{mark-whole-buffer}).
@item C-x C-p
Put region around current page (@code{mark-page}).
@end table

@kindex M-@@
@kindex C-M-@@
@findex mark-word
@findex mark-sexp
@kbd{M-@@} (@code{mark-word}) puts the mark at the end of the next word,
while @kbd{C-M-@@} (@code{mark-sexp}) puts it at the end of the next Lisp
expression. These characters sometimes save you some typing.

@kindex M-h
@kindex C-M-h
@kindex C-x C-p
@kindex C-x h
@findex mark-paragraph
@findex mark-defun
@findex mark-page
@findex mark-whole-buffer
   A number of commands are available that set both point and mark and
thus delimit an object in the buffer.  @kbd{M-h} (@code{mark-paragraph})
moves point to the beginning of the paragraph that surrounds or follows
point, and puts the mark at the end of that paragraph
(@pxref{Paragraphs}).  You can then indent, case-convert, or kill the
whole paragraph.  In the same fashion, @kbd{C-M-h} (@code{mark-defun})
puts point before and the mark after the current or following defun
(@pxref{Defuns}).  @kbd{C-x C-p} (@code{mark-page}) puts point before
the current page (or the next or previous, depending on the argument),
and mark at the end (@pxref{Pages}).  The mark goes after the
terminating page delimiter (to include it), while point goes after the
preceding page delimiter (to exclude it).  Finally, @kbd{C-x h}
(@code{mark-whole-buffer}) sets up the entire buffer as the region by
putting point at the beginning and the mark at the end.

@node Mark Ring,, Marking Objects, Mark
@subsection The Mark Ring

@kindex C-u C-SPC
@cindex mark ring
@kindex C-u C-@@
  Aside from delimiting the region, the mark is also useful for marking
a spot that you may want to go back to.  To make this feature more
useful, Emacs remembers 16 previous locations of the mark in the
@dfn{mark ring}.  Most commands that set the mark push the old mark onto
this ring.  To return to a marked location, use @kbd{C-u C-@key{SPC}}
(or @kbd{C-u C-@@}); this is the command @code{set-mark-command} given a
numeric argument.  The command moves point to where the mark was, and
restores the mark from the ring of former marks. Repeated use of this
command moves point to all the old marks on the ring, one by one.
The marks you have seen go to the end of the ring, so no marks are lost.

  Each buffer has its own mark ring.  All editing commands use the current
buffer's mark ring.  In particular, @kbd{C-u C-@key{SPC}} always stays in
the same buffer.

  Many commands that can move long distances, such as @kbd{M-<}
(@code{beginning-of-buffer}), start by setting the mark and saving the
old mark on the mark ring.  This makes it easier for you to move back
later.  Searches set the mark, unless they do not actually move point.
When a command sets the mark, @samp{Mark Set} is printed in the
echo area.

@vindex mark-ring-max
  The variable @code{mark-ring-max} is the maximum number of entries to
keep in the mark ring.  If that many entries exist and another entry is
added, the last entry in the list is discarded.  Repeating @kbd{C-u
C-@key{SPC}} circulates through the entries that are currently in the
ring.

@vindex mark-ring
  The variable @code{mark-ring} holds the mark ring itself, as a list of
marker objects in the order most recent first.  This variable is local
in every buffer.


code:
@node Pull-down Menus, Entering Emacs, Keystrokes, Top
@comment  node-name,  next,  previous,  up
@section 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.

@table @b
@item File
Perform file and buffer-related operations, such as opening and closing
files, saving and printing buffers, as well as exiting Emacs.
@cindex File menu

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

@c #### The Mule menu needs to be documented, but this is not the place
@c for it since Ben just moved it.

@item 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.
@cindex Apps menu

@item 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.
@cindex Options menu

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

@item 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.
@cindex Tools menu

@item Help
Access to Emacs Info.
@cindex Help menu
@end table
@cindex Pull-down Menus
@cindex menus

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

@itemize @bullet
@item
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.
@item
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.
@end itemize

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
@b{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.
@xref{Mouse Selection}, for information on using the mouse to select
text.  @xref{Using X Selections}, for related information.

There are also @kbd{M-x} equivalents for each menu item.  To find the
equivalent for any left-button menu item, do the following:

@enumerate
@item
Type @kbd{C-h k} to get the @code{Describe Key} prompt.
@item
Select the menu item and click.
@end enumerate

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.
@end menu

@node File Menu
@subsection The File Menu

@cindex File menu

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

@cindex Open File, New Frame... menu item
@cindex Open File... menu item
@cindex Insert File... menu item
@cindex Save Buffer menu item
@cindex Save Buffer As ... menu item
@cindex Revert Buffer menu item
@cindex Kill Buffer menu item
@cindex Print Buffer menu item
@cindex New Frame menu item
@cindex Delete Frame menu item
@cindex Split Frame
@cindex Un-split (Keep This)
@cindex Un-split (Keep Others)
@cindex Exit Emacs menu item

@table @b
@item 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 @b{Delete Frame} menu
item.  When you remove the last frame, you exit Emacs and are prompted
for confirmation. @refill

@item Open File...
Prompts you for a filename and loads that file into a new buffer.
@b{Open File...} is equivalent to the Emacs command @code{find-file} (@kbd{C-x
C-f}).@refill

@item 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
@code{insert-file} (@kbd{C-x i}).@refill

@item Save Buffer
Writes and saves the current Emacs buffer as the latest
version of the current visited file.  @b{Save Buffer} is equivalent to the
Emacs command @code{save-buffer} (@kbd{C-x C-s}).@refill

@item Save Buffer As...
Writes and saves the current Emacs buffer to the filename you specify.
@b{Save Buffer As...} is equivalent to the Emacs command
@code{write-file} (@kbd{C-x C-w}).@refill

@item 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 @b{Revert Buffer} if you do
not want to keep the changes you have made in the buffer.  @b{Revert
Buffer} is equivalent to the Emacs command @code{revert-file} (@kbd{M-x
revert-buffer}).@refill

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

@item Print Buffer
Prints a hardcopy of the current buffer.  Equivalent
to the Emacs command @code{print-buffer} (@kbd{M-x print-buffer}).@refill

@item New Frame
Creates a new Emacs frame displaying the @code{*scratch*} buffer.  This
is like the @b{Open File, New Frame...} menu item, except that it does
not prompt for or load a file.@refill

@item Delete Frame
Allows you to close all but one of the frames created by @b{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 @b{Exit Emacs} for that.@refill

@item 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 @code{split-window-vertically} (@kbd{C-x 2}).@refill

@item 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
@code{delete-other-windows} (@kbd{C-x 1}).@refill

@item 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 @code{delete-window}
(@kbd{C-x 0}).@refill

@item Exit Emacs
Shuts down (kills) the Emacs process.  Equivalent to the Emacs command
@code{save-buffers-kill-emacs} (@kbd{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.@refill
@end table

@node Edit Menu
@subsection The Edit Menu
@cindex Edit menu

The @b{Edit} pull-down menu contains the @b{Undo}, @b{Cut}, @b{Copy},
@b{Paste}, and @b{Clear} menu items.  When you select a menu item, Emacs
executes the equivalent command.  Most commands on the @b{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.  @xref{Using
X Selections}, @pxref{Killing}, and @pxref{Yanking} for more
information.@refill

@c  **** zmacs-regions is on by default these days - jwz
@c
@c Note: By default, you can use the @b{Edit} menu items on the region between
@c point and the mark as well as regions selected with the mouse. To change
@c this behavior, set the variable @code{zmacs-regions} to
@c @code{t}. @xref{Active Regions} for more information.

@cindex Undo menu item
@cindex Cut menu item
@cindex Copy menu item
@cindex Paste menu item
@cindex Clear menu item
@cindex Start Macro Recording menu item
@cindex End Macro Recording menu item
@cindex Execute Last Macro menu item
@table @b
@item Undo
Undoes the previous command.  @b{Undo} is equivalent to
the Emacs command @code{undo} (@kbd{C-x u}).@refill

@item 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.@refill

@item 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.@refill

@item 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
@code{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 @b{Copy} or @b{Cut}.  You can also
use @b{Paste} to insert text that was pasted into the clipboard from other
applications.

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

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

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

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

@node Apps Menu
@subsection The Apps Menu
@cindex Apps menu

The @b{Apps} pull-down menu contains the @b{Read Mail (VM)...}, @b{Read
Mail (MH)...}, @b{Send Mail...}, @b{Usenet News}, @b{Browse the Web},
@b{Gopher}, @b{Spell-Check Buffer} and @b{Emulate VI} menu items,
and the @b{Calendar} and @b{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.

@node Options Menu
@subsection The Options Menu
@cindex Options menu

The @b{Options} pull-down menu contains the @b{Read Only}, @b{Case
Sensitive Search}, @b{Overstrike}, @b{Auto Delete Selection},
@b{Teach Extended Commands}, @b{Syntax Highlighting}, @b{Paren
Highlighting}, @b{Font}, @b{Size}, @b{Weight}, @b{Buffers Menu
Length...}, @b{Buffers Sub-Menus} and @b{Save Options} menu items.
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.

@cindex Read Only menu item
@cindex Case Sensitive Search menu item
@cindex Overstrike menu item
@cindex Auto Delete Selection menu item
@cindex Teach Extended Commands menu item
@cindex Syntax Highlighting menu item
@cindex Paren Highlighting menu item
@cindex Font menu item
@cindex Size menu item
@cindex Weight menu item
@cindex Buffers Menu Length... menu item
@cindex Buffers Sub-Menus menu item
@cindex Save Options
@table @b
@item Read Only
Selecting this item will cause the buffer to visit the file in a
read-only mode. Changes to the file will not be allowed. This is
equivalent to the Emacs command @code{toggle-read-only}
(@kbd{C-x C-q}).

@item Case Sensitive Search
Selecting this item will cause searches to be case-sensitive. If
its not selected then searches will ignore case. This option is
local to the buffer.

@item Overstrike
After selecting this item, when you type letters they will replace
existing text on a one-to-one basis, rather than pushing it to the
right. At the end of a line, such characters extend the line. Before
a tab, such characters insert until the tab is filled in. This is the
same as Emacs command @code{quoted-insert} (@kbd{C-q}).

@item Auto Delete Selection
Selecting this item will cause automatic deletion of the selected
region. The typed text will replace the selection if the selection
is active (i.e. if its highlighted). If the option is not selected
then the typed text is just inserted at the point.

@item Teach Extended Commands
After you  select this item, any time you execute a command with
@kbd{M-x}which has a shorter keybinding, you will be shown the
alternate binding before the command executes.

@item Syntax Highlighting
You can customize your init file to include the font-lock mode so that
when you select this item, the comments will be displayed in one face,
strings in another, reserved words in another, and so on. @xref{Init
File}.  When @b{Fonts} is selected, different parts of the program will
appear in different Fonts. When @b{Colors} is selected, then the program
will be displayed in different colors. Selecting @b{None} causes the
program to appear in just one Font and Color. Selecting @b{Less} resets
the Fonts and Colors to a fast, minimal set of decorations. Selecting
@b{More} resets the Fonts and Colors to a larger set of decorations. For
example, if @b{Less} is selected (which is the default setting) then you
might have all comments in green color.  Whereas, if @b{More} is
selected then a function name in the comments themselves might appear in
a different Color or Font.@refill

@item Paren Highlighting
After selecting @b{Blink} from this item, if you place the cursor
on a parenthesis, the matching parenthesis will blink. If you select
@b{Highlight} and place the cursor on a parenthesis, the whole
expression of the parenthesis under the cursor will be highlighted.
Selecting @b{None} will turn off the options (regarding @b{Paren
Highlighting}) which you had selected earlier.@refill

@item Font
You can select any Font for your program by choosing from one of the
available Fonts.

@item Size
You can select any size ranging from @b{2} to @b{24} by selecting the
appropriate option.@refill

@item Weight
You can choose either @b{Bold} or @b{Medium} for the weight.@refill

@item Buffers Menu Length...
Prompts you for the number of buffers to display. Then it will display
that number of most recently selected buffers.

@item Buffers Sub-Menus
After selection of this item the Buffers menu will contain several
commands, as submenus of each buffer line. If this item is unselected,
then there are no submenus for each buffer line, the only command
available will be selecting that buffer.

@item Save Options
Selecting this item will save the current settings of your Options
menu to your init file.  @xref{Init File}.
@end table

@node Buffers Menu
@subsection The Buffers Menu
@cindex Buffers menu
The @b{Buffers} menu provides a selection of up to ten buffers and the
item @b{List All Buffers}, which provides a Buffer List. @xref{List
Buffers}, for more information.

@node Tools Menu
@subsection The Tools Menu
@cindex Tools menu

The @b{Tools} pull-down menu contains the @b{Grep...}, @b{Compile...},
@b{Shell Command...}, @b{Shell Command on Region...}, @b{Debug(GDB)...}
and @b{Debug(DBX)...} menu items, and the @b{Compare}, @b{Merge},
@b{Apply Patch} and @b{Tags} 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.

@node Help Menu
@subsection The Help Menu
@cindex Help menu

The Help Menu gives you access to Emacs Info and provides a menu
equivalent for each of the choices you have when using @kbd{C-h}.
@xref{Help}, for more information.

The Help menu also gives access to UNIX online manual pages via the
@b{UNIX Manual Page} option.

@node Menu Customization
@subsection Customizing XEmacs Menus

You can customize any of the pull-down menus by adding or removing menu
items and disabling or enabling existing menu items.

The following functions are available:
@table @kbd
@item add-menu: (@var{menu-path} @var{menu-name} @var{menu-items} &optional @var{before})
Add a menu to the menu bar or one of its submenus.
@item add-menu-item: (@var{menu-path} @var{item-name} @var{function}
@var{enabled-p} &optional @var{before})
Add a menu item to a menu, creating the menu first if necessary.
@item delete-menu-item: (@var{path})
Remove the menu item defined by @var{path} from the menu hierarchy.
@item disable-menu-item: (@var{path})
Disable the specified menu item.
@item enable-menu-item: (@var{path})
Enable the specified previously disabled menu item.
@item relabel-menu-item: (@var{path} @var{new-name})
Change the string of the menu item specified by @var{path} to
@var{new-name}.

@end table

@findex add-menu
@cindex adding menus
Use the function @code{add-menu} to add a new menu or submenu.
If a menu or submenu of the given name exists already, it is changed.

@var{menu-path} identifies the menu under which the new menu should be
inserted.  It is a list of strings; for example, @code{("File")} names
the top-level @b{File} menu.  @code{("File" "Foo")} names a hypothetical
submenu of @b{File}.  If @var{menu-path} is @code{nil}, the menu is
added to the menu bar itself.

@var{menu-name} is the string naming the menu to be added.

@var{menu-items} is a list of menu item descriptions.  Each menu item
should be a vector of three elements:

@itemize @bullet
@item
A string, which is the name of the menu item
@item
A symbol naming a command, or a form to evaluate
@item
@code{t} or @code{nil} to indicate whether the item is selectable
@end itemize

The optional argument @var{before} is the name of the menu before which
the new menu or submenu should be added.  If the menu is already
present, it is not moved.

@findex add-menu-item
@cindex adding menu items
The function @code{add-menu-item} adds a menu item to the specified
menu, creating the menu first if necessary.  If the named item already
exists, the menu remains unchanged.

@var{menu-path} identifies the menu into which the new menu item should
be inserted.  It is a list of strings; for example, @code{("File")}
names the top-level @b{File} menu.  @code{("File" "Foo")} names a
hypothetical submenu of @b{File}.

@var{item-name} is the string naming the menu item to add.

@var{function} is the command to invoke when this menu item is selected.
If it is a symbol, it is invoked with @code{call-interactively}, in the
same way that functions bound to keys are invoked.  If it is a list, the
list is simply evaluated.

@var{enabled-p} controls whether the item is selectable or not.
It should be @code{t}, @code{nil}, or a form to evaluate to decide.
This form will be evaluated just before the menu is displayed, and
the menu item will be selectable if that form returns non-@code{nil}.

For example, to make the @code{rename-file} command available from the
@b{File} menu, use the following code:

@example
(add-menu-item '("File") "Rename File" 'rename-file t)
@end example

To add a submenu of file management commands using a @b{File Management}
item, use the following code:

@example
(add-menu-item '("File" "File Management") "Copy File" 'copy-file t)
(add-menu-item '("File" "File Management") "Delete File" 'delete-file t)
(add-menu-item '("File" "File Management") "Rename File" 'rename-file t)
@end example

The optional @var{before} argument is the name of a menu item before
which the new item should be added.  If the item is already present, it
is not moved.

@findex delete-menu-item
@cindex deleting menu items
To remove a specified menu item from the menu hierarchy, use
@code{delete-menu-item}.

@var{path} is a list of strings that identify the position of the menu
item in the menu hierarchy.  @code{("File" "Save")} means the menu item
called @b{Save} under the top level @b{File} menu.  @code{("Menu" "Foo"
"Item")} means the menu item called @b{Item} under the @b{Foo} submenu
of @b{Menu}.

@findex disable-menu-item
@findex enable-menu-item
@cindex enabling menu items
@cindex disabling menu items

To disable a menu item, use @code{disable-menu-item}.  The disabled
menu item is grayed and can no longer be selected.  To make the
item selectable again, use @code{enable-menu-item}.
@code{disable-menu-item} and @code{enable-menu-item} both have the
argument @var{path}.

@findex relabel-menu-item
@cindex changing menu items
To change the string of the specified menu item, use
@code{relabel-menu-item}. This function also takes the argument @var{path}.

@var{new-name} is the string to which the menu item will be changed.

repo_name: mthl/texinfo

license: mit


code:
@node Minibuffer, M-x, Undo, Top
@chapter The Minibuffer
@cindex minibuffer

  The @dfn{minibuffer} is the facility used by XEmacs commands to read
arguments more complicated than a single number.  Minibuffer arguments
can be file names, buffer names, Lisp function names, XEmacs command
names, Lisp expressions, and many other things, depending on the command
reading the argument.  You can use the usual XEmacs editing commands in
the minibuffer to edit the argument text.

@cindex prompt
  When the minibuffer is in use, it appears in the echo area, and the
cursor moves there.  The beginning of the minibuffer line displays a
@dfn{prompt} which says what kind of input you should supply and how it
will be used.  Often this prompt is derived from the name of the command
that the argument is for.  The prompt normally ends with a colon.

@cindex default argument
  Sometimes a @dfn{default argument} appears in parentheses after the
colon; it, too, is part of the prompt.  The default is used as the
argument value if you enter an empty argument (e.g., by just typing @key{RET}).
For example, commands that read buffer names always show a default, which
is the name of the buffer that will be used if you type just @key{RET}.

@kindex C-g
  The simplest way to enter a minibuffer argument is to type the text
you want, terminated by @key{RET} which exits the minibuffer.  You can
cancel the command that wants the argument, and get out of the
minibuffer, by typing @kbd{C-g}.

  Since the minibuffer uses the screen space of the echo area, it can
conflict with other ways XEmacs customarily uses the echo area.  Here is
how XEmacs handles such conflicts:

@itemize @bullet
@item
If a command gets an error while you are in the minibuffer, this does
not cancel the minibuffer.  However, the echo area is needed for the
error message and therefore the minibuffer itself is hidden for a
while.  It comes back after a few seconds, or as soon as you type
anything.

@item
If in the minibuffer you use a command whose purpose is to print a
message in the echo area, such as @kbd{C-x =}, the message is printed
normally, and the minibuffer is hidden for a while.  It comes back
after a few seconds, or as soon as you type anything.

@item
Echoing of keystrokes does not take place while the minibuffer is in
use.
@end itemize

@menu
* File: Minibuffer File.  Entering file names with the minibuffer.
* Edit: Minibuffer Edit.  How to edit in the minibuffer.
* Completion::		  An abbreviation facility for minibuffer input.
* Minibuffer History::    Reusing recent minibuffer arguments.
* Repetition::		  Re-executing commands that used the minibuffer.
@end menu

@node Minibuffer File, Minibuffer Edit, Minibuffer, Minibuffer
@section Minibuffers for File Names

  Sometimes the minibuffer starts out with text in it.  For example, when
you are supposed to give a file name, the minibuffer starts out containing
the @dfn{default directory}, which ends with a slash.  This is to inform
you which directory the file will be found in if you do not specify a
directory.

  For example, the minibuffer might start out with these contents:

@example
Find File: /u2/emacs/src/
@end example

@noindent
where @samp{Find File:@: } is the prompt.  Typing @kbd{buffer.c}
specifies the file @file{/u2/emacs/src/buffer.c}.  To find files in
nearby directories, use @kbd{..}; thus, if you type
@kbd{../lisp/simple.el}, you will get the file named
@file{/u2/emacs/lisp/simple.el}.  Alternatively, you can kill with
@kbd{M-@key{DEL}} the directory names you don't want (@pxref{Words}).

  If you don't want any of the default, you can kill it with @kbd{C-a
C-k}.  But you don't need to kill the default; you can simply ignore it.
Insert an absolute file name, one starting with a slash or a tilde,
after the default directory.  For example, to specify the file
@file{/etc/termcap}, just insert that name, giving these minibuffer
contents:

@example
Find File: /u2/emacs/src//etc/termcap
@end example

@noindent
@cindex // in file name
@cindex double slash in file name
@cindex slashes repeated in file name
XEmacs gives a special meaning to a double slash (which is not normally
a useful thing to write): it means, ``ignore everything before the
second slash in the pair.''  Thus, @samp{/u2/emacs/src/} is ignored in
the example above, and you get the file @file{/etc/termcap}.

@vindex insert-default-directory
If you set @code{insert-default-directory} to @code{nil}, the default
directory is not inserted in the minibuffer.  This way, the minibuffer
starts out empty.  But the name you type, if relative, is still
interpreted with respect to the same default directory.

@node Minibuffer Edit, Completion, Minibuffer File, Minibuffer
@section Editing in the Minibuffer

  The minibuffer is an XEmacs buffer (albeit a peculiar one), and the
usual XEmacs commands are available for editing the text of an argument
you are entering.

  Since @key{RET} in the minibuffer is defined to exit the minibuffer,
you can't use it to insert a newline in the minibuffer.  To do that,
type @kbd{C-o} or @kbd{C-q C-j}.  (Recall that a newline is really the
character control-J.)

  The minibuffer has its own window which always has space on the screen
but acts as if it were not there when the minibuffer is not in use.
When the minibuffer is in use, its window is just like the others; you
can switch to another window with @kbd{C-x o}, edit text in other
windows and perhaps even visit more files, before returning to the
minibuffer to submit the argument.  You can kill text in another window,
return to the minibuffer window, and then yank the text to use it in the
argument.  @xref{Windows}.

  There are some restrictions on the use of the minibuffer window,
however.  You cannot switch buffers in it---the minibuffer and its
window are permanently attached.  Also, you cannot split or kill the
minibuffer window. But you can make it taller in the normal fashion with
@kbd{C-x ^}.  If you enable Resize-Minibuffer mode, then the
minibuffer window expands vertically as necessary to hold the text that
you put in the minibuffer.  Use @kbd{M-x resize-minibuffer-mode} to
enable or disable this minor mode (@pxref{Minor Modes}).

@kindex C-M-v
  If while in the minibuffer you issue a command that displays help text
of any sort in another window, you can use the @kbd{C-M-v} command while
in the minibuffer to scroll the help text.  This lasts until you exit
the minibuffer.  This feature is especially useful if a completing
minibuffer gives you a list of possible completions.  @xref{Other Window}.

@vindex minibuffer-confirm-incomplete
If the variable @code{minibuffer-confirm-incomplete} is @code{t}, you
are asked for confirmation if there is no known completion for the text
you typed. For example, if you attempted to visit a non-existent file,
the minibuffer might read:
@example
        Find File: chocolate_bar.c [no completions, confirm]
@end example
If you press @kbd{Return} again, that confirms the filename. Otherwise,
you can continue editing it.

 XEmacs supports recursive use of the minibuffer.  However, it is easy
to do this by accident (because of autorepeating keyboards, for example)
and get confused.  Therefore, most XEmacs commands that use the
minibuffer refuse to operate if the minibuffer window is selected.  If
the minibuffer is active but you have switched to a different window,
recursive use of the minibuffer is allowed---if you know enough to try
to do this, you probably will not get confused.

@vindex enable-recursive-minibuffers
  If you set the variable @code{enable-recursive-minibuffers} to a
non-@code{nil}, recursive use of the minibuffer is always allowed.

@node Completion, Minibuffer History, Minibuffer Edit, Minibuffer
@section Completion
@cindex completion

  For certain kinds of arguments, you can use @dfn{completion} to enter
the argument value.  Completion means that you type part of the
argument, then XEmacs visibly fills in the rest, or as much as
can be determined from the part you have typed.

  When completion is available, certain keys---@key{TAB}, @key{RET}, and
@key{SPC}---are rebound to complete the text present in the
minibuffer into a longer string that it stands for, by matching it
against a set of @dfn{completion alternatives} provided by the command
reading the argument.  @kbd{?} is defined to display a list of possible
completions of what you have inserted.

  For example, when @kbd{M-x} uses the minibuffer to read the name of a
command, it provides a list of all available XEmacs command names to
complete against.  The completion keys match the text in the minibuffer
against all the command names, find any additional name characters
implied by the ones already present in the minibuffer, and add those
characters to the ones you have given.  This is what makes it possible
to type @kbd{M-x inse @key{SPC} b @key{RET}} instead of @kbd{M-x
insert-buffer @key{RET}} (for example).

  Case is normally significant in completion because it is significant
in most of the names that you can complete (buffer names, file names and
command names).  Thus, @samp{fo} does not complete to @samp{Foo}.  When
you are completing a name in which case does not matter, case may be
ignored for completion's sake if specified by program.

When a completion list is displayed, the completions will highlight as
you move the mouse over them.  Clicking the middle mouse button on any
highlighted completion will ``select'' it just as if you had typed it in
and hit @key{RET}.

@menu
* Example: Completion Example.
* Commands: Completion Commands.
* Strict Completion::
* Options: Completion Options.
@end menu

@node Completion Example, Completion Commands, Completion, Completion
@subsection Completion Example

@kindex TAB
@findex minibuffer-complete
  A concrete example may help here.  If you type @kbd{M-x au @key{TAB}},
the @key{TAB} looks for alternatives (in this case, command names) that
start with @samp{au}.  There are several, including
@code{auto-fill-mode} and @code{auto-save-mode}---but they are all the
same as far as @code{auto}, so the @samp{au} in the minibuffer changes
to @samp{auto}.

  If you type @key{TAB} again immediately, there are multiple
possibilities for the very next character---it could be any of
@samp{c-}---so no more characters are added; instead, @key{TAB}
displays a list of all possible completions in another window.

  If you go on to type @kbd{-f @key{TAB}}, this @key{TAB} sees
@samp{auto-f}.  The only command name starting this way is
@code{auto-fill-mode}, so completion fills in the rest of that.  You now
have @samp{auto-fill-mode} in the minibuffer after typing just @kbd{au
@key{TAB} f @key{TAB}}.  Note that @key{TAB} has this effect because in
the minibuffer it is bound to the command @code{minibuffer-complete}
when completion is available.

@node Completion Commands, Strict Completion, Completion Example, Completion
@subsection Completion Commands

  Here is a list of the completion commands defined in the minibuffer
when completion is available.

@table @kbd
@item @key{TAB}
Complete the text in the minibuffer as much as possible
(@code{minibuffer-complete}).
@item @key{SPC}
Complete the minibuffer text, but don't go beyond one word
(@code{minibuffer-complete-word}).
@item @key{RET}
Submit the text in the minibuffer as the argument, possibly completing
first as described below (@code{minibuffer-complete-and-exit}).
@item ?
Print a list of all possible completions of the text in the minibuffer
(@code{minibuffer-list-completions}).
@item @key{button2}
Select the highlighted text under the mouse as a minibuffer response.
When the minibuffer is being used to prompt the user for a completion,
any valid completions which are visible on the screen will be highlighted
when the mouse moves over them.  Clicking @key{button2} will select the
highlighted completion and exit the minibuffer.
(@code{minibuf-select-highlighted-completion}).
@end table

@kindex SPC
@findex minibuffer-complete-word
  @key{SPC} completes much like @key{TAB}, but never goes beyond the
next hyphen or space.  If you have @samp{auto-f} in the minibuffer and
type @key{SPC}, it finds that the completion is @samp{auto-fill-mode},
but it stops completing after @samp{fill-}.  This gives
@samp{auto-fill-}.  Another @key{SPC} at this point completes all the
way to @samp{auto-fill-mode}.  @key{SPC} in the minibuffer when
completion is available runs the command
@code{minibuffer-complete-word}.

  Here are some commands you can use to choose a completion from a
window that displays a list of completions:

@table @kbd
@findex mouse-choose-completion
@item button2up
Clicking mouse button 2 on a completion in the list of possible
completions chooses that completion (@code{mouse-choose-completion}).
You normally use this command while point is in the minibuffer; but you
must click in the list of completions, not in the minibuffer itself.

@findex switch-to-completions
@item @key{PRIOR}
@itemx M-v
Typing @key{PRIOR} or @kbd{M-v}, while in the minibuffer, selects the
window showing the completion list buffer
(@code{switch-to-completions}).  This paves the way for using the
commands below.  (Selecting that window in the usual ways has the same
effect, but this way is more convenient.)

@findex choose-completion
@item @key{RET}
Typing @key{RET} @emph{in the completion list buffer} chooses the
completion that point is in or next to (@code{choose-completion}).  To
use this command, you must first switch windows to the window that shows
the list of completions.

@findex next-list-mode-item
@item @key{RIGHT}
@itemx @key{TAB}
@itemx C-f
Typing the right-arrow key @key{RIGHT}, @key{TAB} or @kbd{C-f} @emph{in
the completion list buffer} moves point to the following completion
(@code{next-list-mode-item}).

@findex previous-list-mode-item
@item @key{LEFT}
@itemx C-b
Typing the left-arrow key @key{LEFT} or @kbd{C-b} @emph{in the
completion list buffer} moves point toward the beginning of the buffer,
to the previous completion (@code{previous-list-mode-item}).
@end table

@node Strict Completion, Completion Options, Completion Commands, Completion
@subsection Strict Completion

  There are three different ways that @key{RET} can work in completing
minibuffers, depending on how the argument will be used.

@itemize @bullet
@item
@dfn{Strict} completion is used when it is meaningless to give any
argument except one of the known alternatives.  For example, when
@kbd{C-x k} reads the name of a buffer to kill, it is meaningless to
give anything but the name of an existing buffer.  In strict
completion, @key{RET} refuses to exit if the text in the minibuffer
does not complete to an exact match.

@item
@dfn{Cautious} completion is similar to strict completion, except that
@key{RET} exits only if the text was an exact match already, not
needing completion.  If the text is not an exact match, @key{RET} does
not exit, but it does complete the text.  If it completes to an exact
match, a second @key{RET} will exit.

Cautious completion is used for reading file names for files that must
already exist.

@item
@dfn{Permissive} completion is used when any string whatever is
meaningful, and the list of completion alternatives is just a guide.
For example, when @kbd{C-x C-f} reads the name of a file to visit, any
file name is allowed, in case you want to create a file.  In
permissive completion, @key{RET} takes the text in the minibuffer
exactly as given, without completing it.
@end itemize

  The completion commands display a list of all possible completions in
a window whenever there is more than one possibility for the very next
character.  Also, typing @kbd{?} explicitly requests such a list.  If
the list of completions is long, you can scroll it with @kbd{C-M-v}
(@pxref{Other Window}).

@node Completion Options,  , Strict Completion, Completion
@subsection Completion Options

@vindex completion-ignored-extensions
  When completion is done on file names, certain file names are usually
ignored.  The variable @code{completion-ignored-extensions} contains a
list of strings; a file whose name ends in any of those strings is
ignored as a possible completion.  The standard value of this variable
has several elements including @code{".o"}, @code{".elc"}, @code{".dvi"}
and @code{"~"}.  The effect is that, for example, @samp{foo} can
complete to @samp{foo.c} even though @samp{foo.o} exists as well.
However, if @emph{all} the possible completions end in ``ignored''
strings, then they are not ignored.  Ignored extensions do not apply to
lists of completions---those always mention all possible completions.

@vindex completion-auto-help
  If a completion command finds the next character is undetermined, it
automatically displays a list of all possible completions.  If the variable
@code{completion-auto-help} is set to @code{nil}, this does not happen,
and you must type @kbd{?} to display the possible completions.

@vindex minibuffer-confirm-incomplete
If the variable @code{minibuffer-confirm-incomplete} is set to @code{t},
then in contexts where @code{completing-read} allows answers that are
not valid completions, an extra @key{RET} must be typed to confirm the
response.  This is helpful for catching typos.

@cindex Icomplete mode
  Icomplete mode presents a constantly-updated display that tells you
what completions are available for the text you've entered so far.  The
command to enable or disable this minor mode is @kbd{M-x
icomplete-mode}.

@node Minibuffer History, Repetition, Completion, Minibuffer
@section Minibuffer History
@cindex minibuffer history
@cindex history of minibuffer input

  Every argument that you enter with the minibuffer is saved on a
@dfn{minibuffer history list} so that you can use it again later in
another argument.  Special commands load the text of an earlier argument
in the minibuffer.  They discard the old minibuffer contents, so you can
think of them as moving through the history of previous arguments.

@table @kbd
@item @key{UP}
@itemx M-p
Move to the next earlier argument string saved in the minibuffer history
(@code{previous-history-element}).
@item @key{DOWN}
@itemx M-n
Move to the next later argument string saved in the minibuffer history
(@code{next-history-element}).
@item M-r @var{regexp} @key{RET}
Move to an earlier saved argument in the minibuffer history that has a
match for @var{regexp} (@code{previous-matching-history-element}).
@item M-s @var{regexp} @key{RET}
Move to a later saved argument in the minibuffer history that has a
match for @var{regexp} (@code{next-matching-history-element}).
@end table

@kindex M-p @r{(minibuffer history)}
@kindex M-n @r{(minibuffer history)}
@findex next-history-element
@findex previous-history-element
  The simplest way to reuse the saved arguments in the history list is
to move through the history list one element at a time.  While in the
minibuffer, use @kbd{M-p} or up-arrow (@code{previous-history-element})
to ``move to'' the next earlier minibuffer input, and use @kbd{M-n} or
down-arrow (@code{next-history-element}) to ``move to'' the next later
input.

  The previous input that you fetch from the history entirely replaces
the contents of the minibuffer.  To use it as the argument, exit the
minibuffer as usual with @key{RET}.  You can also edit the text before
you reuse it; this does not change the history element that you
``moved'' to, but your new argument does go at the end of the history
list in its own right.

  For many minibuffer arguments there is a ``default'' value.  In some
cases, the minibuffer history commands know the default value.  Then you
can insert the default value into the minibuffer as text by using
@kbd{M-n} to move ``into the future'' in the history.

@findex previous-matching-history-element
@findex next-matching-history-element
@kindex M-r @r{(minibuffer history)}
@kindex M-s @r{(minibuffer history)}
  There are also commands to search forward or backward through the
history; they search for history elements that match a regular
expression that you specify with the minibuffer.  @kbd{M-r}
(@code{previous-matching-history-element}) searches older elements in
the history, while @kbd{M-s} (@code{next-matching-history-element})
searches newer elements.  By special dispensation, these commands can
use the minibuffer to read their arguments even though you are already
in the minibuffer when you issue them.  As with incremental searching,
an uppercase letter in the regular expression makes the search
case-sensitive (@pxref{Search Case}).

  All uses of the minibuffer record your input on a history list, but
there are separate history lists for different kinds of arguments.  For
example, there is a list for file names, used by all the commands that
read file names.

  There are several other very specific history lists, including one for
command names read by @kbd{M-x}, one for buffer names, one for arguments
of commands like @code{query-replace}, and one for compilation commands
read by @code{compile}.  Finally, there is one ``miscellaneous'' history
list that most minibuffer arguments use.

@c Do wee need this?
@ignore
@vindex history-length
  The variable @code{history-length} specifies the maximum length of a
minibuffer history list; once a list gets that long, the oldest element
is deleted each time an element is added.  If the value of
@code{history-length} is @code{t}, though, there is no maximum length
and elements are never deleted.
@end ignore

@node Repetition,  , Minibuffer History, Minibuffer
@section Repeating Minibuffer Commands
@cindex command history
@cindex history of commands

  Every command that uses the minibuffer at least once is recorded on a
special history list, together with the values of its arguments, so that
you can repeat the entire command.  In particular, every use of
@kbd{M-x} is recorded there, since @kbd{M-x} uses the minibuffer to read
the command name.

@findex list-command-history
@c widecommands
@table @kbd
@item C-x @key{ESC} @key{ESC}
Re-execute a recent minibuffer command (@code{repeat-complex-command}).
@item M-p
Within @kbd{C-x @key{ESC} @key{ESC}}, move to previous recorded command
(@code{previous-history-element}).
@item M-n
Within @kbd{C-x @key{ESC} @key{ESC}}, move to the next (more recent)
recorded command (@code{next-history-element}).
@item M-x list-command-history
Display the entire command history, showing all the commands
@kbd{C-x @key{ESC} @key{ESC}} can repeat, most recent first.
@end table

@kindex C-x ESC ESC
@findex repeat-complex-command
  @kbd{C-x @key{ESC} @key{ESC}} is used to re-execute a recent
minibuffer-using command.  With no argument, it repeats the last such
command.  A numeric argument specifies which command to repeat; one
means the last one, and larger numbers specify earlier ones.

  @kbd{C-x @key{ESC} @key{ESC}} works by turning the previous command
into a Lisp expression and then entering a minibuffer initialized with
the text for that expression.  If you type just @key{RET}, the command
is repeated as before.  You can also change the command by editing the
Lisp expression.  Whatever expression you finally submit is what will be
executed.  The repeated command is added to the front of the command
history unless it is identical to the most recently executed command
already there.

  Even if you don't understand Lisp syntax, it will probably be obvious
which command is displayed for repetition.  If you do not change the text,
you can be sure the command will repeat exactly as before.

@kindex M-n
@kindex M-p
@findex next-complex-command
@findex previous-complex-command
  If you are in the minibuffer for @kbd{C-x @key{ESC} @key{ESC}} and the
command shown to you is not the one you want to repeat, you can move
around the list of previous commands using @kbd{M-n} and @kbd{M-p}.
@kbd{M-p} replaces the contents of the minibuffer with the next earlier
recorded command, and @kbd{M-n} replaces it with the next later command.
After finding the desired previous command, you can edit its expression
and then resubmit it by typing @key{RET}.  Any editing you have done on
the command to be repeated is lost if you use @kbd{M-n} or @kbd{M-p}.

@kbd{M-n} and @kbd{M-p} are specially defined within @kbd{C-x @key{ESC}
@key{ESC}} to run the commands @code{previous-history-element} and
@code{next-history-element}.

@vindex command-history
  The list of previous commands using the minibuffer is stored as a Lisp
list in the variable @code{command-history}.  Each element of the list
is a Lisp expression which describes one command and its arguments.
Lisp programs can reexecute a command by feeding the corresponding
@code{command-history} element to @code{eval}.


code:
@iftex
@chapter Miscellaneous Commands

  This chapter contains several brief topics that do not fit anywhere else.

@end iftex

@node Sorting, Shell, Calendar/Diary, Top
@section Sorting Text
@cindex sorting

  XEmacs provides several commands for sorting text in a buffer.  All
operate on the contents of the region (the text between point and the
mark).  They divide the text of the region into many @dfn{sort records},
identify a @dfn{sort key} for each record, and then reorder the records
using the order determined by the sort keys.  The records are ordered so
that their keys are in alphabetical order, or, for numerical sorting, in
numerical order.  In alphabetical sorting, all upper-case letters `A'
through `Z' come before lower-case `a', in accordance with the ASCII
character sequence.

  The sort commands differ in how they divide the text into sort
records and in which part of each record they use as the sort key.  Most of
the commands make each line a separate sort record, but some commands use
paragraphs or pages as sort records.  Most of the sort commands use each
entire sort record as its own sort key, but some use only a portion of the
record as the sort key.

@findex sort-lines
@findex sort-paragraphs
@findex sort-pages
@findex sort-fields
@findex sort-numeric-fields
@table @kbd
@item M-x sort-lines
Divide the region into lines and sort by comparing the entire
text of a line.  A prefix argument means sort in descending order.

@item M-x sort-paragraphs
Divide the region into paragraphs and sort by comparing the entire
text of a paragraph (except for leading blank lines).  A prefix
argument means sort in descending order.

@item M-x sort-pages
Divide the region into pages and sort by comparing the entire
text of a page (except for leading blank lines).  A prefix
argument means sort in descending order.

@item M-x sort-fields
Divide the region into lines and sort by comparing the contents of
one field in each line.  Fields are defined as separated by
whitespace, so the first run of consecutive non-whitespace characters
in a line constitutes field 1, the second such run constitutes field
2, etc.

You specify which field to sort by with a numeric argument: 1 to sort
by field 1, etc.  A negative argument means sort in descending
order.  Thus, minus 2 means sort by field 2 in reverse-alphabetical
order.

@item M-x sort-numeric-fields
Like @kbd{M-x sort-fields}, except the specified field is converted
to a number for each line and the numbers are compared.  @samp{10}
comes before @samp{2} when considered as text, but after it when
considered as a number.

@item M-x sort-columns
Like @kbd{M-x sort-fields}, except that the text within each line
used for comparison comes from a fixed range of columns.  An explanation
is given below.
@end table

For example, if the buffer contains:

@smallexample
On systems where clash detection (locking of files being edited) is
implemented, XEmacs also checks the first time you modify a buffer
whether the file has changed on disk since it was last visited or
saved.  If it has, you are asked to confirm that you want to change
the buffer.
@end smallexample

@noindent
then if you apply @kbd{M-x sort-lines} to the entire buffer you get:

@smallexample
On systems where clash detection (locking of files being edited) is
implemented, XEmacs also checks the first time you modify a buffer
saved.  If it has, you are asked to confirm that you want to change
the buffer.
whether the file has changed on disk since it was last visited or
@end smallexample

@noindent
where the upper case `O' comes before all lower case letters.  If you apply
instead @kbd{C-u 2 M-x sort-fields} you get:

@smallexample
saved.  If it has, you are asked to confirm that you want to change
implemented, XEmacs also checks the first time you modify a buffer
the buffer.
On systems where clash detection (locking of files being edited) is
whether the file has changed on disk since it was last visited or
@end smallexample

@noindent
where the sort keys were @samp{If}, @samp{XEmacs}, @samp{buffer},
@samp{systems}, and @samp{the}.@refill

@findex sort-columns
  @kbd{M-x sort-columns} requires more explanation.  You specify the
columns by putting point at one of the columns and the mark at the other
column.  Because this means you cannot put point or the mark at the
beginning of the first line to sort, this command uses an unusual
definition of `region': all of the line point is in is considered part of
the region, and so is all of the line the mark is in.

  For example, to sort a table by information found in columns 10 to 15,
you could put the mark on column 10 in the first line of the table, and
point on column 15 in the last line of the table, and then use this command.
Or you could put the mark on column 15 in the first line and point on
column 10 in the last line.

  This can be thought of as sorting the rectangle specified by point and
the mark, except that the text on each line to the left or right of the
rectangle moves along with the text inside the rectangle.
@xref{Rectangles}.

@node Shell, Narrowing, Sorting, Top
@section Running Shell Commands from XEmacs
@cindex subshell
@cindex shell commands

  XEmacs has commands for passing single command lines to inferior shell
processes; it can also run a shell interactively with input and output to
an XEmacs buffer @samp{*shell*}.

@table @kbd
@item M-!
Run a specified shell command line and display the output
(@code{shell-command}).
@item M-|
Run a specified shell command line with region contents as input;
optionally replace the region with the output
(@code{shell-command-on-region}).
@item M-x shell
Run a subshell with input and output through an XEmacs buffer.
You can then give commands interactively.
@item M-x term
Run a subshell with input and output through an XEmacs buffer.
You can then give commands interactively.
Full terminal emulation is available.
@end table

@menu
* Single Shell::         How to run one shell command and return.
* Interactive Shell::    Permanent shell taking input via XEmacs.
* Shell Mode::           Special XEmacs commands used with permanent shell.
* Terminal emulator::    An XEmacs window as a terminal emulator.
* Term Mode::            Special XEmacs commands used in Term mode.
* Paging in Term::       Paging in the terminal emulator.
@end menu

@node Single Shell, Interactive Shell, Shell, Shell
@subsection Single Shell Commands

@kindex M-!
@findex shell-command
  @kbd{M-!} (@code{shell-command}) reads a line of text using the
minibuffer and creates an inferior shell to execute the line as a command.
Standard input from the command comes from the null device.  If the shell
command produces any output, the output goes to an XEmacs buffer named
@samp{*Shell Command Output*}, which is displayed in another window but not
selected.  A numeric argument, as in @kbd{M-1 M-!}, directs this command to
insert any output into the current buffer.  In that case, point is left
before the output and the mark is set after the output.

@kindex M-|
@findex shell-command-on-region
  @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but passes
the contents of the region as input to the shell command, instead of no
input.  If a numeric argument is used to direct  output to the current
buffer, then the old region is deleted first and the output replaces it as
the contents of the region.@refill

@vindex shell-file-name
@cindex environment
  Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify the
shell to use.  This variable is initialized based on your @code{SHELL}
environment variable when you start XEmacs.  If the file name does not
specify a directory, the directories in the list @code{exec-path} are
searched; this list is initialized based on the @code{PATH} environment
variable when you start XEmacs.  You can override either or both of these
default initializations in your init file. @xref{Init File}.@refill

  When you use @kbd{M-!} and @kbd{M-|}, XEmacs has to wait until the
shell command completes.  You can quit with @kbd{C-g}; that terminates
the shell command.

@node Interactive Shell, Shell Mode, Single Shell, Shell
@subsection Interactive Inferior Shell

@findex shell
  To run a subshell interactively with its typescript in an XEmacs
buffer, use @kbd{M-x shell}.  This creates (or reuses) a buffer named
@samp{*shell*} and runs a subshell with input coming from and output going
to that buffer.  That is to say, any ``terminal output'' from the subshell
will go into the buffer, advancing point, and any ``terminal input'' for
the subshell comes from text in the buffer.  To give input to the subshell,
go to the end of the buffer and type the input, terminated by @key{RET}.

  XEmacs does not wait for the subshell to do anything.  You can switch
windows or buffers and edit them while the shell is waiting, or while it is
running a command.  Output from the subshell waits until XEmacs has time to
process it; this happens whenever XEmacs is waiting for keyboard input or
for time to elapse.

 To get multiple subshells, change the name of buffer
@samp{*shell*} to something different by using @kbd{M-x rename-buffer}.  The
next use of @kbd{M-x shell} creates a new buffer @samp{*shell*} with
its own subshell.  By renaming this buffer as well you can create a third
one, and so on.  All the subshells run independently and in parallel.

@vindex explicit-shell-file-name
  The file name used to load the subshell is the value of the variable
@code{explicit-shell-file-name}, if that is non-@code{nil}.  Otherwise, the
environment variable @code{ESHELL} is used, or the environment variable
@code{SHELL} if there is no @code{ESHELL}.  If the file name specified
is relative, the directories in the list @code{exec-path} are searched
(@pxref{Single Shell,Single Shell Commands}).@refill

  As soon as the subshell is started, it is sent as input the contents of
the file @file{~/.emacs_@var{shellname}}, if that file exists, where
@var{shellname} is the name of the file that the shell was loaded from.
For example, if you use @code{csh}, the file sent to it is
@file{~/.emacs_csh}.@refill

@vindex shell-pushd-regexp
@vindex shell-popd-regexp
@vindex shell-cd-regexp
  @code{cd}, @code{pushd}, and @code{popd} commands given to the inferior
shell are watched by XEmacs so it can keep the @samp{*shell*} buffer's
default directory the same as the shell's working directory.  These
commands are recognized syntactically by examining lines of input that are
sent.  If you use aliases for these commands, you can tell XEmacs to
recognize them also.  For example, if the value of the variable
@code{shell-pushd-regexp} matches the beginning of a shell command line,
that line is regarded as a @code{pushd} command.  Change this variable when
you add aliases for @samp{pushd}.  Likewise, @code{shell-popd-regexp} and
@code{shell-cd-regexp} are used to recognize commands with the meaning of
@samp{popd} and @samp{cd}.@refill

@kbd{M-x shell-resync-dirs} queries the shell and resynchronizes XEmacs'
idea of what the current directory stack is.  @kbd{M-x
shell-dirtrack-toggle} turns directory tracking on and off.

@vindex input-ring-size
XEmacs keeps a history of the most recent commands you have typed in the
@samp{*shell*} buffer.  If you are at the beginning of a shell command
line and type @key{M-p}, the previous shell input is inserted into the
buffer before point.  Immediately typing @key{M-p} again deletes that
input and inserts the one before it.  By repeating @key{M-p} you can
move backward through your commands until you find one you want to
repeat.  You may then edit the command before typing @key{RET} if you
wish. @key{M-n} moves forward through the command history, in case you
moved backward past the one you wanted while using @key{M-p}.  If you
type the first few characters of a previous command and then type
@key{M-p}, the most recent shell input starting with those characters is
inserted.  This can be very convenient when you are repeating a sequence
of shell commands.  The variable @code{input-ring-size} controls how
many commands are saved in your input history.  The default is 30.

@node Shell Mode, Terminal emulator, Interactive Shell, Shell
@subsection Shell Mode

@cindex Shell mode
  The shell buffer uses Shell mode, which defines several special keys
attached to the @kbd{C-c} prefix.  They are chosen to resemble the usual
editing and job control characters present in shells that are not under
XEmacs, except that you must type @kbd{C-c} first.  Here is a list
of the special key bindings of Shell mode:

@kindex RET (Shell mode)
@kindex C-c C-d (Shell mode)
@kindex C-d (Shell mode)
@kindex C-c C-u (Shell mode)
@kindex C-c C-w (Shell mode)
@kindex C-c C-c (Shell mode)
@kindex C-c C-z (Shell mode)
@kindex C-c C-\ (Shell mode)
@kindex C-c C-o (Shell mode)
@kindex C-c C-r (Shell mode)
@kindex C-c C-y (Shell mode)
@kindex M-p (Shell mode)
@kindex M-n (Shell mode)
@kindex TAB (Shell mode)
@findex send-shell-input
@findex shell-send-eof
@findex comint-delchar-or-maybe-eof
@findex interrupt-shell-subjob
@findex stop-shell-subjob
@findex quit-shell-subjob
@findex kill-output-from-shell
@findex show-output-from-shell
@findex copy-last-shell-input
@findex comint-previous-input
@findex comint-next-input
@findex comint-dynamic-complete
@vindex shell-prompt-pattern
@table @kbd
@item @key{RET}
At end of buffer send line as input; otherwise, copy current line to end of
buffer and send it (@code{send-shell-input}).  When a line is copied, any
text at the beginning of the line that matches the variable
@code{shell-prompt-pattern} is left out; this variable's value should be a
regexp string that matches the prompts that you use in your subshell.
@item C-c C-d
Send end-of-file as input, probably causing the shell or its current
subjob to finish (@code{shell-send-eof}).
@item C-d
If point is not at the end of the buffer, delete the next character just
like most other modes.  If point is at the end of the buffer, send
end-of-file as input, instead of generating an error as in other modes
(@code{comint-delchar-or-maybe-eof}).
@item C-c C-u
Kill all text that has yet to be sent as input (@code{kill-shell-input}).
@item C-c C-w
Kill a word before point (@code{backward-kill-word}).
@item C-c C-c
Interrupt the shell or its current subjob if any
(@code{interrupt-shell-subjob}).
@item C-c C-z
Stop the shell or its current subjob if any (@code{stop-shell-subjob}).
@item C-c C-\
Send quit signal to the shell or its current subjob if any
(@code{quit-shell-subjob}).
@item C-c C-o
Delete last batch of output from shell (@code{kill-output-from-shell}).
@item C-c C-r
Scroll top of last batch of output to top of window
(@code{show-output-from-shell}).
@item C-c C-y
Copy the previous bunch of shell input and insert it into the
buffer before point (@code{copy-last-shell-input}).  No final newline
is inserted, and the input copied is not resubmitted until you type
@key{RET}.
@item M-p
Move backward through the input history.  Search for a matching command
if you have typed the beginning of a command (@code{comint-previous-input}).
@item M-n
Move forward through the input history.  Useful when you are
using @key{M-p} quickly and go past the desired command
(@code{comint-next-input}).
@item @key{TAB}
Complete the file name preceding point (@code{comint-dynamic-complete}).
@end table

@node Terminal emulator, Term Mode, Shell Mode, Shell
@subsection Interactive Inferior Shell with Terminal Emulator
@findex term

  To run a subshell in a terminal emulator, putting its typescript in an XEmacs
buffer, use @kbd{M-x term}.  This creates (or reuses) a buffer named
@samp{*term*} and runs a subshell with input coming from your keyboard and
output going to that buffer.

All the normal keys that you type are sent without any interpretation
by XEmacs directly to the subshell, as ``terminal input.''
Any ``echo'' of your input is the responsibility of the subshell.
(The exception is the terminal escape character,
which by default is @kbd{C-c}. @pxref{Term Mode}.)
Any ``terminal output'' from the subshell goes into the buffer,
advancing point.

  Some programs (such as XEmacs itself) need to control the
appearance on the terminal screen in detail.  They do this by
sending special control codes.  The exact control
codes needed vary from terminal to terminal, but nowadays
most terminals and terminal emulators (including xterm)
understand the so-called "ANSI escape sequences" (first
popularized by the Digital's VT100 family of terminal).
The term mode also understands these escape sequences,
and for each control code does the appropriate thing
to change the buffer so that the appearance of the window
will match what it would be on a real terminal.
Thus you can actually run XEmacs inside an XEmacs Term window!

   XEmacs does not wait for the subshell to do anything.  You can switch
windows or buffers and edit them while the shell is waiting, or while
it is running a command.  Output from the subshell waits until XEmacs
has time to process it; this happens whenever XEmacs is waiting for
keyboard input or for time to elapse.

   To make multiple terminal emulators, rename the buffer @samp{*term*}
to something different using @kbd{M-x rename-uniquely},
just as with Shell mode.

   The file name used to load the subshell is determined
the same way as for Shell mode.

Unlike Shell mode, Term mode does not track the current directory
by examining your input.  Instead, if you use a programmable
shell, you can have it tell Term what the current directory is.
This is done automatically by bash for version 1.15 and later.

@node Term Mode, Paging in Term, Terminal emulator, Shell
@subsection Term Mode
@cindex Term mode
@cindex mode, Term

  Term uses Term mode, which has two input modes:
In line mode, Term basically acts like Shell mode.  @xref{Shell Mode}.
In Char mode, each character is sent directly to the inferior subshell,
except for the Term escape character, normally @kbd{C-c}.

To switch between line and char mode, use these commands:
@table @kbd
@kindex C-c C-j @r{(Term mode)}
findex term-char-mode
@item C-c C-j
Switch to line mode.  Do nothing if already in line mode.

@kindex C-c C-k @r{(Term mode)}
@findex term-line-mode
@item C-c C-k
Switch to char mode.  Do nothing if already in char mode.
@end table

The following commands are only available in Char mode:
@table @kbd
@item C-c C-c
Send a literal @key{C-c} to the sub-shell.

@item C-c C-x
A prefix command to conveniently access the global @key{C-x} commands.
For example, @kbd{C-c C-x o} invokes the global binding of
@kbd{C-x o}, which is normally @samp{other-window}.
@end table

@node Paging in Term,, Term Mode, Shell
@subsection Paging in the terminal emulator

Term mode has a pager feature.  When the pager is enabled,
term mode will pause at the end of each screenful.

@table @kbd
@kindex C-c C-q @r{(Term mode)}
@findex term-pager-toggle
@item C-c C-q
Toggles the pager feature:  Disables the pager if it is enabled,
and vice versa.  This works in both line and char modes.
If the pager enabled, the mode-line contains the word @samp{page}.
@end table

If the pager is enabled, and Term receives more than a screenful
of output since your last input, Term will enter More break mode.
This is indicated by @samp{**MORE**} in the mode-line.
Type a @kbd{Space} to display the next screenful of output.
Type @kbd{?} to see your other options.  The interface is similar
to the Unix @samp{more} program.

@node Narrowing, Hardcopy, Shell, Top
@section Narrowing
@cindex widening
@cindex restriction
@cindex narrowing

  @dfn{Narrowing} means focusing in on some portion of the buffer, making
the rest temporarily invisible and inaccessible.  Cancelling the narrowing
and making the entire buffer once again visible is called @dfn{widening}.
The amount of narrowing in effect in a buffer at any time is called the
buffer's @dfn{restriction}.

@c WideCommands
@table @kbd
@item C-x n n
Narrow down to between point and mark (@code{narrow-to-region}).
@item C-x n w
Widen to make the entire buffer visible again (@code{widen}).
@end table

  Narrowing sometimes makes it easier to concentrate on a single
subroutine or paragraph by eliminating clutter.  It can also be used to
restrict the range of operation of a replace command or repeating
keyboard macro.  The word @samp{Narrow} appears in the mode line
whenever narrowing is in effect.  When you have narrowed to a part of the
buffer, that part appears to be all there is.  You can't see the rest,
can't move into it (motion commands won't go outside the visible part),
and can't change it in any way.  However, the invisible text is not
gone; if you save the file, it will be saved.

@kindex C-x n n
@findex narrow-to-region
  The primary narrowing command is @kbd{C-x n n} (@code{narrow-to-region}).
It sets the current buffer's restrictions so that the text in the current
region remains visible but all text before the region or after the region
is invisible.  Point and mark do not change.

  Because narrowing can easily confuse users who do not understand it,
@code{narrow-to-region} is normally a disabled command.  Attempting to use
this command asks for confirmation and gives you the option of enabling it;
once you enable the command, confirmation will no longer be required.  @xref{Disabling}.

@kindex C-x n w
@findex widen
   To undo narrowing, use @kbd{C-x n w} (@code{widen}).  This makes all
text in the buffer accessible again.

   Use the @kbd{C-x =} command to get information on what part of the
buffer you narrowed down.  @xref{Position Info}.

@node Hardcopy, Recursive Edit, Narrowing, Top
@section Hardcopy Output
@cindex hardcopy

  The XEmacs commands for making hardcopy derive their names from the
Unix commands @samp{print} and @samp{lpr}.

@table @kbd
@item M-x print-buffer
Print hardcopy of current buffer using Unix command @samp{print}
@*(@samp{lpr -p}).  This command adds page headings containing the file name
and page number.
@item M-x lpr-buffer
Print hardcopy of current buffer using Unix command @samp{lpr}.
This command does not add page headings.
@item M-x print-region
Like @code{print-buffer}, but prints only the current region.
@item M-x lpr-region
Like @code{lpr-buffer}, but prints only the current region.
@end table

@findex print-buffer
@findex print-region
@findex lpr-buffer
@findex lpr-region
@vindex lpr-switches
  All the hardcopy commands pass extra switches to the @code{lpr} program
based on the value of the variable @code{lpr-switches}.  Its value should
be a list of strings, each string a switch starting with @samp{-}.  For
example, the value could be @code{("-Pfoo")} to print on printer
@samp{foo}.

@node Recursive Edit, Dissociated Press, Hardcopy, Top
@section Recursive Editing Levels
@cindex recursive editing level
@cindex editing level, recursive

  A @dfn{recursive edit} is a situation in which you are using XEmacs
commands to perform arbitrary editing while in the middle of another
XEmacs command.  For example, when you type @kbd{C-r} inside a
@code{query-replace}, you enter a recursive edit in which you can change
the current buffer.  When you exit from the recursive edit, you go back to
the @code{query-replace}.

@kindex C-M-c
@findex exit-recursive-edit
@cindex exiting
  @dfn{Exiting} a recursive edit means returning to the unfinished
command, which continues execution.  For example, exiting the recursive
edit requested by @kbd{C-r} in @code{query-replace} causes query replacing
to resume.  Exiting is done with @kbd{C-M-c} (@code{exit-recursive-edit}).

@kindex C-]
@findex abort-recursive-edit
  You can also @dfn{abort} a recursive edit.  This is like exiting, but
also quits the unfinished command immediately.  Use the command @kbd{C-]}
(@code{abort-recursive-edit}) for this.  @xref{Quitting}.

  The mode line shows you when you are in a recursive edit by displaying
square brackets around the parentheses that always surround the major
and minor mode names.  Every window's mode line shows the square
brackets, since XEmacs as a whole, rather than any particular buffer, is
in a recursive edit.

@findex top-level
  It is possible to be in recursive edits within recursive edits.  For
example, after typing @kbd{C-r} in a @code{query-replace}, you might
type a command that entered the debugger.  In such a case, two or
more sets of square brackets appear in the mode line(s).  Exiting the
inner recursive edit (here with the debugger @kbd{c} command)
resumes the query-replace command where it called the debugger.  After
the end of the query-replace command, you would be able to exit the
first recursive edit.  Aborting exits only one level of recursive edit;
it returns to the command level of the previous recursive edit.  You can
then abort that one as well.

  The command @kbd{M-x top-level} aborts all levels of
recursive edits, returning immediately to the top level command reader.

  The text you edit inside the recursive edit need not be the same text
that you were editing at top level.  If the command that invokes the
recursive edit selects a different buffer first, that is the buffer you
will edit recursively.  You can switch buffers within the recursive edit
in the normal manner (as long as the buffer-switching keys have not been
rebound).  While you could theoretically do the rest of your editing
inside the recursive edit, including visiting files, this could have
surprising effects (such as stack overflow) from time to time.  It is
best if you always exit or abort a recursive edit when you no longer
need it.

  In general, XEmacs tries to avoid using recursive edits.  It is
usually preferable to allow users to switch among the possible editing
modes in any order they like.  With recursive edits, the only way to get
to another state is to go ``back'' to the state that the recursive edit
was invoked from.

@node Dissociated Press, CONX, Recursive Edit, Top
@section Dissociated Press

@findex dissociated-press
  @kbd{M-x dissociated-press} is a command for scrambling a file of text
either word by word or character by character.  Starting from a buffer of
straight English, it produces extremely amusing output.  The input comes
from the current XEmacs buffer.  Dissociated Press writes its output in a
buffer named @samp{*Dissociation*}, and redisplays that buffer after every
couple of lines (approximately) to facilitate reading it.

  @code{dissociated-press} asks every so often whether to continue
operating.  Answer @kbd{n} to stop it.  You can also stop at any time by
typing @kbd{C-g}.  The dissociation output remains in the @samp{*Dissociation*}
buffer for you to copy elsewhere if you wish.

@cindex presidentagon
  Dissociated Press operates by jumping at random from one point in the
buffer to another.  In order to produce plausible output rather than
gibberish, it insists on a certain amount of overlap between the end of one
run of consecutive words or characters and the start of the next.  That is,
if it has just printed out `president' and then decides to jump to a
different point in the file, it might spot the `ent' in `pentagon' and
continue from there, producing `presidentagon'.  Long sample texts produce
the best results.

@cindex againformation
  A positive argument to @kbd{M-x dissociated-press} tells it to operate
character by character, and specifies the number of overlap characters.  A
negative argument tells it to operate word by word and specifies the number
of overlap words.  In this mode, whole words are treated as the elements to
be permuted, rather than characters.  No argument is equivalent to an
argument of two.  For your againformation, the output goes only into the
buffer @samp{*Dissociation*}.  The buffer you start with is not changed.

@cindex Markov chain
@cindex ignoriginal
@cindex techniquitous
  Dissociated Press produces nearly the same results as a Markov chain
based on a frequency table constructed from the sample text.  It is,
however, an independent, ignoriginal invention.  Dissociated Press
techniquitously copies several consecutive characters from the sample
between random choices, whereas a Markov chain would choose randomly for
each word or character.  This makes for more plausible sounding results
and runs faster.

@cindex outragedy
@cindex buggestion
@cindex properbose
  It is a mustatement that too much use of Dissociated Press can be a
developediment to your real work.  Sometimes to the point of outragedy.
And keep dissociwords out of your documentation, if you want it to be well
userenced and properbose.  Have fun.  Your buggestions are welcome.

@node CONX, Amusements, Dissociated Press, Top
@section CONX
@cindex random sentences

Besides producing a file of scrambled text with Dissociated Press, you
can generate random sentences by using CONX.

@table @kbd
@item M-x conx
Generate random sentences in the @code{*conx*} buffer.
@item M-x conx-buffer
Absorb the text in the current buffer into the @code{conx} database.
@item M-x conx-init
Forget the current word-frequency tree.
@item M-x conx-load
Load a @code{conx} database that has been previously saved with
@code{M-x conx-save}.
@item M-x conx-region
Absorb the text in the current buffer into the @code{conx} database.
@item M-x conx-save
Save the current @code{conx} database to a file for future retrieval.
@end table

@findex conx
@findex conx-buffer
@findex conx-load
@findex conx-region
@findex conx-init
@findex conx-save

Copy text from a buffer using @kbd{M-x conx-buffer} or @kbd{M-x conx-region}
and then type @kbd{M-x conx}.  Output is continuously generated until you
type @key{^G}. You can save the @code{conx} database to a file with
@kbd{M-x conx-save}, which you can retrieve with @code{M-x conx-load}.
To clear the database, use @code{M-x conx-init}.

@node Amusements, Emulation, CONX, Top
@section Other Amusements
@cindex boredom
@findex hanoi
@findex yow

  If you are a little bit bored, you can try @kbd{M-x hanoi}.  If you are
considerably bored, give it a numeric argument.  If you are very, very
bored, try an argument of 9.  Sit back and watch.

  When you are frustrated, try the famous Eliza program.  Just do
@kbd{M-x doctor}.  End each input by typing @kbd{RET} twice.

  When you are feeling strange, type @kbd{M-x yow}.

@node Emulation, Customization, Amusements, Top
@comment  node-name,  next,  previous,  up
@section Emulation
@cindex other editors
@cindex vi
@cindex EDT

  XEmacs can be programmed to emulate (more or less) most other
editors.  Standard facilities can emulate these:

@table @asis
@item Viper (a vi emulator)
@cindex Viper
In XEmacs, Viper is the preferred emulation of vi within XEmacs.
Viper is designed to allow you to take advantage of the best
features of XEmacs while still doing your basic editing in a
familiar, vi-like fashion.  Viper provides various different
levels of vi emulation, from a quite complete emulation that
allows almost no access to native XEmacs commands, to an
``expert'' mode that combines the most useful vi commands with
the most useful XEmacs commands.

To start Viper, put the command

@example
(viper-mode)
@end example

in your init file.  @xref{Init File}.

Viper comes with a separate manual that is provided standard
with the XEmacs distribution.

@ignore
@item evi (alternative vi emulator)
@cindex evi
evi is an alternative vi emulator that also provides a nearly complete
emulation of vi.

evi comes with a separate manual that is provided standard
with the XEmacs distribution.

Warning: loading more than one vi emulator at once may cause name
conflicts; no one has checked.
@end ignore

@item EDT (DEC VMS editor)
@findex edt-emulation-on
@findex edt-emulation-off
Turn on EDT emulation with @kbd{M-x edt-emulation-on}.  @kbd{M-x
@*edt-emulation-off} restores normal Emacs command bindings.

Most of the EDT emulation commands are keypad keys, and most standard
Emacs key bindings are still available.  The EDT emulation rebindings
are done in the global keymap, so there is no problem switching
buffers or major modes while in EDT emulation.

@item Gosling Emacs
@findex set-gosmacs-bindings
@findex set-gnu-bindings
Turn on emulation of Gosling Emacs (aka Unipress Emacs) with @kbd{M-x
set-gosmacs-bindings}.  This redefines many keys, mostly on the
@kbd{C-x} and @kbd{ESC} prefixes, to work as they do in Gosmacs.
@kbd{M-x set-gnu-bindings} returns to normal XEmacs by rebinding
the same keys to the definitions they had at the time @kbd{M-x
set-gosmacs-bindings} was done.

It is also possible to run Mocklisp code written for Gosling Emacs.
@xref{Mocklisp}.
@end table


code:
@node Mouse Selection, Additional Mouse Operations, Mark, Top
@comment  node-name,  next,  previous,  up
@section Selecting Text with the Mouse
@cindex mouse selection

@cindex pointer shapes
  If you are using XEmacs under X, you can use the mouse pointer
to select text. (The normal mouse pointer is an I-beam, the same
pointer that @code{xterm} uses.)

@vindex modeline-pointer-glyph
@vindex nontext-pointer-glyph
@vindex text-pointer-glyph
The glyph variable @code{text-pointer-glyph} controls the shape of
the mouse pointer when over text.  You can also control the shape
of the mouse pointer when over nontext using @code{nontext-pointer-glyph},
and the shape of the mouse pointer when over the modeline using
@code{modeline-pointer-glyph}. (Remember, you should use
@code{set-glyph-image}, not @code{setq}, to set one of these
variables.)

@cindex pointer face
If you want to get fancy, you can set the foreground and background
colors of the mouse pointer by setting the @code{pointer} face.

There are two ways to select a region of text with the mouse:

  To select a word in text, double-click with the left mouse button
while the mouse cursor is over the word.  The word is highlighted when
selected. On monochrome monitors, a stippled background indicates that a
region of text has been highlighted. On color monitors, a color
background indicates highlighted text. You can triple-click to select
whole lines.

To select an arbitrary region of text:

@enumerate
@item
Move the mouse cursor over the character at the beginning of the region of
text you want to select.
@item
Press and hold the left mouse button.
@item
While holding the left mouse button down, drag the cursor to the
character at the end of the region of text you want to select.
@item
Release the left mouse button.
@end enumerate
The selected region of text is highlighted.

  Once a region of text is selected, it becomes the primary X selection
(@pxref{Using X Selections}) as well as the Emacs selected region. You
can paste it into other X applications and use the options from the
@b{Edit} pull-down menu on it.  Since it is also the Emacs region, you
can use Emacs region commands on it.

@node Additional Mouse Operations, Killing, Mouse Selection, Top
@section Additional Mouse Operations
@cindex mouse operations

XEmacs also provides the following mouse functions.  Most of these are
not bound to mouse gestures by default, but they are provided for your
customization pleasure.  For example, if you wanted @kbd{shift-left}
(that is, holding down the @key{Shift} key and clicking the left mouse
button) to delete the character at which you are pointing, then you
could do this:

@example
(global-set-key '(shift button1) 'mouse-del-char)
@end example

@findex mouse-del-char
@findex mouse-delete-window
@findex mouse-keep-one-window
@findex mouse-kill-line
@findex mouse-line-length
@findex mouse-scroll
@findex mouse-select
@findex mouse-select-and-split
@findex mouse-set-mark
@findex mouse-set-point
@findex mouse-track
@findex mouse-track-adjust
@findex mouse-track-and-copy-to-cutbuffer
@findex mouse-track-delete-and-insert

@table @kbd
@item mouse-del-char
Delete the character pointed to by the mouse.
@item mouse-delete-window
Delete the Emacs window that the mouse is on.
@item mouse-keep-one-window
Select the Emacs window that the mouse is on, then delete all other
windows on this frame.
@item mouse-kill-line
Kill the line pointed to by the mouse.
@item mouse-line-length
Print the length of the line indicated by the pointer.
@item mouse-scroll
Scroll point to the mouse position.
@item mouse-select
Select the Emacs window the mouse is on.
@item mouse-select-and-split
Select the Emacs window mouse is on, then split it vertically in half.
@item mouse-set-mark
Select the Emacs window the mouse is on and set the mark at the mouse
position.  Display the cursor at that position for a second.
@item mouse-set-point
Select the Emacs window that the mouse is on and move point to the
mouse position.
@item mouse-track
Make a selection with the mouse.   This is the default binding of
the left mouse button (@key{button1}).
@item mouse-track-adjust
Extend the existing selection.  This is the default binding of
@key{Shift-button1}.
@item mouse-track-and-copy-to-cutbuffer
Make a selection like @code{mouse-track}, but also copy it to the cut buffer.
@item mouse-track-delete-and-insert
Make a selection with the mouse and insert it at point.  This is the
default binding of @key{control-shift-button1}.
@item mouse-track-insert
Make a selection with the mouse and insert it at point.
This is the default binding of @key{control-button1}.
@item mouse-window-to-region
Narrow a window to the region between the cursor and the mouse pointer.
@end table

The @kbd{M-x mouse-track} command should be bound to a mouse button.  If
you click-and-drag, the selection is set to the region between the
point of the initial click and the point at which you release the
button.  These positions do not need to be ordered.

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

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

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

The selected text becomes the current X selection, and is also copied to
the top of the kill ring.  Point will be left at the position at
which you released the button and the mark will be left at the initial
click position.  Bind a mouse click to
@kbd{mouse-track-and-copy-to-cutbuffer} to copy selections to the cut buffer.
(See also the @code{mouse-track-adjust} command, on @kbd{Shift-button1}.)

The @kbd{M-x mouse-track-adjust} command should be bound to a mouse
button.  The selection will be enlarged or shrunk so that the point of
the mouse click is one of its endpoints.  This is only meaningful
after the @code{mouse-track} command (@key{button1}) has been executed.

The @kbd{M-x mouse-track-delete-and-insert} command is exactly the same
as the @code{mouse-track} command on @key{button1}, except that point is
not moved; the selected text is immediately inserted after being
selected; and the text of the selection is deleted.

The @kbd{M-x mouse-track-insert} command is exactly the same as the
@code{mouse-track} command on @key{button1}, except that point is not moved;
the selected text is immediately inserted after being selected; and the
selection is immediately disowned afterwards.