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