(User Interface, Basic Types): Document need to put some

[gnu-emacs] / man / commands.texi

diff --git a/man/commands.texi b/man/commands.texi
index 54ec50acfe890c6361f1b5e21a8e075856de22ec..d2daffe00bb7c344135efcd5db8f8b5d60b3ed6e 100644 (file)
--- a/man/commands.texi
+++ b/man/commands.texi
@@ -1,13 +1,14 @@
 @c This is part of the Emacs manual.
 @c This is part of the Emacs manual.

-@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
+@c   2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.

 @c See file emacs.texi for copying conditions.
 @iftex
 @chapter Characters, Keys and Commands
 
   This chapter explains the character sets used by Emacs for input
 @c See file emacs.texi for copying conditions.
 @iftex
 @chapter Characters, Keys and Commands
 
   This chapter explains the character sets used by Emacs for input

-commands and for the contents of files, and also explains the concepts
-of @dfn{keys} and @dfn{commands}, which are fundamental for understanding
-how Emacs interprets your keyboard and mouse input.
+commands and for the contents of files, and the fundamental concepts of
+@dfn{keys} and @dfn{commands}, whereby Emacs interprets your keyboard
+and mouse input.

 @end iftex
 
 @ifnottex
 @end iftex
 
 @ifnottex


@@ -24,9 +25,18 @@ how Emacs interprets your keyboard and mouse input.
 @cindex Control
 @cindex control characters
 
 @cindex Control
 @cindex control characters
 

-  GNU Emacs uses an extension of the @acronym{ASCII} character set for keyboard
-input; it also accepts non-character input events including function
-keys and mouse button actions.
+  GNU Emacs is designed for use with keyboard commands because that is
+the most efficient way to edit.  You can do editing with the mouse, as
+in other editors, and you can give commands with the menu bar and tool
+bar, and scroll with the scroll bar.  But if you keep on editing that
+way, you won't get the benefits of Emacs.  Therefore, this manual
+documents primarily how to edit with the keyboard.  You can force
+yourself to practice using the keyboard by using the shell command
+@samp{emacs -nw} to start Emacs, so that the mouse won't work.
+
+  Emacs uses an extension of the @acronym{ASCII} character set for
+keyboard input; it also accepts non-character input events including
+function keys and mouse button actions.

 
   @acronym{ASCII} consists of 128 character codes.  Some of these codes are
 assigned graphic symbols such as @samp{a} and @samp{=}; the rest are
 
   @acronym{ASCII} consists of 128 character codes.  Some of these codes are
 assigned graphic symbols such as @samp{a} and @samp{=}; the rest are


@@ -34,12 +44,11 @@ control characters, such as @kbd{Control-a} (usually written @kbd{C-a}
 for short).  @kbd{C-a} gets its name from the fact that you type it by
 holding down the @key{CTRL} key while pressing @kbd{a}.
 
 for short).  @kbd{C-a} gets its name from the fact that you type it by
 holding down the @key{CTRL} key while pressing @kbd{a}.
 

-  Some @acronym{ASCII} control characters have special names, and most terminals
-have special keys you can type them with: for example, @key{RET},
-@key{TAB}, @key{DEL} and @key{ESC}.  The space character is usually
-referred to below as @key{SPC}, even though strictly speaking it is a
-graphic character whose graphic happens to be blank.  Some keyboards
-have a key labeled ``linefeed'' which is an alias for @kbd{C-j}.
+  Some @acronym{ASCII} control characters have special names, and most
+terminals have special keys you can type them with: for example,
+@key{RET}, @key{TAB}, @key{DEL} and @key{ESC}.  The space character is
+usually known as @key{SPC}, even though strictly speaking it is a
+graphic character that is blank.

 
   Emacs extends the @acronym{ASCII} character set with thousands more printing
 characters (@pxref{International}), additional control characters, and a
 
   Emacs extends the @acronym{ASCII} character set with thousands more printing
 characters (@pxref{International}), additional control characters, and a


@@ -51,33 +60,30 @@ addition, the shift key is meaningless with control characters:
 @kbd{C-a} and @kbd{C-A} are the same character, and Emacs cannot
 distinguish them.
 
 @kbd{C-a} and @kbd{C-A} are the same character, and Emacs cannot
 distinguish them.
 

-  But the Emacs character set has room for control variants of all
-printing characters, and for distinguishing between @kbd{C-a} and
-@kbd{C-A}.  The X Window System makes it possible to enter all these
-characters.  For example, @kbd{C--} (that's Control-Minus) and @kbd{C-5}
-are meaningful Emacs commands under X.
+  The Emacs character set has room for control variants of all
+printing characters, and distinguishes @kbd{C-A} from @kbd{C-a}.
+Graphical terminals make it possible to enter all these characters.
+For example, @kbd{C--} (that's Control-Minus) and @kbd{C-5} are
+meaningful Emacs commands on a graphical terminal.

 
   Another Emacs character-set extension is additional modifier bits.
 Only one modifier bit is commonly used; it is called Meta.  Every
 character has a Meta variant; examples include @kbd{Meta-a} (normally
 
   Another Emacs character-set extension is additional modifier bits.
 Only one modifier bit is commonly used; it is called Meta.  Every
 character has a Meta variant; examples include @kbd{Meta-a} (normally

-written @kbd{M-a}, for short), @kbd{M-A} (not the same character as
-@kbd{M-a}, but those two characters normally have the same meaning in
-Emacs), @kbd{M-@key{RET}}, and @kbd{M-C-a}.  For reasons of tradition,
-we usually write @kbd{C-M-a} rather than @kbd{M-C-a}; logically
-speaking, the order in which the modifier keys @key{CTRL} and @key{META}
-are mentioned does not matter.
+written @kbd{M-a}, for short), @kbd{M-A} (different from @kbd{M-a},
+but they are normally equivalent in Emacs), @kbd{M-@key{RET}}, and
+@kbd{M-C-a}.  That last means @kbd{a} with both the @key{CTRL} and
+@key{META} modifiers.  We usually write it as @kbd{C-M-a} rather than
+@kbd{M-C-a}, for reasons of tradition.

 
 @cindex Meta
 @cindex M-
 @cindex @key{ESC} replacing @key{META} key
   Some terminals have a @key{META} key, and allow you to type Meta
 
 @cindex Meta
 @cindex M-
 @cindex @key{ESC} replacing @key{META} key
   Some terminals have a @key{META} key, and allow you to type Meta

-characters by holding this key down.  Thus, @kbd{Meta-a} is typed by
-holding down @key{META} and pressing @kbd{a}.  The @key{META} key
-works much 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.  Sometimes it is labeled
-@key{ALT} or @key{EDIT}; on a Sun keyboard, it may have a diamond on
-it.
+characters by holding this key down.  Thus, you can type @kbd{Meta-a}
+by holding down @key{META} and pressing @kbd{a}.  The @key{META} key
+works much like the @key{SHIFT} key.  In fact, this key is more often
+labeled @key{ALT} or @key{EDIT}, instead of @key{META}; on a Sun
+keyboard, it may have a diamond on it.

 
   If there is no @key{META} key, you can still type Meta characters
 using two-character sequences starting with @key{ESC}.  Thus, you can
 
   If there is no @key{META} key, you can still type Meta characters
 using two-character sequences starting with @key{ESC}.  Thus, you can


@@ -89,16 +95,16 @@ you press it and release it, then you enter the next character.
 @key{ESC} is allowed on terminals with @key{META} keys, too, in case
 you have formed a habit of using it.
 
 @key{ESC} is allowed on terminals with @key{META} keys, too, in case
 you have formed a habit of using it.
 

-  The X Window System provides several other modifier keys that can be
-applied to any input character.  These are called @key{SUPER},
-@key{HYPER} and @key{ALT}.  We write @samp{s-}, @samp{H-} and @samp{A-}
-to say that a character uses these modifiers.  Thus, @kbd{s-H-C-x} is
-short for @kbd{Super-Hyper-Control-x}.  Not all X terminals actually
+  Emacs defines several other modifier keys that can be applied to any
+input character.  These are called @key{SUPER}, @key{HYPER} and
+@key{ALT}.  We write @samp{s-}, @samp{H-} and @samp{A-} to say that a
+character uses these modifiers.  Thus, @kbd{s-H-C-x} is short for
+@kbd{Super-Hyper-Control-x}.  Not all graphical terminals actually

 provide keys for these modifier flags---in fact, many terminals have a
 key labeled @key{ALT} which is really a @key{META} key.  The standard
 key bindings of Emacs do not include any characters with these
 provide keys for these modifier flags---in fact, many terminals have a
 key labeled @key{ALT} which is really a @key{META} key.  The standard
 key bindings of Emacs do not include any characters with these

-modifiers.  But you can assign them meanings of your own by customizing
-Emacs.
+modifiers.  But you can assign them meanings of your own by
+customizing Emacs.

 
   If your keyboard lacks one of these modifier keys, you can enter it
 using @kbd{C-x @@}: @kbd{C-x @@ h} adds the ``hyper'' flag to the next
 
   If your keyboard lacks one of these modifier keys, you can enter it
 using @kbd{C-x @@}: @kbd{C-x @@ h} adds the ``hyper'' flag to the next


@@ -108,35 +114,44 @@ enter @kbd{Hyper-Control-a}.  (Unfortunately there is no way to add
 two modifiers by using @kbd{C-x @@} twice for the same character,
 because the first one goes to work on the @kbd{C-x}.)
 
 two modifiers by using @kbd{C-x @@} twice for the same character,
 because the first one goes to work on the @kbd{C-x}.)
 

-  Keyboard input includes keyboard keys that are not characters at all:
-for example function keys and arrow keys.  Mouse buttons are also
-outside the gamut of characters.  You can modify these events with the
-modifier keys @key{CTRL}, @key{META}, @key{SUPER}, @key{HYPER} and
-@key{ALT}, just like keyboard characters.
+  Keyboard input includes keyboard keys that are not characters at
+all, such as function keys and arrow keys.  Mouse buttons are also not
+characters.  However, you can modify these events with the modifier
+keys @key{CTRL}, @key{META}, @key{SUPER}, @key{HYPER} and @key{ALT},
+just like keyboard characters.

 
 @cindex input event
   Input characters and non-character inputs are collectively called
 @dfn{input events}.  @xref{Input Events,,, elisp, The Emacs Lisp
 
 @cindex input event
   Input characters and non-character inputs are collectively called
 @dfn{input events}.  @xref{Input Events,,, elisp, The Emacs Lisp

-Reference Manual}, for more information.  If you are not doing Lisp
-programming, but simply want to redefine the meaning of some characters
-or non-character events, see @ref{Customization}.
+Reference Manual}, for the full Lisp-level details.  If you are not
+doing Lisp programming, but simply want to redefine the meaning of
+some characters or non-character events, see @ref{Customization}.

 
   @acronym{ASCII} terminals cannot really send anything to the computer except
 @acronym{ASCII} characters.  These terminals use a sequence of characters to
 represent each function key.  But that is invisible to the Emacs user,
 
   @acronym{ASCII} terminals cannot really send anything to the computer except
 @acronym{ASCII} characters.  These terminals use a sequence of characters to
 represent each function key.  But that is invisible to the Emacs user,

-because the keyboard input routines recognize these special sequences
+because the keyboard input routines catch these special sequences

 and convert them to function key events before any other part of Emacs
 gets to see them.
 
 and convert them to function key events before any other part of Emacs
 gets to see them.
 

+@cindex keys stolen by window manager
+@cindex window manager, keys stolen by
+  On graphical displays, the window manager is likely to block the
+character @kbd{Meta-@key{TAB}} before Emacs can see it.  It may also
+block @kbd{Meta-@key{SPC}}, @kbd{C-M-d} and @kbd{C-M-l}.  If you have
+these problems, we recommend that you customize your window manager to
+turn off those commands, or put them on key combinations that Emacs
+does not use.
+

 @node Keys, Commands, User Input, Top
 @section Keys
 
 @cindex key sequence
 @cindex key
   A @dfn{key sequence} (@dfn{key}, for short) is a sequence of input
 @node Keys, Commands, User Input, Top
 @section Keys
 
 @cindex key sequence
 @cindex key
   A @dfn{key sequence} (@dfn{key}, for short) is a sequence of input

-events that are meaningful as a unit---as ``a single command.''  Some
-Emacs command sequences are just one character or one event; for
-example, just @kbd{C-f} is enough to move forward one character in the
+events that is meaningful as a unit---a ``single command.''  Some
+Emacs command sequences are invoked by just one character or one
+event; for example, just @kbd{C-f} moves forward one character in the

 buffer.  But Emacs also has commands that take two or more events to
 invoke.
 
 buffer.  But Emacs also has commands that take two or more events to
 invoke.
 


@@ -161,32 +176,33 @@ r}, are themselves prefix keys that lead to three-event key
 sequences.  There's no limit to the length of a key sequence, but in
 practice people rarely use sequences longer than four events.
 
 sequences.  There's no limit to the length of a key sequence, but in
 practice people rarely use sequences longer than four events.
 

