codekingpro/portable-devtools
114k
1*mbyte.txt* For Vim version 9.2. Last change: 2026 Feb 142 3 4 VIM REFERENCE MANUAL by Bram Moolenaar et al.5 6 7Multi-byte support *multibyte* *multi-byte*8 *Chinese* *Japanese* *Korean*9This is about editing text in languages which have many characters that can10not be represented using one byte (one octet). Examples are Chinese, Japanese11and Korean. Unicode is also covered here.12 13For an introduction to the most common features, see |usr_45.txt| in the user14manual.15For changing the language of messages and menus see |mlang.txt|.16 171. Getting started |mbyte-first|182. Locale |mbyte-locale|193. Encoding |mbyte-encoding|204. Using a terminal |mbyte-terminal|215. Fonts on X11 |mbyte-fonts-X11|226. Fonts on MS-Windows |mbyte-fonts-MSwin|237. Input on X11 |mbyte-XIM|248. Input on MS-Windows |mbyte-IME|259. Input with a keymap |mbyte-keymap|2610. Input with imactivatefunc() |mbyte-func|2711. Using UTF-8 |mbyte-utf8|2812. Overview of options |mbyte-options|29 30NOTE: This file contains UTF-8 characters. These may show up as strange31characters or boxes when using another encoding.32 33==============================================================================341. Getting started *mbyte-first*35 36This is a summary of the multibyte features in Vim. If you are lucky it works37as described and you can start using Vim without much trouble. If something38doesn't work you will have to read the rest. Don't be surprised if it takes39quite a bit of work and experimenting to make Vim use all the multibyte40features. Unfortunately, every system has its own way to deal with multibyte41languages and it is quite complicated.42 43 44LOCALE45 46First of all, you must make sure your current locale is set correctly. If47your system has been installed to use the language, it probably works right48away. If not, you can often make it work by setting the $LANG environment49variable in your shell: >50 51 setenv LANG ja_JP.EUC52 53Unfortunately, the name of the locale depends on your system. Japanese might54also be called "ja_JP.EUCjp" or just "ja". To see what is currently used: >55 56 :language57 58To change the locale inside Vim use: >59 60 :language ja_JP.EUC61 62Vim will give an error message if this doesn't work. This is a good way to63experiment and find the locale name you want to use. But it's always better64to set the locale in the shell, so that it is used right from the start.65 66See |mbyte-locale| for details.67 68 69ENCODING70 71If your locale works properly, Vim will try to set the 'encoding' option72accordingly. If this doesn't work you can overrule its value: >73 74 :set encoding=utf-875 76See |encoding-values| for a list of acceptable values.77 78The result is that all the text that is used inside Vim will be in this79encoding. Not only the text in the buffers, but also in registers, variables,80etc. This also means that changing the value of 'encoding' makes the existing81text invalid! The text doesn't change, but it will be displayed wrong.82 83You can edit files in another encoding than what 'encoding' is set to. Vim84will convert the file when you read it and convert it back when you write it.85See 'fileencoding', 'fileencodings' and |++enc|.86 87 88DISPLAY AND FONTS89 90If you are working in a terminal (emulator) you must make sure it accepts the91same encoding as which Vim is working with. If this is not the case, you can92use the 'termencoding' option to make Vim convert text automatically.93 94For the GUI you must select fonts that work with the current 'encoding'. This95is the difficult part. It depends on the system you are using, the locale and96a few other things. See the chapters on fonts: |mbyte-fonts-X11| for97X-Windows and |mbyte-fonts-MSwin| for MS-Windows.98 99For GTK+ 2, you can skip most of this section. The option 'guifontset' does100no longer exist. You only need to set 'guifont' and everything should "just101work". If your system comes with Xft2 and fontconfig and the current font102does not contain a certain glyph, a different font will be used automatically103if available. The 'guifontwide' option is still supported but usually you do104not need to set it. It is only necessary if the automatic font selection does105not suit your needs.106 107For X11 you can set the 'guifontset' option to a list of fonts that together108cover the characters that are used. Example for Korean: >109 110 :set guifontset=k12,r12111 112Alternatively, you can set 'guifont' and 'guifontwide'. 'guifont' is used for113the single-width characters, 'guifontwide' for the double-width characters.114Thus the 'guifontwide' font must be exactly twice as wide as 'guifont'.115Example for UTF-8: >116 117 :set guifont=-misc-fixed-medium-r-normal-*-18-120-100-100-c-90-iso10646-1118 :set guifontwide=-misc-fixed-medium-r-normal-*-18-120-100-100-c-180-iso10646-1119 120You can also set 'guifont' alone, Vim will try to find a matching121'guifontwide' for you.122 123 124INPUT125 126There are several ways to enter multibyte characters:127- For X11 XIM can be used. See |XIM|.128- For MS-Windows IME can be used. See |IME|.129- For all systems keymaps can be used. See |mbyte-keymap|.130 131The options 'iminsert', 'imsearch' and 'imcmdline' can be used to choose132the different input methods or disable them temporarily.133 134==============================================================================1352. Locale *mbyte-locale*136 137The easiest setup is when your whole system uses the locale you want to work138in. But it's also possible to set the locale for one shell you are working139in, or just use a certain locale inside Vim.140 141 142WHAT IS A LOCALE? *locale*143 144There are many languages in the world. And there are different cultures and145environments at least as many as the number of languages. A linguistic146environment corresponding to an area is called "locale". This includes147information about the used language, the charset, collating order for sorting,148date format, currency format and so on. For Vim only the language and charset149really matter.150 151You can only use a locale if your system has support for it. Some systems152have only a few locales, especially in the USA. The language which you want153to use may not be on your system. In that case you might be able to install154it as an extra package. Check your system documentation for how to do that.155 156The location in which the locales are installed varies from system to system.157For example, "/usr/share/locale" or "/usr/lib/locale". See your system's158setlocale() man page.159 160Looking in these directories will show you the exact name of each locale.161Mostly upper/lowercase matters, thus "ja_JP.EUC" and "ja_jp.euc" are162different. Some systems have a locale.alias file, which allows translation163from a short name like "nl" to the full name "nl_NL.ISO_8859-1".164 165Note that X-windows has its own locale stuff. And unfortunately uses locale166names different from what is used elsewhere. This is confusing! For Vim it167matters what the setlocale() function uses, which is generally NOT the168X-windows stuff. You might have to do some experiments to find out what169really works.170 171 *locale-name*172The (simplified) format of |locale| name is:173 174 language175or language_territory176or language_territory.codeset177 178Territory means the country (or part of it), codeset means the |charset|. For179example, the locale name "ja_JP.eucJP" means:180 ja the language is Japanese181 JP the country is Japan182 eucJP the codeset is EUC-JP183But it also could be "ja", "ja_JP.EUC", "ja_JP.ujis", etc. And unfortunately,184the locale name for a specific language, territory and codeset is not unified185and depends on your system.186 187Examples of locale name:188 charset language locale name ~189 GB2312 Chinese (simplified) zh_CN.EUC, zh_CN.GB2312190 Big5 Chinese (traditional) zh_TW.BIG5, zh_TW.Big5191 CNS-11643 Chinese (traditional) zh_TW192 EUC-JP Japanese ja, ja_JP.EUC, ja_JP.ujis, ja_JP.eucJP193 Shift_JIS Japanese ja_JP.SJIS, ja_JP.Shift_JIS194 EUC-KR Korean ko, ko_KR.EUC195 196 197USING A LOCALE198 199To start using a locale for the whole system, see the documentation of your200system. Mostly you need to set it in a configuration file in "/etc".201 202To use a locale in a shell, set the $LANG environment value. When you want to203use Korean and the |locale| name is "ko", do this:204 205 sh: export LANG=ko206 csh: setenv LANG ko207 208You can put this in your ~/.profile or ~/.cshrc file to always use it.209 210To use a locale in Vim only, use the |:language| command: >211 212 :language ko213 214Put this in your ~/.vimrc file to use it always.215 216Or specify $LANG when starting Vim:217 218 sh: LANG=ko vim {vim-arguments}219 csh: env LANG=ko vim {vim-arguments}220 221You could make a small shell script for this.222 223==============================================================================2243. Encoding *mbyte-encoding*225 226Vim uses the 'encoding' option to specify how characters are identified and227encoded when they are used inside Vim. This applies to all the places where228text is used, including buffers (files loaded into memory), registers and229variables.230 231 *charset* *codeset*232Charset is another name for encoding. There are subtle differences, but these233don't matter when using Vim. "codeset" is another similar name.234 235Each character is encoded as one or more bytes. When all characters are236encoded with one byte, we call this a single-byte encoding. The most often237used one is called "latin1". This limits the number of characters to 256.238Some of these are control characters, thus even fewer can be used for text.239 240When some characters use two or more bytes, we call this a multibyte241encoding. This allows using much more than 256 characters, which is required242for most East Asian languages.243 244Most multibyte encodings use one byte for the first 127 characters. These245are equal to ASCII, which makes it easy to exchange plain-ASCII text, no246matter what language is used. Thus you might see the right text even when the247encoding was set wrong.248 249 *encoding-names*250Vim can use many different character encodings. There are three major groups:251 2521 8bit Single-byte encodings, 256 different characters. Mostly used253 in USA and Europe. Example: ISO-8859-1 (Latin1). All254 characters occupy one screen cell only.255 2562 2byte Double-byte encodings, over 10000 different characters.257 Mostly used in Asian countries. Example: euc-kr (Korean)258 The number of screen cells is equal to the number of bytes259 (except for euc-jp when the first byte is 0x8e).260 261u Unicode Universal encoding, can replace all others. ISO 10646.262 Millions of different characters. Example: UTF-8. The263 relation between bytes and screen cells is complex.264 265Other encodings cannot be used by Vim internally. But files in other266encodings can be edited by using conversion, see 'fileencoding'.267Note that all encodings must use ASCII for the characters up to 128 (except268when compiled for EBCDIC).269 270Supported 'encoding' values are: *encoding-values*2711 latin1 8-bit characters (ISO 8859-1, also used for cp1252)2721 iso-8859-n ISO_8859 variant (n = 2 to 15)2731 koi8-r Russian2741 koi8-u Ukrainian2751 macroman MacRoman (Macintosh encoding)2761 8bit-{name} any 8-bit encoding (Vim specific name)2771 cp437 similar to iso-8859-12781 cp737 similar to iso-8859-72791 cp775 Baltic2801 cp850 similar to iso-8859-42811 cp852 similar to iso-8859-12821 cp855 similar to iso-8859-22831 cp857 similar to iso-8859-52841 cp860 similar to iso-8859-92851 cp861 similar to iso-8859-12861 cp862 similar to iso-8859-12871 cp863 similar to iso-8859-82881 cp865 similar to iso-8859-12891 cp866 similar to iso-8859-52901 cp869 similar to iso-8859-72911 cp874 Thai2921 cp1250 Czech, Polish, etc.2931 cp1251 Cyrillic2941 cp1253 Greek2951 cp1254 Turkish2961 cp1255 Hebrew2971 cp1256 Arabic2981 cp1257 Baltic2991 cp1258 Vietnamese3001 cp{number} MS-Windows: any installed single-byte codepage3012 cp932 Japanese (Windows only)3022 euc-jp Japanese (Unix only)3032 sjis Japanese (Unix only)3042 cp949 Korean (Unix and Windows)3052 euc-kr Korean (Unix only)3062 cp936 simplified Chinese (Windows only)3072 euc-cn simplified Chinese (Unix only)3082 cp950 traditional Chinese (on Unix alias for big5)3092 big5 traditional Chinese (on Windows alias for cp950)3102 euc-tw traditional Chinese (Unix only)3112 2byte-{name} Unix: any double-byte encoding (Vim specific name)3122 cp{number} MS-Windows: any installed double-byte codepage313u utf-8 32 bit UTF-8 encoded Unicode (ISO/IEC 10646-1)314u ucs-2 16 bit UCS-2 encoded Unicode (ISO/IEC 10646-1)315u ucs-2le like ucs-2, little endian316u utf-16 ucs-2 extended with double-words for more characters317u utf-16le like utf-16, little endian318u ucs-4 32 bit UCS-4 encoded Unicode (ISO/IEC 10646-1)319u ucs-4le like ucs-4, little endian320 321The {name} can be any encoding name that your system supports. It is passed322to iconv() to convert between the encoding of the file and the current locale.323For MS-Windows "cp{number}" means using codepage {number}.324Examples: >325 :set encoding=8bit-cp1252326 :set encoding=2byte-cp932327 328The MS-Windows codepage 1252 is very similar to latin1. For practical reasons329the same encoding is used and it's called latin1. 'isprint' can be used to330display the characters 0x80 - 0xA0 or not.331 332Several aliases can be used, they are translated to one of the names above.333An incomplete list:334 3351 ansi same as latin1 (obsolete, for backward compatibility)3362 japan Japanese: on Unix "euc-jp", on MS-Windows cp9323372 korea Korean: on Unix "euc-kr", on MS-Windows cp9493382 prc simplified Chinese: on Unix "euc-cn", on MS-Windows cp9363392 chinese same as "prc"3402 taiwan traditional Chinese: on Unix "euc-tw", on MS-Windows cp950341u utf8 same as utf-8342u unicode same as ucs-2343u ucs2be same as ucs-2 (big endian)344u ucs-2be same as ucs-2 (big endian)345u ucs-4be same as ucs-4 (big endian)346u utf-32 same as ucs-4347u utf-32le same as ucs-4le348 default stands for the default value of 'encoding', depends on the349 environment350 351For the UCS codes the byte order matters. This is tricky, use UTF-8 whenever352you can. The default is to use big-endian (most significant byte comes353first):354 name bytes char ~355 ucs-2 11 22 1122356 ucs-2le 22 11 1122357 ucs-4 11 22 33 44 11223344358 ucs-4le 44 33 22 11 11223344359 360On MS-Windows systems you often want to use "ucs-2le", because it uses little361endian UCS-2.362 363There are a few encodings which are similar, but not exactly the same. Vim364treats them as if they were different encodings, so that conversion will be365done when needed. You might want to use the similar name to avoid conversion366or when conversion is not possible:367 368 cp932, shift-jis, sjis369 cp936, euc-cn370 371 *encoding-table*372Normally 'encoding' is equal to your current locale and 'termencoding' is373empty. This means that your keyboard and display work with characters encoded374in your current locale, and Vim uses the same characters internally.375 376You can make Vim use characters in a different encoding by setting the377'encoding' option to a different value. Since the keyboard and display still378use the current locale, conversion needs to be done. The 'termencoding' then379takes over the value of the current locale, so Vim converts between 'encoding'380and 'termencoding'. Example: >381 :let &termencoding = &encoding382 :set encoding=utf-8383 384However, not all combinations of values are possible. The table below tells385you how each of the nine combinations works. This is further restricted by386not all conversions being possible, iconv() being present, etc. Since this387depends on the system used, no detailed list can be given.388 389('tenc' is the short name for 'termencoding' and 'enc' short for 'encoding')390 391'tenc' 'enc' remark ~392 393 8bit 8bit Works. When 'termencoding' is different from394 'encoding' typing and displaying may be wrong for some395 characters, Vim does NOT perform conversion (set396 'encoding' to "utf-8" to get this).397 8bit 2byte MS-Windows: works for all codepages installed on your398 system; you can only type 8bit characters;399 Other systems: does NOT work.400 8bit Unicode Works, but only 8bit characters can be typed directly401 (others through digraphs, keymaps, etc.); in a402 terminal you can only see 8bit characters; the GUI can403 show all characters that the 'guifont' supports.404 405 2byte 8bit Works, but typing non-ASCII characters might406 be a problem.407 2byte 2byte MS-Windows: works for all codepages installed on your408 system; typing characters might be a problem when409 locale is different from 'encoding'.410 Other systems: Only works when 'termencoding' is equal411 to 'encoding', you might as well leave it empty.412 2byte Unicode works, Vim will translate typed characters.413 414 Unicode 8bit works (unusual)415 Unicode 2byte does NOT work416 Unicode Unicode works very well (leaving 'termencoding' empty works417 the same way, because all Unicode is handled418 internally as UTF-8)419 420CONVERSION *charset-conversion*421 422Vim will automatically convert from one to another encoding in several places:423- When reading a file and 'fileencoding' is different from 'encoding'424- When writing a file and 'fileencoding' is different from 'encoding'425- When displaying characters and 'termencoding' is different from 'encoding'426- When reading input and 'termencoding' is different from 'encoding'427- When displaying messages and the encoding used for LC_MESSAGES differs from428 'encoding' (requires a gettext version that supports this).429- When reading a Vim script where |:scriptencoding| is different from430 'encoding'.431- When reading or writing a |viminfo| file.432Most of these require the |+iconv| feature. Conversion for reading and433writing files may also be specified with the 'charconvert' option.434 435Useful utilities for converting the charset:436 All: iconv437 GNU iconv can convert most encodings. Unicode is used as the438 intermediate encoding, which allows conversion from and to all other439 encodings. See http://www.gnu.org/directory/libiconv.html.440 441 Japanese: nkf442 Nkf is "Network Kanji code conversion Filter". One of the most unique443 facility of nkf is the guess of the input Kanji code. So, you don't444 need to know what the inputting file's |charset| is. When convert to445 EUC-JP from ISO-2022-JP or Shift_JIS, simply do the following command446 in Vim:447 :%!nkf -e448 Nkf can be found at:449 http://www.sfc.wide.ad.jp/~max/FreeBSD/ports/distfiles/nkf-1.62.tar.gz450 451 Chinese: hc452 Hc is "Hanzi Converter". Hc convert a GB file to a Big5 file, or Big5453 file to GB file. Hc can be found at:454 https://www.freshports.org/chinese/hc455 ftp://ftp.cuhk.hk/pub/chinese/ifcss/software/unix/convert/hc-30.tar.gz456 457 Korean: hmconv458 Hmconv is Korean code conversion utility especially for E-mail. It459 can convert between EUC-KR and ISO-2022-KR. Hmconv can be found at:460 https://www.freshports.org/korean/hmconv/461 462 Multilingual: lv463 Lv is a Powerful Multilingual File Viewer. And it can be worked as464 |charset| converter. Supported |charset|: ISO-2022-CN, ISO-2022-JP,465 ISO-2022-KR, EUC-CN, EUC-JP, EUC-KR, EUC-TW, UTF-7, UTF-8, ISO-8859466 series, Shift_JIS, Big5 and HZ. Lv can be found at (link seems dead):467 ff.iij4u.or.jp/~nrt/lv/index.html468 469 470 *mbyte-conversion*471When reading and writing files in an encoding different from 'encoding',472conversion needs to be done. These conversions are supported:473- All conversions between Latin-1 (ISO-8859-1), UTF-8, UCS-2 and UCS-4 are474 handled internally.475- For MS-Windows, when 'encoding' is a Unicode encoding, conversion from and476 to any codepage should work.477- Conversion specified with 'charconvert'478- Conversion with the iconv library, if it is available.479 Old versions of GNU iconv() may cause the conversion to fail (they480 request a very large buffer, more than Vim is willing to provide).481 Try getting another iconv() implementation.482 483 *iconv-dynamic*484On MS-Windows Vim can be compiled with the |+iconv/dyn| feature. This means485Vim will search for the "iconv.dll" and "libiconv.dll" libraries. When486neither of them can be found Vim will still work but some conversions won't be487possible.488 489==============================================================================4904. Using a terminal *mbyte-terminal*491 492The GUI fully supports multibyte characters. It is also possible in a493terminal, if the terminal supports the same encoding that Vim uses. Thus this494is less flexible.495 496For example, you can run Vim in an xterm with added multibyte support and/or497|XIM|. Examples are kterm (Kanji term) and hanterm (for Korean), Eterm498(Enlightened terminal) and rxvt.499 500If your terminal does not support the right encoding, you can set the501'termencoding' option. Vim will then convert the typed characters from502'termencoding' to 'encoding'. And displayed text will be converted from503'encoding' to 'termencoding'. If the encoding supported by the terminal504doesn't include all the characters that Vim uses, this leads to lost505characters. This may mess up the display. If you use a terminal that506supports Unicode, such as the xterm mentioned below, it should work just fine,507since nearly every character set can be converted to Unicode without loss of508information.509 510 511UTF-8 IN XFREE86 XTERM *UTF8-xterm*512 513This is a short explanation of how to use UTF-8 character encoding in the514xterm that comes with XFree86 by Thomas Dickey (text by Markus Kuhn).515 516Get the latest xterm version which has now UTF-8 support:517 518 http://invisible-island.net/xterm/xterm.html519 520Compile it with "./configure --enable-wide-chars ; make"521 522Also get the ISO 10646-1 version of various fonts, which is available on523 524 http://www.cl.cam.ac.uk/~mgk25/download/ucs-fonts.tar.gz525 526and install the font as described in the README file.527 528Now start xterm with >529 530 xterm -u8 -fn -misc-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso10646-1531or, for bigger character: >532 xterm -u8 -fn -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso10646-1533 534and you will have a working UTF-8 terminal emulator. Try both >535 536 cat utf-8-demo.txt537 vim utf-8-demo.txt538 539with the demo text that comes with ucs-fonts.tar.gz in order to see540whether there are any problems with UTF-8 in your xterm.541 542For Vim you may need to set 'encoding' to "utf-8".543 544==============================================================================5455. Fonts on X11 *mbyte-fonts-X11*546 547Unfortunately, using fonts in X11 is complicated. The name of a single-byte548font is a long string. For multibyte fonts we need several of these...549 550Note: Most of this is no longer relevant for GTK+ 2. Selecting a font via551its XLFD is not supported; see 'guifont' for an example of how to552set the font. Do yourself a favor and ignore the |XLFD| and |xfontset|553sections below.554 555First of all, Vim only accepts fixed-width fonts for displaying text. You556cannot use proportionally spaced fonts. This excludes many of the available557(and nicer looking) fonts. However, for menus and tooltips any font can be558used.559 560Note that Display and Input are independent. It is possible to see your561language even though you have no input method for it.562 563You should get a default font for menus and tooltips that works, but it might564be ugly. Read the following to find out how to select a better font.565 566 567X LOGICAL FONT DESCRIPTION (XLFD)568 *XLFD*569XLFD is the X font name and contains the information about the font size,570charset, etc. The name is in this format:571 572FOUNDRY-FAMILY-WEIGHT-SLANT-WIDTH-STYLE-PIXEL-POINT-X-Y-SPACE-AVE-CR-CE573 574Each field means:575 576- FOUNDRY: FOUNDRY field. The company that created the font.577- FAMILY: FAMILY_NAME field. Basic font family name. (helvetica, gothic,578 times, etc)579- WEIGHT: WEIGHT_NAME field. How thick the letters are. (light, medium,580 bold, etc)581- SLANT: SLANT field.582 r: Roman (no slant)583 i: Italic584 o: Oblique585 ri: Reverse Italic586 ro: Reverse Oblique587 ot: Other588 number: Scaled font589- WIDTH: SETWIDTH_NAME field. Width of characters. (normal, condensed,590 narrow, double wide)591- STYLE: ADD_STYLE_NAME field. Extra info to describe font. (Serif, Sans592 Serif, Informal, Decorated, etc)593- PIXEL: PIXEL_SIZE field. Height, in pixels, of characters.594- POINT: POINT_SIZE field. Ten times height of characters in points.595- X: RESOLUTION_X field. X resolution (dots per inch).596- Y: RESOLUTION_Y field. Y resolution (dots per inch).597- SPACE: SPACING field.598 p: Proportional599 m: Monospaced600 c: CharCell601- AVE: AVERAGE_WIDTH field. Ten times average width in pixels.602- CR: CHARSET_REGISTRY field. The name of the charset group.603- CE: CHARSET_ENCODING field. The rest of the charset name. For some604 charsets, such as JIS X 0208, if this field is 0, codepoints has605 the same value as GL, and GR if 1.606 607For example, in case of a 16 dots font corresponding to JIS X 0208, it is608written like:609 -misc-fixed-medium-r-normal--16-110-100-100-c-160-jisx0208.1990-0610 611 612X FONTSET613 *fontset* *xfontset*614A single-byte charset is typically associated with one font. For multibyte615charsets a combination of fonts is often used. This means that one group of616characters are used from one font and another group from another font (which617might be double wide). This collection of fonts is called a fontset.618 619Which fonts are required in a fontset depends on the current locale. X620windows maintains a table of which groups of characters are required for a621locale. You have to specify all the fonts that a locale requires in the622'guifontset' option.623 624Setting the 'guifontset' option also means that all font names will be handled625as a fontset name. Also the ones used for the "font" argument of the626|:highlight| command.627 628Note the difference between 'guifont' and 'guifontset': In 'guifont'629the comma-separated names are alternative names, one of which will be630used. In 'guifontset' the whole string is one fontset name,631including the commas. It is not possible to specify alternative632fontset names.633This example works on many X11 systems: >634 :set guifontset=-*-*-medium-r-normal--16-*-*-*-c-*-*-*635<636The fonts must match with the current locale. If fonts for the character sets637that the current locale uses are not included, setting 'guifontset' will fail.638 639NOTE: The fontset always uses the current locale, even though 'encoding' may640be set to use a different charset. In that situation you might want to use641'guifont' and 'guifontwide' instead of 'guifontset'.642 643Example:644 |charset| language "groups of characters" ~645 GB2312 Chinese (simplified) ISO-8859-1 and GB 2312646 Big5 Chinese (traditional) ISO-8859-1 and Big5647 CNS-11643 Chinese (traditional) ISO-8859-1, CNS 11643-1 and CNS 11643-2648 EUC-JP Japanese JIS X 0201 and JIS X 0208649 EUC-KR Korean ISO-8859-1 and KS C 5601 (KS X 1001)650 651You can search for fonts using the xlsfonts command. For example, when you're652searching for a font for KS C 5601: >653 xlsfonts | grep ksc5601654 655This is complicated and confusing. You might want to consult the X-Windows656documentation if there is something you don't understand.657 658 *base_font_name_list*659When you have found the names of the fonts you want to use, you need to set660the 'guifontset' option. You specify the list by concatenating the font names661and putting a comma in between them.662 663For example, when you use the ja_JP.eucJP locale, this requires JIS X 0201664and JIS X 0208. You could supply a list of fonts that explicitly specifies665the charsets, like: >666 667 :set guifontset=-misc-fixed-medium-r-normal--14-130-75-75-c-140-jisx0208.1983-0,668 \-misc-fixed-medium-r-normal--14-130-75-75-c-70-jisx0201.1976-0669 670Alternatively, you can supply a base font name list that omits the charset671name, letting X-Windows select font characters required for the locale. For672example: >673 674 :set guifontset=-misc-fixed-medium-r-normal--14-130-75-75-c-140,675 \-misc-fixed-medium-r-normal--14-130-75-75-c-70676 677Alternatively, you can supply a single base font name that allows X-Windows to678select from all available fonts. For example: >679 680 :set guifontset=-misc-fixed-medium-r-normal--14-*681 682Alternatively, you can specify alias names. See the fonts.alias file in the683fonts directory (e.g., /usr/X11R6/lib/X11/fonts/). For example: >684 685 :set guifontset=k14,r14686<687 *E253*688Note that in East Asian fonts, the standard character cell is square. When689mixing a Latin font and an East Asian font, the East Asian font width should690be twice the Latin font width.691 692If 'guifontset' is not empty, the "font" argument of the |:highlight| command693is also interpreted as a fontset. For example, you should use for694highlighting: >695 :hi Comment font=english_font,your_font696If you use a wrong "font" argument you will get an error message.697Also make sure that you set 'guifontset' before setting fonts for highlight698groups.699 700 701USING RESOURCE FILES702 703Instead of specifying 'guifontset', you can set X11 resources and Vim will704pick them up. This is only for people who know how X resource files work.705 706For Motif insert these three lines in your $HOME/.Xdefaults file:707 708 Vim.font: |base_font_name_list|709 Vim*fontSet: |base_font_name_list|710 Vim*fontList: your_language_font711 712Note: Vim.font is for text area.713 Vim*fontSet is for menu.714 Vim*fontList is for menu (for Motif GUI)715 716For example, when you are using Japanese and a 14 dots font, >717 718 Vim.font: -misc-fixed-medium-r-normal--14-*719 Vim*fontSet: -misc-fixed-medium-r-normal--14-*720 Vim*fontList: -misc-fixed-medium-r-normal--14-*721<722or: >723 724 Vim*font: k14,r14725 Vim*fontSet: k14,r14726 Vim*fontList: k14,r14727<728To have them take effect immediately you will have to do >729 730 xrdb -merge ~/.Xdefaults731 732Otherwise you will have to stop and restart the X server before the changes733take effect.734 735 736The GTK+ version of GUI Vim does not use .Xdefaults, use ~/.gtkrc instead.737The default mostly works OK. But for the menus you might have to change738it. Example: >739 740 style "default"741 {742 fontset="-*-*-medium-r-normal--14-*-*-*-c-*-*-*"743 }744 widget_class "*" style "default"745 746==============================================================================7476. Fonts on MS-Windows *mbyte-fonts-MSwin*748 749The simplest is to use the font dialog to select fonts and try them out. You750can find this at the "Edit/Select Font..." menu. Once you find a font name751that works well you can use this command to see its name: >752 753 :set guifont754 755Then add a command to your |gvimrc| file to set 'guifont': >756 757 :set guifont=courier_new:h12758 759==============================================================================7607. Input on X11 *mbyte-XIM*761 762X INPUT METHOD (XIM) BACKGROUND *XIM* *xim* *x-input-method*763 764XIM is an international input module for X. There are two kinds of765structures, Xlib unit type and |IM-server| (Input-Method server) type.766|IM-server| type is suitable for complex input, such as CJK.767 768- IM-server769 *IM-server*770 In |IM-server| type input structures, the input event is handled by either771 of the two ways: FrontEnd system and BackEnd system. In the FrontEnd772 system, input events are snatched by the |IM-server| first, then |IM-server|773 give the application the result of input. On the other hand, the BackEnd774 system works reverse order. MS-Windows adopt BackEnd system. In X, most of775 |IM-server|s adopt FrontEnd system. The demerit of BackEnd system is the776 large overhead in communication, but it provides safe synchronization with777 no restrictions on applications.778 779 For example, there are xwnmo and kinput2 Japanese |IM-server|, both are780 FrontEnd system. Xwnmo is distributed with Wnn (see below), kinput2 can be781 found at (link seems dead): ftp://ftp.sra.co.jp/pub/x11/kinput2/782 783 For Chinese, there's a great XIM server named "xcin", you can input both784 Traditional and Simplified Chinese characters. And it can accept other785 locale if you make a correct input table. Xcin can be found at (link seems786 dead): http://cle.linux.org.tw/xcin/787 Others are scim: https://www.freedesktop.org/wiki/Software/scim/ and fcitx:788 http://www.fcitx.org/789 790- Conversion Server791 *conversion-server*792 Some system needs additional server: conversion server. Most of Japanese793 |IM-server|s need it, Kana-Kanji conversion server. For Chinese inputting,794 it depends on the method of inputting, in some methods, PinYin or ZhuYin to795 HanZi conversion server is needed. For Korean inputting, if you want to796 input Hanja, Hangul-Hanja conversion server is needed.797 798 For example, the Japanese inputting process is divided into 2 steps. First799 we pre-input Hira-gana, second Kana-Kanji conversion. There are so many800 Kanji characters (6349 Kanji characters are defined in JIS X 0208) and the801 number of Hira-gana characters are 76. So, first, we pre-input text as802 pronounced in Hira-gana, second, we convert Hira-gana to Kanji or Kata-Kana,803 if needed. There are some Kana-Kanji conversion server: jserver804 (distributed with Wnn, see below) and canna. Canna can be found at:805 (dead link) osdn.net/projects/canna/806 807There is a good input system: Wnn4.2. Wnn 4.2 contains,808 xwnmo (|IM-server|)809 jserver (Japanese Kana-Kanji conversion server)810 cserver (Chinese PinYin or ZhuYin to simplified HanZi conversion server)811 tserver (Chinese PinYin or ZhuYin to traditional HanZi conversion server)812 kserver (Hangul-Hanja conversion server)813Wnn 4.2 for several systems can be found at various places on the internet.814Use the RPM or port for your system.815 816 817- Input Style818 *xim-input-style*819 When inputting CJK, there are four areas:820 1. The area to display of the input while it is being composed821 2. The area to display the currently active input mode.822 3. The area to display the next candidate for the selection.823 4. The area to display other tools.824 825 The third area is needed when converting. For example, in Japanese826 inputting, multiple Kanji characters could have the same pronunciation, so827 a sequence of Hira-gana characters could map to a distinct sequence of Kanji828 characters.829 830 The first and second areas are defined in international input of X with the831 names of "Preedit Area", "Status Area" respectively. The third and fourth832 areas are not defined and are left to be managed by the |IM-server|. In the833 international input, four input styles have been defined using combinations834 of Preedit Area and Status Area: |OnTheSpot|, |OffTheSpot|, |OverTheSpot|835 and |Root|.836 837 Currently, GUI Vim supports three styles, |OverTheSpot|, |OffTheSpot| and838 |Root|.839 When compiled with |+GUI_GTK| feature, GUI Vim supports two styles,840 |OnTheSpot| and |OverTheSpot|. You can select the style with the 'imstyle'841 option.842 843*. on-the-spot *OnTheSpot*844 Preedit Area and Status Area are performed by the client application in845 the area of application. The client application is directed by the846 |IM-server| to display all pre-edit data at the location of text847 insertion. The client registers callbacks invoked by the input method848 during pre-editing.849*. over-the-spot *OverTheSpot*850 Status Area is created in a fixed position within the area of application,851 in case of Vim, the position is the additional status line. Preedit Area852 is made at present input position of application. The input method853 displays pre-edit data in a window which it brings up directly over the854 text insertion position.855*. off-the-spot *OffTheSpot*856 Preedit Area and Status Area are performed in the area of application, in857 case of Vim, the area is additional status line. The client application858 provides display windows for the pre-edit data to the input method which859 displays into them directly.860*. root-window *Root*861 Preedit Area and Status Area are outside of the application. The input862 method displays all pre-edit data in a separate area of the screen in a863 window specific to the input method.864 865 866USING XIM *multibyte-input* *E284* *E285* *E286* *E287*867 *E288* *E289*868 869Note that Display and Input are independent. It is possible to see your870language even though you have no input method for it. But when your Display871method doesn't match your Input method, the text will be displayed wrong.872 873 Note: You can not use IM unless you specify 'guifontset'.874 Therefore, Latin users, you have to also use 'guifontset'875 if you use IM.876 877To input your language you should run the |IM-server| which supports your878language and |conversion-server| if needed.879 880The next 3 lines should be put in your ~/.Xdefaults file. They are common for881all X applications which uses |XIM|. If you already use |XIM|, you can skip882this. >883 884 *international: True885 *.inputMethod: your_input_server_name886 *.preeditType: your_input_style887<888input_server_name is your |IM-server| name (check your |IM-server|889 manual).890your_input_style is one of |OverTheSpot|, |OffTheSpot|, |Root|. See891 also |xim-input-style|.892 893*international may not be necessary if you use X11R6.894*.inputMethod and *.preeditType are optional if you use X11R6.895 896For example, when you are using kinput2 as |IM-server|, >897 898 *international: True899 *.inputMethod: kinput2900 *.preeditType: OverTheSpot901<902When using |OverTheSpot|, GUI Vim always connects to the IM Server even in903Normal mode, so you can input your language with commands like "f" and "r".904But when using one of the other two methods, GUI Vim connects to the IM Server905only if it is not in Normal mode.906 907If your IM Server does not support |OverTheSpot|, and if you want to use your908language with some Normal mode command like "f" or "r", then you should use a909localized xterm or an xterm which supports |XIM|910 911If needed, you can set the XMODIFIERS environment variable:912 913 sh: export XMODIFIERS="@im=input_server_name"914 csh: setenv XMODIFIERS "@im=input_server_name"915 916For example, when you are using kinput2 as |IM-server| and sh, >917 918 export XMODIFIERS="@im=kinput2"919<920 921FULLY CONTROLLED XIM922 923You can fully control XIM, like with IME of MS-Windows (see |multibyte-ime|).924This is currently only available for the GTK GUI.925 926Before using fully controlled XIM, one setting is required. Set the927'imactivatekey' option to the key that is used for the activation of the input928method. For example, when you are using kinput2 + canna as IM Server, the929activation key is probably Shift+Space: >930 931 :set imactivatekey=S-space932 933See 'imactivatekey' for the format.934 935==============================================================================9368. Input on MS-Windows *mbyte-IME*937 938(Windows IME support) *multibyte-ime* *IME*939 940{only works Windows GUI and compiled with the |+multi_byte_ime| feature}941 942To input multibyte characters on Windows, you can use an Input Method Editor943(IME). In process of your editing text, you must switch status (on/off) of944IME many many many times. Because IME with status on is hooking all of your945key inputs, you cannot input 'j', 'k', or almost all of keys to Vim directly.946 947The |+multi_byte_ime| feature helps for this. It reduces the number of times948the IME status has to be switched manually. In Normal mode, there is almost949no need to use IME, even when editing multibyte text. So when exiting Insert950mode, Vim memorizes the last status of IME and turns off IME. When951re-entering Insert mode, Vim sets the IME status to that memorized status952automatically.953 954This works on not only insert-normal mode, but also search-command input and955replace mode.956The options 'iminsert', 'imsearch' and 'imcmdline' can be used to choose957the different input methods or disable them temporarily.958 959On Windows 9x and Windows NT 4.0 there was *global-ime* , but this is no960longer supported. You can still find documentation for Active Input Method961Manager (Global IME) here:962 http://msdn.microsoft.com/en-us/library/aa741221(v=VS.85).aspx963 964NOTE: For IME to work you must make sure the input locales of your language965are added to your system. The exact location of this depends on the version966of Windows you use. For example, on my Windows 2000 box:9671. Control Panel9682. Regional Options9693. Input Locales Tab9704. Add Installed input locales -> Chinese(PRC)971 The default is still English (United Stated)972 973 974MS-Windows IME Compatibility *multibyte-ime-compatibility*975 976Vim manages input methods on Windows systems via the `imm32.dll` (Input Method977Manager). The implementation, dating back to the Windows 2000 era, may not be978fully compatible with modern input methods. Modern input method processing979has shifted to the Text Services Framework (TSF), whose behavior may not fully980align with the traditional IME interface. For details about IME and TSF,981refer to the Microsoft documentation website (link is omitted since MS982documentation URLs often change).983 984In some cases Vim might incorrectly enable the Input Method (IM) in Normal985mode upon startup when the Windows display language is set to a CJK language.986To work around this issue, try adding the following configuration to your987|gvimrc| file: >988 989 autocmd VimEnter * set imdisable | set noimdisable990<991If you make any progress in diagnosing or resolving these issues, feedback is992welcome.993 994Note: IME behavior can vary due to differences in implementations by different995vendors. If you encounter issues with a specific input method, it is996recommended to test with an alternative one.997 998For proper integration with Vim's |+multi_byte_ime| system, changes in the999input method's status must be detectable by the `ImmGetOpenStatus()` function1000in Vim's source code. Currently, some input methods that support1001multi-language input may have internal state changes that gVim cannot capture.1002 1003 1004Cursor color when IME or XIM is on *CursorIM*1005 There is a little cute feature for IME. Cursor can indicate status of IME1006 by changing its color. Usually status of IME was indicated by little icon1007 at a corner of desktop (or taskbar). It is not easy to verify status of1008 IME. But this feature help this.1009 This works in the same way when using XIM.1010 1011 You can select cursor color when status is on by using highlight group1012 CursorIM. For example, add these lines to your |gvimrc|: >1013 1014 if has('multi_byte_ime')1015 highlight Cursor guifg=NONE guibg=Green1016 highlight CursorIM guifg=NONE guibg=Purple1017 endif1018<1019 Cursor color with off IME is green. And purple cursor indicates that1020 status is on.1021 1022==============================================================================10239. Input with a keymap *mbyte-keymap*1024 1025When the keyboard doesn't produce the characters you want to enter in your1026text, you can use the 'keymap' option. This will translate one or more1027(English) characters to another (non-English) character. This only happens1028when typing text, not when typing Vim commands. This avoids having to switch1029between two keyboard settings.1030{only available when compiled with the |+keymap| feature}1031 1032The value of the 'keymap' option specifies a keymap file to use. The name of1033this file is one of these two:1034 1035 keymap/{keymap}_{encoding}.vim1036 keymap/{keymap}.vim1037 1038Here {keymap} is the value of the 'keymap' option and {encoding} of the1039'encoding' option. The file name with the {encoding} included is tried first.1040 1041'runtimepath' is used to find these files. To see an overview of all1042available keymap files, use this: >1043 :echo globpath(&rtp, "keymap/*.vim")1044 1045In Insert and Command-line mode you can use CTRL-^ to toggle between using the1046keyboard map or not. |i_CTRL-^| |c_CTRL-^|1047This flag is remembered for Insert mode with the 'iminsert' option. When1048leaving and entering Insert mode the previous value is used. The same value1049is also used for commands that take a single character argument, like |f| and1050|r|.1051For Command-line mode the flag is NOT remembered. You are expected to type an1052Ex command first, which is ASCII.1053For typing search patterns the 'imsearch' option is used. It can be set to1054use the same value as for 'iminsert'.1055 *lCursor*1056It is possible to give the GUI cursor another color when the language mappings1057are being used. This is disabled by default, to avoid that the cursor becomes1058invisible when you use a non-standard background color. Here is an example to1059use a brightly colored cursor: >1060 :highlight Cursor guifg=NONE guibg=Green1061 :highlight lCursor guifg=NONE guibg=Cyan1062<1063 *keymap-file-format* *:loadk* *:loadkeymap* *E105* *E791*1064The keymap file looks something like this: >1065 1066 " Maintainer: name <email@address>1067 " Last Changed: 2001 Jan 11068 1069 let b:keymap_name = "short"1070 1071 loadkeymap1072 a A1073 b B comment1074 1075The lines starting with a " are comments and will be ignored. Blank lines are1076also ignored. The lines with the mappings may have a comment after the useful1077text.1078 1079The "b:keymap_name" can be set to a short name, which will be shown in the1080status line. The idea is that this takes less room than the value of1081'keymap', which might be long to distinguish between different languages,1082keyboards and encodings.1083 1084The actual mappings are in the lines below "loadkeymap". In the example "a"1085is mapped to "A" and "b" to "B". Thus the first item is mapped to the second1086item. This is done for each line, until the end of the file.1087These items are exactly the same as what can be used in a |:lnoremap| command,1088using "<buffer>" to make the mappings local to the buffer.1089You can check the result with this command: >1090 :lmap1091The two items must be separated by white space. You cannot include white1092space inside an item, use the special names "<Tab>" and "<Space>" instead.1093The length of the two items together must not exceed 200 bytes.1094 1095It's possible to have more than one character in the first column. This works1096like a dead key. Example: >1097 'a á1098Since Vim doesn't know if the next character after a quote is really an "a",1099it will wait for the next character. To be able to insert a single quote,1100also add this line: >1101 '' '1102Since the mapping is defined with |:lnoremap| the resulting quote will not be1103used for the start of another character.1104The "accents" keymap uses this. *keymap-accents*1105 1106The first column can also be in |<>| form:1107 <C-c> Ctrl-C1108 <A-c> Alt-c1109 <A-C> Alt-C1110Note that the Alt mappings may not work, depending on your keyboard and1111terminal.1112 1113Although it's possible to have more than one character in the second column,1114this is unusual. But you can use various ways to specify the character: >1115 A a literal character1116 A <char-97> decimal value1117 A <char-0x61> hexadecimal value1118 A <char-0141> octal value1119 x <Space> special key name1120 1121The characters are assumed to be encoded for the current value of 'encoding'.1122It's possible to use ":scriptencoding" when all characters are given1123literally. That doesn't work when using the <char-> construct, because the1124conversion is done on the keymap file, not on the resulting character.1125 1126The lines after "loadkeymap" are interpreted with 'cpoptions' set to "C".1127This means that continuation lines are not used and a backslash has a special1128meaning in the mappings. Examples: >1129 1130 " a comment line1131 \" x maps " to x1132 \\ y maps \ to y1133 1134If you write a keymap file that will be useful for others, consider submitting1135it to the Vim maintainer for inclusion in the distribution:1136<maintainer@vim.org>1137 1138 1139HEBREW KEYMAP *keymap-hebrew*1140 1141This file explains what characters are available in UTF-8 and CP12551142encodings, and what the keymaps are to get those characters:1143 1144glyph encoding keymap ~1145Char UTF-8 cp1255 hebrew hebrewp name ~1146א 0x5d0 0xe0 t a 'alef1147ב 0x5d1 0xe1 c b bet1148ג 0x5d2 0xe2 d g gimel1149ד 0x5d3 0xe3 s d dalet1150ה 0x5d4 0xe4 v h he1151ו 0x5d5 0xe5 u v vav1152ז 0x5d6 0xe6 z z zayin1153ח 0x5d7 0xe7 j j het1154ט 0x5d8 0xe8 y T tet1155י 0x5d9 0xe9 h y yod1156ך 0x5da 0xea l K kaf sofit1157כ 0x5db 0xeb f k kaf1158ל 0x5dc 0xec k l lamed1159ם 0x5dd 0xed o M mem sofit1160מ 0x5de 0xee n m mem1161ן 0x5df 0xef i N nun sofit1162נ 0x5e0 0xf0 b n nun1163ס 0x5e1 0xf1 x s samech1164ע 0x5e2 0xf2 g u `ayin1165ף 0x5e3 0xf3 ; P pe sofit1166פ 0x5e4 0xf4 p p pe1167ץ 0x5e5 0xf5 . X tsadi sofit1168צ 0x5e6 0xf6 m x tsadi1169ק 0x5e7 0xf7 e q qof1170ר 0x5e8 0xf8 r r resh1171ש 0x5e9 0xf9 a w shin1172ת 0x5ea 0xfa , t tav1173 1174Vowel marks and special punctuation:1175הְ 0x5b0 0xc0 A: A: sheva1176הֱ 0x5b1 0xc1 HE HE hataf segol1177הֲ 0x5b2 0xc2 HA HA hataf patah1178הֳ 0x5b3 0xc3 HO HO hataf qamats1179הִ 0x5b4 0xc4 I I hiriq1180הֵ 0x5b5 0xc5 AY AY tsere1181הֶ 0x5b6 0xc6 E E segol1182הַ 0x5b7 0xc7 AA AA patah1183הָ 0x5b8 0xc8 AO AO qamats1184הֹ 0x5b9 0xc9 O O holam1185הֻ 0x5bb 0xcb U U qubuts1186כּ 0x5bc 0xcc D D dagesh1187הֽ 0x5bd 0xcd ]T ]T meteg1188ה־ 0x5be 0xce ]Q ]Q maqaf1189בֿ 0x5bf 0xcf ]R ]R rafe1190ב׀ 0x5c0 0xd0 ]p ]p paseq1191שׁ 0x5c1 0xd1 SR SR shin-dot1192שׂ 0x5c2 0xd2 SL SL sin-dot1193׃ 0x5c3 0xd3 ]P ]P sof-pasuq1194װ 0x5f0 0xd4 VV VV double-vav1195ױ 0x5f1 0xd5 VY VY vav-yod1196ײ 0x5f2 0xd6 YY YY yod-yod1197 1198The following are only available in UTF-81199 1200Cantillation marks: