1 @c -*- coding: utf-8 -*-
2 @c This is part of the Emacs manual.
3 @c Copyright (C) 1997, 1999-2018 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
16 Emacs supports a wide variety of international character sets,
17 including European and Vietnamese variants of the Latin alphabet, as
18 well as Arabic scripts, Brahmic scripts (for languages such as
19 Bengali, Hindi, and Thai), Cyrillic, Ethiopic, Georgian, Greek, Han
20 (for Chinese and Japanese), Hangul (for Korean), Hebrew and IPA@.
21 Emacs also supports various encodings of these characters that are used by
22 other internationalized software, such as word processors and mailers.
24 Emacs allows editing text with international characters by supporting
25 all the related activities:
29 You can visit files with non-@acronym{ASCII} characters, save non-@acronym{ASCII} text, and
30 pass non-@acronym{ASCII} text between Emacs and programs it invokes (such as
31 compilers, spell-checkers, and mailers). Setting your language
32 environment (@pxref{Language Environments}) takes care of setting up the
33 coding systems and other options for a specific language or culture.
34 Alternatively, you can specify how Emacs should encode or decode text
35 for each command; see @ref{Text Coding}.
38 You can display non-@acronym{ASCII} characters encoded by the various
39 scripts. This works by using appropriate fonts on graphics displays
40 (@pxref{Defining Fontsets}), and by sending special codes to text
41 displays (@pxref{Terminal Coding}). If some characters are displayed
42 incorrectly, refer to @ref{Undisplayable Characters}, which describes
43 possible problems and explains how to solve them.
46 Characters from scripts whose natural ordering of text is from right
47 to left are reordered for display (@pxref{Bidirectional Editing}).
48 These scripts include Arabic, Hebrew, Syriac, Thaana, and a few
52 You can insert non-@acronym{ASCII} characters or search for them. To do that,
53 you can specify an input method (@pxref{Select Input Method}) suitable
54 for your language, or use the default input method set up when you chose
55 your language environment. If
56 your keyboard can produce non-@acronym{ASCII} characters, you can select an
57 appropriate keyboard coding system (@pxref{Terminal Coding}), and Emacs
58 will accept those characters. Latin-1 characters can also be input by
59 using the @kbd{C-x 8} prefix, see @ref{Unibyte Mode}.
61 With the X Window System, your locale should be set to an appropriate
62 value to make sure Emacs interprets keyboard input correctly; see
63 @ref{Language Environments, locales}.
66 The rest of this chapter describes these issues in detail.
69 * International Chars:: Basic concepts of multibyte characters.
70 * Language Environments:: Setting things up for the language you use.
71 * Input Methods:: Entering text characters not on your keyboard.
72 * Select Input Method:: Specifying your choice of input methods.
73 * Coding Systems:: Character set conversion when you read and
74 write files, and so on.
75 * Recognize Coding:: How Emacs figures out which conversion to use.
76 * Specify Coding:: Specifying a file's coding system explicitly.
77 * Output Coding:: Choosing coding systems for output.
78 * Text Coding:: Choosing conversion to use for file text.
79 * Communication Coding:: Coding systems for interprocess communication.
80 * File Name Coding:: Coding systems for file @emph{names}.
81 * Terminal Coding:: Specifying coding systems for converting
82 terminal input and output.
83 * Fontsets:: Fontsets are collections of fonts
84 that cover the whole spectrum of characters.
85 * Defining Fontsets:: Defining a new fontset.
86 * Modifying Fontsets:: Modifying an existing fontset.
87 * Undisplayable Characters:: When characters don't display.
88 * Unibyte Mode:: You can pick one European character set
89 to use without multibyte characters.
90 * Charsets:: How Emacs groups its internal character codes.
91 * Bidirectional Editing:: Support for right-to-left scripts.
94 @node International Chars
95 @section Introduction to International Character Sets
97 The users of international character sets and scripts have
98 established many more-or-less standard coding systems for storing
99 files. These coding systems are typically @dfn{multibyte}, meaning
100 that sequences of two or more bytes are used to represent individual
101 non-@acronym{ASCII} characters.
104 Internally, Emacs uses its own multibyte character encoding, which
105 is a superset of the @dfn{Unicode} standard. This internal encoding
106 allows characters from almost every known script to be intermixed in a
107 single buffer or string. Emacs translates between the multibyte
108 character encoding and various other coding systems when reading and
109 writing files, and when exchanging data with subprocesses.
112 @findex view-hello-file
113 @cindex undisplayable characters
114 @cindex @samp{?} in display
115 The command @kbd{C-h h} (@code{view-hello-file}) displays the file
116 @file{etc/HELLO}, which illustrates various scripts by showing
117 how to say ``hello'' in many languages. If some characters can't be
118 displayed on your terminal, they appear as @samp{?} or as hollow boxes
119 (@pxref{Undisplayable Characters}).
121 Keyboards, even in the countries where these character sets are
122 used, generally don't have keys for all the characters in them. You
123 can insert characters that your keyboard does not support, using
124 @kbd{C-x 8 @key{RET}} (@code{insert-char}). @xref{Inserting Text}.
125 Shorthands are available for some common characters; for example, you
126 can insert a left single quotation mark @t{‘} by typing @kbd{C-x 8
127 [}, or in Electric Quote mode, usually by simply typing @kbd{`}.
128 @xref{Quotation Marks}. Emacs also supports
129 various @dfn{input methods}, typically one for each script or
130 language, which make it easier to type characters in the script.
131 @xref{Input Methods}.
134 The prefix key @kbd{C-x @key{RET}} is used for commands that pertain
135 to multibyte characters, coding systems, and input methods.
137 @kindex C-x =@r{, and international characters}
138 @findex what-cursor-position@r{, and international characters}
139 The command @kbd{C-x =} (@code{what-cursor-position}) shows
140 information about the character at point. In addition to the
141 character position, which was described in @ref{Position Info}, this
142 command displays how the character is encoded. For instance, it
143 displays the following line in the echo area for the character
147 Char: c (99, #o143, #x63) point=28062 of 36168 (78%) column=53
150 The four values after @samp{Char:} describe the character that
151 follows point, first by showing it and then by giving its character
152 code in decimal, octal and hex. For a non-@acronym{ASCII} multibyte
153 character, these are followed by @samp{file} and the character's
154 representation, in hex, in the buffer's coding system, if that coding
155 system encodes the character safely and with a single byte
156 (@pxref{Coding Systems}). If the character's encoding is longer than
157 one byte, Emacs shows @samp{file ...}.
159 As a special case, if the character lies in the range 128 (0200
160 octal) through 159 (0237 octal), it stands for a raw byte that
161 does not correspond to any specific displayable character. Such a
162 character lies within the @code{eight-bit-control} character set,
163 and is displayed as an escaped octal character code. In this case,
164 @kbd{C-x =} shows @samp{part of display ...} instead of @samp{file}.
166 @cindex character set of character at point
167 @cindex font of character at point
168 @cindex text properties at point
169 @cindex face at point
170 With a prefix argument (@kbd{C-u C-x =}), this command displays a
171 detailed description of the character in a window:
175 The character set name, and the codes that identify the character
176 within that character set; @acronym{ASCII} characters are identified
177 as belonging to the @code{ascii} character set.
180 The character's script, syntax and categories.
183 What keys to type to input the character in the current input method
184 (if it supports the character).
187 The character's encodings, both internally in the buffer, and externally
188 if you were to save the file.
191 If you are running Emacs on a graphical display, the font name and
192 glyph code for the character. If you are running Emacs on a text
193 terminal, the code(s) sent to the terminal.
196 The character's text properties (@pxref{Text Properties,,,
197 elisp, the Emacs Lisp Reference Manual}), including any non-default
198 faces used to display the character, and any overlays containing it
199 (@pxref{Overlays,,, elisp, the same manual}).
202 Here's an example, with some lines folded to fit into this manual:
205 position: 1 of 1 (0%), column: 0
206 character: ê (displayed as ê) (codepoint 234, #o352, #xea)
207 preferred charset: unicode (Unicode (ISO10646))
208 code point in charset: 0xEA
210 syntax: w which means: word
211 category: .:Base, L:Left-to-right (strong), c:Chinese,
212 j:Japanese, l:Latin, v:Viet
213 to input: type "C-x 8 RET ea" or
214 "C-x 8 RET LATIN SMALL LETTER E WITH CIRCUMFLEX"
215 buffer code: #xC3 #xAA
216 file code: #xC3 #xAA (encoded by coding system utf-8-unix)
217 display: by this font (glyph code)
218 xft:-PfEd-DejaVu Sans Mono-normal-normal-
219 normal-*-15-*-*-*-m-0-iso10646-1 (#xAC)
221 Character code properties: customize what to show
222 name: LATIN SMALL LETTER E WITH CIRCUMFLEX
223 old-name: LATIN SMALL LETTER E CIRCUMFLEX
224 general-category: Ll (Letter, Lowercase)
225 decomposition: (101 770) ('e' '^')
228 @node Language Environments
229 @section Language Environments
230 @cindex language environments
232 All supported character sets are supported in Emacs buffers whenever
233 multibyte characters are enabled; there is no need to select a
234 particular language in order to display its characters.
235 However, it is important to select a @dfn{language
236 environment} in order to set various defaults. Roughly speaking, the
237 language environment represents a choice of preferred script rather
238 than a choice of language.
240 The language environment controls which coding systems to recognize
241 when reading text (@pxref{Recognize Coding}). This applies to files,
242 incoming mail, and any other text you read into Emacs. It may also
243 specify the default coding system to use when you create a file. Each
244 language environment also specifies a default input method.
246 @findex set-language-environment
247 @vindex current-language-environment
248 To select a language environment, customize
249 @code{current-language-environment} or use the command @kbd{M-x
250 set-language-environment}. It makes no difference which buffer is
251 current when you use this command, because the effects apply globally
252 to the Emacs session. See the variable @code{language-info-alist} for
253 the list of supported language environments, and use the command
254 @kbd{C-h L @var{lang-env} @key{RET}} (@code{describe-language-environment})
255 for more information about the language environment @var{lang-env}.
256 Supported language environments include:
258 @c @cindex entries below are split between portions of the list to
259 @c make them more accurate, i.e., land on the line that mentions the
260 @c language. However, makeinfo 4.x doesn't fill inside @quotation
261 @c lines that follow a @cindex entry and whose text has no whitespace.
262 @c To work around, we group the language environments together, so
263 @c that the blank that separates them triggers refill.
265 @cindex ASCII (language environment)
271 @cindex Brazilian Portuguese
273 Brazilian Portuguese, Bulgarian,
278 Chinese-BIG5, Chinese-CNS, Chinese-EUC-TW, Chinese-GB,
279 Chinese-GB18030, Chinese-GBK,
282 Croatian, Cyrillic-ALT, Cyrillic-ISO, Cyrillic-KOI8,
298 German, Greek, Gujarati,
312 Latin-1, Latin-2, Latin-3, Latin-4, Latin-5, Latin-6, Latin-7,
332 Slovak, Slovenian, Spanish,
355 To display the script(s) used by your language environment on a
356 graphical display, you need to have suitable 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}. (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 (the former overrides the latter),
372 and selects the corresponding language environment if a match is found.
373 It also adjusts the display
374 table and terminal coding system, the locale coding system, the
375 preferred coding system as needed for the locale, and---last but not
376 least---the way Emacs decodes non-@acronym{ASCII} characters sent by your keyboard.
378 @c This seems unlikely, doesn't it?
379 If you modify the @env{LC_ALL}, @env{LC_CTYPE}, or @env{LANG}
380 environment variables while running Emacs (by using @kbd{M-x setenv}),
381 you may want to invoke the @code{set-locale-environment}
382 command afterwards to readjust the language environment from the new
385 @vindex locale-preferred-coding-systems
386 The @code{set-locale-environment} function normally uses the preferred
387 coding system established by the language environment to decode system
388 messages. But if your locale matches an entry in the variable
389 @code{locale-preferred-coding-systems}, Emacs uses the corresponding
390 coding system instead. For example, if the locale @samp{ja_JP.PCK}
391 matches @code{japanese-shift-jis} in
392 @code{locale-preferred-coding-systems}, Emacs uses that encoding even
393 though it might normally use @code{japanese-iso-8bit}.
395 You can override the language environment chosen at startup with
396 explicit use of the command @code{set-language-environment}, or with
397 customization of @code{current-language-environment} in your init
401 @findex describe-language-environment
402 To display information about the effects of a certain language
403 environment @var{lang-env}, use the command @kbd{C-h L @var{lang-env}
404 @key{RET}} (@code{describe-language-environment}). This tells you
405 which languages this language environment is useful for, and lists the
406 character sets, coding systems, and input methods that go with it. It
407 also shows some sample text to illustrate scripts used in this
408 language environment. If you give an empty input for @var{lang-env},
409 this command describes the chosen language environment.
411 @vindex set-language-environment-hook
412 You can customize any language environment with the normal hook
413 @code{set-language-environment-hook}. The command
414 @code{set-language-environment} runs that hook after setting up the new
415 language environment. The hook functions can test for a specific
416 language environment by checking the variable
417 @code{current-language-environment}. This hook is where you should
418 put non-default settings for specific language environments, such as
419 coding systems for keyboard input and terminal output, the default
422 @vindex exit-language-environment-hook
423 Before it starts to set up the new language environment,
424 @code{set-language-environment} first runs the hook
425 @code{exit-language-environment-hook}. This hook is useful for undoing
426 customizations that were made with @code{set-language-environment-hook}.
427 For instance, if you set up a special key binding in a specific language
428 environment using @code{set-language-environment-hook}, you should set
429 up @code{exit-language-environment-hook} to restore the normal binding
433 @section Input Methods
435 @cindex input methods
436 An @dfn{input method} is a kind of character conversion designed
437 specifically for interactive input. In Emacs, typically each language
438 has its own input method; sometimes several languages that use the same
439 characters can share one input method. A few languages support several
442 The simplest kind of input method works by mapping @acronym{ASCII} letters
443 into another alphabet; this allows you to use one other alphabet
444 instead of @acronym{ASCII}. The Greek and Russian input methods
447 A more powerful technique is composition: converting sequences of
448 characters into one letter. Many European input methods use composition
449 to produce a single non-@acronym{ASCII} letter from a sequence that consists of a
450 letter followed by accent characters (or vice versa). For example, some
451 methods convert the sequence @kbd{o ^} into a single accented letter.
452 These input methods have no special commands of their own; all they do
453 is compose sequences of printing characters.
455 The input methods for syllabic scripts typically use mapping followed
456 by composition. The input methods for Thai and Korean work this way.
457 First, letters are mapped into symbols for particular sounds or tone
458 marks; then, sequences of these that make up a whole syllable are
459 mapped into one syllable sign.
461 Chinese and Japanese require more complex methods. In Chinese input
462 methods, first you enter the phonetic spelling of a Chinese word (in
463 input method @code{chinese-py}, among others), or a sequence of
464 portions of the character (input methods @code{chinese-4corner} and
465 @code{chinese-sw}, and others). One input sequence typically
466 corresponds to many possible Chinese characters. You select the one
467 you mean using keys such as @kbd{C-f}, @kbd{C-b}, @kbd{C-n},
468 @kbd{C-p} (or the arrow keys), and digits, which have special meanings
471 The possible characters are conceptually arranged in several rows,
472 with each row holding up to 10 alternatives. Normally, Emacs displays
473 just one row at a time, in the echo area; @code{(@var{i}/@var{j})}
474 appears at the beginning, to indicate that this is the @var{i}th row
475 out of a total of @var{j} rows. Type @kbd{C-n} or @kbd{C-p} to
476 display the next row or the previous row.
478 Type @kbd{C-f} and @kbd{C-b} to move forward and backward among
479 the alternatives in the current row. As you do this, Emacs highlights
480 the current alternative with a special color; type @kbd{C-@key{SPC}}
481 to select the current alternative and use it as input. The
482 alternatives in the row are also numbered; the number appears before
483 the alternative. Typing a number selects the associated alternative
484 of the current row and uses it as input.
486 @key{TAB} in these Chinese input methods displays a buffer showing
487 all the possible characters at once; then clicking @kbd{mouse-2} on
488 one of them selects that alternative. The keys @kbd{C-f}, @kbd{C-b},
489 @kbd{C-n}, @kbd{C-p}, and digits continue to work as usual, but they
490 do the highlighting in the buffer showing the possible characters,
491 rather than in the echo area.
493 In Japanese input methods, first you input a whole word using
494 phonetic spelling; then, after the word is in the buffer, Emacs
495 converts it into one or more characters using a large dictionary. One
496 phonetic spelling corresponds to a number of different Japanese words;
497 to select one of them, use @kbd{C-n} and @kbd{C-p} to cycle through
500 Sometimes it is useful to cut off input method processing so that the
501 characters you have just entered will not combine with subsequent
502 characters. For example, in input method @code{latin-1-postfix}, the
503 sequence @kbd{o ^} combines to form an @samp{o} with an accent. What if
504 you want to enter them as separate characters?
506 One way is to type the accent twice; this is a special feature for
507 entering the separate letter and accent. For example, @kbd{o ^ ^} gives
508 you the two characters @samp{o^}. Another way is to type another letter
509 after the @kbd{o}---something that won't combine with that---and
510 immediately delete it. For example, you could type @kbd{o o @key{DEL}
511 ^} to get separate @samp{o} and @samp{^}. Another method, more
512 general but not quite as easy to type, is to use @kbd{C-\ C-\} between
513 two characters to stop them from combining. This is the command
514 @kbd{C-\} (@code{toggle-input-method}) used twice.
516 @xref{Select Input Method}.
519 @cindex incremental search, input method interference
520 @kbd{C-\ C-\} is especially useful inside an incremental search,
521 because it stops waiting for more characters to combine, and starts
522 searching for what you have already entered.
524 To find out how to input the character after point using the current
525 input method, type @kbd{C-u C-x =}. @xref{Position Info}.
527 @c TODO: document complex-only/default/t of
528 @c @code{input-method-verbose-flag}
529 @vindex input-method-verbose-flag
530 @vindex input-method-highlight-flag
531 The variables @code{input-method-highlight-flag} and
532 @code{input-method-verbose-flag} control how input methods explain
533 what is happening. If @code{input-method-highlight-flag} is
534 non-@code{nil}, the partial sequence is highlighted in the buffer (for
535 most input methods---some disable this feature). If
536 @code{input-method-verbose-flag} is non-@code{nil}, the list of
537 possible characters to type next is displayed in the echo area (but
538 not when you are in the minibuffer).
540 @vindex quail-activate-hook
541 @findex quail-translation-keymap
542 You can modify how an input method works by making your changes in a
543 function that you add to the hook variable @code{quail-activate-hook}.
544 @xref{Hooks}. For example, you can redefine some of the input
545 method's keys by defining key bindings in the keymap returned by the
546 function @code{quail-translation-keymap}, using @code{define-key}.
547 @xref{Init Rebinding}.
549 Another facility for typing characters not on your keyboard is by
550 using @kbd{C-x 8 @key{RET}} (@code{insert-char}) to insert a single
551 character based on its Unicode name or code-point; see @ref{Inserting
554 @node Select Input Method
555 @section Selecting an Input Method
559 Enable or disable use of the selected input method (@code{toggle-input-method}).
561 @item C-x @key{RET} C-\ @var{method} @key{RET}
562 Select a new input method for the current buffer (@code{set-input-method}).
564 @item C-h I @var{method} @key{RET}
565 @itemx C-h C-\ @var{method} @key{RET}
566 @findex describe-input-method
569 Describe the input method @var{method} (@code{describe-input-method}).
570 By default, it describes the current input method (if any). This
571 description should give you the full details of how to use any
572 particular input method.
574 @item M-x list-input-methods
575 Display a list of all the supported input methods.
578 @findex set-input-method
579 @vindex current-input-method
581 To choose an input method for the current buffer, use @kbd{C-x
582 @key{RET} C-\} (@code{set-input-method}). This command reads the
583 input method name from the minibuffer; the name normally starts with the
584 language environment that it is meant to be used with. The variable
585 @code{current-input-method} records which input method is selected.
587 @findex toggle-input-method
589 Input methods use various sequences of @acronym{ASCII} characters to
590 stand for non-@acronym{ASCII} characters. Sometimes it is useful to
591 turn off the input method temporarily. To do this, type @kbd{C-\}
592 (@code{toggle-input-method}). To reenable the input method, type
595 If you type @kbd{C-\} and you have not yet selected an input method,
596 it prompts you to specify one. This has the same effect as using
597 @kbd{C-x @key{RET} C-\} to specify an input method.
599 When invoked with a numeric argument, as in @kbd{C-u C-\},
600 @code{toggle-input-method} always prompts you for an input method,
601 suggesting the most recently selected one as the default.
603 @vindex default-input-method
604 Selecting a language environment specifies a default input method for
605 use in various buffers. When you have a default input method, you can
606 select it in the current buffer by typing @kbd{C-\}. The variable
607 @code{default-input-method} specifies the default input method
608 (@code{nil} means there is none).
610 In some language environments, which support several different input
611 methods, you might want to use an input method different from the
612 default chosen by @code{set-language-environment}. You can instruct
613 Emacs to select a different default input method for a certain
614 language environment, if you wish, by using
615 @code{set-language-environment-hook} (@pxref{Language Environments,
616 set-language-environment-hook}). For example:
619 (defun my-chinese-setup ()
620 "Set up my private Chinese environment."
621 (if (equal current-language-environment "Chinese-GB")
622 (setq default-input-method "chinese-tonepy")))
623 (add-hook 'set-language-environment-hook 'my-chinese-setup)
627 This sets the default input method to be @code{chinese-tonepy}
628 whenever you choose a Chinese-GB language environment.
630 You can instruct Emacs to activate a certain input method
631 automatically. For example:
634 (add-hook 'text-mode-hook
635 (lambda () (set-input-method "german-prefix")))
639 This automatically activates the input method @code{german-prefix} in
642 @findex quail-set-keyboard-layout
643 Some input methods for alphabetic scripts work by (in effect)
644 remapping the keyboard to emulate various keyboard layouts commonly used
645 for those scripts. How to do this remapping properly depends on your
646 actual keyboard layout. To specify which layout your keyboard has, use
647 the command @kbd{M-x quail-set-keyboard-layout}.
649 @findex quail-show-key
650 You can use the command @kbd{M-x quail-show-key} to show what key (or
651 key sequence) to type in order to input the character following point,
652 using the selected keyboard layout. The command @kbd{C-u C-x =} also
653 shows that information, in addition to other information about the
656 @findex list-input-methods
657 @kbd{M-x list-input-methods} displays a list of all the supported
658 input methods. The list gives information about each input method,
659 including the string that stands for it in the mode line.
662 @section Coding Systems
663 @cindex coding systems
665 Users of various languages have established many more-or-less standard
666 coding systems for representing them. Emacs does not use these coding
667 systems internally; instead, it converts from various coding systems to
668 its own system when reading data, and converts the internal coding
669 system to other coding systems when writing data. Conversion is
670 possible in reading or writing files, in sending or receiving from the
671 terminal, and in exchanging data with subprocesses.
673 Emacs assigns a name to each coding system. Most coding systems are
674 used for one language, and the name of the coding system starts with
675 the language name. Some coding systems are used for several
676 languages; their names usually start with @samp{iso}. There are also
677 special coding systems, such as @code{no-conversion}, @code{raw-text},
678 and @code{emacs-internal}.
680 @cindex international files from DOS/Windows systems
681 A special class of coding systems, collectively known as
682 @dfn{codepages}, is designed to support text encoded by MS-Windows and
683 MS-DOS software. The names of these coding systems are
684 @code{cp@var{nnnn}}, where @var{nnnn} is a 3- or 4-digit number of the
685 codepage. You can use these encodings just like any other coding
686 system; for example, to visit a file encoded in codepage 850, type
687 @kbd{C-x @key{RET} c cp850 @key{RET} C-x C-f @var{filename}
690 In addition to converting various representations of non-@acronym{ASCII}
691 characters, a coding system can perform end-of-line conversion. Emacs
692 handles three different conventions for how to separate lines in a file:
693 newline (Unix), carriage-return linefeed (DOS), and just
694 carriage-return (Mac).
697 @item C-h C @var{coding} @key{RET}
698 Describe coding system @var{coding} (@code{describe-coding-system}).
700 @item C-h C @key{RET}
701 Describe the coding systems currently in use.
703 @item M-x list-coding-systems
704 Display a list of all the supported coding systems.
708 @findex describe-coding-system
709 The command @kbd{C-h C} (@code{describe-coding-system}) displays
710 information about particular coding systems, including the end-of-line
711 conversion specified by those coding systems. You can specify a coding
712 system name as the argument; alternatively, with an empty argument, it
713 describes the coding systems currently selected for various purposes,
714 both in the current buffer and as the defaults, and the priority list
715 for recognizing coding systems (@pxref{Recognize Coding}).
717 @findex list-coding-systems
718 To display a list of all the supported coding systems, type @kbd{M-x
719 list-coding-systems}. The list gives information about each coding
720 system, including the letter that stands for it in the mode line
723 @cindex end-of-line conversion
725 @cindex MS-DOS end-of-line conversion
726 @cindex Macintosh end-of-line conversion
727 Each of the coding systems that appear in this list---except for
728 @code{no-conversion}, which means no conversion of any kind---specifies
729 how and whether to convert printing characters, but leaves the choice of
730 end-of-line conversion to be decided based on the contents of each file.
731 For example, if the file appears to use the sequence carriage-return
732 linefeed to separate lines, DOS end-of-line conversion will be used.
734 Each of the listed coding systems has three variants, which specify
735 exactly what to do for end-of-line conversion:
739 Don't do any end-of-line conversion; assume the file uses
740 newline to separate lines. (This is the convention normally used
741 on Unix and GNU systems, and macOS.)
744 Assume the file uses carriage-return linefeed to separate lines, and do
745 the appropriate conversion. (This is the convention normally used on
746 Microsoft systems.@footnote{It is also specified for MIME @samp{text/*}
747 bodies and in other network transport contexts. It is different
748 from the SGML reference syntax record-start/record-end format, which
749 Emacs doesn't support directly.})
752 Assume the file uses carriage-return to separate lines, and do the
753 appropriate conversion. (This was the convention used in Classic Mac
757 These variant coding systems are omitted from the
758 @code{list-coding-systems} display for brevity, since they are entirely
759 predictable. For example, the coding system @code{iso-latin-1} has
760 variants @code{iso-latin-1-unix}, @code{iso-latin-1-dos} and
761 @code{iso-latin-1-mac}.
763 @cindex @code{undecided}, coding system
764 The coding systems @code{unix}, @code{dos}, and @code{mac} are
765 aliases for @code{undecided-unix}, @code{undecided-dos}, and
766 @code{undecided-mac}, respectively. These coding systems specify only
767 the end-of-line conversion, and leave the character code conversion to
768 be deduced from the text itself.
770 @cindex @code{raw-text}, coding system
771 The coding system @code{raw-text} is good for a file which is mainly
772 @acronym{ASCII} text, but may contain byte values above 127 that are
773 not meant to encode non-@acronym{ASCII} characters. With
774 @code{raw-text}, Emacs copies those byte values unchanged, and sets
775 @code{enable-multibyte-characters} to @code{nil} in the current buffer
776 so that they will be interpreted properly. @code{raw-text} handles
777 end-of-line conversion in the usual way, based on the data
778 encountered, and has the usual three variants to specify the kind of
779 end-of-line conversion to use.
781 @cindex @code{no-conversion}, coding system
782 In contrast, the coding system @code{no-conversion} specifies no
783 character code conversion at all---none for non-@acronym{ASCII} byte values and
784 none for end of line. This is useful for reading or writing binary
785 files, tar files, and other files that must be examined verbatim. It,
786 too, sets @code{enable-multibyte-characters} to @code{nil}.
788 The easiest way to edit a file with no conversion of any kind is with
789 the @kbd{M-x find-file-literally} command. This uses
790 @code{no-conversion}, and also suppresses other Emacs features that
791 might convert the file contents before you see them. @xref{Visiting}.
793 @cindex @code{emacs-internal}, coding system
794 The coding system @code{emacs-internal} (or @code{utf-8-emacs},
795 which is equivalent) means that the file contains non-@acronym{ASCII}
796 characters stored with the internal Emacs encoding. This coding
797 system handles end-of-line conversion based on the data encountered,
798 and has the usual three variants to specify the kind of end-of-line
801 @node Recognize Coding
802 @section Recognizing Coding Systems
804 Whenever Emacs reads a given piece of text, it tries to recognize
805 which coding system to use. This applies to files being read, output
806 from subprocesses, text from X selections, etc. Emacs can select the
807 right coding system automatically most of the time---once you have
808 specified your preferences.
810 Some coding systems can be recognized or distinguished by which byte
811 sequences appear in the data. However, there are coding systems that
812 cannot be distinguished, not even potentially. For example, there is no
813 way to distinguish between Latin-1 and Latin-2; they use the same byte
814 values with different meanings.
816 Emacs handles this situation by means of a priority list of coding
817 systems. Whenever Emacs reads a file, if you do not specify the coding
818 system to use, Emacs checks the data against each coding system,
819 starting with the first in priority and working down the list, until it
820 finds a coding system that fits the data. Then it converts the file
821 contents assuming that they are represented in this coding system.
823 The priority list of coding systems depends on the selected language
824 environment (@pxref{Language Environments}). For example, if you use
825 French, you probably want Emacs to prefer Latin-1 to Latin-2; if you use
826 Czech, you probably want Latin-2 to be preferred. This is one of the
827 reasons to specify a language environment.
829 @findex prefer-coding-system
830 However, you can alter the coding system priority list in detail
831 with the command @kbd{M-x prefer-coding-system}. This command reads
832 the name of a coding system from the minibuffer, and adds it to the
833 front of the priority list, so that it is preferred to all others. If
834 you use this command several times, each use adds one element to the
835 front of the priority list.
837 If you use a coding system that specifies the end-of-line conversion
838 type, such as @code{iso-8859-1-dos}, what this means is that Emacs
839 should attempt to recognize @code{iso-8859-1} with priority, and should
840 use DOS end-of-line conversion when it does recognize @code{iso-8859-1}.
842 @vindex file-coding-system-alist
843 Sometimes a file name indicates which coding system to use for the
844 file. The variable @code{file-coding-system-alist} specifies this
845 correspondence. There is a special function
846 @code{modify-coding-system-alist} for adding elements to this list. For
847 example, to read and write all @samp{.txt} files using the coding system
848 @code{chinese-iso-8bit}, you can execute this Lisp expression:
851 (modify-coding-system-alist 'file "\\.txt\\'" 'chinese-iso-8bit)
855 The first argument should be @code{file}, the second argument should be
856 a regular expression that determines which files this applies to, and
857 the third argument says which coding system to use for these files.
859 @vindex inhibit-eol-conversion
860 @cindex DOS-style end-of-line display
861 Emacs recognizes which kind of end-of-line conversion to use based on
862 the contents of the file: if it sees only carriage-returns, or only
863 carriage-return linefeed sequences, then it chooses the end-of-line
864 conversion accordingly. You can inhibit the automatic use of
865 end-of-line conversion by setting the variable @code{inhibit-eol-conversion}
866 to non-@code{nil}. If you do that, DOS-style files will be displayed
867 with the @samp{^M} characters visible in the buffer; some people
868 prefer this to the more subtle @samp{(DOS)} end-of-line type
869 indication near the left edge of the mode line (@pxref{Mode Line,
872 @vindex inhibit-iso-escape-detection
873 @cindex escape sequences in files
874 By default, the automatic detection of coding system is sensitive to
875 escape sequences. If Emacs sees a sequence of characters that begin
876 with an escape character, and the sequence is valid as an ISO-2022
877 code, that tells Emacs to use one of the ISO-2022 encodings to decode
880 However, there may be cases that you want to read escape sequences
881 in a file as is. In such a case, you can set the variable
882 @code{inhibit-iso-escape-detection} to non-@code{nil}. Then the code
883 detection ignores any escape sequences, and never uses an ISO-2022
884 encoding. The result is that all escape sequences become visible in
887 The default value of @code{inhibit-iso-escape-detection} is
888 @code{nil}. We recommend that you not change it permanently, only for
889 one specific operation. That's because some Emacs Lisp source files
890 in the Emacs distribution contain non-@acronym{ASCII} characters encoded in the
891 coding system @code{iso-2022-7bit}, and they won't be
892 decoded correctly when you visit those files if you suppress the
893 escape sequence detection.
894 @c I count a grand total of 3 such files, so is the above really true?
896 @vindex auto-coding-alist
897 @vindex auto-coding-regexp-alist
898 The variables @code{auto-coding-alist} and
899 @code{auto-coding-regexp-alist} are
900 the strongest way to specify the coding system for certain patterns of
901 file names, or for files containing certain patterns, respectively.
902 These variables even override @samp{-*-coding:-*-} tags in the file
903 itself (@pxref{Specify Coding}). For example, Emacs
904 uses @code{auto-coding-alist} for tar and archive files, to prevent it
905 from being confused by a @samp{-*-coding:-*-} tag in a member of the
906 archive and thinking it applies to the archive file as a whole.
908 @c This describes old-style BABYL files, which are no longer relevant.
909 Likewise, Emacs uses @code{auto-coding-regexp-alist} to ensure that
910 RMAIL files, whose names in general don't match any particular
911 pattern, are decoded correctly.
914 @vindex auto-coding-functions
915 Another way to specify a coding system is with the variable
916 @code{auto-coding-functions}. For example, one of the builtin
917 @code{auto-coding-functions} detects the encoding for XML files.
918 Unlike the previous two, this variable does not override any
919 @samp{-*-coding:-*-} tag.
922 @section Specifying a File's Coding System
924 If Emacs recognizes the encoding of a file incorrectly, you can
925 reread the file using the correct coding system with @kbd{C-x
926 @key{RET} r} (@code{revert-buffer-with-coding-system}). This command
927 prompts for the coding system to use. To see what coding system Emacs
928 actually used to decode the file, look at the coding system mnemonic
929 letter near the left edge of the mode line (@pxref{Mode Line}), or
930 type @kbd{C-h C} (@code{describe-coding-system}).
933 You can specify the coding system for a particular file in the file
934 itself, using the @w{@samp{-*-@dots{}-*-}} construct at the beginning,
935 or a local variables list at the end (@pxref{File Variables}). You do
936 this by defining a value for the ``variable'' named @code{coding}.
937 Emacs does not really have a variable @code{coding}; instead of
938 setting a variable, this uses the specified coding system for the
939 file. For example, @samp{-*-mode: C; coding: latin-1;-*-} specifies
940 use of the Latin-1 coding system, as well as C mode. When you specify
941 the coding explicitly in the file, that overrides
942 @code{file-coding-system-alist}.
945 @section Choosing Coding Systems for Output
947 @vindex buffer-file-coding-system
948 Once Emacs has chosen a coding system for a buffer, it stores that
949 coding system in @code{buffer-file-coding-system}. That makes it the
950 default for operations that write from this buffer into a file, such
951 as @code{save-buffer} and @code{write-region}. You can specify a
952 different coding system for further file output from the buffer using
953 @code{set-buffer-file-coding-system} (@pxref{Text Coding}).
955 You can insert any character Emacs supports into any Emacs buffer,
956 but most coding systems can only handle a subset of these characters.
957 Therefore, it's possible that the characters you insert cannot be
958 encoded with the coding system that will be used to save the buffer.
959 For example, you could visit a text file in Polish, encoded in
960 @code{iso-8859-2}, and add some Russian words to it. When you save
961 that buffer, Emacs cannot use the current value of
962 @code{buffer-file-coding-system}, because the characters you added
963 cannot be encoded by that coding system.
965 When that happens, Emacs tries the most-preferred coding system (set
966 by @kbd{M-x prefer-coding-system} or @kbd{M-x
967 set-language-environment}). If that coding system can safely encode
968 all of the characters in the buffer, Emacs uses it, and stores its
969 value in @code{buffer-file-coding-system}. Otherwise, Emacs displays
970 a list of coding systems suitable for encoding the buffer's contents,
971 and asks you to choose one of those coding systems.
973 If you insert the unsuitable characters in a mail message, Emacs
974 behaves a bit differently. It additionally checks whether the
975 @c What determines this?
976 most-preferred coding system is recommended for use in MIME messages;
977 if not, it informs you of this fact and prompts you for another coding
978 system. This is so you won't inadvertently send a message encoded in
979 a way that your recipient's mail software will have difficulty
980 decoding. (You can still use an unsuitable coding system if you enter
981 its name at the prompt.)
983 @c It seems that select-message-coding-system does this.
984 @c Both sendmail.el and smptmail.el call it; i.e., smtpmail.el still
985 @c obeys sendmail-coding-system.
986 @vindex sendmail-coding-system
987 When you send a mail message (@pxref{Sending Mail}),
988 Emacs has four different ways to determine the coding system to use
989 for encoding the message text. It first tries the buffer's own value of
990 @code{buffer-file-coding-system}, if that is non-@code{nil}.
991 Otherwise, it uses the value of @code{sendmail-coding-system}, if that
992 is non-@code{nil}. Thirdly, it uses the value of
993 @code{default-sendmail-coding-system}.
994 If all of these three values are @code{nil}, Emacs encodes outgoing
995 mail using the default coding system for new files (i.e., the
996 default value of @code{buffer-file-coding-system}), which is
997 controlled by your choice of language environment.
1000 @section Specifying a Coding System for File Text
1002 In cases where Emacs does not automatically choose the right coding
1003 system for a file's contents, you can use these commands to specify
1007 @item C-x @key{RET} f @var{coding} @key{RET}
1008 Use coding system @var{coding} to save or revisit the file in
1009 the current buffer (@code{set-buffer-file-coding-system}).
1011 @item C-x @key{RET} c @var{coding} @key{RET}
1012 Specify coding system @var{coding} for the immediately following
1013 command (@code{universal-coding-system-argument}).
1015 @item C-x @key{RET} r @var{coding} @key{RET}
1016 Revisit the current file using the coding system @var{coding}
1017 (@code{revert-buffer-with-coding-system}).
1019 @item M-x recode-region @key{RET} @var{right} @key{RET} @var{wrong} @key{RET}
1020 Convert a region that was decoded using coding system @var{wrong},
1021 decoding it using coding system @var{right} instead.
1025 @findex set-buffer-file-coding-system
1026 The command @kbd{C-x @key{RET} f}
1027 (@code{set-buffer-file-coding-system}) sets the file coding system for
1028 the current buffer (i.e., the coding system to use when saving or
1029 reverting the file). You specify which coding system using the
1030 minibuffer. You can also invoke this command by clicking with
1031 @kbd{mouse-3} on the coding system indicator in the mode line
1032 (@pxref{Mode Line}).
1034 If you specify a coding system that cannot handle all the characters
1035 in the buffer, Emacs will warn you about the troublesome characters,
1036 and ask you to choose another coding system, when you try to save the
1037 buffer (@pxref{Output Coding}).
1039 @cindex specify end-of-line conversion
1040 You can also use this command to specify the end-of-line conversion
1041 (@pxref{Coding Systems, end-of-line conversion}) for encoding the
1042 current buffer. For example, @kbd{C-x @key{RET} f dos @key{RET}} will
1043 cause Emacs to save the current buffer's text with DOS-style
1044 carriage-return linefeed line endings.
1047 @findex universal-coding-system-argument
1048 Another way to specify the coding system for a file is when you visit
1049 the file. First use the command @kbd{C-x @key{RET} c}
1050 (@code{universal-coding-system-argument}); this command uses the
1051 minibuffer to read a coding system name. After you exit the minibuffer,
1052 the specified coding system is used for @emph{the immediately following
1055 So if the immediately following command is @kbd{C-x C-f}, for example,
1056 it reads the file using that coding system (and records the coding
1057 system for when you later save the file). Or if the immediately following
1058 command is @kbd{C-x C-w}, it writes the file using that coding system.
1059 When you specify the coding system for saving in this way, instead
1060 of with @kbd{C-x @key{RET} f}, there is no warning if the buffer
1061 contains characters that the coding system cannot handle.
1063 Other file commands affected by a specified coding system include
1064 @kbd{C-x i} and @kbd{C-x C-v}, as well as the other-window variants
1065 of @kbd{C-x C-f}. @kbd{C-x @key{RET} c} also affects commands that
1066 start subprocesses, including @kbd{M-x shell} (@pxref{Shell}). If the
1067 immediately following command does not use the coding system, then
1068 @kbd{C-x @key{RET} c} ultimately has no effect.
1070 An easy way to visit a file with no conversion is with the @kbd{M-x
1071 find-file-literally} command. @xref{Visiting}.
1073 The default value of the variable @code{buffer-file-coding-system}
1074 specifies the choice of coding system to use when you create a new file.
1075 It applies when you find a new file, and when you create a buffer and
1076 then save it in a file. Selecting a language environment typically sets
1077 this variable to a good choice of default coding system for that language
1081 @findex revert-buffer-with-coding-system
1082 If you visit a file with a wrong coding system, you can correct this
1083 with @kbd{C-x @key{RET} r} (@code{revert-buffer-with-coding-system}).
1084 This visits the current file again, using a coding system you specify.
1086 @findex recode-region
1087 If a piece of text has already been inserted into a buffer using the
1088 wrong coding system, you can redo the decoding of it using @kbd{M-x
1089 recode-region}. This prompts you for the proper coding system, then
1090 for the wrong coding system that was actually used, and does the
1091 conversion. It first encodes the region using the wrong coding system,
1092 then decodes it again using the proper coding system.
1094 @node Communication Coding
1095 @section Coding Systems for Interprocess Communication
1097 This section explains how to specify coding systems for use
1098 in communication with other processes.
1101 @item C-x @key{RET} x @var{coding} @key{RET}
1102 Use coding system @var{coding} for transferring selections to and from
1103 other graphical applications (@code{set-selection-coding-system}).
1105 @item C-x @key{RET} X @var{coding} @key{RET}
1106 Use coding system @var{coding} for transferring @emph{one}
1107 selection---the next one---to or from another graphical application
1108 (@code{set-next-selection-coding-system}).
1110 @item C-x @key{RET} p @var{input-coding} @key{RET} @var{output-coding} @key{RET}
1111 Use coding systems @var{input-coding} and @var{output-coding} for
1112 subprocess input and output in the current buffer
1113 (@code{set-buffer-process-coding-system}).
1118 @findex set-selection-coding-system
1119 @findex set-next-selection-coding-system
1120 The command @kbd{C-x @key{RET} x} (@code{set-selection-coding-system})
1121 specifies the coding system for sending selected text to other windowing
1122 applications, and for receiving the text of selections made in other
1123 applications. This command applies to all subsequent selections, until
1124 you override it by using the command again. The command @kbd{C-x
1125 @key{RET} X} (@code{set-next-selection-coding-system}) specifies the
1126 coding system for the next selection made in Emacs or read by Emacs.
1128 @vindex x-select-request-type
1129 The variable @code{x-select-request-type} specifies the data type to
1130 request from the X Window System for receiving text selections from
1131 other applications. If the value is @code{nil} (the default), Emacs
1132 tries @code{UTF8_STRING} and @code{COMPOUND_TEXT}, in this order, and
1133 uses various heuristics to choose the more appropriate of the two
1134 results; if none of these succeed, Emacs falls back on @code{STRING}.
1135 If the value of @code{x-select-request-type} is one of the symbols
1136 @code{COMPOUND_TEXT}, @code{UTF8_STRING}, @code{STRING}, or
1137 @code{TEXT}, Emacs uses only that request type. If the value is a
1138 list of some of these symbols, Emacs tries only the request types in
1139 the list, in order, until one of them succeeds, or until the list is
1143 @findex set-buffer-process-coding-system
1144 The command @kbd{C-x @key{RET} p} (@code{set-buffer-process-coding-system})
1145 specifies the coding system for input and output to a subprocess. This
1146 command applies to the current buffer; normally, each subprocess has its
1147 own buffer, and thus you can use this command to specify translation to
1148 and from a particular subprocess by giving the command in the
1149 corresponding buffer.
1151 You can also use @kbd{C-x @key{RET} c}
1152 (@code{universal-coding-system-argument}) just before the command that
1153 runs or starts a subprocess, to specify the coding system for
1154 communicating with that subprocess. @xref{Text Coding}.
1156 The default for translation of process input and output depends on the
1157 current language environment.
1159 @vindex locale-coding-system
1160 @cindex decoding non-@acronym{ASCII} keyboard input on X
1161 The variable @code{locale-coding-system} specifies a coding system
1162 to use when encoding and decoding system strings such as system error
1163 messages and @code{format-time-string} formats and time stamps. That
1164 coding system is also used for decoding non-@acronym{ASCII} keyboard
1165 input on the X Window System and for encoding text sent to the
1166 standard output and error streams when in batch mode. You should
1167 choose a coding system that is compatible
1168 with the underlying system's text representation, which is normally
1169 specified by one of the environment variables @env{LC_ALL},
1170 @env{LC_CTYPE}, and @env{LANG}. (The first one, in the order
1171 specified above, whose value is nonempty is the one that determines
1172 the text representation.)
1174 @node File Name Coding
1175 @section Coding Systems for File Names
1178 @item C-x @key{RET} F @var{coding} @key{RET}
1179 Use coding system @var{coding} for encoding and decoding file
1180 names (@code{set-file-name-coding-system}).
1183 @findex set-file-name-coding-system
1185 @cindex file names with non-@acronym{ASCII} characters
1186 The command @kbd{C-x @key{RET} F} (@code{set-file-name-coding-system})
1187 specifies a coding system to use for encoding file @emph{names}. It
1188 has no effect on reading and writing the @emph{contents} of files.
1190 @vindex file-name-coding-system
1191 In fact, all this command does is set the value of the variable
1192 @code{file-name-coding-system}. If you set the variable to a coding
1193 system name (as a Lisp symbol or a string), Emacs encodes file names
1194 using that coding system for all file operations. This makes it
1195 possible to use non-@acronym{ASCII} characters in file names---or, at
1196 least, those non-@acronym{ASCII} characters that the specified coding
1199 If @code{file-name-coding-system} is @code{nil}, Emacs uses a
1200 default coding system determined by the selected language environment,
1201 and stored in the @code{default-file-name-coding-system} variable.
1202 @c FIXME? Is this correct? What is the "default language environment"?
1203 In the default language environment, non-@acronym{ASCII} characters in
1204 file names are not encoded specially; they appear in the file system
1205 using the internal Emacs representation.
1207 @cindex file-name encoding, MS-Windows
1208 @vindex w32-unicode-filenames
1209 When Emacs runs on MS-Windows versions that are descendants of the
1210 NT family (Windows 2000, XP, Vista, Windows 7, and all the later
1211 versions), the value of @code{file-name-coding-system} is largely
1212 ignored, as Emacs by default uses APIs that allow passing Unicode file
1213 names directly. By contrast, on Windows 9X, file names are encoded
1214 using @code{file-name-coding-system}, which should be set to the
1215 codepage (@pxref{Coding Systems, codepage}) pertinent for the current
1216 system locale. The value of the variable @code{w32-unicode-filenames}
1217 controls whether Emacs uses the Unicode APIs when it calls OS
1218 functions that accept file names. This variable is set by the startup
1219 code to @code{nil} on Windows 9X, and to @code{t} on newer versions of
1222 @strong{Warning:} if you change @code{file-name-coding-system} (or the
1223 language environment) in the middle of an Emacs session, problems can
1224 result if you have already visited files whose names were encoded using
1225 the earlier coding system and cannot be encoded (or are encoded
1226 differently) under the new coding system. If you try to save one of
1227 these buffers under the visited file name, saving may use the wrong file
1228 name, or it may encounter an error. If such a problem happens, use @kbd{C-x
1229 C-w} to specify a new file name for that buffer.
1231 @findex recode-file-name
1232 If a mistake occurs when encoding a file name, use the command
1233 @kbd{M-x recode-file-name} to change the file name's coding
1234 system. This prompts for an existing file name, its old coding
1235 system, and the coding system to which you wish to convert.
1237 @node Terminal Coding
1238 @section Coding Systems for Terminal I/O
1241 @item C-x @key{RET} t @var{coding} @key{RET}
1242 Use coding system @var{coding} for terminal output
1243 (@code{set-terminal-coding-system}).
1245 @item C-x @key{RET} k @var{coding} @key{RET}
1246 Use coding system @var{coding} for keyboard input
1247 (@code{set-keyboard-coding-system}).
1251 @findex set-terminal-coding-system
1252 The command @kbd{C-x @key{RET} t} (@code{set-terminal-coding-system})
1253 specifies the coding system for terminal output. If you specify a
1254 character code for terminal output, all characters output to the
1255 terminal are translated into that coding system.
1257 This feature is useful for certain character-only terminals built to
1258 support specific languages or character sets---for example, European
1259 terminals that support one of the ISO Latin character sets. You need to
1260 specify the terminal coding system when using multibyte text, so that
1261 Emacs knows which characters the terminal can actually handle.
1263 By default, output to the terminal is not translated at all, unless
1264 Emacs can deduce the proper coding system from your terminal type or
1265 your locale specification (@pxref{Language Environments}).
1268 @findex set-keyboard-coding-system
1269 @vindex keyboard-coding-system
1270 The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system}),
1271 or the variable @code{keyboard-coding-system}, specifies the coding
1272 system for keyboard input. Character-code translation of keyboard
1273 input is useful for terminals with keys that send non-@acronym{ASCII}
1274 graphic characters---for example, some terminals designed for ISO
1275 Latin-1 or subsets of it.
1277 By default, keyboard input is translated based on your system locale
1278 setting. If your terminal does not really support the encoding
1279 implied by your locale (for example, if you find it inserts a
1280 non-@acronym{ASCII} character if you type @kbd{M-i}), you will need to set
1281 @code{keyboard-coding-system} to @code{nil} to turn off encoding.
1282 You can do this by putting
1285 (set-keyboard-coding-system nil)
1291 There is a similarity between using a coding system translation for
1292 keyboard input, and using an input method: both define sequences of
1293 keyboard input that translate into single characters. However, input
1294 methods are designed to be convenient for interactive use by humans, and
1295 the sequences that are translated are typically sequences of @acronym{ASCII}
1296 printing characters. Coding systems typically translate sequences of
1297 non-graphic characters.
1303 A font typically defines shapes for a single alphabet or script.
1304 Therefore, displaying the entire range of scripts that Emacs supports
1305 requires a collection of many fonts. In Emacs, such a collection is
1306 called a @dfn{fontset}. A fontset is defined by a list of font specifications,
1307 each assigned to handle a range of character codes, and may fall back
1308 on another fontset for characters that are not covered by the fonts
1311 @cindex fonts for various scripts
1312 @cindex Intlfonts package, installation
1313 Each fontset has a name, like a font. However, while fonts are
1314 stored in the system and the available font names are defined by the
1315 system, fontsets are defined within Emacs itself. Once you have
1316 defined a fontset, you can use it within Emacs by specifying its name,
1317 anywhere that you could use a single font. Of course, Emacs fontsets
1318 can use only the fonts that the system supports. If some characters
1319 appear on the screen as empty boxes or hex codes, this means that the
1320 fontset in use for them has no font for those characters. In this
1321 case, or if the characters are shown, but not as well as you would
1322 like, you may need to install extra fonts. Your operating system may
1323 have optional fonts that you can install; or you can install the GNU
1324 Intlfonts package, which includes fonts for most supported
1325 scripts.@footnote{If you run Emacs on X, you may need to inform the X
1326 server about the location of the newly installed fonts with commands
1328 @c FIXME? I feel like this may be out of date.
1329 @c E.g., the intlfonts tarfile is ~ 10 years old.
1332 xset fp+ /usr/local/share/emacs/fonts
1337 Emacs creates three fontsets automatically: the @dfn{standard
1338 fontset}, the @dfn{startup fontset} and the @dfn{default fontset}.
1339 @c FIXME? The doc of *standard*-fontset-spec says:
1340 @c "You have the biggest chance to display international characters
1341 @c with correct glyphs by using the *standard* fontset." (my emphasis)
1342 @c See https://lists.gnu.org/r/emacs-devel/2012-04/msg00430.html
1343 The default fontset is most likely to have fonts for a wide variety of
1344 non-@acronym{ASCII} characters, and is the default fallback for the
1345 other two fontsets, and if you set a default font rather than fontset.
1346 However, it does not specify font family names, so results can be
1347 somewhat random if you use it directly. You can specify use of a
1348 particular fontset by starting Emacs with the @samp{-fn} option.
1352 emacs -fn fontset-standard
1356 You can also specify a fontset with the @samp{Font} resource (@pxref{X
1359 If no fontset is specified for use, then Emacs uses an
1360 @acronym{ASCII} font, with @samp{fontset-default} as a fallback for
1361 characters the font does not cover. The standard fontset is only used if
1362 explicitly requested, despite its name.
1364 @findex describe-fontset
1365 To show the information about a specific fontset, use the
1366 @w{@kbd{M-x describe-fontset}} command. It prompts for a fontset
1367 name, defaulting to the one used by the current frame, and then
1368 displays all the subranges of characters and the fonts assigned to
1369 them in that fontset.
1371 A fontset does not necessarily specify a font for every character
1372 code. If a fontset specifies no font for a certain character, or if
1373 it specifies a font that does not exist on your system, then it cannot
1374 display that character properly. It will display that character as a
1375 hex code or thin space or an empty box instead. (@xref{Text Display, ,
1376 glyphless characters}, for details.)
1378 @node Defining Fontsets
1379 @section Defining Fontsets
1381 @vindex standard-fontset-spec
1382 @vindex w32-standard-fontset-spec
1383 @vindex ns-standard-fontset-spec
1384 @cindex standard fontset
1385 When running on X, Emacs creates a standard fontset automatically according to the value
1386 of @code{standard-fontset-spec}. This fontset's name is
1389 -*-fixed-medium-r-normal-*-16-*-*-*-*-*-fontset-standard
1393 or just @samp{fontset-standard} for short.
1395 On GNUstep and macOS, the standard fontset is created using the value of
1396 @code{ns-standard-fontset-spec}, and on MS Windows it is
1397 created using the value of @code{w32-standard-fontset-spec}.
1399 @c FIXME? How does one access these, or do anything with them?
1401 Bold, italic, and bold-italic variants of the standard fontset are
1402 created automatically. Their names have @samp{bold} instead of
1403 @samp{medium}, or @samp{i} instead of @samp{r}, or both.
1405 @cindex startup fontset
1406 Emacs generates a fontset automatically, based on any default
1407 @acronym{ASCII} font that you specify with the @samp{Font} resource or
1408 the @samp{-fn} argument, or the default font that Emacs found when it
1409 started. This is the @dfn{startup fontset} and its name is
1410 @code{fontset-startup}. Emacs generates this fontset by replacing the
1411 @var{charset_registry} field with @samp{fontset}, and replacing the
1412 @var{charset_encoding} field with @samp{startup}, then using the
1413 resulting string to specify a fontset.
1415 For instance, if you start Emacs with a font of this form,
1417 @c FIXME? I think this is a little misleading, because you cannot (?)
1418 @c actually specify a font with wildcards, it has to be a complete spec.
1419 @c Also, an X font specification of this form hasn't (?) been
1420 @c mentioned before now, and is somewhat obsolete these days.
1421 @c People are more likely to use a form like
1422 @c emacs -fn "DejaVu Sans Mono-12"
1423 @c How does any of this apply in that case?
1425 emacs -fn "*courier-medium-r-normal--14-140-*-iso8859-1"
1429 Emacs generates the following fontset and uses it for the initial X
1433 -*-courier-medium-r-normal-*-14-140-*-*-*-*-fontset-startup
1436 The startup fontset will use the font that you specify, or a variant
1437 with a different registry and encoding, for all the characters that
1438 are supported by that font, and fallback on @samp{fontset-default} for
1441 With the X resource @samp{Emacs.Font}, you can specify a fontset name
1442 just like an actual font name. But be careful not to specify a fontset
1443 name in a wildcard resource like @samp{Emacs*Font}---that wildcard
1444 specification matches various other resources, such as for menus, and
1445 @c FIXME is this still true?
1446 menus cannot handle fontsets. @xref{X Resources}.
1448 You can specify additional fontsets using X resources named
1449 @samp{Fontset-@var{n}}, where @var{n} is an integer starting from 0.
1450 The resource value should have this form:
1453 @var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}}
1457 where @var{fontpattern} should have the form of a standard X font name
1458 (see the previous fontset-startup example), except for the last two
1459 fields. They should have the form @samp{fontset-@var{alias}}.
1461 Each fontset has two names, one long and one short. The long name
1462 is @var{fontpattern}. The short name is @samp{fontset-@var{alias}},
1463 the last 2 fields of the long name (e.g., @samp{fontset-startup} for
1464 the fontset automatically created at startup). You can refer to the
1465 fontset by either name.
1467 The construct @samp{@var{charset}:@var{font}} specifies which font to
1468 use (in this fontset) for one particular character set. Here,
1469 @var{charset} is the name of a character set, and @var{font} is the
1470 font to use for that character set. You can use this construct any
1471 number of times in defining one fontset.
1473 For the other character sets, Emacs chooses a font based on
1474 @var{fontpattern}. It replaces @samp{fontset-@var{alias}} with values
1475 that describe the character set. For the @acronym{ASCII} character font,
1476 @samp{fontset-@var{alias}} is replaced with @samp{ISO8859-1}.
1478 In addition, when several consecutive fields are wildcards, Emacs
1479 collapses them into a single wildcard. This is to prevent use of
1480 auto-scaled fonts. Fonts made by scaling larger fonts are not usable
1481 for editing, and scaling a smaller font is also not useful, because it is
1482 better to use the smaller font in its own size, which is what Emacs
1485 Thus if @var{fontpattern} is this,
1488 -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
1492 the font specification for @acronym{ASCII} characters would be this:
1495 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
1499 and the font specification for Chinese GB2312 characters would be this:
1502 -*-fixed-medium-r-normal-*-24-*-gb2312*-*
1505 You may not have any Chinese font matching the above font
1506 specification. Most X distributions include only Chinese fonts that
1507 have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In
1508 such a case, @samp{Fontset-@var{n}} can be specified as:
1511 Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
1512 chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
1516 Then, the font specifications for all but Chinese GB2312 characters have
1517 @samp{fixed} in the @var{family} field, and the font specification for
1518 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
1521 @findex create-fontset-from-fontset-spec
1522 The function that processes the fontset resource value to create the
1523 fontset is called @code{create-fontset-from-fontset-spec}. You can also
1524 call this function explicitly to create a fontset.
1526 @xref{Fonts}, for more information about font naming.
1528 @node Modifying Fontsets
1529 @section Modifying Fontsets
1530 @cindex fontsets, modifying
1531 @findex set-fontset-font
1533 Fontsets do not always have to be created from scratch. If only
1534 minor changes are required it may be easier to modify an existing
1535 fontset. Modifying @samp{fontset-default} will also affect other
1536 fontsets that use it as a fallback, so can be an effective way of
1537 fixing problems with the fonts that Emacs chooses for a particular
1540 Fontsets can be modified using the function @code{set-fontset-font},
1541 specifying a character, a charset, a script, or a range of characters
1542 to modify the font for, and a font specification for the font to be
1543 used. Some examples are:
1546 ;; Use Liberation Mono for latin-3 charset.
1547 (set-fontset-font "fontset-default" 'iso-8859-3
1550 ;; Prefer a big5 font for han characters.
1551 (set-fontset-font "fontset-default"
1552 'han (font-spec :registry "big5")
1555 ;; Use DejaVu Sans Mono as a fallback in fontset-startup
1556 ;; before resorting to fontset-default.
1557 (set-fontset-font "fontset-startup" nil "DejaVu Sans Mono"
1560 ;; Use MyPrivateFont for the Unicode private use area.
1561 (set-fontset-font "fontset-default" '(#xe000 . #xf8ff)
1567 @cindex fonts, how to ignore
1568 @vindex face-ignored-fonts
1569 Some fonts installed on your system might be broken, or produce
1570 unpleasant results for characters for which they are used, and you may
1571 wish to instruct Emacs to completely ignore them while searching for a
1572 suitable font required to display a character. You can do that by
1573 adding the offending fonts to the value of the variable
1574 @code{face-ignored-fonts}, which is a list. Here's an example to put
1575 in your @file{~/.emacs}:
1578 (add-to-list 'face-ignored-fonts "Some Bad Font")
1581 @node Undisplayable Characters
1582 @section Undisplayable Characters
1584 There may be some non-@acronym{ASCII} characters that your
1585 terminal cannot display. Most text terminals support just a single
1586 character set (use the variable @code{default-terminal-coding-system}
1587 to tell Emacs which one, @ref{Terminal Coding}); characters that
1588 can't be encoded in that coding system are displayed as @samp{?} by
1591 Graphical displays can display a broader range of characters, but
1592 you may not have fonts installed for all of them; characters that have
1593 no font appear as a hollow box.
1595 If you use Latin-1 characters but your terminal can't display
1596 Latin-1, you can arrange to display mnemonic @acronym{ASCII} sequences
1597 instead, e.g., @samp{"o} for o-umlaut. Load the library
1598 @file{iso-ascii} to do this.
1600 @vindex latin1-display
1601 If your terminal can display Latin-1, you can display characters
1602 from other European character sets using a mixture of equivalent
1603 Latin-1 characters and @acronym{ASCII} mnemonics. Customize the variable
1604 @code{latin1-display} to enable this. The mnemonic @acronym{ASCII}
1605 sequences mostly correspond to those of the prefix input methods.
1608 @section Unibyte Editing Mode
1610 @cindex European character sets
1611 @cindex accented characters
1612 @cindex ISO Latin character sets
1613 @cindex Unibyte operation
1614 The ISO 8859 Latin-@var{n} character sets define character codes in
1615 the range 0240 to 0377 octal (160 to 255 decimal) to handle the
1616 accented letters and punctuation needed by various European languages
1617 (and some non-European ones). Note that Emacs considers bytes with
1618 codes in this range as raw bytes, not as characters, even in a unibyte
1619 buffer, i.e., if you disable multibyte characters. However, Emacs can
1620 still handle these character codes as if they belonged to @emph{one}
1621 of the single-byte character sets at a time. To specify @emph{which}
1622 of these codes to use, invoke @kbd{M-x set-language-environment} and
1623 specify a suitable language environment such as @samp{Latin-@var{n}}.
1624 @xref{Disabling Multibyte, , Disabling Multibyte Characters, elisp,
1625 GNU Emacs Lisp Reference Manual}.
1627 @vindex unibyte-display-via-language-environment
1628 Emacs can also display bytes in the range 160 to 255 as readable
1629 characters, provided the terminal or font in use supports them. This
1630 works automatically. On a graphical display, Emacs can also display
1631 single-byte characters through fontsets, in effect by displaying the
1632 equivalent multibyte characters according to the current language
1633 environment. To request this, set the variable
1634 @code{unibyte-display-via-language-environment} to a non-@code{nil}
1635 value. Note that setting this only affects how these bytes are
1636 displayed, but does not change the fundamental fact that Emacs treats
1637 them as raw bytes, not as characters.
1639 @cindex @code{iso-ascii} library
1640 If your terminal does not support display of the Latin-1 character
1641 set, Emacs can display these characters as @acronym{ASCII} sequences which at
1642 least give you a clear idea of what the characters are. To do this,
1643 load the library @code{iso-ascii}. Similar libraries for other
1644 Latin-@var{n} character sets could be implemented, but have not been
1647 @findex standard-display-8bit
1648 @cindex 8-bit display
1649 Normally non-ISO-8859 characters (decimal codes between 128 and 159
1650 inclusive) are displayed as octal escapes. You can change this for
1651 non-standard extended versions of ISO-8859 character sets by using the
1652 function @code{standard-display-8bit} in the @code{disp-table} library.
1654 There are two ways to input single-byte non-@acronym{ASCII}
1660 You can use an input method for the selected language environment.
1661 @xref{Input Methods}. When you use an input method in a unibyte
1662 buffer, the non-@acronym{ASCII} character you specify with it is
1663 converted to unibyte.
1666 If your keyboard can generate character codes 128 (decimal) and up,
1667 representing non-@acronym{ASCII} characters, you can type those
1668 character codes directly.
1670 On a graphical display, you should not need to do anything special to
1671 use these keys; they should simply work. On a text terminal, you
1672 should use the command @kbd{M-x set-keyboard-coding-system} or
1673 customize the variable @code{keyboard-coding-system} to specify which
1674 coding system your keyboard uses (@pxref{Terminal Coding}). Enabling
1675 this feature will probably require you to use @key{ESC} to type Meta
1676 characters; however, on a console terminal or a terminal emulator such
1677 as @code{xterm}, you can arrange for Meta to be converted to @key{ESC}
1678 and still be able to type 8-bit characters present directly on the
1679 keyboard or using @key{Compose} or @key{AltGr} keys. @xref{User Input}.
1681 @cindex @code{iso-transl} library
1682 @cindex compose character
1683 @cindex dead character
1685 You can use the key @kbd{C-x 8} as a compose-character prefix for
1686 entry of non-@acronym{ASCII} Latin-1 and a few other printing
1687 characters. @kbd{C-x 8} is good for insertion (in the minibuffer as
1688 well as other buffers), for searching, and in any other context where
1689 a key sequence is allowed.
1691 @kbd{C-x 8} works by loading the @code{iso-transl} library. Once that
1692 library is loaded, the @key{Alt} modifier key, if the keyboard has
1693 one, serves the same purpose as @kbd{C-x 8}: use @key{Alt} together
1694 with an accent character to modify the following letter. In addition,
1695 if the keyboard has keys for the Latin-1 dead accent characters,
1696 they too are defined to compose with the following character, once
1697 @code{iso-transl} is loaded.
1699 Use @kbd{C-x 8 C-h} to list all the available @kbd{C-x 8} translations.
1706 In Emacs, @dfn{charset} is short for ``character set''. Emacs
1707 supports most popular charsets (such as @code{ascii},
1708 @code{iso-8859-1}, @code{cp1250}, @code{big5}, and @code{unicode}), in
1709 addition to some charsets of its own (such as @code{emacs},
1710 @code{unicode-bmp}, and @code{eight-bit}). All supported characters
1711 belong to one or more charsets.
1713 Emacs normally does the right thing with respect to charsets, so
1714 that you don't have to worry about them. However, it is sometimes
1715 helpful to know some of the underlying details about charsets.
1717 One example is font selection (@pxref{Fonts}). Each language
1718 environment (@pxref{Language Environments}) defines a priority
1719 list for the various charsets. When searching for a font, Emacs
1720 initially attempts to find one that can display the highest-priority
1721 charsets. For instance, in the Japanese language environment, the
1722 charset @code{japanese-jisx0208} has the highest priority, so Emacs
1723 tries to use a font whose @code{registry} property is
1724 @samp{JISX0208.1983-0}.
1726 @findex list-charset-chars
1727 @cindex characters in a certain charset
1728 @findex describe-character-set
1729 There are two commands that can be used to obtain information about
1730 charsets. The command @kbd{M-x list-charset-chars} prompts for a
1731 charset name, and displays all the characters in that character set.
1732 The command @kbd{M-x describe-character-set} prompts for a charset
1733 name, and displays information about that charset, including its
1734 internal representation within Emacs.
1736 @findex list-character-sets
1737 @kbd{M-x list-character-sets} displays a list of all supported
1738 charsets. The list gives the names of charsets and additional
1739 information to identity each charset; for more details, see the
1740 @url{https://www.itscj.ipsj.or.jp/itscj_english/iso-ir/ISO-IR.pdf,
1741 ISO International Register of Coded Character Sets to be Used with
1742 Escape Sequences (ISO-IR)} maintained by
1743 the @url{https://www.itscj.ipsj.or.jp/itscj_english/,
1744 Information Processing Society of Japan/Information Technology
1745 Standards Commission of Japan (IPSJ/ITSCJ)}. In this list,
1746 charsets are divided into two categories: @dfn{normal charsets} are
1747 listed first, followed by @dfn{supplementary charsets}. A
1748 supplementary charset is one that is used to define another charset
1749 (as a parent or a subset), or to provide backward-compatibility for
1750 older Emacs versions.
1752 To find out which charset a character in the buffer belongs to, put
1753 point before it and type @kbd{C-u C-x =} (@pxref{International
1756 @node Bidirectional Editing
1757 @section Bidirectional Editing
1758 @cindex bidirectional editing
1759 @cindex right-to-left text
1761 Emacs supports editing text written in scripts, such as Arabic,
1762 Farsi, and Hebrew, whose natural ordering of horizontal text for
1763 display is from right to left. However, digits and Latin text
1764 embedded in these scripts are still displayed left to right. It is
1765 also not uncommon to have small portions of text in Arabic or Hebrew
1766 embedded in an otherwise Latin document; e.g., as comments and strings
1767 in a program source file. For these reasons, text that uses these
1768 scripts is actually @dfn{bidirectional}: a mixture of runs of
1769 left-to-right and right-to-left characters.
1771 This section describes the facilities and options provided by Emacs
1772 for editing bidirectional text.
1774 @cindex logical order
1775 @cindex visual order
1776 Emacs stores right-to-left and bidirectional text in the so-called
1777 @dfn{logical} (or @dfn{reading}) order: the buffer or string position
1778 of the first character you read precedes that of the next character.
1779 Reordering of bidirectional text into the @dfn{visual} order happens
1780 at display time. As a result, character positions no longer increase
1781 monotonically with their positions on display. Emacs implements the
1782 Unicode Bidirectional Algorithm (UBA) described in the Unicode
1783 Standard Annex #9, for reordering of bidirectional text for display.
1784 It deviates from the UBA only in how continuation lines are displayed
1785 when text direction is opposite to the base paragraph direction,
1786 e.g., when a long line of English text appears in a right-to-left
1789 @vindex bidi-display-reordering
1790 The buffer-local variable @code{bidi-display-reordering} controls
1791 whether text in the buffer is reordered for display. If its value is
1792 non-@code{nil}, Emacs reorders characters that have right-to-left
1793 directionality when they are displayed. The default value is
1796 @cindex base direction of paragraphs
1797 @cindex paragraph, base direction
1798 @vindex bidi-paragraph-start-re
1799 @vindex bidi-paragraph-separate-re
1800 Each paragraph of bidirectional text can have its own @dfn{base
1801 direction}, either right-to-left or left-to-right. Text in
1802 left-to-right paragraphs begins on the screen at the left margin of
1803 the window and is truncated or continued when it reaches the right
1804 margin. By contrast, text in right-to-left paragraphs is displayed
1805 starting at the right margin and is continued or truncated at the left
1806 margin. By default, paragraph boundaries are empty lines, i.e., lines
1807 consisting entirely of whitespace characters. To change that, you can
1808 customize the two variables @code{bidi-paragraph-start-re} and
1809 @code{bidi-paragraph-separate-re}, whose values should be regular
1810 expressions (strings); e.g., to have a single newline start a new
1811 paragraph, set both of these variables to @code{"^"}. These two
1812 variables are buffer-local (@pxref{Locals}).
1814 @vindex bidi-paragraph-direction
1815 Emacs determines the base direction of each paragraph dynamically,
1816 based on the text at the beginning of the paragraph. However,
1817 sometimes a buffer may need to force a certain base direction for its
1818 paragraphs. The variable @code{bidi-paragraph-direction}, if
1819 non-@code{nil}, disables the dynamic determination of the base
1820 direction, and instead forces all paragraphs in the buffer to have the
1821 direction specified by its buffer-local value. The value can be either
1822 @code{right-to-left} or @code{left-to-right}. Any other value is
1823 interpreted as @code{nil}.
1827 Alternatively, you can control the base direction of a paragraph by
1828 inserting special formatting characters in front of the paragraph.
1829 The special character @code{RIGHT-TO-LEFT MARK}, or @sc{rlm}, forces
1830 the right-to-left direction on the following paragraph, while
1831 @code{LEFT-TO-RIGHT MARK}, or @sc{lrm} forces the left-to-right
1832 direction. (You can use @kbd{C-x 8 @key{RET}} to insert these characters.)
1833 In a GUI session, the @sc{lrm} and @sc{rlm} characters display as very
1834 thin blank characters; on text terminals they display as blanks.
1836 Because characters are reordered for display, Emacs commands that
1837 operate in the logical order or on stretches of buffer positions may
1838 produce unusual effects. For example, the commands @kbd{C-f} and
1839 @kbd{C-b} move point in the logical order, so the cursor will
1840 sometimes jump when point traverses reordered bidirectional text.
1841 Similarly, a highlighted region covering a contiguous range of
1842 character positions may look discontinuous if the region spans
1843 reordered text. This is normal and similar to the behavior of other
1844 programs that support bidirectional text.
1846 @kindex RIGHT@r{, and bidirectional text}
1847 @kindex LEFT@r{, and bidirectional text}
1848 @findex right-char@r{, and bidirectional text}
1849 @findex left-char@r{, and bidirectional text}
1850 Cursor motion commands bound to arrow keys, such as @key{LEFT} and
1851 @kbd{C-@key{RIGHT}}, are sensitive to the base direction of the
1852 current paragraph. In a left-to-right paragraph, commands bound to
1853 @key{RIGHT} with or without modifiers move @emph{forward} through
1854 buffer text, but in a right-to-left paragraph they move
1855 @emph{backward} instead. This reflects the fact that in a
1856 right-to-left paragraph buffer positions predominantly increase when
1857 moving to the left on display.
1859 When you move out of a paragraph, the meaning of the arrow keys
1860 might change if the base direction of the preceding or the following
1861 paragraph is different from the paragraph out of which you moved.
1862 When that happens, you need to adjust the arrow key you press to the
1865 @vindex visual-order-cursor-movement
1866 @cindex cursor, visual-order motion
1867 By default, @key{LEFT} and @key{RIGHT} move in the logical order,
1868 but if @code{visual-order-cursor-movement} is non-@code{nil}, these
1869 commands move to the character that is, correspondingly, to the left
1870 or right of the current screen position, moving to the next or
1871 previous screen line as appropriate. Note that this might potentially
1872 move point many buffer positions away, depending on the surrounding
1873 bidirectional context.