1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1997, 1999, 2000, 2001, 2002, 2003, 2004,
3 @c 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node International, Major Modes, Frames, Top
6 @chapter International Character Set Support
7 @c This node is referenced in the tutorial. When renaming or deleting
8 @c it, the tutorial needs to be adjusted. (TUTORIAL.de)
10 @cindex international scripts
11 @cindex multibyte characters
12 @cindex encoding of characters
40 Emacs supports a wide variety of international character sets,
41 including European and Vietnamese variants of the Latin alphabet, as
42 well as Cyrillic, Devanagari (for Hindi and Marathi), Ethiopic, Greek,
43 Han (for Chinese and Japanese), Hangul (for Korean), Hebrew, IPA,
44 Kannada, Lao, Malayalam, Tamil, Thai, Tibetan, and Vietnamese scripts.
45 Emacs also supports various encodings of these characters used by
46 other internationalized software, such as word processors and mailers.
48 Emacs allows editing text with international characters by supporting
49 all the related activities:
53 You can visit files with non-@acronym{ASCII} characters, save non-@acronym{ASCII} text, and
54 pass non-@acronym{ASCII} text between Emacs and programs it invokes (such as
55 compilers, spell-checkers, and mailers). Setting your language
56 environment (@pxref{Language Environments}) takes care of setting up the
57 coding systems and other options for a specific language or culture.
58 Alternatively, you can specify how Emacs should encode or decode text
59 for each command; see @ref{Text Coding}.
62 You can display non-@acronym{ASCII} characters encoded by the various
63 scripts. This works by using appropriate fonts on graphics displays
64 (@pxref{Defining Fontsets}), and by sending special codes to text-only
65 displays (@pxref{Terminal Coding}). If some characters are displayed
66 incorrectly, refer to @ref{Undisplayable Characters}, which describes
67 possible problems and explains how to solve them.
70 You can insert non-@acronym{ASCII} characters or search for them. To do that,
71 you can specify an input method (@pxref{Select Input Method}) suitable
72 for your language, or use the default input method set up when you set
73 your language environment. If
74 your keyboard can produce non-@acronym{ASCII} characters, you can select an
75 appropriate keyboard coding system (@pxref{Terminal Coding}), and Emacs
76 will accept those characters. Latin-1 characters can also be input by
77 using the @kbd{C-x 8} prefix, see @ref{Unibyte Mode}.
79 On X Window systems, your locale should be set to an appropriate value
80 to make sure Emacs interprets keyboard input correctly; see
81 @ref{Language Environments, locales}.
84 The rest of this chapter describes these issues in detail.
87 * International Chars:: Basic concepts of multibyte characters.
88 * Enabling Multibyte:: Controlling whether to use multibyte characters.
89 * Language Environments:: Setting things up for the language you use.
90 * Input Methods:: Entering text characters not on your keyboard.
91 * Select Input Method:: Specifying your choice of input methods.
92 * Coding Systems:: Character set conversion when you read and
93 write files, and so on.
94 * Recognize Coding:: How Emacs figures out which conversion to use.
95 * Specify Coding:: Specifying a file's coding system explicitly.
96 * Output Coding:: Choosing coding systems for output.
97 * Text Coding:: Choosing conversion to use for file text.
98 * Communication Coding:: Coding systems for interprocess communication.
99 * File Name Coding:: Coding systems for file @emph{names}.
100 * Terminal Coding:: Specifying coding systems for converting
101 terminal input and output.
102 * Fontsets:: Fontsets are collections of fonts
103 that cover the whole spectrum of characters.
104 * Defining Fontsets:: Defining a new fontset.
105 * Modifying Fontsets:: Modifying an existing fontset.
106 * Undisplayable Characters:: When characters don't display.
107 * Unibyte Mode:: You can pick one European character set
108 to use without multibyte characters.
109 * Charsets:: How Emacs groups its internal character codes.
112 @node International Chars
113 @section Introduction to International Character Sets
115 The users of international character sets and scripts have
116 established many more-or-less standard coding systems for storing
117 files. These coding systems are typically @dfn{multibyte}, meaning
118 that sequences of two or more bytes are used to represent individual
119 non-@acronym{ASCII} characters.
122 Internally, Emacs uses its own multibyte character encoding, which
123 is a superset of the @dfn{Unicode} standard. This internal encoding
124 allows characters from almost every known script to be intermixed in a
125 single buffer or string. Emacs translates between the multibyte
126 character encoding and various other coding systems when reading and
127 writing files, and when exchanging data with subprocesses.
130 @findex view-hello-file
131 @cindex undisplayable characters
132 @cindex @samp{?} in display
133 The command @kbd{C-h h} (@code{view-hello-file}) displays the file
134 @file{etc/HELLO}, which shows how to say ``hello'' in many languages.
135 This illustrates various scripts. If some characters can't be
136 displayed on your terminal, they appear as @samp{?} or as hollow boxes
137 (@pxref{Undisplayable Characters}).
139 Keyboards, even in the countries where these character sets are
140 used, generally don't have keys for all the characters in them. You
141 can insert characters that your keyboard does not support, using
142 @kbd{C-q} (@code{quoted-insert}) or @kbd{C-x 8 @key{RET}}
143 (@code{ucs-insert}). @xref{Inserting Text}. Emacs also supports
144 various @dfn{input methods}, typically one for each script or
145 language, which make it easier to type characters in the script.
146 @xref{Input Methods}.
149 The prefix key @kbd{C-x @key{RET}} is used for commands that pertain
150 to multibyte characters, coding systems, and input methods.
153 @findex what-cursor-position
154 The command @kbd{C-x =} (@code{what-cursor-position}) shows
155 information about the character at point. In addition to the
156 character position, which was described in @ref{Position Info}, this
157 command displays how the character is encoded. For instance, it
158 displays the following line in the echo area for the character
162 Char: c (99, #o143, #x63) point=28062 of 36168 (78%) column=53
165 The four values after @samp{Char:} describe the character that
166 follows point, first by showing it and then by giving its character
167 code in decimal, octal and hex. For a non-@acronym{ASCII} multibyte
168 character, these are followed by @samp{file} and the character's
169 representation, in hex, in the buffer's coding system, if that coding
170 system encodes the character safely and with a single byte
171 (@pxref{Coding Systems}). If the character's encoding is longer than
172 one byte, Emacs shows @samp{file ...}.
174 As a special case, if the character lies in the range 128 (0200
175 octal) through 159 (0237 octal), it stands for a ``raw'' byte that
176 does not correspond to any specific displayable character. Such a
177 ``character'' lies within the @code{eight-bit-control} character set,
178 and is displayed as an escaped octal character code. In this case,
179 @kbd{C-x =} shows @samp{part of display ...} instead of @samp{file}.
181 @cindex character set of character at point
182 @cindex font of character at point
183 @cindex text properties at point
184 @cindex face at point
185 With a prefix argument (@kbd{C-u C-x =}), this command displays a
186 detailed description of the character in a window:
190 The character set name, and the codes that identify the character
191 within that character set; @acronym{ASCII} characters are identified
192 as belonging to the @code{ascii} character set.
195 The character's syntax and categories.
198 The character's encodings, both internally in the buffer, and externally
199 if you were to save the file.
202 What keys to type to input the character in the current input method
203 (if it supports the character).
206 If you are running Emacs on a graphical display, the font name and
207 glyph code for the character. If you are running Emacs on a text-only
208 terminal, the code(s) sent to the terminal.
211 The character's text properties (@pxref{Text Properties,,,
212 elisp, the Emacs Lisp Reference Manual}), including any non-default
213 faces used to display the character, and any overlays containing it
214 (@pxref{Overlays,,, elisp, the same manual}).
217 Here's an example showing the Latin-1 character A with grave accent,
218 in a buffer whose coding system is @code{utf-8-unix}:
221 character: @`A (192, #o300, #xc0)
222 preferred charset: unicode (Unicode (ISO10646))
224 syntax: w which means: word
225 category: j:Japanese l:Latin v:Vietnamese
226 buffer code: #xC3 #x80
227 file code: not encodable by coding system undecided-unix
228 display: by this font (glyph code)
229 xft:-unknown-DejaVu Sans Mono-normal-normal-normal-*-13-*-*-*-m-0-iso10646-1 (#x82)
231 Character code properties: customize what to show
232 name: LATIN CAPITAL LETTER A WITH GRAVE
233 general-category: Lu (Letter, Uppercase)
234 decomposition: (65 768) ('A' '̀')
235 old-name: LATIN CAPITAL LETTER A GRAVE
237 There are text properties here:
241 @node Enabling Multibyte
242 @section Enabling Multibyte Characters
244 By default, Emacs starts in multibyte mode: it stores the contents
245 of buffers and strings using an internal encoding that represents
246 non-@acronym{ASCII} characters using multi-byte sequences. Multibyte
247 mode allows you to use all the supported languages and scripts without
250 @cindex turn multibyte support on or off
251 Under very special circumstances, you may want to disable multibyte
252 character support, for a specific buffer.
253 When multibyte characters are disabled in a buffer, we call
254 that @dfn{unibyte mode}. In unibyte mode, each character in the
255 buffer has a character code ranging from 0 through 255 (0377 octal); 0
256 through 127 (0177 octal) represent @acronym{ASCII} characters, and 128
257 (0200 octal) through 255 (0377 octal) represent non-@acronym{ASCII}
260 To edit a particular file in unibyte representation, visit it using
261 @code{find-file-literally}. @xref{Visiting}. You can convert a
262 multibyte buffer to unibyte by saving it to a file, killing the
263 buffer, and visiting the file again with @code{find-file-literally}.
264 Alternatively, you can use @kbd{C-x @key{RET} c}
265 (@code{universal-coding-system-argument}) and specify @samp{raw-text}
266 as the coding system with which to visit or save a file. @xref{Text
267 Coding}. Unlike @code{find-file-literally}, finding a file as
268 @samp{raw-text} doesn't disable format conversion, uncompression, or
271 @cindex Lisp files, and multibyte operation
272 @cindex multibyte operation, and Lisp files
273 @cindex unibyte operation, and Lisp files
274 @cindex init file, and non-@acronym{ASCII} characters
275 Emacs normally loads Lisp files as multibyte.
276 This includes the Emacs initialization
277 file, @file{.emacs}, and the initialization files of Emacs packages
278 such as Gnus. However, you can specify unibyte loading for a
279 particular Lisp file, by putting @w{@samp{-*-unibyte: t;-*-}} in a
280 comment on the first line (@pxref{File Variables}). Then that file is
281 always loaded as unibyte text. The motivation for these conventions
282 is that it is more reliable to always load any particular Lisp file in
283 the same way. However, you can load a Lisp file as unibyte, on any
284 one occasion, by typing @kbd{C-x @key{RET} c raw-text @key{RET}}
285 immediately before loading it.
287 The mode line indicates whether multibyte character support is
288 enabled in the current buffer. If it is, there are two or more
289 characters (most often two dashes) near the beginning of the mode
290 line, before the indication of the visited file's end-of-line
291 convention (colon, backslash, etc.). When multibyte characters
292 are not enabled, nothing precedes the colon except a single dash.
293 @xref{Mode Line}, for more details about this.
295 @findex toggle-enable-multibyte-characters
296 You can turn on multibyte support in a specific buffer by invoking the
297 command @code{toggle-enable-multibyte-characters} in that buffer.
299 @node Language Environments
300 @section Language Environments
301 @cindex language environments
303 All supported character sets are supported in Emacs buffers whenever
304 multibyte characters are enabled; there is no need to select a
305 particular language in order to display its characters in an Emacs
306 buffer. However, it is important to select a @dfn{language
307 environment} in order to set various defaults. Roughly speaking, the
308 language environment represents a choice of preferred script rather
309 than a choice of language.
311 The language environment controls which coding systems to recognize
312 when reading text (@pxref{Recognize Coding}). This applies to files,
313 incoming mail, and any other text you read into Emacs. It may also
314 specify the default coding system to use when you create a file. Each
315 language environment also specifies a default input method.
317 @findex set-language-environment
318 @vindex current-language-environment
319 To select a language environment, customize the variable
320 @code{current-language-environment} or use the command @kbd{M-x
321 set-language-environment}. It makes no difference which buffer is
322 current when you use this command, because the effects apply globally
323 to the Emacs session. The supported language environments include:
328 ASCII, Belarusian, Bengali, Brazilian Portuguese, Bulgarian,
329 Chinese-BIG5, Chinese-CNS, Chinese-EUC-TW, Chinese-GB, Chinese-GBK,
330 Chinese-GB18030, Croatian, Cyrillic-ALT, Cyrillic-ISO, Cyrillic-KOI8,
331 Czech, Devanagari, Dutch, English, Esperanto, Ethiopic, French,
332 Georgian, German, Greek, Gujarati, Hebrew, IPA, Italian, Japanese,
333 Kannada, Khmer, Korean, Lao, Latin-1, Latin-2, Latin-3, Latin-4,
334 Latin-5, Latin-6, Latin-7, Latin-8 (Celtic), Latin-9 (updated Latin-1
335 with the Euro sign), Latvian, Lithuanian, Malayalam, Oriya, Polish,
336 Punjabi, Romanian, Russian, Sinhala, Slovak, Slovenian, Spanish,
337 Swedish, TaiViet, Tajik, Tamil, Telugu, Thai, Tibetan, Turkish, UTF-8
338 (for a setup which prefers Unicode characters and files encoded in
339 UTF-8), Ukrainian, Vietnamese, Welsh, and Windows-1255 (for a setup
340 which prefers Cyrillic characters and files encoded in Windows-1255).
343 @cindex fonts for various scripts
344 @cindex Intlfonts package, installation
345 To display the script(s) used by your language environment on a
346 graphical display, you need to have a suitable font. If some of the
347 characters appear as empty boxes, you should install the GNU Intlfonts
348 package, which includes fonts for most supported scripts.@footnote{If
349 you run Emacs on X, you need to inform the X server about the location
350 of the newly installed fonts with the following commands:
353 xset fp+ /usr/local/share/emacs/fonts
357 @xref{Fontsets}, for more details about setting up your fonts.
359 @findex set-locale-environment
360 @vindex locale-language-names
361 @vindex locale-charset-language-names
363 Some operating systems let you specify the character-set locale you
364 are using by setting the locale environment variables @env{LC_ALL},
365 @env{LC_CTYPE}, or @env{LANG}.@footnote{If more than one of these is
366 set, the first one that is nonempty specifies your locale for this
367 purpose.} During startup, Emacs looks up your character-set locale's
368 name in the system locale alias table, matches its canonical name
369 against entries in the value of the variables
370 @code{locale-charset-language-names} and @code{locale-language-names},
371 and selects the corresponding language environment if a match is found.
372 (The former variable overrides the latter.) It also adjusts the display
373 table and terminal coding system, the locale coding system, the
374 preferred coding system as needed for the locale, and---last but not
375 least---the way Emacs decodes non-@acronym{ASCII} characters sent by your keyboard.
377 If you modify the @env{LC_ALL}, @env{LC_CTYPE}, or @env{LANG}
378 environment variables while running Emacs, you may want to invoke the
379 @code{set-locale-environment} function afterwards to readjust the
380 language environment from the new locale.
382 @vindex locale-preferred-coding-systems
383 The @code{set-locale-environment} function normally uses the preferred
384 coding system established by the language environment to decode system
385 messages. But if your locale matches an entry in the variable
386 @code{locale-preferred-coding-systems}, Emacs uses the corresponding
387 coding system instead. For example, if the locale @samp{ja_JP.PCK}
388 matches @code{japanese-shift-jis} in
389 @code{locale-preferred-coding-systems}, Emacs uses that encoding even
390 though it might normally use @code{japanese-iso-8bit}.
392 You can override the language environment chosen at startup with
393 explicit use of the command @code{set-language-environment}, or with
394 customization of @code{current-language-environment} in your init
398 @findex describe-language-environment
399 To display information about the effects of a certain language
400 environment @var{lang-env}, use the command @kbd{C-h L @var{lang-env}
401 @key{RET}} (@code{describe-language-environment}). This tells you
402 which languages this language environment is useful for, and lists the
403 character sets, coding systems, and input methods that go with it. It
404 also shows some sample text to illustrate scripts used in this
405 language environment. If you give an empty input for @var{lang-env},
406 this command describes the chosen language environment.
407 @anchor{Describe Language Environment}
409 @vindex set-language-environment-hook
410 You can customize any language environment with the normal hook
411 @code{set-language-environment-hook}. The command
412 @code{set-language-environment} runs that hook after setting up the new
413 language environment. The hook functions can test for a specific
414 language environment by checking the variable
415 @code{current-language-environment}. This hook is where you should
416 put non-default settings for specific language environment, such as
417 coding systems for keyboard input and terminal output, the default
420 @vindex exit-language-environment-hook
421 Before it starts to set up the new language environment,
422 @code{set-language-environment} first runs the hook
423 @code{exit-language-environment-hook}. This hook is useful for undoing
424 customizations that were made with @code{set-language-environment-hook}.
425 For instance, if you set up a special key binding in a specific language
426 environment using @code{set-language-environment-hook}, you should set
427 up @code{exit-language-environment-hook} to restore the normal binding
431 @section Input Methods
433 @cindex input methods
434 An @dfn{input method} is a kind of character conversion designed
435 specifically for interactive input. In Emacs, typically each language
436 has its own input method; sometimes several languages which use the same
437 characters can share one input method. A few languages support several
440 The simplest kind of input method works by mapping @acronym{ASCII} letters
441 into another alphabet; this allows you to use one other alphabet
442 instead of @acronym{ASCII}. The Greek and Russian input methods
445 A more powerful technique is composition: converting sequences of
446 characters into one letter. Many European input methods use composition
447 to produce a single non-@acronym{ASCII} letter from a sequence that consists of a
448 letter followed by accent characters (or vice versa). For example, some
449 methods convert the sequence @kbd{a'} into a single accented letter.
450 These input methods have no special commands of their own; all they do
451 is compose sequences of printing characters.
453 The input methods for syllabic scripts typically use mapping followed
454 by composition. The input methods for Thai and Korean work this way.
455 First, letters are mapped into symbols for particular sounds or tone
456 marks; then, sequences of these which make up a whole syllable are
457 mapped into one syllable sign.
459 Chinese and Japanese require more complex methods. In Chinese input
460 methods, first you enter the phonetic spelling of a Chinese word (in
461 input method @code{chinese-py}, among others), or a sequence of
462 portions of the character (input methods @code{chinese-4corner} and
463 @code{chinese-sw}, and others). One input sequence typically
464 corresponds to many possible Chinese characters. You select the one
465 you mean using keys such as @kbd{C-f}, @kbd{C-b}, @kbd{C-n},
466 @kbd{C-p}, and digits, which have special meanings in this situation.
468 The possible characters are conceptually arranged in several rows,
469 with each row holding up to 10 alternatives. Normally, Emacs displays
470 just one row at a time, in the echo area; @code{(@var{i}/@var{j})}
471 appears at the beginning, to indicate that this is the @var{i}th row
472 out of a total of @var{j} rows. Type @kbd{C-n} or @kbd{C-p} to
473 display the next row or the previous row.
475 Type @kbd{C-f} and @kbd{C-b} to move forward and backward among
476 the alternatives in the current row. As you do this, Emacs highlights
477 the current alternative with a special color; type @code{C-@key{SPC}}
478 to select the current alternative and use it as input. The
479 alternatives in the row are also numbered; the number appears before
480 the alternative. Typing a digit @var{n} selects the @var{n}th
481 alternative of the current row and uses it as input.
483 @key{TAB} in these Chinese input methods displays a buffer showing
484 all the possible characters at once; then clicking @kbd{Mouse-2} on
485 one of them selects that alternative. The keys @kbd{C-f}, @kbd{C-b},
486 @kbd{C-n}, @kbd{C-p}, and digits continue to work as usual, but they
487 do the highlighting in the buffer showing the possible characters,
488 rather than in the echo area.
490 In Japanese input methods, first you input a whole word using
491 phonetic spelling; then, after the word is in the buffer, Emacs
492 converts it into one or more characters using a large dictionary. One
493 phonetic spelling corresponds to a number of different Japanese words;
494 to select one of them, use @kbd{C-n} and @kbd{C-p} to cycle through
497 Sometimes it is useful to cut off input method processing so that the
498 characters you have just entered will not combine with subsequent
499 characters. For example, in input method @code{latin-1-postfix}, the
500 sequence @kbd{e '} combines to form an @samp{e} with an accent. What if
501 you want to enter them as separate characters?
503 One way is to type the accent twice; this is a special feature for
504 entering the separate letter and accent. For example, @kbd{e ' '} gives
505 you the two characters @samp{e'}. Another way is to type another letter
506 after the @kbd{e}---something that won't combine with that---and
507 immediately delete it. For example, you could type @kbd{e e @key{DEL}
508 '} to get separate @samp{e} and @samp{'}.
510 Another method, more general but not quite as easy to type, is to use
511 @kbd{C-\ C-\} between two characters to stop them from combining. This
512 is the command @kbd{C-\} (@code{toggle-input-method}) used twice.
514 @xref{Select Input Method}.
517 @cindex incremental search, input method interference
518 @kbd{C-\ C-\} is especially useful inside an incremental search,
519 because it stops waiting for more characters to combine, and starts
520 searching for what you have already entered.
522 To find out how to input the character after point using the current
523 input method, type @kbd{C-u C-x =}. @xref{Position Info}.
525 @vindex input-method-verbose-flag
526 @vindex input-method-highlight-flag
527 The variables @code{input-method-highlight-flag} and
528 @code{input-method-verbose-flag} control how input methods explain
529 what is happening. If @code{input-method-highlight-flag} is
530 non-@code{nil}, the partial sequence is highlighted in the buffer (for
531 most input methods---some disable this feature). If
532 @code{input-method-verbose-flag} is non-@code{nil}, the list of
533 possible characters to type next is displayed in the echo area (but
534 not when you are in the minibuffer).
536 @node Select Input Method
537 @section Selecting an Input Method
541 Enable or disable use of the selected input method.
543 @item C-x @key{RET} C-\ @var{method} @key{RET}
544 Select a new input method for the current buffer.
546 @item C-h I @var{method} @key{RET}
547 @itemx C-h C-\ @var{method} @key{RET}
548 @findex describe-input-method
551 Describe the input method @var{method} (@code{describe-input-method}).
552 By default, it describes the current input method (if any). This
553 description should give you the full details of how to use any
554 particular input method.
556 @item M-x list-input-methods
557 Display a list of all the supported input methods.
560 @findex set-input-method
561 @vindex current-input-method
563 To choose an input method for the current buffer, use @kbd{C-x
564 @key{RET} C-\} (@code{set-input-method}). This command reads the
565 input method name from the minibuffer; the name normally starts with the
566 language environment that it is meant to be used with. The variable
567 @code{current-input-method} records which input method is selected.
569 @findex toggle-input-method
571 Input methods use various sequences of @acronym{ASCII} characters to
572 stand for non-@acronym{ASCII} characters. Sometimes it is useful to
573 turn off the input method temporarily. To do this, type @kbd{C-\}
574 (@code{toggle-input-method}). To reenable the input method, type
577 If you type @kbd{C-\} and you have not yet selected an input method,
578 it prompts for you to specify one. This has the same effect as using
579 @kbd{C-x @key{RET} C-\} to specify an input method.
581 When invoked with a numeric argument, as in @kbd{C-u C-\},
582 @code{toggle-input-method} always prompts you for an input method,
583 suggesting the most recently selected one as the default.
585 @vindex default-input-method
586 Selecting a language environment specifies a default input method for
587 use in various buffers. When you have a default input method, you can
588 select it in the current buffer by typing @kbd{C-\}. The variable
589 @code{default-input-method} specifies the default input method
590 (@code{nil} means there is none).
592 In some language environments, which support several different input
593 methods, you might want to use an input method different from the
594 default chosen by @code{set-language-environment}. You can instruct
595 Emacs to select a different default input method for a certain
596 language environment, if you wish, by using
597 @code{set-language-environment-hook} (@pxref{Language Environments,
598 set-language-environment-hook}). For example:
601 (defun my-chinese-setup ()
602 "Set up my private Chinese environment."
603 (if (equal current-language-environment "Chinese-GB")
604 (setq default-input-method "chinese-tonepy")))
605 (add-hook 'set-language-environment-hook 'my-chinese-setup)
609 This sets the default input method to be @code{chinese-tonepy}
610 whenever you choose a Chinese-GB language environment.
612 You can instruct Emacs to activate a certain input method
613 automatically. For example:
616 (add-hook 'text-mode-hook
617 (lambda () (set-input-method "german-prefix")))
621 This activates the input method ``german-prefix'' automatically in the
624 @findex quail-set-keyboard-layout
625 Some input methods for alphabetic scripts work by (in effect)
626 remapping the keyboard to emulate various keyboard layouts commonly used
627 for those scripts. How to do this remapping properly depends on your
628 actual keyboard layout. To specify which layout your keyboard has, use
629 the command @kbd{M-x quail-set-keyboard-layout}.
631 @findex quail-show-key
632 You can use the command @kbd{M-x quail-show-key} to show what key (or
633 key sequence) to type in order to input the character following point,
634 using the selected keyboard layout. The command @kbd{C-u C-x =} also
635 shows that information in addition to the other information about the
638 @findex list-input-methods
639 To see a list of all the supported input methods, type @kbd{M-x
640 list-input-methods}. The list gives information about each input
641 method, including the string that stands for it in the mode line.
644 @section Coding Systems
645 @cindex coding systems
647 Users of various languages have established many more-or-less standard
648 coding systems for representing them. Emacs does not use these coding
649 systems internally; instead, it converts from various coding systems to
650 its own system when reading data, and converts the internal coding
651 system to other coding systems when writing data. Conversion is
652 possible in reading or writing files, in sending or receiving from the
653 terminal, and in exchanging data with subprocesses.
655 Emacs assigns a name to each coding system. Most coding systems are
656 used for one language, and the name of the coding system starts with
657 the language name. Some coding systems are used for several
658 languages; their names usually start with @samp{iso}. There are also
659 special coding systems, such as @code{no-conversion}, @code{raw-text},
660 and @code{emacs-internal}.
662 @cindex international files from DOS/Windows systems
663 A special class of coding systems, collectively known as
664 @dfn{codepages}, is designed to support text encoded by MS-Windows and
665 MS-DOS software. The names of these coding systems are
666 @code{cp@var{nnnn}}, where @var{nnnn} is a 3- or 4-digit number of the
667 codepage. You can use these encodings just like any other coding
668 system; for example, to visit a file encoded in codepage 850, type
669 @kbd{C-x @key{RET} c cp850 @key{RET} C-x C-f @var{filename}
672 In addition to converting various representations of non-@acronym{ASCII}
673 characters, a coding system can perform end-of-line conversion. Emacs
674 handles three different conventions for how to separate lines in a file:
675 newline, carriage-return linefeed, and just carriage-return.
678 @item C-h C @var{coding} @key{RET}
679 Describe coding system @var{coding}.
681 @item C-h C @key{RET}
682 Describe the coding systems currently in use.
684 @item M-x list-coding-systems
685 Display a list of all the supported coding systems.
689 @findex describe-coding-system
690 The command @kbd{C-h C} (@code{describe-coding-system}) displays
691 information about particular coding systems, including the end-of-line
692 conversion specified by those coding systems. You can specify a coding
693 system name as the argument; alternatively, with an empty argument, it
694 describes the coding systems currently selected for various purposes,
695 both in the current buffer and as the defaults, and the priority list
696 for recognizing coding systems (@pxref{Recognize Coding}).
698 @findex list-coding-systems
699 To display a list of all the supported coding systems, type @kbd{M-x
700 list-coding-systems}. The list gives information about each coding
701 system, including the letter that stands for it in the mode line
704 @cindex end-of-line conversion
706 @cindex MS-DOS end-of-line conversion
707 @cindex Macintosh end-of-line conversion
708 Each of the coding systems that appear in this list---except for
709 @code{no-conversion}, which means no conversion of any kind---specifies
710 how and whether to convert printing characters, but leaves the choice of
711 end-of-line conversion to be decided based on the contents of each file.
712 For example, if the file appears to use the sequence carriage-return
713 linefeed to separate lines, DOS end-of-line conversion will be used.
715 Each of the listed coding systems has three variants which specify
716 exactly what to do for end-of-line conversion:
720 Don't do any end-of-line conversion; assume the file uses
721 newline to separate lines. (This is the convention normally used
722 on Unix and GNU systems.)
725 Assume the file uses carriage-return linefeed to separate lines, and do
726 the appropriate conversion. (This is the convention normally used on
727 Microsoft systems.@footnote{It is also specified for MIME @samp{text/*}
728 bodies and in other network transport contexts. It is different
729 from the SGML reference syntax record-start/record-end format which
730 Emacs doesn't support directly.})
733 Assume the file uses carriage-return to separate lines, and do the
734 appropriate conversion. (This is the convention normally used on the
738 These variant coding systems are omitted from the
739 @code{list-coding-systems} display for brevity, since they are entirely
740 predictable. For example, the coding system @code{iso-latin-1} has
741 variants @code{iso-latin-1-unix}, @code{iso-latin-1-dos} and
742 @code{iso-latin-1-mac}.
744 @cindex @code{undecided}, coding system
745 The coding systems @code{unix}, @code{dos}, and @code{mac} are
746 aliases for @code{undecided-unix}, @code{undecided-dos}, and
747 @code{undecided-mac}, respectively. These coding systems specify only
748 the end-of-line conversion, and leave the character code conversion to
749 be deduced from the text itself.
751 The coding system @code{raw-text} is good for a file which is mainly
752 @acronym{ASCII} text, but may contain byte values above 127 which are
753 not meant to encode non-@acronym{ASCII} characters. With
754 @code{raw-text}, Emacs copies those byte values unchanged, and sets
755 @code{enable-multibyte-characters} to @code{nil} in the current buffer
756 so that they will be interpreted properly. @code{raw-text} handles
757 end-of-line conversion in the usual way, based on the data
758 encountered, and has the usual three variants to specify the kind of
759 end-of-line conversion to use.
761 In contrast, the coding system @code{no-conversion} specifies no
762 character code conversion at all---none for non-@acronym{ASCII} byte values and
763 none for end of line. This is useful for reading or writing binary
764 files, tar files, and other files that must be examined verbatim. It,
765 too, sets @code{enable-multibyte-characters} to @code{nil}.
767 The easiest way to edit a file with no conversion of any kind is with
768 the @kbd{M-x find-file-literally} command. This uses
769 @code{no-conversion}, and also suppresses other Emacs features that
770 might convert the file contents before you see them. @xref{Visiting}.
772 The coding system @code{emacs-internal} (or @code{utf-8-emacs},
773 which is equivalent) means that the file contains non-@acronym{ASCII}
774 characters stored with the internal Emacs encoding. This coding
775 system handles end-of-line conversion based on the data encountered,
776 and has the usual three variants to specify the kind of end-of-line
779 @node Recognize Coding
780 @section Recognizing Coding Systems
782 Whenever Emacs reads a given piece of text, it tries to recognize
783 which coding system to use. This applies to files being read, output
784 from subprocesses, text from X selections, etc. Emacs can select the
785 right coding system automatically most of the time---once you have
786 specified your preferences.
788 Some coding systems can be recognized or distinguished by which byte
789 sequences appear in the data. However, there are coding systems that
790 cannot be distinguished, not even potentially. For example, there is no
791 way to distinguish between Latin-1 and Latin-2; they use the same byte
792 values with different meanings.
794 Emacs handles this situation by means of a priority list of coding
795 systems. Whenever Emacs reads a file, if you do not specify the coding
796 system to use, Emacs checks the data against each coding system,
797 starting with the first in priority and working down the list, until it
798 finds a coding system that fits the data. Then it converts the file
799 contents assuming that they are represented in this coding system.
801 The priority list of coding systems depends on the selected language
802 environment (@pxref{Language Environments}). For example, if you use
803 French, you probably want Emacs to prefer Latin-1 to Latin-2; if you use
804 Czech, you probably want Latin-2 to be preferred. This is one of the
805 reasons to specify a language environment.
807 @findex prefer-coding-system
808 However, you can alter the coding system priority list in detail
809 with the command @kbd{M-x prefer-coding-system}. This command reads
810 the name of a coding system from the minibuffer, and adds it to the
811 front of the priority list, so that it is preferred to all others. If
812 you use this command several times, each use adds one element to the
813 front of the priority list.
815 If you use a coding system that specifies the end-of-line conversion
816 type, such as @code{iso-8859-1-dos}, what this means is that Emacs
817 should attempt to recognize @code{iso-8859-1} with priority, and should
818 use DOS end-of-line conversion when it does recognize @code{iso-8859-1}.
820 @vindex file-coding-system-alist
821 Sometimes a file name indicates which coding system to use for the
822 file. The variable @code{file-coding-system-alist} specifies this
823 correspondence. There is a special function
824 @code{modify-coding-system-alist} for adding elements to this list. For
825 example, to read and write all @samp{.txt} files using the coding system
826 @code{chinese-iso-8bit}, you can execute this Lisp expression:
829 (modify-coding-system-alist 'file "\\.txt\\'" 'chinese-iso-8bit)
833 The first argument should be @code{file}, the second argument should be
834 a regular expression that determines which files this applies to, and
835 the third argument says which coding system to use for these files.
837 @vindex inhibit-eol-conversion
838 @cindex DOS-style end-of-line display
839 Emacs recognizes which kind of end-of-line conversion to use based on
840 the contents of the file: if it sees only carriage-returns, or only
841 carriage-return linefeed sequences, then it chooses the end-of-line
842 conversion accordingly. You can inhibit the automatic use of
843 end-of-line conversion by setting the variable @code{inhibit-eol-conversion}
844 to non-@code{nil}. If you do that, DOS-style files will be displayed
845 with the @samp{^M} characters visible in the buffer; some people
846 prefer this to the more subtle @samp{(DOS)} end-of-line type
847 indication near the left edge of the mode line (@pxref{Mode Line,
850 @vindex inhibit-iso-escape-detection
851 @cindex escape sequences in files
852 By default, the automatic detection of coding system is sensitive to
853 escape sequences. If Emacs sees a sequence of characters that begin
854 with an escape character, and the sequence is valid as an ISO-2022
855 code, that tells Emacs to use one of the ISO-2022 encodings to decode
858 However, there may be cases that you want to read escape sequences
859 in a file as is. In such a case, you can set the variable
860 @code{inhibit-iso-escape-detection} to non-@code{nil}. Then the code
861 detection ignores any escape sequences, and never uses an ISO-2022
862 encoding. The result is that all escape sequences become visible in
865 The default value of @code{inhibit-iso-escape-detection} is
866 @code{nil}. We recommend that you not change it permanently, only for
867 one specific operation. That's because many Emacs Lisp source files
868 in the Emacs distribution contain non-@acronym{ASCII} characters encoded in the
869 coding system @code{iso-2022-7bit}, and they won't be
870 decoded correctly when you visit those files if you suppress the
871 escape sequence detection.
873 @vindex auto-coding-alist
874 @vindex auto-coding-regexp-alist
875 @vindex auto-coding-functions
876 The variables @code{auto-coding-alist},
877 @code{auto-coding-regexp-alist} and @code{auto-coding-functions} are
878 the strongest way to specify the coding system for certain patterns of
879 file names, or for files containing certain patterns; these variables
880 even override @samp{-*-coding:-*-} tags in the file itself. Emacs
881 uses @code{auto-coding-alist} for tar and archive files, to prevent it
882 from being confused by a @samp{-*-coding:-*-} tag in a member of the
883 archive and thinking it applies to the archive file as a whole.
884 Likewise, Emacs uses @code{auto-coding-regexp-alist} to ensure that
885 RMAIL files, whose names in general don't match any particular
886 pattern, are decoded correctly. One of the builtin
887 @code{auto-coding-functions} detects the encoding for XML files.
889 @vindex rmail-decode-mime-charset
890 @vindex rmail-file-coding-system
891 When you get new mail in Rmail, each message is translated
892 automatically from the coding system it is written in, as if it were a
893 separate file. This uses the priority list of coding systems that you
894 have specified. If a MIME message specifies a character set, Rmail
895 obeys that specification, unless @code{rmail-decode-mime-charset} is
896 @code{nil}. For reading and saving Rmail files themselves, Emacs uses
897 the coding system specified by the variable
898 @code{rmail-file-coding-system}. The default value is @code{nil},
899 which means that Rmail files are not translated (they are read and
900 written in the Emacs internal character code).
903 @section Specifying a File's Coding System
905 If Emacs recognizes the encoding of a file incorrectly, you can
906 reread the file using the correct coding system by typing @kbd{C-x
907 @key{RET} r @var{coding-system} @key{RET}}. To see what coding system
908 Emacs actually used to decode the file, look at the coding system
909 mnemonic letter near the left edge of the mode line (@pxref{Mode
910 Line}), or type @kbd{C-h C @key{RET}}.
913 You can specify the coding system for a particular file in the file
914 itself, using the @w{@samp{-*-@dots{}-*-}} construct at the beginning,
915 or a local variables list at the end (@pxref{File Variables}). You do
916 this by defining a value for the ``variable'' named @code{coding}.
917 Emacs does not really have a variable @code{coding}; instead of
918 setting a variable, this uses the specified coding system for the
919 file. For example, @samp{-*-mode: C; coding: latin-1;-*-} specifies
920 use of the Latin-1 coding system, as well as C mode. When you specify
921 the coding explicitly in the file, that overrides
922 @code{file-coding-system-alist}.
925 @section Choosing Coding Systems for Output
927 @vindex buffer-file-coding-system
928 Once Emacs has chosen a coding system for a buffer, it stores that
929 coding system in @code{buffer-file-coding-system}. That makes it the
930 default for operations that write from this buffer into a file, such
931 as @code{save-buffer} and @code{write-region}. You can specify a
932 different coding system for further file output from the buffer using
933 @code{set-buffer-file-coding-system} (@pxref{Text Coding}).
935 You can insert any character Emacs supports into any Emacs buffer,
936 but most coding systems can only handle a subset of these characters.
937 Therefore, it's possible that the characters you insert cannot be
938 encoded with the coding system that will be used to save the buffer.
939 For example, you could visit a text file in Polish, encoded in
940 @code{iso-8859-2}, and add some Russian words to it. When you save
941 that buffer, Emacs cannot use the current value of
942 @code{buffer-file-coding-system}, because the characters you added
943 cannot be encoded by that coding system.
945 When that happens, Emacs tries the most-preferred coding system (set
946 by @kbd{M-x prefer-coding-system} or @kbd{M-x
947 set-language-environment}). If that coding system can safely encode
948 all of the characters in the buffer, Emacs uses it, and stores its
949 value in @code{buffer-file-coding-system}. Otherwise, Emacs displays
950 a list of coding systems suitable for encoding the buffer's contents,
951 and asks you to choose one of those coding systems.
953 If you insert the unsuitable characters in a mail message, Emacs
954 behaves a bit differently. It additionally checks whether the
955 most-preferred coding system is recommended for use in MIME messages;
956 if not, Emacs tells you that the most-preferred coding system is not
957 recommended and prompts you for another coding system. This is so you
958 won't inadvertently send a message encoded in a way that your
959 recipient's mail software will have difficulty decoding. (You can
960 still use an unsuitable coding system if you type its name in response
963 @vindex sendmail-coding-system
964 When you send a message with Mail mode (@pxref{Sending Mail}), Emacs has
965 four different ways to determine the coding system to use for encoding
966 the message text. It tries the buffer's own value of
967 @code{buffer-file-coding-system}, if that is non-@code{nil}. Otherwise,
968 it uses the value of @code{sendmail-coding-system}, if that is
969 non-@code{nil}. The third way is to use the default coding system for
970 new files, which is controlled by your choice of language environment,
971 if that is non-@code{nil}. If all of these three values are @code{nil},
972 Emacs encodes outgoing mail using the Latin-1 coding system.
975 @section Specifying a Coding System for File Text
977 In cases where Emacs does not automatically choose the right coding
978 system for a file's contents, you can use these commands to specify
982 @item C-x @key{RET} f @var{coding} @key{RET}
983 Use coding system @var{coding} for saving or revisiting the visited
984 file in the current buffer.
986 @item C-x @key{RET} c @var{coding} @key{RET}
987 Specify coding system @var{coding} for the immediately following
990 @item C-x @key{RET} r @var{coding} @key{RET}
991 Revisit the current file using the coding system @var{coding}.
993 @item M-x recode-region @key{RET} @var{right} @key{RET} @var{wrong} @key{RET}
994 Convert a region that was decoded using coding system @var{wrong},
995 decoding it using coding system @var{right} instead.
999 @findex set-buffer-file-coding-system
1000 The command @kbd{C-x @key{RET} f}
1001 (@code{set-buffer-file-coding-system}) sets the file coding system for
1002 the current buffer---in other words, it says which coding system to
1003 use when saving or reverting the visited file. You specify which
1004 coding system using the minibuffer. If you specify a coding system
1005 that cannot handle all of the characters in the buffer, Emacs warns
1006 you about the troublesome characters when you actually save the
1009 @cindex specify end-of-line conversion
1010 You can also use this command to specify the end-of-line conversion
1011 (@pxref{Coding Systems, end-of-line conversion}) for encoding the
1012 current buffer. For example, @kbd{C-x @key{RET} f dos @key{RET}} will
1013 cause Emacs to save the current buffer's text with DOS-style CRLF line
1017 @findex universal-coding-system-argument
1018 Another way to specify the coding system for a file is when you visit
1019 the file. First use the command @kbd{C-x @key{RET} c}
1020 (@code{universal-coding-system-argument}); this command uses the
1021 minibuffer to read a coding system name. After you exit the minibuffer,
1022 the specified coding system is used for @emph{the immediately following
1025 So if the immediately following command is @kbd{C-x C-f}, for example,
1026 it reads the file using that coding system (and records the coding
1027 system for when you later save the file). Or if the immediately following
1028 command is @kbd{C-x C-w}, it writes the file using that coding system.
1029 When you specify the coding system for saving in this way, instead
1030 of with @kbd{C-x @key{RET} f}, there is no warning if the buffer
1031 contains characters that the coding system cannot handle.
1033 Other file commands affected by a specified coding system include
1034 @kbd{C-x i} and @kbd{C-x C-v}, as well as the other-window variants
1035 of @kbd{C-x C-f}. @kbd{C-x @key{RET} c} also affects commands that
1036 start subprocesses, including @kbd{M-x shell} (@pxref{Shell}). If the
1037 immediately following command does not use the coding system, then
1038 @kbd{C-x @key{RET} c} ultimately has no effect.
1040 An easy way to visit a file with no conversion is with the @kbd{M-x
1041 find-file-literally} command. @xref{Visiting}.
1043 The default value of the variable @code{buffer-file-coding-system}
1044 specifies the choice of coding system to use when you create a new file.
1045 It applies when you find a new file, and when you create a buffer and
1046 then save it in a file. Selecting a language environment typically sets
1047 this variable to a good choice of default coding system for that language
1051 @findex revert-buffer-with-coding-system
1052 If you visit a file with a wrong coding system, you can correct this
1053 with @kbd{C-x @key{RET} r} (@code{revert-buffer-with-coding-system}).
1054 This visits the current file again, using a coding system you specify.
1056 @findex recode-region
1057 If a piece of text has already been inserted into a buffer using the
1058 wrong coding system, you can redo the decoding of it using @kbd{M-x
1059 recode-region}. This prompts you for the proper coding system, then
1060 for the wrong coding system that was actually used, and does the
1061 conversion. It first encodes the region using the wrong coding system,
1062 then decodes it again using the proper coding system.
1064 @node Communication Coding
1065 @section Coding Systems for Interprocess Communication
1067 This section explains how to specify coding systems for use
1068 in communication with other processes.
1071 @item C-x @key{RET} x @var{coding} @key{RET}
1072 Use coding system @var{coding} for transferring selections to and from
1073 other window-based applications.
1075 @item C-x @key{RET} X @var{coding} @key{RET}
1076 Use coding system @var{coding} for transferring @emph{one}
1077 selection---the next one---to or from another window-based application.
1079 @item C-x @key{RET} p @var{input-coding} @key{RET} @var{output-coding} @key{RET}
1080 Use coding systems @var{input-coding} and @var{output-coding} for
1081 subprocess input and output in the current buffer.
1083 @item C-x @key{RET} c @var{coding} @key{RET}
1084 Specify coding system @var{coding} for the immediately following
1090 @findex set-selection-coding-system
1091 @findex set-next-selection-coding-system
1092 The command @kbd{C-x @key{RET} x} (@code{set-selection-coding-system})
1093 specifies the coding system for sending selected text to other windowing
1094 applications, and for receiving the text of selections made in other
1095 applications. This command applies to all subsequent selections, until
1096 you override it by using the command again. The command @kbd{C-x
1097 @key{RET} X} (@code{set-next-selection-coding-system}) specifies the
1098 coding system for the next selection made in Emacs or read by Emacs.
1100 @vindex x-select-request-type
1101 The variable @code{x-select-request-type} specifies the data type to
1102 request from the X Window System for receiving text selections from
1103 other applications. If the value is @code{nil} (the default), Emacs
1104 tries @code{COMPOUND_TEXT} and @code{UTF8_STRING}, in this order, and
1105 uses various heuristics to choose the more appropriate of the two
1106 results; if none of these succeed, Emacs falls back on @code{STRING}.
1107 If the value of @code{x-select-request-type} is one of the symbols
1108 @code{COMPOUND_TEXT}, @code{UTF8_STRING}, @code{STRING}, or
1109 @code{TEXT}, Emacs uses only that request type. If the value is a
1110 list of some of these symbols, Emacs tries only the request types in
1111 the list, in order, until one of them succeeds, or until the list is
1115 @findex set-buffer-process-coding-system
1116 The command @kbd{C-x @key{RET} p} (@code{set-buffer-process-coding-system})
1117 specifies the coding system for input and output to a subprocess. This
1118 command applies to the current buffer; normally, each subprocess has its
1119 own buffer, and thus you can use this command to specify translation to
1120 and from a particular subprocess by giving the command in the
1121 corresponding buffer.
1123 You can also use @kbd{C-x @key{RET} c} just before the command that
1124 runs or starts a subprocess, to specify the coding system to use for
1125 communication with that subprocess.
1127 The default for translation of process input and output depends on the
1128 current language environment.
1130 @vindex locale-coding-system
1131 @cindex decoding non-@acronym{ASCII} keyboard input on X
1132 The variable @code{locale-coding-system} specifies a coding system
1133 to use when encoding and decoding system strings such as system error
1134 messages and @code{format-time-string} formats and time stamps. That
1135 coding system is also used for decoding non-@acronym{ASCII} keyboard input on X
1136 Window systems. You should choose a coding system that is compatible
1137 with the underlying system's text representation, which is normally
1138 specified by one of the environment variables @env{LC_ALL},
1139 @env{LC_CTYPE}, and @env{LANG}. (The first one, in the order
1140 specified above, whose value is nonempty is the one that determines
1141 the text representation.)
1143 @vindex x-select-request-type
1144 The variable @code{x-select-request-type} specifies a selection data
1145 type of selection to request from the X server. The default value is
1146 @code{nil}, which means Emacs tries @code{COMPOUND_TEXT} and
1147 @code{UTF8_STRING}, and uses whichever result seems more appropriate.
1148 You can explicitly specify the data type by setting the variable to
1149 one of the symbols @code{COMPOUND_TEXT}, @code{UTF8_STRING},
1150 @code{STRING} and @code{TEXT}.
1152 @node File Name Coding
1153 @section Coding Systems for File Names
1156 @item C-x @key{RET} F @var{coding} @key{RET}
1157 Use coding system @var{coding} for encoding and decoding file
1161 @vindex file-name-coding-system
1162 @cindex file names with non-@acronym{ASCII} characters
1163 The variable @code{file-name-coding-system} specifies a coding
1164 system to use for encoding file names. It has no effect on reading
1165 and writing the @emph{contents} of files.
1167 @findex set-file-name-coding-system
1168 @kindex C-x @key{RET} F
1169 If you set the variable to a coding system name (as a Lisp symbol or
1170 a string), Emacs encodes file names using that coding system for all
1171 file operations. This makes it possible to use non-@acronym{ASCII}
1172 characters in file names---or, at least, those non-@acronym{ASCII}
1173 characters which the specified coding system can encode. Use @kbd{C-x
1174 @key{RET} F} (@code{set-file-name-coding-system}) to specify this
1177 If @code{file-name-coding-system} is @code{nil}, Emacs uses a
1178 default coding system determined by the selected language environment.
1179 In the default language environment, non-@acronym{ASCII} characters in
1180 file names are not encoded specially; they appear in the file system
1181 using the internal Emacs representation.
1183 @strong{Warning:} if you change @code{file-name-coding-system} (or the
1184 language environment) in the middle of an Emacs session, problems can
1185 result if you have already visited files whose names were encoded using
1186 the earlier coding system and cannot be encoded (or are encoded
1187 differently) under the new coding system. If you try to save one of
1188 these buffers under the visited file name, saving may use the wrong file
1189 name, or it may get an error. If such a problem happens, use @kbd{C-x
1190 C-w} to specify a new file name for that buffer.
1192 @findex recode-file-name
1193 If a mistake occurs when encoding a file name, use the command
1194 @kbd{M-x recode-file-name} to change the file name's coding
1195 system. This prompts for an existing file name, its old coding
1196 system, and the coding system to which you wish to convert.
1198 @node Terminal Coding
1199 @section Coding Systems for Terminal I/O
1202 @item C-x @key{RET} k @var{coding} @key{RET}
1203 Use coding system @var{coding} for keyboard input.
1205 @item C-x @key{RET} t @var{coding} @key{RET}
1206 Use coding system @var{coding} for terminal output.
1210 @findex set-terminal-coding-system
1211 The command @kbd{C-x @key{RET} t} (@code{set-terminal-coding-system})
1212 specifies the coding system for terminal output. If you specify a
1213 character code for terminal output, all characters output to the
1214 terminal are translated into that coding system.
1216 This feature is useful for certain character-only terminals built to
1217 support specific languages or character sets---for example, European
1218 terminals that support one of the ISO Latin character sets. You need to
1219 specify the terminal coding system when using multibyte text, so that
1220 Emacs knows which characters the terminal can actually handle.
1222 By default, output to the terminal is not translated at all, unless
1223 Emacs can deduce the proper coding system from your terminal type or
1224 your locale specification (@pxref{Language Environments}).
1227 @findex set-keyboard-coding-system
1228 @vindex keyboard-coding-system
1229 The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system})
1230 or the variable @code{keyboard-coding-system} specifies the coding
1231 system for keyboard input. Character-code translation of keyboard
1232 input is useful for terminals with keys that send non-@acronym{ASCII}
1233 graphic characters---for example, some terminals designed for ISO
1234 Latin-1 or subsets of it.
1236 By default, keyboard input is translated based on your system locale
1237 setting. If your terminal does not really support the encoding
1238 implied by your locale (for example, if you find it inserts a
1239 non-@acronym{ASCII} character if you type @kbd{M-i}), you will need to set
1240 @code{keyboard-coding-system} to @code{nil} to turn off encoding.
1241 You can do this by putting
1244 (set-keyboard-coding-system nil)
1250 There is a similarity between using a coding system translation for
1251 keyboard input, and using an input method: both define sequences of
1252 keyboard input that translate into single characters. However, input
1253 methods are designed to be convenient for interactive use by humans, and
1254 the sequences that are translated are typically sequences of @acronym{ASCII}
1255 printing characters. Coding systems typically translate sequences of
1256 non-graphic characters.
1262 A font typically defines shapes for a single alphabet or script.
1263 Therefore, displaying the entire range of scripts that Emacs supports
1264 requires a collection of many fonts. In Emacs, such a collection is
1265 called a @dfn{fontset}. A fontset is defined by a list of font specs,
1266 each assigned to handle a range of character codes, and may fall back
1267 on another fontset for characters which are not covered by the fonts
1270 Each fontset has a name, like a font. However, while fonts are
1271 stored in the system and the available font names are defined by the
1272 system, fontsets are defined within Emacs itself. Once you have
1273 defined a fontset, you can use it within Emacs by specifying its name,
1274 anywhere that you could use a single font. Of course, Emacs fontsets
1275 can use only the fonts that the system supports; if certain characters
1276 appear on the screen as hollow boxes, this means that the fontset in
1277 use for them has no font for those characters.@footnote{The Emacs
1278 installation instructions have information on additional font
1281 Emacs creates three fontsets automatically: the @dfn{standard
1282 fontset}, the @dfn{startup fontset} and the @dfn{default fontset}.
1283 The default fontset is most likely to have fonts for a wide variety of
1284 non-@acronym{ASCII} characters and is the default fallback for the
1285 other two fontsets, and if you set a default font rather than fontset.
1286 However it does not specify font family names, so results can be
1287 somewhat random if you use it directly. You can specify use of a
1288 specific fontset with the @samp{-fn} option. For example,
1291 emacs -fn fontset-standard
1295 You can also specify a fontset with the @samp{Font} resource (@pxref{X
1298 If no fontset is specified for use, then Emacs uses an
1299 @acronym{ASCII} font, with @samp{fontset-default} as a fallback for
1300 characters the font does not cover. The standard fontset is only used if
1301 explicitly requested, despite its name.
1303 A fontset does not necessarily specify a font for every character
1304 code. If a fontset specifies no font for a certain character, or if it
1305 specifies a font that does not exist on your system, then it cannot
1306 display that character properly. It will display that character as an
1309 @node Defining Fontsets
1310 @section Defining fontsets
1312 @vindex standard-fontset-spec
1313 @vindex w32-standard-fontset-spec
1314 @vindex ns-standard-fontset-spec
1315 @cindex standard fontset
1316 When running on X, Emacs creates a standard fontset automatically according to the value
1317 of @code{standard-fontset-spec}. This fontset's name is
1320 -*-fixed-medium-r-normal-*-16-*-*-*-*-*-fontset-standard
1324 or just @samp{fontset-standard} for short.
1326 On GNUstep and Mac, fontset-standard is created using the value of
1327 @code{ns-standard-fontset-spec}, and on Windows it is
1328 created using the value of @code{w32-standard-fontset-spec}.
1330 Bold, italic, and bold-italic variants of the standard fontset are
1331 created automatically. Their names have @samp{bold} instead of
1332 @samp{medium}, or @samp{i} instead of @samp{r}, or both.
1334 @cindex startup fontset
1335 Emacs generates a fontset automatically, based on any default
1336 @acronym{ASCII} font that you specify with the @samp{Font} resource or
1337 the @samp{-fn} argument, or the default font that Emacs found when it
1338 started. This is the @dfn{startup fontset} and its name is
1339 @code{fontset-startup}. It does this by replacing the
1340 @var{charset_registry} field with @samp{fontset}, and replacing
1341 @var{charset_encoding} field with @samp{startup}, then using the
1342 resulting string to specify a fontset.
1344 For instance, if you start Emacs this way,
1347 emacs -fn "*courier-medium-r-normal--14-140-*-iso8859-1"
1351 Emacs generates the following fontset and uses it for the initial X
1355 -*-courier-medium-r-normal-*-14-140-*-*-*-*-fontset-startup
1358 The startup fontset will use the font that you specify or a variant
1359 with a different registry and encoding for all the characters which
1360 are supported by that font, and fallback on @samp{fontset-default} for
1363 With the X resource @samp{Emacs.Font}, you can specify a fontset name
1364 just like an actual font name. But be careful not to specify a fontset
1365 name in a wildcard resource like @samp{Emacs*Font}---that wildcard
1366 specification matches various other resources, such as for menus, and
1367 menus cannot handle fontsets.
1369 You can specify additional fontsets using X resources named
1370 @samp{Fontset-@var{n}}, where @var{n} is an integer starting from 0.
1371 The resource value should have this form:
1374 @var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}}
1378 @var{fontpattern} should have the form of a standard X font name, except
1379 for the last two fields. They should have the form
1380 @samp{fontset-@var{alias}}.
1382 The fontset has two names, one long and one short. The long name is
1383 @var{fontpattern}. The short name is @samp{fontset-@var{alias}}. You
1384 can refer to the fontset by either name.
1386 The construct @samp{@var{charset}:@var{font}} specifies which font to
1387 use (in this fontset) for one particular character set. Here,
1388 @var{charset} is the name of a character set, and @var{font} is the
1389 font to use for that character set. You can use this construct any
1390 number of times in defining one fontset.
1392 For the other character sets, Emacs chooses a font based on
1393 @var{fontpattern}. It replaces @samp{fontset-@var{alias}} with values
1394 that describe the character set. For the @acronym{ASCII} character font,
1395 @samp{fontset-@var{alias}} is replaced with @samp{ISO8859-1}.
1397 In addition, when several consecutive fields are wildcards, Emacs
1398 collapses them into a single wildcard. This is to prevent use of
1399 auto-scaled fonts. Fonts made by scaling larger fonts are not usable
1400 for editing, and scaling a smaller font is not useful because it is
1401 better to use the smaller font in its own size, which is what Emacs
1404 Thus if @var{fontpattern} is this,
1407 -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
1411 the font specification for @acronym{ASCII} characters would be this:
1414 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
1418 and the font specification for Chinese GB2312 characters would be this:
1421 -*-fixed-medium-r-normal-*-24-*-gb2312*-*
1424 You may not have any Chinese font matching the above font
1425 specification. Most X distributions include only Chinese fonts that
1426 have @samp{song ti} or @samp{fangsong ti} in @var{family} field. In
1427 such a case, @samp{Fontset-@var{n}} can be specified as below:
1430 Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
1431 chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
1435 Then, the font specifications for all but Chinese GB2312 characters have
1436 @samp{fixed} in the @var{family} field, and the font specification for
1437 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
1440 @findex create-fontset-from-fontset-spec
1441 The function that processes the fontset resource value to create the
1442 fontset is called @code{create-fontset-from-fontset-spec}. You can also
1443 call this function explicitly to create a fontset.
1445 @xref{Font X}, for more information about font naming in X.
1447 @node Modifying Fontsets
1448 @section Modifying Fontsets
1449 @cindex fontsets, modifying
1450 @findex set-fontset-font
1452 Fontsets do not always have to be created from scratch. If only
1453 minor changes are required it may be easier to modify an existing
1454 fontset. Modifying @samp{fontset-default} will also affect other
1455 fontsets that use it as a fallback, so can be an effective way of
1456 fixing problems with the fonts that Emacs chooses for a particular
1459 Fontsets can be modified using the function @code{set-fontset-font},
1460 specifying a character, a charset, a script, or a range of characters
1461 to modify the font for, and a font-spec for the font to be used. Some
1465 ;; Use Liberation Mono for latin-3 charset.
1466 (set-fontset-font "fontset-default" 'iso-8859-3 "Liberation Mono")
1468 ;; Prefer a big5 font for han characters
1469 (set-fontset-font "fontset-default" 'han (font-spec :registry "big5")
1472 ;; Use DejaVu Sans Mono as a fallback in fontset-startup before
1473 ;; resorting to fontset-default.
1474 (set-fontset-font "fontset-startup" nil "DejaVu Sans Mono" nil 'append)
1476 ;; Use MyPrivateFont for the Unicode private use area.
1477 (set-fontset-font "fontset-default" '(#xe000 . #xf8ff) "MyPrivateFont")
1482 @node Undisplayable Characters
1483 @section Undisplayable Characters
1485 There may be a some non-@acronym{ASCII} characters that your terminal cannot
1486 display. Most text-only terminals support just a single character
1487 set (use the variable @code{default-terminal-coding-system}
1488 (@pxref{Terminal Coding}) to tell Emacs which one); characters which
1489 can't be encoded in that coding system are displayed as @samp{?} by
1492 Graphical displays can display a broader range of characters, but
1493 you may not have fonts installed for all of them; characters that have
1494 no font appear as a hollow box.
1496 If you use Latin-1 characters but your terminal can't display
1497 Latin-1, you can arrange to display mnemonic @acronym{ASCII} sequences
1498 instead, e.g.@: @samp{"o} for o-umlaut. Load the library
1499 @file{iso-ascii} to do this.
1501 @vindex latin1-display
1502 If your terminal can display Latin-1, you can display characters
1503 from other European character sets using a mixture of equivalent
1504 Latin-1 characters and @acronym{ASCII} mnemonics. Customize the variable
1505 @code{latin1-display} to enable this. The mnemonic @acronym{ASCII}
1506 sequences mostly correspond to those of the prefix input methods.
1509 @section Unibyte Editing Mode
1511 @cindex European character sets
1512 @cindex accented characters
1513 @cindex ISO Latin character sets
1514 @cindex Unibyte operation
1515 The ISO 8859 Latin-@var{n} character sets define character codes in
1516 the range 0240 to 0377 octal (160 to 255 decimal) to handle the
1517 accented letters and punctuation needed by various European languages
1518 (and some non-European ones). Note that Emacs considers bytes with
1519 codes in this range as raw bytes, not as characters, even in a unibyte
1520 session, i.e.@: if you disable multibyte characters. However, Emacs
1521 can still handle these character codes as if they belonged to
1522 @emph{one} of the single-byte character sets at a time. To specify
1523 @emph{which} of these codes to use, invoke @kbd{M-x
1524 set-language-environment} and specify a suitable language environment
1525 such as @samp{Latin-@var{n}}.
1527 For more information about unibyte operation, see @ref{Enabling
1528 Multibyte}. Note particularly that you probably want to ensure that
1529 your initialization files are read as unibyte if they contain
1530 non-@acronym{ASCII} characters.
1532 @vindex unibyte-display-via-language-environment
1533 Emacs can also display bytes in the range 160 to 255 as readable
1534 characters, provided the terminal or font in use supports them. This
1535 works automatically. On a graphical display, Emacs can also display
1536 single-byte characters through fontsets, in effect by displaying the
1537 equivalent multibyte characters according to the current language
1538 environment. To request this, set the variable
1539 @code{unibyte-display-via-language-environment} to a non-@code{nil}
1540 value. Note that setting this only affects how these bytes are
1541 displayed, but does not change the fundamental fact that Emacs treats
1542 them as raw bytes, not as characters.
1544 @cindex @code{iso-ascii} library
1545 If your terminal does not support display of the Latin-1 character
1546 set, Emacs can display these characters as @acronym{ASCII} sequences which at
1547 least give you a clear idea of what the characters are. To do this,
1548 load the library @code{iso-ascii}. Similar libraries for other
1549 Latin-@var{n} character sets could be implemented, but we don't have
1552 @findex standard-display-8bit
1553 @cindex 8-bit display
1554 Normally non-ISO-8859 characters (decimal codes between 128 and 159
1555 inclusive) are displayed as octal escapes. You can change this for
1556 non-standard ``extended'' versions of ISO-8859 character sets by using the
1557 function @code{standard-display-8bit} in the @code{disp-table} library.
1559 There are two ways to input single-byte non-@acronym{ASCII}
1565 You can use an input method for the selected language environment.
1566 @xref{Input Methods}. When you use an input method in a unibyte buffer,
1567 the non-@acronym{ASCII} character you specify with it is converted to unibyte.
1570 If your keyboard can generate character codes 128 (decimal) and up,
1571 representing non-@acronym{ASCII} characters, you can type those character codes
1574 On a graphical display, you should not need to do anything special to use
1575 these keys; they should simply work. On a text-only terminal, you
1576 should use the command @code{M-x set-keyboard-coding-system} or the
1577 variable @code{keyboard-coding-system} to specify which coding system
1578 your keyboard uses (@pxref{Terminal Coding}). Enabling this feature
1579 will probably require you to use @kbd{ESC} to type Meta characters;
1580 however, on a console terminal or in @code{xterm}, you can arrange for
1581 Meta to be converted to @kbd{ESC} and still be able type 8-bit
1582 characters present directly on the keyboard or using @kbd{Compose} or
1583 @kbd{AltGr} keys. @xref{User Input}.
1586 @cindex @code{iso-transl} library
1587 @cindex compose character
1588 @cindex dead character
1590 For Latin-1 only, you can use the key @kbd{C-x 8} as a ``compose
1591 character'' prefix for entry of non-@acronym{ASCII} Latin-1 printing
1592 characters. @kbd{C-x 8} is good for insertion (in the minibuffer as
1593 well as other buffers), for searching, and in any other context where
1594 a key sequence is allowed.
1596 @kbd{C-x 8} works by loading the @code{iso-transl} library. Once that
1597 library is loaded, the @key{ALT} modifier key, if the keyboard has
1598 one, serves the same purpose as @kbd{C-x 8}: use @key{ALT} together
1599 with an accent character to modify the following letter. In addition,
1600 if the keyboard has keys for the Latin-1 ``dead accent characters,''
1601 they too are defined to compose with the following character, once
1602 @code{iso-transl} is loaded.
1604 Use @kbd{C-x 8 C-h} to list all the available @kbd{C-x 8} translations.
1611 In Emacs, @dfn{charset} is short for ``character set''. Emacs
1612 supports most popular charsets (such as @code{ascii},
1613 @code{iso-8859-1}, @code{cp1250}, @code{big5}, and @code{unicode}), in
1614 addition to some charsets of its own (such as @code{emacs},
1615 @code{unicode-bmp}, and @code{eight-bit}). All supported characters
1616 belong to one or more charsets.
1618 Emacs normally ``does the right thing'' with respect to charsets, so
1619 that you don't have to worry about them. However, it is sometimes
1620 helpful to know some of the underlying details about charsets.
1622 One example is font selection (@pxref{Font X}). Each language
1623 environment (@pxref{Language Environments}) defines a ``priority
1624 list'' for the various charsets. When searching for a font, Emacs
1625 initially attempts to find one that can display the highest-priority
1626 charsets. For instance, in the Japanese language environment, the
1627 charset @code{japanese-jisx0208} has the highest priority, so Emacs
1628 tries to use a font whose @code{registry} property is
1629 @samp{JISX0208.1983-0}.
1631 @findex list-charset-chars
1632 @cindex characters in a certain charset
1633 @findex describe-character-set
1634 There are two commands that can be used to obtain information about
1635 charsets. The command @kbd{M-x list-charset-chars} prompts for a
1636 charset name, and displays all the characters in that character set.
1637 The command @kbd{M-x describe-character-set} prompts for a charset
1638 name, and displays information about that charset, including its
1639 internal representation within Emacs.
1641 @findex list-character-sets
1642 To display a list of all supported charsets, type @kbd{M-x
1643 list-character-sets}. The list gives the names of charsets and
1644 additional information to identity each charset (see
1645 @url{http://www.itscj.ipsj.or.jp/ISO-IR/} for details). In this list,
1646 charsets are divided into two categories: @dfn{normal charsets} are
1647 listed first, followed by @dfn{supplementary charsets}. A
1648 supplementary charset is one that is used to define another charset
1649 (as a parent or a subset), or to provide backward-compatibility for
1650 older Emacs versions.
1652 To find out which charset a character in the buffer belongs to, put
1653 point before it and type @kbd{C-u C-x =} (@pxref{International
1657 arch-tag: 310ba60d-31ef-4ce7-91f1-f282dd57b6b3