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
37 Emacs supports a wide variety of international character sets,
38 including European variants of the Latin alphabet, as well as Chinese,
39 Cyrillic, Devanagari (Hindi and Marathi), Ethiopic, Greek, Hebrew, IPA,
40 Japanese, Korean, Lao, Thai, Tibetan, and Vietnamese scripts. These features
41 have been merged from the modified version of Emacs known as MULE (for
42 ``MULti-lingual Enhancement to GNU Emacs'')
44 Emacs also supports various encodings of these characters used by
45 other internationalized software, such as word processors and mailers.
48 * International Intro:: Basic concepts of multibyte characters.
49 * Enabling Multibyte:: Controlling whether to use multibyte characters.
50 * Language Environments:: Setting things up for the language you use.
51 * Input Methods:: Entering text characters not on your keyboard.
52 * Select Input Method:: Specifying your choice of input methods.
53 * Multibyte Conversion:: How single-byte characters convert to multibyte.
54 * Coding Systems:: Character set conversion when you read and
55 write files, and so on.
56 * Recognize Coding:: How Emacs figures out which conversion to use.
57 * Specify Coding:: Various ways to choose which conversion to use.
58 * Fontsets:: Fontsets are collections of fonts
59 that cover the whole spectrum of characters.
60 * Defining Fontsets:: Defining a new fontset.
61 * Undisplayable Characters:: When characters don't display.
62 * Single-Byte Character Support::
63 You can pick one European character set
64 to use without multibyte characters.
67 @node International Intro
68 @section Introduction to International Character Sets
70 The users of international character sets and scripts have established
71 many more-or-less standard coding systems for storing files. Emacs
72 internally uses a single multibyte character encoding, so that it can
73 intermix characters from all these scripts in a single buffer or string.
74 This encoding represents each non-ASCII character as a sequence of bytes
75 in the range 0200 through 0377. Emacs translates between the multibyte
76 character encoding and various other coding systems when reading and
77 writing files, when exchanging data with subprocesses, and (in some
78 cases) in the @kbd{C-q} command (@pxref{Multibyte Conversion}).
81 @findex view-hello-file
82 @cindex undisplayable characters
83 @cindex @samp{?} in display
84 The command @kbd{C-h h} (@code{view-hello-file}) displays the file
85 @file{etc/HELLO}, which shows how to say ``hello'' in many languages.
86 This illustrates various scripts. If some characters can't be
87 displayed on your terminal, they appear as @samp{?} or as hollow boxes
88 (@pxref{Undisplayable Characters}).
90 Keyboards, even in the countries where these character sets are used,
91 generally don't have keys for all the characters in them. So Emacs
92 supports various @dfn{input methods}, typically one for each script or
93 language, to make it convenient to type them.
96 The prefix key @kbd{C-x @key{RET}} is used for commands that pertain
97 to multibyte characters, coding systems, and input methods.
100 @c This is commented out because it doesn't fit here, or anywhere.
101 @c This manual does not discuss "character sets" as they
102 @c are used in Mule, and it makes no sense to mention these commands
103 @c except as part of a larger discussion of the topic.
104 @c But it is not clear that topic is worth mentioning here,
105 @c since that is more of an implementation concept
106 @c than a user-level concept. And when we switch to Unicode,
107 @c character sets in the current sense may not even exist.
109 @findex list-charset-chars
110 @cindex characters in a certain charset
111 The command @kbd{M-x list-charset-chars} prompts for a name of a
112 character set, and displays all the characters in that character set.
114 @findex describe-character-set
115 @cindex character set, description
116 The command @kbd{M-x describe-character-set} prompts for a character
117 set name and displays information about that character set, including
118 its internal representation within Emacs.
121 @node Enabling Multibyte
122 @section Enabling Multibyte Characters
124 You can enable or disable multibyte character support, either for
125 Emacs as a whole, or for a single buffer. When multibyte characters are
126 disabled in a buffer, then each byte in that buffer represents a
127 character, even codes 0200 through 0377. The old features for
128 supporting the European character sets, ISO Latin-1 and ISO Latin-2,
129 work as they did in Emacs 19 and also work for the other ISO 8859
132 However, there is no need to turn off multibyte character support to
133 use ISO Latin; the Emacs multibyte character set includes all the
134 characters in these character sets, and Emacs can translate
135 automatically to and from the ISO codes.
137 To edit a particular file in unibyte representation, visit it using
138 @code{find-file-literally}. @xref{Visiting}. To convert a buffer in
139 multibyte representation into a single-byte representation of the same
140 characters, the easiest way is to save the contents in a file, kill the
141 buffer, and find the file again with @code{find-file-literally}. You
142 can also use @kbd{C-x @key{RET} c}
143 (@code{universal-coding-system-argument}) and specify @samp{raw-text} as
144 the coding system with which to find or save a file. @xref{Specify
145 Coding}. Finding a file as @samp{raw-text} doesn't disable format
146 conversion, uncompression and auto mode selection as
147 @code{find-file-literally} does.
149 @vindex enable-multibyte-characters
150 @vindex default-enable-multibyte-characters
151 To turn off multibyte character support by default, start Emacs with
152 the @samp{--unibyte} option (@pxref{Initial Options}), or set the
153 environment variable @env{EMACS_UNIBYTE}. You can also customize
154 @code{enable-multibyte-characters} or, equivalently, directly set the
155 variable @code{default-enable-multibyte-characters} in your init file to
156 have basically the same effect as @samp{--unibyte}.
158 @cindex Lisp files, and multibyte operation
159 @cindex multibyte operation, and Lisp files
160 @cindex unibyte operation, and Lisp files
161 @cindex init file, and non-ASCII characters
162 @cindex environment variables, and non-ASCII characters
163 With @samp{--unibyte}, multibyte strings are not created during
164 initialization from the values of environment variables,
165 @file{/etc/passwd} entries etc.@: that contain non-ASCII 8-bit
168 Emacs normally loads Lisp files as multibyte, regardless of whether
169 you used @samp{--unibyte}. This includes the Emacs initialization
170 file, @file{.emacs}, and the initialization files of Emacs packages
171 such as Gnus. However, you can specify unibyte loading for a
172 particular Lisp file, by putting @samp{-*-unibyte: t;-*-} in a comment
173 on the first line. Then that file is always loaded as unibyte text,
174 even if you did not start Emacs with @samp{--unibyte}. The motivation
175 for these conventions is that it is more reliable to always load any
176 particular Lisp file in the same way. However, you can load a Lisp
177 file as unibyte, on any one occasion, by typing @kbd{C-x @key{RET} c
178 raw-text @key{RET}} immediately before loading it.
180 The mode line indicates whether multibyte character support is enabled
181 in the current buffer. If it is, there are two or more characters (most
182 often two dashes) before the colon near the beginning of the mode line.
183 When multibyte characters are not enabled, just one dash precedes the
186 @node Language Environments
187 @section Language Environments
188 @cindex language environments
190 All supported character sets are supported in Emacs buffers whenever
191 multibyte characters are enabled; there is no need to select a
192 particular language in order to display its characters in an Emacs
193 buffer. However, it is important to select a @dfn{language environment}
194 in order to set various defaults. The language environment really
195 represents a choice of preferred script (more or less) rather than a
198 The language environment controls which coding systems to recognize
199 when reading text (@pxref{Recognize Coding}). This applies to files,
200 incoming mail, netnews, and any other text you read into Emacs. It may
201 also specify the default coding system to use when you create a file.
202 Each language environment also specifies a default input method.
204 @findex set-language-environment
205 @vindex current-language-environment
206 To select a language environment, customize the option
207 @code{current-language-environment} or use the command @kbd{M-x
208 set-language-environment}. It makes no difference which buffer is
209 current when you use this command, because the effects apply globally to
210 the Emacs session. The supported language environments include:
214 Chinese-BIG5, Chinese-CNS, Chinese-GB, Cyrillic-ALT, Cyrillic-ISO,
215 Cyrillic-KOI8, Czech, Devanagari, English, Ethiopic, German, Greek,
216 Hebrew, IPA, Japanese, Korean, Lao, Latin-1, Latin-2, Latin-3, Latin-4,
217 Latin-5, Latin-8 (Celtic), Latin-9 (updated Latin-1, with the Euro
218 sign), Polish, Romanian, Slovak, Slovenian, Thai, Tibetan, Turkish,
219 Dutch, Spanish, and Vietnamese.
222 @cindex fonts for various scripts
223 To display the script(s) used by your language environment on a
224 graphical display, you need to have a suitable font. If some of the
225 characters appear as empty boxes, you should install the GNU Intlfonts
226 package, which includes fonts for all supported scripts.
227 @xref{Fontsets}, for more details about setting up your fonts.
229 @findex set-locale-environment
230 @vindex locale-language-names
231 @vindex locale-charset-language-names
233 Some operating systems let you specify the language you are using by
234 setting the locale environment variables @env{LC_ALL}, @env{LC_CTYPE},
235 or @env{LANG}.@footnote{If more than one of these is set, the first
236 one that is nonempty specifies your locale for this purpose.} Emacs
237 handles this during startup by matching your locale against entries in
238 the value of the variables @code{locale-charset-language-names} and
239 @code{locale-language-names} and selects the corresponding language
240 environment if a match is found. (The former variable overrides the
241 latter.) It also adjusts the display table and terminal coding
242 system, the locale coding system, and the preferred coding system as
243 needed for the locale.
245 If you modify the @env{LC_ALL}, @env{LC_CTYPE}, or @env{LANG}
246 environment variables while running Emacs, you may want to invoke the
247 @code{set-locale-environment} function afterwards to readjust the
248 language environment from the new locale.
250 @vindex locale-preferred-coding-systems
251 The @code{set-locale-environment} function normally uses the preferred
252 coding system established by the language environment to decode system
253 messages. But if your locale matches an entry in the variable
254 @code{locale-preferred-coding-systems}, Emacs uses the corresponding
255 coding system instead. For example, if the locale @samp{ja_JP.PCK}
256 matches @code{japanese-shift-jis} in
257 @code{locale-preferred-coding-systems}, Emacs uses that encoding even
258 though it might normally use @code{japanese-iso-8bit}.
260 You can override the language environment chosen at startup with
261 explicit use of the command @code{set-language-environment}, or with
262 customization of @code{current-language-environment} in your init
266 @findex describe-language-environment
267 To display information about the effects of a certain language
268 environment @var{lang-env}, use the command @kbd{C-h L @var{lang-env}
269 @key{RET}} (@code{describe-language-environment}). This tells you which
270 languages this language environment is useful for, and lists the
271 character sets, coding systems, and input methods that go with it. It
272 also shows some sample text to illustrate scripts used in this language
273 environment. By default, this command describes the chosen language
276 @vindex set-language-environment-hook
277 You can customize any language environment with the normal hook
278 @code{set-language-environment-hook}. The command
279 @code{set-language-environment} runs that hook after setting up the new
280 language environment. The hook functions can test for a specific
281 language environment by checking the variable
282 @code{current-language-environment}.
284 @vindex exit-language-environment-hook
285 Before it starts to set up the new language environment,
286 @code{set-language-environment} first runs the hook
287 @code{exit-language-environment-hook}. This hook is useful for undoing
288 customizations that were made with @code{set-language-environment-hook}.
289 For instance, if you set up a special key binding in a specific language
290 environment using @code{set-language-environment-hook}, you should set
291 up @code{exit-language-environment-hook} to restore the normal binding
295 @section Input Methods
297 @cindex input methods
298 An @dfn{input method} is a kind of character conversion designed
299 specifically for interactive input. In Emacs, typically each language
300 has its own input method; sometimes several languages which use the same
301 characters can share one input method. A few languages support several
304 The simplest kind of input method works by mapping ASCII letters into
305 another alphabet. This is how the Greek and Russian input methods work.
307 A more powerful technique is composition: converting sequences of
308 characters into one letter. Many European input methods use composition
309 to produce a single non-ASCII letter from a sequence that consists of a
310 letter followed by accent characters (or vice versa). For example, some
311 methods convert the sequence @kbd{a'} into a single accented letter.
312 These input methods have no special commands of their own; all they do
313 is compose sequences of printing characters.
315 The input methods for syllabic scripts typically use mapping followed
316 by composition. The input methods for Thai and Korean work this way.
317 First, letters are mapped into symbols for particular sounds or tone
318 marks; then, sequences of these which make up a whole syllable are
319 mapped into one syllable sign.
321 Chinese and Japanese require more complex methods. In Chinese input
322 methods, first you enter the phonetic spelling of a Chinese word (in
323 input method @code{chinese-py}, among others), or a sequence of portions
324 of the character (input methods @code{chinese-4corner} and
325 @code{chinese-sw}, and others). Since one phonetic spelling typically
326 corresponds to many different Chinese characters, you must select one of
327 the alternatives using special Emacs commands. Keys such as @kbd{C-f},
328 @kbd{C-b}, @kbd{C-n}, @kbd{C-p}, and digits have special definitions in
329 this situation, used for selecting among the alternatives. @key{TAB}
330 displays a buffer showing all the possibilities.
332 In Japanese input methods, first you input a whole word using
333 phonetic spelling; then, after the word is in the buffer, Emacs converts
334 it into one or more characters using a large dictionary. One phonetic
335 spelling corresponds to many differently written Japanese words, so you
336 must select one of them; use @kbd{C-n} and @kbd{C-p} to cycle through
339 Sometimes it is useful to cut off input method processing so that the
340 characters you have just entered will not combine with subsequent
341 characters. For example, in input method @code{latin-1-postfix}, the
342 sequence @kbd{e '} combines to form an @samp{e} with an accent. What if
343 you want to enter them as separate characters?
345 One way is to type the accent twice; that is a special feature for
346 entering the separate letter and accent. For example, @kbd{e ' '} gives
347 you the two characters @samp{e'}. Another way is to type another letter
348 after the @kbd{e}---something that won't combine with that---and
349 immediately delete it. For example, you could type @kbd{e e @key{DEL}
350 '} to get separate @samp{e} and @samp{'}.
352 Another method, more general but not quite as easy to type, is to use
353 @kbd{C-\ C-\} between two characters to stop them from combining. This
354 is the command @kbd{C-\} (@code{toggle-input-method}) used twice.
356 @xref{Select Input Method}.
359 @kbd{C-\ C-\} is especially useful inside an incremental search,
360 because it stops waiting for more characters to combine, and starts
361 searching for what you have already entered.
363 @vindex input-method-verbose-flag
364 @vindex input-method-highlight-flag
365 The variables @code{input-method-highlight-flag} and
366 @code{input-method-verbose-flag} control how input methods explain what
367 is happening. If @code{input-method-highlight-flag} is non-@code{nil},
368 the partial sequence is highlighted in the buffer. If
369 @code{input-method-verbose-flag} is non-@code{nil}, the list of possible
370 characters to type next is displayed in the echo area (but not when you
371 are in the minibuffer).
374 Input methods are implemented in the separate Leim package: they are
375 available only if the system administrator used Leim when building
376 Emacs. If Emacs was built without Leim, you will find that no input
379 @node Select Input Method
380 @section Selecting an Input Method
384 Enable or disable use of the selected input method.
386 @item C-x @key{RET} C-\ @var{method} @key{RET}
387 Select a new input method for the current buffer.
389 @item C-h I @var{method} @key{RET}
390 @itemx C-h C-\ @var{method} @key{RET}
391 @findex describe-input-method
394 Describe the input method @var{method} (@code{describe-input-method}).
395 By default, it describes the current input method (if any). This
396 description should give you the full details of how to use any
397 particular input method.
399 @item M-x list-input-methods
400 Display a list of all the supported input methods.
403 @findex set-input-method
404 @vindex current-input-method
406 To choose an input method for the current buffer, use @kbd{C-x
407 @key{RET} C-\} (@code{set-input-method}). This command reads the
408 input method name with the minibuffer; the name normally starts with the
409 language environment that it is meant to be used with. The variable
410 @code{current-input-method} records which input method is selected.
412 @findex toggle-input-method
414 Input methods use various sequences of ASCII characters to stand for
415 non-ASCII characters. Sometimes it is useful to turn off the input
416 method temporarily. To do this, type @kbd{C-\}
417 (@code{toggle-input-method}). To reenable the input method, type
420 If you type @kbd{C-\} and you have not yet selected an input method,
421 it prompts for you to specify one. This has the same effect as using
422 @kbd{C-x @key{RET} C-\} to specify an input method.
424 @vindex default-input-method
425 Selecting a language environment specifies a default input method for
426 use in various buffers. When you have a default input method, you can
427 select it in the current buffer by typing @kbd{C-\}. The variable
428 @code{default-input-method} specifies the default input method
429 (@code{nil} means there is none).
431 @findex quail-set-keyboard-layout
432 Some input methods for alphabetic scripts work by (in effect)
433 remapping the keyboard to emulate various keyboard layouts commonly used
434 for those scripts. How to do this remapping properly depends on your
435 actual keyboard layout. To specify which layout your keyboard has, use
436 the command @kbd{M-x quail-set-keyboard-layout}.
438 @findex list-input-methods
439 To display a list of all the supported input methods, type @kbd{M-x
440 list-input-methods}. The list gives information about each input
441 method, including the string that stands for it in the mode line.
443 @node Multibyte Conversion
444 @section Unibyte and Multibyte Non-ASCII characters
446 When multibyte characters are enabled, character codes 0240 (octal)
447 through 0377 (octal) are not really legitimate in the buffer. The valid
448 non-ASCII printing characters have codes that start from 0400.
450 If you type a self-inserting character in the range 0240 through
451 0377, or if you use @kbd{C-q} to insert one, Emacs assumes you
452 intended to use one of the ISO Latin-@var{n} character sets, and
453 converts it to the Emacs code representing that Latin-@var{n}
454 character. You select @emph{which} ISO Latin character set to use
455 through your choice of language environment
460 (@pxref{Language Environments}).
462 If you do not specify a choice, the default is Latin-1.
464 If you insert a character in the range 0200 through 0237, which
465 forms the @code{eight-bit-control} character set, it is inserted
466 literally. You should normally avoid doing this since buffers
467 containing such characters have to be written out in either the
468 @code{emacs-mule} or @code{raw-text} coding system, which is usually
472 @section Coding Systems
473 @cindex coding systems
475 Users of various languages have established many more-or-less standard
476 coding systems for representing them. Emacs does not use these coding
477 systems internally; instead, it converts from various coding systems to
478 its own system when reading data, and converts the internal coding
479 system to other coding systems when writing data. Conversion is
480 possible in reading or writing files, in sending or receiving from the
481 terminal, and in exchanging data with subprocesses.
483 Emacs assigns a name to each coding system. Most coding systems are
484 used for one language, and the name of the coding system starts with the
485 language name. Some coding systems are used for several languages;
486 their names usually start with @samp{iso}. There are also special
487 coding systems @code{no-conversion}, @code{raw-text} and
488 @code{emacs-mule} which do not convert printing characters at all.
490 A special class of coding systems, collectively known as
491 @dfn{codepages}, is designed to support text encoded by MS-Windows and
492 MS-DOS software. To use any of these systems, you need to create it
493 with @kbd{M-x codepage-setup}. @xref{MS-DOS and MULE}.
495 In addition to converting various representations of non-ASCII
496 characters, a coding system can perform end-of-line conversion. Emacs
497 handles three different conventions for how to separate lines in a file:
498 newline, carriage-return linefeed, and just carriage-return.
501 @item C-h C @var{coding} @key{RET}
502 Describe coding system @var{coding}.
504 @item C-h C @key{RET}
505 Describe the coding systems currently in use.
507 @item M-x list-coding-systems
508 Display a list of all the supported coding systems.
512 @findex describe-coding-system
513 The command @kbd{C-h C} (@code{describe-coding-system}) displays
514 information about particular coding systems. You can specify a coding
515 system name as argument; alternatively, with an empty argument, it
516 describes the coding systems currently selected for various purposes,
517 both in the current buffer and as the defaults, and the priority list
518 for recognizing coding systems (@pxref{Recognize Coding}).
520 @findex list-coding-systems
521 To display a list of all the supported coding systems, type @kbd{M-x
522 list-coding-systems}. The list gives information about each coding
523 system, including the letter that stands for it in the mode line
526 @cindex end-of-line conversion
527 @cindex MS-DOS end-of-line conversion
528 @cindex Macintosh end-of-line conversion
529 Each of the coding systems that appear in this list---except for
530 @code{no-conversion}, which means no conversion of any kind---specifies
531 how and whether to convert printing characters, but leaves the choice of
532 end-of-line conversion to be decided based on the contents of each file.
533 For example, if the file appears to use the sequence carriage-return
534 linefeed to separate lines, DOS end-of-line conversion will be used.
536 Each of the listed coding systems has three variants which specify
537 exactly what to do for end-of-line conversion:
541 Don't do any end-of-line conversion; assume the file uses
542 newline to separate lines. (This is the convention normally used
543 on Unix and GNU systems.)
546 Assume the file uses carriage-return linefeed to separate lines, and do
547 the appropriate conversion. (This is the convention normally used on
548 Microsoft systems.@footnote{It is also specified for MIME @samp{text/*}
549 bodies and in other network transport contexts. It is different
550 from the SGML reference syntax record-start/record-end format which
551 Emacs doesn't support directly.})
554 Assume the file uses carriage-return to separate lines, and do the
555 appropriate conversion. (This is the convention normally used on the
559 These variant coding systems are omitted from the
560 @code{list-coding-systems} display for brevity, since they are entirely
561 predictable. For example, the coding system @code{iso-latin-1} has
562 variants @code{iso-latin-1-unix}, @code{iso-latin-1-dos} and
563 @code{iso-latin-1-mac}.
565 The coding system @code{raw-text} is good for a file which is mainly
566 ASCII text, but may contain byte values above 127 which are not meant to
567 encode non-ASCII characters. With @code{raw-text}, Emacs copies those
568 byte values unchanged, and sets @code{enable-multibyte-characters} to
569 @code{nil} in the current buffer so that they will be interpreted
570 properly. @code{raw-text} handles end-of-line conversion in the usual
571 way, based on the data encountered, and has the usual three variants to
572 specify the kind of end-of-line conversion to use.
574 In contrast, the coding system @code{no-conversion} specifies no
575 character code conversion at all---none for non-ASCII byte values and
576 none for end of line. This is useful for reading or writing binary
577 files, tar files, and other files that must be examined verbatim. It,
578 too, sets @code{enable-multibyte-characters} to @code{nil}.
580 The easiest way to edit a file with no conversion of any kind is with
581 the @kbd{M-x find-file-literally} command. This uses
582 @code{no-conversion}, and also suppresses other Emacs features that
583 might convert the file contents before you see them. @xref{Visiting}.
585 The coding system @code{emacs-mule} means that the file contains
586 non-ASCII characters stored with the internal Emacs encoding. It
587 handles end-of-line conversion based on the data encountered, and has
588 the usual three variants to specify the kind of end-of-line conversion.
590 @node Recognize Coding
591 @section Recognizing Coding Systems
593 Most of the time, Emacs can recognize which coding system to use for
594 any given file---once you have specified your preferences.
596 Some coding systems can be recognized or distinguished by which byte
597 sequences appear in the data. However, there are coding systems that
598 cannot be distinguished, not even potentially. For example, there is no
599 way to distinguish between Latin-1 and Latin-2; they use the same byte
600 values with different meanings.
602 Emacs handles this situation by means of a priority list of coding
603 systems. Whenever Emacs reads a file, if you do not specify the coding
604 system to use, Emacs checks the data against each coding system,
605 starting with the first in priority and working down the list, until it
606 finds a coding system that fits the data. Then it converts the file
607 contents assuming that they are represented in this coding system.
609 The priority list of coding systems depends on the selected language
610 environment (@pxref{Language Environments}). For example, if you use
611 French, you probably want Emacs to prefer Latin-1 to Latin-2; if you use
612 Czech, you probably want Latin-2 to be preferred. This is one of the
613 reasons to specify a language environment.
615 @findex prefer-coding-system
616 However, you can alter the priority list in detail with the command
617 @kbd{M-x prefer-coding-system}. This command reads the name of a coding
618 system from the minibuffer, and adds it to the front of the priority
619 list, so that it is preferred to all others. If you use this command
620 several times, each use adds one element to the front of the priority
623 If you use a coding system that specifies the end-of-line conversion
624 type, such as @code{iso-8859-1-dos}, what that means is that Emacs
625 should attempt to recognize @code{iso-8859-1} with priority, and should
626 use DOS end-of-line conversion in case it recognizes @code{iso-8859-1}.
628 @vindex file-coding-system-alist
629 Sometimes a file name indicates which coding system to use for the
630 file. The variable @code{file-coding-system-alist} specifies this
631 correspondence. There is a special function
632 @code{modify-coding-system-alist} for adding elements to this list. For
633 example, to read and write all @samp{.txt} files using the coding system
634 @code{china-iso-8bit}, you can execute this Lisp expression:
637 (modify-coding-system-alist 'file "\\.txt\\'" 'china-iso-8bit)
641 The first argument should be @code{file}, the second argument should be
642 a regular expression that determines which files this applies to, and
643 the third argument says which coding system to use for these files.
645 @vindex inhibit-eol-conversion
646 @cindex DOS-style end-of-line display
647 Emacs recognizes which kind of end-of-line conversion to use based on
648 the contents of the file: if it sees only carriage-returns, or only
649 carriage-return linefeed sequences, then it chooses the end-of-line
650 conversion accordingly. You can inhibit the automatic use of
651 end-of-line conversion by setting the variable @code{inhibit-eol-conversion}
654 @vindex inhibit-iso-escape-detection
655 @cindex escape sequences in files
656 By default, the automatic detection of coding system is sensitive to
657 escape sequences. If Emacs sees a sequence of characters that begin
658 with an escape character, and the sequence is valid as an ISO-2022
659 code, that tells Emacs to use one of the ISO-2022 encodings to decode
662 However, there may be cases that you want to read escape sequences
663 in a file as is. In such a case, you can set the variable
664 @code{inhibit-iso-escape-detection} to non-@code{nil}. Then the code
665 detection ignores any escape sequences, and never uses an ISO-2022
666 encoding. The result is that all escape sequences become visible in
669 The default value of @code{inhibit-iso-escape-detection} is
670 @code{nil}. We recommend that you not change it permanently, only for
671 one specific operation. That's because many Emacs Lisp source files
672 that contain non-ASCII characters are encoded in the coding system
673 @code{iso-2022-7bit} in the Emacs distribution, and they won't be
674 decoded correctly when you visit those files if you suppress the
675 escape sequence detection.
678 You can specify the coding system for a particular file using the
679 @samp{-*-@dots{}-*-} construct at the beginning of a file, or a local
680 variables list at the end (@pxref{File Variables}). You do this by
681 defining a value for the ``variable'' named @code{coding}. Emacs does
682 not really have a variable @code{coding}; instead of setting a variable,
683 it uses the specified coding system for the file. For example,
684 @samp{-*-mode: C; coding: latin-1;-*-} specifies use of the Latin-1
685 coding system, as well as C mode. If you specify the coding explicitly
686 in the file, that overrides @code{file-coding-system-alist}.
688 @vindex auto-coding-alist
689 The variable @code{auto-coding-alist} is the strongest way to specify
690 the coding system for certain patterns of file names; this variable even
691 overrides @samp{-*-coding:-*-} tags in the file itself. Emacs uses this
692 feature for tar and archive files, to prevent Emacs from being confused
693 by a @samp{-*-coding:-*-} tag in a member of the archive and thinking it
694 applies to the archive file as a whole.
696 @vindex buffer-file-coding-system
697 Once Emacs has chosen a coding system for a buffer, it stores that
698 coding system in @code{buffer-file-coding-system} and uses that coding
699 system, by default, for operations that write from this buffer into a
700 file. This includes the commands @code{save-buffer} and
701 @code{write-region}. If you want to write files from this buffer using
702 a different coding system, you can specify a different coding system for
703 the buffer using @code{set-buffer-file-coding-system} (@pxref{Specify
706 You can insert any possible character into any Emacs buffer, but
707 most coding systems can only handle some of the possible characters.
708 This means that you can insert characters that cannot be encoded with
709 the coding system that will be used to save the buffer. For example,
710 you could start with an ASCII file and insert a few Latin-1 characters
711 into it, or you could edit a text file in Polish encoded in
712 @code{iso-8859-2} and add to it translations of several Polish words
713 into Russian. When you save the buffer, Emacs cannot use the current
714 value of @code{buffer-file-coding-system}, because the characters you
715 added cannot be encoded by that coding system.
717 When that happens, Emacs tries the most-preferred coding system (set
718 by @kbd{M-x prefer-coding-system} or @kbd{M-x
719 set-language-environment}), and if that coding system can safely
720 encode all of the characters in the buffer, Emacs uses it, and stores
721 its value in @code{buffer-file-coding-system}. Otherwise, Emacs
722 displays a list of coding systems suitable for encoding the buffer's
723 contents, and asks to choose one of those coding systems.
725 If you insert the unsuitable characters in a mail message, Emacs
726 behaves a bit differently. It additionally checks whether the
727 most-preferred coding system is recommended for use in MIME messages;
728 if it isn't, Emacs tells you that the most-preferred coding system is
729 not recommended and prompts you for another coding system. This is so
730 you won't inadvertently send a message encoded in a way that your
731 recipient's mail software will have difficulty decoding. (If you do
732 want to use the most-preferred coding system, you can type its name to
733 Emacs prompt anyway.)
735 @vindex sendmail-coding-system
736 When you send a message with Mail mode (@pxref{Sending Mail}), Emacs has
737 four different ways to determine the coding system to use for encoding
738 the message text. It tries the buffer's own value of
739 @code{buffer-file-coding-system}, if that is non-@code{nil}. Otherwise,
740 it uses the value of @code{sendmail-coding-system}, if that is
741 non-@code{nil}. The third way is to use the default coding system for
742 new files, which is controlled by your choice of language environment,
743 if that is non-@code{nil}. If all of these three values are @code{nil},
744 Emacs encodes outgoing mail using the Latin-1 coding system.
746 @vindex rmail-decode-mime-charset
747 When you get new mail in Rmail, each message is translated
748 automatically from the coding system it is written in---as if it were a
749 separate file. This uses the priority list of coding systems that you
750 have specified. If a MIME message specifies a character set, Rmail
751 obeys that specification, unless @code{rmail-decode-mime-charset} is
754 @vindex rmail-file-coding-system
755 For reading and saving Rmail files themselves, Emacs uses the coding
756 system specified by the variable @code{rmail-file-coding-system}. The
757 default value is @code{nil}, which means that Rmail files are not
758 translated (they are read and written in the Emacs internal character
762 @section Specifying a Coding System
764 In cases where Emacs does not automatically choose the right coding
765 system, you can use these commands to specify one:
768 @item C-x @key{RET} f @var{coding} @key{RET}
769 Use coding system @var{coding} for the visited file
770 in the current buffer.
772 @item C-x @key{RET} c @var{coding} @key{RET}
773 Specify coding system @var{coding} for the immediately following
776 @item C-x @key{RET} k @var{coding} @key{RET}
777 Use coding system @var{coding} for keyboard input.
779 @item C-x @key{RET} t @var{coding} @key{RET}
780 Use coding system @var{coding} for terminal output.
782 @item C-x @key{RET} p @var{input-coding} @key{RET} @var{output-coding} @key{RET}
783 Use coding systems @var{input-coding} and @var{output-coding} for
784 subprocess input and output in the current buffer.
786 @item C-x @key{RET} x @var{coding} @key{RET}
787 Use coding system @var{coding} for transferring selections to and from
788 other programs through the window system.
790 @item C-x @key{RET} X @var{coding} @key{RET}
791 Use coding system @var{coding} for transferring @emph{one}
792 selection---the next one---to or from the window system.
796 @findex set-buffer-file-coding-system
797 The command @kbd{C-x @key{RET} f} (@code{set-buffer-file-coding-system})
798 specifies the file coding system for the current buffer---in other
799 words, which coding system to use when saving or rereading the visited
800 file. You specify which coding system using the minibuffer. Since this
801 command applies to a file you have already visited, it affects only the
802 way the file is saved.
805 @findex universal-coding-system-argument
806 Another way to specify the coding system for a file is when you visit
807 the file. First use the command @kbd{C-x @key{RET} c}
808 (@code{universal-coding-system-argument}); this command uses the
809 minibuffer to read a coding system name. After you exit the minibuffer,
810 the specified coding system is used for @emph{the immediately following
813 So if the immediately following command is @kbd{C-x C-f}, for example,
814 it reads the file using that coding system (and records the coding
815 system for when the file is saved). Or if the immediately following
816 command is @kbd{C-x C-w}, it writes the file using that coding system.
817 Other file commands affected by a specified coding system include
818 @kbd{C-x C-i} and @kbd{C-x C-v}, as well as the other-window variants of
821 @kbd{C-x @key{RET} c} also affects commands that start subprocesses,
822 including @kbd{M-x shell} (@pxref{Shell}).
824 However, if the immediately following command does not use the coding
825 system, then @kbd{C-x @key{RET} c} ultimately has no effect.
827 An easy way to visit a file with no conversion is with the @kbd{M-x
828 find-file-literally} command. @xref{Visiting}.
830 @vindex default-buffer-file-coding-system
831 The variable @code{default-buffer-file-coding-system} specifies the
832 choice of coding system to use when you create a new file. It applies
833 when you find a new file, and when you create a buffer and then save it
834 in a file. Selecting a language environment typically sets this
835 variable to a good choice of default coding system for that language
839 @findex set-terminal-coding-system
840 The command @kbd{C-x @key{RET} t} (@code{set-terminal-coding-system})
841 specifies the coding system for terminal output. If you specify a
842 character code for terminal output, all characters output to the
843 terminal are translated into that coding system.
845 This feature is useful for certain character-only terminals built to
846 support specific languages or character sets---for example, European
847 terminals that support one of the ISO Latin character sets. You need to
848 specify the terminal coding system when using multibyte text, so that
849 Emacs knows which characters the terminal can actually handle.
851 By default, output to the terminal is not translated at all, unless
852 Emacs can deduce the proper coding system from your terminal type or
853 your locale specification (@pxref{Language Environments}).
856 @findex set-keyboard-coding-system
857 @vindex keyboard-coding-system
858 The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system})
859 or the Custom option @code{keyboard-coding-system}
860 specifies the coding system for keyboard input. Character-code
861 translation of keyboard input is useful for terminals with keys that
862 send non-ASCII graphic characters---for example, some terminals designed
863 for ISO Latin-1 or subsets of it.
865 By default, keyboard input is not translated at all.
867 There is a similarity between using a coding system translation for
868 keyboard input, and using an input method: both define sequences of
869 keyboard input that translate into single characters. However, input
870 methods are designed to be convenient for interactive use by humans, and
871 the sequences that are translated are typically sequences of ASCII
872 printing characters. Coding systems typically translate sequences of
873 non-graphic characters.
877 @findex set-selection-coding-system
878 @findex set-next-selection-coding-system
879 The command @kbd{C-x @key{RET} x} (@code{set-selection-coding-system})
880 specifies the coding system for sending selected text to the window
881 system, and for receiving the text of selections made in other
882 applications. This command applies to all subsequent selections, until
883 you override it by using the command again. The command @kbd{C-x
884 @key{RET} X} (@code{set-next-selection-coding-system}) specifies the
885 coding system for the next selection made in Emacs or read by Emacs.
888 @findex set-buffer-process-coding-system
889 The command @kbd{C-x @key{RET} p} (@code{set-buffer-process-coding-system})
890 specifies the coding system for input and output to a subprocess. This
891 command applies to the current buffer; normally, each subprocess has its
892 own buffer, and thus you can use this command to specify translation to
893 and from a particular subprocess by giving the command in the
894 corresponding buffer.
896 The default for translation of process input and output depends on the
897 current language environment.
899 @vindex file-name-coding-system
900 The variable @code{file-name-coding-system} specifies a coding system
901 to use for encoding file names. If you set the variable to a coding
902 system name (as a Lisp symbol or a string), Emacs encodes file names
903 using that coding system for all file operations. This makes it
904 possible to use non-ASCII characters in file names---or, at least, those
905 non-ASCII characters which the specified coding system can encode.
907 If @code{file-name-coding-system} is @code{nil}, Emacs uses a default
908 coding system determined by the selected language environment. In the
909 default language environment, any non-ASCII characters in file names are
910 not encoded specially; they appear in the file system using the internal
911 Emacs representation.
913 @strong{Warning:} if you change @code{file-name-coding-system} (or the
914 language environment) in the middle of an Emacs session, problems can
915 result if you have already visited files whose names were encoded using
916 the earlier coding system and cannot be encoded (or are encoded
917 differently) under the new coding system. If you try to save one of
918 these buffers under the visited file name, saving may use the wrong file
919 name, or it may get an error. If such a problem happens, use @kbd{C-x
920 C-w} to specify a new file name for that buffer.
922 @vindex locale-coding-system
923 The variable @code{locale-coding-system} specifies a coding system
924 to use when encoding and decoding system strings such as system error
925 messages and @code{format-time-string} formats and time stamps. You
926 should choose a coding system that is compatible with the underlying
927 system's text representation, which is normally specified by one of
928 the environment variables @env{LC_ALL}, @env{LC_CTYPE}, and
929 @env{LANG}. (The first one whose value is nonempty is the one that
930 determines the text representation.)
936 A font for X typically defines shapes for one alphabet or script.
937 Therefore, displaying the entire range of scripts that Emacs supports
938 requires a collection of many fonts. In Emacs, such a collection is
939 called a @dfn{fontset}. A fontset is defined by a list of fonts, each
940 assigned to handle a range of character codes.
942 Each fontset has a name, like a font. The available X fonts are
943 defined by the X server; fontsets, however, are defined within Emacs
944 itself. Once you have defined a fontset, you can use it within Emacs by
945 specifying its name, anywhere that you could use a single font. Of
946 course, Emacs fontsets can use only the fonts that the X server
947 supports; if certain characters appear on the screen as hollow boxes,
948 this means that the fontset in use for them has no font for those
949 characters.@footnote{The Emacs installation instructions have information on
950 additional font support.}
952 Emacs creates two fontsets automatically: the @dfn{standard fontset}
953 and the @dfn{startup fontset}. The standard fontset is most likely to
954 have fonts for a wide variety of non-ASCII characters; however, this is
955 not the default for Emacs to use. (By default, Emacs tries to find a
956 font which has bold and italic variants.) You can specify use of the
957 standard fontset with the @samp{-fn} option, or with the @samp{Font} X
958 resource (@pxref{Font X}). For example,
961 emacs -fn fontset-standard
964 A fontset does not necessarily specify a font for every character
965 code. If a fontset specifies no font for a certain character, or if it
966 specifies a font that does not exist on your system, then it cannot
967 display that character properly. It will display that character as an
970 @vindex highlight-wrong-size-font
971 The fontset height and width are determined by the ASCII characters
972 (that is, by the font used for ASCII characters in that fontset). If
973 another font in the fontset has a different height, or a different
974 width, then characters assigned to that font are clipped to the
975 fontset's size. If @code{highlight-wrong-size-font} is non-@code{nil},
976 a box is displayed around these wrong-size characters as well.
978 @node Defining Fontsets
979 @section Defining fontsets
981 @vindex standard-fontset-spec
982 @cindex standard fontset
983 Emacs creates a standard fontset automatically according to the value
984 of @code{standard-fontset-spec}. This fontset's name is
987 -*-fixed-medium-r-normal-*-16-*-*-*-*-*-fontset-standard
991 or just @samp{fontset-standard} for short.
993 Bold, italic, and bold-italic variants of the standard fontset are
994 created automatically. Their names have @samp{bold} instead of
995 @samp{medium}, or @samp{i} instead of @samp{r}, or both.
997 @cindex startup fontset
998 If you specify a default ASCII font with the @samp{Font} resource or
999 the @samp{-fn} argument, Emacs generates a fontset from it
1000 automatically. This is the @dfn{startup fontset} and its name is
1001 @code{fontset-startup}. It does this by replacing the @var{foundry},
1002 @var{family}, @var{add_style}, and @var{average_width} fields of the
1003 font name with @samp{*}, replacing @var{charset_registry} field with
1004 @samp{fontset}, and replacing @var{charset_encoding} field with
1005 @samp{startup}, then using the resulting string to specify a fontset.
1007 For instance, if you start Emacs this way,
1010 emacs -fn "*courier-medium-r-normal--14-140-*-iso8859-1"
1014 Emacs generates the following fontset and uses it for the initial X
1018 -*-*-medium-r-normal-*-14-140-*-*-*-*-fontset-startup
1021 With the X resource @samp{Emacs.Font}, you can specify a fontset name
1022 just like an actual font name. But be careful not to specify a fontset
1023 name in a wildcard resource like @samp{Emacs*Font}---that wildcard
1024 specification applies to various other purposes, such as menus, and
1025 menus cannot handle fontsets.
1027 You can specify additional fontsets using X resources named
1028 @samp{Fontset-@var{n}}, where @var{n} is an integer starting from 0.
1029 The resource value should have this form:
1032 @var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
1036 @var{fontpattern} should have the form of a standard X font name, except
1037 for the last two fields. They should have the form
1038 @samp{fontset-@var{alias}}.
1040 The fontset has two names, one long and one short. The long name is
1041 @var{fontpattern}. The short name is @samp{fontset-@var{alias}}. You
1042 can refer to the fontset by either name.
1044 The construct @samp{@var{charset}:@var{font}} specifies which font to
1045 use (in this fontset) for one particular character set. Here,
1046 @var{charset} is the name of a character set, and @var{font} is the
1047 font to use for that character set. You can use this construct any
1048 number of times in defining one fontset.
1050 For the other character sets, Emacs chooses a font based on
1051 @var{fontpattern}. It replaces @samp{fontset-@var{alias}} with values
1052 that describe the character set. For the ASCII character font,
1053 @samp{fontset-@var{alias}} is replaced with @samp{ISO8859-1}.
1055 In addition, when several consecutive fields are wildcards, Emacs
1056 collapses them into a single wildcard. This is to prevent use of
1057 auto-scaled fonts. Fonts made by scaling larger fonts are not usable
1058 for editing, and scaling a smaller font is not useful because it is
1059 better to use the smaller font in its own size, which Emacs does.
1061 Thus if @var{fontpattern} is this,
1064 -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
1068 the font specification for ASCII characters would be this:
1071 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
1075 and the font specification for Chinese GB2312 characters would be this:
1078 -*-fixed-medium-r-normal-*-24-*-gb2312*-*
1081 You may not have any Chinese font matching the above font
1082 specification. Most X distributions include only Chinese fonts that
1083 have @samp{song ti} or @samp{fangsong ti} in @var{family} field. In
1084 such a case, @samp{Fontset-@var{n}} can be specified as below:
1087 Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
1088 chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
1092 Then, the font specifications for all but Chinese GB2312 characters have
1093 @samp{fixed} in the @var{family} field, and the font specification for
1094 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
1097 @findex create-fontset-from-fontset-spec
1098 The function that processes the fontset resource value to create the
1099 fontset is called @code{create-fontset-from-fontset-spec}. You can also
1100 call this function explicitly to create a fontset.
1102 @xref{Font X}, for more information about font naming in X.
1104 @node Undisplayable Characters
1105 @section Undisplayable Characters
1107 Your terminal may be unable to display some non-@sc{ascii}
1108 characters. Most non-windowing terminals can only use a single
1109 character set (use the variable @code{default-terminal-coding-system}
1110 (@pxref{Specify Coding}) to tell Emacs which one); characters which
1111 can't be encoded in that coding system are displayed as @samp{?} by
1114 Windowing terminals can display a broader range of characters, but
1115 you may not have fonts installed for all of them; characters that have
1116 no font appear as a hollow box.
1118 If you use Latin-1 characters but your terminal can't display
1119 Latin-1, you can arrange to display mnemonic @sc{ascii} sequences
1120 instead, e.g.@: @samp{"o} for o-umlaut. Load the library
1121 @file{iso-ascii} to do this.
1123 If your terminal can display Latin-1, you can display characters
1124 from other European character sets using a mixture of equivalent
1125 Latin-1 characters and @sc{ascii} mnemonics. Use the Custom option
1126 @code{latin1-display} to enable this. The mnemonic @sc{ascii}
1127 sequences mostly correspond to those of the prefix input methods.
1129 @node Single-Byte Character Support
1130 @section Single-byte Character Set Support
1132 @cindex European character sets
1133 @cindex accented characters
1134 @cindex ISO Latin character sets
1135 @cindex Unibyte operation
1136 The ISO 8859 Latin-@var{n} character sets define character codes in
1137 the range 160 to 255 to handle the accented letters and punctuation
1138 needed by various European languages (and some non-European ones).
1139 If you disable multibyte
1140 characters, Emacs can still handle @emph{one} of these character codes
1141 at a time. To specify @emph{which} of these codes to use, invoke
1142 @kbd{M-x set-language-environment} and specify a suitable language
1143 environment such as @samp{Latin-@var{n}}.
1145 For more information about unibyte operation, see @ref{Enabling
1146 Multibyte}. Note particularly that you probably want to ensure that
1147 your initialization files are read as unibyte if they contain non-ASCII
1150 @vindex unibyte-display-via-language-environment
1151 Emacs can also display those characters, provided the terminal or font
1152 in use supports them. This works automatically. Alternatively, if you
1153 are using a window system, Emacs can also display single-byte characters
1154 through fontsets, in effect by displaying the equivalent multibyte
1155 characters according to the current language environment. To request
1156 this, set the variable @code{unibyte-display-via-language-environment}
1157 to a non-@code{nil} value.
1159 @cindex @code{iso-ascii} library
1160 If your terminal does not support display of the Latin-1 character
1161 set, Emacs can display these characters as ASCII sequences which at
1162 least give you a clear idea of what the characters are. To do this,
1163 load the library @code{iso-ascii}. Similar libraries for other
1164 Latin-@var{n} character sets could be implemented, but we don't have
1167 @findex standard-display-8bit
1168 @cindex 8-bit display
1169 Normally non-ISO-8859 characters (between characters 128 and 159
1170 inclusive) are displayed as octal escapes. You can change this for
1171 non-standard ``extended'' versions of ISO-8859 character sets by using the
1172 function @code{standard-display-8bit} in the @code{disp-table} library.
1174 There are several ways you can input single-byte non-ASCII
1180 If your keyboard can generate character codes 128 and up, representing
1181 non-ASCII you can type those character codes directly.
1183 On a windowing terminal, you should not need to do anything special to
1184 use these keys; they should simply work. On a text-only terminal, you
1185 should use the command @code{M-x set-keyboard-coding-system} or the
1186 Custom option @code{keyboard-coding-system} to specify which coding
1187 system your keyboard uses (@pxref{Specify Coding}). Enabling this
1188 feature will probably require you to use @kbd{ESC} to type Meta
1189 characters; however, on a Linux console or in @code{xterm}, you can
1190 arrange for Meta to be converted to @kbd{ESC} and still be able type
1191 8-bit characters present directly on the keyboard or using
1192 @kbd{Compose} or @kbd{AltGr} keys. @xref{User Input}.
1195 You can use an input method for the selected language environment.
1196 @xref{Input Methods}. When you use an input method in a unibyte buffer,
1197 the non-ASCII character you specify with it is converted to unibyte.
1200 @cindex @code{iso-transl} library
1201 @cindex compose character
1202 @cindex dead character
1204 For Latin-1 only, you can use the
1205 key @kbd{C-x 8} as a ``compose character'' prefix for entry of
1206 non-ASCII Latin-1 printing characters. @kbd{C-x 8} is good for
1207 insertion (in the minibuffer as well as other buffers), for searching,
1208 and in any other context where a key sequence is allowed.
1210 @kbd{C-x 8} works by loading the @code{iso-transl} library. Once that
1211 library is loaded, the @key{ALT} modifier key, if you have one, serves
1212 the same purpose as @kbd{C-x 8}; use @key{ALT} together with an accent
1213 character to modify the following letter. In addition, if you have keys
1214 for the Latin-1 ``dead accent characters,'' they too are defined to
1215 compose with the following character, once @code{iso-transl} is loaded.
1216 Use @kbd{C-x 8 C-h} to list the available translations as mnemonic
1220 @cindex @code{iso-acc} library
1221 @cindex ISO Accents mode
1222 @findex iso-accents-mode
1223 @cindex Latin-1, Latin-2 and Latin-3 input mode
1224 For Latin-1, Latin-2 and Latin-3, @kbd{M-x iso-accents-mode} installs
1225 a minor mode which works much like the @code{latin-1-prefix} input
1226 method does not depend on having the input methods installed. This
1227 mode is buffer-local. It can be customized for various languages with
1228 @kbd{M-x iso-accents-customize}.