@c This is part of the Emacs manual.
-@c Copyright (C) 1997, 1999, 2000 Free Software Foundation, Inc.
+@c Copyright (C) 1997, 1999, 2000, 2001, 2002, 2003, 2004,
+@c 2005, 2006 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node International, Major Modes, Frames, Top
@chapter International Character Set Support
@cindex Tibetan
@cindex Turkish
@cindex Vietnamese
+@cindex Dutch
+@cindex Spanish
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'')
+including European and Vietnamese variants of the Latin alphabet, as
+well as Cyrillic, Devanagari (for Hindi and Marathi), Ethiopic, Greek,
+Han (for Chinese and Japanese), Hangul (for Korean), Hebrew, IPA,
+Kannada, Lao, Malayalam, Tamil, Thai, Tibetan, and Vietnamese scripts.
+Emacs also supports various encodings of these characters used by
+other internationalized software, such as word processors and mailers.
- Emacs also supports various encodings of these characters used by
-internationalized software, such as word processors, mailers, etc.
+ Emacs allows editing text with international characters by supporting
+all the related activities:
+
+@itemize @bullet
+@item
+You can visit files with non-@acronym{ASCII} characters, save non-@acronym{ASCII} text, and
+pass non-@acronym{ASCII} text between Emacs and programs it invokes (such as
+compilers, spell-checkers, and mailers). Setting your language
+environment (@pxref{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 @ref{Text Coding}.
+
+@item
+You can display non-@acronym{ASCII} characters encoded by the various
+scripts. This works by using appropriate fonts on graphics displays
+(@pxref{Defining Fontsets}), and by sending special codes to text-only
+displays (@pxref{Terminal Coding}). If some characters are displayed
+incorrectly, refer to @ref{Undisplayable Characters}, which describes
+possible problems and explains how to solve them.
+
+@item
+You can insert non-@acronym{ASCII} characters or search for them. To do that,
+you can specify an input method (@pxref{Select Input Method}) suitable
+for your language, or use the default input method set up when you set
+your language environment. If
+your keyboard can produce non-@acronym{ASCII} characters, you can select an
+appropriate keyboard coding system (@pxref{Terminal Coding}), and Emacs
+will accept those characters. Latin-1 characters can also be input by
+using the @kbd{C-x 8} prefix, see @ref{Unibyte Mode}.
+
+On X Window systems, your locale should be set to an appropriate value
+to make sure Emacs interprets keyboard input correctly; see
+@ref{Language Environments, locales}.
+@end itemize
+
+ The rest of this chapter describes these issues in detail.
@menu
-* International Intro:: Basic concepts of multibyte characters.
+* 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.
* 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.
+* Text Coding:: Choosing conversion to use for file text.
+* Communication Coding:: Coding systems for interprocess communication.
+* File Name Coding:: Coding systems for file @emph{names}.
+* Terminal Coding:: Specifying coding systems for converting
+ terminal input and output.
* 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.
+* Unibyte Mode:: You can pick one European character set
+ to use without multibyte characters.
+* Charsets:: How Emacs groups its internal character codes.
@end menu
-@node International Intro
+@node International Chars
@section 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 @kbd{C-q} command (@pxref{Multibyte Conversion}).
+ 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-@acronym{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 @kbd{C-q} command
+(@pxref{Multibyte Conversion}).
@kindex C-h h
@findex view-hello-file
+@cindex undisplayable characters
+@cindex @samp{?} in display
The command @kbd{C-h h} (@code{view-hello-file}) displays the file
@file{etc/HELLO}, which shows how to say ``hello'' in many languages.
-This illustrates various scripts. If the font you're using doesn't have
-characters for all those different languages, you will see some hollow
-boxes instead of characters; see @ref{Fontsets}. On non-windowing
-displays, @samp{?} is displayed in place of the hollow box.
-
-@findex list-charset-chars
-@cindex characters in a certain charset
- The command @kbd{M-x list-charset-chars} prompts for a name of a
-character set, and displays all the characters in that character set.
-
-@findex describe-character-set
-@cindex character set, description
- The command @kbd{M-x describe-character-set} prompts for a character
-set name and displays information about that character set, including
-its internal representation within Emacs.
+This illustrates various scripts. If some characters can't be
+displayed on your terminal, they appear as @samp{?} or as hollow boxes
+(@pxref{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
@node Enabling Multibyte
@section 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.
+ By default, Emacs starts in multibyte mode, because that allows you to
+use all the supported languages and scripts without limitations.
- 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.
+@cindex turn multibyte support on or off
+ 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, we call that @dfn{unibyte mode}. 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 in unibyte mode 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
@code{find-file-literally}. @xref{Visiting}. To convert a buffer in
buffer, and find the file again with @code{find-file-literally}. You
can also use @kbd{C-x @key{RET} c}
(@code{universal-coding-system-argument}) and specify @samp{raw-text} as
-the coding system with which to find or save a file. @xref{Specify
+the coding system with which to find or save a file. @xref{Text
Coding}. Finding a file as @samp{raw-text} doesn't disable format
conversion, uncompression and auto mode selection as
@code{find-file-literally} does.
the @samp{--unibyte} option (@pxref{Initial Options}), or set the
environment variable @env{EMACS_UNIBYTE}. You can also customize
@code{enable-multibyte-characters} or, equivalently, directly set the
-variable @code{default-enable-multibyte-characters} in your init file to
-have basically the same effect as @samp{--unibyte}.
+variable @code{default-enable-multibyte-characters} to @code{nil} in
+your init file to have basically the same effect as @samp{--unibyte}.
+
+@findex toggle-enable-multibyte-characters
+ To convert a unibyte session to a multibyte session, set
+@code{default-enable-multibyte-characters} to @code{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 @code{toggle-enable-multibyte-characters}
+in that buffer.
@cindex Lisp files, and multibyte operation
@cindex multibyte operation, and Lisp files
@cindex unibyte operation, and Lisp files
-@cindex init file, and non-ASCII characters
-@cindex environment variables, and non-ASCII characters
- Multibyte strings are not created during initialization from the
-values of environment variables, @file{/etc/passwd} entries etc.@: that
-contain non-ASCII 8-bit characters. However, Lisp files, when they are
-loaded for running, and in particular the initialization file
-@file{.emacs}, are normally read as multibyte---even with
-@samp{--unibyte}. To avoid multibyte strings being generated by
-non-ASCII characters in Lisp files, put @samp{-*-unibyte: t;-*-} in a
-comment on the first line, or specify the coding system @samp{raw-text}
-with @kbd{C-x @key{RET} c}. Do the same for initialization files for
-packages like Gnus.
+@cindex init file, and non-@acronym{ASCII} characters
+@cindex environment variables, and non-@acronym{ASCII} characters
+ With @samp{--unibyte}, multibyte strings are not created during
+initialization from the values of environment variables,
+@file{/etc/passwd} entries etc.@: that contain non-@acronym{ASCII} 8-bit
+characters.
+
+ Emacs normally loads Lisp files as multibyte, regardless of whether
+you used @samp{--unibyte}. This includes the Emacs initialization file,
+@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 @w{@samp{-*-unibyte: t;-*-}} in a comment on the first
+line (@pxref{File Variables}). Then that file is always loaded as
+unibyte text, even if you did not start Emacs with @samp{--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 @kbd{C-x
+@key{RET} c raw-text @key{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.
+When multibyte characters are not enabled, nothing precedes the colon
+except a single dash.
@node Language Environments
@section Language Environments
@findex set-language-environment
@vindex current-language-environment
- To select a language environment, customize the option
+ To select a language environment, you can customize the variable
@code{current-language-environment} or use the command @kbd{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:
@cindex Euro sign
+@cindex UTF-8
@quotation
-Chinese-BIG5, Chinese-CNS, Chinese-GB, Cyrillic-ALT, Cyrillic-ISO,
-Cyrillic-KOI8, Czech, Devanagari, 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, Thai, Tibetan, Turkish, and
-Vietnamese.
+Belarusian, Brazilian Portuguese, Bulgarian, Chinese-BIG5,
+Chinese-CNS, Chinese-EUC-TW, Chinese-GB, Croatian, Cyrillic-ALT,
+Cyrillic-ISO, Cyrillic-KOI8, Czech, Devanagari, Dutch, English,
+Ethiopic, French, Georgian, German, Greek, Hebrew, IPA, Italian,
+Japanese, Kannada, Korean, Lao, Latin-1, Latin-2, Latin-3,
+Latin-4, Latin-5, Latin-6, Latin-7, Latin-8 (Celtic),
+Latin-9 (updated Latin-1 with the Euro sign), Latvian,
+Lithuanian, Malayalam, Polish, Romanian, Russian, Slovak,
+Slovenian, Spanish, Swedish, Tajik, Tamil, Thai, Tibetan,
+Turkish, UTF-8 (for a setup which prefers Unicode characters and
+files encoded in UTF-8), Ukrainian, Vietnamese, Welsh, and
+Windows-1255 (for a setup which prefers Cyrillic characters and
+files encoded in Windows-1255).
@end quotation
-@cindex fonts, for displaying different languages
- To be able to display the script(s) used by your language environment
-on a windowed display, you need to have a suitable font installed. If
-some of the characters appear as empty boxes, download and install the
-GNU Intlfonts distribution, which includes fonts for all supported
-scripts. @xref{Fontsets}, for more details about setting up your
-fonts.
+@cindex fonts for various scripts
+@cindex Intlfonts package, installation
+ 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 most supported scripts.@footnote{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:
+
+@example
+ xset fp+ /usr/local/share/emacs/fonts
+ xset fp rehash
+@end example
+}
+@xref{Fontsets}, for more details about setting up your fonts.
@findex set-locale-environment
@vindex locale-language-names
@vindex locale-charset-language-names
@cindex locales
- Some operating systems let you specify the language you are using by
-setting the locale environment variables @env{LC_ALL}, @env{LC_CTYPE},
-and @env{LANG}; the first of these which is nonempty specifies your
-locale. Emacs handles this during startup by invoking the
-@code{set-locale-environment} function, which matches your locale
-against entries in the value of the variable
-@code{locale-language-names} and selects the corresponding language
-environment if a match is found. But if your locale also matches an
-entry in the variable @code{locale-charset-language-names}, this entry
-is preferred if its character set disagrees. For example, suppose the
-locale @samp{en_GB.ISO8859-15} matches @code{"Latin-1"} in
-@code{locale-language-names} and @code{"Latin-9"} in
-@code{locale-charset-language-names}; since these two language
-environments' character sets disagree, Emacs uses @code{"Latin-9"}.
-
- If all goes well, the @code{set-locale-environment} function selects
-the language environment, since language is part of locale. It also
-adjusts the display table and terminal coding system, the locale coding
-system, and the preferred coding system as needed for the locale.
-
- Since the @code{set-locale-environment} function is automatically
-invoked during startup, you normally do not need to invoke it yourself.
-However, if you modify the @env{LC_ALL}, @env{LC_CTYPE}, or @env{LANG}
-environment variables, you may want to invoke the
-@code{set-locale-environment} function afterwards.
+ Some operating systems let you specify the character-set locale you
+are using by setting the locale environment variables @env{LC_ALL},
+@env{LC_CTYPE}, or @env{LANG}.@footnote{If more than one of these is
+set, the first one that is nonempty specifies your locale for this
+purpose.} 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
+@code{locale-charset-language-names} and @code{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, the
+preferred coding system as needed for the locale, and---last but not
+least---the way Emacs decodes non-@acronym{ASCII} characters sent by your keyboard.
+
+ If you modify the @env{LC_ALL}, @env{LC_CTYPE}, or @env{LANG}
+environment variables while running Emacs, you may want to invoke the
+@code{set-locale-environment} function afterwards to readjust the
+language environment from the new locale.
-@findex set-locale-environment
@vindex locale-preferred-coding-systems
The @code{set-locale-environment} function normally uses the preferred
coding system established by the language environment to decode system
@code{locale-preferred-coding-systems}, Emacs uses that encoding even
though it might normally use @code{japanese-iso-8bit}.
- The environment chosen from the locale when Emacs starts is
-overidden by any explicit use of the command
-@code{set-language-environment} or customization of
-@code{current-language-environment} in your init file.
+ You can override the language environment chosen at startup with
+explicit use of the command @code{set-language-environment}, or with
+customization of @code{current-language-environment} in your init
+file.
@kindex C-h L
@findex describe-language-environment
To display information about the effects of a certain language
environment @var{lang-env}, use the command @kbd{C-h L @var{lang-env}
-@key{RET}} (@code{describe-language-environment}). This tells you which
-languages this language environment is useful for, and lists the
+@key{RET}} (@code{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.
+also shows some sample text to illustrate scripts used in this
+language environment. If you give an empty input for @var{lang-env},
+this command describes the chosen language environment.
@vindex set-language-environment-hook
You can customize any language environment with the normal hook
@code{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
-@code{current-language-environment}.
+@code{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.
@vindex exit-language-environment-hook
Before it starts to set up the new language environment,
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.
+ The simplest kind of input method works by mapping @acronym{ASCII} letters
+into another alphabet; this allows you to use one other alphabet
+instead of @acronym{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
+to produce a single non-@acronym{ASCII} letter from a sequence that consists of a
letter followed by accent characters (or vice versa). For example, some
methods convert the sequence @kbd{a'} into a single accented letter.
These input methods have no special commands of their own; all they do
Chinese and Japanese require more complex methods. In Chinese input
methods, first you enter the phonetic spelling of a Chinese word (in
-input method @code{chinese-py}, among others), or a sequence of portions
-of the character (input methods @code{chinese-4corner} and
-@code{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 @kbd{C-f},
-@kbd{C-b}, @kbd{C-n}, @kbd{C-p}, and digits have special definitions in
-this situation, used for selecting among the alternatives. @key{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 @kbd{C-n} and @kbd{C-p} to cycle through
+input method @code{chinese-py}, among others), or a sequence of
+portions of the character (input methods @code{chinese-4corner} and
+@code{chinese-sw}, and others). One input sequence typically
+corresponds to many possible Chinese characters. You select the one
+you mean using keys such as @kbd{C-f}, @kbd{C-b}, @kbd{C-n},
+@kbd{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; @code{(@var{i}/@var{j})}
+appears at the beginning, to indicate that this is the @var{i}th row
+out of a total of @var{j} rows. Type @kbd{C-n} or @kbd{C-p} to
+display the next row or the previous row.
+
+ Type @kbd{C-f} and @kbd{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 @code{C-@key{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 @var{n} selects the @var{n}th
+alternative of the current row and uses it as input.
+
+ @key{TAB} in these Chinese input methods displays a buffer showing
+all the possible characters at once; then clicking @kbd{Mouse-2} on
+one of them selects that alternative. The keys @kbd{C-f}, @kbd{C-b},
+@kbd{C-n}, @kbd{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 @kbd{C-n} and @kbd{C-p} to cycle through
the alternatives.
Sometimes it is useful to cut off input method processing so that the
sequence @kbd{e '} combines to form an @samp{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
+ One way is to type the accent twice; this is a special feature for
entering the separate letter and accent. For example, @kbd{e ' '} gives
you the two characters @samp{e'}. Another way is to type another letter
after the @kbd{e}---something that won't combine with that---and
@xref{Select Input Method}.
@end ifinfo
+@cindex incremental search, input method interference
@kbd{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.
+ To find out how to input the character after point using the current
+input method, type @kbd{C-u C-x =}. @xref{Position Info}.
+
@vindex input-method-verbose-flag
@vindex input-method-highlight-flag
The variables @code{input-method-highlight-flag} and
-@code{input-method-verbose-flag} control how input methods explain what
-is happening. If @code{input-method-highlight-flag} is non-@code{nil},
-the partial sequence is highlighted in the buffer. If
-@code{input-method-verbose-flag} is non-@code{nil}, the list of possible
-characters to type next is displayed in the echo area (but not when you
-are in the minibuffer).
-
-@cindex Leim package
-Input methods are implemented in the separate Leim package, which must
-be installed with Emacs.
+@code{input-method-verbose-flag} control how input methods explain
+what is happening. If @code{input-method-highlight-flag} is
+non-@code{nil}, the partial sequence is highlighted in the buffer (for
+most input methods---some disable this feature). If
+@code{input-method-verbose-flag} is non-@code{nil}, the list of
+possible characters to type next is displayed in the echo area (but
+not when you are in the minibuffer).
@node Select Input Method
@section Selecting an Input Method
@kindex C-x RET C-\
To choose an input method for the current buffer, use @kbd{C-x
@key{RET} C-\} (@code{set-input-method}). This command reads the
-input method name with the minibuffer; the name normally starts with 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
@code{current-input-method} records which input method is selected.
-
+
@findex toggle-input-method
@kindex C-\
- 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 @kbd{C-\}
+ Input methods use various sequences of @acronym{ASCII} characters to
+stand for non-@acronym{ASCII} characters. Sometimes it is useful to
+turn off the input method temporarily. To do this, type @kbd{C-\}
(@code{toggle-input-method}). To reenable the input method, type
@kbd{C-\} again.
it prompts for you to specify one. This has the same effect as using
@kbd{C-x @key{RET} C-\} to specify an input method.
+ When invoked with a numeric argument, as in @kbd{C-u C-\},
+@code{toggle-input-method} always prompts you for an input method,
+suggesting the most recently selected one as the default.
+
@vindex default-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
@code{default-input-method} specifies the default input method
(@code{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 @code{set-language-environment}. You can instruct
+Emacs to select a different default input method for a certain
+language environment, if you wish, by using
+@code{set-language-environment-hook} (@pxref{Language Environments,
+set-language-environment-hook}). For example:
+
+@lisp
+(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)
+@end lisp
+
+@noindent
+This sets the default input method to be @code{chinese-tonepy}
+whenever you choose a Chinese-GB language environment.
+
@findex quail-set-keyboard-layout
Some input methods for alphabetic scripts work by (in effect)
remapping the keyboard to emulate various keyboard layouts commonly used
actual keyboard layout. To specify which layout your keyboard has, use
the command @kbd{M-x quail-set-keyboard-layout}.
+@findex quail-show-key
+ You can use the command @kbd{M-x quail-show-key} to show what key (or
+key sequence) to type in order to input the character following point,
+using the selected keyboard layout. The command @kbd{C-u C-x =} also
+shows that information in addition to the other information about the
+character.
+
@findex list-input-methods
To display a list of all the supported input methods, type @kbd{M-x
list-input-methods}. The list gives information about each input
method, including the string that stands for it in the mode line.
@node Multibyte Conversion
-@section Unibyte and Multibyte Non-ASCII characters
+@section Unibyte and Multibyte Non-@acronym{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, Emacs assumes you intended to use one of the ISO
-Latin-@var{n} character sets, and converts it to the Emacs code
-representing that Latin-@var{n} character. You select @emph{which} ISO
-Latin character set to use through your choice of language environment
+non-@acronym{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 @kbd{C-q} to insert one, Emacs assumes you
+intended to use one of the ISO Latin-@var{n} character sets, and
+converts it to the Emacs code representing that Latin-@var{n}
+character. You select @emph{which} ISO Latin character set to use
+through your choice of language environment
@iftex
(see above).
@end iftex
@end ifinfo
If you do not specify a choice, the default is Latin-1.
- The same thing happens when you use @kbd{C-q} to enter an octal code
-in this range. If you enter a code in the range 0200 through 0237,
-which forms the @code{eight-bit-control} character set, it is inserted
+ If you insert a character in the range 0200 through 0237, which
+forms the @code{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
-@code{emacs-mule} or @code{raw-text} coding system, which is usually not
-what you want.
+@code{emacs-mule} or @code{raw-text} coding system, which is usually
+not what you want.
@node Coding Systems
@section Coding Systems
coding systems @code{no-conversion}, @code{raw-text} and
@code{emacs-mule} which do not convert printing characters at all.
+@cindex international files from DOS/Windows systems
A special class of coding systems, collectively known as
@dfn{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 @kbd{M-x codepage-setup}. @xref{MS-DOS and MULE}.
-
-@cindex end-of-line conversion
- In addition to converting various representations of non-ASCII
+MS-DOS software. The names of these coding systems are
+@code{cp@var{nnnn}}, where @var{nnnn} is a 3- or 4-digit number of the
+codepage. You can use these encodings just like any other coding
+system; for example, to visit a file encoded in codepage 850, type
+@kbd{C-x @key{RET} c cp850 @key{RET} C-x C-f @var{filename}
+@key{RET}}@footnote{
+In the MS-DOS port of Emacs, you need to create a @code{cp@var{nnn}}
+coding system with @kbd{M-x codepage-setup}, before you can use it.
+@xref{MS-DOS and MULE,,,emacs-extra,Specialized Emacs Features}.}.
+
+ In addition to converting various representations of non-@acronym{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.
@findex describe-coding-system
The command @kbd{C-h C} (@code{describe-coding-system}) displays
information about particular coding systems. You can specify a coding
-system name as argument; alternatively, with an empty argument, it
+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 (@pxref{Recognize Coding}).
@item @dots{}-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.@footnote{It is also specified for MIME `text/*'
+Microsoft systems.@footnote{It is also specified for MIME @samp{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.})
@code{iso-latin-1-mac}.
The coding system @code{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 @code{raw-text}, Emacs copies those
-byte values unchanged, and sets @code{enable-multibyte-characters} to
-@code{nil} in the current buffer so that they will be interpreted
-properly. @code{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.
+@acronym{ASCII} text, but may contain byte values above 127 which are
+not meant to encode non-@acronym{ASCII} characters. With
+@code{raw-text}, Emacs copies those byte values unchanged, and sets
+@code{enable-multibyte-characters} to @code{nil} in the current buffer
+so that they will be interpreted properly. @code{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 @code{no-conversion} specifies no
-character code conversion at all---none for non-ASCII byte values and
+character code conversion at all---none for non-@acronym{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 @code{enable-multibyte-characters} to @code{nil}.
might convert the file contents before you see them. @xref{Visiting}.
The coding system @code{emacs-mule} means that the file contains
-non-ASCII characters stored with the internal Emacs encoding. It
+non-@acronym{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.
@node Recognize Coding
@section Recognizing Coding Systems
- Most of the time, Emacs can recognize which coding system to use for
-any given file---once you have specified your preferences.
+ Emacs tries to recognize which coding system to use for a given text
+as an integral part of reading that text. (This applies to files
+being read, output from subprocesses, text from X selections, etc.)
+Emacs can select the right coding system automatically most of the
+time---once you have specified your preferences.
Some coding systems can be recognized or distinguished by which byte
sequences appear in the data. However, there are coding systems that
reasons to specify a language environment.
@findex prefer-coding-system
- However, you can alter the priority list in detail with the command
-@kbd{M-x prefer-coding-system}. This command reads the name of a coding
-system from the minibuffer, and adds it to the front of the priority
-list, so that it is preferred to all others. If you use this command
-several times, each use adds one element to the front of the priority
-list.
+ However, you can alter the coding system priority list in detail
+with the command @kbd{M-x prefer-coding-system}. This command reads
+the name of a coding system from the minibuffer, and adds it to the
+front of the priority list, so that it is preferred to all others. If
+you use this command several times, each use adds one element to the
+front of the priority list.
If you use a coding system that specifies the end-of-line conversion
-type, such as @code{iso-8859-1-dos}, what that means is that Emacs
+type, such as @code{iso-8859-1-dos}, what this means is that Emacs
should attempt to recognize @code{iso-8859-1} with priority, and should
-use DOS end-of-line conversion in case it recognizes @code{iso-8859-1}.
+use DOS end-of-line conversion when it does recognize @code{iso-8859-1}.
@vindex file-coding-system-alist
Sometimes a file name indicates which coding system to use for the
@code{china-iso-8bit}, you can execute this Lisp expression:
@smallexample
-(modify-coding-system-alist 'file "\\.txt\\'" 'china-iso-8bit)
+(modify-coding-system-alist 'file "\\.txt\\'" 'chinese-iso-8bit)
@end smallexample
@noindent
carriage-return linefeed sequences, then it chooses the end-of-line
conversion accordingly. You can inhibit the automatic use of
end-of-line conversion by setting the variable @code{inhibit-eol-conversion}
-to non-@code{nil}.
+to non-@code{nil}. If you do that, DOS-style files will be displayed
+with the @samp{^M} characters visible in the buffer; some people
+prefer this to the more subtle @samp{(DOS)} end-of-line type
+indication near the left edge of the mode line (@pxref{Mode Line,
+eol-mnemonic}).
@vindex inhibit-iso-escape-detection
@cindex escape sequences in files
By default, the automatic detection of coding system is sensitive to
escape sequences. If Emacs sees a sequence of characters that begin
-with an @key{ESC} character, and the sequence is valid as an ISO-2022
-code, the code is determined as one of ISO-2022 encoding, and the file
-is decoded by the corresponding coding system
-(e.g. @code{iso-2022-7bit}).
+with an escape character, and the sequence is valid as an ISO-2022
+code, that tells Emacs to use one of the ISO-2022 encodings to decode
+the file.
- However, there may be cases that you want to read escape sequences in
-a file as is. In such a case, you can set th variable
+ However, there may be cases that you want to read escape sequences
+in a file as is. In such a case, you can set the variable
@code{inhibit-iso-escape-detection} to non-@code{nil}. Then the code
-detection will ignore any escape sequences, and so no file is detected
-as being encoded in some of ISO-2022 encoding. The result is that all
-escape sequences become visible in a buffer.
+detection ignores any escape sequences, and never uses an ISO-2022
+encoding. The result is that all escape sequences become visible in
+the buffer.
The default value of @code{inhibit-iso-escape-detection} is
-@code{nil}, and it is strongly recommended not to change it. That's
-because many Emacs Lisp source files that contain non-ASCII characters
-are encoded in the coding system @code{iso-2022-7bit} in the Emacs
-distribution, and they won't be decoded correctly when you visit those
-files if you suppress the escape sequence detection.
+@code{nil}. We recommend that you not change it permanently, only for
+one specific operation. That's because many Emacs Lisp source files
+in the Emacs distribution contain non-@acronym{ASCII} characters encoded in the
+coding system @code{iso-2022-7bit}, and they won't be
+decoded correctly when you visit those files if you suppress the
+escape sequence detection.
@vindex coding
You can specify the coding system for a particular file using the
-@samp{-*-@dots{}-*-} construct at the beginning of a file, or a local
-variables list at the end (@pxref{File Variables}). You do this by
-defining a value for the ``variable'' named @code{coding}. Emacs does
-not really have a variable @code{coding}; instead of setting a variable,
-it uses the specified coding system for the file. For example,
-@samp{-*-mode: C; coding: latin-1;-*-} specifies use of the Latin-1
-coding system, as well as C mode. If you specify the coding explicitly
-in the file, that overrides @code{file-coding-system-alist}.
+@w{@samp{-*-@dots{}-*-}} construct at the beginning of a file, or a
+local variables list at the end (@pxref{File Variables}). You do this
+by defining a value for the ``variable'' named @code{coding}. Emacs
+does not really have a variable @code{coding}; instead of setting a
+variable, this uses the specified coding system for the file. For
+example, @samp{-*-mode: C; coding: latin-1;-*-} specifies use of the
+Latin-1 coding system, as well as C mode. When you specify the coding
+explicitly in the file, that overrides
+@code{file-coding-system-alist}.
@vindex auto-coding-alist
- The variable @code{auto-coding-alist} is the strongest way to specify
-the coding system for certain patterns of file names; this variable even
-overrides @samp{-*-coding:-*-} tags in the file itself. Emacs uses this
-feature for tar and archive files, to prevent Emacs from being confused
-by a @samp{-*-coding:-*-} tag in a member of the archive and thinking it
-applies to the archive file as a whole.
+@vindex auto-coding-regexp-alist
+@vindex auto-coding-functions
+ The variables @code{auto-coding-alist},
+@code{auto-coding-regexp-alist} and @code{auto-coding-functions} are
+the strongest way to specify the coding system for certain patterns of
+file names, or for files containing certain patterns; these variables
+even override @samp{-*-coding:-*-} tags in the file itself. Emacs
+uses @code{auto-coding-alist} for tar and archive files, to prevent it
+from being confused by a @samp{-*-coding:-*-} tag in a member of the
+archive and thinking it applies to the archive file as a whole.
+Likewise, Emacs uses @code{auto-coding-regexp-alist} to ensure that
+RMAIL files, whose names in general don't match any particular
+pattern, are decoded correctly. One of the builtin
+@code{auto-coding-functions} detects the encoding for XML files.
+
+ If Emacs recognizes the encoding of a file incorrectly, you can
+reread the file using the correct coding system by typing @kbd{C-x
+@key{RET} r @var{coding-system} @key{RET}}. To see what coding system
+Emacs actually used to decode the file, look at the coding system
+mnemonic letter near the left edge of the mode line (@pxref{Mode
+Line}), or type @kbd{C-h C @key{RET}}.
+
+@findex unify-8859-on-decoding-mode
+ The command @code{unify-8859-on-decoding-mode} enables a mode that
+``unifies'' the Latin alphabets when decoding text. This works by
+converting all non-@acronym{ASCII} Latin-@var{n} characters to either
+Latin-1 or Unicode characters. This way it is easier to use various
+Latin-@var{n} alphabets together. In a future Emacs version we hope
+to move towards full Unicode support and complete unification of
+character sets.
@vindex buffer-file-coding-system
Once Emacs has chosen a coding system for a buffer, it stores that
file. This includes the commands @code{save-buffer} and
@code{write-region}. If you want to write files from this buffer using
a different coding system, you can specify a different coding system for
-the buffer using @code{set-buffer-file-coding-system} (@pxref{Specify
+the buffer using @code{set-buffer-file-coding-system} (@pxref{Text
Coding}).
- While editing a file, you will sometimes insert characters which
-cannot be encoded with the coding system stored in
-@code{buffer-file-coding-system}. For example, suppose you start with
-an ASCII file and insert a few Latin-1 characters into it. Or you could
-edit a text file in Polish encoded in @code{iso-8859-2} and add to it
-translations of several Polish words into Russian. When you save the
-buffer, Emacs can no longer use the previous value of the buffer's
-coding system, because the characters you added cannot be encoded by
-that coding system.
+ You can insert any possible character into any Emacs buffer, but
+most coding systems can only handle some of the possible characters.
+This means that it is possible for you to insert characters that
+cannot be encoded with the coding system that will be used to save the
+buffer. For example, you could start with an @acronym{ASCII} file and insert a
+few Latin-1 characters into it, or you could edit a text file in
+Polish encoded in @code{iso-8859-2} and add some Russian words to it.
+When you save the buffer, Emacs cannot use the current value of
+@code{buffer-file-coding-system}, because the characters you added
+cannot be encoded by that coding system.
When that happens, Emacs tries the most-preferred coding system (set
by @kbd{M-x prefer-coding-system} or @kbd{M-x
-set-language-environment}), and if that coding system can safely encode
-all of the characters in the buffer, Emacs uses it, and stores its value
-in @code{buffer-file-coding-system}. Otherwise, Emacs pops up a window
-with a list of coding systems suitable for encoding the buffer, and
-prompts you to choose one of those coding systems.
-
- If you insert characters which cannot be encoded by the buffer's
-coding system while editing a mail message, Emacs behaves a bit
-differently. It additionally checks whether the most-preferred coding
-system is recommended for use in MIME messages; if it isn't, Emacs tells
-you that the most-preferred coding system is not recommended and prompts
-you for another coding system. This is so you won't inadvertently send
-a message encoded in a way that your recipient's mail software will have
-difficulty decoding. (If you do want to use the most-preferred coding
-system, you can type its name to Emacs prompt anyway.)
+set-language-environment}), and if that coding system can safely
+encode all of the characters in the buffer, Emacs uses it, and stores
+its value in @code{buffer-file-coding-system}. Otherwise, Emacs
+displays a list of coding systems suitable for encoding the buffer's
+contents, and asks you to choose one of those coding systems.
+
+ If you insert the unsuitable characters in a mail message, Emacs
+behaves a bit differently. It additionally checks whether the
+most-preferred coding system is recommended for use in MIME messages;
+if not, Emacs tells you that the most-preferred coding system is
+not recommended and prompts you for another coding system. This is so
+you won't inadvertently send a message encoded in a way that your
+recipient's mail software will have difficulty decoding. (If you do
+want to use the most-preferred coding system, you can still type its
+name in response to the question.)
@vindex sendmail-coding-system
When you send a message with Mail mode (@pxref{Sending Mail}), Emacs has
@vindex rmail-decode-mime-charset
When you get new mail in Rmail, each message is translated
-automatically from the coding system it is written in---as if it were a
+automatically from the coding system it is written in, as if it were a
separate file. This uses the priority list of coding systems that you
have specified. If a MIME message specifies a character set, Rmail
obeys that specification, unless @code{rmail-decode-mime-charset} is
translated (they are read and written in the Emacs internal character
code).
-@node Specify Coding
-@section Specifying a Coding System
+@node Text Coding
+@section Specifying a Coding System for File Text
In cases where Emacs does not automatically choose the right coding
-system, you can use these commands to specify one:
+system for a file's contents, you can use these commands to specify
+one:
@table @kbd
@item C-x @key{RET} f @var{coding} @key{RET}
-Use coding system @var{coding} for the visited file
-in the current buffer.
+Use coding system @var{coding} for saving or revisiting the visited
+file in the current buffer.
@item C-x @key{RET} c @var{coding} @key{RET}
Specify coding system @var{coding} for the immediately following
command.
-@item C-x @key{RET} k @var{coding} @key{RET}
-Use coding system @var{coding} for keyboard input.
-
-@item C-x @key{RET} t @var{coding} @key{RET}
-Use coding system @var{coding} for terminal output.
-
-@item C-x @key{RET} p @var{input-coding} @key{RET} @var{output-coding} @key{RET}
-Use coding systems @var{input-coding} and @var{output-coding} for
-subprocess input and output in the current buffer.
-
-@item C-x @key{RET} x @var{coding} @key{RET}
-Use coding system @var{coding} for transferring selections to and from
-other programs through the window system.
+@item C-x @key{RET} r @var{coding} @key{RET}
+Revisit the current file using the coding system @var{coding}.
-@item C-x @key{RET} X @var{coding} @key{RET}
-Use coding system @var{coding} for transferring @emph{one}
-selection---the next one---to or from the window system.
+@item M-x recode-region @key{RET} @var{right} @key{RET} @var{wrong} @key{RET}
+Convert a region that was decoded using coding system @var{wrong},
+decoding it using coding system @var{right} instead.
@end table
@kindex C-x RET f
@findex set-buffer-file-coding-system
- The command @kbd{C-x @key{RET} f} (@code{set-buffer-file-coding-system})
-specifies the file coding system for the current buffer---in other
-words, which coding system to use when saving or rereading the visited
-file. You specify which coding system using the minibuffer. Since this
-command applies to a file you have already visited, it affects only the
-way the file is saved.
+ The command @kbd{C-x @key{RET} f}
+(@code{set-buffer-file-coding-system}) sets the file coding system for
+the current buffer---in other words, it says which coding system to
+use when saving or reverting the visited file. You specify which
+coding system using the minibuffer. If you specify a coding system
+that cannot handle all of the characters in the buffer, Emacs warns
+you about the troublesome characters when you actually save the
+buffer.
@kindex C-x RET c
@findex universal-coding-system-argument
So if the immediately following command is @kbd{C-x C-f}, for example,
it reads the file using that coding system (and records the coding
-system for when the file is saved). Or if the immediately following
+system for when you later save the file). Or if the immediately following
command is @kbd{C-x C-w}, it writes the file using that coding system.
-Other file commands affected by a specified coding system include
-@kbd{C-x C-i} and @kbd{C-x C-v}, as well as the other-window variants of
-@kbd{C-x C-f}.
-
- @kbd{C-x @key{RET} c} also affects commands that start subprocesses,
-including @kbd{M-x shell} (@pxref{Shell}).
+When you specify the coding system for saving in this way, instead
+of with @kbd{C-x @key{RET} f}, there is no warning if the buffer
+contains characters that the coding system cannot handle.
- However, if the immediately following command does not use the coding
-system, then @kbd{C-x @key{RET} c} ultimately has no effect.
+ Other file commands affected by a specified coding system include
+@kbd{C-x C-i} and @kbd{C-x C-v}, as well as the other-window variants
+of @kbd{C-x C-f}. @kbd{C-x @key{RET} c} also affects commands that
+start subprocesses, including @kbd{M-x shell} (@pxref{Shell}). If the
+immediately following command does not use the coding system, then
+@kbd{C-x @key{RET} c} ultimately has no effect.
An easy way to visit a file with no conversion is with the @kbd{M-x
find-file-literally} command. @xref{Visiting}.
variable to a good choice of default coding system for that language
environment.
-@kindex C-x RET t
-@findex set-terminal-coding-system
- The command @kbd{C-x @key{RET} t} (@code{set-terminal-coding-system})
-specifies the coding system for terminal output. If you specify a
-character code for terminal output, all characters output to the
-terminal are translated into that coding system.
+@kindex C-x RET r
+@findex revert-buffer-with-coding-system
+ If you visit a file with a wrong coding system, you can correct this
+with @kbd{C-x @key{RET} r} (@code{revert-buffer-with-coding-system}).
+This visits the current file again, using a coding system you specify.
- This feature is useful for certain character-only terminals built to
-support specific languages or character sets---for example, European
-terminals that support one of the ISO Latin character sets. You need to
-specify the terminal coding system when using multibyte text, so that
-Emacs knows which characters the terminal can actually handle.
+@findex recode-region
+ If a piece of text has already been inserted into a buffer using the
+wrong coding system, you can redo the decoding of it using @kbd{M-x
+recode-region}. This prompts you for the proper coding system, then
+for the wrong coding system that was actually used, and does the
+conversion. It first encodes the region using the wrong coding system,
+then decodes it again using the proper coding system.
- By default, output to the terminal is not translated at all, unless
-Emacs can deduce the proper coding system from your terminal type or
-your locale specification (@pxref{Language Environments}).
+@node Communication Coding
+@section Coding Systems for Interprocess Communication
-@kindex C-x RET k
-@findex set-keyboard-coding-system
- The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system})
-specifies the coding system for keyboard input. Character-code
-translation of keyboard input is useful for terminals with keys that
-send non-ASCII graphic characters---for example, some terminals designed
-for ISO Latin-1 or subsets of it.
+ This section explains how to specify coding systems for use
+in communication with other processes.
- By default, keyboard input is not translated at all.
+@table @kbd
+@item C-x @key{RET} x @var{coding} @key{RET}
+Use coding system @var{coding} for transferring selections to and from
+other window-based applications.
- There is a similarity between using a coding system translation for
-keyboard input, and using an input method: both define sequences of
-keyboard input that translate into single characters. However, input
-methods are designed to be convenient for interactive use by humans, and
-the sequences that are translated are typically sequences of ASCII
-printing characters. Coding systems typically translate sequences of
-non-graphic characters.
+@item C-x @key{RET} X @var{coding} @key{RET}
+Use coding system @var{coding} for transferring @emph{one}
+selection---the next one---to or from another window-based application.
+
+@item C-x @key{RET} p @var{input-coding} @key{RET} @var{output-coding} @key{RET}
+Use coding systems @var{input-coding} and @var{output-coding} for
+subprocess input and output in the current buffer.
+
+@item C-x @key{RET} c @var{coding} @key{RET}
+Specify coding system @var{coding} for the immediately following
+command.
+@end table
@kindex C-x RET x
@kindex C-x RET X
@findex set-selection-coding-system
@findex set-next-selection-coding-system
The command @kbd{C-x @key{RET} x} (@code{set-selection-coding-system})
-specifies the coding system for sending selected text to the window
-system, and for receiving the text of selections made in other
+specifies the coding system for sending selected text to other windowing
+applications, and for receiving the text of selections made in other
applications. This command applies to all subsequent selections, until
you override it by using the command again. The command @kbd{C-x
@key{RET} X} (@code{set-next-selection-coding-system}) specifies the
and from a particular subprocess by giving the command in the
corresponding buffer.
+ You can also use @kbd{C-x @key{RET} c} just before the command that
+runs or starts a subprocess, to specify the coding system to use for
+communication with that subprocess.
+
The default for translation of process input and output depends on the
current language environment.
+@vindex locale-coding-system
+@cindex decoding non-@acronym{ASCII} keyboard input on X
+ The variable @code{locale-coding-system} specifies a coding system
+to use when encoding and decoding system strings such as system error
+messages and @code{format-time-string} formats and time stamps. That
+coding system is also used for decoding non-@acronym{ASCII} keyboard input on X
+Window systems. You should choose a coding system that is compatible
+with the underlying system's text representation, which is normally
+specified by one of the environment variables @env{LC_ALL},
+@env{LC_CTYPE}, and @env{LANG}. (The first one, in the order
+specified above, whose value is nonempty is the one that determines
+the text representation.)
+
+@node File Name Coding
+@section Coding Systems for File Names
+
+@table @kbd
+@item C-x @key{RET} F @var{coding} @key{RET}
+Use coding system @var{coding} for encoding and decoding file
+@emph{names}.
+@end table
+
@vindex file-name-coding-system
- The variable @code{file-name-coding-system} specifies a coding system
-to use for encoding file names. If you set the variable to a coding
-system name (as a Lisp symbol or a string), Emacs encodes file names
-using that coding system for all file operations. This makes it
-possible to use non-ASCII characters in file names---or, at least, those
-non-ASCII characters which the specified coding system can encode.
-
- If @code{file-name-coding-system} is @code{nil}, Emacs uses a default
-coding system determined by the selected language environment. In the
-default language environment, any non-ASCII characters in file names are
-not encoded specially; they appear in the file system using the internal
-Emacs representation.
+@cindex file names with non-@acronym{ASCII} characters
+ The variable @code{file-name-coding-system} specifies a coding
+system to use for encoding file names. It has no effect on reading
+and writing the @emph{contents} of files.
+
+@findex set-file-name-coding-system
+@kindex C-x @key{RET} F
+ If you set the variable to a coding system name (as a Lisp symbol or
+a string), Emacs encodes file names using that coding system for all
+file operations. This makes it possible to use non-@acronym{ASCII}
+characters in file names---or, at least, those non-@acronym{ASCII}
+characters which the specified coding system can encode. Use @kbd{C-x
+@key{RET} F} (@code{set-file-name-coding-system}) to specify this
+interactively.
+
+ If @code{file-name-coding-system} is @code{nil}, Emacs uses a
+default coding system determined by the selected language environment.
+In the default language environment, any non-@acronym{ASCII}
+characters in file names are not encoded specially; they appear in the
+file system using the internal Emacs representation.
@strong{Warning:} if you change @code{file-name-coding-system} (or the
language environment) in the middle of an Emacs session, problems can
name, or it may get an error. If such a problem happens, use @kbd{C-x
C-w} to specify a new file name for that buffer.
-@vindex locale-coding-system
- The variable @code{locale-coding-system} specifies a coding system to
-use when encoding and decoding system strings such as system error
-messages and @code{format-time-string} formats and time stamps. This
-coding system should be compatible with the underlying system's coding
-system, which is normally specified by the first environment variable in
-the list @env{LC_ALL}, @env{LC_CTYPE}, @env{LANG} whose value is
-nonempty.
+@findex recode-file-name
+ If a mistake occurs when encoding a file name, use the command
+@kbd{M-x recode-file-name} to change the file name's coding
+system. This prompts for an existing file name, its old coding
+system, and the coding system to which you wish to convert.
+
+@node Terminal Coding
+@section Coding Systems for Terminal I/O
+
+@table @kbd
+@item C-x @key{RET} k @var{coding} @key{RET}
+Use coding system @var{coding} for keyboard input.
+
+@item C-x @key{RET} t @var{coding} @key{RET}
+Use coding system @var{coding} for terminal output.
+@end table
+
+@kindex C-x RET t
+@findex set-terminal-coding-system
+ The command @kbd{C-x @key{RET} t} (@code{set-terminal-coding-system})
+specifies the coding system for terminal output. If you specify a
+character code for terminal output, all characters output to the
+terminal are translated into that coding system.
+
+ This feature is useful for certain character-only terminals built to
+support specific languages or character sets---for example, European
+terminals that support one of the ISO Latin character sets. You need to
+specify the terminal coding system when using multibyte text, so that
+Emacs knows which characters the terminal can actually handle.
+
+ By default, output to the terminal is not translated at all, unless
+Emacs can deduce the proper coding system from your terminal type or
+your locale specification (@pxref{Language Environments}).
+
+@kindex C-x RET k
+@findex set-keyboard-coding-system
+@vindex keyboard-coding-system
+ The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system})
+or the variable @code{keyboard-coding-system} specifies the coding
+system for keyboard input. Character-code translation of keyboard
+input is useful for terminals with keys that send non-@acronym{ASCII}
+graphic characters---for example, some terminals designed for ISO
+Latin-1 or subsets of it.
+
+ By default, keyboard input is translated based on your system locale
+setting. If your terminal does not really support the encoding
+implied by your locale (for example, if you find it inserts a
+non-@acronym{ASCII} character if you type @kbd{M-i}), you will need to set
+@code{keyboard-coding-system} to @code{nil} to turn off encoding.
+You can do this by putting
+
+@lisp
+(set-keyboard-coding-system nil)
+@end lisp
+
+@noindent
+in your @file{~/.emacs} file.
+
+ There is a similarity between using a coding system translation for
+keyboard input, and using an input method: both define sequences of
+keyboard input that translate into single characters. However, input
+methods are designed to be convenient for interactive use by humans, and
+the sequences that are translated are typically sequences of @acronym{ASCII}
+printing characters. Coding systems typically translate sequences of
+non-graphic characters.
@node Fontsets
@section Fontsets
@cindex fontsets
- A font for X Windows typically defines shapes for one alphabet or
-script. Therefore, displaying the entire range of scripts that Emacs
-supports requires a collection of many fonts. In Emacs, such a
-collection is called a @dfn{fontset}. A fontset is defined by a list of
-fonts, each assigned to handle a range of character codes.
-
- Each fontset has a name, like a font. The available X fonts are
-defined by the X server; fontsets, however, are defined within Emacs
-itself. Once you have defined a fontset, you can use it within Emacs by
-specifying its name, anywhere that you could use a single font. Of
-course, Emacs fontsets can use only the fonts that the X server
-supports; if certain characters appear on the screen as hollow boxes,
-this means that the fontset in use for them has no font for those
-characters.@footnote{The installation instructions have information on
-additional font support.}
+ A font typically defines shapes for a single alphabet or script.
+Therefore, displaying the entire range of scripts that Emacs supports
+requires a collection of many fonts. In Emacs, such a collection is
+called a @dfn{fontset}. A fontset is defined by a list of fonts, each
+assigned to handle a range of character codes.
+
+ Each fontset has a name, like a font. However, while fonts are
+stored in the system and the available font names are defined by the
+system, fontsets are defined within Emacs itself. Once you have
+defined a fontset, you can use it within Emacs by specifying its name,
+anywhere that you could use a single font. Of course, Emacs fontsets
+can use only the fonts that the system supports; if certain characters
+appear on the screen as hollow boxes, this means that the fontset in
+use for them has no font for those characters.@footnote{The Emacs
+installation instructions have information on additional font
+support.}
Emacs creates two fontsets automatically: the @dfn{standard fontset}
and the @dfn{startup fontset}. The standard fontset is most likely to
-have fonts for a wide variety of non-ASCII characters; however, this is
-not the default for Emacs to use. (By default, Emacs tries to find a
-font which has bold and italic variants.) You can specify use of the
-standard fontset with the @samp{-fn} option, or with the @samp{Font} X
-resource (@pxref{Font X}). For example,
+have fonts for a wide variety of non-@acronym{ASCII} characters;
+however, this is not the default for Emacs to use. (By default, Emacs
+tries to find a font that has bold and italic variants.) You can
+specify use of the standard fontset with the @samp{-fn} option. For
+example,
@example
emacs -fn fontset-standard
@end example
+@noindent
+You can also specify a fontset with the @samp{Font} resource (@pxref{X
+Resources}).
+
A fontset does not necessarily specify a font for every character
code. If a fontset specifies no font for a certain character, or if it
specifies a font that does not exist on your system, then it cannot
display that character properly. It will display that character as an
empty box instead.
-@vindex highlight-wrong-size-font
- The fontset height and width are determined by the ASCII characters
-(that is, by the font used for ASCII characters in that fontset). If
-another font in the fontset has a different height, or a different
-width, then characters assigned to that font are clipped to the
-fontset's size. If @code{highlight-wrong-size-font} is non-@code{nil},
-a box is displayed around these wrong-size characters as well.
-
@node Defining Fontsets
@section Defining fontsets
@samp{medium}, or @samp{i} instead of @samp{r}, or both.
@cindex startup fontset
- If you specify a default ASCII font with the @samp{Font} resource or
+ If you specify a default @acronym{ASCII} font with the @samp{Font} resource or
the @samp{-fn} argument, Emacs generates a fontset from it
automatically. This is the @dfn{startup fontset} and its name is
@code{fontset-startup}. It does this by replacing the @var{foundry},
With the X resource @samp{Emacs.Font}, you can specify a fontset name
just like an actual font name. But be careful not to specify a fontset
name in a wildcard resource like @samp{Emacs*Font}---that wildcard
-specification applies to various other purposes, such as menus, and
+specification matches various other resources, such as for menus, and
menus cannot handle fontsets.
You can specify additional fontsets using X resources named
For the other character sets, Emacs chooses a font based on
@var{fontpattern}. It replaces @samp{fontset-@var{alias}} with values
-that describe the character set. For the ASCII character font,
+that describe the character set. For the @acronym{ASCII} character font,
@samp{fontset-@var{alias}} is replaced with @samp{ISO8859-1}.
In addition, when several consecutive fields are wildcards, Emacs
collapses them into a single wildcard. This is to prevent use of
auto-scaled fonts. Fonts made by scaling larger fonts are not usable
for editing, and scaling a smaller font is not useful because it is
-better to use the smaller font in its own size, which Emacs does.
+better to use the smaller font in its own size, which is what Emacs
+does.
Thus if @var{fontpattern} is this,
@end example
@noindent
-the font specification for ASCII characters would be this:
+the font specification for @acronym{ASCII} characters would be this:
@example
-*-fixed-medium-r-normal-*-24-*-ISO8859-1
@node Undisplayable Characters
@section Undisplayable Characters
-Your terminal may not be able to display some non-@sc{ascii} characters.
-Most non-windowing terminals can only use a single character set,
-specified by the variable @code{default-terminal-coding-system}
-(@pxref{Specify Coding}) and characters which can't be encoded in it are
-displayed as @samp{?} by default. Windowing terminals may not have the
-necessary font available to display a given character and display a
-hollow box instead. You can change the default behavior.
+ There may be a some non-@acronym{ASCII} characters that your terminal cannot
+display. Most text-only terminals support just a single character
+set (use the variable @code{default-terminal-coding-system}
+(@pxref{Terminal Coding}) to tell Emacs which one); characters which
+can't be encoded in that coding system are displayed as @samp{?} by
+default.
+
+ Graphical displays can display a broader range of characters, but
+you may not have fonts installed for all of them; characters that have
+no font appear as a hollow box.
-If you use Latin-1 characters but your terminal can't display Latin-1,
-you can arrange to display mnemonic @sc{ascii} sequences instead, e.g.@:
-@samp{"o} for o-umlaut. Load the library @file{iso-ascii} to do this.
+ If you use Latin-1 characters but your terminal can't display
+Latin-1, you can arrange to display mnemonic @acronym{ASCII} sequences
+instead, e.g.@: @samp{"o} for o-umlaut. Load the library
+@file{iso-ascii} to do this.
-If your terminal can display Latin-1, you can display characters from
-other European character sets using a mixture of equivalent Latin-1
-characters and @sc{ascii} mnemonics. Use the Custom option
-@code{latin1-display} to enable this. The mnemonic @sc{ascii} sequences
-mostly correspond to those of the prefix input methods.
+@vindex latin1-display
+ If your terminal can display Latin-1, you can display characters
+from other European character sets using a mixture of equivalent
+Latin-1 characters and @acronym{ASCII} mnemonics. Customize the variable
+@code{latin1-display} to enable this. The mnemonic @acronym{ASCII}
+sequences mostly correspond to those of the prefix input methods.
-@node Single-Byte Character Support
-@section Single-byte Character Set Support
+@node Unibyte Mode
+@section Unibyte Editing Mode
@cindex European character sets
@cindex accented characters
@cindex ISO Latin character sets
@cindex Unibyte operation
-@vindex enable-multibyte-characters
The ISO 8859 Latin-@var{n} character sets define character codes in
-the range 160 to 255 to handle the accented letters and punctuation
-needed by various European languages (and some non-European ones).
-If you disable multibyte
-characters, Emacs can still handle @emph{one} of these character codes
-at a time. To specify @emph{which} of these codes to use, invoke
-@kbd{M-x set-language-environment} and specify a suitable language
-environment such as @samp{Latin-@var{n}}.
+the range 0240 to 0377 octal (160 to 255 decimal) to handle the
+accented letters and punctuation needed by various European languages
+(and some non-European ones). If you disable multibyte characters,
+Emacs can still handle @emph{one} of these character codes at a time.
+To specify @emph{which} of these codes to use, invoke @kbd{M-x
+set-language-environment} and specify a suitable language environment
+such as @samp{Latin-@var{n}}.
For more information about unibyte operation, see @ref{Enabling
Multibyte}. Note particularly that you probably want to ensure that
-your initialization files are read as unibyte if they contain non-ASCII
-characters.
+your initialization files are read as unibyte if they contain
+non-@acronym{ASCII} characters.
@vindex unibyte-display-via-language-environment
Emacs can also display those characters, provided the terminal or font
-in use supports them. This works automatically. Alternatively, if you
-are using a window system, Emacs can also display single-byte characters
+in use supports them. This works automatically. Alternatively, on a
+graphical display, Emacs can also display single-byte characters
through fontsets, in effect by displaying the equivalent multibyte
characters according to the current language environment. To request
this, set the variable @code{unibyte-display-via-language-environment}
@cindex @code{iso-ascii} library
If your terminal does not support display of the Latin-1 character
-set, Emacs can display these characters as ASCII sequences which at
+set, Emacs can display these characters as @acronym{ASCII} sequences which at
least give you a clear idea of what the characters are. To do this,
load the library @code{iso-ascii}. Similar libraries for other
Latin-@var{n} character sets could be implemented, but we don't have
@findex standard-display-8bit
@cindex 8-bit display
- Normally non-ISO-8859 characters (between characters 128 and 159
+ Normally non-ISO-8859 characters (decimal codes between 128 and 159
inclusive) are displayed as octal escapes. You can change this for
-non-standard `extended' versions of ISO-8859 character sets by using the
+non-standard ``extended'' versions of ISO-8859 character sets by using the
function @code{standard-display-8bit} in the @code{disp-table} library.
- There are several ways you can input single-byte non-ASCII
+ There are two ways to input single-byte non-@acronym{ASCII}
characters:
@itemize @bullet
@cindex 8-bit input
-@item
-If your keyboard can generate character codes 128 and up, representing
-non-ASCII characters, you can execute the following expression to enable
-Emacs to understand them:
-
-@example
-(set-input-mode (car (current-input-mode))
- (nth 1 (current-input-mode))
- 0)
-@end example
-
-It is not necessary to do this under a window system which can
-distinguish 8-bit characters and Meta keys. If you do this on a normal
-terminal, you will probably need to use @kbd{ESC} to type Meta
-characters.@footnote{In some cases, such as the Linux console and
-@code{xterm}, you can arrange for Meta to be converted to @kbd{ESC} and
-still be able type 8-bit characters present directly on the keyboard or
-using @kbd{Compose} or @kbd{AltGr} keys.} @xref{User Input}.
-
@item
You can use an input method for the selected language environment.
@xref{Input Methods}. When you use an input method in a unibyte buffer,
-the non-ASCII character you specify with it is converted to unibyte.
+the non-@acronym{ASCII} character you specify with it is converted to unibyte.
+
+@item
+If your keyboard can generate character codes 128 (decimal) and up,
+representing non-@acronym{ASCII} characters, you can type those character codes
+directly.
+
+On a graphical display, you should not need to do anything special to use
+these keys; they should simply work. On a text-only terminal, you
+should use the command @code{M-x set-keyboard-coding-system} or the
+variable @code{keyboard-coding-system} to specify which coding system
+your keyboard uses (@pxref{Terminal Coding}). Enabling this feature
+will probably require you to use @kbd{ESC} to type Meta characters;
+however, on a console terminal or in @code{xterm}, you can arrange for
+Meta to be converted to @kbd{ESC} and still be able type 8-bit
+characters present directly on the keyboard or using @kbd{Compose} or
+@kbd{AltGr} keys. @xref{User Input}.
@kindex C-x 8
@cindex @code{iso-transl} library
@cindex compose character
@cindex dead character
@item
-For Latin-1 only, you can use the
-key @kbd{C-x 8} as a ``compose character'' prefix for entry of
-non-ASCII Latin-1 printing characters. @kbd{C-x 8} is good for
-insertion (in the minibuffer as well as other buffers), for searching,
-and in any other context where a key sequence is allowed.
+For Latin-1 only, you can use the key @kbd{C-x 8} as a ``compose
+character'' prefix for entry of non-@acronym{ASCII} Latin-1 printing
+characters. @kbd{C-x 8} is good for insertion (in the minibuffer as
+well as other buffers), for searching, and in any other context where
+a key sequence is allowed.
@kbd{C-x 8} works by loading the @code{iso-transl} library. Once that
-library is loaded, the @key{ALT} modifier key, if you have one, serves
-the same purpose as @kbd{C-x 8}; use @key{ALT} together with an accent
-character to modify the following letter. In addition, if you have keys
-for the Latin-1 ``dead accent characters'', they too are defined to
-compose with the following character, once @code{iso-transl} is loaded.
-Use @kbd{C-x 8 C-h} to list the available translations as mnemonic
-command names.
-
-@item
-@cindex @code{iso-acc} library
-@cindex ISO Accents mode
-@findex iso-accents-mode
-@cindex Latin-1, Latin-2 and Latin-3 input mode
-For Latin-1, Latin-2 and Latin-3, @kbd{M-x iso-accents-mode} installs a
-minor mode which provides a facility like the @code{latin-1-prefix}
-input method but independent of the Leim package. This mode is
-buffer-local. It can be customized for various languages with @kbd{M-x
-iso-accents-customize}.
+library is loaded, the @key{ALT} modifier key, if the keyboard has
+one, serves the same purpose as @kbd{C-x 8}: use @key{ALT} together
+with an accent character to modify the following letter. In addition,
+if the keyboard has keys for the Latin-1 ``dead accent characters,''
+they too are defined to compose with the following character, once
+@code{iso-transl} is loaded.
+
+Use @kbd{C-x 8 C-h} to list all the available @kbd{C-x 8} translations.
@end itemize
+
+@node Charsets
+@section Charsets
+@cindex charsets
+
+ Emacs groups all supported characters into disjoint @dfn{charsets}.
+Each character code belongs to one and only one charset. For
+historical reasons, Emacs typically divides an 8-bit character code
+for an extended version of @acronym{ASCII} into two charsets:
+@acronym{ASCII}, which covers the codes 0 through 127, plus another
+charset which covers the ``right-hand part'' (the codes 128 and up).
+For instance, the characters of Latin-1 include the Emacs charset
+@code{ascii} plus the Emacs charset @code{latin-iso8859-1}.
+
+ Emacs characters belonging to different charsets may look the same,
+but they are still different characters. For example, the letter
+@samp{o} with acute accent in charset @code{latin-iso8859-1}, used for
+Latin-1, is different from the letter @samp{o} with acute accent in
+charset @code{latin-iso8859-2}, used for Latin-2.
+
+@findex list-charset-chars
+@cindex characters in a certain charset
+@findex describe-character-set
+ There are two commands for obtaining information about Emacs
+charsets. The command @kbd{M-x list-charset-chars} prompts for a name
+of a character set, and displays all the characters in that character
+set. The command @kbd{M-x describe-character-set} prompts for a
+charset name and displays information about that charset, including
+its internal representation within Emacs.
+
+ To find out which charset a character in the buffer belongs to,
+put point before it and type @kbd{C-u C-x =}.
+
+@ignore
+ arch-tag: 310ba60d-31ef-4ce7-91f1-f282dd57b6b3
+@end ignore