comparison man/custom.texi @ 52979:3649390c0f91

Replace @sc{ascii} and ASCII with @acronym{ASCII}.

52978:1a5c50faf357

* Minibuffer Maps::     The minibuffer uses its own local keymaps.
* Rebinding::           How to redefine one key's meaning conveniently.
* Init Rebinding::      Rebinding keys with your init file, @file{.emacs}.
* Function Keys::       Rebinding terminal function keys.
* Named ASCII Chars::   Distinguishing @key{TAB} from @kbd{C-i}, and so on.
* Non-ASCII Rebinding:: Rebinding non-ASCII characters such as Latin-1.
* Mouse Buttons::       Rebinding mouse buttons in Emacs.
* Disabling::           Disabling a command means confirmation is required
                          before it can be executed.  This is done to protect
                          beginners from surprises.
@end menu

  If you have a set of key bindings that you like to use all the time,
you can specify them in your @file{.emacs} file by using their Lisp
syntax.  (@xref{Init File}.)

  The simplest method for doing this works for ASCII characters and
Meta-modified ASCII characters only.  This method uses a string to
represent the key sequence you want to rebind.  For example, here's how
to bind @kbd{C-z} to @code{shell}:

@example
(global-set-key "\C-z" 'shell)

@example
(global-set-key "\C-x\t" 'indent-rigidly)
@end example

  These examples show how to write some other special ASCII characters
in strings for key bindings:

@example
(global-set-key "\r" 'newline)               ;; @key{RET}
(global-set-key "\d" 'delete-backward-char)  ;; @key{DEL}
(global-set-key "\C-x\e\e" 'repeat-complex-command)  ;; @key{ESC}
@end example

  When the key sequence includes function keys or mouse button events,
or non-ASCII characters such as @code{C-=} or @code{H-a}, you must use
the more general method of rebinding, which uses a vector to specify the
key sequence.

  The way to write a vector in Emacs Lisp is with square brackets around
the vector elements.  Use spaces to separate the elements.  If an

delimiters or punctuation are needed.  If a vector element is a
character, write it as a Lisp character constant: @samp{?} followed by
the character as it would appear in a string.

  Here are examples of using vectors to rebind @kbd{C-=} (a control
character not in ASCII), @kbd{C-M-=} (not in ASCII because @kbd{C-=}
is not), @kbd{H-a} (a Hyper character; ASCII doesn't have Hyper at
all), @key{F7} (a function key), and @kbd{C-Mouse-1} (a
keyboard-modified mouse button):

@example
(global-set-key [?\C-=] 'make-symbolic-link)

As you see, you represent a multi-character key sequence with a vector
by listing each of the characters within the square brackets that
delimit the vector.

  Language and coding systems can cause problems with key bindings
for non-ASCII characters.  @xref{Non-ASCII Rebinding}.

@node Function Keys
@subsection Rebinding Function Keys

  Key sequences can contain function keys as well as ordinary

X) may use different names.  To make certain what symbol is used for a
given function key on your terminal, type @kbd{C-h c} followed by that
key.

  A key sequence which contains function key symbols (or anything but
ASCII characters) must be a vector rather than a string.  The vector
syntax uses spaces between the elements, and square brackets around the
whole vector.  Thus, to bind function key @samp{f1} to the command
@code{rmail}, write the following:

@example

@example
(global-set-key [H-M-right] 'forward-word)
@end example

@node Named ASCII Chars
@subsection Named ASCII Control Characters

  @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL}
started out as names for certain ASCII control characters, used so often
that they have special keys of their own.  Later, users found it
convenient to distinguish in Emacs between these keys and the ``same''
control characters typed with the @key{CTRL} key.

  Emacs distinguishes these two kinds of input, when the keyboard
reports these keys to Emacs.  It treats the ``special'' keys as function
keys named @code{tab}, @code{return}, @code{backspace}, @code{linefeed},
@code{escape}, and @code{delete}.  These function keys translate
automatically into the corresponding ASCII characters @emph{if} they
have no bindings of their own.  As a result, neither users nor Lisp
programs need to pay attention to the distinction unless they care to.

  If you do not want to distinguish between (for example) @key{TAB} and
@kbd{C-i}, make just one binding, for the ASCII character @key{TAB}
(octal code 011).  If you do want to distinguish, make one binding for
this ASCII character, and another for the ``function key'' @code{tab}.

  With an ordinary ASCII terminal, there is no way to distinguish
between @key{TAB} and @kbd{C-i} (and likewise for other such pairs),
because the terminal sends the same character in both cases.

@node Non-ASCII Rebinding
@subsection Non-ASCII Characters on the Keyboard
@cindex rebinding non-ASCII keys
@cindex non-ASCII keys, binding

If your keyboard has keys that send non-ASCII characters, such as
accented letters, rebinding these keys is a bit tricky.  There are two
solutions you can use.  One is to specify a keyboard coding system,
using @code{set-keyboard-coding-system} (@pxref{Specify Coding}).
Then you can bind these keys in the usual way@footnote{Note that you
should avoid the string syntax for binding 8-bit characters, since

@end example

@noindent
Type @kbd{C-q} followed by the key you want to bind, to insert @var{char}.

Since this puts a non-ASCII character in the @file{.emacs}, you should
specify the proper coding system for that file.  @xref{Init Syntax}.
Specify the same coding system for the file that you use for your
keyboard.

If you don't specify a keyboard coding system, that approach won't

the terminal.  Keyboard translations take place at the lowest level of
input processing; the keys that are looked up in keymaps contain the
characters that result from keyboard translation.

  On a window system, the keyboard key named @key{DELETE} is a function
key and is distinct from the ASCII character named @key{DEL}.
@xref{Named ASCII Chars}.  Keyboard translations affect only ASCII
character input, not function keys; thus, the above example used on a
window system does not affect the @key{DELETE} key.  However, the
translation above isn't necessary on window systems, because Emacs can
also distinguish between the @key{BACKSPACE} key and @kbd{C-h}; and it
normally treats @key{BACKSPACE} as @key{DEL}.

@samp{\@var{ooo}} for the character whose octal code is @var{ooo}.
Backslash and double-quote are the only characters for which backslash
sequences are mandatory.

@samp{\C-} can be used as a prefix for a control character, as in
@samp{\C-s} for ASCII control-S, and @samp{\M-} can be used as a prefix for
a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for
@kbd{Control-Meta-A}.@refill

@cindex international characters in @file{.emacs}
@cindex non-ASCII characters in @file{.emacs}
If you want to include non-ASCII characters in strings in your init
file, you should consider putting a @w{@samp{-*-coding:
@var{coding-system}-*-}} tag on the first line which states the coding
system used to save your @file{.emacs}, as explained in @ref{Recognize
Coding}.  This is because the defaults for decoding non-ASCII text might
not yet be set up by the time Emacs reads those parts of your init file
which use such strings, possibly leading Emacs to decode those strings
incorrectly.

@item Characters:

Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}.  Note that
strings and characters are not interchangeable in Lisp; some contexts
require one and some contexts require the other.

@xref{Non-ASCII Rebinding}, for information about binding commands to
keys which send non-ASCII characters.

@item True:
@code{t} stands for `true'.

@item False:

52979:3649390c0f91

* Minibuffer Maps::     The minibuffer uses its own local keymaps.
* Rebinding::           How to redefine one key's meaning conveniently.
* Init Rebinding::      Rebinding keys with your init file, @file{.emacs}.
* Function Keys::       Rebinding terminal function keys.
* Named ASCII Chars::   Distinguishing @key{TAB} from @kbd{C-i}, and so on.
* Non-ASCII Rebinding:: Rebinding non-@acronym{ASCII} characters such as Latin-1.
* Mouse Buttons::       Rebinding mouse buttons in Emacs.
* Disabling::           Disabling a command means confirmation is required
                          before it can be executed.  This is done to protect
                          beginners from surprises.
@end menu

  If you have a set of key bindings that you like to use all the time,
you can specify them in your @file{.emacs} file by using their Lisp
syntax.  (@xref{Init File}.)

  The simplest method for doing this works for @acronym{ASCII} characters and
Meta-modified @acronym{ASCII} characters only.  This method uses a string to
represent the key sequence you want to rebind.  For example, here's how
to bind @kbd{C-z} to @code{shell}:

@example
(global-set-key "\C-z" 'shell)

@example
(global-set-key "\C-x\t" 'indent-rigidly)
@end example

  These examples show how to write some other special @acronym{ASCII} characters
in strings for key bindings:

@example
(global-set-key "\r" 'newline)               ;; @key{RET}
(global-set-key "\d" 'delete-backward-char)  ;; @key{DEL}
(global-set-key "\C-x\e\e" 'repeat-complex-command)  ;; @key{ESC}
@end example

  When the key sequence includes function keys or mouse button events,
or non-@acronym{ASCII} characters such as @code{C-=} or @code{H-a}, you must use
the more general method of rebinding, which uses a vector to specify the
key sequence.

  The way to write a vector in Emacs Lisp is with square brackets around
the vector elements.  Use spaces to separate the elements.  If an

delimiters or punctuation are needed.  If a vector element is a
character, write it as a Lisp character constant: @samp{?} followed by
the character as it would appear in a string.

  Here are examples of using vectors to rebind @kbd{C-=} (a control
character not in @acronym{ASCII}), @kbd{C-M-=} (not in @acronym{ASCII} because @kbd{C-=}
is not), @kbd{H-a} (a Hyper character; @acronym{ASCII} doesn't have Hyper at
all), @key{F7} (a function key), and @kbd{C-Mouse-1} (a
keyboard-modified mouse button):

@example
(global-set-key [?\C-=] 'make-symbolic-link)

As you see, you represent a multi-character key sequence with a vector
by listing each of the characters within the square brackets that
delimit the vector.

  Language and coding systems can cause problems with key bindings
for non-@acronym{ASCII} characters.  @xref{Non-ASCII Rebinding}.

@node Function Keys
@subsection Rebinding Function Keys

  Key sequences can contain function keys as well as ordinary

X) may use different names.  To make certain what symbol is used for a
given function key on your terminal, type @kbd{C-h c} followed by that
key.

  A key sequence which contains function key symbols (or anything but
@acronym{ASCII} characters) must be a vector rather than a string.  The vector
syntax uses spaces between the elements, and square brackets around the
whole vector.  Thus, to bind function key @samp{f1} to the command
@code{rmail}, write the following:

@example

@example
(global-set-key [H-M-right] 'forward-word)
@end example

@node Named ASCII Chars
@subsection Named @acronym{ASCII} Control Characters

  @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL}
started out as names for certain @acronym{ASCII} control characters, used so often
that they have special keys of their own.  Later, users found it
convenient to distinguish in Emacs between these keys and the ``same''
control characters typed with the @key{CTRL} key.

  Emacs distinguishes these two kinds of input, when the keyboard
reports these keys to Emacs.  It treats the ``special'' keys as function
keys named @code{tab}, @code{return}, @code{backspace}, @code{linefeed},
@code{escape}, and @code{delete}.  These function keys translate
automatically into the corresponding @acronym{ASCII} characters @emph{if} they
have no bindings of their own.  As a result, neither users nor Lisp
programs need to pay attention to the distinction unless they care to.

  If you do not want to distinguish between (for example) @key{TAB} and
@kbd{C-i}, make just one binding, for the @acronym{ASCII} character @key{TAB}
(octal code 011).  If you do want to distinguish, make one binding for
this @acronym{ASCII} character, and another for the ``function key'' @code{tab}.

  With an ordinary @acronym{ASCII} terminal, there is no way to distinguish
between @key{TAB} and @kbd{C-i} (and likewise for other such pairs),
because the terminal sends the same character in both cases.

@node Non-ASCII Rebinding
@subsection Non-@acronym{ASCII} Characters on the Keyboard
@cindex rebinding non-@acronym{ASCII} keys
@cindex non-@acronym{ASCII} keys, binding

If your keyboard has keys that send non-@acronym{ASCII} characters, such as
accented letters, rebinding these keys is a bit tricky.  There are two
solutions you can use.  One is to specify a keyboard coding system,
using @code{set-keyboard-coding-system} (@pxref{Specify Coding}).
Then you can bind these keys in the usual way@footnote{Note that you
should avoid the string syntax for binding 8-bit characters, since

@end example

@noindent
Type @kbd{C-q} followed by the key you want to bind, to insert @var{char}.

Since this puts a non-@acronym{ASCII} character in the @file{.emacs}, you should
specify the proper coding system for that file.  @xref{Init Syntax}.
Specify the same coding system for the file that you use for your
keyboard.

If you don't specify a keyboard coding system, that approach won't

the terminal.  Keyboard translations take place at the lowest level of
input processing; the keys that are looked up in keymaps contain the
characters that result from keyboard translation.

  On a window system, the keyboard key named @key{DELETE} is a function
key and is distinct from the @acronym{ASCII} character named @key{DEL}.
@xref{Named ASCII Chars}.  Keyboard translations affect only @acronym{ASCII}
character input, not function keys; thus, the above example used on a
window system does not affect the @key{DELETE} key.  However, the
translation above isn't necessary on window systems, because Emacs can
also distinguish between the @key{BACKSPACE} key and @kbd{C-h}; and it
normally treats @key{BACKSPACE} as @key{DEL}.

@samp{\@var{ooo}} for the character whose octal code is @var{ooo}.
Backslash and double-quote are the only characters for which backslash
sequences are mandatory.

@samp{\C-} can be used as a prefix for a control character, as in
@samp{\C-s} for @acronym{ASCII} control-S, and @samp{\M-} can be used as a prefix for
a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for
@kbd{Control-Meta-A}.@refill

@cindex international characters in @file{.emacs}
@cindex non-@acronym{ASCII} characters in @file{.emacs}
If you want to include non-@acronym{ASCII} characters in strings in your init
file, you should consider putting a @w{@samp{-*-coding:
@var{coding-system}-*-}} tag on the first line which states the coding
system used to save your @file{.emacs}, as explained in @ref{Recognize
Coding}.  This is because the defaults for decoding non-@acronym{ASCII} text might
not yet be set up by the time Emacs reads those parts of your init file
which use such strings, possibly leading Emacs to decode those strings
incorrectly.

@item Characters:

Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}.  Note that
strings and characters are not interchangeable in Lisp; some contexts
require one and some contexts require the other.

@xref{Non-ASCII Rebinding}, for information about binding commands to
keys which send non-@acronym{ASCII} characters.

@item True:
@code{t} stands for `true'.

@item False: