MS-Windows part of 2011-02-21T23:22:34Z!eggert@cs.ucla.edu, addition of min-max.h.
[emacs.git] / doc / emacs / mule.texi
blobf0facec86c11925276bc9d134bd9b5fa8e7646f6
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1997, 1999-2011  Free Software Foundation, Inc.
3 @c See file emacs.texi for copying conditions.
4 @node International, Major Modes, Frames, Top
5 @chapter International Character Set Support
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 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-only
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 set
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 On X Window systems, your locale should be set to an appropriate value
85 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 * Enabling Multibyte::      Controlling whether to use multibyte characters.
94 * Language Environments::   Setting things up for the language you use.
95 * Input Methods::           Entering text characters not on your keyboard.
96 * Select Input Method::     Specifying your choice of input methods.
97 * Coding Systems::          Character set conversion when you read and
98                               write files, and so on.
99 * Recognize Coding::        How Emacs figures out which conversion to use.
100 * Specify Coding::          Specifying a file's coding system explicitly.
101 * Output Coding::           Choosing coding systems for output.
102 * Text Coding::             Choosing conversion to use for file text.
103 * Communication Coding::    Coding systems for interprocess communication.
104 * File Name Coding::        Coding systems for file @emph{names}.
105 * Terminal Coding::         Specifying coding systems for converting
106                               terminal input and output.
107 * Fontsets::                Fontsets are collections of fonts
108                               that cover the whole spectrum of characters.
109 * Defining Fontsets::       Defining a new fontset.
110 * Modifying Fontsets::      Modifying an existing fontset.
111 * Undisplayable Characters:: When characters don't display.
112 * Unibyte Mode::            You can pick one European character set
113                               to use without multibyte characters.
114 * Charsets::                How Emacs groups its internal character codes.
115 * Bidirectional Editing::   Support for right-to-left scripts.
116 @end menu
118 @node International Chars
119 @section Introduction to International Character Sets
121   The users of international character sets and scripts have
122 established many more-or-less standard coding systems for storing
123 files.  These coding systems are typically @dfn{multibyte}, meaning
124 that sequences of two or more bytes are used to represent individual
125 non-@acronym{ASCII} characters.
127 @cindex Unicode
128   Internally, Emacs uses its own multibyte character encoding, which
129 is a superset of the @dfn{Unicode} standard.  This internal encoding
130 allows characters from almost every known script to be intermixed in a
131 single buffer or string.  Emacs translates between the multibyte
132 character encoding and various other coding systems when reading and
133 writing files, and when exchanging data with subprocesses.
135 @kindex C-h h
136 @findex view-hello-file
137 @cindex undisplayable characters
138 @cindex @samp{?} in display
139   The command @kbd{C-h h} (@code{view-hello-file}) displays the file
140 @file{etc/HELLO}, which shows how to say ``hello'' in many languages.
141 This illustrates various scripts.  If some characters can't be
142 displayed on your terminal, they appear as @samp{?} or as hollow boxes
143 (@pxref{Undisplayable Characters}).
145   Keyboards, even in the countries where these character sets are
146 used, generally don't have keys for all the characters in them.  You
147 can insert characters that your keyboard does not support, using
148 @kbd{C-q} (@code{quoted-insert}) or @kbd{C-x 8 @key{RET}}
149 (@code{ucs-insert}).  @xref{Inserting Text}.  Emacs also supports
150 various @dfn{input methods}, typically one for each script or
151 language, which make it easier to type characters in the script.
152 @xref{Input Methods}.
154 @kindex C-x RET
155   The prefix key @kbd{C-x @key{RET}} is used for commands that pertain
156 to multibyte characters, coding systems, and input methods.
158 @kindex C-x =
159 @findex what-cursor-position
160   The command @kbd{C-x =} (@code{what-cursor-position}) shows
161 information about the character at point.  In addition to the
162 character position, which was described in @ref{Position Info}, this
163 command displays how the character is encoded.  For instance, it
164 displays the following line in the echo area for the character
165 @samp{c}:
167 @smallexample
168 Char: c (99, #o143, #x63) point=28062 of 36168 (78%) column=53
169 @end smallexample
171   The four values after @samp{Char:} describe the character that
172 follows point, first by showing it and then by giving its character
173 code in decimal, octal and hex.  For a non-@acronym{ASCII} multibyte
174 character, these are followed by @samp{file} and the character's
175 representation, in hex, in the buffer's coding system, if that coding
176 system encodes the character safely and with a single byte
177 (@pxref{Coding Systems}).  If the character's encoding is longer than
178 one byte, Emacs shows @samp{file ...}.
180   As a special case, if the character lies in the range 128 (0200
181 octal) through 159 (0237 octal), it stands for a ``raw'' byte that
182 does not correspond to any specific displayable character.  Such a
183 ``character'' lies within the @code{eight-bit-control} character set,
184 and is displayed as an escaped octal character code.  In this case,
185 @kbd{C-x =} shows @samp{part of display ...} instead of @samp{file}.
187 @cindex character set of character at point
188 @cindex font of character at point
189 @cindex text properties at point
190 @cindex face at point
191   With a prefix argument (@kbd{C-u C-x =}), this command displays a
192 detailed description of the character in a window:
194 @itemize @bullet
195 @item
196 The character set name, and the codes that identify the character
197 within that character set; @acronym{ASCII} characters are identified
198 as belonging to the @code{ascii} character set.
200 @item
201 The character's syntax and categories.
203 @item
204 The character's encodings, both internally in the buffer, and externally
205 if you were to save the file.
207 @item
208 What keys to type to input the character in the current input method
209 (if it supports the character).
211 @item
212 If you are running Emacs on a graphical display, the font name and
213 glyph code for the character.  If you are running Emacs on a text-only
214 terminal, the code(s) sent to the terminal.
216 @item
217 The character's text properties (@pxref{Text Properties,,,
218 elisp, the Emacs Lisp Reference Manual}), including any non-default
219 faces used to display the character, and any overlays containing it
220 (@pxref{Overlays,,, elisp, the same manual}).
221 @end itemize
223   Here's an example showing the Latin-1 character A with grave accent,
224 in a buffer whose coding system is @code{utf-8-unix}:
226 @smallexample
227         character: @`A (192, #o300, #xc0)
228 preferred charset: unicode (Unicode (ISO10646))
229        code point: 0xC0
230            syntax: w    which means: word
231          category: j:Japanese l:Latin v:Vietnamese
232       buffer code: #xC3 #x80
233         file code: not encodable by coding system undecided-unix
234           display: by this font (glyph code)
235     xft:-unknown-DejaVu Sans Mono-normal-normal-normal-*-13-*-*-*-m-0-iso10646-1 (#x82)
237 Character code properties: customize what to show
238   name: LATIN CAPITAL LETTER A WITH GRAVE
239   general-category: Lu (Letter, Uppercase)
240   decomposition: (65 768) ('A' '̀')
241   old-name: LATIN CAPITAL LETTER A GRAVE
243 There are text properties here:
244   auto-composed        t
245 @end smallexample
247 @node Enabling Multibyte
248 @section Enabling Multibyte Characters
250   By default, Emacs starts in multibyte mode: it stores the contents
251 of buffers and strings using an internal encoding that represents
252 non-@acronym{ASCII} characters using multi-byte sequences.  Multibyte
253 mode allows you to use all the supported languages and scripts without
254 limitations.
256 @cindex turn multibyte support on or off
257   Under very special circumstances, you may want to disable multibyte
258 character support, for a specific buffer.
259 When multibyte characters are disabled in a buffer, we call
260 that @dfn{unibyte mode}.  In unibyte mode, each character in the
261 buffer has a character code ranging from 0 through 255 (0377 octal); 0
262 through 127 (0177 octal) represent @acronym{ASCII} characters, and 128
263 (0200 octal) through 255 (0377 octal) represent non-@acronym{ASCII}
264 characters.
266   To edit a particular file in unibyte representation, visit it using
267 @code{find-file-literally}.  @xref{Visiting}.  You can convert a
268 multibyte buffer to unibyte by saving it to a file, killing the
269 buffer, and visiting the file again with @code{find-file-literally}.
270 Alternatively, you can use @kbd{C-x @key{RET} c}
271 (@code{universal-coding-system-argument}) and specify @samp{raw-text}
272 as the coding system with which to visit or save a file.  @xref{Text
273 Coding}.  Unlike @code{find-file-literally}, finding a file as
274 @samp{raw-text} doesn't disable format conversion, uncompression, or
275 auto mode selection.
277 @cindex Lisp files, and multibyte operation
278 @cindex multibyte operation, and Lisp files
279 @cindex unibyte operation, and Lisp files
280 @cindex init file, and non-@acronym{ASCII} characters
281   Emacs normally loads Lisp files as multibyte.
282 This includes the Emacs initialization
283 file, @file{.emacs}, and the initialization files of Emacs packages
284 such as Gnus.  However, you can specify unibyte loading for a
285 particular Lisp file, by putting @w{@samp{-*-unibyte: t;-*-}} in a
286 comment on the first line (@pxref{File Variables}).  Then that file is
287 always loaded as unibyte text.  The motivation for these conventions
288 is that it is more reliable to always load any particular Lisp file in
289 the same way.  However, you can load a Lisp file as unibyte, on any
290 one occasion, by typing @kbd{C-x @key{RET} c raw-text @key{RET}}
291 immediately before loading it.
293   The mode line indicates whether multibyte character support is
294 enabled in the current buffer.  If it is, there are two or more
295 characters (most often two dashes) near the beginning of the mode
296 line, before the indication of the visited file's end-of-line
297 convention (colon, backslash, etc.).  When multibyte characters
298 are not enabled, nothing precedes the colon except a single dash.
299 @xref{Mode Line}, for more details about this.
301 @findex toggle-enable-multibyte-characters
302 You can turn on multibyte support in a specific buffer by invoking the
303 command @code{toggle-enable-multibyte-characters} in that buffer.
305 @node Language Environments
306 @section Language Environments
307 @cindex language environments
309   All supported character sets are supported in Emacs buffers whenever
310 multibyte characters are enabled; there is no need to select a
311 particular language in order to display its characters in an Emacs
312 buffer.  However, it is important to select a @dfn{language
313 environment} in order to set various defaults.  Roughly speaking, the
314 language environment represents a choice of preferred script rather
315 than a choice of language.
317   The language environment controls which coding systems to recognize
318 when reading text (@pxref{Recognize Coding}).  This applies to files,
319 incoming mail, and any other text you read into Emacs.  It may also
320 specify the default coding system to use when you create a file.  Each
321 language environment also specifies a default input method.
323 @findex set-language-environment
324 @vindex current-language-environment
325   To select a language environment, customize the variable
326 @code{current-language-environment} or use the command @kbd{M-x
327 set-language-environment}.  It makes no difference which buffer is
328 current when you use this command, because the effects apply globally
329 to the Emacs session.  The supported language environments include:
331 @cindex Euro sign
332 @cindex UTF-8
333 @quotation
334 ASCII, Belarusian, Bengali, Brazilian Portuguese, Bulgarian,
335 Chinese-BIG5, Chinese-CNS, Chinese-EUC-TW, Chinese-GB, Chinese-GBK,
336 Chinese-GB18030, Croatian, Cyrillic-ALT, Cyrillic-ISO, Cyrillic-KOI8,
337 Czech, Devanagari, Dutch, English, Esperanto, Ethiopic, French,
338 Georgian, German, Greek, Gujarati, Hebrew, IPA, Italian, Japanese,
339 Kannada, Khmer, Korean, Lao, Latin-1, Latin-2, Latin-3, Latin-4,
340 Latin-5, Latin-6, Latin-7, Latin-8 (Celtic), Latin-9 (updated Latin-1
341 with the Euro sign), Latvian, Lithuanian, Malayalam, Oriya, Polish,
342 Punjabi, Romanian, Russian, Sinhala, Slovak, Slovenian, Spanish,
343 Swedish, TaiViet, Tajik, Tamil, Telugu, Thai, Tibetan, Turkish, UTF-8
344 (for a setup which prefers Unicode characters and files encoded in
345 UTF-8), Ukrainian, Vietnamese, Welsh, and Windows-1255 (for a setup
346 which prefers Cyrillic characters and files encoded in Windows-1255).
347 @end quotation
349 @cindex fonts for various scripts
350 @cindex Intlfonts package, installation
351   To display the script(s) used by your language environment on a
352 graphical display, you need to have a suitable font.  If some of the
353 characters appear as empty boxes or hex codes, you should install the
354 GNU Intlfonts package, which includes fonts for most supported
355 scripts.@footnote{If you run Emacs on X, you need to inform the X
356 server about the location of the newly installed fonts with the
357 following commands:
359 @example
360  xset fp+ /usr/local/share/emacs/fonts
361  xset fp rehash
362 @end example
364 @xref{Fontsets}, for more details about setting up your fonts.
366 @findex set-locale-environment
367 @vindex locale-language-names
368 @vindex locale-charset-language-names
369 @cindex locales
370   Some operating systems let you specify the character-set locale you
371 are using by setting the locale environment variables @env{LC_ALL},
372 @env{LC_CTYPE}, or @env{LANG}.@footnote{If more than one of these is
373 set, the first one that is nonempty specifies your locale for this
374 purpose.}  During startup, Emacs looks up your character-set locale's
375 name in the system locale alias table, matches its canonical name
376 against entries in the value of the variables
377 @code{locale-charset-language-names} and @code{locale-language-names},
378 and selects the corresponding language environment if a match is found.
379 (The former variable overrides the latter.)  It also adjusts the display
380 table and terminal coding system, the locale coding system, the
381 preferred coding system as needed for the locale, and---last but not
382 least---the way Emacs decodes non-@acronym{ASCII} characters sent by your keyboard.
384   If you modify the @env{LC_ALL}, @env{LC_CTYPE}, or @env{LANG}
385 environment variables while running Emacs, you may want to invoke the
386 @code{set-locale-environment} function afterwards to readjust the
387 language environment from the new locale.
389 @vindex locale-preferred-coding-systems
390   The @code{set-locale-environment} function normally uses the preferred
391 coding system established by the language environment to decode system
392 messages.  But if your locale matches an entry in the variable
393 @code{locale-preferred-coding-systems}, Emacs uses the corresponding
394 coding system instead.  For example, if the locale @samp{ja_JP.PCK}
395 matches @code{japanese-shift-jis} in
396 @code{locale-preferred-coding-systems}, Emacs uses that encoding even
397 though it might normally use @code{japanese-iso-8bit}.
399   You can override the language environment chosen at startup with
400 explicit use of the command @code{set-language-environment}, or with
401 customization of @code{current-language-environment} in your init
402 file.
404 @kindex C-h L
405 @findex describe-language-environment
406   To display information about the effects of a certain language
407 environment @var{lang-env}, use the command @kbd{C-h L @var{lang-env}
408 @key{RET}} (@code{describe-language-environment}).  This tells you
409 which languages this language environment is useful for, and lists the
410 character sets, coding systems, and input methods that go with it.  It
411 also shows some sample text to illustrate scripts used in this
412 language environment.  If you give an empty input for @var{lang-env},
413 this command describes the chosen language environment.
414 @anchor{Describe Language Environment}
416 @vindex set-language-environment-hook
417   You can customize any language environment with the normal hook
418 @code{set-language-environment-hook}.  The command
419 @code{set-language-environment} runs that hook after setting up the new
420 language environment.  The hook functions can test for a specific
421 language environment by checking the variable
422 @code{current-language-environment}.  This hook is where you should
423 put non-default settings for specific language environment, such as
424 coding systems for keyboard input and terminal output, the default
425 input method, etc.
427 @vindex exit-language-environment-hook
428   Before it starts to set up the new language environment,
429 @code{set-language-environment} first runs the hook
430 @code{exit-language-environment-hook}.  This hook is useful for undoing
431 customizations that were made with @code{set-language-environment-hook}.
432 For instance, if you set up a special key binding in a specific language
433 environment using @code{set-language-environment-hook}, you should set
434 up @code{exit-language-environment-hook} to restore the normal binding
435 for that key.
437 @node Input Methods
438 @section Input Methods
440 @cindex input methods
441   An @dfn{input method} is a kind of character conversion designed
442 specifically for interactive input.  In Emacs, typically each language
443 has its own input method; sometimes several languages which use the same
444 characters can share one input method.  A few languages support several
445 input methods.
447   The simplest kind of input method works by mapping @acronym{ASCII} letters
448 into another alphabet; this allows you to use one other alphabet
449 instead of @acronym{ASCII}.  The Greek and Russian input methods
450 work this way.
452   A more powerful technique is composition: converting sequences of
453 characters into one letter.  Many European input methods use composition
454 to produce a single non-@acronym{ASCII} letter from a sequence that consists of a
455 letter followed by accent characters (or vice versa).  For example, some
456 methods convert the sequence @kbd{a'} into a single accented letter.
457 These input methods have no special commands of their own; all they do
458 is compose sequences of printing characters.
460   The input methods for syllabic scripts typically use mapping followed
461 by composition.  The input methods for Thai and Korean work this way.
462 First, letters are mapped into symbols for particular sounds or tone
463 marks; then, sequences of these which make up a whole syllable are
464 mapped into one syllable sign.
466   Chinese and Japanese require more complex methods.  In Chinese input
467 methods, first you enter the phonetic spelling of a Chinese word (in
468 input method @code{chinese-py}, among others), or a sequence of
469 portions of the character (input methods @code{chinese-4corner} and
470 @code{chinese-sw}, and others).  One input sequence typically
471 corresponds to many possible Chinese characters.  You select the one
472 you mean using keys such as @kbd{C-f}, @kbd{C-b}, @kbd{C-n},
473 @kbd{C-p}, and digits, which have special meanings in this situation.
475   The possible characters are conceptually arranged in several rows,
476 with each row holding up to 10 alternatives.  Normally, Emacs displays
477 just one row at a time, in the echo area; @code{(@var{i}/@var{j})}
478 appears at the beginning, to indicate that this is the @var{i}th row
479 out of a total of @var{j} rows.  Type @kbd{C-n} or @kbd{C-p} to
480 display the next row or the previous row.
482     Type @kbd{C-f} and @kbd{C-b} to move forward and backward among
483 the alternatives in the current row.  As you do this, Emacs highlights
484 the current alternative with a special color; type @code{C-@key{SPC}}
485 to select the current alternative and use it as input.  The
486 alternatives in the row are also numbered; the number appears before
487 the alternative.  Typing a digit @var{n} selects the @var{n}th
488 alternative of the current row and uses it as input.
490   @key{TAB} in these Chinese input methods displays a buffer showing
491 all the possible characters at once; then clicking @kbd{Mouse-2} on
492 one of them selects that alternative.  The keys @kbd{C-f}, @kbd{C-b},
493 @kbd{C-n}, @kbd{C-p}, and digits continue to work as usual, but they
494 do the highlighting in the buffer showing the possible characters,
495 rather than in the echo area.
497   In Japanese input methods, first you input a whole word using
498 phonetic spelling; then, after the word is in the buffer, Emacs
499 converts it into one or more characters using a large dictionary.  One
500 phonetic spelling corresponds to a number of different Japanese words;
501 to select one of them, use @kbd{C-n} and @kbd{C-p} to cycle through
502 the alternatives.
504   Sometimes it is useful to cut off input method processing so that the
505 characters you have just entered will not combine with subsequent
506 characters.  For example, in input method @code{latin-1-postfix}, the
507 sequence @kbd{e '} combines to form an @samp{e} with an accent.  What if
508 you want to enter them as separate characters?
510   One way is to type the accent twice; this is a special feature for
511 entering the separate letter and accent.  For example, @kbd{e ' '} gives
512 you the two characters @samp{e'}.  Another way is to type another letter
513 after the @kbd{e}---something that won't combine with that---and
514 immediately delete it.  For example, you could type @kbd{e e @key{DEL}
515 '} to get separate @samp{e} and @samp{'}.
517   Another method, more general but not quite as easy to type, is to use
518 @kbd{C-\ C-\} between two characters to stop them from combining.  This
519 is the command @kbd{C-\} (@code{toggle-input-method}) used twice.
520 @ifnottex
521 @xref{Select Input Method}.
522 @end ifnottex
524 @cindex incremental search, input method interference
525   @kbd{C-\ C-\} is especially useful inside an incremental search,
526 because it stops waiting for more characters to combine, and starts
527 searching for what you have already entered.
529   To find out how to input the character after point using the current
530 input method, type @kbd{C-u C-x =}.  @xref{Position Info}.
532 @vindex input-method-verbose-flag
533 @vindex input-method-highlight-flag
534   The variables @code{input-method-highlight-flag} and
535 @code{input-method-verbose-flag} control how input methods explain
536 what is happening.  If @code{input-method-highlight-flag} is
537 non-@code{nil}, the partial sequence is highlighted in the buffer (for
538 most input methods---some disable this feature).  If
539 @code{input-method-verbose-flag} is non-@code{nil}, the list of
540 possible characters to type next is displayed in the echo area (but
541 not when you are in the minibuffer).
543   Another facility for typing characters not on your keyboard is by
544 using the @kbd{C-x 8 @key{RET}} (@code{ucs-insert}) to insert a single
545 character based on its Unicode name or code-point; see @ref{Inserting
546 Text}.
548 @node Select Input Method
549 @section Selecting an Input Method
551 @table @kbd
552 @item C-\
553 Enable or disable use of the selected input method.
555 @item C-x @key{RET} C-\ @var{method} @key{RET}
556 Select a new input method for the current buffer.
558 @item C-h I @var{method} @key{RET}
559 @itemx C-h C-\ @var{method} @key{RET}
560 @findex describe-input-method
561 @kindex C-h I
562 @kindex C-h C-\
563 Describe the input method @var{method} (@code{describe-input-method}).
564 By default, it describes the current input method (if any).  This
565 description should give you the full details of how to use any
566 particular input method.
568 @item M-x list-input-methods
569 Display a list of all the supported input methods.
570 @end table
572 @findex set-input-method
573 @vindex current-input-method
574 @kindex C-x RET C-\
575   To choose an input method for the current buffer, use @kbd{C-x
576 @key{RET} C-\} (@code{set-input-method}).  This command reads the
577 input method name from the minibuffer; the name normally starts with the
578 language environment that it is meant to be used with.  The variable
579 @code{current-input-method} records which input method is selected.
581 @findex toggle-input-method
582 @kindex C-\
583   Input methods use various sequences of @acronym{ASCII} characters to
584 stand for non-@acronym{ASCII} characters.  Sometimes it is useful to
585 turn off the input method temporarily.  To do this, type @kbd{C-\}
586 (@code{toggle-input-method}).  To reenable the input method, type
587 @kbd{C-\} again.
589   If you type @kbd{C-\} and you have not yet selected an input method,
590 it prompts for you to specify one.  This has the same effect as using
591 @kbd{C-x @key{RET} C-\} to specify an input method.
593   When invoked with a numeric argument, as in @kbd{C-u C-\},
594 @code{toggle-input-method} always prompts you for an input method,
595 suggesting the most recently selected one as the default.
597 @vindex default-input-method
598   Selecting a language environment specifies a default input method for
599 use in various buffers.  When you have a default input method, you can
600 select it in the current buffer by typing @kbd{C-\}.  The variable
601 @code{default-input-method} specifies the default input method
602 (@code{nil} means there is none).
604   In some language environments, which support several different input
605 methods, you might want to use an input method different from the
606 default chosen by @code{set-language-environment}.  You can instruct
607 Emacs to select a different default input method for a certain
608 language environment, if you wish, by using
609 @code{set-language-environment-hook} (@pxref{Language Environments,
610 set-language-environment-hook}).  For example:
612 @lisp
613 (defun my-chinese-setup ()
614   "Set up my private Chinese environment."
615   (if (equal current-language-environment "Chinese-GB")
616       (setq default-input-method "chinese-tonepy")))
617 (add-hook 'set-language-environment-hook 'my-chinese-setup)
618 @end lisp
620 @noindent
621 This sets the default input method to be @code{chinese-tonepy}
622 whenever you choose a Chinese-GB language environment.
624 You can instruct Emacs to activate a certain input method
625 automatically.  For example:
627 @lisp
628 (add-hook 'text-mode-hook
629   (lambda () (set-input-method "german-prefix")))
630 @end lisp
632 @noindent
633 This activates the input method ``german-prefix'' automatically in the
634 Text mode.
636 @findex quail-set-keyboard-layout
637   Some input methods for alphabetic scripts work by (in effect)
638 remapping the keyboard to emulate various keyboard layouts commonly used
639 for those scripts.  How to do this remapping properly depends on your
640 actual keyboard layout.  To specify which layout your keyboard has, use
641 the command @kbd{M-x quail-set-keyboard-layout}.
643 @findex quail-show-key
644   You can use the command @kbd{M-x quail-show-key} to show what key (or
645 key sequence) to type in order to input the character following point,
646 using the selected keyboard layout.  The command @kbd{C-u C-x =} also
647 shows that information in addition to the other information about the
648 character.
650 @findex list-input-methods
651   To see a list of all the supported input methods, type @kbd{M-x
652 list-input-methods}.  The list gives information about each input
653 method, including the string that stands for it in the mode line.
655 @node Coding Systems
656 @section Coding Systems
657 @cindex coding systems
659   Users of various languages have established many more-or-less standard
660 coding systems for representing them.  Emacs does not use these coding
661 systems internally; instead, it converts from various coding systems to
662 its own system when reading data, and converts the internal coding
663 system to other coding systems when writing data.  Conversion is
664 possible in reading or writing files, in sending or receiving from the
665 terminal, and in exchanging data with subprocesses.
667   Emacs assigns a name to each coding system.  Most coding systems are
668 used for one language, and the name of the coding system starts with
669 the language name.  Some coding systems are used for several
670 languages; their names usually start with @samp{iso}.  There are also
671 special coding systems, such as @code{no-conversion}, @code{raw-text},
672 and @code{emacs-internal}.
674 @cindex international files from DOS/Windows systems
675   A special class of coding systems, collectively known as
676 @dfn{codepages}, is designed to support text encoded by MS-Windows and
677 MS-DOS software.  The names of these coding systems are
678 @code{cp@var{nnnn}}, where @var{nnnn} is a 3- or 4-digit number of the
679 codepage.  You can use these encodings just like any other coding
680 system; for example, to visit a file encoded in codepage 850, type
681 @kbd{C-x @key{RET} c cp850 @key{RET} C-x C-f @var{filename}
682 @key{RET}}.
684   In addition to converting various representations of non-@acronym{ASCII}
685 characters, a coding system can perform end-of-line conversion.  Emacs
686 handles three different conventions for how to separate lines in a file:
687 newline, carriage-return linefeed, and just carriage-return.
689 @table @kbd
690 @item C-h C @var{coding} @key{RET}
691 Describe coding system @var{coding}.
693 @item C-h C @key{RET}
694 Describe the coding systems currently in use.
696 @item M-x list-coding-systems
697 Display a list of all the supported coding systems.
698 @end table
700 @kindex C-h C
701 @findex describe-coding-system
702   The command @kbd{C-h C} (@code{describe-coding-system}) displays
703 information about particular coding systems, including the end-of-line
704 conversion specified by those coding systems.  You can specify a coding
705 system name as the argument; alternatively, with an empty argument, it
706 describes the coding systems currently selected for various purposes,
707 both in the current buffer and as the defaults, and the priority list
708 for recognizing coding systems (@pxref{Recognize Coding}).
710 @findex list-coding-systems
711   To display a list of all the supported coding systems, type @kbd{M-x
712 list-coding-systems}.  The list gives information about each coding
713 system, including the letter that stands for it in the mode line
714 (@pxref{Mode Line}).
716 @cindex end-of-line conversion
717 @cindex line endings
718 @cindex MS-DOS end-of-line conversion
719 @cindex Macintosh end-of-line conversion
720   Each of the coding systems that appear in this list---except for
721 @code{no-conversion}, which means no conversion of any kind---specifies
722 how and whether to convert printing characters, but leaves the choice of
723 end-of-line conversion to be decided based on the contents of each file.
724 For example, if the file appears to use the sequence carriage-return
725 linefeed to separate lines, DOS end-of-line conversion will be used.
727   Each of the listed coding systems has three variants which specify
728 exactly what to do for end-of-line conversion:
730 @table @code
731 @item @dots{}-unix
732 Don't do any end-of-line conversion; assume the file uses
733 newline to separate lines.  (This is the convention normally used
734 on Unix and GNU systems.)
736 @item @dots{}-dos
737 Assume the file uses carriage-return linefeed to separate lines, and do
738 the appropriate conversion.  (This is the convention normally used on
739 Microsoft systems.@footnote{It is also specified for MIME @samp{text/*}
740 bodies and in other network transport contexts.  It is different
741 from the SGML reference syntax record-start/record-end format which
742 Emacs doesn't support directly.})
744 @item @dots{}-mac
745 Assume the file uses carriage-return to separate lines, and do the
746 appropriate conversion.  (This is the convention normally used on the
747 Macintosh system.)
748 @end table
750   These variant coding systems are omitted from the
751 @code{list-coding-systems} display for brevity, since they are entirely
752 predictable.  For example, the coding system @code{iso-latin-1} has
753 variants @code{iso-latin-1-unix}, @code{iso-latin-1-dos} and
754 @code{iso-latin-1-mac}.
756 @cindex @code{undecided}, coding system
757   The coding systems @code{unix}, @code{dos}, and @code{mac} are
758 aliases for @code{undecided-unix}, @code{undecided-dos}, and
759 @code{undecided-mac}, respectively.  These coding systems specify only
760 the end-of-line conversion, and leave the character code conversion to
761 be deduced from the text itself.
763   The coding system @code{raw-text} is good for a file which is mainly
764 @acronym{ASCII} text, but may contain byte values above 127 which are
765 not meant to encode non-@acronym{ASCII} characters.  With
766 @code{raw-text}, Emacs copies those byte values unchanged, and sets
767 @code{enable-multibyte-characters} to @code{nil} in the current buffer
768 so that they will be interpreted properly.  @code{raw-text} handles
769 end-of-line conversion in the usual way, based on the data
770 encountered, and has the usual three variants to specify the kind of
771 end-of-line conversion to use.
773   In contrast, the coding system @code{no-conversion} specifies no
774 character code conversion at all---none for non-@acronym{ASCII} byte values and
775 none for end of line.  This is useful for reading or writing binary
776 files, tar files, and other files that must be examined verbatim.  It,
777 too, sets @code{enable-multibyte-characters} to @code{nil}.
779   The easiest way to edit a file with no conversion of any kind is with
780 the @kbd{M-x find-file-literally} command.  This uses
781 @code{no-conversion}, and also suppresses other Emacs features that
782 might convert the file contents before you see them.  @xref{Visiting}.
784   The coding system @code{emacs-internal} (or @code{utf-8-emacs},
785 which is equivalent) means that the file contains non-@acronym{ASCII}
786 characters stored with the internal Emacs encoding.  This coding
787 system handles end-of-line conversion based on the data encountered,
788 and has the usual three variants to specify the kind of end-of-line
789 conversion.
791 @node Recognize Coding
792 @section Recognizing Coding Systems
794   Whenever Emacs reads a given piece of text, it tries to recognize
795 which coding system to use.  This applies to files being read, output
796 from subprocesses, text from X selections, etc.  Emacs can select the
797 right coding system automatically most of the time---once you have
798 specified your preferences.
800   Some coding systems can be recognized or distinguished by which byte
801 sequences appear in the data.  However, there are coding systems that
802 cannot be distinguished, not even potentially.  For example, there is no
803 way to distinguish between Latin-1 and Latin-2; they use the same byte
804 values with different meanings.
806   Emacs handles this situation by means of a priority list of coding
807 systems.  Whenever Emacs reads a file, if you do not specify the coding
808 system to use, Emacs checks the data against each coding system,
809 starting with the first in priority and working down the list, until it
810 finds a coding system that fits the data.  Then it converts the file
811 contents assuming that they are represented in this coding system.
813   The priority list of coding systems depends on the selected language
814 environment (@pxref{Language Environments}).  For example, if you use
815 French, you probably want Emacs to prefer Latin-1 to Latin-2; if you use
816 Czech, you probably want Latin-2 to be preferred.  This is one of the
817 reasons to specify a language environment.
819 @findex prefer-coding-system
820   However, you can alter the coding system priority list in detail
821 with the command @kbd{M-x prefer-coding-system}.  This command reads
822 the name of a coding system from the minibuffer, and adds it to the
823 front of the priority list, so that it is preferred to all others.  If
824 you use this command several times, each use adds one element to the
825 front of the priority list.
827   If you use a coding system that specifies the end-of-line conversion
828 type, such as @code{iso-8859-1-dos}, what this means is that Emacs
829 should attempt to recognize @code{iso-8859-1} with priority, and should
830 use DOS end-of-line conversion when it does recognize @code{iso-8859-1}.
832 @vindex file-coding-system-alist
833   Sometimes a file name indicates which coding system to use for the
834 file.  The variable @code{file-coding-system-alist} specifies this
835 correspondence.  There is a special function
836 @code{modify-coding-system-alist} for adding elements to this list.  For
837 example, to read and write all @samp{.txt} files using the coding system
838 @code{chinese-iso-8bit}, you can execute this Lisp expression:
840 @smallexample
841 (modify-coding-system-alist 'file "\\.txt\\'" 'chinese-iso-8bit)
842 @end smallexample
844 @noindent
845 The first argument should be @code{file}, the second argument should be
846 a regular expression that determines which files this applies to, and
847 the third argument says which coding system to use for these files.
849 @vindex inhibit-eol-conversion
850 @cindex DOS-style end-of-line display
851   Emacs recognizes which kind of end-of-line conversion to use based on
852 the contents of the file: if it sees only carriage-returns, or only
853 carriage-return linefeed sequences, then it chooses the end-of-line
854 conversion accordingly.  You can inhibit the automatic use of
855 end-of-line conversion by setting the variable @code{inhibit-eol-conversion}
856 to non-@code{nil}.  If you do that, DOS-style files will be displayed
857 with the @samp{^M} characters visible in the buffer; some people
858 prefer this to the more subtle @samp{(DOS)} end-of-line type
859 indication near the left edge of the mode line (@pxref{Mode Line,
860 eol-mnemonic}).
862 @vindex inhibit-iso-escape-detection
863 @cindex escape sequences in files
864   By default, the automatic detection of coding system is sensitive to
865 escape sequences.  If Emacs sees a sequence of characters that begin
866 with an escape character, and the sequence is valid as an ISO-2022
867 code, that tells Emacs to use one of the ISO-2022 encodings to decode
868 the file.
870   However, there may be cases that you want to read escape sequences
871 in a file as is.  In such a case, you can set the variable
872 @code{inhibit-iso-escape-detection} to non-@code{nil}.  Then the code
873 detection ignores any escape sequences, and never uses an ISO-2022
874 encoding.  The result is that all escape sequences become visible in
875 the buffer.
877   The default value of @code{inhibit-iso-escape-detection} is
878 @code{nil}.  We recommend that you not change it permanently, only for
879 one specific operation.  That's because many Emacs Lisp source files
880 in the Emacs distribution contain non-@acronym{ASCII} characters encoded in the
881 coding system @code{iso-2022-7bit}, and they won't be
882 decoded correctly when you visit those files if you suppress the
883 escape sequence detection.
885 @vindex auto-coding-alist
886 @vindex auto-coding-regexp-alist
887 @vindex auto-coding-functions
888   The variables @code{auto-coding-alist},
889 @code{auto-coding-regexp-alist} and @code{auto-coding-functions} are
890 the strongest way to specify the coding system for certain patterns of
891 file names, or for files containing certain patterns; these variables
892 even override @samp{-*-coding:-*-} tags in the file itself.  Emacs
893 uses @code{auto-coding-alist} for tar and archive files, to prevent it
894 from being confused by a @samp{-*-coding:-*-} tag in a member of the
895 archive and thinking it applies to the archive file as a whole.
896 Likewise, Emacs uses @code{auto-coding-regexp-alist} to ensure that
897 RMAIL files, whose names in general don't match any particular
898 pattern, are decoded correctly.  One of the builtin
899 @code{auto-coding-functions} detects the encoding for XML files.
901 @vindex rmail-decode-mime-charset
902 @vindex rmail-file-coding-system
903   When you get new mail in Rmail, each message is translated
904 automatically from the coding system it is written in, as if it were a
905 separate file.  This uses the priority list of coding systems that you
906 have specified.  If a MIME message specifies a character set, Rmail
907 obeys that specification, unless @code{rmail-decode-mime-charset} is
908 @code{nil}.  For reading and saving Rmail files themselves, Emacs uses
909 the coding system specified by the variable
910 @code{rmail-file-coding-system}.  The default value is @code{nil},
911 which means that Rmail files are not translated (they are read and
912 written in the Emacs internal character code).
914 @node Specify Coding
915 @section Specifying a File's Coding System
917   If Emacs recognizes the encoding of a file incorrectly, you can
918 reread the file using the correct coding system by typing @kbd{C-x
919 @key{RET} r @var{coding-system} @key{RET}}.  To see what coding system
920 Emacs actually used to decode the file, look at the coding system
921 mnemonic letter near the left edge of the mode line (@pxref{Mode
922 Line}), or type @kbd{C-h C @key{RET}}.
924 @vindex coding
925   You can specify the coding system for a particular file in the file
926 itself, using the @w{@samp{-*-@dots{}-*-}} construct at the beginning,
927 or a local variables list at the end (@pxref{File Variables}).  You do
928 this by defining a value for the ``variable'' named @code{coding}.
929 Emacs does not really have a variable @code{coding}; instead of
930 setting a variable, this uses the specified coding system for the
931 file.  For example, @samp{-*-mode: C; coding: latin-1;-*-} specifies
932 use of the Latin-1 coding system, as well as C mode.  When you specify
933 the coding explicitly in the file, that overrides
934 @code{file-coding-system-alist}.
936 @node Output Coding
937 @section Choosing Coding Systems for Output
939 @vindex buffer-file-coding-system
940   Once Emacs has chosen a coding system for a buffer, it stores that
941 coding system in @code{buffer-file-coding-system}.  That makes it the
942 default for operations that write from this buffer into a file, such
943 as @code{save-buffer} and @code{write-region}.  You can specify a
944 different coding system for further file output from the buffer using
945 @code{set-buffer-file-coding-system} (@pxref{Text Coding}).
947   You can insert any character Emacs supports into any Emacs buffer,
948 but most coding systems can only handle a subset of these characters.
949 Therefore, it's possible that the characters you insert cannot be
950 encoded with the coding system that will be used to save the buffer.
951 For example, you could visit a text file in Polish, encoded in
952 @code{iso-8859-2}, and add some Russian words to it.  When you save
953 that buffer, Emacs cannot use the current value of
954 @code{buffer-file-coding-system}, because the characters you added
955 cannot be encoded by that coding system.
957   When that happens, Emacs tries the most-preferred coding system (set
958 by @kbd{M-x prefer-coding-system} or @kbd{M-x
959 set-language-environment}).  If that coding system can safely encode
960 all of the characters in the buffer, Emacs uses it, and stores its
961 value in @code{buffer-file-coding-system}.  Otherwise, Emacs displays
962 a list of coding systems suitable for encoding the buffer's contents,
963 and asks you to choose one of those coding systems.
965   If you insert the unsuitable characters in a mail message, Emacs
966 behaves a bit differently.  It additionally checks whether the
967 most-preferred coding system is recommended for use in MIME messages;
968 if not, Emacs tells you that the most-preferred coding system is not
969 recommended and prompts you for another coding system.  This is so you
970 won't inadvertently send a message encoded in a way that your
971 recipient's mail software will have difficulty decoding.  (You can
972 still use an unsuitable coding system if you type its name in response
973 to the question.)
975 @vindex sendmail-coding-system
976   When you send a message with Message mode (@pxref{Sending Mail}),
977 Emacs has four different ways to determine the coding system to use
978 for encoding the message text.  It tries the buffer's own value of
979 @code{buffer-file-coding-system}, if that is non-@code{nil}.
980 Otherwise, it uses the value of @code{sendmail-coding-system}, if that
981 is non-@code{nil}.  The third way is to use the default coding system
982 for new files, which is controlled by your choice of language
983 environment, if that is non-@code{nil}.  If all of these three values
984 are @code{nil}, Emacs encodes outgoing mail using the Latin-1 coding
985 system.
987 @node Text Coding
988 @section Specifying a Coding System for File Text
990   In cases where Emacs does not automatically choose the right coding
991 system for a file's contents, you can use these commands to specify
992 one:
994 @table @kbd
995 @item C-x @key{RET} f @var{coding} @key{RET}
996 Use coding system @var{coding} for saving or revisiting the visited
997 file in the current buffer.
999 @item C-x @key{RET} c @var{coding} @key{RET}
1000 Specify coding system @var{coding} for the immediately following
1001 command.
1003 @item C-x @key{RET} r @var{coding} @key{RET}
1004 Revisit the current file using the coding system @var{coding}.
1006 @item M-x recode-region @key{RET} @var{right} @key{RET} @var{wrong} @key{RET}
1007 Convert a region that was decoded using coding system @var{wrong},
1008 decoding it using coding system @var{right} instead.
1009 @end table
1011 @kindex C-x RET f
1012 @findex set-buffer-file-coding-system
1013   The command @kbd{C-x @key{RET} f}
1014 (@code{set-buffer-file-coding-system}) sets the file coding system for
1015 the current buffer---in other words, it says which coding system to
1016 use when saving or reverting the visited file.  You specify which
1017 coding system using the minibuffer.  If you specify a coding system
1018 that cannot handle all of the characters in the buffer, Emacs warns
1019 you about the troublesome characters when you actually save the
1020 buffer.
1022 @cindex specify end-of-line conversion
1023   You can also use this command to specify the end-of-line conversion
1024 (@pxref{Coding Systems, end-of-line conversion}) for encoding the
1025 current buffer.  For example, @kbd{C-x @key{RET} f dos @key{RET}} will
1026 cause Emacs to save the current buffer's text with DOS-style CRLF line
1027 endings.
1029 @kindex C-x RET c
1030 @findex universal-coding-system-argument
1031   Another way to specify the coding system for a file is when you visit
1032 the file.  First use the command @kbd{C-x @key{RET} c}
1033 (@code{universal-coding-system-argument}); this command uses the
1034 minibuffer to read a coding system name.  After you exit the minibuffer,
1035 the specified coding system is used for @emph{the immediately following
1036 command}.
1038   So if the immediately following command is @kbd{C-x C-f}, for example,
1039 it reads the file using that coding system (and records the coding
1040 system for when you later save the file).  Or if the immediately following
1041 command is @kbd{C-x C-w}, it writes the file using that coding system.
1042 When you specify the coding system for saving in this way, instead
1043 of with @kbd{C-x @key{RET} f}, there is no warning if the buffer
1044 contains characters that the coding system cannot handle.
1046   Other file commands affected by a specified coding system include
1047 @kbd{C-x i} and @kbd{C-x C-v}, as well as the other-window variants
1048 of @kbd{C-x C-f}.  @kbd{C-x @key{RET} c} also affects commands that
1049 start subprocesses, including @kbd{M-x shell} (@pxref{Shell}).  If the
1050 immediately following command does not use the coding system, then
1051 @kbd{C-x @key{RET} c} ultimately has no effect.
1053   An easy way to visit a file with no conversion is with the @kbd{M-x
1054 find-file-literally} command.  @xref{Visiting}.
1056   The default value of the variable @code{buffer-file-coding-system}
1057 specifies the choice of coding system to use when you create a new file.
1058 It applies when you find a new file, and when you create a buffer and
1059 then save it in a file.  Selecting a language environment typically sets
1060 this variable to a good choice of default coding system for that language
1061 environment.
1063 @kindex C-x RET r
1064 @findex revert-buffer-with-coding-system
1065   If you visit a file with a wrong coding system, you can correct this
1066 with @kbd{C-x @key{RET} r} (@code{revert-buffer-with-coding-system}).
1067 This visits the current file again, using a coding system you specify.
1069 @findex recode-region
1070   If a piece of text has already been inserted into a buffer using the
1071 wrong coding system, you can redo the decoding of it using @kbd{M-x
1072 recode-region}.  This prompts you for the proper coding system, then
1073 for the wrong coding system that was actually used, and does the
1074 conversion.  It first encodes the region using the wrong coding system,
1075 then decodes it again using the proper coding system.
1077 @node Communication Coding
1078 @section Coding Systems for Interprocess Communication
1080   This section explains how to specify coding systems for use
1081 in communication with other processes.
1083 @table @kbd
1084 @item C-x @key{RET} x @var{coding} @key{RET}
1085 Use coding system @var{coding} for transferring selections to and from
1086 other window-based applications.
1088 @item C-x @key{RET} X @var{coding} @key{RET}
1089 Use coding system @var{coding} for transferring @emph{one}
1090 selection---the next one---to or from another window-based application.
1092 @item C-x @key{RET} p @var{input-coding} @key{RET} @var{output-coding} @key{RET}
1093 Use coding systems @var{input-coding} and @var{output-coding} for
1094 subprocess input and output in the current buffer.
1096 @item C-x @key{RET} c @var{coding} @key{RET}
1097 Specify coding system @var{coding} for the immediately following
1098 command.
1099 @end table
1101 @kindex C-x RET x
1102 @kindex C-x RET X
1103 @findex set-selection-coding-system
1104 @findex set-next-selection-coding-system
1105   The command @kbd{C-x @key{RET} x} (@code{set-selection-coding-system})
1106 specifies the coding system for sending selected text to other windowing
1107 applications, and for receiving the text of selections made in other
1108 applications.  This command applies to all subsequent selections, until
1109 you override it by using the command again.  The command @kbd{C-x
1110 @key{RET} X} (@code{set-next-selection-coding-system}) specifies the
1111 coding system for the next selection made in Emacs or read by Emacs.
1113 @vindex x-select-request-type
1114   The variable @code{x-select-request-type} specifies the data type to
1115 request from the X Window System for receiving text selections from
1116 other applications.  If the value is @code{nil} (the default), Emacs
1117 tries @code{COMPOUND_TEXT} and @code{UTF8_STRING}, in this order, and
1118 uses various heuristics to choose the more appropriate of the two
1119 results; if none of these succeed, Emacs falls back on @code{STRING}.
1120 If the value of @code{x-select-request-type} is one of the symbols
1121 @code{COMPOUND_TEXT}, @code{UTF8_STRING}, @code{STRING}, or
1122 @code{TEXT}, Emacs uses only that request type.  If the value is a
1123 list of some of these symbols, Emacs tries only the request types in
1124 the list, in order, until one of them succeeds, or until the list is
1125 exhausted.
1127 @kindex C-x RET p
1128 @findex set-buffer-process-coding-system
1129   The command @kbd{C-x @key{RET} p} (@code{set-buffer-process-coding-system})
1130 specifies the coding system for input and output to a subprocess.  This
1131 command applies to the current buffer; normally, each subprocess has its
1132 own buffer, and thus you can use this command to specify translation to
1133 and from a particular subprocess by giving the command in the
1134 corresponding buffer.
1136   You can also use @kbd{C-x @key{RET} c} just before the command that
1137 runs or starts a subprocess, to specify the coding system to use for
1138 communication with that subprocess.
1140   The default for translation of process input and output depends on the
1141 current language environment.
1143 @vindex locale-coding-system
1144 @cindex decoding non-@acronym{ASCII} keyboard input on X
1145   The variable @code{locale-coding-system} specifies a coding system
1146 to use when encoding and decoding system strings such as system error
1147 messages and @code{format-time-string} formats and time stamps.  That
1148 coding system is also used for decoding non-@acronym{ASCII} keyboard input on X
1149 Window systems.  You should choose a coding system that is compatible
1150 with the underlying system's text representation, which is normally
1151 specified by one of the environment variables @env{LC_ALL},
1152 @env{LC_CTYPE}, and @env{LANG}.  (The first one, in the order
1153 specified above, whose value is nonempty is the one that determines
1154 the text representation.)
1156 @vindex x-select-request-type
1157   The variable @code{x-select-request-type} specifies a selection data
1158 type of selection to request from the X server.  The default value is
1159 @code{nil}, which means Emacs tries @code{COMPOUND_TEXT} and
1160 @code{UTF8_STRING}, and uses whichever result seems more appropriate.
1161 You can explicitly specify the data type by setting the variable to
1162 one of the symbols @code{COMPOUND_TEXT}, @code{UTF8_STRING},
1163 @code{STRING} and @code{TEXT}.
1165 @node File Name Coding
1166 @section Coding Systems for File Names
1168 @table @kbd
1169 @item C-x @key{RET} F @var{coding} @key{RET}
1170 Use coding system @var{coding} for encoding and decoding file
1171 @emph{names}.
1172 @end table
1174 @vindex file-name-coding-system
1175 @cindex file names with non-@acronym{ASCII} characters
1176   The variable @code{file-name-coding-system} specifies a coding
1177 system to use for encoding file names.  It has no effect on reading
1178 and writing the @emph{contents} of files.
1180 @findex set-file-name-coding-system
1181 @kindex C-x @key{RET} F
1182   If you set the variable to a coding system name (as a Lisp symbol or
1183 a string), Emacs encodes file names using that coding system for all
1184 file operations.  This makes it possible to use non-@acronym{ASCII}
1185 characters in file names---or, at least, those non-@acronym{ASCII}
1186 characters which the specified coding system can encode.  Use @kbd{C-x
1187 @key{RET} F} (@code{set-file-name-coding-system}) to specify this
1188 interactively.
1190   If @code{file-name-coding-system} is @code{nil}, Emacs uses a
1191 default coding system determined by the selected language environment.
1192 In the default language environment, non-@acronym{ASCII} characters in
1193 file names are not encoded specially; they appear in the file system
1194 using the internal Emacs representation.
1196   @strong{Warning:} if you change @code{file-name-coding-system} (or the
1197 language environment) in the middle of an Emacs session, problems can
1198 result if you have already visited files whose names were encoded using
1199 the earlier coding system and cannot be encoded (or are encoded
1200 differently) under the new coding system.  If you try to save one of
1201 these buffers under the visited file name, saving may use the wrong file
1202 name, or it may get an error.  If such a problem happens, use @kbd{C-x
1203 C-w} to specify a new file name for that buffer.
1205 @findex recode-file-name
1206   If a mistake occurs when encoding a file name, use the command
1207 @kbd{M-x recode-file-name} to change the file name's coding
1208 system.  This prompts for an existing file name, its old coding
1209 system, and the coding system to which you wish to convert.
1211 @node Terminal Coding
1212 @section Coding Systems for Terminal I/O
1214 @table @kbd
1215 @item C-x @key{RET} k @var{coding} @key{RET}
1216 Use coding system @var{coding} for keyboard input.
1218 @item C-x @key{RET} t @var{coding} @key{RET}
1219 Use coding system @var{coding} for terminal output.
1220 @end table
1222 @kindex C-x RET t
1223 @findex set-terminal-coding-system
1224   The command @kbd{C-x @key{RET} t} (@code{set-terminal-coding-system})
1225 specifies the coding system for terminal output.  If you specify a
1226 character code for terminal output, all characters output to the
1227 terminal are translated into that coding system.
1229   This feature is useful for certain character-only terminals built to
1230 support specific languages or character sets---for example, European
1231 terminals that support one of the ISO Latin character sets.  You need to
1232 specify the terminal coding system when using multibyte text, so that
1233 Emacs knows which characters the terminal can actually handle.
1235   By default, output to the terminal is not translated at all, unless
1236 Emacs can deduce the proper coding system from your terminal type or
1237 your locale specification (@pxref{Language Environments}).
1239 @kindex C-x RET k
1240 @findex set-keyboard-coding-system
1241 @vindex keyboard-coding-system
1242   The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system})
1243 or the variable @code{keyboard-coding-system} specifies the coding
1244 system for keyboard input.  Character-code translation of keyboard
1245 input is useful for terminals with keys that send non-@acronym{ASCII}
1246 graphic characters---for example, some terminals designed for ISO
1247 Latin-1 or subsets of it.
1249   By default, keyboard input is translated based on your system locale
1250 setting.  If your terminal does not really support the encoding
1251 implied by your locale (for example, if you find it inserts a
1252 non-@acronym{ASCII} character if you type @kbd{M-i}), you will need to set
1253 @code{keyboard-coding-system} to @code{nil} to turn off encoding.
1254 You can do this by putting
1256 @lisp
1257 (set-keyboard-coding-system nil)
1258 @end lisp
1260 @noindent
1261 in your init file.
1263   There is a similarity between using a coding system translation for
1264 keyboard input, and using an input method: both define sequences of
1265 keyboard input that translate into single characters.  However, input
1266 methods are designed to be convenient for interactive use by humans, and
1267 the sequences that are translated are typically sequences of @acronym{ASCII}
1268 printing characters.  Coding systems typically translate sequences of
1269 non-graphic characters.
1271 @node Fontsets
1272 @section Fontsets
1273 @cindex fontsets
1275   A font typically defines shapes for a single alphabet or script.
1276 Therefore, displaying the entire range of scripts that Emacs supports
1277 requires a collection of many fonts.  In Emacs, such a collection is
1278 called a @dfn{fontset}.  A fontset is defined by a list of font specs,
1279 each assigned to handle a range of character codes, and may fall back
1280 on another fontset for characters which are not covered by the fonts
1281 it specifies.
1283   Each fontset has a name, like a font.  However, while fonts are
1284 stored in the system and the available font names are defined by the
1285 system, fontsets are defined within Emacs itself.  Once you have
1286 defined a fontset, you can use it within Emacs by specifying its name,
1287 anywhere that you could use a single font.  Of course, Emacs fontsets
1288 can use only the fonts that the system supports; if certain characters
1289 appear on the screen as hollow boxes, this means that the fontset in
1290 use for them has no font for those characters.@footnote{The Emacs
1291 installation instructions have information on additional font
1292 support.}
1294   Emacs creates three fontsets automatically: the @dfn{standard
1295 fontset}, the @dfn{startup fontset} and the @dfn{default fontset}.
1296 The default fontset is most likely to have fonts for a wide variety of
1297 non-@acronym{ASCII} characters and is the default fallback for the
1298 other two fontsets, and if you set a default font rather than fontset.
1299 However it does not specify font family names, so results can be
1300 somewhat random if you use it directly.  You can specify use of a
1301 specific fontset with the @samp{-fn} option.  For example,
1303 @example
1304 emacs -fn fontset-standard
1305 @end example
1307 @noindent
1308 You can also specify a fontset with the @samp{Font} resource (@pxref{X
1309 Resources}).
1311   If no fontset is specified for use, then Emacs uses an
1312 @acronym{ASCII} font, with @samp{fontset-default} as a fallback for
1313 characters the font does not cover.  The standard fontset is only used if
1314 explicitly requested, despite its name.
1316   A fontset does not necessarily specify a font for every character
1317 code.  If a fontset specifies no font for a certain character, or if
1318 it specifies a font that does not exist on your system, then it cannot
1319 display that character properly.  It will display that character as a
1320 hex code or thin space or an empty box instead.  (@xref{Text Display, ,
1321 glyphless characters}, for details.)
1323 @node Defining Fontsets
1324 @section Defining fontsets
1326 @vindex standard-fontset-spec
1327 @vindex w32-standard-fontset-spec
1328 @vindex ns-standard-fontset-spec
1329 @cindex standard fontset
1330   When running on X, Emacs creates a standard fontset automatically according to the value
1331 of @code{standard-fontset-spec}.  This fontset's name is
1333 @example
1334 -*-fixed-medium-r-normal-*-16-*-*-*-*-*-fontset-standard
1335 @end example
1337 @noindent
1338 or just @samp{fontset-standard} for short.
1340   On GNUstep and Mac, fontset-standard is created using the value of
1341 @code{ns-standard-fontset-spec}, and on Windows it is
1342 created using the value of @code{w32-standard-fontset-spec}.
1344   Bold, italic, and bold-italic variants of the standard fontset are
1345 created automatically.  Their names have @samp{bold} instead of
1346 @samp{medium}, or @samp{i} instead of @samp{r}, or both.
1348 @cindex startup fontset
1349   Emacs generates a fontset automatically, based on any default
1350 @acronym{ASCII} font that you specify with the @samp{Font} resource or
1351 the @samp{-fn} argument, or the default font that Emacs found when it
1352 started.  This is the @dfn{startup fontset} and its name is
1353 @code{fontset-startup}.  It does this by replacing the
1354 @var{charset_registry} field with @samp{fontset}, and replacing
1355 @var{charset_encoding} field with @samp{startup}, then using the
1356 resulting string to specify a fontset.
1358   For instance, if you start Emacs this way,
1360 @example
1361 emacs -fn "*courier-medium-r-normal--14-140-*-iso8859-1"
1362 @end example
1364 @noindent
1365 Emacs generates the following fontset and uses it for the initial X
1366 window frame:
1368 @example
1369 -*-courier-medium-r-normal-*-14-140-*-*-*-*-fontset-startup
1370 @end example
1372   The startup fontset will use the font that you specify or a variant
1373 with a different registry and encoding for all the characters which
1374 are supported by that font, and fallback on @samp{fontset-default} for
1375 other characters.
1377   With the X resource @samp{Emacs.Font}, you can specify a fontset name
1378 just like an actual font name.  But be careful not to specify a fontset
1379 name in a wildcard resource like @samp{Emacs*Font}---that wildcard
1380 specification matches various other resources, such as for menus, and
1381 menus cannot handle fontsets.
1383   You can specify additional fontsets using X resources named
1384 @samp{Fontset-@var{n}}, where @var{n} is an integer starting from 0.
1385 The resource value should have this form:
1387 @smallexample
1388 @var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}}
1389 @end smallexample
1391 @noindent
1392 @var{fontpattern} should have the form of a standard X font name, except
1393 for the last two fields.  They should have the form
1394 @samp{fontset-@var{alias}}.
1396   The fontset has two names, one long and one short.  The long name is
1397 @var{fontpattern}.  The short name is @samp{fontset-@var{alias}}.  You
1398 can refer to the fontset by either name.
1400   The construct @samp{@var{charset}:@var{font}} specifies which font to
1401 use (in this fontset) for one particular character set.  Here,
1402 @var{charset} is the name of a character set, and @var{font} is the
1403 font to use for that character set.  You can use this construct any
1404 number of times in defining one fontset.
1406   For the other character sets, Emacs chooses a font based on
1407 @var{fontpattern}.  It replaces @samp{fontset-@var{alias}} with values
1408 that describe the character set.  For the @acronym{ASCII} character font,
1409 @samp{fontset-@var{alias}} is replaced with @samp{ISO8859-1}.
1411   In addition, when several consecutive fields are wildcards, Emacs
1412 collapses them into a single wildcard.  This is to prevent use of
1413 auto-scaled fonts.  Fonts made by scaling larger fonts are not usable
1414 for editing, and scaling a smaller font is not useful because it is
1415 better to use the smaller font in its own size, which is what Emacs
1416 does.
1418   Thus if @var{fontpattern} is this,
1420 @example
1421 -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
1422 @end example
1424 @noindent
1425 the font specification for @acronym{ASCII} characters would be this:
1427 @example
1428 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
1429 @end example
1431 @noindent
1432 and the font specification for Chinese GB2312 characters would be this:
1434 @example
1435 -*-fixed-medium-r-normal-*-24-*-gb2312*-*
1436 @end example
1438   You may not have any Chinese font matching the above font
1439 specification.  Most X distributions include only Chinese fonts that
1440 have @samp{song ti} or @samp{fangsong ti} in @var{family} field.  In
1441 such a case, @samp{Fontset-@var{n}} can be specified as below:
1443 @smallexample
1444 Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
1445         chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
1446 @end smallexample
1448 @noindent
1449 Then, the font specifications for all but Chinese GB2312 characters have
1450 @samp{fixed} in the @var{family} field, and the font specification for
1451 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
1452 field.
1454 @findex create-fontset-from-fontset-spec
1455   The function that processes the fontset resource value to create the
1456 fontset is called @code{create-fontset-from-fontset-spec}.  You can also
1457 call this function explicitly to create a fontset.
1459   @xref{Fonts}, for more information about font naming.
1461 @node Modifying Fontsets
1462 @section Modifying Fontsets
1463 @cindex fontsets, modifying
1464 @findex set-fontset-font
1466   Fontsets do not always have to be created from scratch.  If only
1467 minor changes are required it may be easier to modify an existing
1468 fontset.  Modifying @samp{fontset-default} will also affect other
1469 fontsets that use it as a fallback, so can be an effective way of
1470 fixing problems with the fonts that Emacs chooses for a particular
1471 script.
1473 Fontsets can be modified using the function @code{set-fontset-font},
1474 specifying a character, a charset, a script, or a range of characters
1475 to modify the font for, and a font-spec for the font to be used. Some
1476 examples are:
1478 @example
1479 ;; Use Liberation Mono for latin-3 charset.
1480 (set-fontset-font "fontset-default" 'iso-8859-3 "Liberation Mono")
1482 ;; Prefer a big5 font for han characters
1483 (set-fontset-font "fontset-default" 'han (font-spec :registry "big5")
1484                   nil 'prepend)
1486 ;; Use DejaVu Sans Mono as a fallback in fontset-startup before
1487 ;; resorting to fontset-default.
1488 (set-fontset-font "fontset-startup" nil "DejaVu Sans Mono" nil 'append)
1490 ;; Use MyPrivateFont for the Unicode private use area.
1491 (set-fontset-font "fontset-default"  '(#xe000 . #xf8ff) "MyPrivateFont")
1493 @end example
1496 @node Undisplayable Characters
1497 @section Undisplayable Characters
1499   There may be a some non-@acronym{ASCII} characters that your terminal cannot
1500 display.  Most text-only terminals support just a single character
1501 set (use the variable @code{default-terminal-coding-system}
1502 (@pxref{Terminal Coding}) to tell Emacs which one); characters which
1503 can't be encoded in that coding system are displayed as @samp{?} by
1504 default.
1506   Graphical displays can display a broader range of characters, but
1507 you may not have fonts installed for all of them; characters that have
1508 no font appear as a hollow box.
1510   If you use Latin-1 characters but your terminal can't display
1511 Latin-1, you can arrange to display mnemonic @acronym{ASCII} sequences
1512 instead, e.g.@: @samp{"o} for o-umlaut.  Load the library
1513 @file{iso-ascii} to do this.
1515 @vindex latin1-display
1516   If your terminal can display Latin-1, you can display characters
1517 from other European character sets using a mixture of equivalent
1518 Latin-1 characters and @acronym{ASCII} mnemonics.  Customize the variable
1519 @code{latin1-display} to enable this.  The mnemonic @acronym{ASCII}
1520 sequences mostly correspond to those of the prefix input methods.
1522 @node Unibyte Mode
1523 @section Unibyte Editing Mode
1525 @cindex European character sets
1526 @cindex accented characters
1527 @cindex ISO Latin character sets
1528 @cindex Unibyte operation
1529   The ISO 8859 Latin-@var{n} character sets define character codes in
1530 the range 0240 to 0377 octal (160 to 255 decimal) to handle the
1531 accented letters and punctuation needed by various European languages
1532 (and some non-European ones).  Note that Emacs considers bytes with
1533 codes in this range as raw bytes, not as characters, even in a unibyte
1534 session, i.e.@: if you disable multibyte characters.  However, Emacs
1535 can still handle these character codes as if they belonged to
1536 @emph{one} of the single-byte character sets at a time.  To specify
1537 @emph{which} of these codes to use, invoke @kbd{M-x
1538 set-language-environment} and specify a suitable language environment
1539 such as @samp{Latin-@var{n}}.
1541   For more information about unibyte operation, see @ref{Enabling
1542 Multibyte}.  Note particularly that you probably want to ensure that
1543 your initialization files are read as unibyte if they contain
1544 non-@acronym{ASCII} characters.
1546 @vindex unibyte-display-via-language-environment
1547   Emacs can also display bytes in the range 160 to 255 as readable
1548 characters, provided the terminal or font in use supports them.  This
1549 works automatically.  On a graphical display, Emacs can also display
1550 single-byte characters through fontsets, in effect by displaying the
1551 equivalent multibyte characters according to the current language
1552 environment.  To request this, set the variable
1553 @code{unibyte-display-via-language-environment} to a non-@code{nil}
1554 value.  Note that setting this only affects how these bytes are
1555 displayed, but does not change the fundamental fact that Emacs treats
1556 them as raw bytes, not as characters.
1558 @cindex @code{iso-ascii} library
1559   If your terminal does not support display of the Latin-1 character
1560 set, Emacs can display these characters as @acronym{ASCII} sequences which at
1561 least give you a clear idea of what the characters are.  To do this,
1562 load the library @code{iso-ascii}.  Similar libraries for other
1563 Latin-@var{n} character sets could be implemented, but we don't have
1564 them yet.
1566 @findex standard-display-8bit
1567 @cindex 8-bit display
1568   Normally non-ISO-8859 characters (decimal codes between 128 and 159
1569 inclusive) are displayed as octal escapes.  You can change this for
1570 non-standard ``extended'' versions of ISO-8859 character sets by using the
1571 function @code{standard-display-8bit} in the @code{disp-table} library.
1573   There are two ways to input single-byte non-@acronym{ASCII}
1574 characters:
1576 @itemize @bullet
1577 @cindex 8-bit input
1578 @item
1579 You can use an input method for the selected language environment.
1580 @xref{Input Methods}.  When you use an input method in a unibyte buffer,
1581 the non-@acronym{ASCII} character you specify with it is converted to unibyte.
1583 @item
1584 If your keyboard can generate character codes 128 (decimal) and up,
1585 representing non-@acronym{ASCII} characters, you can type those character codes
1586 directly.
1588 On a graphical display, you should not need to do anything special to use
1589 these keys; they should simply work.  On a text-only terminal, you
1590 should use the command @code{M-x set-keyboard-coding-system} or the
1591 variable @code{keyboard-coding-system} to specify which coding system
1592 your keyboard uses (@pxref{Terminal Coding}).  Enabling this feature
1593 will probably require you to use @kbd{ESC} to type Meta characters;
1594 however, on a console terminal or in @code{xterm}, you can arrange for
1595 Meta to be converted to @kbd{ESC} and still be able type 8-bit
1596 characters present directly on the keyboard or using @kbd{Compose} or
1597 @kbd{AltGr} keys.  @xref{User Input}.
1599 @kindex C-x 8
1600 @cindex @code{iso-transl} library
1601 @cindex compose character
1602 @cindex dead character
1603 @item
1604 For Latin-1 only, you can use the key @kbd{C-x 8} as a ``compose
1605 character'' prefix for entry of non-@acronym{ASCII} Latin-1 printing
1606 characters.  @kbd{C-x 8} is good for insertion (in the minibuffer as
1607 well as other buffers), for searching, and in any other context where
1608 a key sequence is allowed.
1610 @kbd{C-x 8} works by loading the @code{iso-transl} library.  Once that
1611 library is loaded, the @key{ALT} modifier key, if the keyboard has
1612 one, serves the same purpose as @kbd{C-x 8}: use @key{ALT} together
1613 with an accent character to modify the following letter.  In addition,
1614 if the keyboard has keys for the Latin-1 ``dead accent characters,''
1615 they too are defined to compose with the following character, once
1616 @code{iso-transl} is loaded.
1618 Use @kbd{C-x 8 C-h} to list all the available @kbd{C-x 8} translations.
1619 @end itemize
1621 @node Charsets
1622 @section Charsets
1623 @cindex charsets
1625   In Emacs, @dfn{charset} is short for ``character set''.  Emacs
1626 supports most popular charsets (such as @code{ascii},
1627 @code{iso-8859-1}, @code{cp1250}, @code{big5}, and @code{unicode}), in
1628 addition to some charsets of its own (such as @code{emacs},
1629 @code{unicode-bmp}, and @code{eight-bit}).  All supported characters
1630 belong to one or more charsets.
1632   Emacs normally ``does the right thing'' with respect to charsets, so
1633 that you don't have to worry about them.  However, it is sometimes
1634 helpful to know some of the underlying details about charsets.
1636   One example is font selection (@pxref{Fonts}).  Each language
1637 environment (@pxref{Language Environments}) defines a ``priority
1638 list'' for the various charsets.  When searching for a font, Emacs
1639 initially attempts to find one that can display the highest-priority
1640 charsets.  For instance, in the Japanese language environment, the
1641 charset @code{japanese-jisx0208} has the highest priority, so Emacs
1642 tries to use a font whose @code{registry} property is
1643 @samp{JISX0208.1983-0}.
1645 @findex list-charset-chars
1646 @cindex characters in a certain charset
1647 @findex describe-character-set
1648   There are two commands that can be used to obtain information about
1649 charsets.  The command @kbd{M-x list-charset-chars} prompts for a
1650 charset name, and displays all the characters in that character set.
1651 The command @kbd{M-x describe-character-set} prompts for a charset
1652 name, and displays information about that charset, including its
1653 internal representation within Emacs.
1655 @findex list-character-sets
1656   To display a list of all supported charsets, type @kbd{M-x
1657 list-character-sets}.  The list gives the names of charsets and
1658 additional information to identity each charset (see
1659 @url{http://www.itscj.ipsj.or.jp/ISO-IR/} for details).  In this list,
1660 charsets are divided into two categories: @dfn{normal charsets} are
1661 listed first, followed by @dfn{supplementary charsets}.  A
1662 supplementary charset is one that is used to define another charset
1663 (as a parent or a subset), or to provide backward-compatibility for
1664 older Emacs versions.
1666   To find out which charset a character in the buffer belongs to, put
1667 point before it and type @kbd{C-u C-x =} (@pxref{International
1668 Chars}).
1670 @node Bidirectional Editing
1671 @section Bidirectional Editing
1672 @cindex bidirectional editing
1673 @cindex right-to-left text
1675   Emacs supports editing text written in scripts, such as Arabic and
1676 Hebrew, whose natural ordering of horizontal text for display is from
1677 right to left.  However, digits and Latin text embedded in these
1678 scripts are still displayed left to right.  It is also not uncommon to
1679 have small portions of text in Arabic or Hebrew embedded in otherwise
1680 Latin document, e.g., as comments and strings in a program source
1681 file.  For these reasons, text that uses these scripts is actually
1682 @dfn{bidirectional}: a mixture of runs of left-to-right and
1683 right-to-left characters.
1685   This section describes the facilities and options provided by Emacs
1686 for editing bidirectional text.
1688 @cindex logical order
1689 @cindex visual order
1690   Emacs stores right-to-left and bidirectional text in the so-called
1691 @dfn{logical} (or @dfn{reading}) order: the buffer or string position
1692 of the first character you read precedes that of the next character.
1693 Reordering of bidirectional text into the @dfn{visual} order happens
1694 at display time.  As result, character positions no longer increase
1695 monotonically with their positions on display.  Emacs implements the
1696 Unicode Bidirectional Algorithm described in the Unicode Standard
1697 Annex #9, for reordering of bidirectional text for display.
1699 @vindex bidi-display-reordering
1700   The buffer-local variable @code{bidi-display-reordering} controls
1701 whether text in the buffer is reordered for display.  If its value is
1702 non-@code{nil}, Emacs reorders characters that have right-to-left
1703 directionality when they are displayed.  The default value is
1704 @code{nil}.
1706   Each paragraph of bidirectional text can have its own @dfn{base
1707 direction}, either right-to-left or left-to-right.  (Paragraph
1708 boundaries are defined by the regular expressions
1709 @code{paragraph-start} and @code{paragraph-separate}, see
1710 @ref{Paragraphs}.)  Text in left-to-right paragraphs begins at the
1711 left margin of the window and is truncated or continued when it
1712 reaches the right margin.  By contrast, text in right-to-left
1713 paragraphs begins at the right margin and is continued or truncated at
1714 the left margin.
1716 @vindex bidi-paragraph-direction
1717   Emacs determines the base direction of each paragraph dynamically,
1718 based on the text at the beginning of the paragraph.  However,
1719 sometimes a buffer may need to force a certain base direction for its
1720 paragraphs.  The variable @code{bidi-paragraph-direction}, if
1721 non-@code{nil}, disables the dynamic determination of the base
1722 direction, and instead forces all paragraphs in the buffer to have the
1723 direction specified by its buffer-local value.  The value can be either
1724 @code{right-to-left} or @code{left-to-right}.  Any other value is
1725 interpreted as @code{nil}.
1727 @cindex LRM
1728 @cindex RLM
1729   Alternatively, you can control the base direction of a paragraph by
1730 inserting special formatting characters in front of the paragraph.
1731 The special character @code{RIGHT-TO-LEFT MARK}, or @sc{rlm}, forces
1732 the right-to-left direction on the following paragraph, while
1733 @code{LEFT-TO-RIGHT MARK}, or @sc{lrm} forces the left-to-right
1734 direction.  (You can use @kbd{C-x 8 RET} to insert these characters.)
1735 In a GUI session, the @sc{lrm} and @sc{rlm} characters display as
1736 blanks.
1738   Because characters are reordered for display, Emacs commands that
1739 operate in the logical order or on stretches of buffer positions may
1740 produce unusual effects.  For example, @kbd{C-f} and @kbd{C-b}
1741 commands move point in the logical order, so the cursor will sometimes
1742 jump when point traverses reordered bidirectional text.  Similarly, a
1743 highlighted region covering a contiguous range of character positions
1744 may look discontinuous if the region spans reordered text.  This is
1745 normal and similar to behavior of other programs that support
1746 bidirectional text.