vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

mbyte.txt (60193B)


      1 *mbyte.txt*	For Vim version 9.2.  Last change: 2026 Feb 14
      2 
      3 
      4 		  VIM REFERENCE MANUAL	  by Bram Moolenaar et al.
      5 
      6 
      7 Multi-byte support				*multibyte* *multi-byte*
      8 						*Chinese* *Japanese* *Korean*
      9 This is about editing text in languages which have many characters that can
     10 not be represented using one byte (one octet).  Examples are Chinese, Japanese
     11 and Korean.  Unicode is also covered here.
     12 
     13 For an introduction to the most common features, see |usr_45.txt| in the user
     14 manual.
     15 For changing the language of messages and menus see |mlang.txt|.
     16 
     17 1.  Getting started			|mbyte-first|
     18 2.  Locale				|mbyte-locale|
     19 3.  Encoding				|mbyte-encoding|
     20 4.  Using a terminal			|mbyte-terminal|
     21 5.  Fonts on X11			|mbyte-fonts-X11|
     22 6.  Fonts on MS-Windows			|mbyte-fonts-MSwin|
     23 7.  Input on X11			|mbyte-XIM|
     24 8.  Input on MS-Windows			|mbyte-IME|
     25 9.  Input with a keymap			|mbyte-keymap|
     26 10. Input with imactivatefunc()		|mbyte-func|
     27 11. Using UTF-8				|mbyte-utf8|
     28 12. Overview of options			|mbyte-options|
     29 
     30 NOTE: This file contains UTF-8 characters.  These may show up as strange
     31 characters or boxes when using another encoding.
     32 
     33 ==============================================================================
     34 1. Getting started					*mbyte-first*
     35 
     36 This is a summary of the multibyte features in Vim.  If you are lucky it works
     37 as described and you can start using Vim without much trouble.  If something
     38 doesn't work you will have to read the rest.  Don't be surprised if it takes
     39 quite a bit of work and experimenting to make Vim use all the multibyte
     40 features.  Unfortunately, every system has its own way to deal with multibyte
     41 languages and it is quite complicated.
     42 
     43 
     44 LOCALE
     45 
     46 First of all, you must make sure your current locale is set correctly.  If
     47 your system has been installed to use the language, it probably works right
     48 away.  If not, you can often make it work by setting the $LANG environment
     49 variable in your shell: >
     50 
     51 	setenv LANG ja_JP.EUC
     52 
     53 Unfortunately, the name of the locale depends on your system.  Japanese might
     54 also be called "ja_JP.EUCjp" or just "ja".  To see what is currently used: >
     55 
     56 	:language
     57 
     58 To change the locale inside Vim use: >
     59 
     60 	:language ja_JP.EUC
     61 
     62 Vim will give an error message if this doesn't work.  This is a good way to
     63 experiment and find the locale name you want to use.  But it's always better
     64 to set the locale in the shell, so that it is used right from the start.
     65 
     66 See |mbyte-locale| for details.
     67 
     68 
     69 ENCODING
     70 
     71 If your locale works properly, Vim will try to set the 'encoding' option
     72 accordingly.  If this doesn't work you can overrule its value: >
     73 
     74 	:set encoding=utf-8
     75 
     76 See |encoding-values| for a list of acceptable values.
     77 
     78 The result is that all the text that is used inside Vim will be in this
     79 encoding.  Not only the text in the buffers, but also in registers, variables,
     80 etc.  This also means that changing the value of 'encoding' makes the existing
     81 text invalid!  The text doesn't change, but it will be displayed wrong.
     82 
     83 You can edit files in another encoding than what 'encoding' is set to.  Vim
     84 will convert the file when you read it and convert it back when you write it.
     85 See 'fileencoding', 'fileencodings' and |++enc|.
     86 
     87 
     88 DISPLAY AND FONTS
     89 
     90 If you are working in a terminal (emulator) you must make sure it accepts the
     91 same encoding as which Vim is working with.  If this is not the case, you can
     92 use the 'termencoding' option to make Vim convert text automatically.
     93 
     94 For the GUI you must select fonts that work with the current 'encoding'.  This
     95 is the difficult part.  It depends on the system you are using, the locale and
     96 a few other things.  See the chapters on fonts: |mbyte-fonts-X11| for
     97 X-Windows and |mbyte-fonts-MSwin| for MS-Windows.
     98 
     99 For GTK+ 2, you can skip most of this section.  The option 'guifontset' does
    100 no longer exist.  You only need to set 'guifont' and everything should "just
    101 work".  If your system comes with Xft2 and fontconfig and the current font
    102 does not contain a certain glyph, a different font will be used automatically
    103 if available.  The 'guifontwide' option is still supported but usually you do
    104 not need to set it.  It is only necessary if the automatic font selection does
    105 not suit your needs.
    106 
    107 For X11 you can set the 'guifontset' option to a list of fonts that together
    108 cover the characters that are used.  Example for Korean: >
    109 
    110 	:set guifontset=k12,r12
    111 
    112 Alternatively, you can set 'guifont' and 'guifontwide'.  'guifont' is used for
    113 the single-width characters, 'guifontwide' for the double-width characters.
    114 Thus the 'guifontwide' font must be exactly twice as wide as 'guifont'.
    115 Example for UTF-8: >
    116 
    117 	:set guifont=-misc-fixed-medium-r-normal-*-18-120-100-100-c-90-iso10646-1
    118 	:set guifontwide=-misc-fixed-medium-r-normal-*-18-120-100-100-c-180-iso10646-1
    119 
    120 You can also set 'guifont' alone, Vim will try to find a matching
    121 'guifontwide' for you.
    122 
    123 
    124 INPUT
    125 
    126 There 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 
    131 The options 'iminsert', 'imsearch' and 'imcmdline' can be used to choose
    132 the different input methods or disable them temporarily.
    133 
    134 ==============================================================================
    135 2.  Locale						*mbyte-locale*
    136 
    137 The easiest setup is when your whole system uses the locale you want to work
    138 in.  But it's also possible to set the locale for one shell you are working
    139 in, or just use a certain locale inside Vim.
    140 
    141 
    142 WHAT IS A LOCALE?					*locale*
    143 
    144 There are many languages in the world.  And there are different cultures and
    145 environments at least as many as the number of languages.  A linguistic
    146 environment corresponding to an area is called "locale".  This includes
    147 information about the used language, the charset, collating order for sorting,
    148 date format, currency format and so on.  For Vim only the language and charset
    149 really matter.
    150 
    151 You can only use a locale if your system has support for it.  Some systems
    152 have only a few locales, especially in the USA.  The language which you want
    153 to use may not be on your system.  In that case you might be able to install
    154 it as an extra package.  Check your system documentation for how to do that.
    155 
    156 The location in which the locales are installed varies from system to system.
    157 For example, "/usr/share/locale" or "/usr/lib/locale".  See your system's
    158 setlocale() man page.
    159 
    160 Looking in these directories will show you the exact name of each locale.
    161 Mostly upper/lowercase matters, thus "ja_JP.EUC" and "ja_jp.euc" are
    162 different.  Some systems have a locale.alias file, which allows translation
    163 from a short name like "nl" to the full name "nl_NL.ISO_8859-1".
    164 
    165 Note that X-windows has its own locale stuff.  And unfortunately uses locale
    166 names different from what is used elsewhere.  This is confusing!  For Vim it
    167 matters what the setlocale() function uses, which is generally NOT the
    168 X-windows stuff.  You might have to do some experiments to find out what
    169 really works.
    170 
    171 							*locale-name*
    172 The (simplified) format of |locale| name is:
    173 
    174 	language
    175 or	language_territory
    176 or	language_territory.codeset
    177 
    178 Territory means the country (or part of it), codeset means the |charset|.  For
    179 example, the locale name "ja_JP.eucJP" means:
    180 	ja	the language is Japanese
    181 	JP	the country is Japan
    182 	eucJP	the codeset is EUC-JP
    183 But it also could be "ja", "ja_JP.EUC", "ja_JP.ujis", etc.  And unfortunately,
    184 the locale name for a specific language, territory and codeset is not unified
    185 and depends on your system.
    186 
    187 Examples of locale name:
    188     charset	    language		  locale name ~
    189     GB2312	    Chinese (simplified)  zh_CN.EUC, zh_CN.GB2312
    190     Big5	    Chinese (traditional) zh_TW.BIG5, zh_TW.Big5
    191     CNS-11643	    Chinese (traditional) zh_TW
    192     EUC-JP	    Japanese		  ja, ja_JP.EUC, ja_JP.ujis, ja_JP.eucJP
    193     Shift_JIS	    Japanese		  ja_JP.SJIS, ja_JP.Shift_JIS
    194     EUC-KR	    Korean		  ko, ko_KR.EUC
    195 
    196 
    197 USING A LOCALE
    198 
    199 To start using a locale for the whole system, see the documentation of your
    200 system.  Mostly you need to set it in a configuration file in "/etc".
    201 
    202 To use a locale in a shell, set the $LANG environment value.  When you want to
    203 use Korean and the |locale| name is "ko", do this:
    204 
    205     sh:    export LANG=ko
    206     csh:   setenv LANG ko
    207 
    208 You can put this in your ~/.profile or ~/.cshrc file to always use it.
    209 
    210 To use a locale in Vim only, use the |:language| command: >
    211 
    212 	:language ko
    213 
    214 Put this in your ~/.vimrc file to use it always.
    215 
    216 Or specify $LANG when starting Vim:
    217 
    218    sh:    LANG=ko vim {vim-arguments}
    219    csh:	  env LANG=ko vim {vim-arguments}
    220 
    221 You could make a small shell script for this.
    222 
    223 ==============================================================================
    224 3.  Encoding				*mbyte-encoding*
    225 
    226 Vim uses the 'encoding' option to specify how characters are identified and
    227 encoded when they are used inside Vim.  This applies to all the places where
    228 text is used, including buffers (files loaded into memory), registers and
    229 variables.
    230 
    231 							*charset* *codeset*
    232 Charset is another name for encoding.  There are subtle differences, but these
    233 don't matter when using Vim.  "codeset" is another similar name.
    234 
    235 Each character is encoded as one or more bytes.  When all characters are
    236 encoded with one byte, we call this a single-byte encoding.  The most often
    237 used one is called "latin1".  This limits the number of characters to 256.
    238 Some of these are control characters, thus even fewer can be used for text.
    239 
    240 When some characters use two or more bytes, we call this a multibyte
    241 encoding.  This allows using much more than 256 characters, which is required
    242 for most East Asian languages.
    243 
    244 Most multibyte encodings use one byte for the first 127 characters.  These
    245 are equal to ASCII, which makes it easy to exchange plain-ASCII text, no
    246 matter what language is used.  Thus you might see the right text even when the
    247 encoding was set wrong.
    248 
    249 							*encoding-names*
    250 Vim can use many different character encodings.  There are three major groups:
    251 
    252 1   8bit	Single-byte encodings, 256 different characters.  Mostly used
    253 		in USA and Europe.  Example: ISO-8859-1 (Latin1).  All
    254 		characters occupy one screen cell only.
    255 
    256 2   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 bytes
    259 		(except for euc-jp when the first byte is 0x8e).
    260 
    261 u   Unicode	Universal encoding, can replace all others.  ISO 10646.
    262 		Millions of different characters.  Example: UTF-8.  The
    263 		relation between bytes and screen cells is complex.
    264 
    265 Other encodings cannot be used by Vim internally.  But files in other
    266 encodings can be edited by using conversion, see 'fileencoding'.
    267 Note that all encodings must use ASCII for the characters up to 128 (except
    268 when compiled for EBCDIC).
    269 
    270 Supported 'encoding' values are:			*encoding-values*
    271 1   latin1	8-bit characters (ISO 8859-1, also used for cp1252)
    272 1   iso-8859-n	ISO_8859 variant (n = 2 to 15)
    273 1   koi8-r	Russian
    274 1   koi8-u	Ukrainian
    275 1   macroman    MacRoman (Macintosh encoding)
    276 1   8bit-{name} any 8-bit encoding (Vim specific name)
    277 1   cp437	similar to iso-8859-1
    278 1   cp737	similar to iso-8859-7
    279 1   cp775	Baltic
    280 1   cp850	similar to iso-8859-4
    281 1   cp852	similar to iso-8859-1
    282 1   cp855	similar to iso-8859-2
    283 1   cp857	similar to iso-8859-5
    284 1   cp860	similar to iso-8859-9
    285 1   cp861	similar to iso-8859-1
    286 1   cp862	similar to iso-8859-1
    287 1   cp863	similar to iso-8859-8
    288 1   cp865	similar to iso-8859-1
    289 1   cp866	similar to iso-8859-5
    290 1   cp869	similar to iso-8859-7
    291 1   cp874	Thai
    292 1   cp1250	Czech, Polish, etc.
    293 1   cp1251	Cyrillic
    294 1   cp1253	Greek
    295 1   cp1254	Turkish
    296 1   cp1255	Hebrew
    297 1   cp1256	Arabic
    298 1   cp1257	Baltic
    299 1   cp1258	Vietnamese
    300 1   cp{number}	MS-Windows: any installed single-byte codepage
    301 2   cp932	Japanese (Windows only)
    302 2   euc-jp	Japanese (Unix only)
    303 2   sjis	Japanese (Unix only)
    304 2   cp949	Korean (Unix and Windows)
    305 2   euc-kr	Korean (Unix only)
    306 2   cp936	simplified Chinese (Windows only)
    307 2   euc-cn	simplified Chinese (Unix only)
    308 2   cp950	traditional Chinese (on Unix alias for big5)
    309 2   big5	traditional Chinese (on Windows alias for cp950)
    310 2   euc-tw	traditional Chinese (Unix only)
    311 2   2byte-{name} Unix: any double-byte encoding (Vim specific name)
    312 2   cp{number}	MS-Windows: any installed double-byte codepage
    313 u   utf-8	32 bit UTF-8 encoded Unicode (ISO/IEC 10646-1)
    314 u   ucs-2	16 bit UCS-2 encoded Unicode (ISO/IEC 10646-1)
    315 u   ucs-2le	like ucs-2, little endian
    316 u   utf-16	ucs-2 extended with double-words for more characters
    317 u   utf-16le	like utf-16, little endian
    318 u   ucs-4	32 bit UCS-4 encoded Unicode (ISO/IEC 10646-1)
    319 u   ucs-4le	like ucs-4, little endian
    320 
    321 The {name} can be any encoding name that your system supports.  It is passed
    322 to iconv() to convert between the encoding of the file and the current locale.
    323 For MS-Windows "cp{number}" means using codepage {number}.
    324 Examples: >
    325 		:set encoding=8bit-cp1252
    326 		:set encoding=2byte-cp932
    327 
    328 The MS-Windows codepage 1252 is very similar to latin1.  For practical reasons
    329 the same encoding is used and it's called latin1.  'isprint' can be used to
    330 display the characters 0x80 - 0xA0 or not.
    331 
    332 Several aliases can be used, they are translated to one of the names above.
    333 An incomplete list:
    334 
    335 1   ansi	same as latin1 (obsolete, for backward compatibility)
    336 2   japan	Japanese: on Unix "euc-jp", on MS-Windows cp932
    337 2   korea	Korean: on Unix "euc-kr", on MS-Windows cp949
    338 2   prc		simplified Chinese: on Unix "euc-cn", on MS-Windows cp936
    339 2   chinese     same as "prc"
    340 2   taiwan	traditional Chinese: on Unix "euc-tw", on MS-Windows cp950
    341 u   utf8	same as utf-8
    342 u   unicode	same as ucs-2
    343 u   ucs2be	same as ucs-2 (big endian)
    344 u   ucs-2be	same as ucs-2 (big endian)
    345 u   ucs-4be	same as ucs-4 (big endian)
    346 u   utf-32	same as ucs-4
    347 u   utf-32le	same as ucs-4le
    348     default     stands for the default value of 'encoding', depends on the
    349 		environment
    350 
    351 For the UCS codes the byte order matters.  This is tricky, use UTF-8 whenever
    352 you can.  The default is to use big-endian (most significant byte comes
    353 first):
    354 	    name	bytes		char ~
    355 	    ucs-2	      11 22	    1122
    356 	    ucs-2le	      22 11	    1122
    357 	    ucs-4	11 22 33 44	11223344
    358 	    ucs-4le	44 33 22 11	11223344
    359 
    360 On MS-Windows systems you often want to use "ucs-2le", because it uses little
    361 endian UCS-2.
    362 
    363 There are a few encodings which are similar, but not exactly the same.  Vim
    364 treats them as if they were different encodings, so that conversion will be
    365 done when needed.  You might want to use the similar name to avoid conversion
    366 or when conversion is not possible:
    367 
    368 	cp932, shift-jis, sjis
    369 	cp936, euc-cn
    370 
    371 							*encoding-table*
    372 Normally 'encoding' is equal to your current locale and 'termencoding' is
    373 empty.  This means that your keyboard and display work with characters encoded
    374 in your current locale, and Vim uses the same characters internally.
    375 
    376 You can make Vim use characters in a different encoding by setting the
    377 'encoding' option to a different value.  Since the keyboard and display still
    378 use the current locale, conversion needs to be done.  The 'termencoding' then
    379 takes over the value of the current locale, so Vim converts between 'encoding'
    380 and 'termencoding'.  Example: >
    381 	:let &termencoding = &encoding
    382 	:set encoding=utf-8
    383 
    384 However, not all combinations of values are possible.  The table below tells
    385 you how each of the nine combinations works.  This is further restricted by
    386 not all conversions being possible, iconv() being present, etc.  Since this
    387 depends 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 from
    394 			'encoding' typing and displaying may be wrong for some
    395 			characters, Vim does NOT perform conversion (set
    396 			'encoding' to "utf-8" to get this).
    397  8bit      2byte	MS-Windows: works for all codepages installed on your
    398 			system; you can only type 8bit characters;
    399 			Other systems: does NOT work.
    400  8bit	   Unicode	Works, but only 8bit characters can be typed directly
    401 			(others through digraphs, keymaps, etc.); in a
    402 			terminal you can only see 8bit characters; the GUI can
    403 			show all characters that the 'guifont' supports.
    404 
    405  2byte	    8bit	Works, but typing non-ASCII characters might
    406 			be a problem.
    407  2byte	   2byte	MS-Windows: works for all codepages installed on your
    408 			system; typing characters might be a problem when
    409 			locale is different from 'encoding'.
    410 			Other systems: Only works when 'termencoding' is equal
    411 			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 work
    416  Unicode   Unicode	works very well (leaving 'termencoding' empty works
    417 			the same way, because all Unicode is handled
    418 			internally as UTF-8)
    419 
    420 CONVERSION						*charset-conversion*
    421 
    422 Vim 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 from
    428   'encoding' (requires a gettext version that supports this).
    429 - When reading a Vim script where |:scriptencoding| is different from
    430   'encoding'.
    431 - When reading or writing a |viminfo| file.
    432 Most of these require the |+iconv| feature.  Conversion for reading and
    433 writing files may also be specified with the 'charconvert' option.
    434 
    435 Useful utilities for converting the charset:
    436     All:	    iconv
    437 	GNU iconv can convert most encodings.  Unicode is used as the
    438 	intermediate encoding, which allows conversion from and to all other
    439 	encodings.  See http://www.gnu.org/directory/libiconv.html.
    440 
    441     Japanese:	    nkf
    442 	Nkf is "Network Kanji code conversion Filter".  One of the most unique
    443 	facility of nkf is the guess of the input Kanji code.  So, you don't
    444 	need to know what the inputting file's |charset| is.  When convert to
    445 	EUC-JP from ISO-2022-JP or Shift_JIS, simply do the following command
    446 	in Vim:
    447 	    :%!nkf -e
    448 	Nkf can be found at:
    449 	http://www.sfc.wide.ad.jp/~max/FreeBSD/ports/distfiles/nkf-1.62.tar.gz
    450 
    451     Chinese:	    hc
    452 	Hc is "Hanzi Converter".  Hc convert a GB file to a Big5 file, or Big5
    453 	file to GB file.  Hc can be found at:
    454 	https://www.freshports.org/chinese/hc
    455 	ftp://ftp.cuhk.hk/pub/chinese/ifcss/software/unix/convert/hc-30.tar.gz
    456 
    457     Korean:	    hmconv
    458 	Hmconv is Korean code conversion utility especially for E-mail.  It
    459 	can convert between EUC-KR and ISO-2022-KR.  Hmconv can be found at:
    460 	https://www.freshports.org/korean/hmconv/
    461 
    462     Multilingual:   lv
    463 	Lv is a Powerful Multilingual File Viewer.  And it can be worked as
    464 	|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-8859
    466 	series, Shift_JIS, Big5 and HZ.  Lv can be found at (link seems dead):
    467 	ff.iij4u.or.jp/~nrt/lv/index.html
    468 
    469 
    470 							*mbyte-conversion*
    471 When reading and writing files in an encoding different from 'encoding',
    472 conversion needs to be done.  These conversions are supported:
    473 - All conversions between Latin-1 (ISO-8859-1), UTF-8, UCS-2 and UCS-4 are
    474   handled internally.
    475 - For MS-Windows, when 'encoding' is a Unicode encoding, conversion from and
    476   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 (they
    480 	request a very large buffer, more than Vim is willing to provide).
    481 	Try getting another iconv() implementation.
    482 
    483 							*iconv-dynamic*
    484 On MS-Windows Vim can be compiled with the |+iconv/dyn| feature.  This means
    485 Vim will search for the "iconv.dll" and "libiconv.dll" libraries.  When
    486 neither of them can be found Vim will still work but some conversions won't be
    487 possible.
    488 
    489 ==============================================================================
    490 4. Using a terminal					*mbyte-terminal*
    491 
    492 The GUI fully supports multibyte characters.  It is also possible in a
    493 terminal, if the terminal supports the same encoding that Vim uses.  Thus this
    494 is less flexible.
    495 
    496 For example, you can run Vim in an xterm with added multibyte support and/or
    497 |XIM|.  Examples are kterm (Kanji term) and hanterm (for Korean), Eterm
    498 (Enlightened terminal) and rxvt.
    499 
    500 If your terminal does not support the right encoding, you can set the
    501 'termencoding' option.  Vim will then convert the typed characters from
    502 'termencoding' to 'encoding'.  And displayed text will be converted from
    503 'encoding' to 'termencoding'.  If the encoding supported by the terminal
    504 doesn't include all the characters that Vim uses, this leads to lost
    505 characters.  This may mess up the display.  If you use a terminal that
    506 supports Unicode, such as the xterm mentioned below, it should work just fine,
    507 since nearly every character set can be converted to Unicode without loss of
    508 information.
    509 
    510 
    511 UTF-8 IN XFREE86 XTERM					*UTF8-xterm*
    512 
    513 This is a short explanation of how to use UTF-8 character encoding in the
    514 xterm that comes with XFree86 by Thomas Dickey (text by Markus Kuhn).
    515 
    516 Get the latest xterm version which has now UTF-8 support:
    517 
    518 	http://invisible-island.net/xterm/xterm.html
    519 
    520 Compile it with "./configure --enable-wide-chars ; make"
    521 
    522 Also get the ISO 10646-1 version of various fonts, which is available on
    523 
    524 	http://www.cl.cam.ac.uk/~mgk25/download/ucs-fonts.tar.gz
    525 
    526 and install the font as described in the README file.
    527 
    528 Now start xterm with >
    529 
    530   xterm -u8 -fn -misc-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso10646-1
    531 or, for bigger character: >
    532   xterm -u8 -fn -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso10646-1
    533 
    534 and you will have a working UTF-8 terminal emulator.  Try both >
    535 
    536    cat utf-8-demo.txt
    537    vim utf-8-demo.txt
    538 
    539 with the demo text that comes with ucs-fonts.tar.gz in order to see
    540 whether there are any problems with UTF-8 in your xterm.
    541 
    542 For Vim you may need to set 'encoding' to "utf-8".
    543 
    544 ==============================================================================
    545 5.  Fonts on X11					*mbyte-fonts-X11*
    546 
    547 Unfortunately, using fonts in X11 is complicated.  The name of a single-byte
    548 font is a long string.  For multibyte fonts we need several of these...
    549 
    550 Note: Most of this is no longer relevant for GTK+ 2.  Selecting a font via
    551 its XLFD is not supported; see 'guifont' for an example of how to
    552 set the font.  Do yourself a favor and ignore the |XLFD| and |xfontset|
    553 sections below.
    554 
    555 First of all, Vim only accepts fixed-width fonts for displaying text.  You
    556 cannot use proportionally spaced fonts.  This excludes many of the available
    557 (and nicer looking) fonts.  However, for menus and tooltips any font can be
    558 used.
    559 
    560 Note that Display and Input are independent.  It is possible to see your
    561 language even though you have no input method for it.
    562 
    563 You should get a default font for menus and tooltips that works, but it might
    564 be ugly.  Read the following to find out how to select a better font.
    565 
    566 
    567 X LOGICAL FONT DESCRIPTION (XLFD)
    568 							*XLFD*
    569 XLFD is the X font name and contains the information about the font size,
    570 charset, etc.  The name is in this format:
    571 
    572 FOUNDRY-FAMILY-WEIGHT-SLANT-WIDTH-STYLE-PIXEL-POINT-X-Y-SPACE-AVE-CR-CE
    573 
    574 Each 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:  Italic
    584 		o:  Oblique
    585 		ri: Reverse Italic
    586 		ro: Reverse Oblique
    587 		ot: Other
    588 		number:	Scaled font
    589 - 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, Sans
    592 	    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:  Proportional
    599 		m:  Monospaced
    600 		c:  CharCell
    601 - 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 some
    604 	    charsets, such as JIS X 0208, if this field is 0, codepoints has
    605 	    the same value as GL, and GR if 1.
    606 
    607 For example, in case of a 16 dots font corresponding to JIS X 0208, it is
    608 written like:
    609     -misc-fixed-medium-r-normal--16-110-100-100-c-160-jisx0208.1990-0
    610 
    611 
    612 X FONTSET
    613 						*fontset* *xfontset*
    614 A single-byte charset is typically associated with one font.  For multibyte
    615 charsets a combination of fonts is often used.  This means that one group of
    616 characters are used from one font and another group from another font (which
    617 might be double wide).  This collection of fonts is called a fontset.
    618 
    619 Which fonts are required in a fontset depends on the current locale.  X
    620 windows maintains a table of which groups of characters are required for a
    621 locale.  You have to specify all the fonts that a locale requires in the
    622 'guifontset' option.
    623 
    624 Setting the 'guifontset' option also means that all font names will be handled
    625 as a fontset name.  Also the ones used for the "font" argument of the
    626 |:highlight| command.
    627 
    628 Note the difference between 'guifont' and 'guifontset': In 'guifont'
    629 the comma-separated names are alternative names, one of which will be
    630 used.  In 'guifontset' the whole string is one fontset name,
    631 including the commas.  It is not possible to specify alternative
    632 fontset names.
    633 This example works on many X11 systems: >
    634 	:set guifontset=-*-*-medium-r-normal--16-*-*-*-c-*-*-*
    635 <
    636 The fonts must match with the current locale.  If fonts for the character sets
    637 that the current locale uses are not included, setting 'guifontset' will fail.
    638 
    639 NOTE: The fontset always uses the current locale, even though 'encoding' may
    640 be set to use a different charset.  In that situation you might want to use
    641 'guifont' and 'guifontwide' instead of 'guifontset'.
    642 
    643 Example:
    644     |charset| language		    "groups of characters" ~
    645     GB2312    Chinese (simplified)  ISO-8859-1 and GB 2312
    646     Big5      Chinese (traditional) ISO-8859-1 and Big5
    647     CNS-11643 Chinese (traditional) ISO-8859-1, CNS 11643-1 and CNS 11643-2
    648     EUC-JP    Japanese		    JIS X 0201 and JIS X 0208
    649     EUC-KR    Korean		    ISO-8859-1 and KS C 5601 (KS X 1001)
    650 
    651 You can search for fonts using the xlsfonts command.  For example, when you're
    652 searching for a font for KS C 5601: >
    653     xlsfonts | grep ksc5601
    654 
    655 This is complicated and confusing.  You might want to consult the X-Windows
    656 documentation if there is something you don't understand.
    657 
    658 						*base_font_name_list*
    659 When you have found the names of the fonts you want to use, you need to set
    660 the 'guifontset' option.  You specify the list by concatenating the font names
    661 and putting a comma in between them.
    662 
    663 For example, when you use the ja_JP.eucJP locale, this requires JIS X 0201
    664 and JIS X 0208.  You could supply a list of fonts that explicitly specifies
    665 the 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-0
    669 
    670 Alternatively, you can supply a base font name list that omits the charset
    671 name, letting X-Windows select font characters required for the locale.  For
    672 example: >
    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-70
    676 
    677 Alternatively, you can supply a single base font name that allows X-Windows to
    678 select from all available fonts.  For example: >
    679 
    680  :set guifontset=-misc-fixed-medium-r-normal--14-*
    681 
    682 Alternatively, you can specify alias names.  See the fonts.alias file in the
    683 fonts directory (e.g., /usr/X11R6/lib/X11/fonts/).  For example: >
    684 
    685  :set guifontset=k14,r14
    686 <
    687 							*E253*
    688 Note that in East Asian fonts, the standard character cell is square.  When
    689 mixing a Latin font and an East Asian font, the East Asian font width should
    690 be twice the Latin font width.
    691 
    692 If 'guifontset' is not empty, the "font" argument of the |:highlight| command
    693 is also interpreted as a fontset.  For example, you should use for
    694 highlighting: >
    695 	:hi Comment font=english_font,your_font
    696 If you use a wrong "font" argument you will get an error message.
    697 Also make sure that you set 'guifontset' before setting fonts for highlight
    698 groups.
    699 
    700 
    701 USING RESOURCE FILES
    702 
    703 Instead of specifying 'guifontset', you can set X11 resources and Vim will
    704 pick them up.  This is only for people who know how X resource files work.
    705 
    706 For 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_font
    711 
    712 Note: Vim.font is for text area.
    713       Vim*fontSet is for menu.
    714       Vim*fontList is for menu (for Motif GUI)
    715 
    716 For 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 <
    722 or: >
    723 
    724 	Vim*font: k14,r14
    725 	Vim*fontSet: k14,r14
    726 	Vim*fontList: k14,r14
    727 <
    728 To have them take effect immediately you will have to do >
    729 
    730 	xrdb -merge ~/.Xdefaults
    731 
    732 Otherwise you will have to stop and restart the X server before the changes
    733 take effect.
    734 
    735 
    736 The GTK+ version of GUI Vim does not use .Xdefaults, use ~/.gtkrc instead.
    737 The default mostly works OK.  But for the menus you might have to change
    738 it.  Example: >
    739 
    740 	style "default"
    741 	{
    742 		fontset="-*-*-medium-r-normal--14-*-*-*-c-*-*-*"
    743 	}
    744 	widget_class "*" style "default"
    745 
    746 ==============================================================================
    747 6.  Fonts on MS-Windows				*mbyte-fonts-MSwin*
    748 
    749 The simplest is to use the font dialog to select fonts and try them out.  You
    750 can find this at the "Edit/Select Font..." menu.  Once you find a font name
    751 that works well you can use this command to see its name: >
    752 
    753 	:set guifont
    754 
    755 Then add a command to your |gvimrc| file to set 'guifont': >
    756 
    757 	:set guifont=courier_new:h12
    758 
    759 ==============================================================================
    760 7.  Input on X11				*mbyte-XIM*
    761 
    762 X INPUT METHOD (XIM) BACKGROUND			*XIM* *xim* *x-input-method*
    763 
    764 XIM is an international input module for X.  There are two kinds of
    765 structures, 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-server
    769 							*IM-server*
    770   In |IM-server| type input structures, the input event is handled by either
    771   of the two ways: FrontEnd system and BackEnd system.  In the FrontEnd
    772   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 BackEnd
    774   system works reverse order.  MS-Windows adopt BackEnd system.  In X, most of
    775   |IM-server|s adopt FrontEnd system.  The demerit of BackEnd system is the
    776   large overhead in communication, but it provides safe synchronization with
    777   no restrictions on applications.
    778 
    779   For example, there are xwnmo and kinput2 Japanese |IM-server|, both are
    780   FrontEnd system.  Xwnmo is distributed with Wnn (see below), kinput2 can be
    781   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 both
    784   Traditional and Simplified Chinese characters.  And it can accept other
    785   locale if you make a correct input table.  Xcin can be found at (link seems
    786   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 Server
    791 							*conversion-server*
    792   Some system needs additional server: conversion server.  Most of Japanese
    793   |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 to
    795   HanZi conversion server is needed.  For Korean inputting, if you want to
    796   input Hanja, Hangul-Hanja conversion server is needed.
    797 
    798   For example, the Japanese inputting process is divided into 2 steps.  First
    799   we pre-input Hira-gana, second Kana-Kanji conversion.  There are so many
    800   Kanji characters (6349 Kanji characters are defined in JIS X 0208) and the
    801   number of Hira-gana characters are 76.  So, first, we pre-input text as
    802   pronounced in Hira-gana, second, we convert Hira-gana to Kanji or Kata-Kana,
    803   if needed.  There are some Kana-Kanji conversion server: jserver
    804   (distributed with Wnn, see below) and canna.  Canna can be found at:
    805   (dead link) osdn.net/projects/canna/
    806 
    807 There 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)
    813 Wnn 4.2 for several systems can be found at various places on the internet.
    814 Use the RPM or port for your system.
    815 
    816 
    817 - Input Style
    818 							*xim-input-style*
    819   When inputting CJK, there are four areas:
    820       1. The area to display of the input while it is being composed
    821       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 Japanese
    826   inputting, multiple Kanji characters could have the same pronunciation, so
    827   a sequence of Hira-gana characters could map to a distinct sequence of Kanji
    828   characters.
    829 
    830   The first and second areas are defined in international input of X with the
    831   names of "Preedit Area", "Status Area" respectively.  The third and fourth
    832   areas are not defined and are left to be managed by the |IM-server|.  In the
    833   international input, four input styles have been defined using combinations
    834   of Preedit Area and Status Area: |OnTheSpot|, |OffTheSpot|, |OverTheSpot|
    835   and |Root|.
    836 
    837   Currently, GUI Vim supports three styles, |OverTheSpot|, |OffTheSpot| and
    838   |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 in
    845     the area of application.  The client application is directed by the
    846     |IM-server| to display all pre-edit data at the location of text
    847     insertion.  The client registers callbacks invoked by the input method
    848     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 Area
    852     is made at present input position of application.  The input method
    853     displays pre-edit data in a window which it brings up directly over the
    854     text insertion position.
    855 *.  off-the-spot					*OffTheSpot*
    856     Preedit Area and Status Area are performed in the area of application, in
    857     case of Vim, the area is additional status line.  The client application
    858     provides display windows for the pre-edit data to the input method which
    859     displays into them directly.
    860 *.  root-window						*Root*
    861     Preedit Area and Status Area are outside of the application.  The input
    862     method displays all pre-edit data in a separate area of the screen in a
    863     window specific to the input method.
    864 
    865 
    866 USING XIM			*multibyte-input* *E284* *E285* *E286* *E287*
    867 					*E288* *E289*
    868 
    869 Note that Display and Input are independent.  It is possible to see your
    870 language even though you have no input method for it.  But when your Display
    871 method 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 
    877 To input your language you should run the |IM-server| which supports your
    878 language and |conversion-server| if needed.
    879 
    880 The next 3 lines should be put in your ~/.Xdefaults file.  They are common for
    881 all X applications which uses |XIM|.  If you already use |XIM|, you can skip
    882 this. >
    883 
    884 	*international: True
    885 	*.inputMethod: your_input_server_name
    886 	*.preeditType: your_input_style
    887 <
    888 input_server_name	is your |IM-server| name (check your |IM-server|
    889 			manual).
    890 your_input_style	is one of |OverTheSpot|, |OffTheSpot|, |Root|.  See
    891 			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 
    896 For example, when you are using kinput2 as |IM-server|, >
    897 
    898 	*international: True
    899 	*.inputMethod: kinput2
    900 	*.preeditType: OverTheSpot
    901 <
    902 When using |OverTheSpot|, GUI Vim always connects to the IM Server even in
    903 Normal mode, so you can input your language with commands like "f" and "r".
    904 But when using one of the other two methods, GUI Vim connects to the IM Server
    905 only if it is not in Normal mode.
    906 
    907 If your IM Server does not support |OverTheSpot|, and if you want to use your
    908 language with some Normal mode command like "f" or "r", then you should use a
    909 localized xterm  or an xterm which supports |XIM|
    910 
    911 If 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 
    916 For example, when you are using kinput2 as |IM-server| and sh, >
    917 
    918 	export XMODIFIERS="@im=kinput2"
    919 <
    920 
    921 FULLY CONTROLLED XIM
    922 
    923 You can fully control XIM, like with IME of MS-Windows (see |multibyte-ime|).
    924 This is currently only available for the GTK GUI.
    925 
    926 Before using fully controlled XIM, one setting is required.  Set the
    927 'imactivatekey' option to the key that is used for the activation of the input
    928 method.  For example, when you are using kinput2 + canna as IM Server, the
    929 activation key is probably Shift+Space: >
    930 
    931 	:set imactivatekey=S-space
    932 
    933 See 'imactivatekey' for the format.
    934 
    935 ==============================================================================
    936 8.  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 
    942 To input multibyte characters on Windows, you can use an Input Method Editor
    943 (IME).  In process of your editing text, you must switch status (on/off) of
    944 IME many many many times.  Because IME with status on is hooking all of your
    945 key inputs, you cannot input 'j', 'k', or almost all of keys to Vim directly.
    946 
    947 The |+multi_byte_ime| feature helps for this.  It reduces the number of times
    948 the IME status has to be switched manually.  In Normal mode, there is almost
    949 no need to use IME, even when editing multibyte text.  So when exiting Insert
    950 mode, Vim memorizes the last status of IME and turns off IME.  When
    951 re-entering Insert mode, Vim sets the IME status to that memorized status
    952 automatically.
    953 
    954 This works on not only insert-normal mode, but also search-command input and
    955 replace mode.
    956 The options 'iminsert', 'imsearch' and 'imcmdline' can be used to choose
    957 the different input methods or disable them temporarily.
    958 
    959 On Windows 9x and Windows NT 4.0 there was *global-ime* , but this is no
    960 longer supported.  You can still find documentation for Active Input Method
    961 Manager (Global IME) here:
    962 	http://msdn.microsoft.com/en-us/library/aa741221(v=VS.85).aspx
    963 
    964 NOTE: For IME to work you must make sure the input locales of your language
    965 are added to your system.  The exact location of this depends on the version
    966 of Windows you use.  For example, on my Windows 2000 box:
    967 1. Control Panel
    968 2. Regional Options
    969 3. Input Locales Tab
    970 4. Add Installed input locales -> Chinese(PRC)
    971    The default is still English (United Stated)
    972 
    973 
    974 MS-Windows IME Compatibility			*multibyte-ime-compatibility*
    975 
    976 Vim manages input methods on Windows systems via the `imm32.dll` (Input Method
    977 Manager).  The implementation, dating back to the Windows 2000 era, may not be
    978 fully compatible with modern input methods.  Modern input method processing
    979 has shifted to the Text Services Framework (TSF), whose behavior may not fully
    980 align with the traditional IME interface.  For details about IME and TSF,
    981 refer to the Microsoft documentation website (link is omitted since MS
    982 documentation URLs often change).
    983 
    984 In some cases Vim might incorrectly enable the Input Method (IM) in Normal
    985 mode upon startup when the Windows display language is set to a CJK language.
    986 To work around this issue, try adding the following configuration to your
    987 |gvimrc| file: >
    988 
    989 	autocmd VimEnter * set imdisable | set noimdisable
    990 <
    991 If you make any progress in diagnosing or resolving these issues, feedback is
    992 welcome.
    993 
    994 Note: IME behavior can vary due to differences in implementations by different
    995 vendors.  If you encounter issues with a specific input method, it is
    996 recommended to test with an alternative one.
    997 
    998 For proper integration with Vim's |+multi_byte_ime| system, changes in the
    999 input method's status must be detectable by the `ImmGetOpenStatus()` function
   1000 in Vim's source code.  Currently, some input methods that support
   1001 multi-language input may have internal state changes that gVim cannot capture.
   1002 
   1003 
   1004 Cursor color when IME or XIM is on				*CursorIM*
   1005     There is a little cute feature for IME.  Cursor can indicate status of IME
   1006     by changing its color.  Usually status of IME was indicated by little icon
   1007     at a corner of desktop (or taskbar).  It is not easy to verify status of
   1008     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 group
   1012     CursorIM.  For example, add these lines to your |gvimrc|: >
   1013 
   1014 	if has('multi_byte_ime')
   1015 	    highlight Cursor guifg=NONE guibg=Green
   1016 	    highlight CursorIM guifg=NONE guibg=Purple
   1017 	endif
   1018 <
   1019     Cursor color with off IME is green.  And purple cursor indicates that
   1020     status is on.
   1021 
   1022 ==============================================================================
   1023 9. Input with a keymap					*mbyte-keymap*
   1024 
   1025 When the keyboard doesn't produce the characters you want to enter in your
   1026 text, you can use the 'keymap' option.  This will translate one or more
   1027 (English) characters to another (non-English) character.  This only happens
   1028 when typing text, not when typing Vim commands.  This avoids having to switch
   1029 between two keyboard settings.
   1030 {only available when compiled with the |+keymap| feature}
   1031 
   1032 The value of the 'keymap' option specifies a keymap file to use.  The name of
   1033 this file is one of these two:
   1034 
   1035 	keymap/{keymap}_{encoding}.vim
   1036 	keymap/{keymap}.vim
   1037 
   1038 Here {keymap} is the value of the 'keymap' option and {encoding} of the
   1039 '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 all
   1042 available keymap files, use this: >
   1043 	:echo globpath(&rtp, "keymap/*.vim")
   1044 
   1045 In Insert and Command-line mode you can use CTRL-^ to toggle between using the
   1046 keyboard map or not. |i_CTRL-^| |c_CTRL-^|
   1047 This flag is remembered for Insert mode with the 'iminsert' option.  When
   1048 leaving and entering Insert mode the previous value is used.  The same value
   1049 is also used for commands that take a single character argument, like |f| and
   1050 |r|.
   1051 For Command-line mode the flag is NOT remembered.  You are expected to type an
   1052 Ex command first, which is ASCII.
   1053 For typing search patterns the 'imsearch' option is used.  It can be set to
   1054 use the same value as for 'iminsert'.
   1055 								*lCursor*
   1056 It is possible to give the GUI cursor another color when the language mappings
   1057 are being used.  This is disabled by default, to avoid that the cursor becomes
   1058 invisible when you use a non-standard background color.  Here is an example to
   1059 use a brightly colored cursor: >
   1060 	:highlight Cursor guifg=NONE guibg=Green
   1061 	:highlight lCursor guifg=NONE guibg=Cyan
   1062 <
   1063 		*keymap-file-format* *:loadk* *:loadkeymap* *E105* *E791*
   1064 The keymap file looks something like this: >
   1065 
   1066 	" Maintainer:	name <email@address>
   1067 	" Last Changed:	2001 Jan 1
   1068 
   1069 	let b:keymap_name = "short"
   1070 
   1071 	loadkeymap
   1072 	a	A
   1073 	b	B	comment
   1074 
   1075 The lines starting with a " are comments and will be ignored.  Blank lines are
   1076 also ignored.  The lines with the mappings may have a comment after the useful
   1077 text.
   1078 
   1079 The "b:keymap_name" can be set to a short name, which will be shown in the
   1080 status line.  The idea is that this takes less room than the value of
   1081 'keymap', which might be long to distinguish between different languages,
   1082 keyboards and encodings.
   1083 
   1084 The actual mappings are in the lines below "loadkeymap".  In the example "a"
   1085 is mapped to "A" and "b" to "B".  Thus the first item is mapped to the second
   1086 item.  This is done for each line, until the end of the file.
   1087 These items are exactly the same as what can be used in a |:lnoremap| command,
   1088 using "<buffer>" to make the mappings local to the buffer.
   1089 You can check the result with this command: >
   1090 	:lmap
   1091 The two items must be separated by white space.  You cannot include white
   1092 space inside an item, use the special names "<Tab>" and "<Space>" instead.
   1093 The length of the two items together must not exceed 200 bytes.
   1094 
   1095 It's possible to have more than one character in the first column.  This works
   1096 like a dead key.  Example: >
   1097 	'a	á
   1098 Since Vim doesn't know if the next character after a quote is really an "a",
   1099 it will wait for the next character.  To be able to insert a single quote,
   1100 also add this line: >
   1101 	''	'
   1102 Since the mapping is defined with |:lnoremap| the resulting quote will not be
   1103 used for the start of another character.
   1104 The "accents" keymap uses this.				*keymap-accents*
   1105 
   1106 The first column can also be in |<>| form:
   1107 	<C-c>		Ctrl-C
   1108 	<A-c>		Alt-c
   1109 	<A-C>		Alt-C
   1110 Note that the Alt mappings may not work, depending on your keyboard and
   1111 terminal.
   1112 
   1113 Although it's possible to have more than one character in the second column,
   1114 this is unusual.  But you can use various ways to specify the character: >
   1115 	A	a		literal character
   1116 	A	<char-97>	decimal value
   1117 	A	<char-0x61>	hexadecimal value
   1118 	A	<char-0141>	octal value
   1119 	x	<Space>		special key name
   1120 
   1121 The characters are assumed to be encoded for the current value of 'encoding'.
   1122 It's possible to use ":scriptencoding" when all characters are given
   1123 literally.  That doesn't work when using the <char-> construct, because the
   1124 conversion is done on the keymap file, not on the resulting character.
   1125 
   1126 The lines after "loadkeymap" are interpreted with 'cpoptions' set to "C".
   1127 This means that continuation lines are not used and a backslash has a special
   1128 meaning in the mappings.  Examples: >
   1129 
   1130 	" a comment line
   1131 	\"	x	maps " to x
   1132 	\\	y	maps \ to y
   1133 
   1134 If you write a keymap file that will be useful for others, consider submitting
   1135 it to the Vim maintainer for inclusion in the distribution:
   1136 <maintainer@vim.org>
   1137 
   1138 
   1139 HEBREW KEYMAP						*keymap-hebrew*
   1140 
   1141 This file explains what characters are available in UTF-8 and CP1255
   1142 encodings, and what the keymaps are to get those characters:
   1143 
   1144 glyph   encoding	   keymap ~
   1145 Char UTF-8 cp1255  hebrew  hebrewp  name ~
   1146 א    0x5d0  0xe0     t	      a     'alef
   1147 ב    0x5d1  0xe1     c	      b     bet
   1148 ג    0x5d2  0xe2     d	      g     gimel
   1149 ד    0x5d3  0xe3     s	      d     dalet
   1150 ה    0x5d4  0xe4     v	      h     he
   1151 ו    0x5d5  0xe5     u	      v     vav
   1152 ז    0x5d6  0xe6     z	      z     zayin
   1153 ח    0x5d7  0xe7     j	      j     het
   1154 ט    0x5d8  0xe8     y	      T     tet
   1155 י    0x5d9  0xe9     h	      y     yod
   1156 ך    0x5da  0xea     l	      K     kaf sofit
   1157 כ    0x5db  0xeb     f	      k     kaf
   1158 ל    0x5dc  0xec     k	      l     lamed
   1159 ם    0x5dd  0xed     o	      M     mem sofit
   1160 מ    0x5de  0xee     n	      m     mem
   1161 ן    0x5df  0xef     i	      N     nun sofit
   1162 נ    0x5e0  0xf0     b	      n     nun
   1163 ס    0x5e1  0xf1     x	      s     samech
   1164 ע    0x5e2  0xf2     g	      u     `ayin
   1165 ף    0x5e3  0xf3     ;	      P     pe sofit
   1166 פ    0x5e4  0xf4     p	      p     pe
   1167 ץ    0x5e5  0xf5     .	      X     tsadi sofit
   1168 צ    0x5e6  0xf6     m	      x     tsadi
   1169 ק    0x5e7  0xf7     e	      q     qof
   1170 ר    0x5e8  0xf8     r	      r     resh
   1171 ש    0x5e9  0xf9     a	      w     shin
   1172 ת    0x5ea  0xfa     ,	      t     tav
   1173 
   1174 Vowel marks and special punctuation:
   1175 הְ    0x5b0  0xc0     A:      A:   sheva
   1176 הֱ    0x5b1  0xc1     HE      HE   hataf segol
   1177 הֲ    0x5b2  0xc2     HA      HA   hataf patah
   1178 הֳ    0x5b3  0xc3     HO      HO   hataf qamats
   1179 הִ    0x5b4  0xc4     I       I    hiriq
   1180 הֵ    0x5b5  0xc5     AY      AY   tsere
   1181 הֶ    0x5b6  0xc6     E       E    segol
   1182 הַ    0x5b7  0xc7     AA      AA   patah
   1183 הָ    0x5b8  0xc8     AO      AO   qamats
   1184 הֹ    0x5b9  0xc9     O       O    holam
   1185 הֻ    0x5bb  0xcb     U       U    qubuts
   1186 כּ    0x5bc  0xcc     D       D    dagesh
   1187 הֽ    0x5bd  0xcd     ]T      ]T   meteg
   1188 ה־   0x5be  0xce     ]Q      ]Q   maqaf
   1189 בֿ    0x5bf  0xcf     ]R      ]R   rafe
   1190 ב׀   0x5c0  0xd0     ]p      ]p   paseq
   1191 שׁ    0x5c1  0xd1     SR      SR   shin-dot
   1192 שׂ    0x5c2  0xd2     SL      SL   sin-dot
   1193 ׃    0x5c3  0xd3     ]P      ]P   sof-pasuq
   1194 װ    0x5f0  0xd4     VV      VV   double-vav
   1195 ױ    0x5f1  0xd5     VY      VY   vav-yod
   1196 ײ    0x5f2  0xd6     YY      YY   yod-yod
   1197 
   1198 The following are only available in UTF-8
   1199 
   1200 Cantillation marks:
   1201 glyph
   1202 Char UTF-8 hebrew name
   1203 ב֑    0x591   C:   etnahta
   1204 ב֒    0x592   Cs   segol
   1205 ב֓    0x593   CS   shalshelet
   1206 ב֔    0x594   Cz   zaqef qatan
   1207 ב֕    0x595   CZ   zaqef gadol
   1208 ב֖    0x596   Ct   tipeha
   1209 ב֗    0x597   Cr   revia
   1210 ב֘    0x598   Cq   zarqa
   1211 ב֙    0x599   Cp   pashta
   1212 ב֚    0x59a   C!   yetiv
   1213 ב֛    0x59b   Cv   tevir
   1214 ב֜    0x59c   Cg   geresh
   1215 ב֝    0x59d   C*   geresh qadim
   1216 ב֞    0x59e   CG   gershayim
   1217 ב֟    0x59f   CP   qarnei-parah
   1218 ב֪    0x5aa   Cy   yerach-ben-yomo
   1219 ב֫    0x5ab   Co   ole
   1220 ב֬    0x5ac   Ci   iluy
   1221 ב֭    0x5ad   Cd   dehi
   1222 ב֮    0x5ae   Cn   zinor
   1223 ב֯    0x5af   CC   masora circle
   1224 
   1225 Combining forms:
   1226 ﬠ    0xfb20  X`   Alternative `ayin
   1227 ﬡ    0xfb21  X'   Alternative 'alef
   1228 ﬢ    0xfb22  X-d  Alternative dalet
   1229 ﬣ    0xfb23  X-h  Alternative he
   1230 ﬤ    0xfb24  X-k  Alternative kaf
   1231 ﬥ    0xfb25  X-l  Alternative lamed
   1232 ﬦ    0xfb26  X-m  Alternative mem-sofit
   1233 ﬧ    0xfb27  X-r  Alternative resh
   1234 ﬨ    0xfb28  X-t  Alternative tav
   1235 ﬩    0xfb29  X-+  Alternative plus
   1236 שׁ    0xfb2a  XW   shin+shin-dot
   1237 שׂ    0xfb2b  Xw   shin+sin-dot
   1238 שּׁ    0xfb2c  X..W  shin+shin-dot+dagesh
   1239 שּׂ    0xfb2d  X..w  shin+sin-dot+dagesh
   1240 אַ    0xfb2e  XA   alef+patah
   1241 אָ    0xfb2f  XO   alef+qamats
   1242 אּ    0xfb30  XI   alef+hiriq (mapiq)
   1243 בּ    0xfb31  X.b  bet+dagesh
   1244 גּ    0xfb32  X.g  gimel+dagesh
   1245 דּ    0xfb33  X.d  dalet+dagesh
   1246 הּ    0xfb34  X.h  he+dagesh
   1247 וּ    0xfb35  Xu  vav+dagesh
   1248 זּ    0xfb36  X.z  zayin+dagesh
   1249 טּ    0xfb38  X.T  tet+dagesh
   1250 יּ    0xfb39  X.y  yud+dagesh
   1251 ךּ    0xfb3a  X.K  kaf sofit+dagesh
   1252 כּ    0xfb3b  X.k  kaf+dagesh
   1253 לּ    0xfb3c  X.l  lamed+dagesh
   1254 מּ    0xfb3e  X.m  mem+dagesh
   1255 נּ    0xfb40  X.n  nun+dagesh
   1256 סּ    0xfb41  X.s  samech+dagesh
   1257 ףּ    0xfb43  X.P  pe sofit+dagesh
   1258 פּ    0xfb44  X.p  pe+dagesh
   1259 צּ    0xfb46  X.x  tsadi+dagesh
   1260 קּ    0xfb47  X.q  qof+dagesh
   1261 רּ    0xfb48  X.r  resh+dagesh
   1262 שּ    0xfb49  X.w  shin+dagesh
   1263 תּ    0xfb4a  X.t  tav+dagesh
   1264 וֹ    0xfb4b  Xo   vav+holam
   1265 בֿ    0xfb4c  XRb  bet+rafe
   1266 כֿ    0xfb4d  XRk  kaf+rafe
   1267 פֿ    0xfb4e  XRp  pe+rafe
   1268 ﭏ    0xfb4f  Xal  alef-lamed
   1269 
   1270 ==============================================================================
   1271 10.  Input with imactivatefunc()				*mbyte-func*
   1272 
   1273 Vim has the 'imactivatefunc' and 'imstatusfunc' options.  These are useful to
   1274 activate/deactivate the input method from Vim in any way, also with an
   1275 external command.  For example, fcitx provide fcitx-remote command: >
   1276 
   1277 	set iminsert=2
   1278 	set imsearch=2
   1279 	set imcmdline
   1280 
   1281 	set imactivatefunc=ImActivate
   1282 	function! ImActivate(active)
   1283 	  if a:active
   1284 	    call system('fcitx-remote -o')
   1285 	  else
   1286 	    call system('fcitx-remote -c')
   1287 	  endif
   1288 	endfunction
   1289 
   1290 	set imstatusfunc=ImStatus
   1291 	function! ImStatus()
   1292 	  return system('fcitx-remote')[0] is# '2'
   1293 	endfunction
   1294 
   1295 Using this script, you can activate/deactivate XIM via Vim even when it is not
   1296 compiled with |+xim|.
   1297 
   1298 ==============================================================================
   1299 11. Using UTF-8				*mbyte-utf8* *UTF-8* *utf-8* *utf8*
   1300 							*Unicode* *unicode*
   1301 The Unicode character set was designed to include all characters from other
   1302 character sets.  Therefore it is possible to write text in any language using
   1303 Unicode (with a few rarely used languages excluded).  And it's mostly possible
   1304 to mix these languages in one file, which is impossible with other encodings.
   1305 
   1306 Unicode can be encoded in several ways.  The most popular one is UTF-8, which
   1307 uses one or more bytes for each character and is backwards compatible with
   1308 ASCII.   On MS-Windows UTF-16 is also used (previously UCS-2), which uses
   1309 16-bit words.  Vim can support all of these encodings, but always uses UTF-8
   1310 internally.
   1311 
   1312 Vim has comprehensive UTF-8 support.  It works well in:
   1313 - xterm with UTF-8 support enabled
   1314 - Motif and GTK GUI
   1315 - MS-Windows GUI
   1316 - several other platforms
   1317 
   1318 Double-width characters are supported.  This works best with 'guifontwide' or
   1319 'guifontset'.  When using only 'guifont' the wide characters are drawn in the
   1320 normal width and a space to fill the gap.  Note that the 'guifontset' option
   1321 is no longer relevant in the GTK+ 2 GUI.
   1322 
   1323 							*bom-bytes*
   1324 When reading a file a BOM (Byte Order Mark) can be used to recognize the
   1325 Unicode encoding:
   1326 	EF BB BF     UTF-8
   1327 	FE FF        UTF-16 big endian
   1328 	FF FE        UTF-16 little endian
   1329 	00 00 FE FF  UTF-32 big endian
   1330 	FF FE 00 00  UTF-32 little endian
   1331 
   1332 UTF-8 is the recommended encoding.  Note that it's difficult to tell utf-16
   1333 and utf-32 apart.  Utf-16 is often used on MS-Windows, utf-32 is not
   1334 widespread as file format.
   1335 
   1336 
   1337 					*mbyte-combining* *mbyte-composing*
   1338 A composing or combining character is used to change the meaning of the
   1339 character before it.  The combining characters are drawn on top of the
   1340 preceding character.
   1341 Up to two combining characters can be used by default.  This can be changed
   1342 with the 'maxcombine' option.
   1343 When editing text a composing character is mostly considered part of the
   1344 preceding character.  For example "x" will delete a character and its
   1345 following composing characters by default.
   1346 If the 'delcombine' option is on, then pressing 'x' will delete the combining
   1347 characters, one at a time, then the base character.  But when inserting, you
   1348 type the first character and the following composing characters separately,
   1349 after which they will be joined.  The "r" command will not allow you to type a
   1350 combining character, because it doesn't know one is coming.  Use "R" instead.
   1351 
   1352 Bytes which are not part of a valid UTF-8 byte sequence are handled like a
   1353 single character and displayed as <xx>, where "xx" is the hex value of the
   1354 byte.
   1355 
   1356 Overlong sequences are not handled specially and displayed like a valid
   1357 character.  However, search patterns may not match on an overlong sequence.
   1358 (an overlong sequence is where more bytes are used than required for the
   1359 character.)  An exception is NUL (zero) which is displayed as "<00>".
   1360 
   1361 In the file and buffer the full range of Unicode characters can be used (31
   1362 bits).  However, displaying only works for the characters present in the
   1363 selected font.
   1364 
   1365 Useful commands:
   1366 - "ga" shows the decimal, hexadecimal and octal value of the character under
   1367   the cursor.  If there are composing characters these are shown too.  (If the
   1368   message is truncated, use ":messages").
   1369 - "g8" shows the bytes used in a UTF-8 character, also the composing
   1370   characters, as hex numbers.
   1371 - ":set encoding=utf-8 fileencodings=" forces using UTF-8 for all files.  The
   1372   default is to use the current locale for 'encoding' and set 'fileencodings'
   1373   to automatically detect the encoding of a file.
   1374 
   1375 
   1376 STARTING VIM
   1377 
   1378 If your current locale is in an UTF-8 encoding, Vim will automatically start
   1379 in UTF-8 mode.
   1380 
   1381 If you are using another locale: >
   1382 
   1383 	set encoding=utf-8
   1384 
   1385 You might also want to select the font used for the menus.  Unfortunately this
   1386 doesn't always work.  See the system specific remarks below, and 'langmenu'.
   1387 
   1388 
   1389 USING UTF-8 IN X-WINDOWS				*utf-8-in-xwindows*
   1390 
   1391 Note: This section does not apply to the GTK+ 2 GUI.
   1392 
   1393 You need to specify a font to be used.  For double-wide characters another
   1394 font is required, which is exactly twice as wide.  There are three ways to do
   1395 this:
   1396 
   1397 1. Set 'guifont' and let Vim find a matching 'guifontwide'
   1398 2. Set 'guifont' and 'guifontwide'
   1399 3. Set 'guifontset'
   1400 
   1401 See the documentation for each option for details.  Example: >
   1402 
   1403    :set guifont=-misc-fixed-medium-r-normal--15-140-75-75-c-90-iso10646-1
   1404 
   1405 You might also want to set the font used for the menus.  This only works for
   1406 Motif.  Use the ":hi Menu font={fontname}" command for this. |:highlight|
   1407 
   1408 
   1409 TYPING UTF-8						*utf-8-typing*
   1410 
   1411 If you are using X-Windows, you should find an input method that supports
   1412 the UTF-8 encoding.
   1413 
   1414 If your system does not provide support for typing UTF-8, you can use the
   1415 'keymap' feature.  This allows writing a keymap file, which defines a UTF-8
   1416 character as a sequence of ASCII characters.  See |mbyte-keymap|.
   1417 
   1418 Another method is to set the current locale to the language you want to use
   1419 and for which you have a XIM available.  Then set 'termencoding' to that
   1420 language and Vim will convert the typed characters to 'encoding' for you.
   1421 
   1422 If everything else fails, you can type any character as four hex bytes: >
   1423 
   1424 	CTRL-V u 1234
   1425 
   1426 "1234" is interpreted as a hex number.  You must type four characters, prepend
   1427 a zero if necessary.
   1428 
   1429 
   1430 COMMAND ARGUMENTS					*utf-8-char-arg*
   1431 
   1432 Commands like |f|, |F|, |t| and |r| take an argument of one character.  For
   1433 UTF-8 this argument may include one or two composing characters.  These need
   1434 to be produced together with the base character, Vim doesn't wait for the next
   1435 character to be typed to find out if it is a composing character or not.
   1436 Using 'keymap' or |:lmap| is a nice way to type these characters.
   1437 
   1438 The commands that search for a character in a line handle composing characters
   1439 as follows.  When searching for a character without a composing character,
   1440 this will find matches in the text with or without composing characters.  When
   1441 searching for a character with a composing character, this will only find
   1442 matches with that composing character.  It was implemented this way, because
   1443 not everybody is able to type a composing character.
   1444 
   1445 
   1446 ==============================================================================
   1447 12. Overview of options					*mbyte-options*
   1448 
   1449 These options are relevant for editing multibyte files.  Check the help in
   1450 options.txt for detailed information.
   1451 
   1452 'encoding'	Encoding used for the keyboard and display.  It is also the
   1453 		default encoding for files.
   1454 
   1455 'fileencoding'	Encoding of a file.  When it's different from 'encoding'
   1456 		conversion is done when reading or writing the file.
   1457 
   1458 'fileencodings'	List of possible encodings of a file.  When opening a file
   1459 		these will be tried and the first one that doesn't cause an
   1460 		error is used for 'fileencoding'.
   1461 
   1462 'charconvert'	Expression used to convert files from one encoding to another.
   1463 
   1464 'formatoptions' The 'm' flag can be included to have formatting break a line
   1465 		at a multibyte character of 256 or higher.  Thus is useful for
   1466 		languages where a sequence of characters can be broken
   1467 		anywhere.
   1468 
   1469 'guifontset'	The list of font names used for a multibyte encoding.  When
   1470 		this option is not empty, it replaces 'guifont'.
   1471 
   1472 'keymap'	Specify the name of a keyboard mapping.
   1473 
   1474 ==============================================================================
   1475 
   1476 Contributions specifically for the multibyte features by:
   1477 	Chi-Deok Hwang <hwang@mizi.co.kr>
   1478 	SungHyun Nam <goweol@gmail.com>
   1479 	K.Nagano <nagano@atese.advantest.co.jp>
   1480 	Taro Muraoka  <koron@tka.att.ne.jp>
   1481 	Yasuhiro Matsumoto <mattn@mail.goo.ne.jp>
   1482 
   1483  vim:tw=78:ts=8:noet:ft=help:norl: