1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1997, 1999, 2000 Free Software Foundation, Inc.
3 @c See file emacs.texi for copying conditions.
4 @node International, Major Modes, Frames, Top
5 @chapter International Character Set Support
7 @cindex international scripts
8 @cindex multibyte characters
9 @cindex encoding of characters
35 Emacs supports a wide variety of international character sets,
36 including European variants of the Latin alphabet, as well as Chinese,
37 Cyrillic, Devanagari (Hindi and Marathi), Ethiopic, Greek, Hebrew, IPA,
38 Japanese, Korean, Lao, Thai, Tibetan, and Vietnamese scripts. These features
39 have been merged from the modified version of Emacs known as MULE (for
40 ``MULti-lingual Enhancement to GNU Emacs'')
43 * International Intro:: Basic concepts of multibyte characters.
44 * Enabling Multibyte:: Controlling whether to use multibyte characters.
45 * Language Environments:: Setting things up for the language you use.
46 * Input Methods:: Entering text characters not on your keyboard.
47 * Select Input Method:: Specifying your choice of input methods.
48 * Multibyte Conversion:: How single-byte characters convert to multibyte.
49 * Coding Systems:: Character set conversion when you read and
50 write files, and so on.
51 * Recognize Coding:: How Emacs figures out which conversion to use.
52 * Specify Coding:: Various ways to choose which conversion to use.
53 * Fontsets:: Fontsets are collections of fonts
54 that cover the whole spectrum of characters.
55 * Defining Fontsets:: Defining a new fontset.
56 * Single-Byte Character Support::
57 You can pick one European character set
58 to use without multibyte characters.
61 @node International Intro
62 @section Introduction to International Character Sets
64 The users of international character sets and scripts have established
65 many more-or-less standard coding systems for storing files. Emacs
66 internally uses a single multibyte character encoding, so that it can
67 intermix characters from all these scripts in a single buffer or string.
68 This encoding represents each non-ASCII character as a sequence of bytes
69 in the range 0200 through 0377. Emacs translates between the multibyte
70 character encoding and various other coding systems when reading and
71 writing files, when exchanging data with subprocesses, and (in some
72 cases) in the @kbd{C-q} command (@pxref{Multibyte Conversion}).
75 @findex view-hello-file
76 The command @kbd{C-h h} (@code{view-hello-file}) displays the file
77 @file{etc/HELLO}, which shows how to say ``hello'' in many languages.
78 This illustrates various scripts. If the font you're using doesn't have
79 characters for all those different languages, you will see some hollow
80 boxes instead of characters; see @ref{Fontsets}.
82 @findex list-charset-chars
83 @cindex characters in a certain charset
84 The command @kbd{M-x list-charset-chars} prompts for a name of a
85 character set, and displays all the characters in that character set.
87 Keyboards, even in the countries where these character sets are used,
88 generally don't have keys for all the characters in them. So Emacs
89 supports various @dfn{input methods}, typically one for each script or
90 language, to make it convenient to type them.
93 The prefix key @kbd{C-x @key{RET}} is used for commands that pertain
94 to multibyte characters, coding systems, and input methods.
96 @node Enabling Multibyte
97 @section Enabling Multibyte Characters
99 You can enable or disable multibyte character support, either for
100 Emacs as a whole, or for a single buffer. When multibyte characters are
101 disabled in a buffer, then each byte in that buffer represents a
102 character, even codes 0200 through 0377. The old features for
103 supporting the European character sets, ISO Latin-1 and ISO Latin-2,
104 work as they did in Emacs 19 and also work for the other ISO 8859
107 However, there is no need to turn off multibyte character support to
108 use ISO Latin; the Emacs multibyte character set includes all the
109 characters in these character sets, and Emacs can translate
110 automatically to and from the ISO codes.
112 To edit a particular file in unibyte representation, visit it using
113 @code{find-file-literally}. @xref{Visiting}. To convert a buffer in
114 multibyte representation into a single-byte representation of the same
115 characters, the easiest way is to save the contents in a file, kill the
116 buffer, and find the file again with @code{find-file-literally}. You
117 can also use @kbd{C-x @key{RET} c}
118 (@code{universal-coding-system-argument}) and specify @samp{raw-text} as
119 the coding system with which to find or save a file. @xref{Specify
120 Coding}. Finding a file as @samp{raw-text} doesn't disable format
121 conversion, uncompression and auto mode selection as
122 @code{find-file-literally} does.
124 @vindex enable-multibyte-characters
125 @vindex default-enable-multibyte-characters
126 To turn off multibyte character support by default, start Emacs with
127 the @samp{--unibyte} option (@pxref{Initial Options}), or set the
128 environment variable @env{EMACS_UNIBYTE}. You can also customize
129 @code{enable-multibyte-characters} or, equivalently, directly set the
130 variable @code{default-enable-multibyte-characters} in your init file to
131 have basically the same effect as @samp{--unibyte}.
133 @cindex Lisp files, and multibyte operation
134 @cindex multibyte operation, and Lisp files
135 @cindex unibyte operation, and Lisp files
136 @cindex init file, and non-ASCII characters
137 @cindex environment variables, and non-ASCII characters
138 Multibyte strings are not created during initialization from the
139 values of environment variables, @file{/etc/passwd} entries etc.@: that
140 contain non-ASCII 8-bit characters. However, Lisp files, when they are
141 loaded for running, and in particular the initialization file
142 @file{.emacs}, are normally read as multibyte---even with
143 @samp{--unibyte}. To avoid multibyte strings being generated by
144 non-ASCII characters in Lisp files, put @samp{-*-unibyte: t;-*-} in a
145 comment on the first line, or specify the coding system @samp{raw-text}
146 with @kbd{C-x @key{RET} c}. Do the same for initialization files for
149 The mode line indicates whether multibyte character support is enabled
150 in the current buffer. If it is, there are two or more characters (most
151 often two dashes) before the colon near the beginning of the mode line.
152 When multibyte characters are not enabled, just one dash precedes the
155 @node Language Environments
156 @section Language Environments
157 @cindex language environments
159 All supported character sets are supported in Emacs buffers whenever
160 multibyte characters are enabled; there is no need to select a
161 particular language in order to display its characters in an Emacs
162 buffer. However, it is important to select a @dfn{language environment}
163 in order to set various defaults. The language environment really
164 represents a choice of preferred script (more or less) rather than a
167 The language environment controls which coding systems to recognize
168 when reading text (@pxref{Recognize Coding}). This applies to files,
169 incoming mail, netnews, and any other text you read into Emacs. It may
170 also specify the default coding system to use when you create a file.
171 Each language environment also specifies a default input method.
173 @findex set-language-environment
174 @vindex current-language-environment
175 To select a language environment, customize the option
176 @code{current-language-environment} or use the command @kbd{M-x
177 set-language-environment}. It makes no difference which buffer is
178 current when you use this command, because the effects apply globally to
179 the Emacs session. The supported language environments include:
183 Chinese-BIG5, Chinese-CNS, Chinese-GB, Cyrillic-ALT, Cyrillic-ISO,
184 Cyrillic-KOI8, Czech, Devanagari, English, Ethiopic, German, Greek,
185 Hebrew, IPA, Japanese, Korean, Lao, Latin-1, Latin-2, Latin-3, Latin-4,
186 Latin-5, Latin-8 (Celtic), Latin-9 (updated Latin-1, with the Euro
187 sign), Polish, Romanian, Slovak, Slovenian, Thai, Tibetan, Turkish, and
191 @findex set-locale-environment
192 @vindex locale-language-names
193 @vindex locale-charset-language-names
194 Some operating systems let you specify the language you are using by
195 setting the locale environment variables @env{LC_ALL}, @env{LC_CTYPE},
196 and @env{LANG}; the first of these which is nonempty specifies your
197 locale. Emacs handles this during startup by invoking the
198 @code{set-locale-environment} function, which matches your locale
199 against entries in the value of the variable
200 @code{locale-language-names} and selects the corresponding language
201 environment if a match is found. But if your locale also matches an
202 entry in the variable @code{locale-charset-language-names}, this entry
203 is preferred if its character set disagrees. For example, suppose the
204 locale @samp{en_GB.ISO8859-15} matches @code{"Latin-1"} in
205 @code{locale-language-names} and @code{"Latin-9"} in
206 @code{locale-charset-language-names}; since these two language
207 environments' character sets disagree, Emacs uses @code{"Latin-9"}.
209 If all goes well, the @code{set-locale-environment} function selects
210 the language environment, since language is part of locale. It also
211 adjusts the display table and terminal coding system, the locale coding
212 system, and the preferred coding system as needed for the locale.
214 Since the @code{set-locale-environment} function is automatically
215 invoked during startup, you normally do not need to invoke it yourself.
216 However, if you modify the @env{LC_ALL}, @env{LC_CTYPE}, or @env{LANG}
217 environment variables, you may want to invoke the
218 @code{set-locale-environment} function afterwards.
220 @findex set-locale-environment
221 @vindex locale-preferred-coding-systems
222 The @code{set-locale-environment} function normally uses the preferred
223 coding system established by the language environment to decode system
224 messages. But if your locale matches an entry in the variable
225 @code{locale-preferred-coding-systems}, Emacs uses the corresponding
226 coding system instead. For example, if the locale @samp{ja_JP.PCK}
227 matches @code{japanese-shift-jis} in
228 @code{locale-preferred-coding-systems}, Emacs uses that encoding even
229 though it might normally use @code{japanese-iso-8bit}.
231 The environment chosen from the locale when Emacs starts is
232 overidden by any explicit use of the command
233 @code{set-language-environment} or customization of
234 @code{current-language-environment} in your init file.
237 @findex describe-language-environment
238 To display information about the effects of a certain language
239 environment @var{lang-env}, use the command @kbd{C-h L @var{lang-env}
240 @key{RET}} (@code{describe-language-environment}). This tells you which
241 languages this language environment is useful for, and lists the
242 character sets, coding systems, and input methods that go with it. It
243 also shows some sample text to illustrate scripts used in this language
244 environment. By default, this command describes the chosen language
247 @vindex set-language-environment-hook
248 You can customize any language environment with the normal hook
249 @code{set-language-environment-hook}. The command
250 @code{set-language-environment} runs that hook after setting up the new
251 language environment. The hook functions can test for a specific
252 language environment by checking the variable
253 @code{current-language-environment}.
255 @vindex exit-language-environment-hook
256 Before it starts to set up the new language environment,
257 @code{set-language-environment} first runs the hook
258 @code{exit-language-environment-hook}. This hook is useful for undoing
259 customizations that were made with @code{set-language-environment-hook}.
260 For instance, if you set up a special key binding in a specific language
261 environment using @code{set-language-environment-hook}, you should set
262 up @code{exit-language-environment-hook} to restore the normal binding
266 @section Input Methods
268 @cindex input methods
269 An @dfn{input method} is a kind of character conversion designed
270 specifically for interactive input. In Emacs, typically each language
271 has its own input method; sometimes several languages which use the same
272 characters can share one input method. A few languages support several
275 The simplest kind of input method works by mapping ASCII letters into
276 another alphabet. This is how the Greek and Russian input methods work.
278 A more powerful technique is composition: converting sequences of
279 characters into one letter. Many European input methods use composition
280 to produce a single non-ASCII letter from a sequence that consists of a
281 letter followed by accent characters (or vice versa). For example, some
282 methods convert the sequence @kbd{a'} into a single accented letter.
283 These input methods have no special commands of their own; all they do
284 is compose sequences of printing characters.
286 The input methods for syllabic scripts typically use mapping followed
287 by composition. The input methods for Thai and Korean work this way.
288 First, letters are mapped into symbols for particular sounds or tone
289 marks; then, sequences of these which make up a whole syllable are
290 mapped into one syllable sign.
292 Chinese and Japanese require more complex methods. In Chinese input
293 methods, first you enter the phonetic spelling of a Chinese word (in
294 input method @code{chinese-py}, among others), or a sequence of portions
295 of the character (input methods @code{chinese-4corner} and
296 @code{chinese-sw}, and others). Since one phonetic spelling typically
297 corresponds to many different Chinese characters, you must select one of
298 the alternatives using special Emacs commands. Keys such as @kbd{C-f},
299 @kbd{C-b}, @kbd{C-n}, @kbd{C-p}, and digits have special definitions in
300 this situation, used for selecting among the alternatives. @key{TAB}
301 displays a buffer showing all the possibilities.
303 In Japanese input methods, first you input a whole word using
304 phonetic spelling; then, after the word is in the buffer, Emacs converts
305 it into one or more characters using a large dictionary. One phonetic
306 spelling corresponds to many differently written Japanese words, so you
307 must select one of them; use @kbd{C-n} and @kbd{C-p} to cycle through
310 Sometimes it is useful to cut off input method processing so that the
311 characters you have just entered will not combine with subsequent
312 characters. For example, in input method @code{latin-1-postfix}, the
313 sequence @kbd{e '} combines to form an @samp{e} with an accent. What if
314 you want to enter them as separate characters?
316 One way is to type the accent twice; that is a special feature for
317 entering the separate letter and accent. For example, @kbd{e ' '} gives
318 you the two characters @samp{e'}. Another way is to type another letter
319 after the @kbd{e}---something that won't combine with that---and
320 immediately delete it. For example, you could type @kbd{e e @key{DEL}
321 '} to get separate @samp{e} and @samp{'}.
323 Another method, more general but not quite as easy to type, is to use
324 @kbd{C-\ C-\} between two characters to stop them from combining. This
325 is the command @kbd{C-\} (@code{toggle-input-method}) used twice.
327 @xref{Select Input Method}.
330 @kbd{C-\ C-\} is especially useful inside an incremental search,
331 because it stops waiting for more characters to combine, and starts
332 searching for what you have already entered.
334 @vindex input-method-verbose-flag
335 @vindex input-method-highlight-flag
336 The variables @code{input-method-highlight-flag} and
337 @code{input-method-verbose-flag} control how input methods explain what
338 is happening. If @code{input-method-highlight-flag} is non-@code{nil},
339 the partial sequence is highlighted in the buffer. If
340 @code{input-method-verbose-flag} is non-@code{nil}, the list of possible
341 characters to type next is displayed in the echo area (but not when you
342 are in the minibuffer).
345 Input methods are implemented in the separate Leim package, which must
346 be installed with Emacs.
348 @node Select Input Method
349 @section Selecting an Input Method
353 Enable or disable use of the selected input method.
355 @item C-x @key{RET} C-\ @var{method} @key{RET}
356 Select a new input method for the current buffer.
358 @item C-h I @var{method} @key{RET}
359 @itemx C-h C-\ @var{method} @key{RET}
360 @findex describe-input-method
363 Describe the input method @var{method} (@code{describe-input-method}).
364 By default, it describes the current input method (if any). This
365 description should give you the full details of how to use any
366 particular input method.
368 @item M-x list-input-methods
369 Display a list of all the supported input methods.
372 @findex set-input-method
373 @vindex current-input-method
375 To choose an input method for the current buffer, use @kbd{C-x
376 @key{RET} C-\} (@code{set-input-method}). This command reads the
377 input method name with the minibuffer; the name normally starts with the
378 language environment that it is meant to be used with. The variable
379 @code{current-input-method} records which input method is selected.
381 @findex toggle-input-method
383 Input methods use various sequences of ASCII characters to stand for
384 non-ASCII characters. Sometimes it is useful to turn off the input
385 method temporarily. To do this, type @kbd{C-\}
386 (@code{toggle-input-method}). To reenable the input method, type
389 If you type @kbd{C-\} and you have not yet selected an input method,
390 it prompts for you to specify one. This has the same effect as using
391 @kbd{C-x @key{RET} C-\} to specify an input method.
393 @vindex default-input-method
394 Selecting a language environment specifies a default input method for
395 use in various buffers. When you have a default input method, you can
396 select it in the current buffer by typing @kbd{C-\}. The variable
397 @code{default-input-method} specifies the default input method
398 (@code{nil} means there is none).
400 @findex quail-set-keyboard-layout
401 Some input methods for alphabetic scripts work by (in effect)
402 remapping the keyboard to emulate various keyboard layouts commonly used
403 for those scripts. How to do this remapping properly depends on your
404 actual keyboard layout. To specify which layout your keyboard has, use
405 the command @kbd{M-x quail-set-keyboard-layout}.
407 @findex list-input-methods
408 To display a list of all the supported input methods, type @kbd{M-x
409 list-input-methods}. The list gives information about each input
410 method, including the string that stands for it in the mode line.
412 @node Multibyte Conversion
413 @section Unibyte and Multibyte Non-ASCII characters
415 When multibyte characters are enabled, character codes 0240 (octal)
416 through 0377 (octal) are not really legitimate in the buffer. The valid
417 non-ASCII printing characters have codes that start from 0400.
419 If you type a self-inserting character in the invalid range 0240
420 through 0377, Emacs assumes you intended to use one of the ISO
421 Latin-@var{n} character sets, and converts it to the Emacs code
422 representing that Latin-@var{n} character. You select @emph{which} ISO
423 Latin character set to use through your choice of language environment
428 (@pxref{Language Environments}).
430 If you do not specify a choice, the default is Latin-1.
432 The same thing happens when you use @kbd{C-q} to enter an octal code
436 @section Coding Systems
437 @cindex coding systems
439 Users of various languages have established many more-or-less standard
440 coding systems for representing them. Emacs does not use these coding
441 systems internally; instead, it converts from various coding systems to
442 its own system when reading data, and converts the internal coding
443 system to other coding systems when writing data. Conversion is
444 possible in reading or writing files, in sending or receiving from the
445 terminal, and in exchanging data with subprocesses.
447 Emacs assigns a name to each coding system. Most coding systems are
448 used for one language, and the name of the coding system starts with the
449 language name. Some coding systems are used for several languages;
450 their names usually start with @samp{iso}. There are also special
451 coding systems @code{no-conversion}, @code{raw-text} and
452 @code{emacs-mule} which do not convert printing characters at all.
454 @cindex end-of-line conversion
455 In addition to converting various representations of non-ASCII
456 characters, a coding system can perform end-of-line conversion. Emacs
457 handles three different conventions for how to separate lines in a file:
458 newline, carriage-return linefeed, and just carriage-return.
461 @item C-h C @var{coding} @key{RET}
462 Describe coding system @var{coding}.
464 @item C-h C @key{RET}
465 Describe the coding systems currently in use.
467 @item M-x list-coding-systems
468 Display a list of all the supported coding systems.
472 @findex describe-coding-system
473 The command @kbd{C-h C} (@code{describe-coding-system}) displays
474 information about particular coding systems. You can specify a coding
475 system name as argument; alternatively, with an empty argument, it
476 describes the coding systems currently selected for various purposes,
477 both in the current buffer and as the defaults, and the priority list
478 for recognizing coding systems (@pxref{Recognize Coding}).
480 @findex list-coding-systems
481 To display a list of all the supported coding systems, type @kbd{M-x
482 list-coding-systems}. The list gives information about each coding
483 system, including the letter that stands for it in the mode line
486 @cindex end-of-line conversion
487 @cindex MS-DOS end-of-line conversion
488 @cindex Macintosh end-of-line conversion
489 Each of the coding systems that appear in this list---except for
490 @code{no-conversion}, which means no conversion of any kind---specifies
491 how and whether to convert printing characters, but leaves the choice of
492 end-of-line conversion to be decided based on the contents of each file.
493 For example, if the file appears to use the sequence carriage-return
494 linefeed to separate lines, DOS end-of-line conversion will be used.
496 Each of the listed coding systems has three variants which specify
497 exactly what to do for end-of-line conversion:
501 Don't do any end-of-line conversion; assume the file uses
502 newline to separate lines. (This is the convention normally used
503 on Unix and GNU systems.)
506 Assume the file uses carriage-return linefeed to separate lines, and do
507 the appropriate conversion. (This is the convention normally used on
508 Microsoft systems.@footnote{It is also specified for MIME `text/*'
509 bodies and in other network transport contexts. It is different
510 from the SGML reference syntax record-start/record-end format which
511 Emacs doesn't support directly.})
514 Assume the file uses carriage-return to separate lines, and do the
515 appropriate conversion. (This is the convention normally used on the
519 These variant coding systems are omitted from the
520 @code{list-coding-systems} display for brevity, since they are entirely
521 predictable. For example, the coding system @code{iso-latin-1} has
522 variants @code{iso-latin-1-unix}, @code{iso-latin-1-dos} and
523 @code{iso-latin-1-mac}.
525 The coding system @code{raw-text} is good for a file which is mainly
526 ASCII text, but may contain byte values above 127 which are not meant to
527 encode non-ASCII characters. With @code{raw-text}, Emacs copies those
528 byte values unchanged, and sets @code{enable-multibyte-characters} to
529 @code{nil} in the current buffer so that they will be interpreted
530 properly. @code{raw-text} handles end-of-line conversion in the usual
531 way, based on the data encountered, and has the usual three variants to
532 specify the kind of end-of-line conversion to use.
534 In contrast, the coding system @code{no-conversion} specifies no
535 character code conversion at all---none for non-ASCII byte values and
536 none for end of line. This is useful for reading or writing binary
537 files, tar files, and other files that must be examined verbatim. It,
538 too, sets @code{enable-multibyte-characters} to @code{nil}.
540 The easiest way to edit a file with no conversion of any kind is with
541 the @kbd{M-x find-file-literally} command. This uses
542 @code{no-conversion}, and also suppresses other Emacs features that
543 might convert the file contents before you see them. @xref{Visiting}.
545 The coding system @code{emacs-mule} means that the file contains
546 non-ASCII characters stored with the internal Emacs encoding. It
547 handles end-of-line conversion based on the data encountered, and has
548 the usual three variants to specify the kind of end-of-line conversion.
550 @node Recognize Coding
551 @section Recognizing Coding Systems
553 Most of the time, Emacs can recognize which coding system to use for
554 any given file---once you have specified your preferences.
556 Some coding systems can be recognized or distinguished by which byte
557 sequences appear in the data. However, there are coding systems that
558 cannot be distinguished, not even potentially. For example, there is no
559 way to distinguish between Latin-1 and Latin-2; they use the same byte
560 values with different meanings.
562 Emacs handles this situation by means of a priority list of coding
563 systems. Whenever Emacs reads a file, if you do not specify the coding
564 system to use, Emacs checks the data against each coding system,
565 starting with the first in priority and working down the list, until it
566 finds a coding system that fits the data. Then it converts the file
567 contents assuming that they are represented in this coding system.
569 The priority list of coding systems depends on the selected language
570 environment (@pxref{Language Environments}). For example, if you use
571 French, you probably want Emacs to prefer Latin-1 to Latin-2; if you use
572 Czech, you probably want Latin-2 to be preferred. This is one of the
573 reasons to specify a language environment.
575 @findex prefer-coding-system
576 However, you can alter the priority list in detail with the command
577 @kbd{M-x prefer-coding-system}. This command reads the name of a coding
578 system from the minibuffer, and adds it to the front of the priority
579 list, so that it is preferred to all others. If you use this command
580 several times, each use adds one element to the front of the priority
583 If you use a coding system that specifies the end-of-line conversion
584 type, such as @code{iso-8859-1-dos}, what that means is that Emacs
585 should attempt to recognize @code{iso-8859-1} with priority, and should
586 use DOS end-of-line conversion in case it recognizes @code{iso-8859-1}.
588 @vindex file-coding-system-alist
589 Sometimes a file name indicates which coding system to use for the
590 file. The variable @code{file-coding-system-alist} specifies this
591 correspondence. There is a special function
592 @code{modify-coding-system-alist} for adding elements to this list. For
593 example, to read and write all @samp{.txt} files using the coding system
594 @code{china-iso-8bit}, you can execute this Lisp expression:
597 (modify-coding-system-alist 'file "\\.txt\\'" 'china-iso-8bit)
601 The first argument should be @code{file}, the second argument should be
602 a regular expression that determines which files this applies to, and
603 the third argument says which coding system to use for these files.
605 @vindex inhibit-eol-conversion
606 @cindex DOS-style end-of-line display
607 Emacs recognizes which kind of end-of-line conversion to use based on
608 the contents of the file: if it sees only carriage-returns, or only
609 carriage-return linefeed sequences, then it chooses the end-of-line
610 conversion accordingly. You can inhibit the automatic use of
611 end-of-line conversion by setting the variable @code{inhibit-eol-conversion}
614 @vindex inhibit-iso-escape-detection
615 @cindex escape sequences in files
616 By default, the automatic detection of coding system is sensitive to
617 escape sequences. If Emacs sees a sequence of characters that begin
618 with an @key{ESC} character, and the sequence is valid as an ISO-2022
619 code, the code is determined as one of ISO-2022 encoding, and the file
620 is decoded by the corresponding coding system
621 (e.g. @code{iso-2022-7bit}).
623 However, there may be cases that you want to read escape sequences in
624 a file as is. In such a case, you can set th variable
625 @code{inhibit-iso-escape-detection} to non-@code{nil}. Then the code
626 detection will ignore any escape sequences, and so no file is detected
627 as being encoded in some of ISO-2022 encoding. The result is that all
628 escape sequences become visible in a buffer.
630 The default value of @code{inhibit-iso-escape-detection} is
631 @code{nil}, and it is strongly recommended not to change it. That's
632 because many Emacs Lisp source files that contain non-ASCII characters
633 are encoded in the coding system @code{iso-2022-7bit} in the Emacs
634 distribution, and they won't be decoded correctly when you visit those
635 files if you suppress the escape sequence detection.
638 You can specify the coding system for a particular file using the
639 @samp{-*-@dots{}-*-} construct at the beginning of a file, or a local
640 variables list at the end (@pxref{File Variables}). You do this by
641 defining a value for the ``variable'' named @code{coding}. Emacs does
642 not really have a variable @code{coding}; instead of setting a variable,
643 it uses the specified coding system for the file. For example,
644 @samp{-*-mode: C; coding: latin-1;-*-} specifies use of the Latin-1
645 coding system, as well as C mode. If you specify the coding explicitly
646 in the file, that overrides @code{file-coding-system-alist}.
648 @vindex auto-coding-alist
649 The variable @code{auto-coding-alist} is the strongest way to specify
650 the coding system for certain patterns of file names; this variable even
651 overrides @samp{-*-coding:-*-} tags in the file itself. Emacs uses this
652 feature for tar and archive files, to prevent Emacs from being confused
653 by a @samp{-*-coding:-*-} tag in a member of the archive and thinking it
654 applies to the archive file as a whole.
656 @vindex buffer-file-coding-system
657 Once Emacs has chosen a coding system for a buffer, it stores that
658 coding system in @code{buffer-file-coding-system} and uses that coding
659 system, by default, for operations that write from this buffer into a
660 file. This includes the commands @code{save-buffer} and
661 @code{write-region}. If you want to write files from this buffer using
662 a different coding system, you can specify a different coding system for
663 the buffer using @code{set-buffer-file-coding-system} (@pxref{Specify
666 While editing a file, you will sometimes insert characters which
667 cannot be encoded with the coding system stored in
668 @code{buffer-file-coding-system}. For example, suppose you start with
669 an ASCII file and insert a few Latin-1 characters into it. Or you could
670 edit a text file in Polish encoded in @code{iso-8859-2} and add to it
671 translations of several Polish words into Russian. When you save the
672 buffer, Emacs can no longer use the previous value of the buffer's
673 coding system, because the characters you added cannot be encoded by
676 When that happens, Emacs tries the most-preferred coding system (set
677 by @kbd{M-x prefer-coding-system} or @kbd{M-x
678 set-language-environment}), and if that coding system can safely encode
679 all of the characters in the buffer, Emacs uses it, and stores its value
680 in @code{buffer-file-coding-system}. Otherwise, Emacs pops up a window
681 with a list of coding systems suitable for encoding the buffer, and
682 prompts you to choose one of those coding systems.
684 If you insert characters which cannot be encoded by the buffer's
685 coding system while editing a mail message, Emacs behaves a bit
686 differently. It additionally checks whether the most-preferred coding
687 system is recommended for use in MIME messages; if it isn't, Emacs tells
688 you that the most-preferred coding system is not recommended and prompts
689 you for another coding system. This is so you won't inadvertently send
690 a message encoded in a way that your recipient's mail software will have
691 difficulty decoding. (If you do want to use the most-preferred coding
692 system, you can type its name to Emacs prompt anyway.)
694 @vindex sendmail-coding-system
695 When you send a message with Mail mode (@pxref{Sending Mail}), Emacs has
696 four different ways to determine the coding system to use for encoding
697 the message text. It tries the buffer's own value of
698 @code{buffer-file-coding-system}, if that is non-@code{nil}. Otherwise,
699 it uses the value of @code{sendmail-coding-system}, if that is
700 non-@code{nil}. The third way is to use the default coding system for
701 new files, which is controlled by your choice of language environment,
702 if that is non-@code{nil}. If all of these three values are @code{nil},
703 Emacs encodes outgoing mail using the Latin-1 coding system.
705 @vindex rmail-decode-mime-charset
706 When you get new mail in Rmail, each message is translated
707 automatically from the coding system it is written in---as if it were a
708 separate file. This uses the priority list of coding systems that you
709 have specified. If a MIME message specifies a character set, Rmail
710 obeys that specification, unless @code{rmail-decode-mime-charset} is
713 @vindex rmail-file-coding-system
714 For reading and saving Rmail files themselves, Emacs uses the coding
715 system specified by the variable @code{rmail-file-coding-system}. The
716 default value is @code{nil}, which means that Rmail files are not
717 translated (they are read and written in the Emacs internal character
721 @section Specifying a Coding System
723 In cases where Emacs does not automatically choose the right coding
724 system, you can use these commands to specify one:
727 @item C-x @key{RET} f @var{coding} @key{RET}
728 Use coding system @var{coding} for the visited file
729 in the current buffer.
731 @item C-x @key{RET} c @var{coding} @key{RET}
732 Specify coding system @var{coding} for the immediately following
735 @item C-x @key{RET} k @var{coding} @key{RET}
736 Use coding system @var{coding} for keyboard input.
738 @item C-x @key{RET} t @var{coding} @key{RET}
739 Use coding system @var{coding} for terminal output.
741 @item C-x @key{RET} p @var{input-coding} @key{RET} @var{output-coding} @key{RET}
742 Use coding systems @var{input-coding} and @var{output-coding} for
743 subprocess input and output in the current buffer.
745 @item C-x @key{RET} x @var{coding} @key{RET}
746 Use coding system @var{coding} for transferring selections to and from
747 other programs through the window system.
749 @item C-x @key{RET} X @var{coding} @key{RET}
750 Use coding system @var{coding} for transferring @emph{one}
751 selection---the next one---to or from the window system.
755 @findex set-buffer-file-coding-system
756 The command @kbd{C-x @key{RET} f} (@code{set-buffer-file-coding-system})
757 specifies the file coding system for the current buffer---in other
758 words, which coding system to use when saving or rereading the visited
759 file. You specify which coding system using the minibuffer. Since this
760 command applies to a file you have already visited, it affects only the
761 way the file is saved.
764 @findex universal-coding-system-argument
765 Another way to specify the coding system for a file is when you visit
766 the file. First use the command @kbd{C-x @key{RET} c}
767 (@code{universal-coding-system-argument}); this command uses the
768 minibuffer to read a coding system name. After you exit the minibuffer,
769 the specified coding system is used for @emph{the immediately following
772 So if the immediately following command is @kbd{C-x C-f}, for example,
773 it reads the file using that coding system (and records the coding
774 system for when the file is saved). Or if the immediately following
775 command is @kbd{C-x C-w}, it writes the file using that coding system.
776 Other file commands affected by a specified coding system include
777 @kbd{C-x C-i} and @kbd{C-x C-v}, as well as the other-window variants of
780 @kbd{C-x @key{RET} c} also affects commands that start subprocesses,
781 including @kbd{M-x shell} (@pxref{Shell}).
783 However, if the immediately following command does not use the coding
784 system, then @kbd{C-x @key{RET} c} ultimately has no effect.
786 An easy way to visit a file with no conversion is with the @kbd{M-x
787 find-file-literally} command. @xref{Visiting}.
789 @vindex default-buffer-file-coding-system
790 The variable @code{default-buffer-file-coding-system} specifies the
791 choice of coding system to use when you create a new file. It applies
792 when you find a new file, and when you create a buffer and then save it
793 in a file. Selecting a language environment typically sets this
794 variable to a good choice of default coding system for that language
798 @findex set-terminal-coding-system
799 The command @kbd{C-x @key{RET} t} (@code{set-terminal-coding-system})
800 specifies the coding system for terminal output. If you specify a
801 character code for terminal output, all characters output to the
802 terminal are translated into that coding system.
804 This feature is useful for certain character-only terminals built to
805 support specific languages or character sets---for example, European
806 terminals that support one of the ISO Latin character sets. You need to
807 specify the terminal coding system when using multibyte text, so that
808 Emacs knows which characters the terminal can actually handle.
810 By default, output to the terminal is not translated at all, unless
811 Emacs can deduce the proper coding system from your terminal type.
814 @findex set-keyboard-coding-system
815 The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system})
816 specifies the coding system for keyboard input. Character-code
817 translation of keyboard input is useful for terminals with keys that
818 send non-ASCII graphic characters---for example, some terminals designed
819 for ISO Latin-1 or subsets of it.
821 By default, keyboard input is not translated at all.
823 There is a similarity between using a coding system translation for
824 keyboard input, and using an input method: both define sequences of
825 keyboard input that translate into single characters. However, input
826 methods are designed to be convenient for interactive use by humans, and
827 the sequences that are translated are typically sequences of ASCII
828 printing characters. Coding systems typically translate sequences of
829 non-graphic characters.
833 @findex set-selection-coding-system
834 @findex set-next-selection-coding-system
835 The command @kbd{C-x @key{RET} x} (@code{set-selection-coding-system})
836 specifies the coding system for sending selected text to the window
837 system, and for receiving the text of selections made in other
838 applications. This command applies to all subsequent selections, until
839 you override it by using the command again. The command @kbd{C-x
840 @key{RET} X} (@code{set-next-selection-coding-system}) specifies the
841 coding system for the next selection made in Emacs or read by Emacs.
844 @findex set-buffer-process-coding-system
845 The command @kbd{C-x @key{RET} p} (@code{set-buffer-process-coding-system})
846 specifies the coding system for input and output to a subprocess. This
847 command applies to the current buffer; normally, each subprocess has its
848 own buffer, and thus you can use this command to specify translation to
849 and from a particular subprocess by giving the command in the
850 corresponding buffer.
852 The default for translation of process input and output depends on the
853 current language environment.
855 @vindex file-name-coding-system
856 The variable @code{file-name-coding-system} specifies a coding system
857 to use for encoding file names. If you set the variable to a coding
858 system name (as a Lisp symbol or a string), Emacs encodes file names
859 using that coding system for all file operations. This makes it
860 possible to use non-ASCII characters in file names---or, at least, those
861 non-ASCII characters which the specified coding system can encode.
863 If @code{file-name-coding-system} is @code{nil}, Emacs uses a default
864 coding system determined by the selected language environment. In the
865 default language environment, any non-ASCII characters in file names are
866 not encoded specially; they appear in the file system using the internal
867 Emacs representation.
869 @strong{Warning:} if you change @code{file-name-coding-system} (or the
870 language environment) in the middle of an Emacs session, problems can
871 result if you have already visited files whose names were encoded using
872 the earlier coding system and cannot be encoded (or are encoded
873 differently) under the new coding system. If you try to save one of
874 these buffers under the visited file name, saving may use the wrong file
875 name, or it may get an error. If such a problem happens, use @kbd{C-x
876 C-w} to specify a new file name for that buffer.
878 @vindex locale-coding-system
879 The variable @code{locale-coding-system} specifies a coding system to
880 use when encoding and decoding system strings such as system error
881 messages and @code{format-time-string} formats and time stamps. This
882 coding system should be compatible with the underlying system's coding
883 system, which is normally specified by the first environment variable in
884 the list @env{LC_ALL}, @env{LC_CTYPE}, @env{LANG} whose value is
891 A font for X Windows typically defines shapes for one alphabet or
892 script. Therefore, displaying the entire range of scripts that Emacs
893 supports requires a collection of many fonts. In Emacs, such a
894 collection is called a @dfn{fontset}. A fontset is defined by a list of
895 fonts, each assigned to handle a range of character codes.
897 Each fontset has a name, like a font. The available X fonts are
898 defined by the X server; fontsets, however, are defined within Emacs
899 itself. Once you have defined a fontset, you can use it within Emacs by
900 specifying its name, anywhere that you could use a single font. Of
901 course, Emacs fontsets can use only the fonts that the X server
902 supports; if certain characters appear on the screen as hollow boxes,
903 this means that the fontset in use for them has no font for those
906 Emacs creates two fontsets automatically: the @dfn{standard fontset}
907 and the @dfn{startup fontset}. The standard fontset is most likely to
908 have fonts for a wide variety of non-ASCII characters; however, this is
909 not the default for Emacs to use. (By default, Emacs tries to find a
910 font which has bold and italic variants.) You can specify use of the
911 standard fontset with the @samp{-fn} option, or with the @samp{Font} X
912 resource (@pxref{Font X}). For example,
915 emacs -fn fontset-standard
918 A fontset does not necessarily specify a font for every character
919 code. If a fontset specifies no font for a certain character, or if it
920 specifies a font that does not exist on your system, then it cannot
921 display that character properly. It will display that character as an
924 @vindex highlight-wrong-size-font
925 The fontset height and width are determined by the ASCII characters
926 (that is, by the font used for ASCII characters in that fontset). If
927 another font in the fontset has a different height, or a different
928 width, then characters assigned to that font are clipped to the
929 fontset's size. If @code{highlight-wrong-size-font} is non-@code{nil},
930 a box is displayed around these wrong-size characters as well.
932 @node Defining Fontsets
933 @section Defining fontsets
935 @vindex standard-fontset-spec
936 @cindex standard fontset
937 Emacs creates a standard fontset automatically according to the value
938 of @code{standard-fontset-spec}. This fontset's name is
941 -*-fixed-medium-r-normal-*-16-*-*-*-*-*-fontset-standard
945 or just @samp{fontset-standard} for short.
947 Bold, italic, and bold-italic variants of the standard fontset are
948 created automatically. Their names have @samp{bold} instead of
949 @samp{medium}, or @samp{i} instead of @samp{r}, or both.
951 @cindex startup fontset
952 If you specify a default ASCII font with the @samp{Font} resource or
953 the @samp{-fn} argument, Emacs generates a fontset from it
954 automatically. This is the @dfn{startup fontset} and its name is
955 @code{fontset-startup}. It does this by replacing the @var{foundry},
956 @var{family}, @var{add_style}, and @var{average_width} fields of the
957 font name with @samp{*}, replacing @var{charset_registry} field with
958 @samp{fontset}, and replacing @var{charset_encoding} field with
959 @samp{startup}, then using the resulting string to specify a fontset.
961 For instance, if you start Emacs this way,
964 emacs -fn "*courier-medium-r-normal--14-140-*-iso8859-1"
968 Emacs generates the following fontset and uses it for the initial X
972 -*-*-medium-r-normal-*-14-140-*-*-*-*-fontset-startup
975 With the X resource @samp{Emacs.Font}, you can specify a fontset name
976 just like an actual font name. But be careful not to specify a fontset
977 name in a wildcard resource like @samp{Emacs*Font}---that wildcard
978 specification applies to various other purposes, such as menus, and
979 menus cannot handle fontsets.
981 You can specify additional fontsets using X resources named
982 @samp{Fontset-@var{n}}, where @var{n} is an integer starting from 0.
983 The resource value should have this form:
986 @var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
990 @var{fontpattern} should have the form of a standard X font name, except
991 for the last two fields. They should have the form
992 @samp{fontset-@var{alias}}.
994 The fontset has two names, one long and one short. The long name is
995 @var{fontpattern}. The short name is @samp{fontset-@var{alias}}. You
996 can refer to the fontset by either name.
998 The construct @samp{@var{charset}:@var{font}} specifies which font to
999 use (in this fontset) for one particular character set. Here,
1000 @var{charset} is the name of a character set, and @var{font} is the
1001 font to use for that character set. You can use this construct any
1002 number of times in defining one fontset.
1004 For the other character sets, Emacs chooses a font based on
1005 @var{fontpattern}. It replaces @samp{fontset-@var{alias}} with values
1006 that describe the character set. For the ASCII character font,
1007 @samp{fontset-@var{alias}} is replaced with @samp{ISO8859-1}.
1009 In addition, when several consecutive fields are wildcards, Emacs
1010 collapses them into a single wildcard. This is to prevent use of
1011 auto-scaled fonts. Fonts made by scaling larger fonts are not usable
1012 for editing, and scaling a smaller font is not useful because it is
1013 better to use the smaller font in its own size, which Emacs does.
1015 Thus if @var{fontpattern} is this,
1018 -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
1022 the font specification for ASCII characters would be this:
1025 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
1029 and the font specification for Chinese GB2312 characters would be this:
1032 -*-fixed-medium-r-normal-*-24-*-gb2312*-*
1035 You may not have any Chinese font matching the above font
1036 specification. Most X distributions include only Chinese fonts that
1037 have @samp{song ti} or @samp{fangsong ti} in @var{family} field. In
1038 such a case, @samp{Fontset-@var{n}} can be specified as below:
1041 Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
1042 chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
1046 Then, the font specifications for all but Chinese GB2312 characters have
1047 @samp{fixed} in the @var{family} field, and the font specification for
1048 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
1051 @findex create-fontset-from-fontset-spec
1052 The function that processes the fontset resource value to create the
1053 fontset is called @code{create-fontset-from-fontset-spec}. You can also
1054 call this function explicitly to create a fontset.
1056 @xref{Font X}, for more information about font naming in X.
1058 @node Single-Byte Character Support
1059 @section Single-byte Character Set Support
1061 @cindex European character sets
1062 @cindex accented characters
1063 @cindex ISO Latin character sets
1064 @cindex Unibyte operation
1065 @vindex enable-multibyte-characters
1066 The ISO 8859 Latin-@var{n} character sets define character codes in
1067 the range 160 to 255 to handle the accented letters and punctuation
1068 needed by various European languages (and some non-European ones).
1069 If you disable multibyte
1070 characters, Emacs can still handle @emph{one} of these character codes
1071 at a time. To specify @emph{which} of these codes to use, invoke
1072 @kbd{M-x set-language-environment} and specify a suitable language
1073 environment such as @samp{Latin-@var{n}}.
1075 For more information about unibyte operation, see @ref{Enabling
1076 Multibyte}. Note particularly that you probably want to ensure that
1077 your initialization files are read as unibyte if they contain non-ASCII
1080 @vindex unibyte-display-via-language-environment
1081 Emacs can also display those characters, provided the terminal or font
1082 in use supports them. This works automatically. Alternatively, if you
1083 are using a window system, Emacs can also display single-byte characters
1084 through fontsets, in effect by displaying the equivalent multibyte
1085 characters according to the current language environment. To request
1086 this, set the variable @code{unibyte-display-via-language-environment}
1087 to a non-@code{nil} value.
1089 @cindex @code{iso-ascii} library
1090 If your terminal does not support display of the Latin-1 character
1091 set, Emacs can display these characters as ASCII sequences which at
1092 least give you a clear idea of what the characters are. To do this,
1093 load the library @code{iso-ascii}. Similar libraries for other
1094 Latin-@var{n} character sets could be implemented, but we don't have
1097 @findex standard-display-8bit
1098 @cindex 8-bit display
1099 Normally non-ISO-8859 characters (between characters 128 and 159
1100 inclusive) are displayed as octal escapes. You can change this for
1101 non-standard `extended' versions of ISO-8859 character sets by using the
1102 function @code{standard-display-8bit} in the @code{disp-table} library.
1104 There are several ways you can input single-byte non-ASCII
1110 If your keyboard can generate character codes 128 and up, representing
1111 non-ASCII characters, you can execute the following expression to enable
1112 Emacs to understand them:
1115 (set-input-mode (car (current-input-mode))
1116 (nth 1 (current-input-mode))
1120 It is not necessary to do this under a window system which can
1121 distinguish 8-bit characters and Meta keys. If you do this on a normal
1122 terminal, you will probably need to use @kbd{ESC} to type Meta
1123 characters.@footnote{In some cases, such as the Linux console and
1124 @code{xterm}, you can arrange for Meta to be converted to @kbd{ESC} and
1125 still be able type 8-bit characters present directly on the keyboard or
1126 using @kbd{Compose} or @kbd{AltGr} keys.} @xref{User Input}.
1129 You can use an input method for the selected language environment.
1130 @xref{Input Methods}. When you use an input method in a unibyte buffer,
1131 the non-ASCII character you specify with it is converted to unibyte.
1134 @cindex @code{iso-transl} library
1135 @cindex compose character
1136 @cindex dead character
1138 For Latin-1 only, you can use the
1139 key @kbd{C-x 8} as a ``compose character'' prefix for entry of
1140 non-ASCII Latin-1 printing characters. @kbd{C-x 8} is good for
1141 insertion (in the minibuffer as well as other buffers), for searching,
1142 and in any other context where a key sequence is allowed.
1144 @kbd{C-x 8} works by loading the @code{iso-transl} library. Once that
1145 library is loaded, the @key{ALT} modifier key, if you have one, serves
1146 the same purpose as @kbd{C-x 8}; use @key{ALT} together with an accent
1147 character to modify the following letter. In addition, if you have keys
1148 for the Latin-1 ``dead accent characters'', they too are defined to
1149 compose with the following character, once @code{iso-transl} is loaded.
1150 Use @kbd{C-x 8 C-h} to list the available translations as mnemonic
1154 @cindex @code{iso-acc} library
1155 @cindex ISO Accents mode
1156 @findex iso-accents-mode
1157 @cindex Latin-1 input mode
1158 For Latin-1, Latin-2 and Latin-3, @kbd{M-x iso-accents-mode} installs a
1159 minor mode which provides a facility like the @code{latin-1-prefix}
1160 input method but independent of the Leim package. This mode is
1161 buffer-local. It can be customized for various languages with @kbd{M-x
1162 iso-accents-customize}.