Adding upstream version 2:9.1.0016.upstream/2%9.1.0016

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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..4a3684e
--- /dev/null
+++ b/runtime/doc/usr_45.txt
@@ -0,0 +1,413 @@
+*usr_45.txt*	For Vim version 9.1.  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: