In display-buffer-pop-up-frame make BUFFER current (Bug#15133).
[emacs.git] / doc / emacs / mule.texi
blobebddc46be9400fedcfde7ed18b0a1e0090aef184
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1997, 1999-2013 Free Software Foundation, Inc.
3 @c See file emacs.texi for copying conditions.
4 @node International
5 @chapter International Character Set Support
6 @c This node is referenced in the tutorial.  When renaming or deleting
7 @c it, the tutorial needs to be adjusted.  (TUTORIAL.de)
8 @cindex MULE
9 @cindex international scripts
10 @cindex multibyte characters
11 @cindex encoding of characters
13 @cindex Celtic
14 @cindex Chinese
15 @cindex Cyrillic
16 @cindex Czech
17 @cindex Devanagari
18 @cindex Hindi
19 @cindex Marathi
20 @cindex Ethiopic
21 @cindex German
22 @cindex Greek
23 @cindex Hebrew
24 @cindex IPA
25 @cindex Japanese
26 @cindex Korean
27 @cindex Lao
28 @cindex Latin
29 @cindex Polish
30 @cindex Romanian
31 @cindex Slovak
32 @cindex Slovenian
33 @cindex Thai
34 @cindex Tibetan
35 @cindex Turkish
36 @cindex Vietnamese
37 @cindex Dutch
38 @cindex Spanish
39   Emacs supports a wide variety of international character sets,
40 including European and Vietnamese variants of the Latin alphabet, as
41 well as Cyrillic, Devanagari (for Hindi and Marathi), Ethiopic, Greek,
42 Han (for Chinese and Japanese), Hangul (for Korean), Hebrew, IPA,
43 Kannada, Lao, Malayalam, Tamil, Thai, Tibetan, and Vietnamese scripts.
44 Emacs also supports various encodings of these characters that are used by
45 other internationalized software, such as word processors and mailers.
47   Emacs allows editing text with international characters by supporting
48 all the related activities:
50 @itemize @bullet
51 @item
52 You can visit files with non-@acronym{ASCII} characters, save non-@acronym{ASCII} text, and
53 pass non-@acronym{ASCII} text between Emacs and programs it invokes (such as
54 compilers, spell-checkers, and mailers).  Setting your language
55 environment (@pxref{Language Environments}) takes care of setting up the
56 coding systems and other options for a specific language or culture.
57 Alternatively, you can specify how Emacs should encode or decode text
58 for each command; see @ref{Text Coding}.
60 @item
61 You can display non-@acronym{ASCII} characters encoded by the various
62 scripts.  This works by using appropriate fonts on graphics displays
63 (@pxref{Defining Fontsets}), and by sending special codes to text
64 displays (@pxref{Terminal Coding}).  If some characters are displayed
65 incorrectly, refer to @ref{Undisplayable Characters}, which describes
66 possible problems and explains how to solve them.
68 @item
69 Characters from scripts whose natural ordering of text is from right
70 to left are reordered for display (@pxref{Bidirectional Editing}).
71 These scripts include Arabic, Hebrew, Syriac, Thaana, and a few
72 others.
74 @item
75 You can insert non-@acronym{ASCII} characters or search for them.  To do that,
76 you can specify an input method (@pxref{Select Input Method}) suitable
77 for your language, or use the default input method set up when you chose
78 your language environment.  If
79 your keyboard can produce non-@acronym{ASCII} characters, you can select an
80 appropriate keyboard coding system (@pxref{Terminal Coding}), and Emacs
81 will accept those characters.  Latin-1 characters can also be input by
82 using the @kbd{C-x 8} prefix, see @ref{Unibyte Mode}.
84 With the X Window System, your locale should be set to an appropriate
85 value to make sure Emacs interprets keyboard input correctly; see
86 @ref{Language Environments, locales}.
87 @end itemize
89   The rest of this chapter describes these issues in detail.
91 @menu
92 * International Chars::     Basic concepts of multibyte characters.
93 * Language Environments::   Setting things up for the language you use.
94 * Input Methods::           Entering text characters not on your keyboard.
95 * Select Input Method::     Specifying your choice of input methods.
96 * Coding Systems::          Character set conversion when you read and
97                               write files, and so on.
98 * Recognize Coding::        How Emacs figures out which conversion to use.
99 * Specify Coding::          Specifying a file's coding system explicitly.
100 * Output Coding::           Choosing coding systems for output.
101 * Text Coding::             Choosing conversion to use for file text.
102 * Communication Coding::    Coding systems for interprocess communication.
103 * File Name Coding::        Coding systems for file @emph{names}.
104 * Terminal Coding::         Specifying coding systems for converting
105                               terminal input and output.
106 * Fontsets::                Fontsets are collections of fonts
107                               that cover the whole spectrum of characters.
108 * Defining Fontsets::       Defining a new fontset.
109 * Modifying Fontsets::      Modifying an existing fontset.
110 * Undisplayable Characters:: When characters don't display.
111 * Unibyte Mode::            You can pick one European character set
112                               to use without multibyte characters.
113 * Charsets::                How Emacs groups its internal character codes.
114 * Bidirectional Editing::   Support for right-to-left scripts.
115 @end menu
117 @node International Chars
118 @section Introduction to International Character Sets
120   The users of international character sets and scripts have
121 established many more-or-less standard coding systems for storing
122 files.  These coding systems are typically @dfn{multibyte}, meaning
123 that sequences of two or more bytes are used to represent individual
124 non-@acronym{ASCII} characters.
126 @cindex Unicode
127   Internally, Emacs uses its own multibyte character encoding, which
128 is a superset of the @dfn{Unicode} standard.  This internal encoding
129 allows characters from almost every known script to be intermixed in a
130 single buffer or string.  Emacs translates between the multibyte
131 character encoding and various other coding systems when reading and
132 writing files, and when exchanging data with subprocesses.
134 @kindex C-h h
135 @findex view-hello-file
136 @cindex undisplayable characters
137 @cindex @samp{?} in display
138   The command @kbd{C-h h} (@code{view-hello-file}) displays the file
139 @file{etc/HELLO}, which illustrates various scripts by showing
140 how to say ``hello'' in many languages.  If some characters can't be
141 displayed on your terminal, they appear as @samp{?} or as hollow boxes
142 (@pxref{Undisplayable Characters}).
144   Keyboards, even in the countries where these character sets are
145 used, generally don't have keys for all the characters in them.  You
146 can insert characters that your keyboard does not support, using
147 @kbd{C-q} (@code{quoted-insert}) or @kbd{C-x 8 @key{RET}}
148 (@code{insert-char}).  @xref{Inserting Text}.  Emacs also supports
149 various @dfn{input methods}, typically one for each script or
150 language, which make it easier to type characters in the script.
151 @xref{Input Methods}.
153 @kindex C-x RET
154   The prefix key @kbd{C-x @key{RET}} is used for commands that pertain
155 to multibyte characters, coding systems, and input methods.
157 @kindex C-x =
158 @findex what-cursor-position
159   The command @kbd{C-x =} (@code{what-cursor-position}) shows
160 information about the character at point.  In addition to the
161 character position, which was described in @ref{Position Info}, this
162 command displays how the character is encoded.  For instance, it
163 displays the following line in the echo area for the character
164 @samp{c}:
166 @smallexample
167 Char: c (99, #o143, #x63) point=28062 of 36168 (78%) column=53
168 @end smallexample
170   The four values after @samp{Char:} describe the character that
171 follows point, first by showing it and then by giving its character
172 code in decimal, octal and hex.  For a non-@acronym{ASCII} multibyte
173 character, these are followed by @samp{file} and the character's
174 representation, in hex, in the buffer's coding system, if that coding
175 system encodes the character safely and with a single byte
176 (@pxref{Coding Systems}).  If the character's encoding is longer than
177 one byte, Emacs shows @samp{file ...}.
179   As a special case, if the character lies in the range 128 (0200
180 octal) through 159 (0237 octal), it stands for a ``raw'' byte that
181 does not correspond to any specific displayable character.  Such a
182 ``character'' lies within the @code{eight-bit-control} character set,
183 and is displayed as an escaped octal character code.  In this case,
184 @kbd{C-x =} shows @samp{part of display ...} instead of @samp{file}.
186 @cindex character set of character at point
187 @cindex font of character at point
188 @cindex text properties at point
189 @cindex face at point
190   With a prefix argument (@kbd{C-u C-x =}), this command displays a
191 detailed description of the character in a window:
193 @itemize @bullet
194 @item
195 The character set name, and the codes that identify the character
196 within that character set; @acronym{ASCII} characters are identified
197 as belonging to the @code{ascii} character set.
199 @item
200 The character's syntax and categories.
202 @item
203 The character's encodings, both internally in the buffer, and externally
204 if you were to save the file.
206 @item
207 What keys to type to input the character in the current input method
208 (if it supports the character).
210 @item
211 If you are running Emacs on a graphical display, the font name and
212 glyph code for the character.  If you are running Emacs on a text
213 terminal, the code(s) sent to the terminal.
215 @item
216 The character's text properties (@pxref{Text Properties,,,
217 elisp, the Emacs Lisp Reference Manual}), including any non-default
218 faces used to display the character, and any overlays containing it
219 (@pxref{Overlays,,, elisp, the same manual}).
220 @end itemize
222   Here's an example showing the Latin-1 character A with grave accent,
223 in a buffer whose coding system is @code{utf-8-unix}:
225 @smallexample
226              position: 1 of 1 (0%), column: 0
227             character: @`A (displayed as @`A) (codepoint 192, #o300, #xc0)
228     preferred charset: unicode (Unicode (ISO10646))
229 code point in charset: 0xC0
230                syntax: w       which means: word
231              category: .:Base, L:Left-to-right (strong),
232                        j:Japanese, l:Latin, v:Viet
233           buffer code: #xC3 #x80
234             file code: not encodable by coding system undecided-unix
235               display: by this font (glyph code)
236     xft:-unknown-DejaVu Sans Mono-normal-normal-
237         normal-*-13-*-*-*-m-0-iso10646-1 (#x82)
239 Character code properties: customize what to show
240   name: LATIN CAPITAL LETTER A WITH GRAVE
241   old-name: LATIN CAPITAL LETTER A GRAVE
242   general-category: Lu (Letter, Uppercase)
243   decomposition: (65 768) ('A' '`')
244 @end smallexample
246 @node Language Environments
247 @section Language Environments
248 @cindex language environments
250   All supported character sets are supported in Emacs buffers whenever
251 multibyte characters are enabled; there is no need to select a
252 particular language in order to display its characters.
253 However, it is important to select a @dfn{language
254 environment} in order to set various defaults.  Roughly speaking, the
255 language environment represents a choice of preferred script rather
256 than a choice of language.
258   The language environment controls which coding systems to recognize
259 when reading text (@pxref{Recognize Coding}).  This applies to files,
260 incoming mail, and any other text you read into Emacs.  It may also
261 specify the default coding system to use when you create a file.  Each
262 language environment also specifies a default input method.
264 @findex set-language-environment
265 @vindex current-language-environment
266   To select a language environment, customize
267 @code{current-language-environment} or use the command @kbd{M-x
268 set-language-environment}.  It makes no difference which buffer is
269 current when you use this command, because the effects apply globally
270 to the Emacs session.  The supported language environments
271 (see the variable @code{language-info-alist}) include:
273 @cindex Euro sign
274 @cindex UTF-8
275 @quotation
276 ASCII, Belarusian, Bengali, Brazilian Portuguese, Bulgarian, Cham,
277 Chinese-BIG5, Chinese-CNS, Chinese-EUC-TW, Chinese-GB, Chinese-GBK,
278 Chinese-GB18030, Croatian, Cyrillic-ALT, Cyrillic-ISO, Cyrillic-KOI8,
279 Czech, Devanagari, Dutch, English, Esperanto, Ethiopic, French,
280 Georgian, German, Greek, Gujarati, Hebrew, IPA, Italian, Japanese,
281 Kannada, Khmer, Korean, Lao, Latin-1, Latin-2, Latin-3, Latin-4,
282 Latin-5, Latin-6, Latin-7, Latin-8 (Celtic), Latin-9 (updated Latin-1
283 with the Euro sign), Latvian, Lithuanian, Malayalam, Oriya, Polish,
284 Punjabi, Romanian, Russian, Sinhala, Slovak, Slovenian, Spanish,
285 Swedish, TaiViet, Tajik, Tamil, Telugu, Thai, Tibetan, Turkish, UTF-8
286 (for a setup which prefers Unicode characters and files encoded in
287 UTF-8), Ukrainian, Vietnamese, Welsh, and Windows-1255 (for a setup
288 which prefers Cyrillic characters and files encoded in Windows-1255).
289 @end quotation
291   To display the script(s) used by your language environment on a
292 graphical display, you need to have suitable fonts.
293 @xref{Fontsets}, for more details about setting up your fonts.
295 @findex set-locale-environment
296 @vindex locale-language-names
297 @vindex locale-charset-language-names
298 @cindex locales
299   Some operating systems let you specify the character-set locale you
300 are using by setting the locale environment variables @env{LC_ALL},
301 @env{LC_CTYPE}, or @env{LANG}.  (If more than one of these is
302 set, the first one that is nonempty specifies your locale for this
303 purpose.)  During startup, Emacs looks up your character-set locale's
304 name in the system locale alias table, matches its canonical name
305 against entries in the value of the variables
306 @code{locale-charset-language-names} and @code{locale-language-names}
307 (the former overrides the latter),
308 and selects the corresponding language environment if a match is found.
309 It also adjusts the display
310 table and terminal coding system, the locale coding system, the
311 preferred coding system as needed for the locale, and---last but not
312 least---the way Emacs decodes non-@acronym{ASCII} characters sent by your keyboard.
314 @c This seems unlikely, doesn't it?
315   If you modify the @env{LC_ALL}, @env{LC_CTYPE}, or @env{LANG}
316 environment variables while running Emacs (by using @kbd{M-x setenv}),
317 you may want to invoke the @code{set-locale-environment}
318 function afterwards to readjust the language environment from the new
319 locale.
321 @vindex locale-preferred-coding-systems
322   The @code{set-locale-environment} function normally uses the preferred
323 coding system established by the language environment to decode system
324 messages.  But if your locale matches an entry in the variable
325 @code{locale-preferred-coding-systems}, Emacs uses the corresponding
326 coding system instead.  For example, if the locale @samp{ja_JP.PCK}
327 matches @code{japanese-shift-jis} in
328 @code{locale-preferred-coding-systems}, Emacs uses that encoding even
329 though it might normally use @code{japanese-iso-8bit}.
331   You can override the language environment chosen at startup with
332 explicit use of the command @code{set-language-environment}, or with
333 customization of @code{current-language-environment} in your init
334 file.
336 @kindex C-h L
337 @findex describe-language-environment
338   To display information about the effects of a certain language
339 environment @var{lang-env}, use the command @kbd{C-h L @var{lang-env}
340 @key{RET}} (@code{describe-language-environment}).  This tells you
341 which languages this language environment is useful for, and lists the
342 character sets, coding systems, and input methods that go with it.  It
343 also shows some sample text to illustrate scripts used in this
344 language environment.  If you give an empty input for @var{lang-env},
345 this command describes the chosen language environment.
346 @anchor{Describe Language Environment}
348 @vindex set-language-environment-hook
349   You can customize any language environment with the normal hook
350 @code{set-language-environment-hook}.  The command
351 @code{set-language-environment} runs that hook after setting up the new
352 language environment.  The hook functions can test for a specific
353 language environment by checking the variable
354 @code{current-language-environment}.  This hook is where you should
355 put non-default settings for specific language environments, such as
356 coding systems for keyboard input and terminal output, the default
357 input method, etc.
359 @vindex exit-language-environment-hook
360   Before it starts to set up the new language environment,
361 @code{set-language-environment} first runs the hook
362 @code{exit-language-environment-hook}.  This hook is useful for undoing
363 customizations that were made with @code{set-language-environment-hook}.
364 For instance, if you set up a special key binding in a specific language
365 environment using @code{set-language-environment-hook}, you should set
366 up @code{exit-language-environment-hook} to restore the normal binding
367 for that key.
369 @node Input Methods
370 @section Input Methods
372 @cindex input methods
373   An @dfn{input method} is a kind of character conversion designed
374 specifically for interactive input.  In Emacs, typically each language
375 has its own input method; sometimes several languages that use the same
376 characters can share one input method.  A few languages support several
377 input methods.
379   The simplest kind of input method works by mapping @acronym{ASCII} letters
380 into another alphabet; this allows you to use one other alphabet
381 instead of @acronym{ASCII}.  The Greek and Russian input methods
382 work this way.
384   A more powerful technique is composition: converting sequences of
385 characters into one letter.  Many European input methods use composition
386 to produce a single non-@acronym{ASCII} letter from a sequence that consists of a
387 letter followed by accent characters (or vice versa).  For example, some
388 methods convert the sequence @kbd{o ^} into a single accented letter.
389 These input methods have no special commands of their own; all they do
390 is compose sequences of printing characters.
392   The input methods for syllabic scripts typically use mapping followed
393 by composition.  The input methods for Thai and Korean work this way.
394 First, letters are mapped into symbols for particular sounds or tone
395 marks; then, sequences of these that make up a whole syllable are
396 mapped into one syllable sign.
398   Chinese and Japanese require more complex methods.  In Chinese input
399 methods, first you enter the phonetic spelling of a Chinese word (in
400 input method @code{chinese-py}, among others), or a sequence of
401 portions of the character (input methods @code{chinese-4corner} and
402 @code{chinese-sw}, and others).  One input sequence typically
403 corresponds to many possible Chinese characters.  You select the one
404 you mean using keys such as @kbd{C-f}, @kbd{C-b}, @kbd{C-n},
405 @kbd{C-p} (or the arrow keys), and digits, which have special meanings
406 in this situation.
408   The possible characters are conceptually arranged in several rows,
409 with each row holding up to 10 alternatives.  Normally, Emacs displays
410 just one row at a time, in the echo area; @code{(@var{i}/@var{j})}
411 appears at the beginning, to indicate that this is the @var{i}th row
412 out of a total of @var{j} rows.  Type @kbd{C-n} or @kbd{C-p} to
413 display the next row or the previous row.
415     Type @kbd{C-f} and @kbd{C-b} to move forward and backward among
416 the alternatives in the current row.  As you do this, Emacs highlights
417 the current alternative with a special color; type @code{C-@key{SPC}}
418 to select the current alternative and use it as input.  The
419 alternatives in the row are also numbered; the number appears before
420 the alternative.  Typing a number selects the associated alternative
421 of the current row and uses it as input.
423   @key{TAB} in these Chinese input methods displays a buffer showing
424 all the possible characters at once; then clicking @kbd{Mouse-2} on
425 one of them selects that alternative.  The keys @kbd{C-f}, @kbd{C-b},
426 @kbd{C-n}, @kbd{C-p}, and digits continue to work as usual, but they
427 do the highlighting in the buffer showing the possible characters,
428 rather than in the echo area.
430   In Japanese input methods, first you input a whole word using
431 phonetic spelling; then, after the word is in the buffer, Emacs
432 converts it into one or more characters using a large dictionary.  One
433 phonetic spelling corresponds to a number of different Japanese words;
434 to select one of them, use @kbd{C-n} and @kbd{C-p} to cycle through
435 the alternatives.
437   Sometimes it is useful to cut off input method processing so that the
438 characters you have just entered will not combine with subsequent
439 characters.  For example, in input method @code{latin-1-postfix}, the
440 sequence @kbd{o ^} combines to form an @samp{o} with an accent.  What if
441 you want to enter them as separate characters?
443   One way is to type the accent twice; this is a special feature for
444 entering the separate letter and accent.  For example, @kbd{o ^ ^} gives
445 you the two characters @samp{o^}.  Another way is to type another letter
446 after the @kbd{o}---something that won't combine with that---and
447 immediately delete it.  For example, you could type @kbd{o o @key{DEL}
448 ^} to get separate @samp{o} and @samp{^}.
450   Another method, more general but not quite as easy to type, is to use
451 @kbd{C-\ C-\} between two characters to stop them from combining.  This
452 is the command @kbd{C-\} (@code{toggle-input-method}) used twice.
453 @ifnottex
454 @xref{Select Input Method}.
455 @end ifnottex
457 @cindex incremental search, input method interference
458   @kbd{C-\ C-\} is especially useful inside an incremental search,
459 because it stops waiting for more characters to combine, and starts
460 searching for what you have already entered.
462   To find out how to input the character after point using the current
463 input method, type @kbd{C-u C-x =}.  @xref{Position Info}.
465 @vindex input-method-verbose-flag
466 @vindex input-method-highlight-flag
467   The variables @code{input-method-highlight-flag} and
468 @code{input-method-verbose-flag} control how input methods explain
469 what is happening.  If @code{input-method-highlight-flag} is
470 non-@code{nil}, the partial sequence is highlighted in the buffer (for
471 most input methods---some disable this feature).  If
472 @code{input-method-verbose-flag} is non-@code{nil}, the list of
473 possible characters to type next is displayed in the echo area (but
474 not when you are in the minibuffer).
476   Another facility for typing characters not on your keyboard is by
477 using @kbd{C-x 8 @key{RET}} (@code{insert-char}) to insert a single
478 character based on its Unicode name or code-point; see @ref{Inserting
479 Text}.
481 @node Select Input Method
482 @section Selecting an Input Method
484 @table @kbd
485 @item C-\
486 Enable or disable use of the selected input method (@code{toggle-input-method}).
488 @item C-x @key{RET} C-\ @var{method} @key{RET}
489 Select a new input method for the current buffer (@code{set-input-method}).
491 @item C-h I @var{method} @key{RET}
492 @itemx C-h C-\ @var{method} @key{RET}
493 @findex describe-input-method
494 @kindex C-h I
495 @kindex C-h C-\
496 Describe the input method @var{method} (@code{describe-input-method}).
497 By default, it describes the current input method (if any).  This
498 description should give you the full details of how to use any
499 particular input method.
501 @item M-x list-input-methods
502 Display a list of all the supported input methods.
503 @end table
505 @findex set-input-method
506 @vindex current-input-method
507 @kindex C-x RET C-\
508   To choose an input method for the current buffer, use @kbd{C-x
509 @key{RET} C-\} (@code{set-input-method}).  This command reads the
510 input method name from the minibuffer; the name normally starts with the
511 language environment that it is meant to be used with.  The variable
512 @code{current-input-method} records which input method is selected.
514 @findex toggle-input-method
515 @kindex C-\
516   Input methods use various sequences of @acronym{ASCII} characters to
517 stand for non-@acronym{ASCII} characters.  Sometimes it is useful to
518 turn off the input method temporarily.  To do this, type @kbd{C-\}
519 (@code{toggle-input-method}).  To reenable the input method, type
520 @kbd{C-\} again.
522   If you type @kbd{C-\} and you have not yet selected an input method,
523 it prompts you to specify one.  This has the same effect as using
524 @kbd{C-x @key{RET} C-\} to specify an input method.
526   When invoked with a numeric argument, as in @kbd{C-u C-\},
527 @code{toggle-input-method} always prompts you for an input method,
528 suggesting the most recently selected one as the default.
530 @vindex default-input-method
531   Selecting a language environment specifies a default input method for
532 use in various buffers.  When you have a default input method, you can
533 select it in the current buffer by typing @kbd{C-\}.  The variable
534 @code{default-input-method} specifies the default input method
535 (@code{nil} means there is none).
537   In some language environments, which support several different input
538 methods, you might want to use an input method different from the
539 default chosen by @code{set-language-environment}.  You can instruct
540 Emacs to select a different default input method for a certain
541 language environment, if you wish, by using
542 @code{set-language-environment-hook} (@pxref{Language Environments,
543 set-language-environment-hook}).  For example:
545 @lisp
546 (defun my-chinese-setup ()
547   "Set up my private Chinese environment."
548   (if (equal current-language-environment "Chinese-GB")
549       (setq default-input-method "chinese-tonepy")))
550 (add-hook 'set-language-environment-hook 'my-chinese-setup)
551 @end lisp
553 @noindent
554 This sets the default input method to be @code{chinese-tonepy}
555 whenever you choose a Chinese-GB language environment.
557 You can instruct Emacs to activate a certain input method
558 automatically.  For example:
560 @lisp
561 (add-hook 'text-mode-hook
562   (lambda () (set-input-method "german-prefix")))
563 @end lisp
565 @noindent
566 This automatically activates the input method ``german-prefix'' in
567 Text mode.
569 @findex quail-set-keyboard-layout
570   Some input methods for alphabetic scripts work by (in effect)
571 remapping the keyboard to emulate various keyboard layouts commonly used
572 for those scripts.  How to do this remapping properly depends on your
573 actual keyboard layout.  To specify which layout your keyboard has, use
574 the command @kbd{M-x quail-set-keyboard-layout}.
576 @findex quail-show-key
577   You can use the command @kbd{M-x quail-show-key} to show what key (or
578 key sequence) to type in order to input the character following point,
579 using the selected keyboard layout.  The command @kbd{C-u C-x =} also
580 shows that information, in addition to other information about the
581 character.
583 @findex list-input-methods
584   @kbd{M-x list-input-methods} displays a list of all the supported
585 input methods.  The list gives information about each input method,
586 including the string that stands for it in the mode line.
588 @node Coding Systems
589 @section Coding Systems
590 @cindex coding systems
592   Users of various languages have established many more-or-less standard
593 coding systems for representing them.  Emacs does not use these coding
594 systems internally; instead, it converts from various coding systems to
595 its own system when reading data, and converts the internal coding
596 system to other coding systems when writing data.  Conversion is
597 possible in reading or writing files, in sending or receiving from the
598 terminal, and in exchanging data with subprocesses.
600   Emacs assigns a name to each coding system.  Most coding systems are
601 used for one language, and the name of the coding system starts with
602 the language name.  Some coding systems are used for several
603 languages; their names usually start with @samp{iso}.  There are also
604 special coding systems, such as @code{no-conversion}, @code{raw-text},
605 and @code{emacs-internal}.
607 @cindex international files from DOS/Windows systems
608   A special class of coding systems, collectively known as
609 @dfn{codepages}, is designed to support text encoded by MS-Windows and
610 MS-DOS software.  The names of these coding systems are
611 @code{cp@var{nnnn}}, where @var{nnnn} is a 3- or 4-digit number of the
612 codepage.  You can use these encodings just like any other coding
613 system; for example, to visit a file encoded in codepage 850, type
614 @kbd{C-x @key{RET} c cp850 @key{RET} C-x C-f @var{filename}
615 @key{RET}}.
617   In addition to converting various representations of non-@acronym{ASCII}
618 characters, a coding system can perform end-of-line conversion.  Emacs
619 handles three different conventions for how to separate lines in a file:
620 newline (``unix''), carriage-return linefeed (``dos''), and just
621 carriage-return (``mac'').
623 @table @kbd
624 @item C-h C @var{coding} @key{RET}
625 Describe coding system @var{coding} (@code{describe-coding-system}).
627 @item C-h C @key{RET}
628 Describe the coding systems currently in use.
630 @item M-x list-coding-systems
631 Display a list of all the supported coding systems.
632 @end table
634 @kindex C-h C
635 @findex describe-coding-system
636   The command @kbd{C-h C} (@code{describe-coding-system}) displays
637 information about particular coding systems, including the end-of-line
638 conversion specified by those coding systems.  You can specify a coding
639 system name as the argument; alternatively, with an empty argument, it
640 describes the coding systems currently selected for various purposes,
641 both in the current buffer and as the defaults, and the priority list
642 for recognizing coding systems (@pxref{Recognize Coding}).
644 @findex list-coding-systems
645   To display a list of all the supported coding systems, type @kbd{M-x
646 list-coding-systems}.  The list gives information about each coding
647 system, including the letter that stands for it in the mode line
648 (@pxref{Mode Line}).
650 @cindex end-of-line conversion
651 @cindex line endings
652 @cindex MS-DOS end-of-line conversion
653 @cindex Macintosh end-of-line conversion
654   Each of the coding systems that appear in this list---except for
655 @code{no-conversion}, which means no conversion of any kind---specifies
656 how and whether to convert printing characters, but leaves the choice of
657 end-of-line conversion to be decided based on the contents of each file.
658 For example, if the file appears to use the sequence carriage-return
659 linefeed to separate lines, DOS end-of-line conversion will be used.
661   Each of the listed coding systems has three variants, which specify
662 exactly what to do for end-of-line conversion:
664 @table @code
665 @item @dots{}-unix
666 Don't do any end-of-line conversion; assume the file uses
667 newline to separate lines.  (This is the convention normally used
668 on Unix and GNU systems, and Mac OS X.)
670 @item @dots{}-dos
671 Assume the file uses carriage-return linefeed to separate lines, and do
672 the appropriate conversion.  (This is the convention normally used on
673 Microsoft systems.@footnote{It is also specified for MIME @samp{text/*}
674 bodies and in other network transport contexts.  It is different
675 from the SGML reference syntax record-start/record-end format, which
676 Emacs doesn't support directly.})
678 @item @dots{}-mac
679 Assume the file uses carriage-return to separate lines, and do the
680 appropriate conversion.  (This was the convention used on the
681 Macintosh system prior to OS X.)
682 @end table
684   These variant coding systems are omitted from the
685 @code{list-coding-systems} display for brevity, since they are entirely
686 predictable.  For example, the coding system @code{iso-latin-1} has
687 variants @code{iso-latin-1-unix}, @code{iso-latin-1-dos} and
688 @code{iso-latin-1-mac}.
690 @cindex @code{undecided}, coding system
691   The coding systems @code{unix}, @code{dos}, and @code{mac} are
692 aliases for @code{undecided-unix}, @code{undecided-dos}, and
693 @code{undecided-mac}, respectively.  These coding systems specify only
694 the end-of-line conversion, and leave the character code conversion to
695 be deduced from the text itself.
697 @cindex @code{raw-text}, coding system
698   The coding system @code{raw-text} is good for a file which is mainly
699 @acronym{ASCII} text, but may contain byte values above 127 that are
700 not meant to encode non-@acronym{ASCII} characters.  With
701 @code{raw-text}, Emacs copies those byte values unchanged, and sets
702 @code{enable-multibyte-characters} to @code{nil} in the current buffer
703 so that they will be interpreted properly.  @code{raw-text} handles
704 end-of-line conversion in the usual way, based on the data
705 encountered, and has the usual three variants to specify the kind of
706 end-of-line conversion to use.
708 @cindex @code{no-conversion}, coding system
709   In contrast, the coding system @code{no-conversion} specifies no
710 character code conversion at all---none for non-@acronym{ASCII} byte values and
711 none for end of line.  This is useful for reading or writing binary
712 files, tar files, and other files that must be examined verbatim.  It,
713 too, sets @code{enable-multibyte-characters} to @code{nil}.
715   The easiest way to edit a file with no conversion of any kind is with
716 the @kbd{M-x find-file-literally} command.  This uses
717 @code{no-conversion}, and also suppresses other Emacs features that
718 might convert the file contents before you see them.  @xref{Visiting}.
720 @cindex @code{emacs-internal}, coding system
721   The coding system @code{emacs-internal} (or @code{utf-8-emacs},
722 which is equivalent) means that the file contains non-@acronym{ASCII}
723 characters stored with the internal Emacs encoding.  This coding
724 system handles end-of-line conversion based on the data encountered,
725 and has the usual three variants to specify the kind of end-of-line
726 conversion.
728 @node Recognize Coding
729 @section Recognizing Coding Systems
731   Whenever Emacs reads a given piece of text, it tries to recognize
732 which coding system to use.  This applies to files being read, output
733 from subprocesses, text from X selections, etc.  Emacs can select the
734 right coding system automatically most of the time---once you have
735 specified your preferences.
737   Some coding systems can be recognized or distinguished by which byte
738 sequences appear in the data.  However, there are coding systems that
739 cannot be distinguished, not even potentially.  For example, there is no
740 way to distinguish between Latin-1 and Latin-2; they use the same byte
741 values with different meanings.
743   Emacs handles this situation by means of a priority list of coding
744 systems.  Whenever Emacs reads a file, if you do not specify the coding
745 system to use, Emacs checks the data against each coding system,
746 starting with the first in priority and working down the list, until it
747 finds a coding system that fits the data.  Then it converts the file
748 contents assuming that they are represented in this coding system.
750   The priority list of coding systems depends on the selected language
751 environment (@pxref{Language Environments}).  For example, if you use
752 French, you probably want Emacs to prefer Latin-1 to Latin-2; if you use
753 Czech, you probably want Latin-2 to be preferred.  This is one of the
754 reasons to specify a language environment.
756 @findex prefer-coding-system
757   However, you can alter the coding system priority list in detail
758 with the command @kbd{M-x prefer-coding-system}.  This command reads
759 the name of a coding system from the minibuffer, and adds it to the
760 front of the priority list, so that it is preferred to all others.  If
761 you use this command several times, each use adds one element to the
762 front of the priority list.
764   If you use a coding system that specifies the end-of-line conversion
765 type, such as @code{iso-8859-1-dos}, what this means is that Emacs
766 should attempt to recognize @code{iso-8859-1} with priority, and should
767 use DOS end-of-line conversion when it does recognize @code{iso-8859-1}.
769 @vindex file-coding-system-alist
770   Sometimes a file name indicates which coding system to use for the
771 file.  The variable @code{file-coding-system-alist} specifies this
772 correspondence.  There is a special function
773 @code{modify-coding-system-alist} for adding elements to this list.  For
774 example, to read and write all @samp{.txt} files using the coding system
775 @code{chinese-iso-8bit}, you can execute this Lisp expression:
777 @smallexample
778 (modify-coding-system-alist 'file "\\.txt\\'" 'chinese-iso-8bit)
779 @end smallexample
781 @noindent
782 The first argument should be @code{file}, the second argument should be
783 a regular expression that determines which files this applies to, and
784 the third argument says which coding system to use for these files.
786 @vindex inhibit-eol-conversion
787 @cindex DOS-style end-of-line display
788   Emacs recognizes which kind of end-of-line conversion to use based on
789 the contents of the file: if it sees only carriage-returns, or only
790 carriage-return linefeed sequences, then it chooses the end-of-line
791 conversion accordingly.  You can inhibit the automatic use of
792 end-of-line conversion by setting the variable @code{inhibit-eol-conversion}
793 to non-@code{nil}.  If you do that, DOS-style files will be displayed
794 with the @samp{^M} characters visible in the buffer; some people
795 prefer this to the more subtle @samp{(DOS)} end-of-line type
796 indication near the left edge of the mode line (@pxref{Mode Line,
797 eol-mnemonic}).
799 @vindex inhibit-iso-escape-detection
800 @cindex escape sequences in files
801   By default, the automatic detection of coding system is sensitive to
802 escape sequences.  If Emacs sees a sequence of characters that begin
803 with an escape character, and the sequence is valid as an ISO-2022
804 code, that tells Emacs to use one of the ISO-2022 encodings to decode
805 the file.
807   However, there may be cases that you want to read escape sequences
808 in a file as is.  In such a case, you can set the variable
809 @code{inhibit-iso-escape-detection} to non-@code{nil}.  Then the code
810 detection ignores any escape sequences, and never uses an ISO-2022
811 encoding.  The result is that all escape sequences become visible in
812 the buffer.
814   The default value of @code{inhibit-iso-escape-detection} is
815 @code{nil}.  We recommend that you not change it permanently, only for
816 one specific operation.  That's because some Emacs Lisp source files
817 in the Emacs distribution contain non-@acronym{ASCII} characters encoded in the
818 coding system @code{iso-2022-7bit}, and they won't be
819 decoded correctly when you visit those files if you suppress the
820 escape sequence detection.
821 @c I count a grand total of 3 such files, so is the above really true?
823 @vindex auto-coding-alist
824 @vindex auto-coding-regexp-alist
825   The variables @code{auto-coding-alist} and
826 @code{auto-coding-regexp-alist} are
827 the strongest way to specify the coding system for certain patterns of
828 file names, or for files containing certain patterns, respectively.
829 These variables even override @samp{-*-coding:-*-} tags in the file
830 itself (@pxref{Specify Coding}).  For example, Emacs
831 uses @code{auto-coding-alist} for tar and archive files, to prevent it
832 from being confused by a @samp{-*-coding:-*-} tag in a member of the
833 archive and thinking it applies to the archive file as a whole.
834 @ignore
835 @c This describes old-style BABYL files, which are no longer relevant.
836 Likewise, Emacs uses @code{auto-coding-regexp-alist} to ensure that
837 RMAIL files, whose names in general don't match any particular
838 pattern, are decoded correctly.
839 @end ignore
841 @vindex auto-coding-functions
842   Another way to specify a coding system is with the variable
843 @code{auto-coding-functions}.  For example, one of the builtin
844 @code{auto-coding-functions} detects the encoding for XML files.
845 Unlike the previous two, this variable does not override any
846 @samp{-*-coding:-*-} tag.
848 @node Specify Coding
849 @section Specifying a File's Coding System
851   If Emacs recognizes the encoding of a file incorrectly, you can
852 reread the file using the correct coding system with @kbd{C-x
853 @key{RET} r} (@code{revert-buffer-with-coding-system}).  This command
854 prompts for the coding system to use.  To see what coding system Emacs
855 actually used to decode the file, look at the coding system mnemonic
856 letter near the left edge of the mode line (@pxref{Mode Line}), or
857 type @kbd{C-h C} (@code{describe-coding-system}).
859 @vindex coding
860   You can specify the coding system for a particular file in the file
861 itself, using the @w{@samp{-*-@dots{}-*-}} construct at the beginning,
862 or a local variables list at the end (@pxref{File Variables}).  You do
863 this by defining a value for the ``variable'' named @code{coding}.
864 Emacs does not really have a variable @code{coding}; instead of
865 setting a variable, this uses the specified coding system for the
866 file.  For example, @samp{-*-mode: C; coding: latin-1;-*-} specifies
867 use of the Latin-1 coding system, as well as C mode.  When you specify
868 the coding explicitly in the file, that overrides
869 @code{file-coding-system-alist}.
871 @node Output Coding
872 @section Choosing Coding Systems for Output
874 @vindex buffer-file-coding-system
875   Once Emacs has chosen a coding system for a buffer, it stores that
876 coding system in @code{buffer-file-coding-system}.  That makes it the
877 default for operations that write from this buffer into a file, such
878 as @code{save-buffer} and @code{write-region}.  You can specify a
879 different coding system for further file output from the buffer using
880 @code{set-buffer-file-coding-system} (@pxref{Text Coding}).
882   You can insert any character Emacs supports into any Emacs buffer,
883 but most coding systems can only handle a subset of these characters.
884 Therefore, it's possible that the characters you insert cannot be
885 encoded with the coding system that will be used to save the buffer.
886 For example, you could visit a text file in Polish, encoded in
887 @code{iso-8859-2}, and add some Russian words to it.  When you save
888 that buffer, Emacs cannot use the current value of
889 @code{buffer-file-coding-system}, because the characters you added
890 cannot be encoded by that coding system.
892   When that happens, Emacs tries the most-preferred coding system (set
893 by @kbd{M-x prefer-coding-system} or @kbd{M-x
894 set-language-environment}).  If that coding system can safely encode
895 all of the characters in the buffer, Emacs uses it, and stores its
896 value in @code{buffer-file-coding-system}.  Otherwise, Emacs displays
897 a list of coding systems suitable for encoding the buffer's contents,
898 and asks you to choose one of those coding systems.
900   If you insert the unsuitable characters in a mail message, Emacs
901 behaves a bit differently.  It additionally checks whether the
902 @c What determines this?
903 most-preferred coding system is recommended for use in MIME messages;
904 if not, it informs you of this fact and prompts you for another coding
905 system.  This is so you won't inadvertently send a message encoded in
906 a way that your recipient's mail software will have difficulty
907 decoding.  (You can still use an unsuitable coding system if you enter
908 its name at the prompt.)
910 @c It seems that select-message-coding-system does this.
911 @c Both sendmail.el and smptmail.el call it; i.e., smtpmail.el still
912 @c obeys sendmail-coding-system.
913 @vindex sendmail-coding-system
914   When you send a mail message (@pxref{Sending Mail}),
915 Emacs has four different ways to determine the coding system to use
916 for encoding the message text.  It tries the buffer's own value of
917 @code{buffer-file-coding-system}, if that is non-@code{nil}.
918 Otherwise, it uses the value of @code{sendmail-coding-system}, if that
919 is non-@code{nil}.  The third way is to use the default coding system
920 for new files, which is controlled by your choice of language
921 @c i.e., default-sendmail-coding-system
922 environment, if that is non-@code{nil}.  If all of these three values
923 are @code{nil}, Emacs encodes outgoing mail using the Latin-1 coding
924 system.
925 @c FIXME?  Where does the Latin-1 default come in?
927 @node Text Coding
928 @section Specifying a Coding System for File Text
930   In cases where Emacs does not automatically choose the right coding
931 system for a file's contents, you can use these commands to specify
932 one:
934 @table @kbd
935 @item C-x @key{RET} f @var{coding} @key{RET}
936 Use coding system @var{coding} to save or revisit the file in
937 the current buffer (@code{set-buffer-file-coding-system}).
939 @item C-x @key{RET} c @var{coding} @key{RET}
940 Specify coding system @var{coding} for the immediately following
941 command (@code{universal-coding-system-argument}).
943 @item C-x @key{RET} r @var{coding} @key{RET}
944 Revisit the current file using the coding system @var{coding}
945 (@code{revert-buffer-with-coding-system}).
947 @item M-x recode-region @key{RET} @var{right} @key{RET} @var{wrong} @key{RET}
948 Convert a region that was decoded using coding system @var{wrong},
949 decoding it using coding system @var{right} instead.
950 @end table
952 @kindex C-x RET f
953 @findex set-buffer-file-coding-system
954   The command @kbd{C-x @key{RET} f}
955 (@code{set-buffer-file-coding-system}) sets the file coding system for
956 the current buffer (i.e., the coding system to use when saving or
957 reverting the file).  You specify which coding system using the
958 minibuffer.  You can also invoke this command by clicking with
959 @kbd{Mouse-3} on the coding system indicator in the mode line
960 (@pxref{Mode Line}).
962   If you specify a coding system that cannot handle all the characters
963 in the buffer, Emacs will warn you about the troublesome characters,
964 and ask you to choose another coding system, when you try to save the
965 buffer (@pxref{Output Coding}).
967 @cindex specify end-of-line conversion
968   You can also use this command to specify the end-of-line conversion
969 (@pxref{Coding Systems, end-of-line conversion}) for encoding the
970 current buffer.  For example, @kbd{C-x @key{RET} f dos @key{RET}} will
971 cause Emacs to save the current buffer's text with DOS-style
972 carriage-return linefeed line endings.
974 @kindex C-x RET c
975 @findex universal-coding-system-argument
976   Another way to specify the coding system for a file is when you visit
977 the file.  First use the command @kbd{C-x @key{RET} c}
978 (@code{universal-coding-system-argument}); this command uses the
979 minibuffer to read a coding system name.  After you exit the minibuffer,
980 the specified coding system is used for @emph{the immediately following
981 command}.
983   So if the immediately following command is @kbd{C-x C-f}, for example,
984 it reads the file using that coding system (and records the coding
985 system for when you later save the file).  Or if the immediately following
986 command is @kbd{C-x C-w}, it writes the file using that coding system.
987 When you specify the coding system for saving in this way, instead
988 of with @kbd{C-x @key{RET} f}, there is no warning if the buffer
989 contains characters that the coding system cannot handle.
991   Other file commands affected by a specified coding system include
992 @kbd{C-x i} and @kbd{C-x C-v}, as well as the other-window variants
993 of @kbd{C-x C-f}.  @kbd{C-x @key{RET} c} also affects commands that
994 start subprocesses, including @kbd{M-x shell} (@pxref{Shell}).  If the
995 immediately following command does not use the coding system, then
996 @kbd{C-x @key{RET} c} ultimately has no effect.
998   An easy way to visit a file with no conversion is with the @kbd{M-x
999 find-file-literally} command.  @xref{Visiting}.
1001   The default value of the variable @code{buffer-file-coding-system}
1002 specifies the choice of coding system to use when you create a new file.
1003 It applies when you find a new file, and when you create a buffer and
1004 then save it in a file.  Selecting a language environment typically sets
1005 this variable to a good choice of default coding system for that language
1006 environment.
1008 @kindex C-x RET r
1009 @findex revert-buffer-with-coding-system
1010   If you visit a file with a wrong coding system, you can correct this
1011 with @kbd{C-x @key{RET} r} (@code{revert-buffer-with-coding-system}).
1012 This visits the current file again, using a coding system you specify.
1014 @findex recode-region
1015   If a piece of text has already been inserted into a buffer using the
1016 wrong coding system, you can redo the decoding of it using @kbd{M-x
1017 recode-region}.  This prompts you for the proper coding system, then
1018 for the wrong coding system that was actually used, and does the
1019 conversion.  It first encodes the region using the wrong coding system,
1020 then decodes it again using the proper coding system.
1022 @node Communication Coding
1023 @section Coding Systems for Interprocess Communication
1025   This section explains how to specify coding systems for use
1026 in communication with other processes.
1028 @table @kbd
1029 @item C-x @key{RET} x @var{coding} @key{RET}
1030 Use coding system @var{coding} for transferring selections to and from
1031 other graphical applications (@code{set-selection-coding-system}).
1033 @item C-x @key{RET} X @var{coding} @key{RET}
1034 Use coding system @var{coding} for transferring @emph{one}
1035 selection---the next one---to or from another graphical application
1036 (@code{set-next-selection-coding-system}).
1038 @item C-x @key{RET} p @var{input-coding} @key{RET} @var{output-coding} @key{RET}
1039 Use coding systems @var{input-coding} and @var{output-coding} for
1040 subprocess input and output in the current buffer
1041 (@code{set-buffer-process-coding-system}).
1042 @end table
1044 @kindex C-x RET x
1045 @kindex C-x RET X
1046 @findex set-selection-coding-system
1047 @findex set-next-selection-coding-system
1048   The command @kbd{C-x @key{RET} x} (@code{set-selection-coding-system})
1049 specifies the coding system for sending selected text to other windowing
1050 applications, and for receiving the text of selections made in other
1051 applications.  This command applies to all subsequent selections, until
1052 you override it by using the command again.  The command @kbd{C-x
1053 @key{RET} X} (@code{set-next-selection-coding-system}) specifies the
1054 coding system for the next selection made in Emacs or read by Emacs.
1056 @vindex x-select-request-type
1057   The variable @code{x-select-request-type} specifies the data type to
1058 request from the X Window System for receiving text selections from
1059 other applications.  If the value is @code{nil} (the default), Emacs
1060 tries @code{UTF8_STRING} and @code{COMPOUND_TEXT}, in this order, and
1061 uses various heuristics to choose the more appropriate of the two
1062 results; if none of these succeed, Emacs falls back on @code{STRING}.
1063 If the value of @code{x-select-request-type} is one of the symbols
1064 @code{COMPOUND_TEXT}, @code{UTF8_STRING}, @code{STRING}, or
1065 @code{TEXT}, Emacs uses only that request type.  If the value is a
1066 list of some of these symbols, Emacs tries only the request types in
1067 the list, in order, until one of them succeeds, or until the list is
1068 exhausted.
1070 @kindex C-x RET p
1071 @findex set-buffer-process-coding-system
1072   The command @kbd{C-x @key{RET} p} (@code{set-buffer-process-coding-system})
1073 specifies the coding system for input and output to a subprocess.  This
1074 command applies to the current buffer; normally, each subprocess has its
1075 own buffer, and thus you can use this command to specify translation to
1076 and from a particular subprocess by giving the command in the
1077 corresponding buffer.
1079   You can also use @kbd{C-x @key{RET} c}
1080 (@code{universal-coding-system-argument}) just before the command that
1081 runs or starts a subprocess, to specify the coding system for
1082 communicating with that subprocess.  @xref{Text Coding}.
1084   The default for translation of process input and output depends on the
1085 current language environment.
1087 @vindex locale-coding-system
1088 @cindex decoding non-@acronym{ASCII} keyboard input on X
1089   The variable @code{locale-coding-system} specifies a coding system
1090 to use when encoding and decoding system strings such as system error
1091 messages and @code{format-time-string} formats and time stamps.  That
1092 coding system is also used for decoding non-@acronym{ASCII} keyboard
1093 input on the X Window System.  You should choose a coding system that is compatible
1094 with the underlying system's text representation, which is normally
1095 specified by one of the environment variables @env{LC_ALL},
1096 @env{LC_CTYPE}, and @env{LANG}.  (The first one, in the order
1097 specified above, whose value is nonempty is the one that determines
1098 the text representation.)
1100 @node File Name Coding
1101 @section Coding Systems for File Names
1103 @table @kbd
1104 @item C-x @key{RET} F @var{coding} @key{RET}
1105 Use coding system @var{coding} for encoding and decoding file
1106 names (@code{set-file-name-coding-system}).
1107 @end table
1109 @findex set-file-name-coding-system
1110 @kindex C-x @key{RET} F
1111 @cindex file names with non-@acronym{ASCII} characters
1112   The command @kbd{C-x @key{RET} F} (@code{set-file-name-coding-system})
1113 specifies a coding system to use for encoding file @emph{names}.  It
1114 has no effect on reading and writing the @emph{contents} of files.
1116 @vindex file-name-coding-system
1117   In fact, all this command does is set the value of the variable
1118 @code{file-name-coding-system}.  If you set the variable to a coding
1119 system name (as a Lisp symbol or a string), Emacs encodes file names
1120 using that coding system for all file operations.  This makes it
1121 possible to use non-@acronym{ASCII} characters in file names---or, at
1122 least, those non-@acronym{ASCII} characters that the specified coding
1123 system can encode.
1125   If @code{file-name-coding-system} is @code{nil}, Emacs uses a
1126 default coding system determined by the selected language environment,
1127 and stored in the @code{default-file-name-coding-system} variable.
1128 @c FIXME?  Is this correct?  What is the "default language environment"?
1129 In the default language environment, non-@acronym{ASCII} characters in
1130 file names are not encoded specially; they appear in the file system
1131 using the internal Emacs representation.
1133   @strong{Warning:} if you change @code{file-name-coding-system} (or the
1134 language environment) in the middle of an Emacs session, problems can
1135 result if you have already visited files whose names were encoded using
1136 the earlier coding system and cannot be encoded (or are encoded
1137 differently) under the new coding system.  If you try to save one of
1138 these buffers under the visited file name, saving may use the wrong file
1139 name, or it may encounter an error.  If such a problem happens, use @kbd{C-x
1140 C-w} to specify a new file name for that buffer.
1142 @findex recode-file-name
1143   If a mistake occurs when encoding a file name, use the command
1144 @kbd{M-x recode-file-name} to change the file name's coding
1145 system.  This prompts for an existing file name, its old coding
1146 system, and the coding system to which you wish to convert.
1148 @node Terminal Coding
1149 @section Coding Systems for Terminal I/O
1151 @table @kbd
1152 @item C-x @key{RET} t @var{coding} @key{RET}
1153 Use coding system @var{coding} for terminal output
1154 (@code{set-terminal-coding-system}).
1156 @item C-x @key{RET} k @var{coding} @key{RET}
1157 Use coding system @var{coding} for keyboard input
1158 (@code{set-keyboard-coding-system}).
1159 @end table
1161 @kindex C-x RET t
1162 @findex set-terminal-coding-system
1163   The command @kbd{C-x @key{RET} t} (@code{set-terminal-coding-system})
1164 specifies the coding system for terminal output.  If you specify a
1165 character code for terminal output, all characters output to the
1166 terminal are translated into that coding system.
1168   This feature is useful for certain character-only terminals built to
1169 support specific languages or character sets---for example, European
1170 terminals that support one of the ISO Latin character sets.  You need to
1171 specify the terminal coding system when using multibyte text, so that
1172 Emacs knows which characters the terminal can actually handle.
1174   By default, output to the terminal is not translated at all, unless
1175 Emacs can deduce the proper coding system from your terminal type or
1176 your locale specification (@pxref{Language Environments}).
1178 @kindex C-x RET k
1179 @findex set-keyboard-coding-system
1180 @vindex keyboard-coding-system
1181   The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system}),
1182 or the variable @code{keyboard-coding-system}, specifies the coding
1183 system for keyboard input.  Character-code translation of keyboard
1184 input is useful for terminals with keys that send non-@acronym{ASCII}
1185 graphic characters---for example, some terminals designed for ISO
1186 Latin-1 or subsets of it.
1188   By default, keyboard input is translated based on your system locale
1189 setting.  If your terminal does not really support the encoding
1190 implied by your locale (for example, if you find it inserts a
1191 non-@acronym{ASCII} character if you type @kbd{M-i}), you will need to set
1192 @code{keyboard-coding-system} to @code{nil} to turn off encoding.
1193 You can do this by putting
1195 @lisp
1196 (set-keyboard-coding-system nil)
1197 @end lisp
1199 @noindent
1200 in your init file.
1202   There is a similarity between using a coding system translation for
1203 keyboard input, and using an input method: both define sequences of
1204 keyboard input that translate into single characters.  However, input
1205 methods are designed to be convenient for interactive use by humans, and
1206 the sequences that are translated are typically sequences of @acronym{ASCII}
1207 printing characters.  Coding systems typically translate sequences of
1208 non-graphic characters.
1210 @node Fontsets
1211 @section Fontsets
1212 @cindex fontsets
1214   A font typically defines shapes for a single alphabet or script.
1215 Therefore, displaying the entire range of scripts that Emacs supports
1216 requires a collection of many fonts.  In Emacs, such a collection is
1217 called a @dfn{fontset}.  A fontset is defined by a list of font specifications,
1218 each assigned to handle a range of character codes, and may fall back
1219 on another fontset for characters that are not covered by the fonts
1220 it specifies.
1222 @cindex fonts for various scripts
1223 @cindex Intlfonts package, installation
1224   Each fontset has a name, like a font.  However, while fonts are
1225 stored in the system and the available font names are defined by the
1226 system, fontsets are defined within Emacs itself.  Once you have
1227 defined a fontset, you can use it within Emacs by specifying its name,
1228 anywhere that you could use a single font.  Of course, Emacs fontsets
1229 can use only the fonts that the system supports.  If some characters
1230 appear on the screen as empty boxes or hex codes, this means that the
1231 fontset in use for them has no font for those characters.  In this
1232 case, or if the characters are shown, but not as well as you would
1233 like, you may need to install extra fonts.  Your operating system may
1234 have optional fonts that you can install; or you can install the GNU
1235 Intlfonts package, which includes fonts for most supported
1236 scripts.@footnote{If you run Emacs on X, you may need to inform the X
1237 server about the location of the newly installed fonts with commands
1238 such as:
1239 @c FIXME?  I feel like this may be out of date.
1240 @c E.g., the intlfonts tarfile is ~ 10 years old.
1242 @example
1243  xset fp+ /usr/local/share/emacs/fonts
1244  xset fp rehash
1245 @end example
1248   Emacs creates three fontsets automatically: the @dfn{standard
1249 fontset}, the @dfn{startup fontset} and the @dfn{default fontset}.
1250 @c FIXME?  The doc of *standard*-fontset-spec says:
1251 @c "You have the biggest chance to display international characters
1252 @c with correct glyphs by using the *standard* fontset." (my emphasis)
1253 @c See http://lists.gnu.org/archive/html/emacs-devel/2012-04/msg00430.html
1254 The default fontset is most likely to have fonts for a wide variety of
1255 non-@acronym{ASCII} characters, and is the default fallback for the
1256 other two fontsets, and if you set a default font rather than fontset.
1257 However, it does not specify font family names, so results can be
1258 somewhat random if you use it directly.  You can specify use of a
1259 particular fontset by starting Emacs with the @samp{-fn} option.
1260 For example,
1262 @example
1263 emacs -fn fontset-standard
1264 @end example
1266 @noindent
1267 You can also specify a fontset with the @samp{Font} resource (@pxref{X
1268 Resources}).
1270   If no fontset is specified for use, then Emacs uses an
1271 @acronym{ASCII} font, with @samp{fontset-default} as a fallback for
1272 characters the font does not cover.  The standard fontset is only used if
1273 explicitly requested, despite its name.
1275   A fontset does not necessarily specify a font for every character
1276 code.  If a fontset specifies no font for a certain character, or if
1277 it specifies a font that does not exist on your system, then it cannot
1278 display that character properly.  It will display that character as a
1279 hex code or thin space or an empty box instead.  (@xref{Text Display, ,
1280 glyphless characters}, for details.)
1282 @node Defining Fontsets
1283 @section Defining fontsets
1285 @vindex standard-fontset-spec
1286 @vindex w32-standard-fontset-spec
1287 @vindex ns-standard-fontset-spec
1288 @cindex standard fontset
1289   When running on X, Emacs creates a standard fontset automatically according to the value
1290 of @code{standard-fontset-spec}.  This fontset's name is
1292 @example
1293 -*-fixed-medium-r-normal-*-16-*-*-*-*-*-fontset-standard
1294 @end example
1296 @noindent
1297 or just @samp{fontset-standard} for short.
1299   On GNUstep and Mac OS X, the standard fontset is created using the value of
1300 @code{ns-standard-fontset-spec}, and on MS Windows it is
1301 created using the value of @code{w32-standard-fontset-spec}.
1303 @c FIXME?  How does one access these, or do anything with them?
1304 @c Does it matter?
1305   Bold, italic, and bold-italic variants of the standard fontset are
1306 created automatically.  Their names have @samp{bold} instead of
1307 @samp{medium}, or @samp{i} instead of @samp{r}, or both.
1309 @cindex startup fontset
1310   Emacs generates a fontset automatically, based on any default
1311 @acronym{ASCII} font that you specify with the @samp{Font} resource or
1312 the @samp{-fn} argument, or the default font that Emacs found when it
1313 started.  This is the @dfn{startup fontset} and its name is
1314 @code{fontset-startup}.  It does this by replacing the
1315 @var{charset_registry} field with @samp{fontset}, and replacing
1316 @var{charset_encoding} field with @samp{startup}, then using the
1317 resulting string to specify a fontset.
1319   For instance, if you start Emacs with a font of this form,
1321 @c FIXME?  I think this is a little misleading, because you cannot (?)
1322 @c actually specify a font with wildcards, it has to be a complete spec.
1323 @c Also, an X font specification of this form hasn't (?) been
1324 @c mentioned before now, and is somewhat obsolete these days.
1325 @c People are more likely to use a form like
1326 @c emacs -fn "DejaVu Sans Mono-12"
1327 @c How does any of this apply in that case?
1328 @example
1329 emacs -fn "*courier-medium-r-normal--14-140-*-iso8859-1"
1330 @end example
1332 @noindent
1333 Emacs generates the following fontset and uses it for the initial X
1334 window frame:
1336 @example
1337 -*-courier-medium-r-normal-*-14-140-*-*-*-*-fontset-startup
1338 @end example
1340   The startup fontset will use the font that you specify, or a variant
1341 with a different registry and encoding, for all the characters that
1342 are supported by that font, and fallback on @samp{fontset-default} for
1343 other characters.
1345   With the X resource @samp{Emacs.Font}, you can specify a fontset name
1346 just like an actual font name.  But be careful not to specify a fontset
1347 name in a wildcard resource like @samp{Emacs*Font}---that wildcard
1348 specification matches various other resources, such as for menus, and
1349 @c FIXME is this still true?
1350 menus cannot handle fontsets.  @xref{X Resources}.
1352   You can specify additional fontsets using X resources named
1353 @samp{Fontset-@var{n}}, where @var{n} is an integer starting from 0.
1354 The resource value should have this form:
1356 @smallexample
1357 @var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}}
1358 @end smallexample
1360 @noindent
1361 @var{fontpattern} should have the form of a standard X font name (see
1362 the previous fontset-startup example), except
1363 for the last two fields.  They should have the form
1364 @samp{fontset-@var{alias}}.
1366   The fontset has two names, one long and one short.  The long name is
1367 @var{fontpattern}.  The short name is @samp{fontset-@var{alias}}.  You
1368 can refer to the fontset by either name.
1370   The construct @samp{@var{charset}:@var{font}} specifies which font to
1371 use (in this fontset) for one particular character set.  Here,
1372 @var{charset} is the name of a character set, and @var{font} is the
1373 font to use for that character set.  You can use this construct any
1374 number of times in defining one fontset.
1376   For the other character sets, Emacs chooses a font based on
1377 @var{fontpattern}.  It replaces @samp{fontset-@var{alias}} with values
1378 that describe the character set.  For the @acronym{ASCII} character font,
1379 @samp{fontset-@var{alias}} is replaced with @samp{ISO8859-1}.
1381   In addition, when several consecutive fields are wildcards, Emacs
1382 collapses them into a single wildcard.  This is to prevent use of
1383 auto-scaled fonts.  Fonts made by scaling larger fonts are not usable
1384 for editing, and scaling a smaller font is not also useful, because it is
1385 better to use the smaller font in its own size, which is what Emacs
1386 does.
1388   Thus if @var{fontpattern} is this,
1390 @example
1391 -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
1392 @end example
1394 @noindent
1395 the font specification for @acronym{ASCII} characters would be this:
1397 @example
1398 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
1399 @end example
1401 @noindent
1402 and the font specification for Chinese GB2312 characters would be this:
1404 @example
1405 -*-fixed-medium-r-normal-*-24-*-gb2312*-*
1406 @end example
1408   You may not have any Chinese font matching the above font
1409 specification.  Most X distributions include only Chinese fonts that
1410 have @samp{song ti} or @samp{fangsong ti} in the @var{family} field.  In
1411 such a case, @samp{Fontset-@var{n}} can be specified as:
1413 @smallexample
1414 Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
1415         chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
1416 @end smallexample
1418 @noindent
1419 Then, the font specifications for all but Chinese GB2312 characters have
1420 @samp{fixed} in the @var{family} field, and the font specification for
1421 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
1422 field.
1424 @findex create-fontset-from-fontset-spec
1425   The function that processes the fontset resource value to create the
1426 fontset is called @code{create-fontset-from-fontset-spec}.  You can also
1427 call this function explicitly to create a fontset.
1429   @xref{Fonts}, for more information about font naming.
1431 @node Modifying Fontsets
1432 @section Modifying Fontsets
1433 @cindex fontsets, modifying
1434 @findex set-fontset-font
1436   Fontsets do not always have to be created from scratch.  If only
1437 minor changes are required it may be easier to modify an existing
1438 fontset.  Modifying @samp{fontset-default} will also affect other
1439 fontsets that use it as a fallback, so can be an effective way of
1440 fixing problems with the fonts that Emacs chooses for a particular
1441 script.
1443 Fontsets can be modified using the function @code{set-fontset-font},
1444 specifying a character, a charset, a script, or a range of characters
1445 to modify the font for, and a font specification for the font to be
1446 used.  Some examples are:
1448 @example
1449 ;; Use Liberation Mono for latin-3 charset.
1450 (set-fontset-font "fontset-default" 'iso-8859-3
1451                   "Liberation Mono")
1453 ;; Prefer a big5 font for han characters
1454 (set-fontset-font "fontset-default"
1455                   'han (font-spec :registry "big5")
1456                   nil 'prepend)
1458 ;; Use DejaVu Sans Mono as a fallback in fontset-startup
1459 ;; before resorting to fontset-default.
1460 (set-fontset-font "fontset-startup" nil "DejaVu Sans Mono"
1461                   nil 'append)
1463 ;; Use MyPrivateFont for the Unicode private use area.
1464 (set-fontset-font "fontset-default"  '(#xe000 . #xf8ff)
1465                   "MyPrivateFont")
1467 @end example
1470 @node Undisplayable Characters
1471 @section Undisplayable Characters
1473   There may be some non-@acronym{ASCII} characters that your
1474 terminal cannot display.  Most text terminals support just a single
1475 character set (use the variable @code{default-terminal-coding-system}
1476 to tell Emacs which one, @ref{Terminal Coding}); characters that
1477 can't be encoded in that coding system are displayed as @samp{?} by
1478 default.
1480   Graphical displays can display a broader range of characters, but
1481 you may not have fonts installed for all of them; characters that have
1482 no font appear as a hollow box.
1484   If you use Latin-1 characters but your terminal can't display
1485 Latin-1, you can arrange to display mnemonic @acronym{ASCII} sequences
1486 instead, e.g., @samp{"o} for o-umlaut.  Load the library
1487 @file{iso-ascii} to do this.
1489 @vindex latin1-display
1490   If your terminal can display Latin-1, you can display characters
1491 from other European character sets using a mixture of equivalent
1492 Latin-1 characters and @acronym{ASCII} mnemonics.  Customize the variable
1493 @code{latin1-display} to enable this.  The mnemonic @acronym{ASCII}
1494 sequences mostly correspond to those of the prefix input methods.
1496 @node Unibyte Mode
1497 @section Unibyte Editing Mode
1499 @cindex European character sets
1500 @cindex accented characters
1501 @cindex ISO Latin character sets
1502 @cindex Unibyte operation
1503   The ISO 8859 Latin-@var{n} character sets define character codes in
1504 the range 0240 to 0377 octal (160 to 255 decimal) to handle the
1505 accented letters and punctuation needed by various European languages
1506 (and some non-European ones).  Note that Emacs considers bytes with
1507 codes in this range as raw bytes, not as characters, even in a unibyte
1508 buffer, i.e., if you disable multibyte characters.  However, Emacs can
1509 still handle these character codes as if they belonged to @emph{one}
1510 of the single-byte character sets at a time.  To specify @emph{which}
1511 of these codes to use, invoke @kbd{M-x set-language-environment} and
1512 specify a suitable language environment such as @samp{Latin-@var{n}}.
1513 @xref{Disabling Multibyte, , Disabling Multibyte Characters, elisp,
1514 GNU Emacs Lisp Reference Manual}.
1516 @vindex unibyte-display-via-language-environment
1517   Emacs can also display bytes in the range 160 to 255 as readable
1518 characters, provided the terminal or font in use supports them.  This
1519 works automatically.  On a graphical display, Emacs can also display
1520 single-byte characters through fontsets, in effect by displaying the
1521 equivalent multibyte characters according to the current language
1522 environment.  To request this, set the variable
1523 @code{unibyte-display-via-language-environment} to a non-@code{nil}
1524 value.  Note that setting this only affects how these bytes are
1525 displayed, but does not change the fundamental fact that Emacs treats
1526 them as raw bytes, not as characters.
1528 @cindex @code{iso-ascii} library
1529   If your terminal does not support display of the Latin-1 character
1530 set, Emacs can display these characters as @acronym{ASCII} sequences which at
1531 least give you a clear idea of what the characters are.  To do this,
1532 load the library @code{iso-ascii}.  Similar libraries for other
1533 Latin-@var{n} character sets could be implemented, but have not been
1534 so far.
1536 @findex standard-display-8bit
1537 @cindex 8-bit display
1538   Normally non-ISO-8859 characters (decimal codes between 128 and 159
1539 inclusive) are displayed as octal escapes.  You can change this for
1540 non-standard ``extended'' versions of ISO-8859 character sets by using the
1541 function @code{standard-display-8bit} in the @code{disp-table} library.
1543   There are two ways to input single-byte non-@acronym{ASCII}
1544 characters:
1546 @itemize @bullet
1547 @cindex 8-bit input
1548 @item
1549 You can use an input method for the selected language environment.
1550 @xref{Input Methods}.  When you use an input method in a unibyte buffer,
1551 the non-@acronym{ASCII} character you specify with it is converted to unibyte.
1553 @item
1554 If your keyboard can generate character codes 128 (decimal) and up,
1555 representing non-@acronym{ASCII} characters, you can type those character codes
1556 directly.
1558 On a graphical display, you should not need to do anything special to
1559 use these keys; they should simply work.  On a text terminal, you
1560 should use the command @code{M-x set-keyboard-coding-system} or customize the
1561 variable @code{keyboard-coding-system} to specify which coding system
1562 your keyboard uses (@pxref{Terminal Coding}).  Enabling this feature
1563 will probably require you to use @kbd{ESC} to type Meta characters;
1564 however, on a console terminal or in @code{xterm}, you can arrange for
1565 Meta to be converted to @kbd{ESC} and still be able type 8-bit
1566 characters present directly on the keyboard or using @kbd{Compose} or
1567 @kbd{AltGr} keys.  @xref{User Input}.
1569 @kindex C-x 8
1570 @cindex @code{iso-transl} library
1571 @cindex compose character
1572 @cindex dead character
1573 @item
1574 For Latin-1 only, you can use the key @kbd{C-x 8} as a ``compose
1575 character'' prefix for entry of non-@acronym{ASCII} Latin-1 printing
1576 characters.  @kbd{C-x 8} is good for insertion (in the minibuffer as
1577 well as other buffers), for searching, and in any other context where
1578 a key sequence is allowed.
1580 @kbd{C-x 8} works by loading the @code{iso-transl} library.  Once that
1581 library is loaded, the @key{ALT} modifier key, if the keyboard has
1582 one, serves the same purpose as @kbd{C-x 8}: use @key{ALT} together
1583 with an accent character to modify the following letter.  In addition,
1584 if the keyboard has keys for the Latin-1 ``dead accent characters'',
1585 they too are defined to compose with the following character, once
1586 @code{iso-transl} is loaded.
1588 Use @kbd{C-x 8 C-h} to list all the available @kbd{C-x 8} translations.
1589 @end itemize
1591 @node Charsets
1592 @section Charsets
1593 @cindex charsets
1595   In Emacs, @dfn{charset} is short for ``character set''.  Emacs
1596 supports most popular charsets (such as @code{ascii},
1597 @code{iso-8859-1}, @code{cp1250}, @code{big5}, and @code{unicode}), in
1598 addition to some charsets of its own (such as @code{emacs},
1599 @code{unicode-bmp}, and @code{eight-bit}).  All supported characters
1600 belong to one or more charsets.
1602   Emacs normally ``does the right thing'' with respect to charsets, so
1603 that you don't have to worry about them.  However, it is sometimes
1604 helpful to know some of the underlying details about charsets.
1606   One example is font selection (@pxref{Fonts}).  Each language
1607 environment (@pxref{Language Environments}) defines a ``priority
1608 list'' for the various charsets.  When searching for a font, Emacs
1609 initially attempts to find one that can display the highest-priority
1610 charsets.  For instance, in the Japanese language environment, the
1611 charset @code{japanese-jisx0208} has the highest priority, so Emacs
1612 tries to use a font whose @code{registry} property is
1613 @samp{JISX0208.1983-0}.
1615 @findex list-charset-chars
1616 @cindex characters in a certain charset
1617 @findex describe-character-set
1618   There are two commands that can be used to obtain information about
1619 charsets.  The command @kbd{M-x list-charset-chars} prompts for a
1620 charset name, and displays all the characters in that character set.
1621 The command @kbd{M-x describe-character-set} prompts for a charset
1622 name, and displays information about that charset, including its
1623 internal representation within Emacs.
1625 @findex list-character-sets
1626   @kbd{M-x list-character-sets} displays a list of all supported
1627 charsets.  The list gives the names of charsets and additional
1628 information to identity each charset; see the
1629 @url{http://www.itscj.ipsj.or.jp/ISO-IR/, International Register of
1630 Coded Character Sets} for more details.  In this list,
1631 charsets are divided into two categories: @dfn{normal charsets} are
1632 listed first, followed by @dfn{supplementary charsets}.  A
1633 supplementary charset is one that is used to define another charset
1634 (as a parent or a subset), or to provide backward-compatibility for
1635 older Emacs versions.
1637   To find out which charset a character in the buffer belongs to, put
1638 point before it and type @kbd{C-u C-x =} (@pxref{International
1639 Chars}).
1641 @node Bidirectional Editing
1642 @section Bidirectional Editing
1643 @cindex bidirectional editing
1644 @cindex right-to-left text
1646   Emacs supports editing text written in scripts, such as Arabic and
1647 Hebrew, whose natural ordering of horizontal text for display is from
1648 right to left.  However, digits and Latin text embedded in these
1649 scripts are still displayed left to right.  It is also not uncommon to
1650 have small portions of text in Arabic or Hebrew embedded in an otherwise
1651 Latin document; e.g., as comments and strings in a program source
1652 file.  For these reasons, text that uses these scripts is actually
1653 @dfn{bidirectional}: a mixture of runs of left-to-right and
1654 right-to-left characters.
1656   This section describes the facilities and options provided by Emacs
1657 for editing bidirectional text.
1659 @cindex logical order
1660 @cindex visual order
1661   Emacs stores right-to-left and bidirectional text in the so-called
1662 @dfn{logical} (or @dfn{reading}) order: the buffer or string position
1663 of the first character you read precedes that of the next character.
1664 Reordering of bidirectional text into the @dfn{visual} order happens
1665 at display time.  As result, character positions no longer increase
1666 monotonically with their positions on display.  Emacs implements the
1667 Unicode Bidirectional Algorithm described in the Unicode Standard
1668 Annex #9, for reordering of bidirectional text for display.
1670 @vindex bidi-display-reordering
1671   The buffer-local variable @code{bidi-display-reordering} controls
1672 whether text in the buffer is reordered for display.  If its value is
1673 non-@code{nil}, Emacs reorders characters that have right-to-left
1674 directionality when they are displayed.  The default value is
1675 @code{t}.
1677 @cindex base direction of paragraphs
1678 @cindex paragraph, base direction
1679   Each paragraph of bidirectional text can have its own @dfn{base
1680 direction}, either right-to-left or left-to-right.  (Paragraph
1681 @c paragraph-separate etc have no influence on this?
1682 boundaries are empty lines, i.e., lines consisting entirely of
1683 whitespace characters.)  Text in left-to-right paragraphs begins on
1684 the screen at the left margin of the window and is truncated or
1685 continued when it reaches the right margin.  By contrast, text in
1686 right-to-left paragraphs is displayed starting at the right margin and
1687 is continued or truncated at the left margin.
1689 @vindex bidi-paragraph-direction
1690   Emacs determines the base direction of each paragraph dynamically,
1691 based on the text at the beginning of the paragraph.  However,
1692 sometimes a buffer may need to force a certain base direction for its
1693 paragraphs.  The variable @code{bidi-paragraph-direction}, if
1694 non-@code{nil}, disables the dynamic determination of the base
1695 direction, and instead forces all paragraphs in the buffer to have the
1696 direction specified by its buffer-local value.  The value can be either
1697 @code{right-to-left} or @code{left-to-right}.  Any other value is
1698 interpreted as @code{nil}.
1700 @cindex LRM
1701 @cindex RLM
1702   Alternatively, you can control the base direction of a paragraph by
1703 inserting special formatting characters in front of the paragraph.
1704 The special character @code{RIGHT-TO-LEFT MARK}, or @sc{rlm}, forces
1705 the right-to-left direction on the following paragraph, while
1706 @code{LEFT-TO-RIGHT MARK}, or @sc{lrm} forces the left-to-right
1707 direction.  (You can use @kbd{C-x 8 RET} to insert these characters.)
1708 In a GUI session, the @sc{lrm} and @sc{rlm} characters display as very
1709 thin blank characters; on text terminals they display as blanks.
1711   Because characters are reordered for display, Emacs commands that
1712 operate in the logical order or on stretches of buffer positions may
1713 produce unusual effects.  For example, @kbd{C-f} and @kbd{C-b}
1714 commands move point in the logical order, so the cursor will sometimes
1715 jump when point traverses reordered bidirectional text.  Similarly, a
1716 highlighted region covering a contiguous range of character positions
1717 may look discontinuous if the region spans reordered text.  This is
1718 normal and similar to the behavior of other programs that support
1719 bidirectional text.  If you set @code{visual-order-cursor-movement} to
1720 a non-@code{nil} value, cursor motion by the arrow keys follows the
1721 visual order on screen (@pxref{Moving Point, visual-order movement}).