1 @c -*- coding: utf-8 -*-
2 @c This is part of the Emacs manual.
3 @c Copyright (C) 1997, 1999-2017 Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
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)
9 @cindex international scripts
10 @cindex multibyte characters
11 @cindex encoding of characters
31 Emacs supports a wide variety of international character sets,
32 including European and Vietnamese variants of the Latin alphabet, as
33 well as Arabic scripts, Brahmic scripts (for languages such as
34 Bengali, Hindi, and Thai), Cyrillic, Ethiopic, Georgian, Greek, Han
35 (for Chinese and Japanese), Hangul (for Korean), Hebrew and IPA@.
36 Emacs also supports various encodings of these characters that are used by
37 other internationalized software, such as word processors and mailers.
39 Emacs allows editing text with international characters by supporting
40 all the related activities:
44 You can visit files with non-@acronym{ASCII} characters, save non-@acronym{ASCII} text, and
45 pass non-@acronym{ASCII} text between Emacs and programs it invokes (such as
46 compilers, spell-checkers, and mailers). Setting your language
47 environment (@pxref{Language Environments}) takes care of setting up the
48 coding systems and other options for a specific language or culture.
49 Alternatively, you can specify how Emacs should encode or decode text
50 for each command; see @ref{Text Coding}.
53 You can display non-@acronym{ASCII} characters encoded by the various
54 scripts. This works by using appropriate fonts on graphics displays
55 (@pxref{Defining Fontsets}), and by sending special codes to text
56 displays (@pxref{Terminal Coding}). If some characters are displayed
57 incorrectly, refer to @ref{Undisplayable Characters}, which describes
58 possible problems and explains how to solve them.
61 Characters from scripts whose natural ordering of text is from right
62 to left are reordered for display (@pxref{Bidirectional Editing}).
63 These scripts include Arabic, Hebrew, Syriac, Thaana, and a few
67 You can insert non-@acronym{ASCII} characters or search for them. To do that,
68 you can specify an input method (@pxref{Select Input Method}) suitable
69 for your language, or use the default input method set up when you chose
70 your language environment. If
71 your keyboard can produce non-@acronym{ASCII} characters, you can select an
72 appropriate keyboard coding system (@pxref{Terminal Coding}), and Emacs
73 will accept those characters. Latin-1 characters can also be input by
74 using the @kbd{C-x 8} prefix, see @ref{Unibyte Mode}.
76 With the X Window System, your locale should be set to an appropriate
77 value to make sure Emacs interprets keyboard input correctly; see
78 @ref{Language Environments, locales}.
81 The rest of this chapter describes these issues in detail.
84 * International Chars:: Basic concepts of multibyte characters.
85 * Language Environments:: Setting things up for the language you use.
86 * Input Methods:: Entering text characters not on your keyboard.
87 * Select Input Method:: Specifying your choice of input methods.
88 * Coding Systems:: Character set conversion when you read and
89 write files, and so on.
90 * Recognize Coding:: How Emacs figures out which conversion to use.
91 * Specify Coding:: Specifying a file's coding system explicitly.
92 * Output Coding:: Choosing coding systems for output.
93 * Text Coding:: Choosing conversion to use for file text.
94 * Communication Coding:: Coding systems for interprocess communication.
95 * File Name Coding:: Coding systems for file @emph{names}.
96 * Terminal Coding:: Specifying coding systems for converting
97 terminal input and output.
98 * Fontsets:: Fontsets are collections of fonts
99 that cover the whole spectrum of characters.
100 * Defining Fontsets:: Defining a new fontset.
101 * Modifying Fontsets:: Modifying an existing fontset.
102 * Undisplayable Characters:: When characters don't display.
103 * Unibyte Mode:: You can pick one European character set
104 to use without multibyte characters.
105 * Charsets:: How Emacs groups its internal character codes.
106 * Bidirectional Editing:: Support for right-to-left scripts.
109 @node International Chars
110 @section Introduction to International Character Sets
112 The users of international character sets and scripts have
113 established many more-or-less standard coding systems for storing
114 files. These coding systems are typically @dfn{multibyte}, meaning
115 that sequences of two or more bytes are used to represent individual
116 non-@acronym{ASCII} characters.
119 Internally, Emacs uses its own multibyte character encoding, which
120 is a superset of the @dfn{Unicode} standard. This internal encoding
121 allows characters from almost every known script to be intermixed in a
122 single buffer or string. Emacs translates between the multibyte
123 character encoding and various other coding systems when reading and
124 writing files, and when exchanging data with subprocesses.
127 @findex view-hello-file
128 @cindex undisplayable characters
129 @cindex @samp{?} in display
130 The command @kbd{C-h h} (@code{view-hello-file}) displays the file
131 @file{etc/HELLO}, which illustrates various scripts by showing
132 how to say ``hello'' in many languages. If some characters can't be
133 displayed on your terminal, they appear as @samp{?} or as hollow boxes
134 (@pxref{Undisplayable Characters}).
136 Keyboards, even in the countries where these character sets are
137 used, generally don't have keys for all the characters in them. You
138 can insert characters that your keyboard does not support, using
139 @kbd{C-x 8 @key{RET}} (@code{insert-char}). @xref{Inserting Text}.
140 Shorthands are available for some common characters; for example, you
141 can insert a left single quotation mark @t{‘} by typing @kbd{C-x 8
142 [}, or in Electric Quote mode often by simply typing @kbd{`}.
143 @xref{Quotation Marks}. 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 script, syntax and categories.
198 What keys to type to input the character in the current input method
199 (if it supports the character).
202 The character's encodings, both internally in the buffer, and externally
203 if you were to save the file.
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
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, with some lines folded to fit into this manual:
220 position: 1 of 1 (0%), column: 0
221 character: ê (displayed as ê) (codepoint 234, #o352, #xea)
222 preferred charset: unicode (Unicode (ISO10646))
223 code point in charset: 0xEA
225 syntax: w which means: word
226 category: .:Base, L:Left-to-right (strong), c:Chinese,
227 j:Japanese, l:Latin, v:Viet
228 to input: type "C-x 8 RET ea" or
229 "C-x 8 RET LATIN SMALL LETTER E WITH CIRCUMFLEX"
230 buffer code: #xC3 #xAA
231 file code: #xC3 #xAA (encoded by coding system utf-8-unix)
232 display: by this font (glyph code)
233 xft:-PfEd-DejaVu Sans Mono-normal-normal-
234 normal-*-15-*-*-*-m-0-iso10646-1 (#xAC)
236 Character code properties: customize what to show
237 name: LATIN SMALL LETTER E WITH CIRCUMFLEX
238 old-name: LATIN SMALL LETTER E CIRCUMFLEX
239 general-category: Ll (Letter, Lowercase)
240 decomposition: (101 770) ('e' '^')
243 @node Language Environments
244 @section Language Environments
245 @cindex language environments
247 All supported character sets are supported in Emacs buffers whenever
248 multibyte characters are enabled; there is no need to select a
249 particular language in order to display its characters.
250 However, it is important to select a @dfn{language
251 environment} in order to set various defaults. Roughly speaking, the
252 language environment represents a choice of preferred script rather
253 than a choice of language.
255 The language environment controls which coding systems to recognize
256 when reading text (@pxref{Recognize Coding}). This applies to files,
257 incoming mail, and any other text you read into Emacs. It may also
258 specify the default coding system to use when you create a file. Each
259 language environment also specifies a default input method.
261 @findex set-language-environment
262 @vindex current-language-environment
263 To select a language environment, customize
264 @code{current-language-environment} or use the command @kbd{M-x
265 set-language-environment}. It makes no difference which buffer is
266 current when you use this command, because the effects apply globally
267 to the Emacs session. See the variable @code{language-info-alist} for
268 the list of supported language environments, and use the command
269 @kbd{C-h L @var{lang-env} @key{RET}} (@code{describe-language-environment})
270 for more information about the language environment @var{lang-env}.
271 Supported language environments include:
273 @c @cindex entries below are split between portions of the list to
274 @c make them more accurate, i.e., land on the line that mentions the
275 @c language. However, makeinfo 4.x doesn't fill inside @quotation
276 @c lines that follow a @cindex entry and whose text has no whitespace.
277 @c To work around, we group the language environments together, so
278 @c that the blank that separates them triggers refill.
286 @cindex Brazilian Portuguese
288 Brazilian Portuguese, Bulgarian,
293 Chinese-BIG5, Chinese-CNS, Chinese-EUC-TW, Chinese-GB,
294 Chinese-GB18030, Chinese-GBK,
297 Croatian, Cyrillic-ALT, Cyrillic-ISO, Cyrillic-KOI8,
313 German, Greek, Gujarati,
327 Latin-1, Latin-2, Latin-3, Latin-4, Latin-5, Latin-6, Latin-7,
347 Slovak, Slovenian, Spanish,
370 To display the script(s) used by your language environment on a
371 graphical display, you need to have suitable fonts.
372 @xref{Fontsets}, for more details about setting up your fonts.
374 @findex set-locale-environment
375 @vindex locale-language-names
376 @vindex locale-charset-language-names
378 Some operating systems let you specify the character-set locale you
379 are using by setting the locale environment variables @env{LC_ALL},
380 @env{LC_CTYPE}, or @env{LANG}. (If more than one of these is
381 set, the first one that is nonempty specifies your locale for this
382 purpose.) During startup, Emacs looks up your character-set locale's
383 name in the system locale alias table, matches its canonical name
384 against entries in the value of the variables
385 @code{locale-charset-language-names} and @code{locale-language-names}
386 (the former overrides the latter),
387 and selects the corresponding language environment if a match is found.
388 It also adjusts the display
389 table and terminal coding system, the locale coding system, the
390 preferred coding system as needed for the locale, and---last but not
391 least---the way Emacs decodes non-@acronym{ASCII} characters sent by your keyboard.
393 @c This seems unlikely, doesn't it?
394 If you modify the @env{LC_ALL}, @env{LC_CTYPE}, or @env{LANG}
395 environment variables while running Emacs (by using @kbd{M-x setenv}),
396 you may want to invoke the @code{set-locale-environment}
397 function afterwards to readjust the language environment from the new
400 @vindex locale-preferred-coding-systems
401 The @code{set-locale-environment} function normally uses the preferred
402 coding system established by the language environment to decode system
403 messages. But if your locale matches an entry in the variable
404 @code{locale-preferred-coding-systems}, Emacs uses the corresponding
405 coding system instead. For example, if the locale @samp{ja_JP.PCK}
406 matches @code{japanese-shift-jis} in
407 @code{locale-preferred-coding-systems}, Emacs uses that encoding even
408 though it might normally use @code{japanese-iso-8bit}.
410 You can override the language environment chosen at startup with
411 explicit use of the command @code{set-language-environment}, or with
412 customization of @code{current-language-environment} in your init
416 @findex describe-language-environment
417 To display information about the effects of a certain language
418 environment @var{lang-env}, use the command @kbd{C-h L @var{lang-env}
419 @key{RET}} (@code{describe-language-environment}). This tells you
420 which languages this language environment is useful for, and lists the
421 character sets, coding systems, and input methods that go with it. It
422 also shows some sample text to illustrate scripts used in this
423 language environment. If you give an empty input for @var{lang-env},
424 this command describes the chosen language environment.
426 @vindex set-language-environment-hook
427 You can customize any language environment with the normal hook
428 @code{set-language-environment-hook}. The command
429 @code{set-language-environment} runs that hook after setting up the new
430 language environment. The hook functions can test for a specific
431 language environment by checking the variable
432 @code{current-language-environment}. This hook is where you should
433 put non-default settings for specific language environments, such as
434 coding systems for keyboard input and terminal output, the default
437 @vindex exit-language-environment-hook
438 Before it starts to set up the new language environment,
439 @code{set-language-environment} first runs the hook
440 @code{exit-language-environment-hook}. This hook is useful for undoing
441 customizations that were made with @code{set-language-environment-hook}.
442 For instance, if you set up a special key binding in a specific language
443 environment using @code{set-language-environment-hook}, you should set
444 up @code{exit-language-environment-hook} to restore the normal binding
448 @section Input Methods
450 @cindex input methods
451 An @dfn{input method} is a kind of character conversion designed
452 specifically for interactive input. In Emacs, typically each language
453 has its own input method; sometimes several languages that use the same
454 characters can share one input method. A few languages support several
457 The simplest kind of input method works by mapping @acronym{ASCII} letters
458 into another alphabet; this allows you to use one other alphabet
459 instead of @acronym{ASCII}. The Greek and Russian input methods
462 A more powerful technique is composition: converting sequences of
463 characters into one letter. Many European input methods use composition
464 to produce a single non-@acronym{ASCII} letter from a sequence that consists of a
465 letter followed by accent characters (or vice versa). For example, some
466 methods convert the sequence @kbd{o ^} into a single accented letter.
467 These input methods have no special commands of their own; all they do
468 is compose sequences of printing characters.
470 The input methods for syllabic scripts typically use mapping followed
471 by composition. The input methods for Thai and Korean work this way.
472 First, letters are mapped into symbols for particular sounds or tone
473 marks; then, sequences of these that make up a whole syllable are
474 mapped into one syllable sign.
476 Chinese and Japanese require more complex methods. In Chinese input
477 methods, first you enter the phonetic spelling of a Chinese word (in
478 input method @code{chinese-py}, among others), or a sequence of
479 portions of the character (input methods @code{chinese-4corner} and
480 @code{chinese-sw}, and others). One input sequence typically
481 corresponds to many possible Chinese characters. You select the one
482 you mean using keys such as @kbd{C-f}, @kbd{C-b}, @kbd{C-n},
483 @kbd{C-p} (or the arrow keys), and digits, which have special meanings
486 The possible characters are conceptually arranged in several rows,
487 with each row holding up to 10 alternatives. Normally, Emacs displays
488 just one row at a time, in the echo area; @code{(@var{i}/@var{j})}
489 appears at the beginning, to indicate that this is the @var{i}th row
490 out of a total of @var{j} rows. Type @kbd{C-n} or @kbd{C-p} to
491 display the next row or the previous row.
493 Type @kbd{C-f} and @kbd{C-b} to move forward and backward among
494 the alternatives in the current row. As you do this, Emacs highlights
495 the current alternative with a special color; type @code{C-@key{SPC}}
496 to select the current alternative and use it as input. The
497 alternatives in the row are also numbered; the number appears before
498 the alternative. Typing a number selects the associated alternative
499 of the current row and uses it as input.
501 @key{TAB} in these Chinese input methods displays a buffer showing
502 all the possible characters at once; then clicking @kbd{mouse-2} on
503 one of them selects that alternative. The keys @kbd{C-f}, @kbd{C-b},
504 @kbd{C-n}, @kbd{C-p}, and digits continue to work as usual, but they
505 do the highlighting in the buffer showing the possible characters,
506 rather than in the echo area.
508 In Japanese input methods, first you input a whole word using
509 phonetic spelling; then, after the word is in the buffer, Emacs
510 converts it into one or more characters using a large dictionary. One
511 phonetic spelling corresponds to a number of different Japanese words;
512 to select one of them, use @kbd{C-n} and @kbd{C-p} to cycle through
515 Sometimes it is useful to cut off input method processing so that the
516 characters you have just entered will not combine with subsequent
517 characters. For example, in input method @code{latin-1-postfix}, the
518 sequence @kbd{o ^} combines to form an @samp{o} with an accent. What if
519 you want to enter them as separate characters?
521 One way is to type the accent twice; this is a special feature for
522 entering the separate letter and accent. For example, @kbd{o ^ ^} gives
523 you the two characters @samp{o^}. Another way is to type another letter
524 after the @kbd{o}---something that won't combine with that---and
525 immediately delete it. For example, you could type @kbd{o o @key{DEL}
526 ^} to get separate @samp{o} and @samp{^}.
528 Another method, more general but not quite as easy to type, is to use
529 @kbd{C-\ C-\} between two characters to stop them from combining. This
530 is the command @kbd{C-\} (@code{toggle-input-method}) used twice.
532 @xref{Select Input Method}.
535 @cindex incremental search, input method interference
536 @kbd{C-\ C-\} is especially useful inside an incremental search,
537 because it stops waiting for more characters to combine, and starts
538 searching for what you have already entered.
540 To find out how to input the character after point using the current
541 input method, type @kbd{C-u C-x =}. @xref{Position Info}.
543 @c TODO: document complex-only/default/t of
544 @c @code{input-method-verbose-flag}
545 @vindex input-method-verbose-flag
546 @vindex input-method-highlight-flag
547 The variables @code{input-method-highlight-flag} and
548 @code{input-method-verbose-flag} control how input methods explain
549 what is happening. If @code{input-method-highlight-flag} is
550 non-@code{nil}, the partial sequence is highlighted in the buffer (for
551 most input methods---some disable this feature). If
552 @code{input-method-verbose-flag} is non-@code{nil}, the list of
553 possible characters to type next is displayed in the echo area (but
554 not when you are in the minibuffer).
556 @vindex quail-activate-hook
557 @findex quail-translation-keymap
558 You can modify how an input method works by making your changes in a
559 function that you add to the hook variable @code{quail-activate-hook}.
560 @xref{Hooks}. For example, you can redefine some of the input
561 method's keys by defining key bindings in the keymap returned by the
562 function @code{quail-translation-keymap}, using @code{define-key}.
563 @xref{Init Rebinding}.
565 Another facility for typing characters not on your keyboard is by
566 using @kbd{C-x 8 @key{RET}} (@code{insert-char}) to insert a single
567 character based on its Unicode name or code-point; see @ref{Inserting
570 @node Select Input Method
571 @section Selecting an Input Method
575 Enable or disable use of the selected input method (@code{toggle-input-method}).
577 @item C-x @key{RET} C-\ @var{method} @key{RET}
578 Select a new input method for the current buffer (@code{set-input-method}).
580 @item C-h I @var{method} @key{RET}
581 @itemx C-h C-\ @var{method} @key{RET}
582 @findex describe-input-method
585 Describe the input method @var{method} (@code{describe-input-method}).
586 By default, it describes the current input method (if any). This
587 description should give you the full details of how to use any
588 particular input method.
590 @item M-x list-input-methods
591 Display a list of all the supported input methods.
594 @findex set-input-method
595 @vindex current-input-method
597 To choose an input method for the current buffer, use @kbd{C-x
598 @key{RET} C-\} (@code{set-input-method}). This command reads the
599 input method name from the minibuffer; the name normally starts with the
600 language environment that it is meant to be used with. The variable
601 @code{current-input-method} records which input method is selected.
603 @findex toggle-input-method
605 Input methods use various sequences of @acronym{ASCII} characters to
606 stand for non-@acronym{ASCII} characters. Sometimes it is useful to
607 turn off the input method temporarily. To do this, type @kbd{C-\}
608 (@code{toggle-input-method}). To reenable the input method, type
611 If you type @kbd{C-\} and you have not yet selected an input method,
612 it prompts you to specify one. This has the same effect as using
613 @kbd{C-x @key{RET} C-\} to specify an input method.
615 When invoked with a numeric argument, as in @kbd{C-u C-\},
616 @code{toggle-input-method} always prompts you for an input method,
617 suggesting the most recently selected one as the default.
619 @vindex default-input-method
620 Selecting a language environment specifies a default input method for
621 use in various buffers. When you have a default input method, you can
622 select it in the current buffer by typing @kbd{C-\}. The variable
623 @code{default-input-method} specifies the default input method
624 (@code{nil} means there is none).
626 In some language environments, which support several different input
627 methods, you might want to use an input method different from the
628 default chosen by @code{set-language-environment}. You can instruct
629 Emacs to select a different default input method for a certain
630 language environment, if you wish, by using
631 @code{set-language-environment-hook} (@pxref{Language Environments,
632 set-language-environment-hook}). For example:
635 (defun my-chinese-setup ()
636 "Set up my private Chinese environment."
637 (if (equal current-language-environment "Chinese-GB")
638 (setq default-input-method "chinese-tonepy")))
639 (add-hook 'set-language-environment-hook 'my-chinese-setup)
643 This sets the default input method to be @code{chinese-tonepy}
644 whenever you choose a Chinese-GB language environment.
646 You can instruct Emacs to activate a certain input method
647 automatically. For example:
650 (add-hook 'text-mode-hook
651 (lambda () (set-input-method "german-prefix")))
655 This automatically activates the input method @code{german-prefix} in
658 @findex quail-set-keyboard-layout
659 Some input methods for alphabetic scripts work by (in effect)
660 remapping the keyboard to emulate various keyboard layouts commonly used
661 for those scripts. How to do this remapping properly depends on your
662 actual keyboard layout. To specify which layout your keyboard has, use
663 the command @kbd{M-x quail-set-keyboard-layout}.
665 @findex quail-show-key
666 You can use the command @kbd{M-x quail-show-key} to show what key (or
667 key sequence) to type in order to input the character following point,
668 using the selected keyboard layout. The command @kbd{C-u C-x =} also
669 shows that information, in addition to other information about the
672 @findex list-input-methods
673 @kbd{M-x list-input-methods} displays a list of all the supported
674 input methods. The list gives information about each input method,
675 including the string that stands for it in the mode line.
678 @section Coding Systems
679 @cindex coding systems
681 Users of various languages have established many more-or-less standard
682 coding systems for representing them. Emacs does not use these coding
683 systems internally; instead, it converts from various coding systems to
684 its own system when reading data, and converts the internal coding
685 system to other coding systems when writing data. Conversion is
686 possible in reading or writing files, in sending or receiving from the
687 terminal, and in exchanging data with subprocesses.
689 Emacs assigns a name to each coding system. Most coding systems are
690 used for one language, and the name of the coding system starts with
691 the language name. Some coding systems are used for several
692 languages; their names usually start with @samp{iso}. There are also
693 special coding systems, such as @code{no-conversion}, @code{raw-text},
694 and @code{emacs-internal}.
696 @cindex international files from DOS/Windows systems
697 A special class of coding systems, collectively known as
698 @dfn{codepages}, is designed to support text encoded by MS-Windows and
699 MS-DOS software. The names of these coding systems are
700 @code{cp@var{nnnn}}, where @var{nnnn} is a 3- or 4-digit number of the
701 codepage. You can use these encodings just like any other coding
702 system; for example, to visit a file encoded in codepage 850, type
703 @kbd{C-x @key{RET} c cp850 @key{RET} C-x C-f @var{filename}
706 In addition to converting various representations of non-@acronym{ASCII}
707 characters, a coding system can perform end-of-line conversion. Emacs
708 handles three different conventions for how to separate lines in a file:
709 newline (Unix), carriage-return linefeed (DOS), and just
710 carriage-return (Mac).
713 @item C-h C @var{coding} @key{RET}
714 Describe coding system @var{coding} (@code{describe-coding-system}).
716 @item C-h C @key{RET}
717 Describe the coding systems currently in use.
719 @item M-x list-coding-systems
720 Display a list of all the supported coding systems.
724 @findex describe-coding-system
725 The command @kbd{C-h C} (@code{describe-coding-system}) displays
726 information about particular coding systems, including the end-of-line
727 conversion specified by those coding systems. You can specify a coding
728 system name as the argument; alternatively, with an empty argument, it
729 describes the coding systems currently selected for various purposes,
730 both in the current buffer and as the defaults, and the priority list
731 for recognizing coding systems (@pxref{Recognize Coding}).
733 @findex list-coding-systems
734 To display a list of all the supported coding systems, type @kbd{M-x
735 list-coding-systems}. The list gives information about each coding
736 system, including the letter that stands for it in the mode line
739 @cindex end-of-line conversion
741 @cindex MS-DOS end-of-line conversion
742 @cindex Macintosh end-of-line conversion
743 Each of the coding systems that appear in this list---except for
744 @code{no-conversion}, which means no conversion of any kind---specifies
745 how and whether to convert printing characters, but leaves the choice of
746 end-of-line conversion to be decided based on the contents of each file.
747 For example, if the file appears to use the sequence carriage-return
748 linefeed to separate lines, DOS end-of-line conversion will be used.
750 Each of the listed coding systems has three variants, which specify
751 exactly what to do for end-of-line conversion:
755 Don't do any end-of-line conversion; assume the file uses
756 newline to separate lines. (This is the convention normally used
757 on Unix and GNU systems, and macOS.)
760 Assume the file uses carriage-return linefeed to separate lines, and do
761 the appropriate conversion. (This is the convention normally used on
762 Microsoft systems.@footnote{It is also specified for MIME @samp{text/*}
763 bodies and in other network transport contexts. It is different
764 from the SGML reference syntax record-start/record-end format, which
765 Emacs doesn't support directly.})
768 Assume the file uses carriage-return to separate lines, and do the
769 appropriate conversion. (This was the convention used in Classic Mac
773 These variant coding systems are omitted from the
774 @code{list-coding-systems} display for brevity, since they are entirely
775 predictable. For example, the coding system @code{iso-latin-1} has
776 variants @code{iso-latin-1-unix}, @code{iso-latin-1-dos} and
777 @code{iso-latin-1-mac}.
779 @cindex @code{undecided}, coding system
780 The coding systems @code{unix}, @code{dos}, and @code{mac} are
781 aliases for @code{undecided-unix}, @code{undecided-dos}, and
782 @code{undecided-mac}, respectively. These coding systems specify only
783 the end-of-line conversion, and leave the character code conversion to
784 be deduced from the text itself.
786 @cindex @code{raw-text}, coding system
787 The coding system @code{raw-text} is good for a file which is mainly
788 @acronym{ASCII} text, but may contain byte values above 127 that are
789 not meant to encode non-@acronym{ASCII} characters. With
790 @code{raw-text}, Emacs copies those byte values unchanged, and sets
791 @code{enable-multibyte-characters} to @code{nil} in the current buffer
792 so that they will be interpreted properly. @code{raw-text} handles
793 end-of-line conversion in the usual way, based on the data
794 encountered, and has the usual three variants to specify the kind of
795 end-of-line conversion to use.
797 @cindex @code{no-conversion}, coding system
798 In contrast, the coding system @code{no-conversion} specifies no
799 character code conversion at all---none for non-@acronym{ASCII} byte values and
800 none for end of line. This is useful for reading or writing binary
801 files, tar files, and other files that must be examined verbatim. It,
802 too, sets @code{enable-multibyte-characters} to @code{nil}.
804 The easiest way to edit a file with no conversion of any kind is with
805 the @kbd{M-x find-file-literally} command. This uses
806 @code{no-conversion}, and also suppresses other Emacs features that
807 might convert the file contents before you see them. @xref{Visiting}.
809 @cindex @code{emacs-internal}, coding system
810 The coding system @code{emacs-internal} (or @code{utf-8-emacs},
811 which is equivalent) means that the file contains non-@acronym{ASCII}
812 characters stored with the internal Emacs encoding. This coding
813 system handles end-of-line conversion based on the data encountered,
814 and has the usual three variants to specify the kind of end-of-line
817 @node Recognize Coding
818 @section Recognizing Coding Systems
820 Whenever Emacs reads a given piece of text, it tries to recognize
821 which coding system to use. This applies to files being read, output
822 from subprocesses, text from X selections, etc. Emacs can select the
823 right coding system automatically most of the time---once you have
824 specified your preferences.
826 Some coding systems can be recognized or distinguished by which byte
827 sequences appear in the data. However, there are coding systems that
828 cannot be distinguished, not even potentially. For example, there is no
829 way to distinguish between Latin-1 and Latin-2; they use the same byte
830 values with different meanings.
832 Emacs handles this situation by means of a priority list of coding
833 systems. Whenever Emacs reads a file, if you do not specify the coding
834 system to use, Emacs checks the data against each coding system,
835 starting with the first in priority and working down the list, until it
836 finds a coding system that fits the data. Then it converts the file
837 contents assuming that they are represented in this coding system.
839 The priority list of coding systems depends on the selected language
840 environment (@pxref{Language Environments}). For example, if you use
841 French, you probably want Emacs to prefer Latin-1 to Latin-2; if you use
842 Czech, you probably want Latin-2 to be preferred. This is one of the
843 reasons to specify a language environment.
845 @findex prefer-coding-system
846 However, you can alter the coding system priority list in detail
847 with the command @kbd{M-x prefer-coding-system}. This command reads
848 the name of a coding system from the minibuffer, and adds it to the
849 front of the priority list, so that it is preferred to all others. If
850 you use this command several times, each use adds one element to the
851 front of the priority list.
853 If you use a coding system that specifies the end-of-line conversion
854 type, such as @code{iso-8859-1-dos}, what this means is that Emacs
855 should attempt to recognize @code{iso-8859-1} with priority, and should
856 use DOS end-of-line conversion when it does recognize @code{iso-8859-1}.
858 @vindex file-coding-system-alist
859 Sometimes a file name indicates which coding system to use for the
860 file. The variable @code{file-coding-system-alist} specifies this
861 correspondence. There is a special function
862 @code{modify-coding-system-alist} for adding elements to this list. For
863 example, to read and write all @samp{.txt} files using the coding system
864 @code{chinese-iso-8bit}, you can execute this Lisp expression:
867 (modify-coding-system-alist 'file "\\.txt\\'" 'chinese-iso-8bit)
871 The first argument should be @code{file}, the second argument should be
872 a regular expression that determines which files this applies to, and
873 the third argument says which coding system to use for these files.
875 @vindex inhibit-eol-conversion
876 @cindex DOS-style end-of-line display
877 Emacs recognizes which kind of end-of-line conversion to use based on
878 the contents of the file: if it sees only carriage-returns, or only
879 carriage-return linefeed sequences, then it chooses the end-of-line
880 conversion accordingly. You can inhibit the automatic use of
881 end-of-line conversion by setting the variable @code{inhibit-eol-conversion}
882 to non-@code{nil}. If you do that, DOS-style files will be displayed
883 with the @samp{^M} characters visible in the buffer; some people
884 prefer this to the more subtle @samp{(DOS)} end-of-line type
885 indication near the left edge of the mode line (@pxref{Mode Line,
888 @vindex inhibit-iso-escape-detection
889 @cindex escape sequences in files
890 By default, the automatic detection of coding system is sensitive to
891 escape sequences. If Emacs sees a sequence of characters that begin
892 with an escape character, and the sequence is valid as an ISO-2022
893 code, that tells Emacs to use one of the ISO-2022 encodings to decode
896 However, there may be cases that you want to read escape sequences
897 in a file as is. In such a case, you can set the variable
898 @code{inhibit-iso-escape-detection} to non-@code{nil}. Then the code
899 detection ignores any escape sequences, and never uses an ISO-2022
900 encoding. The result is that all escape sequences become visible in
903 The default value of @code{inhibit-iso-escape-detection} is
904 @code{nil}. We recommend that you not change it permanently, only for
905 one specific operation. That's because some Emacs Lisp source files
906 in the Emacs distribution contain non-@acronym{ASCII} characters encoded in the
907 coding system @code{iso-2022-7bit}, and they won't be
908 decoded correctly when you visit those files if you suppress the
909 escape sequence detection.
910 @c I count a grand total of 3 such files, so is the above really true?
912 @vindex auto-coding-alist
913 @vindex auto-coding-regexp-alist
914 The variables @code{auto-coding-alist} and
915 @code{auto-coding-regexp-alist} are
916 the strongest way to specify the coding system for certain patterns of
917 file names, or for files containing certain patterns, respectively.
918 These variables even override @samp{-*-coding:-*-} tags in the file
919 itself (@pxref{Specify Coding}). For example, Emacs
920 uses @code{auto-coding-alist} for tar and archive files, to prevent it
921 from being confused by a @samp{-*-coding:-*-} tag in a member of the
922 archive and thinking it applies to the archive file as a whole.
924 @c This describes old-style BABYL files, which are no longer relevant.
925 Likewise, Emacs uses @code{auto-coding-regexp-alist} to ensure that
926 RMAIL files, whose names in general don't match any particular
927 pattern, are decoded correctly.
930 @vindex auto-coding-functions
931 Another way to specify a coding system is with the variable
932 @code{auto-coding-functions}. For example, one of the builtin
933 @code{auto-coding-functions} detects the encoding for XML files.
934 Unlike the previous two, this variable does not override any
935 @samp{-*-coding:-*-} tag.
938 @section Specifying a File's Coding System
940 If Emacs recognizes the encoding of a file incorrectly, you can
941 reread the file using the correct coding system with @kbd{C-x
942 @key{RET} r} (@code{revert-buffer-with-coding-system}). This command
943 prompts for the coding system to use. To see what coding system Emacs
944 actually used to decode the file, look at the coding system mnemonic
945 letter near the left edge of the mode line (@pxref{Mode Line}), or
946 type @kbd{C-h C} (@code{describe-coding-system}).
949 You can specify the coding system for a particular file in the file
950 itself, using the @w{@samp{-*-@dots{}-*-}} construct at the beginning,
951 or a local variables list at the end (@pxref{File Variables}). You do
952 this by defining a value for the ``variable'' named @code{coding}.
953 Emacs does not really have a variable @code{coding}; instead of
954 setting a variable, this uses the specified coding system for the
955 file. For example, @samp{-*-mode: C; coding: latin-1;-*-} specifies
956 use of the Latin-1 coding system, as well as C mode. When you specify
957 the coding explicitly in the file, that overrides
958 @code{file-coding-system-alist}.
961 @section Choosing Coding Systems for Output
963 @vindex buffer-file-coding-system
964 Once Emacs has chosen a coding system for a buffer, it stores that
965 coding system in @code{buffer-file-coding-system}. That makes it the
966 default for operations that write from this buffer into a file, such
967 as @code{save-buffer} and @code{write-region}. You can specify a
968 different coding system for further file output from the buffer using
969 @code{set-buffer-file-coding-system} (@pxref{Text Coding}).
971 You can insert any character Emacs supports into any Emacs buffer,
972 but most coding systems can only handle a subset of these characters.
973 Therefore, it's possible that the characters you insert cannot be
974 encoded with the coding system that will be used to save the buffer.
975 For example, you could visit a text file in Polish, encoded in
976 @code{iso-8859-2}, and add some Russian words to it. When you save
977 that buffer, Emacs cannot use the current value of
978 @code{buffer-file-coding-system}, because the characters you added
979 cannot be encoded by that coding system.
981 When that happens, Emacs tries the most-preferred coding system (set
982 by @kbd{M-x prefer-coding-system} or @kbd{M-x
983 set-language-environment}). If that coding system can safely encode
984 all of the characters in the buffer, Emacs uses it, and stores its
985 value in @code{buffer-file-coding-system}. Otherwise, Emacs displays
986 a list of coding systems suitable for encoding the buffer's contents,
987 and asks you to choose one of those coding systems.
989 If you insert the unsuitable characters in a mail message, Emacs
990 behaves a bit differently. It additionally checks whether the
991 @c What determines this?
992 most-preferred coding system is recommended for use in MIME messages;
993 if not, it informs you of this fact and prompts you for another coding
994 system. This is so you won't inadvertently send a message encoded in
995 a way that your recipient's mail software will have difficulty
996 decoding. (You can still use an unsuitable coding system if you enter
997 its name at the prompt.)
999 @c It seems that select-message-coding-system does this.
1000 @c Both sendmail.el and smptmail.el call it; i.e., smtpmail.el still
1001 @c obeys sendmail-coding-system.
1002 @vindex sendmail-coding-system
1003 When you send a mail message (@pxref{Sending Mail}),
1004 Emacs has four different ways to determine the coding system to use
1005 for encoding the message text. It tries the buffer's own value of
1006 @code{buffer-file-coding-system}, if that is non-@code{nil}.
1007 Otherwise, it uses the value of @code{sendmail-coding-system}, if that
1008 is non-@code{nil}. The third way is to use the default coding system
1009 for new files, which is controlled by your choice of language
1010 @c i.e., default-sendmail-coding-system
1011 environment, if that is non-@code{nil}. If all of these three values
1012 are @code{nil}, Emacs encodes outgoing mail using the Latin-1 coding
1014 @c FIXME? Where does the Latin-1 default come in?
1017 @section Specifying a Coding System for File Text
1019 In cases where Emacs does not automatically choose the right coding
1020 system for a file's contents, you can use these commands to specify
1024 @item C-x @key{RET} f @var{coding} @key{RET}
1025 Use coding system @var{coding} to save or revisit the file in
1026 the current buffer (@code{set-buffer-file-coding-system}).
1028 @item C-x @key{RET} c @var{coding} @key{RET}
1029 Specify coding system @var{coding} for the immediately following
1030 command (@code{universal-coding-system-argument}).
1032 @item C-x @key{RET} r @var{coding} @key{RET}
1033 Revisit the current file using the coding system @var{coding}
1034 (@code{revert-buffer-with-coding-system}).
1036 @item M-x recode-region @key{RET} @var{right} @key{RET} @var{wrong} @key{RET}
1037 Convert a region that was decoded using coding system @var{wrong},
1038 decoding it using coding system @var{right} instead.
1042 @findex set-buffer-file-coding-system
1043 The command @kbd{C-x @key{RET} f}
1044 (@code{set-buffer-file-coding-system}) sets the file coding system for
1045 the current buffer (i.e., the coding system to use when saving or
1046 reverting the file). You specify which coding system using the
1047 minibuffer. You can also invoke this command by clicking with
1048 @kbd{mouse-3} on the coding system indicator in the mode line
1049 (@pxref{Mode Line}).
1051 If you specify a coding system that cannot handle all the characters
1052 in the buffer, Emacs will warn you about the troublesome characters,
1053 and ask you to choose another coding system, when you try to save the
1054 buffer (@pxref{Output Coding}).
1056 @cindex specify end-of-line conversion
1057 You can also use this command to specify the end-of-line conversion
1058 (@pxref{Coding Systems, end-of-line conversion}) for encoding the
1059 current buffer. For example, @kbd{C-x @key{RET} f dos @key{RET}} will
1060 cause Emacs to save the current buffer's text with DOS-style
1061 carriage-return linefeed line endings.
1064 @findex universal-coding-system-argument
1065 Another way to specify the coding system for a file is when you visit
1066 the file. First use the command @kbd{C-x @key{RET} c}
1067 (@code{universal-coding-system-argument}); this command uses the
1068 minibuffer to read a coding system name. After you exit the minibuffer,
1069 the specified coding system is used for @emph{the immediately following
1072 So if the immediately following command is @kbd{C-x C-f}, for example,
1073 it reads the file using that coding system (and records the coding
1074 system for when you later save the file). Or if the immediately following
1075 command is @kbd{C-x C-w}, it writes the file using that coding system.
1076 When you specify the coding system for saving in this way, instead
1077 of with @kbd{C-x @key{RET} f}, there is no warning if the buffer
1078 contains characters that the coding system cannot handle.
1080 Other file commands affected by a specified coding system include
1081 @kbd{C-x i} and @kbd{C-x C-v}, as well as the other-window variants
1082 of @kbd{C-x C-f}. @kbd{C-x @key{RET} c} also affects commands that
1083 start subprocesses, including @kbd{M-x shell} (@pxref{Shell}). If the
1084 immediately following command does not use the coding system, then
1085 @kbd{C-x @key{RET} c} ultimately has no effect.
1087 An easy way to visit a file with no conversion is with the @kbd{M-x
1088 find-file-literally} command. @xref{Visiting}.
1090 The default value of the variable @code{buffer-file-coding-system}
1091 specifies the choice of coding system to use when you create a new file.
1092 It applies when you find a new file, and when you create a buffer and
1093 then save it in a file. Selecting a language environment typically sets
1094 this variable to a good choice of default coding system for that language
1098 @findex revert-buffer-with-coding-system
1099 If you visit a file with a wrong coding system, you can correct this
1100 with @kbd{C-x @key{RET} r} (@code{revert-buffer-with-coding-system}).
1101 This visits the current file again, using a coding system you specify.
1103 @findex recode-region
1104 If a piece of text has already been inserted into a buffer using the
1105 wrong coding system, you can redo the decoding of it using @kbd{M-x
1106 recode-region}. This prompts you for the proper coding system, then
1107 for the wrong coding system that was actually used, and does the
1108 conversion. It first encodes the region using the wrong coding system,
1109 then decodes it again using the proper coding system.
1111 @node Communication Coding
1112 @section Coding Systems for Interprocess Communication
1114 This section explains how to specify coding systems for use
1115 in communication with other processes.
1118 @item C-x @key{RET} x @var{coding} @key{RET}
1119 Use coding system @var{coding} for transferring selections to and from
1120 other graphical applications (@code{set-selection-coding-system}).
1122 @item C-x @key{RET} X @var{coding} @key{RET}
1123 Use coding system @var{coding} for transferring @emph{one}
1124 selection---the next one---to or from another graphical application
1125 (@code{set-next-selection-coding-system}).
1127 @item C-x @key{RET} p @var{input-coding} @key{RET} @var{output-coding} @key{RET}
1128 Use coding systems @var{input-coding} and @var{output-coding} for
1129 subprocess input and output in the current buffer
1130 (@code{set-buffer-process-coding-system}).
1135 @findex set-selection-coding-system
1136 @findex set-next-selection-coding-system
1137 The command @kbd{C-x @key{RET} x} (@code{set-selection-coding-system})
1138 specifies the coding system for sending selected text to other windowing
1139 applications, and for receiving the text of selections made in other
1140 applications. This command applies to all subsequent selections, until
1141 you override it by using the command again. The command @kbd{C-x
1142 @key{RET} X} (@code{set-next-selection-coding-system}) specifies the
1143 coding system for the next selection made in Emacs or read by Emacs.
1145 @vindex x-select-request-type
1146 The variable @code{x-select-request-type} specifies the data type to
1147 request from the X Window System for receiving text selections from
1148 other applications. If the value is @code{nil} (the default), Emacs
1149 tries @code{UTF8_STRING} and @code{COMPOUND_TEXT}, in this order, and
1150 uses various heuristics to choose the more appropriate of the two
1151 results; if none of these succeed, Emacs falls back on @code{STRING}.
1152 If the value of @code{x-select-request-type} is one of the symbols
1153 @code{COMPOUND_TEXT}, @code{UTF8_STRING}, @code{STRING}, or
1154 @code{TEXT}, Emacs uses only that request type. If the value is a
1155 list of some of these symbols, Emacs tries only the request types in
1156 the list, in order, until one of them succeeds, or until the list is
1160 @findex set-buffer-process-coding-system
1161 The command @kbd{C-x @key{RET} p} (@code{set-buffer-process-coding-system})
1162 specifies the coding system for input and output to a subprocess. This
1163 command applies to the current buffer; normally, each subprocess has its
1164 own buffer, and thus you can use this command to specify translation to
1165 and from a particular subprocess by giving the command in the
1166 corresponding buffer.
1168 You can also use @kbd{C-x @key{RET} c}
1169 (@code{universal-coding-system-argument}) just before the command that
1170 runs or starts a subprocess, to specify the coding system for
1171 communicating with that subprocess. @xref{Text Coding}.
1173 The default for translation of process input and output depends on the
1174 current language environment.
1176 @vindex locale-coding-system
1177 @cindex decoding non-@acronym{ASCII} keyboard input on X
1178 The variable @code{locale-coding-system} specifies a coding system
1179 to use when encoding and decoding system strings such as system error
1180 messages and @code{format-time-string} formats and time stamps. That
1181 coding system is also used for decoding non-@acronym{ASCII} keyboard
1182 input on the X Window System and for encoding text sent to the
1183 standard output and error streams when in batch mode. You should
1184 choose a coding system that is compatible
1185 with the underlying system's text representation, which is normally
1186 specified by one of the environment variables @env{LC_ALL},
1187 @env{LC_CTYPE}, and @env{LANG}. (The first one, in the order
1188 specified above, whose value is nonempty is the one that determines
1189 the text representation.)
1191 @node File Name Coding
1192 @section Coding Systems for File Names
1195 @item C-x @key{RET} F @var{coding} @key{RET}
1196 Use coding system @var{coding} for encoding and decoding file
1197 names (@code{set-file-name-coding-system}).
1200 @findex set-file-name-coding-system
1201 @kindex C-x @key{RET} F
1202 @cindex file names with non-@acronym{ASCII} characters
1203 The command @kbd{C-x @key{RET} F} (@code{set-file-name-coding-system})
1204 specifies a coding system to use for encoding file @emph{names}. It
1205 has no effect on reading and writing the @emph{contents} of files.
1207 @vindex file-name-coding-system
1208 In fact, all this command does is set the value of the variable
1209 @code{file-name-coding-system}. If you set the variable to a coding
1210 system name (as a Lisp symbol or a string), Emacs encodes file names
1211 using that coding system for all file operations. This makes it
1212 possible to use non-@acronym{ASCII} characters in file names---or, at
1213 least, those non-@acronym{ASCII} characters that the specified coding
1216 If @code{file-name-coding-system} is @code{nil}, Emacs uses a
1217 default coding system determined by the selected language environment,
1218 and stored in the @code{default-file-name-coding-system} variable.
1219 @c FIXME? Is this correct? What is the "default language environment"?
1220 In the default language environment, non-@acronym{ASCII} characters in
1221 file names are not encoded specially; they appear in the file system
1222 using the internal Emacs representation.
1224 @cindex file-name encoding, MS-Windows
1225 @vindex w32-unicode-filenames
1226 When Emacs runs on MS-Windows versions that are descendants of the
1227 NT family (Windows 2000, XP, Vista, Windows 7, and Windows 8), the
1228 value of @code{file-name-coding-system} is largely ignored, as Emacs
1229 by default uses APIs that allow passing Unicode file names directly.
1230 By contrast, on Windows 9X, file names are encoded using
1231 @code{file-name-coding-system}, which should be set to the codepage
1232 (@pxref{Coding Systems, codepage}) pertinent for the current system
1233 locale. The value of the variable @code{w32-unicode-filenames}
1234 controls whether Emacs uses the Unicode APIs when it calls OS
1235 functions that accept file names. This variable is set by the startup
1236 code to @code{nil} on Windows 9X, and to @code{t} on newer versions of
1239 @strong{Warning:} if you change @code{file-name-coding-system} (or the
1240 language environment) in the middle of an Emacs session, problems can
1241 result if you have already visited files whose names were encoded using
1242 the earlier coding system and cannot be encoded (or are encoded
1243 differently) under the new coding system. If you try to save one of
1244 these buffers under the visited file name, saving may use the wrong file
1245 name, or it may encounter an error. If such a problem happens, use @kbd{C-x
1246 C-w} to specify a new file name for that buffer.
1248 @findex recode-file-name
1249 If a mistake occurs when encoding a file name, use the command
1250 @kbd{M-x recode-file-name} to change the file name's coding
1251 system. This prompts for an existing file name, its old coding
1252 system, and the coding system to which you wish to convert.
1254 @node Terminal Coding
1255 @section Coding Systems for Terminal I/O
1258 @item C-x @key{RET} t @var{coding} @key{RET}
1259 Use coding system @var{coding} for terminal output
1260 (@code{set-terminal-coding-system}).
1262 @item C-x @key{RET} k @var{coding} @key{RET}
1263 Use coding system @var{coding} for keyboard input
1264 (@code{set-keyboard-coding-system}).
1268 @findex set-terminal-coding-system
1269 The command @kbd{C-x @key{RET} t} (@code{set-terminal-coding-system})
1270 specifies the coding system for terminal output. If you specify a
1271 character code for terminal output, all characters output to the
1272 terminal are translated into that coding system.
1274 This feature is useful for certain character-only terminals built to
1275 support specific languages or character sets---for example, European
1276 terminals that support one of the ISO Latin character sets. You need to
1277 specify the terminal coding system when using multibyte text, so that
1278 Emacs knows which characters the terminal can actually handle.
1280 By default, output to the terminal is not translated at all, unless
1281 Emacs can deduce the proper coding system from your terminal type or
1282 your locale specification (@pxref{Language Environments}).
1285 @findex set-keyboard-coding-system
1286 @vindex keyboard-coding-system
1287 The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system}),
1288 or the variable @code{keyboard-coding-system}, specifies the coding
1289 system for keyboard input. Character-code translation of keyboard
1290 input is useful for terminals with keys that send non-@acronym{ASCII}
1291 graphic characters---for example, some terminals designed for ISO
1292 Latin-1 or subsets of it.
1294 By default, keyboard input is translated based on your system locale
1295 setting. If your terminal does not really support the encoding
1296 implied by your locale (for example, if you find it inserts a
1297 non-@acronym{ASCII} character if you type @kbd{M-i}), you will need to set
1298 @code{keyboard-coding-system} to @code{nil} to turn off encoding.
1299 You can do this by putting
1302 (set-keyboard-coding-system nil)
1308 There is a similarity between using a coding system translation for
1309 keyboard input, and using an input method: both define sequences of
1310 keyboard input that translate into single characters. However, input
1311 methods are designed to be convenient for interactive use by humans, and
1312 the sequences that are translated are typically sequences of @acronym{ASCII}
1313 printing characters. Coding systems typically translate sequences of
1314 non-graphic characters.
1320 A font typically defines shapes for a single alphabet or script.
1321 Therefore, displaying the entire range of scripts that Emacs supports
1322 requires a collection of many fonts. In Emacs, such a collection is
1323 called a @dfn{fontset}. A fontset is defined by a list of font specifications,
1324 each assigned to handle a range of character codes, and may fall back
1325 on another fontset for characters that are not covered by the fonts
1328 @cindex fonts for various scripts
1329 @cindex Intlfonts package, installation
1330 Each fontset has a name, like a font. However, while fonts are
1331 stored in the system and the available font names are defined by the
1332 system, fontsets are defined within Emacs itself. Once you have
1333 defined a fontset, you can use it within Emacs by specifying its name,
1334 anywhere that you could use a single font. Of course, Emacs fontsets
1335 can use only the fonts that the system supports. If some characters
1336 appear on the screen as empty boxes or hex codes, this means that the
1337 fontset in use for them has no font for those characters. In this
1338 case, or if the characters are shown, but not as well as you would
1339 like, you may need to install extra fonts. Your operating system may
1340 have optional fonts that you can install; or you can install the GNU
1341 Intlfonts package, which includes fonts for most supported
1342 scripts.@footnote{If you run Emacs on X, you may need to inform the X
1343 server about the location of the newly installed fonts with commands
1345 @c FIXME? I feel like this may be out of date.
1346 @c E.g., the intlfonts tarfile is ~ 10 years old.
1349 xset fp+ /usr/local/share/emacs/fonts
1354 Emacs creates three fontsets automatically: the @dfn{standard
1355 fontset}, the @dfn{startup fontset} and the @dfn{default fontset}.
1356 @c FIXME? The doc of *standard*-fontset-spec says:
1357 @c "You have the biggest chance to display international characters
1358 @c with correct glyphs by using the *standard* fontset." (my emphasis)
1359 @c See http://lists.gnu.org/archive/html/emacs-devel/2012-04/msg00430.html
1360 The default fontset is most likely to have fonts for a wide variety of
1361 non-@acronym{ASCII} characters, and is the default fallback for the
1362 other two fontsets, and if you set a default font rather than fontset.
1363 However, it does not specify font family names, so results can be
1364 somewhat random if you use it directly. You can specify use of a
1365 particular fontset by starting Emacs with the @samp{-fn} option.
1369 emacs -fn fontset-standard
1373 You can also specify a fontset with the @samp{Font} resource (@pxref{X
1376 If no fontset is specified for use, then Emacs uses an
1377 @acronym{ASCII} font, with @samp{fontset-default} as a fallback for
1378 characters the font does not cover. The standard fontset is only used if
1379 explicitly requested, despite its name.
1381 @findex describe-fontset
1382 To show the information about a specific fontset, use the
1383 @w{@kbd{M-x describe-fontset}} command. It prompts for a fontset
1384 name, defaulting to the one used by the current frame, and then
1385 displays all the subranges of characters and the fonts assigned to
1386 them in that fontset.
1388 A fontset does not necessarily specify a font for every character
1389 code. If a fontset specifies no font for a certain character, or if
1390 it specifies a font that does not exist on your system, then it cannot
1391 display that character properly. It will display that character as a
1392 hex code or thin space or an empty box instead. (@xref{Text Display, ,
1393 glyphless characters}, for details.)
1395 @node Defining Fontsets
1396 @section Defining fontsets
1398 @vindex standard-fontset-spec
1399 @vindex w32-standard-fontset-spec
1400 @vindex ns-standard-fontset-spec
1401 @cindex standard fontset
1402 When running on X, Emacs creates a standard fontset automatically according to the value
1403 of @code{standard-fontset-spec}. This fontset's name is
1406 -*-fixed-medium-r-normal-*-16-*-*-*-*-*-fontset-standard
1410 or just @samp{fontset-standard} for short.
1412 On GNUstep and macOS, the standard fontset is created using the value of
1413 @code{ns-standard-fontset-spec}, and on MS Windows it is
1414 created using the value of @code{w32-standard-fontset-spec}.
1416 @c FIXME? How does one access these, or do anything with them?
1418 Bold, italic, and bold-italic variants of the standard fontset are
1419 created automatically. Their names have @samp{bold} instead of
1420 @samp{medium}, or @samp{i} instead of @samp{r}, or both.
1422 @cindex startup fontset
1423 Emacs generates a fontset automatically, based on any default
1424 @acronym{ASCII} font that you specify with the @samp{Font} resource or
1425 the @samp{-fn} argument, or the default font that Emacs found when it
1426 started. This is the @dfn{startup fontset} and its name is
1427 @code{fontset-startup}. It does this by replacing the
1428 @var{charset_registry} field with @samp{fontset}, and replacing
1429 @var{charset_encoding} field with @samp{startup}, then using the
1430 resulting string to specify a fontset.
1432 For instance, if you start Emacs with a font of this form,
1434 @c FIXME? I think this is a little misleading, because you cannot (?)
1435 @c actually specify a font with wildcards, it has to be a complete spec.
1436 @c Also, an X font specification of this form hasn't (?) been
1437 @c mentioned before now, and is somewhat obsolete these days.
1438 @c People are more likely to use a form like
1439 @c emacs -fn "DejaVu Sans Mono-12"
1440 @c How does any of this apply in that case?
1442 emacs -fn "*courier-medium-r-normal--14-140-*-iso8859-1"
1446 Emacs generates the following fontset and uses it for the initial X
1450 -*-courier-medium-r-normal-*-14-140-*-*-*-*-fontset-startup
1453 The startup fontset will use the font that you specify, or a variant
1454 with a different registry and encoding, for all the characters that
1455 are supported by that font, and fallback on @samp{fontset-default} for
1458 With the X resource @samp{Emacs.Font}, you can specify a fontset name
1459 just like an actual font name. But be careful not to specify a fontset
1460 name in a wildcard resource like @samp{Emacs*Font}---that wildcard
1461 specification matches various other resources, such as for menus, and
1462 @c FIXME is this still true?
1463 menus cannot handle fontsets. @xref{X Resources}.
1465 You can specify additional fontsets using X resources named
1466 @samp{Fontset-@var{n}}, where @var{n} is an integer starting from 0.
1467 The resource value should have this form:
1470 @var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}}
1474 @var{fontpattern} should have the form of a standard X font name (see
1475 the previous fontset-startup example), except
1476 for the last two fields. They should have the form
1477 @samp{fontset-@var{alias}}.
1479 The fontset has two names, one long and one short. The long name is
1480 @var{fontpattern}. The short name is @samp{fontset-@var{alias}}. You
1481 can refer to the fontset by either name.
1483 The construct @samp{@var{charset}:@var{font}} specifies which font to
1484 use (in this fontset) for one particular character set. Here,
1485 @var{charset} is the name of a character set, and @var{font} is the
1486 font to use for that character set. You can use this construct any
1487 number of times in defining one fontset.
1489 For the other character sets, Emacs chooses a font based on
1490 @var{fontpattern}. It replaces @samp{fontset-@var{alias}} with values
1491 that describe the character set. For the @acronym{ASCII} character font,
1492 @samp{fontset-@var{alias}} is replaced with @samp{ISO8859-1}.
1494 In addition, when several consecutive fields are wildcards, Emacs
1495 collapses them into a single wildcard. This is to prevent use of
1496 auto-scaled fonts. Fonts made by scaling larger fonts are not usable
1497 for editing, and scaling a smaller font is not also useful, because it is
1498 better to use the smaller font in its own size, which is what Emacs
1501 Thus if @var{fontpattern} is this,
1504 -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
1508 the font specification for @acronym{ASCII} characters would be this:
1511 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
1515 and the font specification for Chinese GB2312 characters would be this:
1518 -*-fixed-medium-r-normal-*-24-*-gb2312*-*
1521 You may not have any Chinese font matching the above font
1522 specification. Most X distributions include only Chinese fonts that
1523 have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In
1524 such a case, @samp{Fontset-@var{n}} can be specified as:
1527 Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
1528 chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
1532 Then, the font specifications for all but Chinese GB2312 characters have
1533 @samp{fixed} in the @var{family} field, and the font specification for
1534 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
1537 @findex create-fontset-from-fontset-spec
1538 The function that processes the fontset resource value to create the
1539 fontset is called @code{create-fontset-from-fontset-spec}. You can also
1540 call this function explicitly to create a fontset.
1542 @xref{Fonts}, for more information about font naming.
1544 @node Modifying Fontsets
1545 @section Modifying Fontsets
1546 @cindex fontsets, modifying
1547 @findex set-fontset-font
1549 Fontsets do not always have to be created from scratch. If only
1550 minor changes are required it may be easier to modify an existing
1551 fontset. Modifying @samp{fontset-default} will also affect other
1552 fontsets that use it as a fallback, so can be an effective way of
1553 fixing problems with the fonts that Emacs chooses for a particular
1556 Fontsets can be modified using the function @code{set-fontset-font},
1557 specifying a character, a charset, a script, or a range of characters
1558 to modify the font for, and a font specification for the font to be
1559 used. Some examples are:
1562 ;; Use Liberation Mono for latin-3 charset.
1563 (set-fontset-font "fontset-default" 'iso-8859-3
1566 ;; Prefer a big5 font for han characters
1567 (set-fontset-font "fontset-default"
1568 'han (font-spec :registry "big5")
1571 ;; Use DejaVu Sans Mono as a fallback in fontset-startup
1572 ;; before resorting to fontset-default.
1573 (set-fontset-font "fontset-startup" nil "DejaVu Sans Mono"
1576 ;; Use MyPrivateFont for the Unicode private use area.
1577 (set-fontset-font "fontset-default" '(#xe000 . #xf8ff)
1583 @cindex fonts, how to ignore
1584 @vindex face-ignored-fonts
1585 Some fonts installed on your system might be broken, or produce
1586 unpleasant results for characters for which they are used, and you may
1587 wish to instruct Emacs to completely ignore them while searching for a
1588 suitable font required to display a character. You can do that by
1589 adding the offending fonts to the value of @code{face-ignored-fonts}
1590 variable, which is a list. Here's an example to put in your
1594 (add-to-list 'face-ignored-fonts "Some Bad Font")
1597 @node Undisplayable Characters
1598 @section Undisplayable Characters
1600 There may be some non-@acronym{ASCII} characters that your
1601 terminal cannot display. Most text terminals support just a single
1602 character set (use the variable @code{default-terminal-coding-system}
1603 to tell Emacs which one, @ref{Terminal Coding}); characters that
1604 can't be encoded in that coding system are displayed as @samp{?} by
1607 Graphical displays can display a broader range of characters, but
1608 you may not have fonts installed for all of them; characters that have
1609 no font appear as a hollow box.
1611 If you use Latin-1 characters but your terminal can't display
1612 Latin-1, you can arrange to display mnemonic @acronym{ASCII} sequences
1613 instead, e.g., @samp{"o} for o-umlaut. Load the library
1614 @file{iso-ascii} to do this.
1616 @vindex latin1-display
1617 If your terminal can display Latin-1, you can display characters
1618 from other European character sets using a mixture of equivalent
1619 Latin-1 characters and @acronym{ASCII} mnemonics. Customize the variable
1620 @code{latin1-display} to enable this. The mnemonic @acronym{ASCII}
1621 sequences mostly correspond to those of the prefix input methods.
1624 @section Unibyte Editing Mode
1626 @cindex European character sets
1627 @cindex accented characters
1628 @cindex ISO Latin character sets
1629 @cindex Unibyte operation
1630 The ISO 8859 Latin-@var{n} character sets define character codes in
1631 the range 0240 to 0377 octal (160 to 255 decimal) to handle the
1632 accented letters and punctuation needed by various European languages
1633 (and some non-European ones). Note that Emacs considers bytes with
1634 codes in this range as raw bytes, not as characters, even in a unibyte
1635 buffer, i.e., if you disable multibyte characters. However, Emacs can
1636 still handle these character codes as if they belonged to @emph{one}
1637 of the single-byte character sets at a time. To specify @emph{which}
1638 of these codes to use, invoke @kbd{M-x set-language-environment} and
1639 specify a suitable language environment such as @samp{Latin-@var{n}}.
1640 @xref{Disabling Multibyte, , Disabling Multibyte Characters, elisp,
1641 GNU Emacs Lisp Reference Manual}.
1643 @vindex unibyte-display-via-language-environment
1644 Emacs can also display bytes in the range 160 to 255 as readable
1645 characters, provided the terminal or font in use supports them. This
1646 works automatically. On a graphical display, Emacs can also display
1647 single-byte characters through fontsets, in effect by displaying the
1648 equivalent multibyte characters according to the current language
1649 environment. To request this, set the variable
1650 @code{unibyte-display-via-language-environment} to a non-@code{nil}
1651 value. Note that setting this only affects how these bytes are
1652 displayed, but does not change the fundamental fact that Emacs treats
1653 them as raw bytes, not as characters.
1655 @cindex @code{iso-ascii} library
1656 If your terminal does not support display of the Latin-1 character
1657 set, Emacs can display these characters as @acronym{ASCII} sequences which at
1658 least give you a clear idea of what the characters are. To do this,
1659 load the library @code{iso-ascii}. Similar libraries for other
1660 Latin-@var{n} character sets could be implemented, but have not been
1663 @findex standard-display-8bit
1664 @cindex 8-bit display
1665 Normally non-ISO-8859 characters (decimal codes between 128 and 159
1666 inclusive) are displayed as octal escapes. You can change this for
1667 non-standard extended versions of ISO-8859 character sets by using the
1668 function @code{standard-display-8bit} in the @code{disp-table} library.
1670 There are two ways to input single-byte non-@acronym{ASCII}
1676 You can use an input method for the selected language environment.
1677 @xref{Input Methods}. When you use an input method in a unibyte buffer,
1678 the non-@acronym{ASCII} character you specify with it is converted to unibyte.
1681 If your keyboard can generate character codes 128 (decimal) and up,
1682 representing non-@acronym{ASCII} characters, you can type those character codes
1685 On a graphical display, you should not need to do anything special to
1686 use these keys; they should simply work. On a text terminal, you
1687 should use the command @code{M-x set-keyboard-coding-system} or customize the
1688 variable @code{keyboard-coding-system} to specify which coding system
1689 your keyboard uses (@pxref{Terminal Coding}). Enabling this feature
1690 will probably require you to use @key{ESC} to type Meta characters;
1691 however, on a console terminal or in @code{xterm}, you can arrange for
1692 Meta to be converted to @key{ESC} and still be able type 8-bit
1693 characters present directly on the keyboard or using @key{Compose} or
1694 @key{AltGr} keys. @xref{User Input}.
1697 @cindex @code{iso-transl} library
1698 @cindex compose character
1699 @cindex dead character
1701 You can use the key @kbd{C-x 8} as a compose-character prefix for
1702 entry of non-@acronym{ASCII} Latin-1 and a few other printing
1703 characters. @kbd{C-x 8} is good for insertion (in the minibuffer as
1704 well as other buffers), for searching, and in any other context where
1705 a key sequence is allowed.
1707 @kbd{C-x 8} works by loading the @code{iso-transl} library. Once that
1708 library is loaded, the @key{Alt} modifier key, if the keyboard has
1709 one, serves the same purpose as @kbd{C-x 8}: use @key{Alt} together
1710 with an accent character to modify the following letter. In addition,
1711 if the keyboard has keys for the Latin-1 dead accent characters,
1712 they too are defined to compose with the following character, once
1713 @code{iso-transl} is loaded.
1715 Use @kbd{C-x 8 C-h} to list all the available @kbd{C-x 8} translations.
1722 In Emacs, @dfn{charset} is short for ``character set''. Emacs
1723 supports most popular charsets (such as @code{ascii},
1724 @code{iso-8859-1}, @code{cp1250}, @code{big5}, and @code{unicode}), in
1725 addition to some charsets of its own (such as @code{emacs},
1726 @code{unicode-bmp}, and @code{eight-bit}). All supported characters
1727 belong to one or more charsets.
1729 Emacs normally does the right thing with respect to charsets, so
1730 that you don't have to worry about them. However, it is sometimes
1731 helpful to know some of the underlying details about charsets.
1733 One example is font selection (@pxref{Fonts}). Each language
1734 environment (@pxref{Language Environments}) defines a priority
1735 list for the various charsets. When searching for a font, Emacs
1736 initially attempts to find one that can display the highest-priority
1737 charsets. For instance, in the Japanese language environment, the
1738 charset @code{japanese-jisx0208} has the highest priority, so Emacs
1739 tries to use a font whose @code{registry} property is
1740 @samp{JISX0208.1983-0}.
1742 @findex list-charset-chars
1743 @cindex characters in a certain charset
1744 @findex describe-character-set
1745 There are two commands that can be used to obtain information about
1746 charsets. The command @kbd{M-x list-charset-chars} prompts for a
1747 charset name, and displays all the characters in that character set.
1748 The command @kbd{M-x describe-character-set} prompts for a charset
1749 name, and displays information about that charset, including its
1750 internal representation within Emacs.
1752 @findex list-character-sets
1753 @kbd{M-x list-character-sets} displays a list of all supported
1754 charsets. The list gives the names of charsets and additional
1755 information to identity each charset; for more details, see the
1756 @url{https://www.itscj.ipsj.or.jp/itscj_english/iso-ir/ISO-IR.pdf,
1757 ISO International Register of Coded Character Sets to be Used with
1758 Escape Sequences (ISO-IR)} maintained by
1759 the @url{https://www.itscj.ipsj.or.jp/itscj_english/,
1760 Information Processing Society of Japan/Information Technology
1761 Standards Commission of Japan (IPSJ/ITSCJ)}. In this list,
1762 charsets are divided into two categories: @dfn{normal charsets} are
1763 listed first, followed by @dfn{supplementary charsets}. A
1764 supplementary charset is one that is used to define another charset
1765 (as a parent or a subset), or to provide backward-compatibility for
1766 older Emacs versions.
1768 To find out which charset a character in the buffer belongs to, put
1769 point before it and type @kbd{C-u C-x =} (@pxref{International
1772 @node Bidirectional Editing
1773 @section Bidirectional Editing
1774 @cindex bidirectional editing
1775 @cindex right-to-left text
1777 Emacs supports editing text written in scripts, such as Arabic and
1778 Hebrew, whose natural ordering of horizontal text for display is from
1779 right to left. However, digits and Latin text embedded in these
1780 scripts are still displayed left to right. It is also not uncommon to
1781 have small portions of text in Arabic or Hebrew embedded in an otherwise
1782 Latin document; e.g., as comments and strings in a program source
1783 file. For these reasons, text that uses these scripts is actually
1784 @dfn{bidirectional}: a mixture of runs of left-to-right and
1785 right-to-left characters.
1787 This section describes the facilities and options provided by Emacs
1788 for editing bidirectional text.
1790 @cindex logical order
1791 @cindex visual order
1792 Emacs stores right-to-left and bidirectional text in the so-called
1793 @dfn{logical} (or @dfn{reading}) order: the buffer or string position
1794 of the first character you read precedes that of the next character.
1795 Reordering of bidirectional text into the @dfn{visual} order happens
1796 at display time. As result, character positions no longer increase
1797 monotonically with their positions on display. Emacs implements the
1798 Unicode Bidirectional Algorithm (UBA) described in the Unicode
1799 Standard Annex #9, for reordering of bidirectional text for display.
1800 It deviates from the UBA only in how continuation lines are displayed
1801 when text direction is opposite to the base paragraph direction,
1802 e.g. when a long line of English text appears in a right-to-left
1805 @vindex bidi-display-reordering
1806 The buffer-local variable @code{bidi-display-reordering} controls
1807 whether text in the buffer is reordered for display. If its value is
1808 non-@code{nil}, Emacs reorders characters that have right-to-left
1809 directionality when they are displayed. The default value is
1812 @cindex base direction of paragraphs
1813 @cindex paragraph, base direction
1814 Each paragraph of bidirectional text can have its own @dfn{base
1815 direction}, either right-to-left or left-to-right. (Paragraph
1816 @c paragraph-separate etc have no influence on this?
1817 boundaries are empty lines, i.e., lines consisting entirely of
1818 whitespace characters.) Text in left-to-right paragraphs begins on
1819 the screen at the left margin of the window and is truncated or
1820 continued when it reaches the right margin. By contrast, text in
1821 right-to-left paragraphs is displayed starting at the right margin and
1822 is continued or truncated at the left margin.
1824 @vindex bidi-paragraph-direction
1825 Emacs determines the base direction of each paragraph dynamically,
1826 based on the text at the beginning of the paragraph. However,
1827 sometimes a buffer may need to force a certain base direction for its
1828 paragraphs. The variable @code{bidi-paragraph-direction}, if
1829 non-@code{nil}, disables the dynamic determination of the base
1830 direction, and instead forces all paragraphs in the buffer to have the
1831 direction specified by its buffer-local value. The value can be either
1832 @code{right-to-left} or @code{left-to-right}. Any other value is
1833 interpreted as @code{nil}.
1837 Alternatively, you can control the base direction of a paragraph by
1838 inserting special formatting characters in front of the paragraph.
1839 The special character @code{RIGHT-TO-LEFT MARK}, or @sc{rlm}, forces
1840 the right-to-left direction on the following paragraph, while
1841 @code{LEFT-TO-RIGHT MARK}, or @sc{lrm} forces the left-to-right
1842 direction. (You can use @kbd{C-x 8 @key{RET}} to insert these characters.)
1843 In a GUI session, the @sc{lrm} and @sc{rlm} characters display as very
1844 thin blank characters; on text terminals they display as blanks.
1846 Because characters are reordered for display, Emacs commands that
1847 operate in the logical order or on stretches of buffer positions may
1848 produce unusual effects. For example, @kbd{C-f} and @kbd{C-b}
1849 commands move point in the logical order, so the cursor will sometimes
1850 jump when point traverses reordered bidirectional text. Similarly, a
1851 highlighted region covering a contiguous range of character positions
1852 may look discontinuous if the region spans reordered text. This is
1853 normal and similar to the behavior of other programs that support
1854 bidirectional text. If you set @code{visual-order-cursor-movement} to
1855 a non-@code{nil} value, cursor motion by the arrow keys follows the
1856 visual order on screen (@pxref{Moving Point, visual-order movement}).