[Emacs-diffs] Changes to emacs/man/commands.texi

[Richard M. Stallman]

Index: emacs/man/commands.texi
diff -u emacs/man/commands.texi:1.22 emacs/man/commands.texi:1.23
--- emacs/man/commands.texi:1.22        Wed Feb  8 02:25:09 2006
+++ emacs/man/commands.texi     Wed May  3 23:20:33 2006
@@ -6,9 +6,9 @@
 @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
address@hidden and @dfn{commands}, whereby Emacs interprets your keyboard
+and mouse input.
 @end iftex
 
 @ifnottex
@@ -35,11 +35,11 @@
 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},
address@hidden, @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 @acronym{ASCII} control characters have special names, and most
+terminals have special keys you can type them with: for example,
address@hidden, @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
@@ -51,11 +51,11 @@
 @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
address@hidden  Graphical terminals make it possible to enter all these
-characters.  For example, @kbd{C--} (that's Control-Minus) and
address@hidden are meaningful Emacs commands on a graphical terminal.
+  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
@@ -106,10 +106,10 @@
 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.  However, you can modify these events
-with the modifier keys @key{CTRL}, @key{META}, @key{SUPER},
address@hidden and @key{ALT}, just as you can modify keyboard characters.
+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
@@ -121,7 +121,7 @@
   @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.
 
@@ -131,9 +131,9 @@
 @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.
 
@@ -158,33 +158,33 @@
 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
address@hidden C-k} an independent meaning as a command.  @kbd{C-f C-k} is two
-key sequences, not address@hidden
+  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 address@hidden
 
   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}, @address@hidden 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}.)  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 some
-of the standard ones.  @xref{Key Bindings}.
+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 do make or eliminate prefix keys, that changes the set of
+  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
-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
address@hidden) is no longer a key.
+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
address@hidden 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 for which @kbd{C-h} does not work---for historical
+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.  But @key{F1} should work for all prefix keys.
+change.  @key{F1} works after all prefix keys.
 
 @node Commands, Text Characters, Keys, Top
 @section Keys and Commands
@@ -197,61 +197,65 @@
 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
address@hidden 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.)
address@hidden 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
address@hidden  @xref{Keymaps}.
 
   When we say that address@hidden 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
address@hidden that is programmed to move down vertically.  @kbd{C-n} has
-this effect @emph{because} it is bound to that command.  If you rebind
address@hidden to the command @code{forward-word} then @kbd{C-n} will move
-forward by words instead.  Rebinding keys is a common method of
address@hidden
+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
address@hidden, @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 a key is bound to some
-command.  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
address@hidden''  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}.
+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
address@hidden  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)
 
-  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, address@hidden 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.
+
+  address@hidden 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, address@hidden 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
@@ -259,16 +263,9 @@
 is used for indenting to the next tab stop column (normally every 8
 columns).  @xref{Text Display}.
 
-  address@hidden printing characters can also appear in buffers.  When
-multibyte characters are enabled, you can use any of the address@hidden
-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
-alphabet of address@hidden characters, but they all fit in one byte.  They
-use codes 0200 through 0377.  @xref{Unibyte Mode}.
+alphabet of address@hidden characters, which all fit in one byte.
+They use octal codes 0200 through 0377.  @xref{Unibyte Mode}.
 
 @ifnottex
 @lowersections