summaryrefslogtreecommitdiffstats
path: root/runtime/doc/usr_45.txt
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 08:50:31 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 08:50:31 +0000
commitaed8ce9da277f5ecffe968b324f242c41c3b752a (patch)
treed2e538394cb7a8a7c42a4aac6ccf1a8e3256999b /runtime/doc/usr_45.txt
parentInitial commit. (diff)
downloadvim-aed8ce9da277f5ecffe968b324f242c41c3b752a.tar.xz
vim-aed8ce9da277f5ecffe968b324f242c41c3b752a.zip
Adding upstream version 2:9.0.1378.upstream/2%9.0.1378upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'runtime/doc/usr_45.txt')
-rw-r--r--runtime/doc/usr_45.txt413
1 files changed, 413 insertions, 0 deletions
diff --git a/runtime/doc/usr_45.txt b/runtime/doc/usr_45.txt
new file mode 100644
index 0000000..7e919a9
--- /dev/null
+++ b/runtime/doc/usr_45.txt
@@ -0,0 +1,413 @@
+*usr_45.txt* For Vim version 9.0. Last change: 2022 May 13
+
+ VIM USER MANUAL - by Bram Moolenaar
+
+ Select your language (locale)
+
+
+The messages in Vim can be given in several languages. This chapter explains
+how to change which one is used. Also, the different ways to work with files
+in various languages is explained.
+
+|45.1| Language for Messages
+|45.2| Language for Menus
+|45.3| Using another encoding
+|45.4| Editing files with a different encoding
+|45.5| Entering language text
+
+ Next chapter: |usr_50.txt| Advanced Vim script writing
+ Previous chapter: |usr_44.txt| Your own syntax highlighted
+Table of contents: |usr_toc.txt|
+
+==============================================================================
+*45.1* Language for Messages
+
+When you start Vim, it checks the environment to find out what language you
+are using. Mostly this should work fine, and you get the messages in your
+language (if they are available). To see what the current language is, use
+this command: >
+
+ :language
+
+If it replies with "C", this means the default is being used, which is
+English.
+
+ Note:
+ Using different languages only works when Vim was compiled to handle
+ it. To find out if it works, use the ":version" command and check the
+ output for "+gettext" and "+multi_lang". If they are there, you are
+ OK. If you see "-gettext" or "-multi_lang" you will have to find
+ another Vim.
+
+What if you would like your messages in a different language? There are
+several ways. Which one you should use depends on the capabilities of your
+system.
+ The first way is to set the environment to the desired language before
+starting Vim. Example for Unix: >
+
+ env LANG=de_DE.ISO_8859-1 vim
+
+This only works if the language is available on your system. The advantage is
+that all the GUI messages and things in libraries will use the right language
+as well. A disadvantage is that you must do this before starting Vim. If you
+want to change language while Vim is running, you can use the second method: >
+
+ :language fr_FR.ISO_8859-1
+
+This way you can try out several names for your language. You will get an
+error message when it's not supported on your system. You don't get an error
+when translated messages are not available. Vim will silently fall back to
+using English.
+ To find out which languages are supported on your system, find the
+directory where they are listed. On my system it is "/usr/share/locale". On
+some systems it's in "/usr/lib/locale". The manual page for "setlocale"
+should give you a hint where it is found on your system.
+ Be careful to type the name exactly as it should be. Upper and lowercase
+matter, and the '-' and '_' characters are easily confused.
+
+You can also set the language separately for messages, edited text and the
+time format. See |:language|.
+
+
+DO-IT-YOURSELF MESSAGE TRANSLATION
+
+If translated messages are not available for your language, you could write
+them yourself. To do this, get the source code for Vim and the GNU gettext
+package. After unpacking the sources, instructions can be found in the
+directory src/po/README.txt.
+ It's not too difficult to do the translation. You don't need to be a
+programmer. You must know both English and the language you are translating
+to, of course.
+ When you are satisfied with the translation, consider making it available
+to others. Upload it at vim-online (http://vim.sf.net) or e-mail it to
+the Vim maintainer <maintainer@vim.org>. Or both.
+
+==============================================================================
+*45.2* Language for Menus
+
+The default menus are in English. To be able to use your local language, they
+must be translated. Normally this is automatically done for you if the
+environment is set for your language, just like with messages. You don't need
+to do anything extra for this. But it only works if translations for the
+language are available.
+ Suppose you are in Germany, with the language set to German, but prefer to
+use "File" instead of "Datei". You can switch back to using the English menus
+this way: >
+
+ :set langmenu=none
+
+It is also possible to specify a language: >
+
+ :set langmenu=nl_NL.ISO_8859-1
+
+Like above, differences between "-" and "_" matter. However, upper/lowercase
+differences are ignored here.
+ The 'langmenu' option must be set before the menus are loaded. Once the
+menus have been defined changing 'langmenu' has no direct effect. Therefore,
+put the command to set 'langmenu' in your vimrc file.
+ If you really want to switch menu language while running Vim, you can do it
+this way: >
+
+ :source $VIMRUNTIME/delmenu.vim
+ :set langmenu=de_DE.ISO_8859-1
+ :source $VIMRUNTIME/menu.vim
+
+There is one drawback: All menus that you defined yourself will be gone. You
+will need to redefine them as well.
+
+
+DO-IT-YOURSELF MENU TRANSLATION
+
+To see which menu translations are available, look in this directory:
+
+ $VIMRUNTIME/lang ~
+
+The files are called menu_{language}.vim. If you don't see the language you
+want to use, you can do your own translations. The simplest way to do this is
+by copying one of the existing language files, and change it.
+ First find out the name of your language with the ":language" command. Use
+this name, but with all letters made lowercase. Then copy the file to your
+own runtime directory, as found early in 'runtimepath'. For example, for Unix
+you would do: >
+
+ :!cp $VIMRUNTIME/lang/menu_ko_kr.euckr.vim ~/.vim/lang/menu_nl_be.iso_8859-1.vim
+
+You will find hints for the translation in "$VIMRUNTIME/lang/README.txt".
+
+==============================================================================
+*45.3* Using another encoding
+
+Vim guesses that the files you are going to edit are encoded for your
+language. For many European languages this is "latin1". Then each byte is
+one character. That means there are 256 different characters possible. For
+Asian languages this is not sufficient. These mostly use a double-byte
+encoding, providing for over ten thousand possible characters. This still
+isn't enough when a text is to contain several different languages. This is
+where Unicode comes in. It was designed to include all characters used in
+commonly used languages. This is the "Super encoding that replaces all
+others". But it isn't used that much yet.
+ Fortunately, Vim supports these three kinds of encodings. And, with some
+restrictions, you can use them even when your environment uses another
+language than the text.
+ Nevertheless, when you only edit files that are in the encoding of your
+language, the default should work fine and you don't need to do anything. The
+following is only relevant when you want to edit different languages.
+
+
+USING UNICODE IN THE GUI
+
+The nice thing about Unicode is that other encodings can be converted to it
+and back without losing information. When you make Vim use Unicode
+internally, you will be able to edit files in any encoding.
+ Unfortunately, the number of systems supporting Unicode is still limited.
+Thus it's unlikely that your language uses it. You need to tell Vim you want
+to use Unicode, and how to handle interfacing with the rest of the system.
+ Let's start with the GUI version of Vim, which is able to display Unicode
+characters. This should work: >
+
+ :set encoding=utf-8
+ :set guifont=-misc-fixed-medium-r-normal--18-120-100-100-c-90-iso10646-1
+
+The 'encoding' option tells Vim the encoding of the characters that you use.
+This applies to the text in buffers (files you are editing), registers, Vim
+script files, etc. You can regard 'encoding' as the setting for the internals
+of Vim.
+ This example assumes you have this font on your system. The name in the
+example is for the X Window System. This font is in a package that is used to
+enhance xterm with Unicode support. If you don't have this font, you might
+find it here:
+
+ http://www.cl.cam.ac.uk/~mgk25/download/ucs-fonts.tar.gz ~
+
+For MS-Windows, some fonts have a limited number of Unicode characters. Try
+using the "Courier New" font. You can use the Edit/Select Font... menu to
+select and try out the fonts available. Only fixed-width fonts can be used
+though. Example: >
+
+ :set guifont=courier_new:h12
+
+If it doesn't work well, try getting a fontpack. If Microsoft didn't move it,
+you can find it here:
+
+ http://www.microsoft.com/typography/fonts/default.aspx ~
+
+Now you have told Vim to use Unicode internally and display text with a
+Unicode font. Typed characters still arrive in the encoding of your original
+language. This requires converting them to Unicode. Tell Vim the language
+from which to convert with the 'termencoding' option. You can do it like
+this: >
+
+ :let &termencoding = &encoding
+ :set encoding=utf-8
+
+This assigns the old value of 'encoding' to 'termencoding' before setting
+'encoding' to utf-8. You will have to try out if this really works for your
+setup. It should work especially well when using an input method for an Asian
+language, and you want to edit Unicode text.
+
+
+USING UNICODE IN A UNICODE TERMINAL
+
+There are terminals that support Unicode directly. The standard xterm that
+comes with XFree86 is one of them. Let's use that as an example.
+ First of all, the xterm must have been compiled with Unicode support. See
+|UTF8-xterm| how to check that and how to compile it when needed.
+ Start the xterm with the "-u8" argument. You might also need so specify a
+font. Example: >
+
+ xterm -u8 -fn -misc-fixed-medium-r-normal--18-120-100-100-c-90-iso10646-1
+
+Now you can run Vim inside this terminal. Set 'encoding' to "utf-8" as
+before. That's all.
+
+
+USING UNICODE IN AN ORDINARY TERMINAL
+
+Suppose you want to work with Unicode files, but don't have a terminal with
+Unicode support. You can do this with Vim, although characters that are not
+supported by the terminal will not be displayed. The layout of the text
+will be preserved. >
+
+ :let &termencoding = &encoding
+ :set encoding=utf-8
+
+This is the same as what was used for the GUI. But it works differently: Vim
+will convert the displayed text before sending it to the terminal. That
+avoids that the display is messed up with strange characters.
+ For this to work the conversion between 'termencoding' and 'encoding' must
+be possible. Vim will convert from latin1 to Unicode, thus that always works.
+For other conversions the |+iconv| feature is required.
+ Try editing a file with Unicode characters in it. You will notice that Vim
+will put a question mark (or underscore or some other character) in places
+where a character should be that the terminal can't display. Move the cursor
+to a question mark and use this command: >
+
+ ga
+
+Vim will display a line with the code of the character. This gives you a hint
+about what character it is. You can look it up in a Unicode table. You could
+actually view a file that way, if you have lots of time at hand.
+
+ Note:
+ Since 'encoding' is used for all text inside Vim, changing it makes
+ all non-ASCII text invalid. You will notice this when using registers
+ and the 'viminfo' file (e.g., a remembered search pattern). It's
+ recommended to set 'encoding' in your vimrc file, and leave it alone.
+
+==============================================================================
+*45.4* Editing files with a different encoding
+
+Suppose you have setup Vim to use Unicode, and you want to edit a file that is
+in 16-bit Unicode. Sounds simple, right? Well, Vim actually uses utf-8
+encoding internally, thus the 16-bit encoding must be converted, since there
+is a difference between the character set (Unicode) and the encoding (utf-8 or
+16-bit).
+ Vim will try to detect what kind of file you are editing. It uses the
+encoding names in the 'fileencodings' option. When using Unicode, the default
+value is: "ucs-bom,utf-8,latin1". This means that Vim checks the file to see
+if it's one of these encodings:
+
+ ucs-bom File must start with a Byte Order Mark (BOM). This
+ allows detection of 16-bit, 32-bit and utf-8 Unicode
+ encodings.
+ utf-8 utf-8 Unicode. This is rejected when a sequence of
+ bytes is illegal in utf-8.
+ latin1 The good old 8-bit encoding. Always works.
+
+When you start editing that 16-bit Unicode file, and it has a BOM, Vim will
+detect this and convert the file to utf-8 when reading it. The 'fileencoding'
+option (without s at the end) is set to the detected value. In this case it
+is "utf-16le". That means it's Unicode, 16-bit and little-endian. This
+file format is common on MS-Windows (e.g., for registry files).
+ When writing the file, Vim will compare 'fileencoding' with 'encoding'. If
+they are different, the text will be converted.
+ An empty value for 'fileencoding' means that no conversion is to be done.
+Thus the text is assumed to be encoded with 'encoding'.
+
+If the default 'fileencodings' value is not good for you, set it to the
+encodings you want Vim to try. Only when a value is found to be invalid will
+the next one be used. Putting "latin1" first doesn't work, because it is
+never illegal. An example, to fall back to Japanese when the file doesn't
+have a BOM and isn't utf-8: >
+
+ :set fileencodings=ucs-bom,utf-8,sjis
+
+See |encoding-values| for suggested values. Other values may work as well.
+This depends on the conversion available.
+
+
+FORCING AN ENCODING
+
+If the automatic detection doesn't work you must tell Vim what encoding the
+file is. Example: >
+
+ :edit ++enc=koi8-r russian.txt
+
+The "++enc" part specifies the name of the encoding to be used for this file
+only. Vim will convert the file from the specified encoding, Russian in this
+example, to 'encoding'. 'fileencoding' will also be set to the specified
+encoding, so that the reverse conversion can be done when writing the file.
+ The same argument can be used when writing the file. This way you can
+actually use Vim to convert a file. Example: >
+
+ :write ++enc=utf-8 russian.txt
+<
+ Note:
+ Conversion may result in lost characters. Conversion from an encoding
+ to Unicode and back is mostly free of this problem, unless there are
+ illegal characters. Conversion from Unicode to other encodings often
+ loses information when there was more than one language in the file.
+
+==============================================================================
+*45.5* Entering language text
+
+Computer keyboards don't have much more than a hundred keys. Some languages
+have thousands of characters, Unicode has over hundred thousand. So how do
+you type these characters?
+ First of all, when you don't use too many of the special characters, you
+can use digraphs. This was already explained in |24.9|.
+ When you use a language that uses many more characters than keys on your
+keyboard, you will want to use an Input Method (IM). This requires learning
+the translation from typed keys to resulting character. When you need an IM
+you probably already have one on your system. It should work with Vim like
+with other programs. For details see |mbyte-XIM| for the X Window system and
+|mbyte-IME| for MS-Windows.
+
+
+KEYMAPS
+
+For some languages the character set is different from latin, but uses a
+similar number of characters. It's possible to map keys to characters. Vim
+uses keymaps for this.
+ Suppose you want to type Hebrew. You can load the keymap like this: >
+
+ :set keymap=hebrew
+
+Vim will try to find a keymap file for you. This depends on the value of
+'encoding'. If no matching file was found, you will get an error message.
+
+Now you can type Hebrew in Insert mode. In Normal mode, and when typing a ":"
+command, Vim automatically switches to English. You can use this command to
+switch between Hebrew and English: >
+
+ CTRL-^
+
+This only works in Insert mode and Command-line mode. In Normal mode it does
+something completely different (jumps to alternate file).
+ The usage of the keymap is indicated in the mode message, if you have the
+'showmode' option set. In the GUI Vim will indicate the usage of keymaps with
+a different cursor color.
+ You can also change the usage of the keymap with the 'iminsert' and
+'imsearch' options.
+
+To see the list of mappings, use this command: >
+
+ :lmap
+
+To find out which keymap files are available, in the GUI you can use the
+Edit/Keymap menu. Otherwise you can use this command: >
+
+ :echo globpath(&rtp, "keymap/*.vim")
+
+
+DO-IT-YOURSELF KEYMAPS
+
+You can create your own keymap file. It's not very difficult. Start with
+a keymap file that is similar to the language you want to use. Copy it to the
+"keymap" directory in your runtime directory. For example, for Unix, you
+would use the directory "~/.vim/keymap".
+ The name of the keymap file must look like this:
+
+ keymap/{name}.vim ~
+or
+ keymap/{name}_{encoding}.vim ~
+
+{name} is the name of the keymap. Chose a name that is obvious, but different
+from existing keymaps (unless you want to replace an existing keymap file).
+{name} cannot contain an underscore. Optionally, add the encoding used after
+an underscore. Examples:
+
+ keymap/hebrew.vim ~
+ keymap/hebrew_utf-8.vim ~
+
+The contents of the file should be self-explanatory. Look at a few of the
+keymaps that are distributed with Vim. For the details, see |mbyte-keymap|.
+
+
+LAST RESORT
+
+If all other methods fail, you can enter any character with CTRL-V:
+
+ encoding type range ~
+ 8-bit CTRL-V 123 decimal 0-255
+ 8-bit CTRL-V x a1 hexadecimal 00-ff
+ 16-bit CTRL-V u 013b hexadecimal 0000-ffff
+ 31-bit CTRL-V U 001303a4 hexadecimal 00000000-7fffffff
+
+Don't type the spaces. See |i_CTRL-V_digit| for the details.
+
+==============================================================================
+
+Next chapter: |usr_50.txt| Advanced Vim script writing
+
+Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: