This is Info file ../info/emacs, produced by Makeinfo version 1.68 from
the input file ../texi/emacs.texi.

   This is the thirteenth edition of the `GNU Emacs Manual', updated
for Emacs version 20.7.

INFO-DIR-SECTION Editors
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    Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
General Public License" are included exactly as in the original, and
provided that the entire resulting derived work is distributed under the
terms of a permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the sections entitled "The GNU Manifesto",
"Distribution" and "GNU General Public License" may be included in a
translation approved by the Free Software Foundation instead of in the
original English.


File: emacs,  Node: Speedbar,  Next: Creating Frames,  Prev: Mode Line Mouse,  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: Creating Frames,  Up: Frames

Multiple Displays
=================

   A single Emacs can talk to more than one X Windows 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.

`M-x set-background-color <RET> COLOR <RET>'
     Specify color COLOR for the background of the selected frame.
     This changes the foreground color of the `modeline' face also, so
     that it remains in inverse video compared with the default.

`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 is used for all text displayed in the frame,
     except when a face (*note Faces::.) specifies a different font to
     use for certain text.  *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.

   For information on frame parameters and customization, see *Note
Frame Parameters: (elisp)Frame Parameters.


File: emacs,  Node: Scroll Bars,  Next: Menu Bars,  Prev: Frame Parameters,  Up: Frames

Scroll Bars
===========

   When using X, Emacs normally makes a "scroll bar" at the left of
each Emacs window.  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.

   Aside from scrolling, 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.  You can use the X resource
`verticalScrollBars' to control the initial setting of Scroll Bar mode.
*Note Resources X::.

   To enable or disable scroll bars for just the selected frame, use the
`M-x toggle-scroll-bar' command.


File: emacs,  Node: Menu Bars,  Next: Faces,  Prev: Scroll Bars,  Up: Frames

Menu Bars
=========

   You can turn display of menu bars on or off with `M-x
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.

   *Note Menu Bar::, for information on how to invoke commands with the
menu bar.


File: emacs,  Node: Faces,  Next: Font Lock,  Prev: Menu Bars,  Up: Frames

Using Multiple Typefaces
========================

   When using Emacs with X, you can set up multiple styles of displaying
characters.  The aspects of style that you can control are the type
font, the foreground color, the background color, and whether to
underline.  Emacs on MS-DOS supports faces partially by letting you
control the foreground and background colors of each face (*note
MS-DOS::.).

   The way you control display style is by defining named "faces".
Each face can specify a type font, a foreground color, a background
color, and an underline flag; but it does not have to specify all of
them.  Then by specifying the face or faces to use for a given part of
the text in the buffer, you control how that text appears.

   The style of display used for a given character in the text is
determined by combining several faces.  Any aspect of the display style
that isn't specified by overlays or text properties comes from the frame
itself.

   Enriched mode, the mode for editing formatted text, includes several
commands and menus for specifying faces.  *Note Format Faces::, for how
to specify the font for text in the buffer.  *Note Format Colors::, for
how to specify the foreground and background color.

   To alter the appearance of a face, use the customization buffer.
*Note Face Customization::.  You can also use X resources to specify
attributes of particular faces (*note Resources X::.).

   To see what faces are currently defined, and what they look like,
type `M-x list-faces-display'.  It's possible for a given face to look
different in different frames; this command shows the appearance in the
frame in which you type it.  Here's a list of the standardly defined
faces:

`default'
     This face is used for ordinary text that doesn't specify any other
     face.

`modeline'
     This face is used for mode lines.  By default, it's set up as the
     inverse of the default face.  *Note Display Vars::.

`highlight'
     This face is used for highlighting portions of text, in various
     modes.

`region'
     This face is used for displaying a selected region (when Transient
     Mark mode is enabled--see below).

`secondary-selection'
     This face is used for displaying a secondary selection (*note
     Secondary Selection::.).

`bold'
     This face uses a bold variant of the default font, if it has one.

`italic'
     This face uses an italic variant of the default font, if it has
     one.

`bold-italic'
     This face uses a bold italic variant of the default font, if it
     has one.

`underline'
     This face underlines text.

   When Transient Mark mode is enabled, the text of the region is
highlighted when the mark is active.  This uses the face named
`region'; you can control the style of highlighting by changing the
style of this face (*note Face Customization::.).  *Note Transient
Mark::, for more information about Transient Mark mode and activation
and deactivation of the mark.

   One easy way to use faces is to turn on Font Lock mode.  This minor
mode, which is always local to a particular buffer, arranges to choose
faces according to the syntax of the text you are editing.  It can
recognize comments and strings in most languages; in several languages,
it can also recognize and properly highlight various other important
constructs.  *Note Font Lock::, for more information about Font Lock
mode and syntactic highlighting.

   You can print out the buffer with the highlighting that appears on
your screen using the command `ps-print-buffer-with-faces'.  *Note
Postscript::.


File: emacs,  Node: Font Lock,  Next: Support Modes,  Prev: Faces,  Up: Frames

Font Lock mode
==============

   Font Lock mode is a minor mode, always local to a particular buffer,
which highlights (or "fontifies") using various faces according to the
syntax of the text you are editing.  It can recognize comments and
strings in most languages; in several languages, it can also recognize
and properly highlight various other important constructs--for example,
names of functions being defined or reserved keywords.

   The command `M-x font-lock-mode' turns Font Lock mode on or off
according to the argument, and toggles the mode when it has no argument.
The function `turn-on-font-lock' unconditionally enables Font Lock
mode.  This is useful in mode-hook functions.  For example, to enable
Font Lock mode whenever you edit a C file, you can do this:

     (add-hook 'c-mode-hook 'turn-on-font-lock)

   To turn on Font Lock mode automatically in all modes which support
it, use the function `global-font-lock-mode', like this:

     (global-font-lock-mode 1)

   In Font Lock mode, when you edit the text, the highlighting updates
automatically in the line that you changed.  Most changes don't affect
the highlighting of subsequent lines, but occasionally they do.  To
rehighlight a range of lines, use the command `M-g M-g'
(`font-lock-fontify-block').

   In certain major modes, `M-g M-g' refontifies the entire current
function.  (The variable `font-lock-mark-block-function' controls how
to find the current function.)  In other major modes, `M-g M-g'
refontifies 16 lines above and below point.

   With a prefix argument N, `M-g M-g' refontifies N lines above and
below point, regardless of the mode.

   To get the full benefit of Font Lock mode, you need to choose a
default font which has bold, italic, and bold-italic variants; or else
you need to have a color or gray-scale screen.

   The variable `font-lock-maximum-decoration' specifies the preferred
level of fontification, for modes that provide multiple levels.  Level
1 is the least amount of fontification; some modes support levels as
high as 3.  The normal default is "as high as possible."  You can
specify an integer, which applies to all modes, or you can specify
different numbers for particular major modes; for example, to use level
1 for C/C++ modes, and the default level otherwise, use this:

     (setq font-lock-maximum-decoration
           '((c-mode . 1) (c++-mode . 1)))

   Fontification can be too slow for large buffers, so you can suppress
it.  The variable `font-lock-maximum-size' specifies a buffer size,
beyond which buffer fontification is suppressed.

   Comment and string fontification (or "syntactic" fontification)
relies on analysis of the syntactic structure of the buffer text.  For
the purposes of speed, some modes including C mode and Lisp mode rely on
a special convention: an open-parenthesis in the leftmost column always
defines the beginning of a defun, and is thus always outside any string
or comment.  (*Note Defuns::.)  If you don't follow this convention,
then Font Lock mode can misfontify the text after an open-parenthesis in
the leftmost column that is inside a string or comment.

   The variable `font-lock-beginning-of-syntax-function' (always
buffer-local) specifies how Font Lock mode can find a position
guaranteed to be outside any comment or string.  In modes which use the
leftmost column parenthesis convention, the default value of the
variable is `beginning-of-defun'--that tells Font Lock mode to use the
convention.  If you set this variable to `nil', Font Lock no longer
relies on the convention.  This avoids incorrect results, but the price
is that, in some cases, fontification for a changed text must rescan
buffer text from the beginning of the buffer.

   Font Lock highlighting patterns already exist for many modes, but you
may want to fontify additional patterns.  You can use the function
`font-lock-add-keywords', to add your own highlighting patterns for a
particular mode.  For example, to highlight `FIXME:' words in C
comments, use this:

     (font-lock-add-keywords
      'c-mode
      '(("\\<\\(FIXME\\):" 1 font-lock-warning-face t)))


File: emacs,  Node: Support Modes,  Next: Highlight Changes,  Prev: Font Lock,  Up: Frames

Font Lock Support Modes
=======================

   Font Lock support modes make Font Lock mode faster for large buffers.
There are two support modes: Fast Lock mode and Lazy Lock mode.  They
use two different methods of speeding up Font Lock mode.

* Menu:

* Fast Lock Mode::      Saving font information in files.
* Lazy Lock Mode::      Fontifying only text that is actually displayed.
* Fast or Lazy::        Which support mode is best for you?


File: emacs,  Node: Fast Lock Mode,  Next: Lazy Lock Mode,  Up: Support Modes

Fast Lock Mode
--------------

   To make Font Lock mode faster for buffers visiting large files, you
can use Fast Lock mode.  Fast Lock mode saves the font information for
each file in a separate cache file; each time you visit the file, it
rereads the font information from the cache file instead of refontifying
the text from scratch.

   The command `M-x fast-lock-mode' turns Fast Lock mode on or off,
according to the argument (with no argument, it toggles).  You can also
arrange to enable Fast Lock mode whenever you use Font Lock mode, like
this:

     (setq font-lock-support-mode 'fast-lock-mode)

   It is not worth writing a cache file for small buffers.  Therefore,
the variable `fast-lock-minimum-size' specifies a minimum file size for
caching font information.

   The variable `fast-lock-cache-directories' specifies where to put
the cache files.  Its value is a list of directories to try; `"."'
means the same directory as the file being edited.  The default value is
`("." "~/.emacs-flc")', which means to use the same directory if
possible, and otherwise the directory `~/.emacs-flc'.

   The variable `fast-lock-save-others' specifies whether Fast Lock
mode should save cache files for files that you do not own.  A
non-`nil' value means yes (and that is the default).


File: emacs,  Node: Lazy Lock Mode,  Next: Fast or Lazy,  Prev: Fast Lock Mode,  Up: Support Modes

Lazy Lock Mode
--------------

   To make Font Lock mode faster for large buffers, you can use Lazy
Lock mode to reduce the amount of text that is fontified.  In Lazy Lock
mode, buffer fontification is demand-driven; it happens to portions of
the buffer that are about to be displayed.  And fontification of your
changes is deferred; it happens only when Emacs has been idle for a
certain short period of time.

   The command `M-x lazy-lock-mode' turns Lazy Lock mode on or off,
according to the argument (with no argument, it toggles).  You can also
arrange to enable Lazy Lock mode whenever you use Font Lock mode, like
this:

     (setq font-lock-support-mode 'lazy-lock-mode)

   It is not worth avoiding buffer fontification for small buffers.
Therefore, the variable `lazy-lock-minimum-size' specifies a minimum
buffer size for demand-driven buffer fontification.  Buffers smaller
than that are fontified all at once, as in plain Font Lock mode.

   When you alter the buffer, Lazy Lock mode defers fontification of the
text you changed.  The variable `lazy-lock-defer-time' specifies how
many seconds Emacs must be idle before it starts fontifying your
changes.  If the value is 0, then changes are fontified immediately, as
in plain Font Lock mode.

   Lazy Lock mode normally fontifies newly visible portions of the
buffer before they are first displayed.  However, if the value of
`lazy-lock-defer-on-scrolling' is non-`nil', newly visible text is
fontified only when Emacs is idle for `lazy-lock-defer-time' seconds.

   In some modes, including C mode and Emacs Lisp mode, changes in one
line's contents can alter the context for subsequent lines, and thus
change how they ought to be fontified.  Ordinarily, you must type `M-g
M-g' to refontify the subsequent lines.  However, if you set the
variable `lazy-lock-defer-contextually' to non-`nil', Lazy Lock mode
does this automatically, after `lazy-lock-defer-time' seconds.

   When Emacs is idle for a long time, Lazy Lock fontifies additional
portions of the buffer, not yet displayed, in case you will display them
later.  This is called "stealth fontification".

   The variable `lazy-lock-stealth-time' specifies how many seconds
Emacs has to be idle before stealth fontification starts.  A value of
`nil' means no stealth fontification.  The variables
`lazy-lock-stealth-lines' and `lazy-lock-stealth-verbose' specify the
granularity and verbosity of stealth fontification.


File: emacs,  Node: Fast or Lazy,  Prev: Lazy Lock Mode,  Up: Support Modes

Fast Lock or Lazy Lock?
-----------------------

   Here is a simple guide to help you choose one of the Font Lock
support modes.

   * Fast Lock mode intervenes only during file visiting and buffer
     killing (and related events); therefore buffer editing and window
     scrolling are no faster or slower than in plain Font Lock mode.

   * Fast Lock mode is slower at reading a cache file than Lazy Lock
     mode is at fontifying a window; therefore Fast Lock mode is slower
     at visiting a file than Lazy Lock mode.

   * Lazy Lock mode intervenes during window scrolling to fontify text
     that scrolls onto the screen; therefore, scrolling is slower than
     in plain Font Lock mode.

   * Lazy Lock mode doesn't fontify during buffer editing (it defers
     fontification of changes); therefore, editing is faster than in
     plain Font Lock mode.

   * Fast Lock mode can be fooled by a file that is kept under version
     control software; therefore buffer fontification may occur even
     when a cache file exists for the file.

   * Fast Lock mode only works with a buffer visiting a file; Lazy Lock
     mode works with any buffer.

   * Fast Lock mode generates cache files; Lazy Lock mode does not.

   The variable `font-lock-support-mode' specifies which of these
support modes to use; for example, to specify that Fast Lock mode is
used for C/C++ modes, and Lazy Lock mode otherwise, set the variable
like this:

     (setq font-lock-support-mode
           '((c-mode . fast-lock-mode) (c++-mode . fast-lock-mode)
             (t . lazy-lock-mode)))


File: emacs,  Node: Highlight Changes,  Next: Misc X,  Prev: Support Modes,  Up: Frames

Highlight Changes Mode
======================

   Use `M-x highlight-changes-mode' to enable a minor mode that uses
faces (colors, typically) to indicate which parts of the buffer were
changed most recently.


File: emacs,  Node: Misc X,  Next: Non-Window Terminals,  Prev: Highlight Changes,  Up: Frames

Miscellaneous X Window Features
===============================

   The following commands let you create, delete and operate on frames:

`C-z'
     Iconify the selected Emacs frame (`iconify-or-deiconify-frame').
     The normal meaning of `C-z', to suspend Emacs, is not useful under
     a window system, so it has a different binding in that case.

     If you type this command on an Emacs frame's icon, it deiconifies
     the frame.

`C-x 5 0'
     Delete the selected frame (`delete-frame').  This is not allowed if
     there is only one frame.

`C-x 5 o'
     Select another frame, raise it, and warp the mouse to it so that it
     stays selected.  If you repeat this command, it cycles through all
     the frames on your terminal.


File: emacs,  Node: Non-Window Terminals,  Prev: Misc X,  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: 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,
Devanagari (Hindi and Marathi), Ethiopian, Greek, IPA, Japanese, Korean,
Lao, Russian, 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")

* Menu:

* International Intro::     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.
* Single-Byte European Support::
                            You can pick one European character set
                            to use without multibyte characters.


File: emacs,  Node: International Intro,  Next: Enabling Multibyte,  Up: International

Introduction to International Character Sets
============================================

   The users of these 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.

   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 Intro,  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.

   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' in your init file to
have basically the same effect as `--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.  However, the initialization file is
normally read as multibyte--like Lisp files in general--even with
`--unibyte'.  To avoid multibyte strings being generated by non-ASCII
characters in it, put `-*-unibyte: t;-*-' in a comment on the first
line.  Do the same for initialization files for packages like Gnus.

   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.

   The way to select a language environment is with 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-Alternativnyj,
     Cyrillic-ISO, Cyrillic-KOI8, Devanagari, English, Ethiopic, Greek,
     Hebrew, Japanese, Korean, Lao, Latin-1, Latin-2, Latin-3, Latin-4,
     Latin-5, Thai, Tibetan, and Vietnamese.

   Some operating systems let you specify the language you are using by
setting locale environment variables.  Emacs handles one common special
case of this: if your locale name for character types contains the
string `8859-N', Emacs automatically selects the corresponding language
environment.

   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'.

   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.


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 is how the Greek and Russian input methods work.

   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).  Since one phonetic spelling typically corresponds to many
different Chinese characters, you must select one of the alternatives
using special Emacs commands.  Keys such as `C-f', `C-b', `C-n', `C-p',
and digits have special definitions in this situation, used for
selecting among the alternatives.  <TAB> displays a buffer showing all
the possibilities.

   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 many differently written Japanese words, so you
must 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; that 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.  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).


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
with 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.

   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).

   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 invalid range 0240
through 0377, 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.

   The same thing happens when you use `C-q' to enter an octal code in
this range.


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.

   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 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.