code:
@node Help, Mark, M-x, Top
@chapter Help
@kindex Help
@cindex help
@cindex self-documentation
@findex help-command
@kindex C-h
@kindex F1

  XEmacs provides extensive help features accessible through a single
character, @kbd{C-h}.  @kbd{C-h} is a prefix key that is used only for
documentation-printing commands.  The characters that you can type after
@kbd{C-h} are called @dfn{help options}.  One help option is @kbd{C-h};
that is how you ask for help about using @kbd{C-h}.  To cancel, type
@kbd{C-g}.  The function key @key{F1} is equivalent to @kbd{C-h}.

@kindex C-h C-h
@findex help-for-help
  @kbd{C-h C-h} (@code{help-for-help}) displays a list of the possible
help options, and then asks you to type the desired option.  It prompts
with the string:

@smallexample
A B C F I K L M N P S T V W C-c C-d C-f C-i C-k C-n C-w;  ? for more help:
@end smallexample

@noindent
You should type one of those characters.

  Typing a third @kbd{C-h} displays a description of what the options mean;
Emacs still waits for you to type an option.  To cancel, type @kbd{C-g}.

  Most help buffers use a special major mode, Help mode, which lets you
scroll conveniently with @key{SPC} and @key{DEL} or @key{BS}.

@menu
* Help Summary::	Brief list of all Help commands.
* Key Help::		Asking what a key does in XEmacs.
* Name Help::		Asking about a command, variable or function name.
* Apropos::		Asking what pertains to a given topic.
* Library Keywords::	Finding Lisp libraries by keywords (topics).
* Help Mode::           Special features of Help mode and Help buffers.
* Misc Help::		Other help commands.
@end menu

@iftex
@node Help Summary, Help Summary, Help, Help
@end iftex
@ifinfo
@node Help Summary, Key Help, Help, Help
@section Help Summary
@end ifinfo

  Here is a summary of the defined help commands.

@table @kbd
@item C-h a @var{regexp} @key{RET}
Display a list of functions and variables whose names match @var{regexp}
(@code{hyper-apropos}).
@item C-h A @var{regexp}
Show all commands whose names contain matches for @var{regexp}
(@code{command-apropos}).
@item C-h b
Display a table of all key bindings currently in effect, with local
bindings of the current major mode first, followed by all global
bindings (@code{describe-bindings}).
@item C-h c @var{key}
Print the name of the command that @var{key} runs
(@code{describe-key-briefly}).  Here @kbd{c} stands for `character'.  For more
extensive information on @var{key}, use @kbd{C-h k}.
@item C-h d @var{function} @key{RET}
@itemx C-h f @var{function} @key{RET}
Display documentation on the Lisp function named @var{function}
(@code{describe-function}).  Since commands are Lisp functions,
a command name may be used.
@item C-h i
Run Info, the program for browsing documentation files (@code{info}).
The complete XEmacs manual is available online in Info.
@item C-h k @var{key}
Display the name and documentation of the command that @var{key} runs
(@code{describe-key}).
@item C-h l
Display a description of the last 100 characters you typed
(@code{view-lossage}).
@item C-h m
Display documentation of the current major mode (@code{describe-mode}).
@item C-h n
@itemx C-h C-n
Display documentation of XEmacs changes, most recent first
(@code{view-emacs-news}).
@item C-h p
Find packages by topic keyword (@code{finder-by-keyword}).
@item C-h C-p
Display a table of all mouse bindings currently in effect now, with
local bindings of the current major mode first, followed by all global
bindings (@code{describe-pointer}).
@item C-h s
Display current contents of the syntax table, plus an explanation of
what they mean (@code{describe-syntax}).  @xref{Syntax}.
@item C-h t
Enter the XEmacs interactive tutorial (@code{help-with-tutorial}).
@item C-h v @var{var} @key{RET}
Display the documentation of the Lisp variable @var{var}
(@code{describe-variable}).
@item C-h w @var{command} @key{RET}
Print which keys run the command named @var{command} (@code{where-is}).
@item C-h B @key{RET}
Display info on how to deal with Beta versions of XEmacs
(@code{describe-beta}).
@item C-h C @var{group} @key{RET}
Select customization buffer for @var{group} (@code{customize}).
@item C-h F @key{RET}
View the local copy of the XEmacs FAQ (@code{xemacs-local-faq}).
@item C-h C-i @var{file} @key{RET}
Read Info file @var{file} with Info browser (@code{Info-query}).
@item C-h C-c @var{command} @key{RET}
Look up an Emacs command @var{command} in the Emacs manual in the Info
system (@code{Info-goto-emacs-command-node}).
@item C-h C-f @var{function} @key{RET}
Look up an Emacs Lisp function @var{function} in the Elisp manual in the
Info system (@code{Info-elisp-ref}).
@end table

@node Key Help, Name Help, Help Summary, Help
@section Documentation for a Key

@kindex C-h c
@findex describe-key-briefly
  The most basic @kbd{C-h} options are @kbd{C-h c}
(@code{describe-key-briefly}) and @w{@kbd{C-h k}} (@code{describe-key}).
@kbd{C-h c @var{key}} prints in the echo area the name of the command
that @var{key} is bound to.  For example, @kbd{C-h c C-f} prints
@samp{forward-char}.  Since command names are chosen to describe what
the commands do, this is a good way to get a very brief description of
what @var{key} does.

@kindex C-h k
@findex describe-key
  @kbd{C-h k @var{key}} is similar to @kbd{C-h c} but gives more
information.  It displays the documentation string of the function
@var{key} is bound to as well as its name.  @var{key} is a string or
vector of events.  When called interactively, @var{key} may also be a menu
selection.  This information does not usually fit into the echo area, so a
window is used for the display.

  @kbd{C-h c} and @kbd{C-h k} work for any sort of key sequences,
including function keys and mouse events.

@node Name Help, Apropos, Key Help, Help
@section Help by Command or Variable Name

@kindex C-h f
@findex describe-function
@vindex describe-function-show-arglist
  @kbd{C-h f} (@code{describe-function}) reads the name of a Lisp
function using the minibuffer, then displays that function's
documentation string in a window.  Since commands are Lisp functions,
you can use the argument @var{function} to get the documentation of a
command that you know by name.  For example,

@example
C-h f auto-fill-mode @key{RET}
@end example

@noindent
displays the documentation for @code{auto-fill-mode}. Using @kbd{C-h f}
is the only way to see the documentation of a command that is not bound
to any key, that is, a command you would normally call using @kbd{M-x}.
If the variable @code{describe-function-show-arglist} is @code{t},
@code{describe-function} shows its arglist if the @var{function} is not
an autoload function.

  @kbd{C-h f} is also useful for Lisp functions that you are planning to
use in a Lisp program.  For example, if you have just written the
expression @code{(make-vector len)} and want to make sure you are using
@code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}.
Because @kbd{C-h f} allows all function names, not just command names,
you may find that some of your favorite abbreviations that work in
@kbd{M-x} don't work in @kbd{C-h f}.  An abbreviation may be unique
among command names, yet fail to be unique when other function names are
allowed.

  The function name for @kbd{C-h f} to describe has a default which is
used if you type @key{RET} leaving the minibuffer empty.  The default is
the function called by the innermost Lisp expression in the buffer
around point, @emph{provided} that is a valid, defined Lisp function
name.  For example, if point is located following the text
@samp{(make-vector (car x)}, the innermost list containing point is the
one that starts with @samp{(make-vector}, so the default is to describe the
function @code{make-vector}.

  @kbd{C-h f} is often useful just to verify that you have the right
spelling for the function name.  If @kbd{C-h f} mentions a name from the
buffer as the default, that name must be defined as a Lisp function.  If
that is all you want to know, just type @kbd{C-g} to cancel the @kbd{C-h
f} command, then go on editing.

@kindex C-h w
@findex where-is
  @kbd{C-h w @var{command} @key{RET}} (@code{where-is}) tells you what
keys are bound to @var{command}.  It prints a list of the keys in the
echo area. Alternatively, it informs you that a command is not bound to
any keys, which implies that you must use @kbd{M-x} to call the
command.

@kindex C-h v
@findex describe-variable
  @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but
describes Lisp variables instead of Lisp functions.  Its default is the
Lisp symbol around or before point, if that is the name of a known Lisp
variable.  @xref{Variables}.

@node Apropos, Library Keywords, Name Help, Help
@section Apropos

@kindex C-h A
@findex command-apropos
@cindex apropos

@table @kbd
@item C-h A
Show only symbols that are names of commands
(@code{command-apropos}).

@item M-x apropos @var{regexp}
Show all symbols whose names contain matches for @var{regexp}.
@end table

  A more sophisticated sort of question to ask is, ``What are the
commands for working with files?''  To ask this question, type @kbd{C-h
a file @key{RET}}, which displays a list of all command names that
contain @samp{file}, including @code{copy-file}, @code{find-file}, and
so on.  With each command name appears a brief description of how to use
the command, and what keys you can currently invoke it with.  For
example, it would say that you can invoke @code{find-file} by typing
@kbd{C-x C-f}.  The @kbd{A} in @kbd{C-h A} stands for `Apropos';
@kbd{C-h A} runs the command @code{command-apropos}.  This command
normally checks only commands (interactive functions); if you specify a
prefix argument, it checks noninteractive functions as well.

  Because @kbd{C-h A} looks only for functions whose names contain the