-  By contrast, you can't add more events onto a complete key.  For
-example, the two-event sequence @kbd{C-f C-k} is not a key, because
-the @kbd{C-f} is a complete key in itself.  It's impossible to give
-@kbd{C-f C-k} an independent meaning as a command.  @kbd{C-f C-k} is two
-key sequences, not one.@refill
+  You can't add input events onto a complete key.  For example, the
+two-event sequence @kbd{C-f C-k} is not a key, because the @kbd{C-f}
+is a complete key in itself.  It's impossible to give @kbd{C-f C-k} an
+independent meaning as a command.  @kbd{C-f C-k} is two key sequences,
+not one.@refill

 
   All told, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-h},
 
   All told, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-h},

-@kbd{C-x}, @kbd{C-x @key{RET}}, @kbd{C-x @@}, @kbd{C-x a}, @kbd{C-x n}, @w{@kbd{C-x
-r}}, @kbd{C-x v}, @kbd{C-x 4}, @kbd{C-x 5}, @kbd{C-x 6}, @key{ESC}, and
-@kbd{M-g}.  But this list is not cast in concrete; it is
-just a matter of Emacs's standard key bindings.  If you customize Emacs,
-you can make new prefix keys, or eliminate these.  @xref{Key Bindings}.
-
-  If you do make or eliminate prefix keys, that changes the set of
+@kbd{C-x}, @kbd{C-x @key{RET}}, @kbd{C-x @@}, @kbd{C-x a}, @kbd{C-x
+n}, @w{@kbd{C-x r}}, @kbd{C-x v}, @kbd{C-x 4}, @kbd{C-x 5}, @kbd{C-x
+6}, @key{ESC}, @kbd{M-g}, and @kbd{M-o}.  (@key{F1} and @key{F2} are
+aliases for @kbd{C-h} and @kbd{C-x 6}.)  This list is not cast in stone;
+it describes the standard key bindings.  If you customize Emacs, you can make
+new prefix keys, or eliminate some of the standard ones (not
+recommended for most users).  @xref{Key Bindings}.
+
+  If you make or eliminate prefix keys, that changes the set of

 possible key sequences.  For example, if you redefine @kbd{C-f} as a
 possible key sequences.  For example, if you redefine @kbd{C-f} as a

-prefix, @kbd{C-f C-k} automatically becomes a key (complete, unless you
-define that too as a prefix).  Conversely, if you remove the prefix
-definition of @kbd{C-x 4}, then @kbd{C-x 4 f} (or @kbd{C-x 4
-@var{anything}}) is no longer a key.
-
-  Typing the help character (@kbd{C-h} or @key{F1}) after a prefix
-key displays a list of the commands starting with that prefix.
-There are a few prefix keys for which @kbd{C-h} does not
-work---for historical reasons, they have other meanings for @kbd{C-h}
-which are not easy to change.  But @key{F1} should work for all prefix
-keys.
+prefix, @kbd{C-f C-k} automatically becomes a key (complete, unless
+you define that too as a prefix).  Conversely, if you remove the
+prefix definition of @kbd{C-x 4}, then @kbd{C-x 4 f} and @kbd{C-x 4
+@var{anything}} are no longer keys.
+
+  Typing the help character (@kbd{C-h} or @key{F1}) after a prefix key
+displays a list of the commands starting with that prefix.  There are
+a few prefix keys after which @kbd{C-h} does not work---for historical
+reasons, they define other meanings for @kbd{C-h} which are painful to
+change.  @key{F1} works after all prefix keys.

 
 @node Commands, Text Characters, Keys, Top
 @section Keys and Commands
 
 @node Commands, Text Characters, Keys, Top
 @section Keys and Commands


@@ -199,59 +215,65 @@ do.  But Emacs does not assign meanings to keys directly.  Instead,
 Emacs assigns meanings to named @dfn{commands}, and then gives keys
 their meanings by @dfn{binding} them to commands.
 
 Emacs assigns meanings to named @dfn{commands}, and then gives keys
 their meanings by @dfn{binding} them to commands.
 

-  Every command has a name chosen by a programmer.  The name is usually
-made of a few English words separated by dashes; for example,
+  Every command has a name chosen by a programmer.  The name is
+usually made of a few English words separated by dashes; for example,

 @code{next-line} or @code{forward-word}.  A command also has a
 @code{next-line} or @code{forward-word}.  A command also has a

-@dfn{function definition} which is a Lisp program; this is what makes
-the command do what it does.  In Emacs Lisp, a command is actually a
-special kind of Lisp function; one which specifies how to read arguments
-for it and call it interactively.  For more information on commands and
-functions, see @ref{What Is a Function,, What Is a Function, elisp, The
-Emacs Lisp Reference Manual}.  (The definition we use in this manual is
-simplified slightly.)
+@dfn{function definition} which is a Lisp program; this is how the
+command does its work.  In Emacs Lisp, a command is a Lisp function with
+special options to read arguments and for interactive use.  For more
+information on commands and functions, see @ref{What Is a Function,,
+What Is a Function, elisp, The Emacs Lisp Reference Manual}.  (The
+definition here is simplified slightly.)

 
 

-  The bindings between keys and commands are recorded in various tables
-called @dfn{keymaps}.  @xref{Keymaps}.
+  The bindings between keys and commands are recorded in tables called
+@dfn{keymaps}.  @xref{Keymaps}.

 
   When we say that ``@kbd{C-n} moves down vertically one line'' we are
 
   When we say that ``@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.  It is the command
-@code{next-line} that is programmed to move down vertically.  @kbd{C-n} has
-this effect @emph{because} it is bound to that command.  If you rebind
-@kbd{C-n} to the command @code{forward-word} then @kbd{C-n} will move
-forward by words instead.  Rebinding keys is a common method of
-customization.@refill
-
-  In the rest of this manual, we usually ignore this subtlety to keep
-things simple.  To give the information needed for customization, we
-state the name of the command which 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 normally bound to it.
-
-  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 examines the variable
-and behaves differently according to the value that you set.  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}.
+glossing over a subtle distinction that is irrelevant in ordinary use,
+but vital for Emacs customization.  The command @code{next-line} does
+a vertical move downward.  @kbd{C-n} has this effect @emph{because} it
+is bound to @code{next-line}.  If you rebind @kbd{C-n} to the command
+@code{forward-word}, @kbd{C-n} will move forward one word instead.
+Rebinding keys is an important method of customization.
+
+  In the rest of this manual, we usually ignore this distinction to
+keep things simple.  We will often speak of keys like @kbd{C-n} as
+commands, even though strictly speaking the key is bound to a command.
+Usually we state the name of the command which 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 the command @code{next-line} moves
+vertically down, and the key @kbd{C-n} is normally bound to it.
+
+  Since we are discussing customization, we should 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 store a value.  Most of the variables documented in this
+manual are meant for customization: some command or other part of
+Emacs examines the variable and behaves differently according to the
+value that you set.  You can ignore the information about variables
+until you are interested in customizing them.  Then read the basic
+information on variables (@pxref{Variables}) and the information about
+specific variables will make sense.

 
 @node Text Characters, Entering Emacs, Commands, Top
 @section Character Set for Text
 @cindex characters (in text)
 
 
 @node Text Characters, Entering Emacs, Commands, Top
 @section Character Set for Text
 @cindex characters (in text)
 

-  Text in Emacs buffers is a sequence of 8-bit bytes.  Each byte can
-hold a single @acronym{ASCII} character.  Both @acronym{ASCII} control characters (octal
-codes 000 through 037, and 0177) and @acronym{ASCII} printing characters (codes
-040 through 0176) are allowed; however, non-@acronym{ASCII} control characters
-cannot appear in a buffer.  The other modifier flags used in keyboard
-input, such as Meta, are not allowed in buffers either.
+  Text in Emacs buffers is a sequence of characters.  In the simplest
+case, these are @acronym{ASCII} characters, each stored in one 8-bit
+byte.  Both @acronym{ASCII} control characters (octal codes 000
+through 037, and 0177) and @acronym{ASCII} printing characters (codes
+040 through 0176) are allowed.  The other modifier flags used in
+keyboard input, such as Meta, are not allowed in buffers.
+
+  Non-@acronym{ASCII} printing characters can also appear in buffers,
+when multibyte characters are enabled.  They have character codes
+starting at 256, octal 0400, and each one is represented as a sequence
+of two or more bytes.  @xref{International}.  Single-byte characters
+with codes 128 through 255 can also appear in multibyte buffers.
+However, non-@acronym{ASCII} control characters cannot appear in a
+buffer.

 
   Some @acronym{ASCII} control characters serve special purposes in text, and have
 special names.  For example, the newline character (octal code 012) is
 
   Some @acronym{ASCII} control characters serve special purposes in text, and have
 special names.  For example, the newline character (octal code 012) is


@@ -259,16 +281,9 @@ used in the buffer to end a line, and the tab character (octal code 011)
 is used for indenting to the next tab stop column (normally every 8
 columns).  @xref{Text Display}.
 
 is used for indenting to the next tab stop column (normally every 8
 columns).  @xref{Text Display}.
 

-  Non-@acronym{ASCII} printing characters can also appear in buffers.  When
-multibyte characters are enabled, you can use any of the non-@acronym{ASCII}
-printing characters that Emacs supports.  They have character codes
-starting at 256, octal 0400, and each one is represented as a sequence
-of two or more bytes.  @xref{International}.  Single-byte characters
-with codes 128 through 255 can also appear in multibyte buffers.
-

   If you disable multibyte characters, then you can use only one
   If you disable multibyte characters, then you can use only one

-alphabet of non-@acronym{ASCII} characters, but they all fit in one byte.  They
-use codes 0200 through 0377.  @xref{Single-Byte Character Support}.
+alphabet of non-@acronym{ASCII} characters, which all fit in one byte.
+They use octal codes 0200 through 0377.  @xref{Unibyte Mode}.

 
 @ifnottex
 @lowersections
 
 @ifnottex
 @lowersections