This is ../info/emacs, produced by makeinfo version 4.0 from emacs.texi.
This is the Fourteenth edition of the `GNU Emacs Manual', updated
for Emacs version 21.1.
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Emacs: (emacs). The extensible self-documenting text editor.
END-INFO-DIR-ENTRY
Published by the Free Software Foundation 59 Temple Place, Suite 330
Boston, MA 02111-1307 USA
Copyright (C) 1985,
1986,1987,1993,1994,1995,1996,1997,1998,1999,2000,2001 Free Software
Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "The GNU Manifesto", "Distribution" and "GNU
GENERAL PUBLIC LICENSE", with the Front-Cover texts being "A GNU
Manual," and with the Back-Cover Texts as in (a) below. A copy of the
license is included in the section entitled "GNU Free Documentation
License."
(a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development."
File: emacs, Node: Speedbar, Next: Multiple Displays, Prev: Frame Commands, Up: Frames
Making and Using a Speedbar Frame
=================================
An Emacs frame can have a "speedbar", which is a vertical window
that serves as a scrollable menu of files you could visit and tags
within those files. To create a speedbar, type `M-x speedbar'; this
creates a speedbar window for the selected frame. From then on, you can
click on a file name in the speedbar to visit that file in the
corresponding Emacs frame, or click on a tag name to jump to that tag in
the Emacs frame.
Initially the speedbar lists the immediate contents of the current
directory, one file per line. Each line also has a box, `[+]' or
`<+>', that you can click on with `Mouse-2' to "open up" the contents
of that item. If the line names a directory, opening it adds the
contents of that directory to the speedbar display, underneath the
directory's own line. If the line lists an ordinary file, opening it up
adds a list of the tags in that file to the speedbar display. When a
file is opened up, the `[+]' changes to `[-]'; you can click on that
box to "close up" that file (hide its contents).
Some major modes, including Rmail mode, Info, and GUD, have
specialized ways of putting useful items into the speedbar for you to
select. For example, in Rmail mode, the speedbar shows a list of Rmail
files, and lets you move the current message to another Rmail file by
clicking on its `<M>' box.
A speedbar belongs to one Emacs frame, and always operates on that
frame. If you use multiple frames, you can make a speedbar for some or
all of the frames; type `M-x speedbar' in any given frame to make a
speedbar for it.
File: emacs, Node: Multiple Displays, Next: Special Buffer Frames, Prev: Speedbar, Up: Frames
Multiple Displays
=================
A single Emacs can talk to more than one X display. Initially, Emacs
uses just one display--the one specified with the `DISPLAY' environment
variable or with the `--display' option (*note Initial Options::). To
connect to another display, use the command `make-frame-on-display':
`M-x make-frame-on-display <RET> DISPLAY <RET>'
Create a new frame on display DISPLAY.
A single X server can handle more than one screen. When you open
frames on two screens belonging to one server, Emacs knows they share a
single keyboard, and it treats all the commands arriving from these
screens as a single stream of input.
When you open frames on different X servers, Emacs makes a separate
input stream for each server. This way, two users can type
simultaneously on the two displays, and Emacs will not garble their
input. Each server also has its own selected frame. The commands you
enter with a particular X server apply to that server's selected frame.
Despite these features, people using the same Emacs job from
different displays can still interfere with each other if they are not
careful. For example, if any one types `C-x C-c', that exits the Emacs
job for all of them!
File: emacs, Node: Special Buffer Frames, Next: Frame Parameters, Prev: Multiple Displays, Up: Frames
Special Buffer Frames
=====================
You can make certain chosen buffers, for which Emacs normally creates
a second window when you have just one window, appear in special frames
of their own. To do this, set the variable
`special-display-buffer-names' to a list of buffer names; any buffer
whose name is in that list automatically gets a special frame, when an
Emacs command wants to display it "in another window."
For example, if you set the variable this way,
(setq special-display-buffer-names
'("*Completions*" "*grep*" "*tex-shell*"))
then completion lists, `grep' output and the TeX mode shell buffer get
individual frames of their own. These frames, and the windows in them,
are never automatically split or reused for any other buffers. They
continue to show the buffers they were created for, unless you alter
them by hand. Killing the special buffer deletes its frame
automatically.
More generally, you can set `special-display-regexps' to a list of
regular expressions; then a buffer gets its own frame if its name
matches any of those regular expressions. (Once again, this applies
only to buffers that normally get displayed for you in a separate
window.)
The variable `special-display-frame-alist' specifies the frame
parameters for these frames. It has a default value, so you don't need
to set it.
For those who know Lisp, an element of
`special-display-buffer-names' or `special-display-regexps' can also be
a list. Then the first element is the buffer name or regular
expression; the rest of the list specifies how to create the frame. It
can be an association list specifying frame parameter values; these
values take precedence over parameter values specified in
`special-display-frame-alist'. Alternatively, it can have this form:
(FUNCTION ARGS...)
where FUNCTION is a symbol. Then the frame is constructed by calling
FUNCTION; its first argument is the buffer, and its remaining arguments
are ARGS.
An analogous feature lets you specify buffers which should be
displayed in the selected window. *Note Force Same Window::. The
same-window feature takes precedence over the special-frame feature;
therefore, if you add a buffer name to `special-display-buffer-names'
and it has no effect, check to see whether that feature is also in use
for the same buffer name.
File: emacs, Node: Frame Parameters, Next: Scroll Bars, Prev: Special Buffer Frames, Up: Frames
Setting Frame Parameters
========================
This section describes commands for altering the display style and
window management behavior of the selected frame.
`M-x set-foreground-color <RET> COLOR <RET>'
Specify color COLOR for the foreground of the selected frame.
(This also changes the foreground color of the default face.)
`M-x set-background-color <RET> COLOR <RET>'
Specify color COLOR for the background of the selected frame.
(This also changes the background color of the default face.)
`M-x set-cursor-color <RET> COLOR <RET>'
Specify color COLOR for the cursor of the selected frame.
`M-x set-mouse-color <RET> COLOR <RET>'
Specify color COLOR for the mouse cursor when it is over the
selected frame.
`M-x set-border-color <RET> COLOR <RET>'
Specify color COLOR for the border of the selected frame.
`M-x list-colors-display'
Display the defined color names and show what the colors look like.
This command is somewhat slow.
`M-x auto-raise-mode'
Toggle whether or not the selected frame should auto-raise.
Auto-raise means that every time you move the mouse onto the
frame, it raises the frame.
Note that this auto-raise feature is implemented by Emacs itself.
Some window managers also implement auto-raise. If you enable
auto-raise for Emacs frames in your X window manager, it should
work, but it is beyond Emacs's control and therefore
`auto-raise-mode' has no effect on it.
`M-x auto-lower-mode'
Toggle whether or not the selected frame should auto-lower.
Auto-lower means that every time you move the mouse off the frame,
the frame moves to the bottom of the stack of X windows.
The command `auto-lower-mode' has no effect on auto-lower
implemented by the X window manager. To control that, you must use
the appropriate window manager features.
`M-x set-frame-font <RET> FONT <RET>'
Specify font FONT as the principal font for the selected frame.
The principal font controls several face attributes of the
`default' face (*note Faces::). For example, if the principal font
has a height of 12 pt, all text will be drawn in 12 pt fonts,
unless you use another face that specifies a different height.
*Note Font X::, for ways to list the available fonts on your
system.
You can also set a frame's principal font through a pop-up menu.
Press `S-Mouse-1' to activate this menu.
In Emacs versions that use an X toolkit, the color-setting and
font-setting functions don't affect menus and the menu bar, since they
are displayed by their own widget classes. To change the appearance of
the menus and menu bar, you must use X resources (*note Resources X::).
*Note Colors X::, regarding colors. *Note Font X::, regarding choice of
font.
Colors, fonts, and other attributes of the frame's display can also
be customized by setting frame parameters in the variable
`default-frame-alist' (*note Creating Frames::). For a detailed
description of frame parameters and customization, see *Note Frame
Parameters: (elisp)Frame Parameters.
File: emacs, Node: Scroll Bars, Next: Wheeled Mice, Prev: Frame Parameters, Up: Frames
Scroll Bars
===========
When using X, Emacs normally makes a "scroll bar" at the left of
each Emacs window.(1) The scroll bar runs the height of the window, and
shows a moving rectangular inner box which represents the portion of
the buffer currently displayed. The entire height of the scroll bar
represents the entire length of the buffer.
You can use `Mouse-2' (normally, the middle button) in the scroll
bar to move or drag the inner box up and down. If you move it to the
top of the scroll bar, you see the top of the buffer. If you move it to
the bottom of the scroll bar, you see the bottom of the buffer.
The left and right buttons in the scroll bar scroll by controlled
increments. `Mouse-1' (normally, the left button) moves the line at
the level where you click up to the top of the window. `Mouse-3'
(normally, the right button) moves the line at the top of the window
down to the level where you click. By clicking repeatedly in the same
place, you can scroll by the same distance over and over.
If you are using Emacs's own implementation of scroll bars, as
opposed to scroll bars from an X toolkit, you can also click
`C-Mouse-2' in the scroll bar to split a window vertically. The split
occurs on the line where you click.
You can enable or disable Scroll Bar mode with the command `M-x
scroll-bar-mode'. With no argument, it toggles the use of scroll bars.
With an argument, it turns use of scroll bars on if and only if the
argument is positive. This command applies to all frames, including
frames yet to be created. Customize the option `scroll-bar-mode' to
control the use of scroll bars at startup. You can use it to specify
that they are placed at the right of windows if you prefer that. You
can use the X resource `verticalScrollBars' to control the initial
setting of Scroll Bar mode similarly. *Note Resources X::.
To enable or disable scroll bars for just the selected frame, use the
`M-x toggle-scroll-bar' command.
You can control the scroll bar width by changing the value of the
`scroll-bar-width' frame parameter.
---------- Footnotes ----------
(1) Placing it at the left is usually more useful with overlapping
frames with text starting at the left margin.
File: emacs, Node: Wheeled Mice, Next: Menu Bars, Prev: Scroll Bars, Up: Frames
Scrolling With "Wheeled" Mice
=============================
Some mice have a "wheel" instead of a third button. You can usually
click the wheel to act as either `Mouse-2' or `Mouse-3', depending on
the setup. You can also use the wheel to scroll windows instead of
using the scroll bar or keyboard commands. To do so, turn on Mouse
Wheel global minor mode with the command `M-x mouse-wheel-mode' or by
customizing the option `mouse-wheel-mode'. Support for the wheel
depends on the system generating appropriate events for Emacs.
The variables `mouse-wheel-follow-mouse' and
`mouse-wheel-scroll-amount' determine where and by how much buffers are
scrolled.
File: emacs, Node: Menu Bars, Next: Tool Bars, Prev: Wheeled Mice, Up: Frames
Menu Bars
=========
You can turn display of menu bars on or off with `M-x menu-bar-mode'
or by customizing the option `menu-bar-mode'. With no argument, this
command toggles Menu Bar mode, a minor mode. With an argument, the
command turns Menu Bar mode on if the argument is positive, off if the
argument is not positive. You can use the X resource `menuBarLines' to
control the initial setting of Menu Bar mode. *Note Resources X::.
Expert users often turn off the menu bar, especially on text-only
terminals, where this makes one additional line available for text. If
the menu bar is off, you can still pop up a menu of its contents with
`C-Mouse-3' on a display which supports pop-up menus. *Note Menu Mouse
Clicks::.
*Note Menu Bar::, for information on how to invoke commands with the
menu bar.
File: emacs, Node: Tool Bars, Next: Dialog Boxes, Prev: Menu Bars, Up: Frames
Tool Bars
=========
The "tool bar" is a line (or multiple lines) of icons at the top of
the Emacs window. You can click on these icons with the mouse to do
various jobs.
The global tool bar contains general commands. Some major modes
define their own tool bars to replace it. A few "special" modes that
are not designed for ordinary editing remove some items from the global
tool bar.
Tool bars work only on a graphical display. The tool bar uses
colored XPM icons if Emacs was built with XPM support. Otherwise, the
tool bar uses monochrome icons (PBM or XBM format).
You can turn display of tool bars on or off with `M-x tool-bar-mode'.
File: emacs, Node: Dialog Boxes, Next: Tooltips, Prev: Tool Bars, Up: Frames
Using Dialog Boxes
==================
A dialog box is a special kind of menu for asking you a yes-or-no
question or some other special question. Many Emacs commands use a
dialog box to ask a yes-or-no question, if you used the mouse to invoke
the command to begin with.
You can customize the option `use-dialog-box' to suppress the use of
dialog boxes. This also controls whether to use file selection windows
(but those are not supported on all platforms).
File: emacs, Node: Tooltips, Next: Mouse Avoidance, Prev: Dialog Boxes, Up: Frames
Tooltips (or "Balloon Help")
============================
Tooltips are small X windows displaying a help string at the current
mouse position, typically over text--including the mode line--which can
be activated with the mouse or other keys. (This facility is sometimes
known as "balloon help".) Help text may be available for menu items
too.
To use tooltips, enable Tooltip mode with the command `M-x
tooltip-mode'. The customization group `tooltip' controls various
aspects of how tooltips work. When Tooltip mode is disabled, the help
text is displayed in the echo area instead.
As of Emacs 21.1, tooltips are not supported on MS-Windows. So help
text always appears in the echo area.
File: emacs, Node: Mouse Avoidance, Next: Non-Window Terminals, Prev: Tooltips, Up: Frames
Mouse Avoidance
===============
Mouse Avoidance mode keeps the window system mouse pointer away from
point, to avoid obscuring text. Whenever it moves the mouse, it also
raises the frame. To use Mouse Avoidance mode, customize the option
`mouse-avoidance-mode'. You can set this to various values to move the
mouse in several ways:
`banish'
Move the mouse to the upper-right corner on any key-press;
`exile'
Move the mouse to the corner only if the cursor gets too close,
and allow it to return once the cursor is out of the way;
`jump'
If the cursor gets too close to the mouse, displace the mouse a
random distance & direction;
`animate'
As `jump', but shows steps along the way for illusion of motion;
`cat-and-mouse'
The same as `animate';
`proteus'
As `animate', but changes the shape of the mouse pointer too.
You can also use the command `M-x mouse-avoidance-mode' to enable
the mode.
File: emacs, Node: Non-Window Terminals, Next: XTerm Mouse, Prev: Mouse Avoidance, Up: Frames
Non-Window Terminals
====================
If your terminal does not have a window system that Emacs supports,
then it can display only one Emacs frame at a time. However, you can
still create multiple Emacs frames, and switch between them. Switching
frames on these terminals is much like switching between different
window configurations.
Use `C-x 5 2' to create a new frame and switch to it; use `C-x 5 o'
to cycle through the existing frames; use `C-x 5 0' to delete the
current frame.
Each frame has a number to distinguish it. If your terminal can
display only one frame at a time, the selected frame's number N appears
near the beginning of the mode line, in the form `FN'.
`FN' is actually the frame's name. You can also specify a different
name if you wish, and you can select a frame by its name. Use the
command `M-x set-frame-name <RET> NAME <RET>' to specify a new name for
the selected frame, and use `M-x select-frame-by-name <RET> NAME <RET>'
to select a frame according to its name. The name you specify appears
in the mode line when the frame is selected.
File: emacs, Node: XTerm Mouse, Prev: Non-Window Terminals, Up: Frames
Using a Mouse in Terminal Emulators
===================================
Some terminal emulators under X support mouse clicks in the terminal
window. In a terminal emulator which is compatible with `xterm', you
can use `M-x xterm-mouse-mode' to enable simple use of the mouse--only
single clicks are supported. The normal `xterm' mouse functionality is
still available by holding down the `SHIFT' key when you press the
mouse button. The Linux console supports this mode if it has support
for the mouse enabled, e.g. using the `gpm' daemon.
File: emacs, Node: International, Next: Major Modes, Prev: Frames, Up: Top
International Character Set Support
***********************************
Emacs supports a wide variety of international character sets,
including European variants of the Latin alphabet, as well as Chinese,
Cyrillic, Devanagari (Hindi and Marathi), Ethiopic, Greek, Hebrew, IPA,
Japanese, Korean, Lao, Thai, Tibetan, and Vietnamese scripts. These
features have been merged from the modified version of Emacs known as
MULE (for "MULti-lingual Enhancement to GNU Emacs")
Emacs also supports various encodings of these characters used by
other internationalized software, such as word processors and mailers.
Emacs allows editing text with international characters by supporting
all the related activities:
* You can visit files with non-ASCII characters, save non-ASCII
text, and pass non-ASCII text between Emacs and programs it
invokes (such as compilers, spell-checkers, and mailers). Setting
your language environment (*note Language Environments::) takes
care of setting up the coding systems and other options for a
specific language or culture. Alternatively, you can specify how
Emacs should encode or decode text for each command; see *Note
Specify Coding::.
* You can display non-ASCII characters encoded by the various
scripts. This works by using appropriate fonts on X and similar
graphics displays (*note Defining Fontsets::), and by sending
special codes to text-only displays (*note Specify Coding::). If
some characters are displayed incorrectly, refer to *Note
Undisplayable Characters::, which describes possible problems and
explains how to solve them.
* You can insert non-ASCII characters or search for them. To do
that, you can specify an input method (*note Select Input
Method::) suitable for your language, or use the default input
method set up when you set your language environment. (Emacs
input methods are part of the Leim package, which must be
installed for you to be able to use them.) If your keyboard can
produce non-ASCII characters, you can select an appropriate
keyboard coding system (*note Specify Coding::), and Emacs will
accept those characters. Latin-1 characters can also be input by
using the `C-x 8' prefix, see *Note C-x 8: Single-Byte Character
Support.
The rest of this chapter describes these issues in detail.
* Menu:
* International Chars:: Basic concepts of multibyte characters.
* Enabling Multibyte:: Controlling whether to use multibyte characters.
* Language Environments:: Setting things up for the language you use.
* Input Methods:: Entering text characters not on your keyboard.
* Select Input Method:: Specifying your choice of input methods.
* Multibyte Conversion:: How single-byte characters convert to multibyte.
* Coding Systems:: Character set conversion when you read and
write files, and so on.
* Recognize Coding:: How Emacs figures out which conversion to use.
* Specify Coding:: Various ways to choose which conversion to use.
* Fontsets:: Fontsets are collections of fonts
that cover the whole spectrum of characters.
* Defining Fontsets:: Defining a new fontset.
* Undisplayable Characters:: When characters don't display.
* Single-Byte Character Support::
You can pick one European character set
to use without multibyte characters.
File: emacs, Node: International Chars, Next: Enabling Multibyte, Up: International
Introduction to International Character Sets
============================================
The users of international character sets and scripts have
established many more-or-less standard coding systems for storing
files. Emacs internally uses a single multibyte character encoding, so
that it can intermix characters from all these scripts in a single
buffer or string. This encoding represents each non-ASCII character as
a sequence of bytes in the range 0200 through 0377. Emacs translates
between the multibyte character encoding and various other coding
systems when reading and writing files, when exchanging data with
subprocesses, and (in some cases) in the `C-q' command (*note Multibyte
Conversion::).
The command `C-h h' (`view-hello-file') displays the file
`etc/HELLO', which shows how to say "hello" in many languages. This
illustrates various scripts. If some characters can't be displayed on
your terminal, they appear as `?' or as hollow boxes (*note
Undisplayable Characters::).
Keyboards, even in the countries where these character sets are used,
generally don't have keys for all the characters in them. So Emacs
supports various "input methods", typically one for each script or
language, to make it convenient to type them.
The prefix key `C-x <RET>' is used for commands that pertain to
multibyte characters, coding systems, and input methods.
File: emacs, Node: Enabling Multibyte, Next: Language Environments, Prev: International Chars, Up: International
Enabling Multibyte Characters
=============================
You can enable or disable multibyte character support, either for
Emacs as a whole, or for a single buffer. When multibyte characters are
disabled in a buffer, then each byte in that buffer represents a
character, even codes 0200 through 0377. The old features for
supporting the European character sets, ISO Latin-1 and ISO Latin-2,
work as they did in Emacs 19 and also work for the other ISO 8859
character sets.
However, there is no need to turn off multibyte character support to
use ISO Latin; the Emacs multibyte character set includes all the
characters in these character sets, and Emacs can translate
automatically to and from the ISO codes.
By default, Emacs starts in multibyte mode, because that allows you
to use all the supported languages and scripts without limitations.
To edit a particular file in unibyte representation, visit it using
`find-file-literally'. *Note Visiting::. To convert a buffer in
multibyte representation into a single-byte representation of the same
characters, the easiest way is to save the contents in a file, kill the
buffer, and find the file again with `find-file-literally'. You can
also use `C-x <RET> c' (`universal-coding-system-argument') and specify
`raw-text' as the coding system with which to find or save a file.
*Note Specify Coding::. Finding a file as `raw-text' doesn't disable
format conversion, uncompression and auto mode selection as
`find-file-literally' does.
To turn off multibyte character support by default, start Emacs with
the `--unibyte' option (*note Initial Options::), or set the
environment variable `EMACS_UNIBYTE'. You can also customize
`enable-multibyte-characters' or, equivalently, directly set the
variable `default-enable-multibyte-characters' to `nil' in your init
file to have basically the same effect as `--unibyte'.
To convert a unibyte session to a multibyte session, set
`default-enable-multibyte-characters' to `t'. Buffers which were
created in the unibyte session before you turn on multibyte support
will stay unibyte. You can turn on multibyte support in a specific
buffer by invoking the command `toggle-enable-multibyte-characters' in
that buffer.
With `--unibyte', multibyte strings are not created during
initialization from the values of environment variables, `/etc/passwd'
entries etc. that contain non-ASCII 8-bit characters.
Emacs normally loads Lisp files as multibyte, regardless of whether
you used `--unibyte'. This includes the Emacs initialization file,
`.emacs', and the initialization files of Emacs packages such as Gnus.
However, you can specify unibyte loading for a particular Lisp file, by
putting `-*-unibyte: t;-*-' in a comment on the first line. Then that
file is always loaded as unibyte text, even if you did not start Emacs
with `--unibyte'. The motivation for these conventions is that it is
more reliable to always load any particular Lisp file in the same way.
However, you can load a Lisp file as unibyte, on any one occasion, by
typing `C-x <RET> c raw-text <RET>' immediately before loading it.
The mode line indicates whether multibyte character support is
enabled in the current buffer. If it is, there are two or more
characters (most often two dashes) before the colon near the beginning
of the mode line. When multibyte characters are not enabled, just one
dash precedes the colon.
File: emacs, Node: Language Environments, Next: Input Methods, Prev: Enabling Multibyte, Up: International
Language Environments
=====================
All supported character sets are supported in Emacs buffers whenever
multibyte characters are enabled; there is no need to select a
particular language in order to display its characters in an Emacs
buffer. However, it is important to select a "language environment" in
order to set various defaults. The language environment really
represents a choice of preferred script (more or less) rather than a
choice of language.
The language environment controls which coding systems to recognize
when reading text (*note Recognize Coding::). This applies to files,
incoming mail, netnews, and any other text you read into Emacs. It may
also specify the default coding system to use when you create a file.
Each language environment also specifies a default input method.
To select a language environment, customize the option
`current-language-environment' or use the command `M-x
set-language-environment'. It makes no difference which buffer is
current when you use this command, because the effects apply globally to
the Emacs session. The supported language environments include:
Chinese-BIG5, Chinese-CNS, Chinese-GB, Cyrillic-ALT, Cyrillic-ISO,
Cyrillic-KOI8, Czech, Devanagari, Dutch, English, Ethiopic, German,
Greek, Hebrew, IPA, Japanese, Korean, Lao, Latin-1, Latin-2,
Latin-3, Latin-4, Latin-5, Latin-8 (Celtic), Latin-9 (updated
Latin-1, with the Euro sign), Polish, Romanian, Slovak, Slovenian,
Spanish, Thai, Tibetan, Turkish, and Vietnamese.
To display the script(s) used by your language environment on a
graphical display, you need to have a suitable font. If some of the
characters appear as empty boxes, you should install the GNU Intlfonts
package, which includes fonts for all supported scripts.(1) *Note
Fontsets::, for more details about setting up your fonts.
Some operating systems let you specify the character-set locale you
are using by setting the locale environment variables `LC_ALL',
`LC_CTYPE', or `LANG'.(2) During startup, Emacs looks up your
character-set locale's name in the system locale alias table, matches
its canonical name against entries in the value of the variables
`locale-charset-language-names' and `locale-language-names', and
selects the corresponding language environment if a match is found.
(The former variable overrides the latter.) It also adjusts the display
table and terminal coding system, the locale coding system, and the
preferred coding system as needed for the locale.
If you modify the `LC_ALL', `LC_CTYPE', or `LANG' environment
variables while running Emacs, you may want to invoke the
`set-locale-environment' function afterwards to readjust the language
environment from the new locale.
The `set-locale-environment' function normally uses the preferred
coding system established by the language environment to decode system
messages. But if your locale matches an entry in the variable
`locale-preferred-coding-systems', Emacs uses the corresponding coding
system instead. For example, if the locale `ja_JP.PCK' matches
`japanese-shift-jis' in `locale-preferred-coding-systems', Emacs uses
that encoding even though it might normally use `japanese-iso-8bit'.
You can override the language environment chosen at startup with
explicit use of the command `set-language-environment', or with
customization of `current-language-environment' in your init file.
To display information about the effects of a certain language
environment LANG-ENV, use the command `C-h L LANG-ENV <RET>'
(`describe-language-environment'). This tells you which languages this
language environment is useful for, and lists the character sets,
coding systems, and input methods that go with it. It also shows some
sample text to illustrate scripts used in this language environment.
By default, this command describes the chosen language environment.
You can customize any language environment with the normal hook
`set-language-environment-hook'. The command
`set-language-environment' runs that hook after setting up the new
language environment. The hook functions can test for a specific
language environment by checking the variable
`current-language-environment'. This hook is where you should put
non-default settings for specific language environment, such as coding
systems for keyboard input and terminal output, the default input
method, etc.
Before it starts to set up the new language environment,
`set-language-environment' first runs the hook
`exit-language-environment-hook'. This hook is useful for undoing
customizations that were made with `set-language-environment-hook'.
For instance, if you set up a special key binding in a specific language
environment using `set-language-environment-hook', you should set up
`exit-language-environment-hook' to restore the normal binding for that
key.
---------- Footnotes ----------
(1) If you run Emacs on X, you need to inform the X server about the
location of the newly installed fonts with the following commands:
xset fp+ /usr/local/share/emacs/fonts
xset fp rehash
(2) If more than one of these is set, the first one that is nonempty
specifies your locale for this purpose.
File: emacs, Node: Input Methods, Next: Select Input Method, Prev: Language Environments, Up: International
Input Methods
=============
An "input method" is a kind of character conversion designed
specifically for interactive input. In Emacs, typically each language
has its own input method; sometimes several languages which use the same
characters can share one input method. A few languages support several
input methods.
The simplest kind of input method works by mapping ASCII letters
into another alphabet; this allows you to use one other alphabet
instead of ASCII. The Greek and Russian input methods work this way.
A more powerful technique is composition: converting sequences of
characters into one letter. Many European input methods use composition
to produce a single non-ASCII letter from a sequence that consists of a
letter followed by accent characters (or vice versa). For example, some
methods convert the sequence `a'' into a single accented letter. These
input methods have no special commands of their own; all they do is
compose sequences of printing characters.
The input methods for syllabic scripts typically use mapping followed
by composition. The input methods for Thai and Korean work this way.
First, letters are mapped into symbols for particular sounds or tone
marks; then, sequences of these which make up a whole syllable are
mapped into one syllable sign.
Chinese and Japanese require more complex methods. In Chinese input
methods, first you enter the phonetic spelling of a Chinese word (in
input method `chinese-py', among others), or a sequence of portions of
the character (input methods `chinese-4corner' and `chinese-sw', and
others). One input sequence typically corresponds to many possible
Chinese characters. You select the one you mean using keys such as
`C-f', `C-b', `C-n', `C-p', and digits, which have special meanings in
this situation.
The possible characters are conceptually arranged in several rows,
with each row holding up to 10 alternatives. Normally, Emacs displays
just one row at a time, in the echo area; `(I/J)' appears at the
beginning, to indicate that this is the Ith row out of a total of J
rows. Type `C-n' or `C-p' to display the next row or the previous row.
Type `C-f' and `C-b' to move forward and backward among the
alternatives in the current row. As you do this, Emacs highlights the
current alternative with a special color; type `C-<SPC>' to select the
current alternative and use it as input. The alternatives in the row
are also numbered; the number appears before the alternative. Typing a
digit N selects the Nth alternative of the current row and uses it as
input.
<TAB> in these Chinese input methods displays a buffer showing all
the possible characters at once; then clicking `Mouse-2' on one of them
selects that alternative. The keys `C-f', `C-b', `C-n', `C-p', and
digits continue to work as usual, but they do the highlighting in the
buffer showing the possible characters, rather than in the echo area.
In Japanese input methods, first you input a whole word using
phonetic spelling; then, after the word is in the buffer, Emacs
converts it into one or more characters using a large dictionary. One
phonetic spelling corresponds to a number of different Japanese words;
to select one of them, use `C-n' and `C-p' to cycle through the
alternatives.
Sometimes it is useful to cut off input method processing so that the
characters you have just entered will not combine with subsequent
characters. For example, in input method `latin-1-postfix', the
sequence `e '' combines to form an `e' with an accent. What if you
want to enter them as separate characters?
One way is to type the accent twice; this is a special feature for
entering the separate letter and accent. For example, `e ' '' gives
you the two characters `e''. Another way is to type another letter
after the `e'--something that won't combine with that--and immediately
delete it. For example, you could type `e e <DEL> '' to get separate
`e' and `''.
Another method, more general but not quite as easy to type, is to use
`C-\ C-\' between two characters to stop them from combining. This is
the command `C-\' (`toggle-input-method') used twice. *Note Select
Input Method::.
`C-\ C-\' is especially useful inside an incremental search, because
it stops waiting for more characters to combine, and starts searching
for what you have already entered.
The variables `input-method-highlight-flag' and
`input-method-verbose-flag' control how input methods explain what is
happening. If `input-method-highlight-flag' is non-`nil', the partial
sequence is highlighted in the buffer (for most input methods--some
disable this feature). If `input-method-verbose-flag' is non-`nil',
the list of possible characters to type next is displayed in the echo
area (but not when you are in the minibuffer).
Input methods are implemented in the separate Leim package: they are
available only if the system administrator used Leim when building
Emacs. If Emacs was built without Leim, you will find that no input
methods are defined.
File: emacs, Node: Select Input Method, Next: Multibyte Conversion, Prev: Input Methods, Up: International
Selecting an Input Method
=========================
`C-\'
Enable or disable use of the selected input method.
`C-x <RET> C-\ METHOD <RET>'
Select a new input method for the current buffer.
`C-h I METHOD <RET>'
`C-h C-\ METHOD <RET>'
Describe the input method METHOD (`describe-input-method'). By
default, it describes the current input method (if any). This
description should give you the full details of how to use any
particular input method.
`M-x list-input-methods'
Display a list of all the supported input methods.
To choose an input method for the current buffer, use `C-x <RET>
C-\' (`set-input-method'). This command reads the input method name
from the minibuffer; the name normally starts with the language
environment that it is meant to be used with. The variable
`current-input-method' records which input method is selected.
Input methods use various sequences of ASCII characters to stand for
non-ASCII characters. Sometimes it is useful to turn off the input
method temporarily. To do this, type `C-\' (`toggle-input-method').
To reenable the input method, type `C-\' again.
If you type `C-\' and you have not yet selected an input method, it
prompts for you to specify one. This has the same effect as using `C-x
<RET> C-\' to specify an input method.
When invoked with a numeric argument, as in `C-u C-\',
`toggle-input-method' always prompts you for an input method,
suggesting the most recently selected one as the default.
Selecting a language environment specifies a default input method for
use in various buffers. When you have a default input method, you can
select it in the current buffer by typing `C-\'. The variable
`default-input-method' specifies the default input method (`nil' means
there is none).
In some language environments, which support several different input
methods, you might want to use an input method different from the
default chosen by `set-language-environment'. You can instruct Emacs
to select a different default input method for a certain language
environment, if you wish, by using `set-language-environment-hook'
(*note set-language-environment-hook: Language Environments.). For
example:
(defun my-chinese-setup ()
"Set up my private Chinese environment."
(if (equal current-language-environment "Chinese-GB")
(setq default-input-method "chinese-tonepy")))
(add-hook 'set-language-environment-hook 'my-chinese-setup)
This sets the default input method to be `chinese-tonepy' whenever you
choose a Chinese-GB language environment.
Some input methods for alphabetic scripts work by (in effect)
remapping the keyboard to emulate various keyboard layouts commonly used
for those scripts. How to do this remapping properly depends on your
actual keyboard layout. To specify which layout your keyboard has, use
the command `M-x quail-set-keyboard-layout'.
To display a list of all the supported input methods, type `M-x
list-input-methods'. The list gives information about each input
method, including the string that stands for it in the mode line.
File: emacs, Node: Multibyte Conversion, Next: Coding Systems, Prev: Select Input Method, Up: International
Unibyte and Multibyte Non-ASCII characters
==========================================
When multibyte characters are enabled, character codes 0240 (octal)
through 0377 (octal) are not really legitimate in the buffer. The valid
non-ASCII printing characters have codes that start from 0400.
If you type a self-inserting character in the range 0240 through
0377, or if you use `C-q' to insert one, Emacs assumes you intended to
use one of the ISO Latin-N character sets, and converts it to the Emacs
code representing that Latin-N character. You select _which_ ISO Latin
character set to use through your choice of language environment (*note
Language Environments::). If you do not specify a choice, the default
is Latin-1.
If you insert a character in the range 0200 through 0237, which
forms the `eight-bit-control' character set, it is inserted literally.
You should normally avoid doing this since buffers containing such
characters have to be written out in either the `emacs-mule' or
`raw-text' coding system, which is usually not what you want.
File: emacs, Node: Coding Systems, Next: Recognize Coding, Prev: Multibyte Conversion, Up: International
Coding Systems
==============
Users of various languages have established many more-or-less
standard coding systems for representing them. Emacs does not use
these coding systems internally; instead, it converts from various
coding systems to its own system when reading data, and converts the
internal coding system to other coding systems when writing data.
Conversion is possible in reading or writing files, in sending or
receiving from the terminal, and in exchanging data with subprocesses.
Emacs assigns a name to each coding system. Most coding systems are
used for one language, and the name of the coding system starts with the
language name. Some coding systems are used for several languages;
their names usually start with `iso'. There are also special coding
systems `no-conversion', `raw-text' and `emacs-mule' which do not
convert printing characters at all.
A special class of coding systems, collectively known as
"codepages", is designed to support text encoded by MS-Windows and
MS-DOS software. To use any of these systems, you need to create it
with `M-x codepage-setup'. *Note MS-DOS and MULE::. After creating
the coding system for the codepage, you can use it as any other coding
system. For example, to visit a file encoded in codepage 850, type
`C-x <RET> c cp850 <RET> C-x C-f FILENAME <RET>'.
In addition to converting various representations of non-ASCII
characters, a coding system can perform end-of-line conversion. Emacs
handles three different conventions for how to separate lines in a file:
newline, carriage-return linefeed, and just carriage-return.
`C-h C CODING <RET>'
Describe coding system CODING.
`C-h C <RET>'
Describe the coding systems currently in use.
`M-x list-coding-systems'
Display a list of all the supported coding systems.
The command `C-h C' (`describe-coding-system') displays information
about particular coding systems. You can specify a coding system name
as the argument; alternatively, with an empty argument, it describes
the coding systems currently selected for various purposes, both in the
current buffer and as the defaults, and the priority list for
recognizing coding systems (*note Recognize Coding::).
To display a list of all the supported coding systems, type `M-x
list-coding-systems'. The list gives information about each coding
system, including the letter that stands for it in the mode line (*note
Mode Line::).
Each of the coding systems that appear in this list--except for
`no-conversion', which means no conversion of any kind--specifies how
and whether to convert printing characters, but leaves the choice of
end-of-line conversion to be decided based on the contents of each file.
For example, if the file appears to use the sequence carriage-return
linefeed to separate lines, DOS end-of-line conversion will be used.
Each of the listed coding systems has three variants which specify
exactly what to do for end-of-line conversion:
`...-unix'
Don't do any end-of-line conversion; assume the file uses newline
to separate lines. (This is the convention normally used on Unix
and GNU systems.)
`...-dos'
Assume the file uses carriage-return linefeed to separate lines,
and do the appropriate conversion. (This is the convention
normally used on Microsoft systems.(1))
`...-mac'
Assume the file uses carriage-return to separate lines, and do the
appropriate conversion. (This is the convention normally used on
the Macintosh system.)
These variant coding systems are omitted from the
`list-coding-systems' display for brevity, since they are entirely
predictable. For example, the coding system `iso-latin-1' has variants
`iso-latin-1-unix', `iso-latin-1-dos' and `iso-latin-1-mac'.
The coding system `raw-text' is good for a file which is mainly
ASCII text, but may contain byte values above 127 which are not meant to
encode non-ASCII characters. With `raw-text', Emacs copies those byte
values unchanged, and sets `enable-multibyte-characters' to `nil' in
the current buffer so that they will be interpreted properly.
`raw-text' handles end-of-line conversion in the usual way, based on
the data encountered, and has the usual three variants to specify the
kind of end-of-line conversion to use.
In contrast, the coding system `no-conversion' specifies no
character code conversion at all--none for non-ASCII byte values and
none for end of line. This is useful for reading or writing binary
files, tar files, and other files that must be examined verbatim. It,
too, sets `enable-multibyte-characters' to `nil'.
The easiest way to edit a file with no conversion of any kind is with
the `M-x find-file-literally' command. This uses `no-conversion', and
also suppresses other Emacs features that might convert the file
contents before you see them. *Note Visiting::.
The coding system `emacs-mule' means that the file contains
non-ASCII characters stored with the internal Emacs encoding. It
handles end-of-line conversion based on the data encountered, and has
the usual three variants to specify the kind of end-of-line conversion.
---------- Footnotes ----------
(1) It is also specified for MIME `text/*' bodies and in other
network transport contexts. It is different from the SGML reference
syntax record-start/record-end format which Emacs doesn't support
directly.