string you specify, you must use ingenuity in choosing the string.  If
you are looking for commands for killing backwards and @kbd{C-h a
kill-backwards @key{RET}} doesn't reveal any, don't give up.  Try just
@kbd{kill}, or just @kbd{backwards}, or just @kbd{back}.  Be persistent.
Pretend you are playing Adventure.  Also note that you can use a regular
expression as the argument, for more flexibility (@pxref{Regexps}).

  Here is a set of arguments to give to @kbd{C-h a} that covers many
classes of XEmacs commands, since there are strong conventions for
naming the standard XEmacs commands.  By giving you a feel for the
naming conventions, this set should also serve to aid you in developing
a technique for picking @code{apropos} strings.

@quotation
char, line, word, sentence, paragraph, region, page, sexp, list, defun,
rect, buffer, frame, window, face, file, dir, register, mode, beginning,
end, forward, backward, next, previous, up, down, search, goto, kill,
delete, mark, insert, yank, fill, indent, case, change, set, what, list,
find, view, describe, default.
@end quotation

@findex apropos
  To list all Lisp symbols that contain a match for a regexp, not just
the ones that are defined as commands, use the command @kbd{M-x apropos}
instead of @kbd{C-h A}.  This command does not check key bindings by
default; specify a numeric argument if you want it to check them.

@findex apropos-documentation
  The @code{apropos-documentation} command is like @code{apropos} except
that it searches documentation strings for matches for the specified
regular expression.

@findex apropos-value
  The @code{apropos-value} command is like @code{apropos} except that it
searches symbols' values for matches for the specified regular
expression.  This command does not check function definitions or
property lists by default; specify a numeric argument if you want it to
check them.

@vindex apropos-do-all
  If the variable @code{apropos-do-all} is non-@code{nil}, the commands
above all behave as if they had been given a prefix argument.

  If you want more information about a function definition, variable or
symbol property listed in the Apropos buffer, you can click on it with
@kbd{Mouse-2} or move there and type @key{RET}.

@node Library Keywords, Help Mode, Apropos, Help
@section Keyword Search for Lisp Libraries

@kindex C-h p
@findex finder-by-keyword
The @kbd{C-h p} command lets you search the standard Emacs Lisp
libraries by topic keywords.  Here is a partial list of keywords you can
use:

@display
abbrev        abbreviation handling, typing shortcuts, macros
bib           code related to the `bib' bibliography processor
c             C, C++, and Objective-C language support
calendar      calendar and time management support
comm          communications, networking, remote access to files
data          support for editing files of data
docs          support for Emacs documentation
dumped        files preloaded into Emacs
emulations    emulations of other editors
extensions    Emacs Lisp language extensions
faces         support for multiple fonts
frames        support for Emacs frames and window systems
games         games, jokes and amusements
hardware      support for interfacing with exotic hardware
help          support for on-line help systems
hypermedia    support for links between text or other media types
i18n          internationalization and alternate character-set support
internal      code for Emacs internals, build process, defaults
languages     specialized modes for editing programming languages
lisp          Lisp support, including Emacs Lisp
local         code local to your site
maint         maintenance aids for the Emacs development group
mail          modes for electronic-mail handling
matching      various sorts of searching and matching
mouse         mouse support
mule          multi-language extensions
news          support for netnews reading and posting
oop           support for object-oriented programming
outlines      support for hierarchical outlining
processes     process, subshell, compilation, and job control support
terminals     support for terminal types
tex           code related to the TeX formatter
tools         programming tools
unix          front-ends/assistants for, or emulators of, UNIX features
vms           support code for vms
wp            word processing
@end display

@node Help Mode, Misc Help, Library Keywords, Help
@section Help Mode Commands

  Help buffers provide the commands of View mode (@pxref{Misc File
Ops}), plus a few special commands of their own.

@table @kbd
@item @key{SPC}
Scroll forward.
@item @key{DEL}
@itemx @key{BS}
Scroll backward.
@c @item @key{RET}
@c Follow a cross reference at point.
@c @item @key{TAB}
@c Move point forward to the next cross reference.
@c @item S-@key{TAB}
@c Move point back to the previous cross reference.
@c @item Mouse-2
@c Follow a cross reference that you click on.
@end table

  When a command name (@pxref{M-x,, Running Commands by Name}) or
variable name (@pxref{Variables}) appears in the documentation, it
normally appears inside paired single-quotes.

@node Misc Help,  , Help Mode, Help
@section Other Help Commands

@kindex C-h i
@findex info
@cindex Info
@cindex manuals, on-line
@cindex on-line manuals
  @kbd{C-h i} (@code{info}) runs the Info program, which is used for
browsing through structured documentation files.  The entire XEmacs manual
is available within Info.  Eventually all the documentation of the GNU
system will be available.  Type @kbd{h} after entering Info to run
a tutorial on using Info.

  If you specify a numeric argument, @kbd{C-h i} prompts for the name of
a documentation file.  This way, you can browse a file which doesn't
have an entry in the top-level Info menu.  It is also handy when you
need to get to the documentation quickly, and you know the exact name of
the file.

@kindex C-h C-f
@kindex C-h C-k
@findex Info-elisp-ref
@findex Info-goto-emacs-command-node
  There are two special help commands for accessing XEmacs documentation
through Info.  @kbd{C-h C-f @var{function} @key{RET}} enters Info and
goes straight to the documentation of the XEmacs function
@var{function}.  @kbd{C-h C-k @var{key}} enters Info and goes straight
to the documentation of the key @var{key}.  These two keys run the
commands @code{Info-elisp-ref} and
@code{Info-goto-emacs-key-command-node}.

@kindex C-h l
@findex view-lossage
  If something surprising happens, and you are not sure what commands you
typed, use @kbd{C-h l} (@code{view-lossage}).  @kbd{C-h l} prints the last
100 command characters you typed in.  If you see commands that you don't
know, you can use @kbd{C-h c} to find out what they do.

@kindex C-h m
@findex describe-mode
  XEmacs has several major modes.  Each mode redefines a few keys and
makes a few other changes in how editing works.  @kbd{C-h m}
(@code{describe-mode}) prints documentation on the current major mode,
which normally describes all the commands that are changed in this mode.

@kindex C-h b
@findex describe-bindings
  @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s}
(@code{describe-syntax}) present information about the current XEmacs
mode that is not covered by @kbd{C-h m}.  @kbd{C-h b} displays a list of
all the key bindings currently in effect, with the local bindings of the
current major mode first, followed by the global bindings (@pxref{Key
Bindings}).  @kbd{C-h s} displays the contents of the syntax table with
explanations of each character's syntax (@pxref{Syntax}).

  You can get a similar list for a particular prefix key by typing
@kbd{C-h} after the prefix key.  (There are a few prefix keys for which
this does not work---those that provide their own bindings for
@kbd{C-h}.  One of these is @key{ESC}, because @kbd{@key{ESC} C-h} is
actually @kbd{C-M-h}, which marks a defun.)

@kindex C-h F
@findex xemacs-local-faq
@kindex C-h n
@findex view-emacs-news
@kindex C-h t
@findex help-with-tutorial
@kindex C-h C-c
@findex describe-copying
@kindex C-h C-d
@findex describe-distribution
@kindex C-h C-w
@findex describe-no-warranty
  The other @kbd{C-h} options display various files of useful
information.  @kbd{C-h C-w} (@code{describe-no-warranty}) displays the
full details on the complete absence of warranty for XEmacs.  @kbd{C-h
n} (@code{view-emacs-news}) displays the file @file{xemacs/etc/NEWS},
which contains documentation on XEmacs changes arranged chronologically.
@kbd{C-h F} (@code{xemacs-local-faq}) displays local version of the
XEmacs frequently-answered-questions-list.  @kbd{C-h t}
(@code{help-with-tutorial}) displays the learn-by-doing XEmacs
tutorial. @kbd{C-h C-c} (@code{describe-copying}) displays the file
@file{xemacs/etc/COPYING}, which tells you the conditions you must obey
in distributing copies of XEmacs.  @kbd{C-h C-d}
(@code{describe-distribution}) displays another file named
@file{xemacs/etc/DISTRIB}, which tells you how you can order a copy of
the latest version of XEmacs.


code:
@node Indentation, Text, Major Modes, Top
@chapter Indentation
@cindex indentation

@c WideCommands
@table @kbd
@item @key{TAB}
Indent current line ``appropriately'' in a mode-dependent fashion.
@item @key{LFD}
Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
@item M-^
Merge two lines (@code{delete-indentation}).  This would cancel out
the effect of @key{LFD}.
@item C-M-o
Split line at point; text on the line after point becomes a new line
indented to the same column that it now starts in (@code{split-line}).
@item M-m
Move (forward or back) to the first non-blank character on the current
line (@code{back-to-indentation}).
@item C-M-\
Indent several lines to same column (@code{indent-region}).
@item C-x @key{TAB}
Shift block of lines rigidly right or left (@code{indent-rigidly}).
@item M-i
Indent from point to the next prespecified tab stop column
(@code{tab-to-tab-stop}).
@item M-x indent-relative
Indent from point to under an indentation point in the previous line.
@end table

@kindex TAB
@cindex indentation
  Most programming languages have some indentation convention.  For Lisp
code, lines are indented according to their nesting in parentheses.  The
same general idea is used for C code, though details differ.

   Use the @key{TAB} command to indent a line whatever the language.
Each major mode defines this command to perform indentation appropriate
for the particular language.  In Lisp mode, @key{TAB} aligns a line
according to its depth in parentheses.  No matter where in the line you
are when you type @key{TAB}, it aligns the line as a whole.  In C mode,
@key{TAB} implements a subtle and sophisticated indentation style that
knows about many aspects of C syntax.

@kindex TAB
  In Text mode, @key{TAB} runs the command @code{tab-to-tab-stop}, which
indents to the next tab stop column.  You can set the tab stops with
@kbd{M-x edit-tab-stops}.

@menu
* Indentation Commands:: Various commands and techniques for indentation.
* Tab Stops::            You can set arbitrary "tab stops" and then
                         indent to the next tab stop when you want to.
* Just Spaces::          You can request indentation using just spaces.
@end menu

@node Indentation Commands, Tab Stops, Indentation, Indentation
@section Indentation Commands and Techniques
@c ??? Explain what Emacs has instead of space-indent-flag.

  If you just want to insert a tab character in the buffer, you can type
@kbd{C-q @key{TAB}}.

@kindex M-m
@findex back-to-indentation
  To move over the indentation on a line, type @kbd{Meta-m}
(@code{back-to-indentation}).  This command, given anywhere on a line,
positions point at the first non-blank character on the line.

  To insert an indented line before the current line, type @kbd{C-a C-o
@key{TAB}}.  To make an indented line after the current line, use
@kbd{C-e @key{LFD}}.

@kindex C-M-o
@findex split-line
  @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of
the line vertically down, so that the current line becomes two lines.
@kbd{C-M-o} first moves point forward over any spaces and tabs.  Then it
inserts after point a newline and enough indentation to reach the same
column point is on.  Point remains before the inserted newline; in this
regard, @kbd{C-M-o} resembles @kbd{C-o}.

@kindex M-\
@kindex M-^
@findex delete-horizontal-space
@findex delete-indentation
  To join two lines cleanly, use the @kbd{Meta-^}
(@code{delete-indentation}) command to delete the indentation at the
front of the current line, and the line boundary as well.  Empty spaces
are replaced by a single space, or by no space if at the beginning of a
line, before a close parenthesis, or after an open parenthesis.
To delete just the indentation of a line, go to the beginning of the
line and use @kbd{Meta-\} (@code{delete-horizontal-space}), which
deletes all spaces and tabs around the cursor.

@kindex C-M-\
@kindex C-x TAB
@findex indent-region
@findex indent-rigidly
  There are also commands for changing the indentation of several lines at
once.  @kbd{Control-Meta-\} (@code{indent-region}) gives each line which
begins in the region the ``usual'' indentation by invoking @key{TAB} at the
beginning of the line.  A numeric argument specifies the column to indent
to.  Each line is shifted left or right so that its first non-blank
character appears in that column.  @kbd{C-x @key{TAB}}
(@code{indent-rigidly}) moves all the lines in the region right by its
argument (left, for negative arguments).  The whole group of lines moves
rigidly sideways, which is how the command gets its name.@refill

@findex indent-relative
  @kbd{M-x indent-relative} indents at point based on the previous line
(actually, the last non-empty line.)  It inserts whitespace at point, moving
point, until it is underneath an indentation point in the previous line.
An indentation point is the end of a sequence of whitespace or the end of
the line.  If point is farther right than any indentation point in the
previous line, the whitespace before point is deleted and the first
indentation point then applicable is used.  If no indentation point is
applicable even then, @code{tab-to-tab-stop} is run (see next section).

  @code{indent-relative} is the definition of @key{TAB} in Indented Text
mode.  @xref{Text}.

@node Tab Stops, Just Spaces, Indentation Commands, Indentation
@section Tab Stops

@kindex M-i
@findex tab-to-tab-stop
  For typing in tables, you can use Text mode's definition of @key{TAB},
@code{tab-to-tab-stop}.  This command inserts indentation before point,
enough to reach the next tab stop column.  Even if you are not in Text mode,
this function is associated with @kbd{M-i} anyway.

@findex edit-tab-stops
@findex edit-tab-stops-note-changes
@kindex C-c C-c (Edit Tab Stops)
@vindex tab-stop-list
  You can arbitrarily set the tab stops used by @kbd{M-i}.  They are
stored as a list of column-numbers in increasing order in the variable
@code{tab-stop-list}.

  The convenient way to set the tab stops is using @kbd{M-x edit-tab-stops},
which creates and selects a buffer containing a description of the tab stop
settings.  You can edit this buffer to specify different tab stops, and
then type @kbd{C-c C-c} to make those new tab stops take effect.  In the
tab stop buffer, @kbd{C-c C-c} runs the function
@code{edit-tab-stops-note-changes} rather than the default
@code{save-buffer}.  @code{edit-tab-stops} records which buffer was current
when you invoked it, and stores the tab stops in that buffer.  Normally
all buffers share the same tab stops and changing them in one buffer
affects all.  If you make @code{tab-stop-list} local in one
buffer @code{edit-tab-stops} in that buffer edits only the local
settings.

  Below is the text representing ordinary tab stops every eight columns:

@example
        :       :       :       :       :       :
0         1         2         3         4
0123456789012345678901234567890123456789012345678
To install changes, type C-c C-c
@end example

  The first line contains a colon at each tab stop.  The remaining lines
help you see where the colons are and tell you what to do.

  Note that the tab stops that control @code{tab-to-tab-stop} have nothing
to do with displaying tab characters in the buffer.  @xref{Display Vars},
for more information on that.

@node Just Spaces,, Tab Stops, Indentation
@section Tabs vs. Spaces

@vindex indent-tabs-mode
  Emacs normally uses both tabs and spaces to indent lines.  If you prefer,
all indentation can be made from spaces only.  To request this, set
@code{indent-tabs-mode} to @code{nil}.  This is a per-buffer variable;
altering the variable affects only the current buffer, but there is a
default value which you can change as well.  @xref{Locals}.

@findex tabify
@findex untabify
  There are also commands to convert tabs to spaces or vice versa, always
preserving the columns of all non-blank text.  @kbd{M-x tabify} scans the
region for sequences of spaces, and converts sequences of at least three
spaces to tabs if that is possible without changing indentation.  @kbd{M-x
untabify} changes all tabs in the region to corresponding numbers of spaces.

repo_name: mthl/texinfo

license: mit


code:
@node Keystrokes, Pull-down Menus, Frame, Top
@chapter Keystrokes, Key Sequences, and Key Bindings

@iftex
  This chapter discusses the character set Emacs uses for input commands
and inside files.  You have already learned that the more frequently
used Emacs commands are bound to keys.  For example, @kbd{Control-f} is
bound to @code{forward-char}.  The following issues are covered:

@itemize @bullet
@item
How keystrokes can be represented
@item
How you can create key sequences from keystrokes
@item
How you can add to the available modifier keys by customizing your
keyboard: for example, you could have the
@key{Capslock} key be understood as the @key{Super} key by Emacs. A
@key{Super} key is used like @key{Control} or @key{Meta} in that you hold
it while typing another key.
@end itemize

 You will also learn how to customize existing key bindings and
create new ones.
@end iftex

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

@node Intro to Keystrokes, Representing Keystrokes, Keystrokes, Keystrokes
@section Keystrokes as Building Blocks of Key Sequences
@cindex character set
@cindex ASCII
@cindex keystroke

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

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

@cindex modifier key
@cindex keysym
@kindex meta key
@kindex control key
@kindex hyper key
@kindex super key
@kindex shift key
@kindex button1
@kindex button2
@kindex button3
@kindex button1up
@kindex button2up
@kindex button3up

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

  The rest of the keys on your keyboard, along with the mouse buttons,
make up the set of keysyms.  A keysym is usually what is printed on the
keys on your keyboard.  Here is a table of some of the symbolic names
for keysyms:
@table @kbd
@item a,b,c...
alphabetic keys
@item f1,f2...
function keys
@item button1
left mouse button
@item button2
middle mouse button
@item button3
right mouse button
@item button1up
upstroke on the left mouse button
@item button2up
upstroke on the middle mouse button
@item button3up
upstroke on the right mouse button
@item return
Return key
@end table

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

@node Representing Keystrokes, Key Sequences, Intro to Keystrokes, Keystrokes
@comment  node-name,  next,  previous,  up
@subsection Representing Keystrokes
@kindex hyper key
@kindex super key
@findex read-key-sequence

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

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

@table @kbd
@item (control a)
Pressing @key{CTRL} and @kbd{a} simultaneously.
@item (control ?a)
Another way of writing the keystroke @kbd{C-a}.
@item (control 65)
Yet another way of writing the keystroke @kbd{C-a}.
@item (break)
Pressing the @key{BREAK} key.
@item (control meta button2up)
Release the middle mouse button, while pressing @key{CTRL} and
@key{META}.
@end table
@cindex shift modifier
  Note: As you define keystrokes, you can use the @kbd{shift} key only
as a modifier with characters that do not have a second keysym on the
same key, such as @kbd{backspace} and @kbd{tab}.  It is an error to
define a keystroke using the @key{shift} modifier with keysyms such as
@kbd{a} and @kbd{=}.  The correct forms are @kbd{A} and @kbd{+}.

@node Key Sequences, String Key Sequences, Representing Keystrokes, Keystrokes
@subsection Representing Key Sequences

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

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

@example
  [(modifier .. modifier keysym) ... (modifier .. modifier keysym)]
@end example

  Here are some examples of complete key sequences:

@table @kbd
@item [(control c) (control a)]
Typing @kbd{C-c} followed by @kbd{C-a}
@item [(control c) (control 65)]
Typing @kbd{C-c} followed by @kbd{C-a}. (Using the ASCII code
for the character `a')@refill
@item [(control c) (break)]
Typing @kbd{C-c} followed by the @kbd{break} character.@refill
@end table

@kindex C-c
@kindex C-x
@kindex C-h
@kindex ESC
@cindex prefix key sequence

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

@itemize @bullet
@item
@kbd{[(control x) (c)]}
@item
@kbd{[(control x) (control c)]}
@end itemize

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

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

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

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

@node String Key Sequences, Meta Key, Key Sequences, Keystrokes
@comment  node-name,  next,  previous,  up
@subsection  String Key Sequences
For backward compatibility, you may also represent a key sequence using
strings.  For example, we have the following equivalent representations:

@table @kbd
@item "\C-c\C-c"
@code{[(control c) (control c)]}
@item "\e\C-c"
@code{[(meta control c)]}
@end table

@kindex LFD
@kindex TAB

@node Meta Key, Super and Hyper Keys, String Key Sequences, Keystrokes
@comment  node-name,  next,  previous,  up
@subsection Assignment of the @key{META} Key

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

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

If you are running under X and do not have a @key{META} key, it
is possible to reconfigure some other key to be a @key{META}
key.  @xref{Super and Hyper Keys}. @refill

@vindex meta-flag
  Emacs believes the terminal has a @key{META} key if the variable
@code{meta-flag} is non-@code{nil}.  Normally this is set automatically
according to the termcap entry for your terminal type.  However, sometimes
the termcap entry is wrong, and then it is useful to set this variable
yourself.  @xref{Variables}, for how to do this.

Note: If you are running under the X window system, the setting of
the @code{meta-flag} variable is irrelevant.

@node Super and Hyper Keys, Character Representation, Meta Key, Keystrokes
@comment  node-name,  next,  previous,  up
@subsection Assignment of the @key{SUPER} and @key{HYPER} Keys
@kindex hyper key
@kindex super key

  Most keyboards do not, by default, have @key{SUPER} or @key{HYPER}
modifier keys.  Under X, you can simulate the @key{SUPER} or
@key{HYPER} key if you want to bind keys to sequences using @kbd{super}
and @kbd{hyper}.  You can use the @code{xmodmap} program to do this.

  For example, to turn your @key{CAPS-LOCK} key into a @key{SUPER} key,
do the following:

  Create a file called @code{~/.xmodmap}.  In this file, place the lines

@example
        remove Lock = Caps_Lock
        keysym Caps_Lock = Super_L
        add Mod2 = Super_L
@end example

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

To create a @key{META} or @key{HYPER} key instead of a @key{SUPER} key,
replace the word @code{Super} above with @code{Meta} or @code{Hyper}.

Just after you start up X, execute the command @code{xmodmap /.xmodmap}.
You can add this command to the appropriate initialization file to have
the command executed automatically.@refill

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

@cindex keysyms
@cindex keycode

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

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

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

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

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

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

@cindex modifier mapping

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

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

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

A client needing to use an extra modifier, for example @code{Meta}, should:

@enumerate
@item
Scan the existing modifier mappings.

@enumerate
@item
If it finds a modifier that contains a keycode whose set of keysyms
includes @code{XK_Meta_L} or @code{XK_Meta_R}, it should use that
modifier bit.

@item
If there is no existing modifier controlled by @code{XK_Meta_L} or
@code{XK_Meta_R}, it should select an unused modifier bit (one with
an empty controlling set) and:
@end enumerate

@item
If there is a keycode with @code{XL_Meta_L} in its set of keysyms,
add that keycode to the set for the chosen modifier, and then:

@enumerate
@item
If there is a keycode with @code{XL_Meta_R} in its set of keysyms,
add that keycode to the set for the chosen modifier, and then:

@item
If the controlling set is still empty, interact with the user to
select one or more keys to be @code{Meta}.
@end enumerate

@item
If there are no unused modifier bits, ask the user to take corrective action.
@end enumerate

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

 Therefore, if you want to make a @key{META} key, the right way
is to make the keycode in question generate both a @code{Meta} keysym
and some previously-unassigned modifier bit.

@node Character Representation, Commands, Super and Hyper Keys, Keystrokes
@comment  node-name,  next,  previous,  up
@section Representation of Characters

This section briefly discusses how characters are represented in Emacs
buffers.  @xref{Key Sequences}, for information on representing key
sequences to create key bindings.

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

The variable @code{ctl-arrow} may be used to alter this behavior.
@xref{Display Vars}.

@node Commands, , Character Representation, Keystrokes
@section Keys and Commands

@cindex binding
@cindex customization
@cindex keymap
@cindex function
@cindex command
  This manual is full of passages that tell you what particular keys do.
But Emacs does not assign meanings to keys directly.  Instead, Emacs
assigns meanings to @dfn{functions}, and then gives keys their meanings
by @dfn{binding} them to functions.

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

  The bindings between keys and functions are recorded in various tables
called @dfn{keymaps}.  @xref{Key Bindings}, for more information on key
sequences you can bind commands to.  @xref{Keymaps}, for information on
creating keymaps.

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

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

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


code:
@iftex
@chapter Killing and Moving Text

  @dfn{Killing} means erasing text and copying it into the @dfn{kill ring},
from which it can be retrieved by @dfn{yanking} it.  Some other systems
that have recently become popular use the terms ``cutting'' and ``pasting''
for these operations.

  The most common way of moving or copying text with Emacs is to kill it
and later yank it in one or more places.  This is safe because all the
text killed recently is stored in the kill ring, and it is versatile,
because you can use the same commands for killing syntactic units and
for moving those units.  There are other ways of copying text for
special purposes.

  Emacs has only one kill ring, so you can kill text in one buffer and yank
it in another buffer. If you are using XEmacs under X, you can
also use the X selection mechanism to copy text from one buffer to
another, or between applications. @xref{Using X Selections}.

@end iftex

@node Killing, Yanking, Additional Mouse Operations, Top
@section Deletion and Killing
@findex delete-char
@findex delete-backward-char

@cindex killing
@cindex cutting
@cindex deletion
@kindex C-d
@kindex DEL
  Most commands that erase text from the buffer save it. You can get
the text back if you change your mind, or you can move or copy it to
other parts of the buffer.  Commands which erase text and save it in the
kill ring are known as @dfn{kill} commands.  Some other commands erase
text but do not save it; they are known as @dfn{delete} commands.  (This
distinction is made only for erasing text in the buffer.)

The commands' names and individual descriptions use the words
@samp{kill} and @samp{delete} to indicate what they do.  If you perform
a kill or delete command by mistake, use the @kbd{C-x u} (@code{undo})
command to undo it (@pxref{Undo}). The delete commands include @kbd{C-d}
(@code{delete-char}) and @key{DEL} (@code{delete-backward-char}), which
delete only one character at a time, and those commands that delete only
spaces or newlines.  Commands that can destroy significant amounts of
nontrivial data usually kill.@refill

@subsection Deletion

@table @kbd
@item C-d
Delete next character (@code{delete-char}).
@item @key{DEL}
Delete previous character (@code{delete-backward-char}).
@item M-\
Delete spaces and tabs around point (@code{delete-horizontal-space}).
@item M-@key{SPC}
Delete spaces and tabs around point, leaving one space
(@code{just-one-space}).
@item C-x C-o
Delete blank lines around the current line (@code{delete-blank-lines}).
@item M-^
Join two lines by deleting the intervening newline, and any indentation
following it (@code{delete-indentation}).
@end table

  The most basic delete commands are @kbd{C-d} (@code{delete-char}) and
@key{DEL} (@code{delete-backward-char}).  @kbd{C-d} deletes the
character after point, the one the cursor is ``on top of''.  Point
doesn't move.  @key{DEL} deletes the character before the cursor, and
moves point back.  You can delete newlines like any other characters in
the buffer; deleting a newline joins two lines.  Actually, @kbd{C-d} and
@key{DEL} aren't always delete commands; if you give them an argument,
they kill instead, since they can erase more than one character this
way.

@kindex M-\
@findex delete-horizontal-space
@kindex M-SPC
@findex just-one-space
@kindex C-x C-o
@findex delete-blank-lines
@kindex M-^
@findex delete-indentation
  The other delete commands delete only formatting characters: spaces,
tabs and newlines.  @kbd{M-\} (@code{delete-horizontal-space}) deletes
all spaces and tab characters before and after point.
@kbd{M-@key{SPC}} (@code{just-one-space}) does the same but leaves a
single space after point, regardless of the number of spaces that
existed previously (even zero).

  @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines after
the current line. If the current line is blank, it deletes all blank lines
preceding the current line as well as leaving one blank line, the current
line.  @kbd{M-^} (@code{delete-indentation}) joins the current line and
the previous line, or, if given an argument, joins the current line and
the next line by deleting a newline and all surrounding spaces, possibly
leaving a single space.  @xref{Indentation,M-^}.

@subsection Killing by Lines

@table @kbd
@item C-k
Kill rest of line or one or more lines (@code{kill-line}).
@end table

@kindex C-k
@findex kill-line
  The simplest kill command is @kbd{C-k}.  If given at the beginning of
a line, it kills all the text on the line, leaving the line blank.  If
given on a blank line, the blank line disappears.  As a consequence, a
line disappears completely if you go to the front of a non-blank line
and type @kbd{C-k} twice.

  More generally, @kbd{C-k} kills from point up to the end of the line,
unless it is at the end of a line.  In that case, it kills the newline
following the line, thus merging the next line into the current one.
Emacs ignores invisible spaces and tabs at the end of the line when deciding
which case applies: if point appears to be at the end of the line, you
can be sure the newline will be killed.

  If you give @kbd{C-k} a positive argument, it kills that many lines
and the newlines that follow them (however, text on the current line
before point is not killed).  With a negative argument, @kbd{C-k} kills
back to a number of line beginnings.  An argument of @minus{}2 means
kill back to the second line beginning.  If point is at the beginning of
a line, that line beginning doesn't count, so @kbd{C-u - 2 C-k} with
point at the front of a line kills the two previous lines.

  @kbd{C-k} with an argument of zero kills all the text before point on the
current line.

@subsection Other Kill Commands
@findex kill-region
@findex kill-word
@findex backward-kill-word
@findex kill-sexp
@findex kill-sentence
@findex backward-kill-sentence
@kindex M-d
@kindex M-DEL
@kindex C-M-k
@kindex C-x DEL
@kindex M-k
@kindex C-w

@c DoubleWideCommands
@table @kbd
@item C-w
Kill region (from point to the mark) (@code{kill-region}).
@xref{Words}.
@item M-d
Kill word (@code{kill-word}).
@item M-@key{DEL}
Kill word backwards (@code{backward-kill-word}).
@item C-x @key{DEL}
Kill back to beginning of sentence (@code{backward-kill-sentence}).
@xref{Sentences}.
@item M-k
Kill to end of sentence (@code{kill-sentence}).
@item C-M-k
Kill sexp (@code{kill-sexp}).  @xref{Lists}.
@item M-z @var{char}
Kill up to next occurrence of @var{char} (@code{zap-to-char}).
@end table

   @kbd{C-w} (@code{kill-region}) is a very general kill command; it
kills everything between point and the mark. You can use this command to
kill any contiguous sequence of characters by first setting the mark at
one end of a sequence of characters, then going to the other end and
typing @kbd{C-w}.

@kindex M-z
@findex zap-to-char
  A convenient way of killing is combined with searching: @kbd{M-z}
(@code{zap-to-char}) reads a character and kills from point up to (but not
including) the next occurrence of that character in the buffer.  If there
is no next occurrence, killing goes to the end of the buffer.  A numeric
argument acts as a repeat count.  A negative argument means to search
backward and kill text before point.

  Other syntactic units can be killed: words, with @kbd{M-@key{DEL}} and
@kbd{M-d} (@pxref{Words}); sexps, with @kbd{C-M-k} (@pxref{Lists}); and
sentences, with @kbd{C-x @key{DEL}} and @kbd{M-k}
(@pxref{Sentences}).@refill

@node Yanking, Using X Selections, Killing, Top
@section Yanking
@cindex moving text
@cindex copying text
@cindex kill ring
@cindex yanking
@cindex pasting

  @dfn{Yanking} means getting back text which was killed. Some systems
call this ``pasting''.  The usual way to move or copy text is to kill it
and then yank it one or more times.

@table @kbd
@item C-y
Yank last killed text (@code{yank}).
@item M-y
Replace re-inserted killed text with the previously killed text
(@code{yank-pop}).
@item M-w
Save region as last killed text without actually killing it
(@code{copy-region-as-kill}).
@item C-M-w
Append next kill to last batch of killed text (@code{append-next-kill}).
@end table

@menu
* Kill Ring::       Where killed text is stored.  Basic yanking.
* Appending Kills:: Several kills in a row all yank together.
* Earlier Kills::   Yanking something killed some time ago.
@end menu

@node Kill Ring, Appending Kills, Yanking, Yanking
@subsection The Kill Ring

@kindex C-y
@findex Yank
  All killed text is recorded in the @dfn{kill ring}, a list of blocks of
text that have been killed.  There is only one kill ring, used in all
buffers, so you can kill text in one buffer and yank it in another buffer.
This is the usual way to move text from one file to another.
(@xref{Accumulating Text}, for some other ways.)

  If you have two separate Emacs processes, you cannot use the kill ring
to move text. If you are using XEmacs under X, however, you can
use the X selection mechanism to move text from one to another.

If you are using XEmacs under X and have one Emacs process with
multiple frames, they do share the same kill ring.  You can kill or
copy text in one Emacs frame, then yank it in the other frame
belonging to the same process.

  The command @kbd{C-y} (@code{yank}) reinserts the text of the most recent
kill.  It leaves the cursor at the end of the text and sets the mark at
the beginning of the text.  @xref{Mark}.

  @kbd{C-u C-y} yanks the text, leaves the cursor in front of the text,
and sets the mark after it, if the argument is with just a @kbd{C-u}.
Any other argument, including @kbd{C-u} and digits, has different
results, described below, under ``Yanking Earlier Kills''.

@kindex M-w
@findex copy-region-as-kill
 To copy a block of text, you can also use @kbd{M-w}
(@code{copy-region-as-kill}), which copies the region into the kill ring
without removing it from the buffer. @kbd{M-w} is similar to @kbd{C-w}
followed by @kbd{C-y} but does not mark the buffer as ``modified'' and
does not actually cut anything.

@node Appending Kills, Earlier Kills, Kill Ring, Yanking
@subsection Appending Kills

@cindex television
  Normally, each kill command pushes a new block onto the kill ring.
However, two or more kill commands in a row combine their text into a
single entry, so that a single @kbd{C-y} yanks it all back. This means
you don't have to kill all the text you want to yank in one command; you
can kill line after line, or word after word, until you have killed what
you want, then get it all back at once using @kbd{C-y}. (Thus we join
television in leading people to kill thoughtlessly.)

  Commands that kill forward from point add onto the end of the previous
killed text.  Commands that kill backward from point add onto the
beginning.  This way, any sequence of mixed forward and backward kill
commands puts all the killed text into one entry without rearrangement.
Numeric arguments do not break the sequence of appending kills.  For
example, suppose the buffer contains:

@example
This is the first
line of sample text
and here is the third.
@end example

@noindent
with point at the beginning of the second line.  If you type @kbd{C-k C-u 2
M-@key{DEL} C-k}, the first @kbd{C-k} kills the text @samp{line of sample
text}, @kbd{C-u 2 M-@key{DEL}} kills @samp{the first} with the newline that
followed it, and the second @kbd{C-k} kills the newline after the second
line.  The result is that the buffer contains @samp{This is and here is the
third.} and a single kill entry contains @samp{the first@key{RET}line of
sample text@key{RET}}---all the killed text, in its original order.

@kindex C-M-w
@findex append-next-kill
  If a kill command is separated from the last kill command by other
commands (not just numeric arguments), it starts a new entry on the kill
ring.  To force a kill command to append, first type the command @kbd{C-M-w}
(@code{append-next-kill}). @kbd{C-M-w} tells the following command,
if it is a kill command, to append the text it kills to the last killed
text, instead of starting a new entry.  With @kbd{C-M-w}, you can kill
several separated pieces of text and accumulate them to be yanked back
in one place.@refill

@node Earlier Kills,, Appending Kills, Yanking
@subsection Yanking Earlier Kills

@kindex M-y
@findex yank-pop
  To recover killed text that is no longer the most recent kill, you need
the @kbd{Meta-y} (@code{yank-pop}) command.  You can use @kbd{M-y} only
after a @kbd{C-y} or another @kbd{M-y}.  It takes the text previously
yanked and replaces it with the text from an earlier kill.  To recover
the text of the next-to-the-last kill, first use @kbd{C-y} to recover
the last kill, then @kbd{M-y} to replace it with the previous
kill.@refill

  You can think in terms of a ``last yank'' pointer which points at an item
in the kill ring.  Each time you kill, the ``last yank'' pointer moves to
the new item at the front of the ring.  @kbd{C-y} yanks the item
which the ``last yank'' pointer points to.  @kbd{M-y} moves the ``last
yank'' pointer to a different item, and the text in the buffer changes to
match.  Enough @kbd{M-y} commands can move the pointer to any item in the
ring, so you can get any item into the buffer.  Eventually the pointer
reaches the end of the ring; the next @kbd{M-y} moves it to the first item
again.

  Yanking moves the ``last yank'' pointer around the ring, but does not
change the order of the entries in the ring, which always runs from the
most recent kill at the front to the oldest one still remembered.

  Use @kbd{M-y} with a numeric argument to advance the ``last
yank'' pointer by the specified number of items.  A negative argument
moves the pointer toward the front of the ring; from the front of the
ring, it moves to the last entry and starts moving forward from there.

  Once the text you are looking for is brought into the buffer, you can
stop doing @kbd{M-y} commands and the text will stay there. Since the
text is just a copy of the kill ring item, editing it in the buffer does
not change what's in the ring.  As long you don't kill additional text,
the ``last yank'' pointer remains at the same place in the kill ring:
repeating @kbd{C-y} will yank another copy of the same old kill.

  If you know how many @kbd{M-y} commands it would take to find the
text you want, you can yank that text in one step using @kbd{C-y} with
a numeric argument.  @kbd{C-y} with an argument greater than one
restores the text the specified number of entries back in the kill
ring.  Thus, @kbd{C-u 2 C-y} gets the next to the last block of killed
text.  It is equivalent to @kbd{C-y M-y}.  @kbd{C-y} with a numeric
argument starts counting from the ``last yank'' pointer, and sets the
``last yank'' pointer to the entry that it yanks.

@vindex kill-ring-max
  The variable @code{kill-ring-max} controls the length of the kill
ring; no more than that many blocks of killed text are saved.

@node Using X Selections, Accumulating Text, Yanking, Top
@section Using X Selections
@comment  node-name,  next,  previous,  up

In the X window system, mouse selections provide a simple mechanism for
text transfer between different applications.  In a typical X
application, you can select text by pressing the left mouse button and
dragging the cursor over the text you want to copy.  The text becomes the
primary X selection and is highlighted.  The highlighted region is also
the Emacs selected region.

@itemize @bullet
@item
Since the region is the primary X selection, you can go to a different X
application and click the middle mouse button: the text that you selected in
the previous application is pasted into the current application.
@item
Since the region is the Emacs selected region, you can use all region
commands (@kbd{C-w, M-w} etc.) as well as the options of the @b{Edit}
menu to manipulate the selected text.
@end itemize

@menu
* X Clipboard Selection::     	Pasting to the X clipboard.
* X Selection Commands::	Other operations on the selection.
* X Cut Buffers::       	X cut buffers are available for compatibility.
* Active Regions::      	Using zmacs-style highlighting of the
                        	 selected region.
@end menu

@node X Clipboard Selection, X Selection Commands, Using X Selections, Using X Selections
@comment  node-name,  next,  previous,  up
@subsection The Clipboard Selection
@cindex clipboard selections

There are other kinds of X selections besides the @b{Primary} selection; one
common one is the @b{Clipboard} selection.  Some applications prefer to
transfer data using this selection in preference to the @b{Primary}.
One can transfer text from the @b{Primary} selection to the  @b{Clipboard}
selection with the @b{Copy} command under the @b{Edit} menu in the menubar.

Usually, the clipboard selection is not visible.  However, if you run the
@file{xclipboard} application, the text most recently copied to the clipboard
(with the @b{Copy} command) is displayed in a window.  Any time new text is
thus copied, the @file{xclipboard} application makes a copy of it and displays
it in its window.  The value of the clipboard can survive the lifetime of the
running Emacs process.  The @code{xclipboard} man page provides more details.

Warning: If you use the @file{xclipboard} application, remember that it
maintains a list of all things that have been pasted to the clipboard (that
is, copied with the @b{Copy} command).  If you don't manually delete elements
from this list by clicking on the @b{Delete} button in the @code{xclipboard}
window, the clipboard will eventually consume a lot of memory.

In summary, some X applications (such as @file{xterm}) allow one to paste
text in them from XEmacs in the following way:

@itemize @bullet
@item
Drag out a region of text in Emacs with the left mouse button,
making that text be the @b{Primary} selection.

@item
Click the middle button in the other application, pasting the @b{Primary}
selection.
@end itemize

With some other applications (notably, the OpenWindows and Motif tools) you
must use this method instead:

@itemize @bullet
@item
Drag out a region of text in Emacs with the left mouse button,
making that text be the @b{Primary} selection.

@item
Copy the selected text to the @b{Clipboard} selection by selecting the
@b{Copy} menu item from the @b{Edit} menu, or by hitting the @b{Copy}
key on your keyboard.

@item
Paste the text in the other application by selecting @b{Paste} from its
menu, or by hitting the @b{Paste} key on your keyboard.
@end itemize

@node X Selection Commands, X Cut Buffers, X Clipboard Selection, Using X Selections
@subsection Miscellaneous X Selection Commands
@comment  node-name,  next,  previous,  up
@cindex cut buffers
@cindex primary selections

@findex x-copy-primary-selection
@findex x-delete-primary-selection
@findex x-insert-selection
@findex x-kill-primary-selection
@findex x-mouse-kill
@findex x-own-secondary-selection
@findex x-own-selection
@findex x-set-point-and-insert-selection
@table @kbd
@item M-x x-copy-primary-selection
Copy the primary selection to both the kill ring and the Clipboard.
@item M-x x-insert-selection
Insert the current selection into the buffer at point.
@item M-x x-delete-primary-selection
Deletes the text in the primary selection without copying it to the kill
ring or the Clipboard.
@item M-x x-kill-primary-selection
Deletes the text in the primary selection and copies it to
both the kill ring and the Clipboard.
@item M-x x-mouse-kill
Kill the text between point and the mouse and copy it to
the clipboard and to the cut buffer.
@item M-x x-own-secondary-selection
Make a secondary X selection of the given argument.
@item M-x x-own-selection
Make a primary X selection of the given argument.
@item M-x x-set-point-and-insert-selection
Set point where clicked and insert the primary selection or the
cut buffer.
@end table

@node X Cut Buffers, Active Regions, X Selection Commands, Using X Selections
@subsection X Cut Buffers
@comment  node-name,  next,  previous,  up

X cut buffers are a different, older way of transferring text between
applications.  XEmacs supports cut buffers for compatibility
with older programs, even though selections are now the preferred way of
transferring text.

X has a concept of applications "owning" selections.  When you select
text by clicking and dragging inside an application, the application
tells the X server that it owns the selection.  When another
application asks the X server for the value of the selection, the X
server requests the information from the owner. When you use
selections, the selection data is not actually transferred unless
someone wants it; the act of making a selection doesn't transfer data.
Cut buffers are different: when you "own" a cut buffer, the data is
actually transferred to the X server immediately, and survives the
lifetime of the application.

Any time a region of text becomes the primary selection in Emacs,
Emacs also copies that text to the cut buffer.  This makes it possible
to copy text from an XEmacs buffer and paste it into an older,
non-selection-based application (such as Emacs 18).

Note: Older versions of Emacs could not access the X selections, only
the X cut buffers.

@node Active Regions, , X Cut Buffers, Using X Selections
@subsection Active Regions
@comment  node-name,  next,  previous,  up
@cindex active regions

  By default, both the text you select in an Emacs buffer using the
click-and-drag mechanism and text you select by setting point and the
mark is highlighted. You can use Emacs region commands as well as the
@b{Cut} and @b{Copy} commands on the highlighted region you selected
with the mouse.

If you prefer, you can make a distinction between text selected with the
mouse and text selected with point and the mark by setting the variable
@code{zmacs-regions} to @code{nil}.  In that case:

@itemize @bullet
@item
The text selected with the mouse becomes both the X selection and the
Emacs selected region. You can use menu-bar commands as well as Emacs
region commands on it.
@item
The text selected with point and the mark is not highlighted. You can
only use Emacs region commands on it, not the menu-bar items.
@end itemize

  Active regions originally come from Zmacs, the Lisp Machine editor.
The idea behind them is that commands can only operate on a region when
the region is in an "active" state.  Put simply, you can only operate on
a region that is highlighted.

@vindex zmacs-regions
The variable @code{zmacs-regions} checks whether LISPM-style active
regions should be used.  This means that commands that operate on the
region (the area between point and the mark) only work while
the region is in the active state, which is indicated by highlighting.
Most commands causes the region to not be in the active state;
for example, @kbd{C-w} only works immediately after activating the
region.

More specifically:
@itemize @bullet
@item
Commands that operate on the region only work if the region is active.
@item
Only a very small set of commands causes the region to become active---
those commands whose semantics are to mark an area, such as @code{mark-defun}.
@item
The region is deactivated after each command that is executed, except that
motion commands do not change whether the region is active or not.
@end itemize

@code{set-mark-command} (@kbd{C-SPC}) pushes a mark and activates the
region.  Moving the cursor with normal motion commands (@kbd{C-n},
@kbd{C-p}, etc.) will cause the region between point and the
recently-pushed mark to be highlighted.  It will remain highlighted
until some non-motion command is executed.

@code{exchange-point-and-mark} (@kbd{C-x C-x}) activates the region.
So if you mark a region and execute a command that operates on it, you
can reactivate the same region with @kbd{C-x C-x} (or perhaps @kbd{C-x
C-x C-x C-x}) to operate on it again.

Generally, commands that push marks as a means of navigation, such as
@code{beginning-of-buffer} (@kbd{M-<}) and @code{end-of-buffer}
(@kbd{M->}), do not activate the region.  However, commands that push
marks as a means of marking an area of text, such as @code{mark-defun}
(@kbd{M-C-h}), @code{mark-word} (@kbd{M-@@}), and @code{mark-whole-buffer}
(@kbd{C-x h}), do activate the region.

When @code{zmacs-regions} is @code{t}, there is no distinction between
the primary X selection and the active region selected by point and the
mark.  To see this, set the mark (@key{C-SPC}) and move the cursor
with any cursor-motion command: the region between point and mark is
highlighted, and you can watch it grow and shrink as you move the
cursor.

Any other commands besides cursor-motion commands (such as inserting or
deleting text) will cause the region to no longer be active; it will no
longer be highlighted, and will no longer be the primary selection.
Region can be explicitly deactivated with @kbd{C-g}.

Commands that require a region (such as @kbd{C-w}) signal an error if
the region is not active.  Certain commands cause the region to be in
its active state.  The most common ones are @code{push-mark}
(@key{C-SPC}) and @code{exchange-point-and-mark} (@kbd{C-x C-x}).

@vindex zmacs-region-stays
When @code{zmacs-regions} is @code{t}, programs can be non-intrusive
on the state of the region by setting the variable @code{zmacs-region-stays}
to a non-@code{nil} value.  If you are writing a new Emacs command that
is conceptually a ``motion'' command and should not interfere with the
current highlightedness of the region, then you may set this variable.
It is reset to @code{nil} after each user command is executed.

@findex zmacs-activate-region
When @code{zmacs-regions} is @code{t}, programs can make the region between
point and mark go into the active (highlighted) state by using the
function @code{zmacs-activate-region}. Only a small number of commands
should ever do this.

@findex zmacs-deactivate-region
When @code{zmacs-regions} is @code{t}, programs can deactivate the region
between point and the mark by using @code{zmacs-deactivate-region}.
Note: you should not have to call this function; the command loop calls
it when appropriate.

@node Accumulating Text, Rectangles, Using X Selections, Top
@section Accumulating Text
@findex append-to-buffer
@findex prepend-to-buffer
@findex copy-to-buffer
@findex append-to-file
@cindex copying text
@cindex accumulating text

  Usually you copy or move text by killing it and yanking it, but there are
other ways that are useful for copying one block of text in many places, or
for copying many scattered blocks of text into one place.

  If you like, you can accumulate blocks of text from scattered
locations either into a buffer or into a file.  The relevant commands
are described here.  You can also use Emacs registers for storing and
accumulating text.  @xref{Registers}.

@table @kbd
@item M-x append-to-buffer
Append region to contents of specified buffer (@code{append-to-buffer}).
@item M-x prepend-to-buffer
Prepend region to contents of specified buffer.
@item M-x copy-to-buffer
Copy region into specified buffer, deleting that buffer's old contents.
@item M-x insert-buffer
Insert contents of specified buffer into current buffer at point.
@item M-x append-to-file
Append region to the end of the contents of specified file.
@end table

  To accumulate text into a buffer, use the command @kbd{M-x
append-to-buffer}, which inserts a copy of the region into the buffer
@var{buffername}, at the location of point in that buffer.  If there is
no buffer with the given name, one is created.

  If you append text to a buffer that has been used for editing, the
copied text goes to the place where point is.  Point in that buffer is
left at the end of the copied text, so successive uses of
@code{append-to-buffer} accumulate the text in the specified buffer in
the same order as they were copied.  Strictly speaking, this command does
not always append to the text already in the buffer; but if this command
is the only command used to alter a buffer, it does always append to the
existing text because point is always at the end.

  @kbd{M-x prepend-to-buffer} is similar to @code{append-to-buffer}, but
point in the other buffer is left before the copied text, so successive
prependings add text in reverse order.  @kbd{M-x copy-to-buffer} is
similar, except that any existing text in the other buffer is deleted,
so the buffer is left containing just the text newly copied into it.

  You can retrieve the accumulated text from that buffer with @kbd{M-x
insert-buffer}, which takes @var{buffername} as an argument.  It inserts
a copy of the text in buffer @var{buffername} into the selected buffer.
You could alternatively select the other buffer for editing, perhaps moving
text from it by killing or with @code{append-to-buffer}.  @xref{Buffers}, for
background information on buffers.

  Instead of accumulating text within Emacs in a buffer, you can append
text directly into a file with @kbd{M-x append-to-file}, which takes
@var{file-name} as an argument.  It adds the text of the region to the
end of the specified file.  The file is changed immediately on disk.
This command is normally used with files that are @i{not} being visited
in Emacs.  Using it on a file that Emacs is visiting can produce
confusing results, because the file's text inside Emacs does not change
while the file itself changes.

@node Rectangles, Registers, Accumulating Text, Top
@section Rectangles
@cindex rectangles

  The rectangle commands affect rectangular areas of text: all
characters between a certain pair of columns, in a certain range of lines.
Commands are provided to kill rectangles, yank killed rectangles, clear
them out, or delete them.  Rectangle commands are useful with text in
multicolumnar formats, like code with comments at the right,
or for changing text into or out of such formats.

  To specify the rectangle a command should work on, put the mark at one
corner and point at the opposite corner.  The specified rectangle is
called the @dfn{region-rectangle} because it is controlled about the
same way the region is controlled.  Remember that a given
combination of point and mark values can be interpreted either as
specifying a region or as specifying a rectangle; it is up to the
command that uses them to choose the interpretation.

@table @kbd
@item M-x delete-rectangle
Delete the text of the region-rectangle, moving any following text on
each line leftward to the left edge of the region-rectangle.
@item M-x kill-rectangle
Similar, but also save the contents of the region-rectangle as the
``last killed rectangle''.
@item M-x yank-rectangle
Yank the last killed rectangle with its upper left corner at point.
@item M-x open-rectangle
Insert blank space to fill the space of the region-rectangle.
The previous contents of the region-rectangle are pushed rightward.
@item M-x clear-rectangle
Clear the region-rectangle by replacing its contents with spaces.
@end table

  The rectangle operations fall into two classes: commands deleting and
moving rectangles, and commands for blank rectangles.

@findex delete-rectangle
@findex kill-rectangle
  There are two ways to get rid of the text in a rectangle: you can discard
the text (delete it) or save it as the ``last killed'' rectangle.  The
commands for these two ways are @kbd{M-x delete-rectangle} and @kbd{M-x
kill-rectangle}.  In either case, the portion of each line that falls inside
the rectangle's boundaries is deleted, causing following text (if any) on
the line to move left.

  Note that ``killing'' a rectangle is not killing in the usual sense; the
rectangle is not stored in the kill ring, but in a special place that
only records the most recently killed rectangle (that is, does not
append to a killed rectangle).  Different yank commands
have to be used and only one rectangle is stored, because yanking
a rectangle is quite different from yanking linear text and yank-popping
commands are difficult to make sense of.

  Inserting a rectangle is the opposite of deleting one.  You specify
where to put the upper left corner by putting point there.  The
rectangle's first line is inserted at point, the rectangle's second line
is inserted at a point one line vertically down, and so on.  The number
of lines affected is determined by the height of the saved rectangle.

@findex yank-rectangle
  To insert the last killed rectangle, type @kbd{M-x yank-rectangle}.
This can be used to convert single-column lists into double-column
lists; kill the second half of the list as a rectangle and then
yank it beside the first line of the list.

@findex open-rectangle
@findex clear-rectangle
  There are two commands for working with blank rectangles: @kbd{M-x
clear-rectangle} erases existing text, and @kbd{M-x open-rectangle}
inserts a blank rectangle.  Clearing a rectangle is equivalent to
deleting it and then inserting a blank rectangle of the same size.

  Rectangles can also be copied into and out of registers.
@xref{RegRect,,Rectangle Registers}.


code:
@node M-x, Help, Minibuffer, Top
@chapter Running Commands by Name

  The Emacs commands that are used often or that must be quick to type are
bound to keys---short sequences of characters---for convenient use.  Other
Emacs commands that are used more rarely are not bound to keys; to run
them, you must refer to them by name.

  A command name consists, by convention, of one or more words,
separated by hyphens: for example, @code{auto-fill-mode} or
@code{manual-entry}.  The use of English words makes the command name
easier to remember than a key made up of obscure characters, even though
it results in more characters to type.  You can run any command by name,
even if it can be run by keys as well.

@kindex M-x
@cindex minibuffer
 To run a command by name, start with @kbd{M-x}, then type the
command name, and finish with @key{RET}.  @kbd{M-x} uses the minibuffer
to read the command name.  @key{RET} exits the minibuffer and runs the
command.

  Emacs uses the minibuffer for reading input for many different purposes;
on this occasion, the string @samp{M-x} is displayed at the beginning of
the minibuffer as a @dfn{prompt} to remind you that your input should be
the name of a command to be run.  @xref{Minibuffer}, for full information
on the features of the minibuffer.

  You can use completion to enter a command name.  For example, to
invoke the command @code{forward-char}, type:

@example
M-x forward-char @key{RET}
@end example
or
@example
M-x fo @key{TAB} c @key{RET}
@end example

@noindent
After you type in @code{M-x fo TAB} emacs will give you a possible list of
completions from which you can choose. Note that @code{forward-char} is the
same command that you invoke with the key @kbd{C-f}.  You can call any
command (interactively callable function) defined in Emacs by its name
using @kbd{M-x} regardless of whether or not any keys are bound to it.

  If you type @kbd{C-g} while Emacs reads the command name, you cancel
the @kbd{M-x} command and get out of the minibuffer, ending up at top level.

  To pass a numeric argument to a command you are invoking with
@kbd{M-x}, specify the numeric argument before the @kbd{M-x}.  @kbd{M-x}
passes the argument along to the function that it calls.  The argument
value appears in the prompt while the command name is being read.

@findex interactive
You can use the command @code{M-x interactive} to specify a way of
parsing arguments for interactive use of a function.  For example, write:

@example
  (defun foo (arg) "Doc string" (interactive "p") ...use arg...)
@end example

to make @code{arg} be the prefix argument when @code{foo} is called as a
command.  The call to @code{interactive} is actually a declaration
rather than a function; it tells @code{call-interactively} how to read
arguments to pass to the function.  When actually called, @code{interactive}
returns @code{nil}.

The argument of @var{interactive} is usually a string containing a code
letter followed by a prompt.  Some code letters do not use I/O to get
the argument and do not need prompts.  To prompt for multiple arguments,
you must provide a code letter, its prompt, a newline, and another code
letter, and so forth.  If the argument is not a string, it is evaluated
to get a list of arguments to pass to the function.  If you do not provide an
argument to @code{interactive}, no arguments are passed when calling
interactively.

Available code letters are:

@table @code
@item a
Function name: symbol with a function definition
@item b
Name of existing buffer
@item B
Name of buffer, possibly nonexistent
@item c
Character
@item C
Command name: symbol with interactive function definition
@item d
Value of point as number (does not do I/O)
@item D
Directory name
@item e
Last mouse event
@item f
Existing file name
@item F
Possibly nonexistent file name
@item k
Key sequence (string)
@item m
Value of mark as number (does not do I/O)
@item n
Number read using minibuffer
@item N
Prefix arg converted to number, or if none, do like code @code{n}
@item p
Prefix arg converted to number (does not do I/O)
@item P
Prefix arg in raw form (does not do I/O)
@item r
Region: point and mark as two numeric arguments, smallest first (does
not do I/O)
@item s
Any string
@item S
Any symbol
@item v
Variable name: symbol that is @code{user-variable-p}
@item x
Lisp expression read but not evaluated
@item X
Lisp expression read and evaluated
@end table

In addition, if the string begins with @samp{*}, an error is
signaled if the buffer is read-only.  This happens before reading any
arguments.  If the string begins with @samp{@@}, the window the mouse is
over is selected before anything else is done.  You may use both
@samp{@@} and @samp{*}; they are processed in the order that they appear.

Normally, when describing a command that is run by name, we omit the
@key{RET} that is needed to terminate the name.  Thus we may refer to
@kbd{M-x auto-fill-mode} rather than @kbd{M-x auto-fill-mode} @key{RET}.
We mention the @key{RET} only when it is necessary to emphasize its
presence, for example, when describing a sequence of input that contains
a command name and arguments that follow it.

@findex execute-extended-command
  @kbd{M-x} is defined to run the command @code{execute-extended-command},
which is responsible for reading the name of another command and invoking
it.


code:
@node Major Modes, Indentation, Mule, Top
@chapter Major Modes
@cindex major modes
@kindex TAB
@kindex DEL
@kindex LFD

  Emacs has many different @dfn{major modes}, each of which customizes
Emacs for editing text of a particular sort.  The major modes are mutually
exclusive;  at any time, each buffer has one major mode.  The mode line
normally contains the name of the current major mode in parentheses.
@xref{Mode Line}.

  The least specialized major mode is called @dfn{Fundamental mode}.  This
mode has no mode-specific redefinitions or variable settings.  Each
Emacs command behaves in its most general manner, and each option is in its
default state.  For editing any specific type of text, such as Lisp code or
English text, you should switch to the appropriate major mode, such as Lisp
mode or Text mode.

  Selecting a major mode changes the meanings of a few keys to become
more specifically adapted to the language being edited.  @key{TAB},
@key{DEL}, and @key{LFD} are changed frequently.  In addition, commands
which handle comments use the mode to determine how to delimit comments.
Many major modes redefine the syntactical properties of characters
appearing in the buffer.  @xref{Syntax}.

  The major modes fall into three major groups.  Lisp mode (which has
several variants), C mode, and Muddle mode are for specific programming
languages.  Text mode, Nroff mode, @TeX{} mode, and Outline mode are for
editing English text.  The remaining major modes are not intended for use
on users' files; they are used in buffers created by Emacs for specific
purposes and include Dired mode for buffers made by Dired (@pxref{Dired}),
Mail mode for buffers made by @kbd{C-x m} (@pxref{Sending Mail}), and Shell
mode for buffers used for communicating with an inferior shell process
(@pxref{Interactive Shell}).

  Most programming language major modes specify that only blank lines
separate paragraphs.  This is so that the paragraph commands remain useful.
@xref{Paragraphs}.  They also cause Auto Fill mode to use the definition of
@key{TAB} to indent the new lines it creates.  This is because most lines
in a program are usually indented.  @xref{Indentation}.

@menu
* Choosing Modes::     How major modes are specified or chosen.
@end menu

@node Choosing Modes,,Major Modes,Major Modes
@section Choosing Major Modes

  You can select a major mode explicitly for the current buffer, but
most of the time Emacs determines which mode to use based on the file
name or some text in the file.

  Use a @kbd{M-x} command to explicitly select a new major mode.  Add
@code{-mode} to the name of a major mode to get the name of a command to
select that mode.  For example, to enter Lisp mode, execute @kbd{M-x
lisp-mode}.

@vindex auto-mode-alist
  When you visit a file, Emacs usually chooses the right major mode
based on the file's name.  For example, files whose names end in
@code{.c} are edited in C mode.  The variable @code{auto-mode-alist}
controls the correspondence between file names and major mode.  Its value
is a list in which each element has the form:

@example
(@var{regexp} . @var{mode-function})
@end example

@noindent
For example, one element normally found in the list has the form
@code{(@t{"\\.c$"} . c-mode)}. It is responsible for selecting C mode
for files whose names end in @file{.c}.  (Note that @samp{\\} is needed in
Lisp syntax to include a @samp{\} in the string, which is needed to
suppress the special meaning of @samp{.} in regexps.)  The only practical
way to change this variable is with Lisp code.

  You can specify which major mode should be used for editing a certain
file by a special sort of text in the first non-blank line of the file.
The mode name should appear in this line both preceded and followed by
@samp{-*-}.  Other text may appear on the line as well.  For example,

@example
;-*-Lisp-*-
@end example

@noindent
tells Emacs to use Lisp mode.  Note how the semicolon is used to make Lisp
treat this line as a comment.  Such an explicit specification overrides any
default mode based on the file name.

  Another format of mode specification is:

@example
-*-Mode: @var{modename};-*-
@end example

@noindent
which allows other things besides the major mode name to be specified.
However, Emacs does not look for anything except the mode name.

The major mode can also be specified in a local variables list.
@xref{File Variables}.

@vindex default-major-mode
  When you visit a file that does not specify a major mode to use, or
when you create a new buffer with @kbd{C-x b}, Emacs uses the major mode
specified by the variable @code{default-major-mode}.  Normally this
value is the symbol @code{fundamental-mode}, which specifies Fundamental
mode.  If @code{default-major-mode} is @code{nil}, the major mode is
taken from the previously selected buffer.