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