diff options
| author | ZyX <kp-pav@yandex.ru> | 2017-05-08 15:43:45 +0300 |
|---|---|---|
| committer | ZyX <kp-pav@yandex.ru> | 2017-05-08 15:43:45 +0300 |
| commit | 09f849b60000c2d401d82f2b2fb2badde5583658 (patch) | |
| tree | 662d17ea2e905f4136abef2d003014cb7dc914d4 /runtime/doc | |
| parent | 1d7fde39a6927d01de74aefb540ad445bfdfbfda (diff) | |
| parent | a9605bb4aff76a934a4c39fbda093ee8fc8a1c71 (diff) | |
| download | rneovim-09f849b60000c2d401d82f2b2fb2badde5583658.tar.gz rneovim-09f849b60000c2d401d82f2b2fb2badde5583658.tar.bz2 rneovim-09f849b60000c2d401d82f2b2fb2badde5583658.zip | |
Merge branch 'master' into luaviml'/lua
Diffstat (limited to 'runtime/doc')
67 files changed, 950 insertions, 1648 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 2bcc996d8b..8db35c4590 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -9,8 +9,9 @@ Nvim API *API* *api* Nvim exposes a powerful API that can be used by plugins and external processes via |msgpack-rpc|, Lua and VimL (|eval-api|). -Nvim can also be embedded in C applications as libnvim, so the application -can control the embedded instance by calling the C API directly. +Applications can also embed libnvim to work with the C API directly. + + Type <M-]> to see the table of contents. ============================================================================== API Types *api-types* @@ -55,6 +56,28 @@ error_types Possible error types returned by API functions External programs ("clients") can use the metadata to discover the |rpc-api|. ============================================================================== +API contract *api-contract* + +The API is made of functions and events. Clients call functions like those +described at |api-global|, and may "attach" in order to receive rich events, +described at |rpc-remote-ui|. + +As Nvim develops, its API may change only according the following "contract": + +- New functions and events may be added. + - Any such extensions are OPTIONAL: old clients may ignore them. +- Function signatures will NOT CHANGE (after release). + - Functions introduced in the development (unreleased) version MAY CHANGE. + (Clients can dynamically check `api_prerelease`, etc. |api-metadata|) +- Event parameters will not be removed or reordered (after release). +- Events may be EXTENDED: new parameters may be added. +- New items may be ADDED to map/list parameters/results of functions and + events. + - Any such new items are OPTIONAL: old clients may ignore them. + - Existing items will not be removed (after release). +- Deprecated functions will not be removed until Nvim version 2.0 + +============================================================================== Buffer highlighting *api-highlights* Nvim allows plugins to add position-based highlights to buffers. This is @@ -247,7 +270,7 @@ nvim_get_option({name}) *nvim_get_option()* {name} Option name Return:~ - Option value + Option value (global) nvim_set_option({name}, {value}) *nvim_set_option()* Sets an option value @@ -347,6 +370,17 @@ nvim_get_color_by_name({name}) *nvim_get_color_by_name()* nvim_get_color_map() *nvim_get_color_map()* TODO: Documentation +nvim_get_mode() *nvim_get_mode()* + Gets the current mode. + mode: Mode string. |mode()| + blocking: true if Nvim is waiting for input. + + Attributes:~ + {async} + + Return:~ + Dictionary { "mode": String, "blocking": Boolean } + nvim_get_api_info() *nvim_get_api_info()* TODO: Documentation @@ -491,15 +525,6 @@ nvim_buf_set_option({buffer}, {name}, {value}) *nvim_buf_set_option()* {name} Option name {value} Option value -nvim_buf_get_number({buffer}) *nvim_buf_get_number()* - Gets the buffer number - - Parameters:~ - {buffer} Buffer handle - - Return:~ - Buffer number - nvim_buf_get_name({buffer}) *nvim_buf_get_name()* Gets the full file name for the buffer diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index e7c7b0d71a..2a98d08c4e 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -8,17 +8,7 @@ Automatic commands *autocommand* For a basic explanation, see section |40.3| in the user manual. -1. Introduction |autocmd-intro| -2. Defining autocommands |autocmd-define| -3. Removing autocommands |autocmd-remove| -4. Listing autocommands |autocmd-list| -5. Events |autocmd-events| -6. Patterns |autocmd-patterns| -7. Buffer-local autocommands |autocmd-buflocal| -8. Groups |autocmd-groups| -9. Executing autocommands |autocmd-execute| -10. Using autocommands |autocmd-use| -11. Disabling autocommands |autocmd-disable| + Type <M-]> to see the table of contents. ============================================================================== 1. Introduction *autocmd-intro* @@ -30,7 +20,7 @@ files matching *.c. You can also use autocommands to implement advanced features, such as editing compressed files (see |gzip-example|). The usual place to put autocommands is in your vimrc file. - *E203* *E204* *E143* *E855* + *E203* *E204* *E143* *E855* *E937* WARNING: Using autocommands is very powerful, and may lead to unexpected side effects. Be careful not to destroy your text. - It's a good idea to do some testing on an expendable copy of a file first. @@ -76,11 +66,15 @@ exception is that "<sfile>" is expanded when the autocmd is defined. Example: Here Vim expands <sfile> to the name of the file containing this line. -When your vimrc file is sourced twice, the autocommands will appear twice. -To avoid this, put this command in your vimrc file, before defining -autocommands: > +`:autocmd` adds to the list of autocommands regardless of whether they are +already present. When your .vimrc file is sourced twice, the autocommands +will appear twice. To avoid this, define your autocommands in a group, so +that you can easily clear them: > - :autocmd! " Remove ALL autocommands for the current group. + augroup vimrc + autocmd! " Remove all vimrc autocommands + au BufNewFile,BufRead *.html so <sfile>:h/html.vim + augroup END If you don't want to remove all autocommands, you can instead use a variable to ensure that Vim includes the autocommands only once: > @@ -127,8 +121,13 @@ prompt. When one command outputs two messages this can happen anyway. :au[tocmd]! [group] {event} Remove ALL autocommands for {event}. + Warning: You should not do this without a group for + |BufRead| and other common events, it can break + plugins, syntax highlighting, etc. :au[tocmd]! [group] Remove ALL autocommands. + Warning: You should normally not do this without a + group, it breaks plugins, syntax highlighting, etc. When the [group] argument is not given, Vim uses the current group (as defined with ":augroup"); otherwise, Vim uses the group defined with [group]. @@ -422,8 +421,8 @@ BufUnload Before unloading a buffer. This is when the NOTE: When this autocommand is executed, the current buffer "%" may be different from the buffer being unloaded "<afile>". - Don't change to another buffer, it will cause - problems. + Don't change to another buffer or window, it + will cause problems! When exiting and v:dying is 2 or more this event is not triggered. *BufWinEnter* @@ -794,7 +793,9 @@ QuickFixCmdPre Before a quickfix command is run (|:make|, |:vimgrepadd|, |:lvimgrepadd|, |:cscope|, |:cfile|, |:cgetfile|, |:caddfile|, |:lfile|, |:lgetfile|, |:laddfile|, |:helpgrep|, - |:lhelpgrep|). + |:lhelpgrep|, |:cexpr|, |:cgetexpr|, + |:caddexpr|, |:cbuffer|, |:cgetbuffer|, + |:caddbuffer|). The pattern is matched against the command being run. When |:grep| is used but 'grepprg' is set to "internal" it still matches "grep". @@ -1002,7 +1003,7 @@ WinLeave Before leaving a window. If the window to be *WinNew* WinNew When a new window was created. Not done for - the fist window, when Vim has just started. + the first window, when Vim has just started. Before a WinEnter event. ============================================================================== @@ -1086,6 +1087,9 @@ Note that for all systems the '/' character is used for path separator (even Windows). This was done because the backslash is difficult to use in a pattern and to make the autocommands portable across different systems. +It is possible to use |pattern| items, but they may not work as expected, +because of the translation done for the above. + *autocmd-changes* Matching with the pattern is done when an event is triggered. Changing the buffer name in one of the autocommands, or even deleting the buffer, does not @@ -1184,11 +1188,12 @@ name! different from existing {event} names, as this most likely will not do what you intended. - *:augroup-delete* *E367* *W19* + *:augroup-delete* *E367* *W19* *E936* :aug[roup]! {name} Delete the autocmd group {name}. Don't use this if there is still an autocommand using this group! You will get a warning if doing - it anyway. + it anyway. when the group is the current group + you will get error E936. To enter autocommands for a specific group, use this method: 1. Select the group with ":augroup {name}". diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt index e0974b103c..6af3c4d5d7 100644 --- a/runtime/doc/change.txt +++ b/runtime/doc/change.txt @@ -9,20 +9,10 @@ changing text means deleting the text and replacing it with other text using one command. You can undo all of these commands. You can repeat the non-Ex commands with the "." command. -1. Deleting text |deleting| -2. Delete and insert |delete-insert| -3. Simple changes |simple-change| *changing* -4. Complex changes |complex-change| - 4.1 Filter commands |filter| - 4.2 Substitute |:substitute| - 4.3 Search and replace |search-replace| - 4.4 Changing tabs |change-tabs| -5. Copying and moving text |copy-move| -6. Formatting text |formatting| -7. Sorting text |sorting| - For inserting text see |insert.txt|. + Type <M-]> to see the table of contents. + ============================================================================== 1. Deleting text *deleting* *E470* @@ -259,7 +249,7 @@ Or use "caw" (see |aw|). command is executed. ============================================================================== -3. Simple changes *simple-change* +3. Simple changes *simple-change* *changing* *r* r{char} Replace the character under the cursor with {char}. @@ -398,11 +388,6 @@ CTRL-X Subtract [count] from the number or alphabetic {Visual}CTRL-X Subtract [count] from the number or alphabetic character in the highlighted text. {not in Vi} - On MS-Windows, this is mapped to cut Visual text - |dos-standard-mappings|. If you want to disable the - mapping, use this: > - silent! vunmap <C-X> -< *v_g_CTRL-X* {Visual}g CTRL-X Subtract [count] from the number or alphabetic character in the highlighted text. If several lines @@ -614,12 +599,14 @@ Directory for temporary files is created in the first suitable directory of: For the {pattern} see |pattern|. {string} can be a literal string, or something special; see |sub-replace-special|. + *E939* When [range] and [count] are omitted, replace in the - current line only. - When [count] is given, replace in [count] lines, - starting with the last line in [range]. When [range] - is omitted start in the current line. - Also see |cmdline-ranges|. + current line only. When [count] is given, replace in + [count] lines, starting with the last line in [range]. + When [range] is omitted start in the current line. + [count] must be a positive number. Also see + |cmdline-ranges|. + See |:s_flags| for [flags]. :[range]s[ubstitute] [flags] [count] @@ -833,6 +820,7 @@ The numbering of "\1", "\2" etc. is done based on which "\(" comes first in the pattern (going left to right). When a parentheses group matches several times, the last one will be used for "\1", "\2", etc. Example: > :s/\(\(a[a-d] \)*\)/\2/ modifies "aa ab x" to "ab x" +The "\2" is for "\(a[a-d] \)". At first it matches "aa ", secondly "ab ". When using parentheses in combination with '|', like in \([ab]\)\|\([cd]\), either the first or second pattern in parentheses did not match, so either diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt index 7277e1d22e..948c921431 100644 --- a/runtime/doc/cmdline.txt +++ b/runtime/doc/cmdline.txt @@ -13,13 +13,7 @@ Command-line mode is used to enter Ex commands (":"), search patterns Basic command line editing is explained in chapter 20 of the user manual |usr_20.txt|. -1. Command-line editing |cmdline-editing| -2. Command-line completion |cmdline-completion| -3. Ex command-lines |cmdline-lines| -4. Ex command-line ranges |cmdline-ranges| -5. Ex command-line flags |ex-flags| -6. Ex special characters |cmdline-special| -7. Command-line window |cmdline-window| + Type <M-]> to see the table of contents. ============================================================================== 1. Command-line editing *cmdline-editing* @@ -219,9 +213,10 @@ CTRL-Y When there is a modeless selection, copy the selection into the clipboard. |modeless-selection| If there is no selection CTRL-Y is inserted as a character. -CTRL-J *c_CTRL-J* *c_<NL>* *c_<CR>* *c_CR* +CTRL-M or CTRL-J *c_CTRL-M* *c_CTRL-J* *c_<NL>* *c_<CR>* *c_CR* <CR> or <NL> start entered command - *c_<Esc>* *c_Esc* + +CTRL-[ *c_CTRL-[* *c_<Esc>* *c_Esc* <Esc> When typed and 'x' not present in 'cpoptions', quit Command-line mode without executing. In macros or when 'x' present in 'cpoptions', start entered command. @@ -999,10 +994,10 @@ There are several ways to leave the command-line window: Insert and in Normal mode. CTRL-C Continue in Command-line mode. The command-line under the cursor is used as the command-line. Works both in Insert and - in Normal mode. ":close" also works. There is no redraw, - thus the window will remain visible. + in Normal mode. There is no redraw, thus the window will + remain visible. :quit Discard the command line and go back to Normal mode. - ":exit", ":xit" and CTRL-\ CTRL-N also work. + ":close", ":exit", ":xit" and CTRL-\ CTRL-N also work. :qall Quit Vim, unless there are changes in some buffer. :qall! Quit Vim, discarding changes to any buffer. diff --git a/runtime/doc/debug.txt b/runtime/doc/debug.txt index c5414e91ca..fd2c4fa54e 100644 --- a/runtime/doc/debug.txt +++ b/runtime/doc/debug.txt @@ -9,9 +9,7 @@ Debugging Vim *debug-vim* This is for debugging Vim itself, when it doesn't work properly. For debugging Vim scripts, functions, etc. see |debug-scripts| -1. Location of a crash, using gcc and gdb |debug-gcc| -2. Locating memory leaks |debug-leaks| -3. Windows Bug Reporting |debug-win32| + Type <M-]> to see the table of contents. ============================================================================== diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 76ccc42546..7fd1f90173 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -6,22 +6,19 @@ Development of Nvim. *development* -1. Design goals |design-goals| -2. Design decisions |design-decisions| - Nvim is open source software. Everybody is encouraged to contribute. https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md -See src/nvim/README.md for a high-level overview of the source code: - https://github.com/neovim/neovim/blob/master/src/nvim/README.md +See src/nvim/README.md for an overview of the source code. + + Type <M-]> to see the table of contents. ============================================================================== -1. Design goals *design-goals* +Design goals *design-goals* Most important things come first (roughly). -Note that quite a few items are contradicting. This is intentional. A -balance must be found between them. +Note that some items conflict; this is intentional. A balance must be found. NVIM IS... IMPROVED *design-improved* @@ -41,7 +38,7 @@ completely different editor. Extensions are done with a "Vi spirit". - There are many first-time and inexperienced Vim users. Make it easy for them to start using Vim and learn more over time. - There is no limit to the features that can be added. Selecting new features - is one based on (1) what users ask for, (2) how much effort it takes to + is based on (1) what users ask for, (2) how much effort it takes to implement and (3) someone actually implementing it. @@ -56,20 +53,14 @@ Vim tries to help as many users on as many platforms as possible. - Support many compilers and libraries. Not everybody is able or allowed to install another compiler or GUI library. - People switch from one platform to another, and from GUI to terminal - version. Features should be present in all versions, or at least in as many - as possible with a reasonable effort. Try to avoid that users must switch - between platforms to accomplish their work efficiently. -- That a feature is not possible on some platforms, or only possible on one - platform, does not mean it cannot be implemented. [This intentionally - contradicts the previous item, these two must be balanced.] + version. Features should be present in all versions. NVIM IS... WELL DOCUMENTED *design-documented* - A feature that isn't documented is a useless feature. A patch for a new feature must include the documentation. -- Documentation should be comprehensive and understandable. Using examples is - recommended. +- Documentation should be comprehensive and understandable. Use examples. - Don't make the text unnecessarily long. Less documentation means that an item is easier to find. - Do not prefix doc-tags with "nvim-". Use |vim_diff.txt| to document @@ -77,12 +68,12 @@ NVIM IS... WELL DOCUMENTED *design-documented* to mark a specific feature. No other distinction is necessary. - If a feature is removed, delete its doc entry and move its tag to |vim_diff.txt|. +- Move deprecated features to |deprecated.txt|. NVIM IS... HIGH SPEED AND SMALL IN SIZE *design-speed-size* -Using Vim must not be a big attack on system resources. Keep it small and -fast. +Keep Nvim small and fast. - Computers are becoming faster and bigger each year. Vim can grow too, but no faster than computers are growing. Keep Vim usable on older systems. - Many users start Vim from a shell very often. Startup time must be short. @@ -118,13 +109,14 @@ NVIM IS... NOT *design-not* Nvim is not an operating system; instead it should be composed with other tools or hosted as a component. Marvim once said: "Unlike Emacs, Nvim does not -include the kitchen sink... but you can use it for plumbing." +include the kitchen sink... but it's good for plumbing." ============================================================================== -2. Design decisions *design-decisions* +Developer guidelines *dev-help* -JARGON *dev-jargon* + +JARGON *dev-jargon* API client ~ All external UIs and remote plugins (as opposed to regular Vim plugins) are @@ -150,15 +142,14 @@ the xterm window, a window inside Vim to view a buffer. To avoid confusion, other items that are sometimes called window have been given another name. Here is an overview of the related items: -screen The whole display. For the GUI it's something like 1024x768 - pixels. The Vim shell can use the whole screen or part of it. +screen The whole display. shell The Vim application. This can cover the whole screen (e.g., when running in a console) or part of it (xterm or GUI). window View on a buffer. There can be several windows in Vim, together with the command line, menubar, toolbar, etc. they fit in the shell. -PROVIDERS *dev-provider* +PROVIDERS *dev-provider* A goal of Nvim is to allow extension of the editor without special knowledge in the core. But some Vim components are too tightly coupled; in those cases @@ -202,7 +193,7 @@ Python host isn't installed then the plugin will "think" it is running in a Vim compiled without the |+python| feature. -API *dev-api* +API *dev-api* Use this pattern to name new API functions: nvim_{thing}_{action}_{arbitrary-qualifiers} @@ -233,4 +224,23 @@ _not_ a Buffer). The common {action} "list" indicates that it lists all bufs (plural) in the global context. +EXTERNAL UI *dev-ui* + +External UIs should be aware of the |api-contract|. In particular, future +versions of Nvim may add optional, new items to existing events. The API is +strongly backwards-compatible, but clients must not break if new fields are +added to existing events. + +External UIs are expected to implement some common features. + +- Users may want to configure UI-specific options. The UI should publish the + |GUIEnter| autocmd after attaching to Nvim: > + doautocmd GUIEnter +- Options can be monitored for changes by the |OptionSet| autocmd. E.g. if the + user sets the 'guifont' option, this autocmd notifies channel 42: > + autocmd OptionSet guifont call rpcnotify(42, 'option-changed', 'guifont', &guifont) +- cursor-shape change: 'guicursor' properties are sent in the mode_info_set UI + event. + + vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/diff.txt b/runtime/doc/diff.txt index 12f4563518..74a3d183a3 100644 --- a/runtime/doc/diff.txt +++ b/runtime/doc/diff.txt @@ -10,11 +10,7 @@ eight versions of the same file. The basics are explained in section |08.7| of the user manual. -1. Starting diff mode |diff-mode| -2. Viewing diffs |view-diffs| -3. Jumping to diffs |jumpto-diffs| -4. Copying diffs |copy-diffs| -5. Diff options |diff-options| + Type <M-]> to see the table of contents. ============================================================================== 1. Starting diff mode @@ -123,6 +119,8 @@ file for a moment and come back to the same file and be in diff mode again. related options only happens in a window that has 'diff' set, if the current window does not have 'diff' set then no options in it are changed. + Hidden buffers are also removed from the list of diff'ed + buffers. The `:diffoff` command resets the relevant options to the values they had when using `:diffsplit`, `:diffpatch` , `:diffthis`. or starting Vim in diff mode. @@ -156,7 +154,8 @@ The alignment of text will go wrong when: All the buffers edited in a window where the 'diff' option is set will join in the diff. This is also possible for hidden buffers. They must have been -edited in a window first for this to be possible. +edited in a window first for this to be possible. To get rid of the hidden +buffers use `:diffoff!`. *:DiffOrig* *diff-original-file* Since 'diff' is a window-local option, it's possible to view the same buffer diff --git a/runtime/doc/digraph.txt b/runtime/doc/digraph.txt index 20fbe60602..89351c5b4f 100644 --- a/runtime/doc/digraph.txt +++ b/runtime/doc/digraph.txt @@ -14,9 +14,7 @@ with CTRL-V (see |i_CTRL-V|). There is a brief introduction on digraphs in the user manual: |24.9| An alternative is using the 'keymap' option. -1. Defining digraphs |digraphs-define| -2. Using digraphs |digraphs-use| -3. Default digraphs |digraphs-default| + Type <M-]> to see the table of contents. ============================================================================== 1. Defining digraphs *digraphs-define* diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt index 57458b7b81..9fe815ea9c 100644 --- a/runtime/doc/editing.txt +++ b/runtime/doc/editing.txt @@ -6,17 +6,7 @@ Editing files *edit-files* -1. Introduction |edit-intro| -2. Editing a file |edit-a-file| -3. The argument list |argument-list| -4. Writing |writing| -5. Writing and quitting |write-quit| -6. Dialogs |edit-dialogs| -7. The current directory |current-directory| -8. Editing binary files |edit-binary| -9. Encryption |encryption| -10. Timestamps |timestamps| -11. File Searching |file-searching| + Type <M-]> to see the table of contents. ============================================================================== 1. Introduction *edit-intro* @@ -160,7 +150,8 @@ start editing another file, Vim will refuse this. In order to overrule this protection, add a '!' to the command. The changes will then be lost. For example: ":q" will not work if the buffer was changed, but ":q!" will. To see whether the buffer was changed use the "CTRL-G" command. The message includes -the string "[Modified]" if the buffer has been changed. +the string "[Modified]" if the buffer has been changed, or "+" if the 'm' flag +is in 'shortmess'. If you want to automatically save the changes without asking, switch on the 'autowriteall' option. 'autowrite' is the associated Vi-compatible option diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 5540c993f6..911fe43819 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -12,23 +12,7 @@ Note: Expression evaluation can be disabled at compile time. If this has been done, the features in this document are not available. See |+eval| and |no-eval-feature|. -1. Variables |variables| - 1.1 Variable types - 1.2 Function references |Funcref| - 1.3 Lists |Lists| - 1.4 Dictionaries |Dictionaries| - 1.5 More about variables |more-variables| -2. Expression syntax |expression-syntax| -3. Internal variable |internal-variables| -4. Builtin Functions |functions| -5. Defining functions |user-functions| -6. Curly braces names |curly-braces-names| -7. Commands |expression-commands| -8. Exception handling |exception-handling| -9. Examples |eval-examples| -10. No +eval feature |no-eval-feature| -11. The sandbox |eval-sandbox| -12. Textlock |textlock| + Type <M-]> to see the table of contents. ============================================================================== 1. Variables *variables* @@ -38,7 +22,7 @@ done, the features in this document are not available. See |+eval| and There are six types of variables: Number A 32 or 64 bit signed number. |expr-number| *Number* - Examples: -123 0x10 0177 + Examples: -123 0x10 0177 0b1011 Float A floating point number. |floating-point-format| *Float* Examples: 123.456 1.15e-6 -1.1e3 @@ -107,7 +91,7 @@ To test for a non-empty string, use empty(): > *non-zero-arg* Function arguments often behave slightly different from |TRUE|: If the argument is present and it evaluates to a non-zero Number, |v:true| or a -non-empty String, then the value is considere to be TRUE. +non-empty String, then the value is considered to be TRUE. Note that " " and "0" are also non-empty strings, thus cause the mode to be cleared. A List, Dictionary or Float is not a Number or String, thus evaluates to FALSE. @@ -394,10 +378,6 @@ This works like: > : let index = index + 1 :endwhile -Note that all items in the list should be of the same type, otherwise this -results in error |E706|. To avoid this |:unlet| the variable at the end of -the loop. - If all you want to do is modify each item in the list then the |map()| function will be a simpler method than a for loop. @@ -631,13 +611,17 @@ It's possible to form a variable name with curly braces, see Expression syntax summary, from least to most significant: -|expr1| expr2 ? expr1 : expr1 if-then-else +|expr1| expr2 + expr2 ? expr1 : expr1 if-then-else -|expr2| expr3 || expr3 .. logical OR +|expr2| expr3 + expr3 || expr3 .. logical OR -|expr3| expr4 && expr4 .. logical AND +|expr3| expr4 + expr4 && expr4 .. logical AND -|expr4| expr5 == expr5 equal +|expr4| expr5 + expr5 == expr5 equal expr5 != expr5 not equal expr5 > expr5 greater than expr5 >= expr5 greater than or equal @@ -654,24 +638,28 @@ Expression syntax summary, from least to most significant: expr5 is expr5 same |List| instance expr5 isnot expr5 different |List| instance -|expr5| expr6 + expr6 .. number addition or list concatenation +|expr5| expr6 + expr6 + expr6 .. number addition or list concatenation expr6 - expr6 .. number subtraction expr6 . expr6 .. string concatenation -|expr6| expr7 * expr7 .. number multiplication +|expr6| expr7 + expr7 * expr7 .. number multiplication expr7 / expr7 .. number division expr7 % expr7 .. number modulo -|expr7| ! expr7 logical NOT +|expr7| expr8 + ! expr7 logical NOT - expr7 unary minus + expr7 unary plus -|expr8| expr8[expr1] byte of a String or item of a |List| +|expr8| expr9 + expr8[expr1] byte of a String or item of a |List| expr8[expr1 : expr1] substring of a String or sublist of a |List| expr8.name entry in a |Dictionary| expr8(expr1, ...) function call with |Funcref| variable -|expr9| number number constant +|expr9| number number constant "string" string constant, backslash is special 'string' string constant, ' is doubled [expr1, ...] |List| @@ -931,7 +919,7 @@ expr8[expr1] item of String or |List| *expr-[]* *E111* If expr8 is a Number or String this results in a String that contains the expr1'th single byte from expr8. expr8 is used as a String, expr1 as a -Number. This doesn't recognize multi-byte encodings, see |byteidx()| for +Number. This doesn't recognize multi-byte encodings, see `byteidx()` for an alternative, or use `split()` to turn the string into a list of characters. Index zero gives the first byte. This is like it works in C. Careful: @@ -1022,9 +1010,10 @@ When expr8 is a |Funcref| type variable, invoke the function it refers to. number ------ number number constant *expr-number* - *hex-number* *octal-number* + *hex-number* *octal-number* *binary-number* -Decimal, Hexadecimal (starting with 0x or 0X), or Octal (starting with 0). +Decimal, Hexadecimal (starting with 0x or 0X), Binary (starting with 0b or 0B) +and Octal (starting with 0). *floating-point-format* Floating point numbers can be written in two forms: @@ -1213,8 +1202,8 @@ The arguments are optional. Example: > < error function *closure* Lambda expressions can access outer scope variables and arguments. This is -often called a closure. Example where "i" a and "a:arg" are used in a lambda -while they exists in the function scope. They remain valid even after the +often called a closure. Example where "i" and "a:arg" are used in a lambda +while they exist in the function scope. They remain valid even after the function returns: > :function Foo(arg) : let i = 3 @@ -1232,7 +1221,7 @@ Examples for using a lambda expression with |sort()|, |map()| and |filter()|: > :echo sort([3,7,2,1,4], {a, b -> a - b}) < [1, 2, 3, 4, 7] -The lambda expression is also useful for Channel, Job and timer: > +The lambda expression is also useful for jobs and timers: > :let timer = timer_start(500, \ {-> execute("echo 'Handler called'", "")}, \ {'repeat': 3}) @@ -1296,7 +1285,8 @@ b:changedtick The total number of changes to the current buffer. It is : let my_changedtick = b:changedtick : call My_Update() :endif -< +< You cannot change or delete the b:changedtick variable. + *window-variable* *w:var* *w:* A variable name that is preceded with "w:" is local to the current window. It is deleted when the window is closed. @@ -1425,8 +1415,8 @@ v:beval_winnr The number of the window, over which the mouse pointer is. Only window gets a number). *v:beval_winid* *beval_winid-variable* -v:beval_winid The window ID of the window, over which the mouse pointer is. - Otherwise like v:beval_winnr. +v:beval_winid The |window-ID| of the window, over which the mouse pointer + is. Otherwise like v:beval_winnr. *v:char* *char-variable* v:char Argument for evaluating 'formatexpr' and used for the typed @@ -1524,13 +1514,18 @@ v:errors Errors found by assert functions, such as |assert_true()|. list by the assert function. *v:event* *event-variable* -v:event Dictionary of event data for the current |autocommand|. The - available keys differ per event type and are specified at the - documentation for each |event|. The possible keys are: - operator The operation performed. Unlike - |v:operator|, it is set also for an Ex - mode command. For instance, |:yank| is - translated to "|y|". +v:event Dictionary of event data for the current |autocommand|. Valid + only during the autocommand lifetime: storing or passing + `v:event` is invalid. Copy it instead: > + au TextYankPost * let g:foo = deepcopy(v:event) +< Keys vary by event; see the documentation for the specific + event, e.g. |TextYankPost|. + KEY DESCRIPTION ~ + operator The current |operator|. Also set for + Ex commands (unlike |v:operator|). For + example if |TextYankPost| is triggered + by the |:yank| Ex command then + `v:event['operator']` is "y". regcontents Text stored in the register as a |readfile()|-style list of lines. regname Requested register (e.g "x" for "xyy) @@ -1681,7 +1676,7 @@ v:mouse_win Window number for a mouse click obtained with |getchar()|. zero when there was no mouse button click. *v:mouse_winid* *mouse_winid-variable* -v:mouse_winid Window ID for a mouse click obtained with |getchar()|. +v:mouse_winid |window-ID| for a mouse click obtained with |getchar()|. The value is zero when there was no mouse button click. *v:mouse_lnum* *mouse_lnum-variable* @@ -1917,9 +1912,10 @@ v:vim_did_enter Zero until most of startup is done. It is set to one just v:warningmsg Last given warning message. It's allowed to set this variable. *v:windowid* *windowid-variable* -v:windowid Application-specific window ID ("window handle" in MS-Windows) - which may be set by any attached UI. Defaults to zero. - Note: for windows inside Vim use |winnr()| or |win_getid()|. +v:windowid Application-specific window "handle" which may be set by any + attached UI. Defaults to zero. + Note: For Nvim |windows| use |winnr()| or |win_getid()|, see + |window-ID|. ============================================================================== 4. Builtin Functions *functions* @@ -1947,7 +1943,7 @@ assert_exception( {error} [, {msg}]) none assert {error} is in v:exception assert_fails( {cmd} [, {error}]) none assert {cmd} fails assert_false({actual} [, {msg}]) none assert {actual} is false assert_inrange({lower}, {upper}, {actual} [, {msg}]) - none assert {actual} is inside the range + none assert {actual} is inside the range assert_match( {pat}, {text} [, {msg}]) none assert {pat} matches {text} assert_notequal( {exp}, {act} [, {msg}]) none assert {exp} is not equal {act} assert_notmatch( {pat}, {text} [, {msg}]) none assert {pat} not matches {text} @@ -1963,7 +1959,7 @@ buflisted({expr}) Number |TRUE| if buffer {expr} is listed bufloaded({expr}) Number |TRUE| if buffer {expr} is loaded bufname({expr}) String Name of the buffer {expr} bufnr({expr} [, {create}]) Number Number of the buffer {expr} -bufwinid({expr}) Number window ID of buffer {expr} +bufwinid({expr}) Number |window-ID| of buffer {expr} bufwinnr({expr}) Number window number of buffer {expr} byte2line({byte}) Number line number at byte count {byte} byteidx({expr}, {nr}) Number byte index of {nr}'th char in {expr} @@ -1986,7 +1982,7 @@ cos({expr}) Float cosine of {expr} cosh({expr}) Float hyperbolic cosine of {expr} count({list}, {expr} [, {ic} [, {start}]]) Number count how many {expr} are in {list} -cscope_connection([{num} , {dbpath} [, {prepend}]]) +cscope_connection([{num}, {dbpath} [, {prepend}]]) Number checks existence of cscope connection cursor({lnum}, {col} [, {off}]) Number move cursor to {lnum}, {col}, {off} @@ -2016,8 +2012,8 @@ expand({expr} [, {nosuf} [, {list}]]) feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer filereadable({file}) Number |TRUE| if {file} is a readable file filewritable({file}) Number |TRUE| if {file} is a writable file -filter({expr}, {string}) List/Dict remove items from {expr} where - {string} is 0 +filter({expr1}, {expr2}) List/Dict remove items from {expr1} where + {expr2} is 0 finddir({name}[, {path}[, {count}]]) String find directory {name} in {path} findfile({name}[, {path}[, {count}]]) @@ -2041,7 +2037,7 @@ garbagecollect([{atexit}]) none free memory, breaking cyclic references get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def} get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def} get({func}, {what}) any get property of funcref/partial {func} -getbufinfo( [{expr}]) List information about buffers +getbufinfo([{expr}]) List information about buffers getbufline({expr}, {lnum} [, {end}]) List lines {lnum} to {end} of buffer {expr} getbufvar({expr}, {varname} [, {def}]) @@ -2141,7 +2137,7 @@ localtime() Number current time log({expr}) Float natural logarithm (base e) of {expr} log10({expr}) Float logarithm of Float {expr} to base 10 luaeval({expr}[, {expr}]) any evaluate Lua expression -map({expr}, {string}) List/Dict change each item in {expr} to {expr} +map({expr1}, {expr2}) List/Dict change each item in {expr1} to {expr} maparg({name}[, {mode} [, {abbr} [, {dict}]]]) String or Dict rhs of mapping {name} in mode {mode} @@ -2163,8 +2159,8 @@ matchstr({expr}, {pat}[, {start}[, {count}]]) String {count}'th match of {pat} in {expr} matchstrpos({expr}, {pat}[, {start}[, {count}]]) List {count}'th match of {pat} in {expr} -max({list}) Number maximum value of items in {list} -min({list}) Number minimum value of items in {list} +max({expr}) Number maximum value of items in {expr} +min({expr}) Number minimum value of items in {expr} mkdir({name} [, {path} [, {prot}]]) Number create directory {name} mode([expr]) String current editing mode @@ -2298,9 +2294,12 @@ tan({expr}) Float tangent of {expr} tanh({expr}) Float hyperbolic tangent of {expr} tempname() String name for a temporary file test_garbagecollect_now() none free memory right now for testing +timer_info([{id}]) List information about timers +timer_pause({id}, {pause}) none pause or unpause a timer timer_start({time}, {callback} [, {options}]) Number create a timer timer_stop({timer}) none stop a timer +timer_stopall() none stop all timers tolower({expr}) String the String {expr} switched to lowercase toupper({expr}) String the String {expr} switched to uppercase tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr} @@ -2316,10 +2315,10 @@ virtcol({expr}) Number screen column of cursor or mark visualmode([expr]) String last visual mode used wildmenumode() Number whether 'wildmenu' mode is active win_findbuf({bufnr}) List find windows containing {bufnr} -win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab} -win_gotoid({expr}) Number go to window with ID {expr} -win_id2tabwin({expr}) List get tab and window nr from window ID -win_id2win({expr}) Number get window nr from window ID +win_getid([{win} [, {tab}]]) Number get |window-ID| for {win} in {tab} +win_gotoid({expr}) Number go to |window-ID| {expr} +win_id2tabwin({expr}) List get tab and window nr from |window-ID| +win_id2win({expr}) Number get window nr from |window-ID| winbufnr({nr}) Number buffer number of window {nr} wincol() Number window column of the cursor winheight({nr}) Number height of window {nr} @@ -2410,7 +2409,7 @@ arglistid([{winnr} [, {tabnr}]]) With {winnr} only use this window in the current tab page. With {winnr} and {tabnr} use the window in the specified tab page. - {winnr} can be the window number or the window ID. + {winnr} can be the window number or the |window-ID|. *argv()* argv([{nr}]) The result is the {nr}th file in the argument list of the @@ -2456,7 +2455,7 @@ assert_exception({error} [, {msg}]) *assert_exception()* assert_fails({cmd} [, {error}]) *assert_fails()* Run {cmd} and add an error message to |v:errors| if it does NOT produce an error. - When {error} is given it must match |v:errmsg|. + When {error} is given it must match in |v:errmsg|. assert_false({actual} [, {msg}]) *assert_false()* When {actual} is not false an error message is added to @@ -2645,7 +2644,7 @@ bufnr({expr} [, {create}]) them. Use bufexists() to test for the existence of a buffer. bufwinid({expr}) *bufwinid()* - The result is a Number, which is the window ID of the first + The result is a Number, which is the |window-ID| of the first window associated with buffer {expr}. For the use of {expr}, see |bufname()| above. If buffer {expr} doesn't exist or there is no such window, -1 is returned. Example: > @@ -3035,6 +3034,8 @@ delete({fname} [, {flags}]) *delete()* When {flags} is "rf": Deletes the directory by the name {fname} and everything in it, recursively. BE CAREFUL! + Note: on MS-Windows it is not possible to delete a directory + that is being used. The result is a Number, which is 0 if the delete operation was successful and -1 when the deletion failed or partly failed. @@ -3199,8 +3200,12 @@ exepath({expr}) *exepath()* *exists()* exists({expr}) The result is a Number, which is |TRUE| if {expr} is - defined, zero otherwise. The {expr} argument is a string, - which contains one of these: + defined, zero otherwise. + + For checking for a supported feature use |has()|. + For checking if a file exists use |filereadable()|. + + The {expr} argument is a string, which contains one of these: &option-name Vim option (only checks if it exists, not if it really works) +option-name Vim option that works. @@ -3248,7 +3253,6 @@ exists({expr}) The result is a Number, which is |TRUE| if {expr} is event and pattern. ##event autocommand for this event is supported. - For checking for a supported feature use |has()|. Examples: > exists("&mouse") @@ -3466,9 +3470,10 @@ filter({expr1}, {expr2}) *filter()* is zero remove the item from the |List| or |Dictionary|. {expr2} must be a |string| or |Funcref|. - if {expr2} is a |string|, inside {expr2} |v:val| has the value + If {expr2} is a |string|, inside {expr2} |v:val| has the value of the current item. For a |Dictionary| |v:key| has the key - of the current item. + of the current item and for a |List| |v:key| has the index of + the current item. For a |Dictionary| |v:key| has the key of the current item. Examples: > call filter(mylist, 'v:val !~ "OLD"') @@ -3491,6 +3496,10 @@ filter({expr1}, {expr2}) *filter()* return a:idx % 2 == 1 endfunc call filter(mylist, function('Odd')) +< It is shorter when using a |lambda|: > + call filter(myList, {idx, val -> idx * val <= 42}) +< If you do not use "val" you can leave it out: > + call filter(myList, {idx -> idx % 2 == 1}) < The operation is done in-place. If you want a |List| or |Dictionary| to remain unmodified make a copy first: > @@ -4061,7 +4070,7 @@ getcwd([{winnr}[, {tabnr}]]) *getcwd()* getcwd(0) getcwd(0, 0) < If {winnr} is -1 it is ignored, only the tab is resolved. - {winnr} can be the window number or the window ID. + {winnr} can be the window number or the |window-ID|. getfsize({fname}) *getfsize()* @@ -4156,7 +4165,7 @@ getline({lnum} [, {end}]) getloclist({nr},[, {what}]) *getloclist()* Returns a list with all the entries in the location list for - window {nr}. {nr} can be the window number or the window ID. + window {nr}. {nr} can be the window number or the |window-ID|. When {nr} is zero the current window is used. For a location list window, the displayed location list is @@ -4231,7 +4240,7 @@ getqflist([{what}]) *getqflist()* type type of the error, 'E', '1', etc. valid |TRUE|: recognized error message - When there is no error list or it's empty an empty list is + When there is no error list or it's empty, an empty list is returned. Quickfix list entries with non-existing buffer number are returned with "bufnr" set to zero. @@ -4246,8 +4255,8 @@ getqflist([{what}]) *getqflist()* returns only the items listed in {what} as a dictionary. The following string items are supported in {what}: nr get information for this quickfix list - title get list title - winid get window id (if opened) + title get the list title + winid get the |window-ID| (if opened) all all of the above quickfix properties Non-string items in {what} are ignored. If "nr" is not present then the current quickfix list is used. @@ -4257,7 +4266,7 @@ getqflist([{what}]) *getqflist()* The returned dictionary contains the following entries: nr quickfix list number title quickfix list title text - winid quickfix window id (if opened) + winid quickfix |window-ID| (if opened) Examples: > :echo getqflist({'all': 1}) @@ -4268,7 +4277,7 @@ getreg([{regname} [, 1 [, {list}]]]) *getreg()* The result is a String, which is the contents of register {regname}. Example: > :let cliptext = getreg('*') -< When {regname} was not set the result is a empty string. +< When {regname} was not set the result is an empty string. getreg('=') returns the last evaluated value of the expression register. (For use in maps.) @@ -4304,10 +4313,10 @@ gettabinfo([{arg}]) *gettabinfo()* empty List is returned. Each List item is a Dictionary with the following entries: - nr tab page number. + tabnr tab page number. variables a reference to the dictionary with tabpage-local variables - windows List of window IDs in the tag page. + windows List of |window-ID|s in the tag page. gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()* Get the value of a tab-local variable {varname} in tab page @@ -4331,7 +4340,7 @@ gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* Note that {varname} must be the name without "w:". Tabs are numbered starting with one. For the current tabpage use |getwinvar()|. - {winnr} can be the window number or the window ID. + {winnr} can be the window number or the |window-ID|. When {winnr} is zero the current window is used. This also works for a global option, buffer-local option and window-local option, but it doesn't work for a global variable @@ -4359,20 +4368,20 @@ getwininfo([{winid}]) *getwininfo()* is returned. If the window does not exist the result is an empty list. - Without an information about all the windows in all the tab - pages is returned. + Without {winid} information about all the windows in all the + tab pages is returned. Each List item is a Dictionary with the following entries: - bufnum number of buffer in the window + bufnr number of buffer in the window height window height loclist 1 if showing a location list - nr window number quickfix 1 if quickfix or location list window - tpnr tab page number + tabnr tab page number variables a reference to the dictionary with window-local variables width window width - winid window ID + winid |window-ID| + winnr window number To obtain all window-local variables use: > gettabwinvar({tabnr}, {winnr}, '&') @@ -4476,9 +4485,8 @@ has_key({dict}, {key}) *has_key()* an entry with key {key}. Zero otherwise. haslocaldir([{winnr}[, {tabnr}]]) *haslocaldir()* - The result is a Number, which is 1 when the specified tabpage - or window has a local path set via |:lcd| or |:tcd|, and - 0 otherwise. + The result is a Number, which is 1 when the tabpage or window + has set a local path via |:tcd| or |:lcd|, otherwise 0. Tabs and windows are identified by their respective numbers, 0 means current tab or window. Missing argument implies 0. @@ -4486,7 +4494,9 @@ haslocaldir([{winnr}[, {tabnr}]]) *haslocaldir()* haslocaldir() haslocaldir(0) haslocaldir(0, 0) -< {winnr} can be the window number or the window ID. +< With {winnr} use that window in the current tabpage. + With {winnr} and {tabnr} use the window in that tabpage. + {winnr} can be the window number or the |window-ID|. If {winnr} is -1 it is ignored, only the tab is resolved. hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()* @@ -4525,6 +4535,7 @@ histadd({history}, {item}) *histadd()* "expr" or "=" typed expression history "input" or "@" input line history "debug" or ">" debug command history + empty the current or last used history The {history} string does not need to be the whole name, one character is sufficient. If {item} does already exist in the history, it will be @@ -4848,16 +4859,18 @@ jobstart({cmd}[, {opts}]) {Nvim} *jobstart()* Spawns {cmd} as a job. If {cmd} is a |List| it is run directly. If {cmd} is a |String| it is processed like this: > :call jobstart(split(&shell) + split(&shellcmdflag) + ['{cmd}']) -< NOTE: This only shows the idea; see |shell-unquoting| before - constructing lists with 'shell' or 'shellcmdflag'. - - NOTE: On Windows if {cmd} is a List, cmd[0] must be a valid - executable (.exe, .com). If the executable is in $PATH it can - be called by name, with or without an extension: > - :call jobstart(['ping', 'neovim.io']) -< If it is a path (not a name), it must include the extension: > - :call jobstart(['System32\ping.exe', 'neovim.io']) -< +< (Only shows the idea; see |shell-unquoting| for full details.) + + NOTE: on Windows if {cmd} is a List: + - cmd[0] must be an executable (not a "built-in"). If it is + in $PATH it can be called by name, without an extension: > + :call jobstart(['ping', 'neovim.io']) +< If it is a full or partial path, extension is required: > + :call jobstart(['System32\ping.exe', 'neovim.io']) +< - {cmd} is collapsed to a string of quoted args as expected + by CommandLineToArgvW https://msdn.microsoft.com/bb776391 + unless cmd[0] is some form of "cmd.exe". + {opts} is a dictionary with these keys: on_stdout: stdout event handler (function name or |Funcref|) on_stderr: stderr event handler (function name or |Funcref|) @@ -5128,6 +5141,10 @@ map({expr1}, {expr2}) *map()* return a:key . '-' . a:val endfunc call map(myDict, function('KeyValue')) +< It is shorter when using a |lambda|: > + call map(myDict, {key, val -> key . '-' . val}) +< If you do not use "val" you can leave it out: > + call map(myDict, {key -> 'item: ' . key}) < The operation is done in-place. If you want a |List| or |Dictionary| to remain unmodified make a copy first: > @@ -5334,7 +5351,8 @@ matchadd({group}, {pattern}[, {priority}[, {id} [, {dict}]]]) available from |getmatches()|. All matches can be deleted in one operation by |clearmatches()|. -matchaddpos({group}, {pos}[, {priority}[, {id}[, {dict}]]]) *matchaddpos()* + *matchaddpos()* +matchaddpos({group}, {pos}[, {priority}[, {id}[, {dict}]]]) Same as |matchadd()|, but requires a list of positions {pos} instead of a pattern. This command is faster than |matchadd()| because it does not require to handle regular expressions and @@ -5448,16 +5466,20 @@ matchstrpos({expr}, {pat}[, {start}[, {count}]]) *matchstrpos()* The type isn't changed, it's not necessarily a String. *max()* -max({list}) Return the maximum value of all items in {list}. - If {list} is not a list or one of the items in {list} cannot - be used as a Number this results in an error. - An empty |List| results in zero. +max({expr}) Return the maximum value of all items in {expr}. + {expr} can be a list or a dictionary. For a dictionary, + it returns the maximum of all values in the dictionary. + If {expr} is neither a list nor a dictionary, or one of the + items in {expr} cannot be used as a Number this results in + an error. An empty |List| or |Dictionary| results in zero. *min()* -min({list}) Return the minimum value of all items in {list}. - If {list} is not a list or one of the items in {list} cannot - be used as a Number this results in an error. - An empty |List| results in zero. +min({expr}) Return the minimum value of all items in {expr}. + {expr} can be a list or a dictionary. For a dictionary, + it returns the minimum of all values in the dictionary. + If {expr} is neither a list nor a dictionary, or one of the + items in {expr} cannot be used as a Number this results in + an error. An empty |List| or |Dictionary| results in zero. *mkdir()* *E739* mkdir({name} [, {path} [, {prot}]]) @@ -5693,7 +5715,7 @@ printf({fmt}, {expr1} ...) *printf()* %e floating point number as 1.23e3, inf, -inf or nan %E floating point number as 1.23E3, INF, -INF or NAN %g floating point number, as %f or %e depending on value - %G floating point number, as %f or %E depending on value + %G floating point number, as %F or %E depending on value %% the % character itself %p representation of the pointer to the container @@ -5804,6 +5826,9 @@ printf({fmt}, {expr1} ...) *printf()* s The text of the String argument is used. If a precision is specified, no more bytes than the number specified are used. + If the argument is not a String type, it is + automatically converted to text with the same format + as ":echo". *printf-S* S The text of the String argument is used. If a precision is specified, no more display cells than the @@ -6151,7 +6176,7 @@ rpcstop({channel}) {Nvim} *rpcstop()* connecting to |v:servername|. screenattr(row, col) *screenattr()* - Like screenchar(), but return the attribute. This is a rather + Like |screenchar()|, but return the attribute. This is a rather arbitrary number that can only be used to compare to the attribute at other positions. @@ -6527,7 +6552,7 @@ setline({lnum}, {text}) *setline()* setloclist({nr}, {list} [, {action}[, {what}]]) *setloclist()* Create or replace or add to the location list for window {nr}. - {nr} can be the window number or the window ID. + {nr} can be the window number or the |window-ID|. When {nr} is zero the current window is used. For a location list window, the displayed location list is @@ -6719,7 +6744,7 @@ settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()* {val}. Tabs are numbered starting with one. For the current tabpage use |setwinvar()|. - {winnr} can be the window number or the window ID. + {winnr} can be the window number or the |window-ID|. When {winnr} is zero the current window is used. This also works for a global or local buffer option, but it doesn't work for a global or local buffer variable. @@ -7025,7 +7050,7 @@ strcharpart({src}, {start}[, {len}]) *strcharpart()* Like |strpart()| but using character index and length instead of byte index and length. When a character index is used where a character does not - exist it is assumed to be one byte. For example: > + exist it is assumed to be one character. For example: > strcharpart('abc', -1, 2) < results in 'a'. @@ -7170,7 +7195,7 @@ strwidth({expr}) *strwidth()* Ambiguous, this function's return value depends on 'ambiwidth'. Also see |strlen()|, |strdisplaywidth()| and |strchars()|. -submatch({nr}[, {list}]) *submatch()* +submatch({nr}[, {list}]) *submatch()* *E935* Only for an expression in a |:substitute| command or substitute() function. Returns the {nr}'th submatch of the matched text. When {nr} @@ -7385,16 +7410,16 @@ systemlist({cmd} [, {input} [, {keepempty}]]) *systemlist()* output separated by NL) with NULs transformed into NLs. Output is the same as |readfile()| will output with {binary} argument set to "b", except that a final newline is not preserved, - unless {keepempty} is present and it's non-zero. + unless {keepempty} is non-zero. + Note that on MS-Windows you may get trailing CR characters. - Returns an empty string on error, so be careful not to run - into |E706|. + Returns an empty string on error. tabpagebuflist([{arg}]) *tabpagebuflist()* The result is a |List|, where each item is the number of the buffer associated with each window in the current tab page. - {arg} specifies the number of tab page to be used. When + {arg} specifies the number of the tab page to be used. When omitted the current tab page is used. When {arg} is invalid the number zero is returned. To get a list of all buffers in all tabs use this: > @@ -7525,7 +7550,36 @@ tanh({expr}) *tanh()* < -0.761594 - *timer_start()* + *timer_info()* +timer_info([{id}]) + Return a list with information about timers. + When {id} is given only information about this timer is + returned. When timer {id} does not exist an empty list is + returned. + When {id} is omitted information about all timers is returned. + + For each timer the information is stored in a Dictionary with + these items: + "id" the timer ID + "time" time the timer was started with + "repeat" number of times the timer will still fire; + -1 means forever + "callback" the callback + +timer_pause({timer}, {paused}) *timer_pause()* + Pause or unpause a timer. A paused timer does not invoke its + callback when its time expires. Unpausing a timer may cause + the callback to be invoked almost immediately if enough time + has passed. + + Pausing a timer is useful to avoid the callback to be called + for a short time. + + If {paused} evaluates to a non-zero Number or a non-empty + String, then the timer is paused, otherwise it is unpaused. + See |non-zero-arg|. + + *timer_start()* *timer* *timers* timer_start({time}, {callback} [, {options}]) Create a timer and return the timer ID. @@ -7534,13 +7588,14 @@ timer_start({time}, {callback} [, {options}]) busy or Vim is not waiting for input the time will be longer. {callback} is the function to call. It can be the name of a - function or a Funcref. It is called with one argument, which + function or a |Funcref|. It is called with one argument, which is the timer ID. The callback is only invoked when Vim is waiting for input. {options} is a dictionary. Supported entries: "repeat" Number of times to repeat calling the - callback. -1 means forever. + callback. -1 means forever. When not present + the callback will be called once. Example: > func MyHandler(timer) @@ -7554,7 +7609,12 @@ timer_start({time}, {callback} [, {options}]) timer_stop({timer}) *timer_stop()* Stop a timer. The timer callback will no longer be invoked. {timer} is an ID returned by timer_start(), thus it must be a - Number. + Number. If {timer} does not exist there is no error. + +timer_stopall() *timer_stopall()* + Stop all timers. The timer callbacks will no longer be + invoked. Useful if some timers is misbehaving. If there are + no timers there is no error. tolower({expr}) *tolower()* The result is a copy of the String given, with all uppercase @@ -7756,11 +7816,11 @@ wildmenumode() *wildmenumode()* win_findbuf({bufnr}) *win_findbuf()* - Returns a list with window IDs for windows that contain buffer - {bufnr}. When there is none the list is empty. + Returns a list with |window-ID|s for windows that contain + buffer {bufnr}. When there is none the list is empty. win_getid([{win} [, {tab}]]) *win_getid()* - Get the window ID for the specified window. + Get the |window-ID| for the specified window. When {win} is missing use the current window. With {win} this is the window number. The top window has number 1. @@ -7785,7 +7845,7 @@ win_id2win({expr}) *win_id2win()* *winbufnr()* winbufnr({nr}) The result is a Number, which is the number of the buffer associated with window {nr}. {nr} can be the window number or - the window ID. + the |window-ID|. When {nr} is zero, the number of the buffer in the current window is returned. When window {nr} doesn't exist, -1 is returned. @@ -7799,7 +7859,7 @@ wincol() The result is a Number, which is the virtual column of the winheight({nr}) *winheight()* The result is a Number, which is the height of window {nr}. - {nr} can be the window number or the window ID. + {nr} can be the window number or the |window-ID|. When {nr} is zero, the height of the current window is returned. When window {nr} doesn't exist, -1 is returned. An existing window always has a height of zero or more. @@ -7825,7 +7885,7 @@ winnr([{arg}]) The result is a Number, which is the number of the current is returned. The number can be used with |CTRL-W_w| and ":wincmd w" |:wincmd|. - Also see |tabpagewinnr()|. + Also see |tabpagewinnr()| and |win_getid()|. *winrestcmd()* winrestcmd() Returns a sequence of |:resize| commands that should restore @@ -7879,7 +7939,7 @@ winsaveview() Returns a |Dictionary| that contains information to restore winwidth({nr}) *winwidth()* The result is a Number, which is the width of window {nr}. - {nr} can be the window number or the window ID. + {nr} can be the window number or the |window-ID|. When {nr} is zero, the width of the current window is returned. When window {nr} doesn't exist, -1 is returned. An existing window always has a width of zero or more. @@ -8090,6 +8150,7 @@ timers Compiled with |timer_start()| support. title Compiled with window title support |'title'|. toolbar Compiled with support for |gui-toolbar|. unix Unix version of Vim. +unnamedplus Compiled with support for "unnamedplus" in 'clipboard' user_commands User-defined commands. vertsplit Compiled with vertically split windows |:vsplit|. vim_starting True while initial source'ing takes place. |startup| @@ -8584,6 +8645,11 @@ This does NOT work: > value and the global value are changed. Example: > :let &path = &path . ',/usr/local/include' +< This also works for terminal codes in the form t_xx. + But only for alphanumerical names. Example: > + :let &t_k1 = "\<Esc>[234;" +< When the code does not exist yet it will be created as + a terminal key code, there is no error. :let &{option-name} .= {expr1} For a string option: Append {expr1} to the value. diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt index 4c7360c88e..64d9c6daa9 100644 --- a/runtime/doc/filetype.txt +++ b/runtime/doc/filetype.txt @@ -6,12 +6,10 @@ Filetypes *filetype* *file-type* -1. Filetypes |filetypes| -2. Filetype plugin |filetype-plugins| -3. Docs for the default filetype plugins. |ftplugin-docs| - Also see |autocmd.txt|. + Type <M-]> to see the table of contents. + ============================================================================== 1. Filetypes *filetypes* *file-types* @@ -542,6 +540,7 @@ K or CTRL-] Jump to the manpage for the <cWORD> under the cursor. Takes a count for the section. CTRL-T Jump back to the location that the manpage was opened from. +META-] Show the manpage outline in the |location-list|. q :quit if invoked as $MANPAGER, otherwise :close. Variables: @@ -565,6 +564,17 @@ These maps can be disabled with > :let g:no_pdf_maps = 1 < +PYTHON *ft-python-plugin* *PEP8* + +By default the following options are set, in accordance with PEP8: > + + setlocal expandtab shiftwidth=4 softtabstop=4 tabstop=8 + +To disable this behaviour, set the following variable in your vimrc: > + + let g:python_recommended_style = 0 + + RPM SPEC *ft-spec-plugin* Since the text for this plugin is rather long it has been put in a separate diff --git a/runtime/doc/fold.txt b/runtime/doc/fold.txt index 4826a65d7b..88dde9f61d 100644 --- a/runtime/doc/fold.txt +++ b/runtime/doc/fold.txt @@ -9,10 +9,7 @@ Folding *Folding* *folding* *folds* You can find an introduction on folding in chapter 28 of the user manual. |usr_28.txt| -1. Fold methods |fold-methods| -2. Fold commands |fold-commands| -3. Fold options |fold-options| -4. Behavior of folds |fold-behavior| + Type <M-]> to see the table of contents. ============================================================================== 1. Fold methods *fold-methods* diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt index 4b89cd0d35..314799d083 100644 --- a/runtime/doc/gui.txt +++ b/runtime/doc/gui.txt @@ -6,34 +6,17 @@ Vim's Graphical User Interface *gui* *GUI* -1. Starting the GUI |gui-start| -2. Scrollbars |gui-scrollbars| -3. Mouse Control |gui-mouse| -4. Making GUI Selections |gui-selections| -5. Menus |menus| -6. Extras |gui-extras| - -Other GUI documentation: -|gui_w32.txt| For specific items of the Win32 GUI. + Type <M-]> to see the table of contents. ============================================================================== 1. Starting the GUI *gui-start* *E229* *E233* -First you must make sure you actually have a version of Vim with the GUI code -included. - -How to start the GUI depends on the system used. Mostly you can run the -GUI version of Vim with: - gvim [options] [files...] - *ginit.vim* *gui-init* *gvimrc* *$MYGVIMRC* The gvimrc file is where GUI-specific startup commands should be placed. It is always sourced after the |init.vim| file. If you have one then the $MYGVIMRC environment variable has its name. When the GUI starts up initializations are carried out, in this order: -- The 'term' option is set to "builtin_gui" and terminal options are reset to - their default value for the GUI |terminal-options|. - If the system menu file exists, it is sourced. The name of this file is normally "$VIMRUNTIME/menu.vim". You can check this with ":version". Also see |$VIMRUNTIME|. To skip loading the system menu include 'M' in @@ -92,8 +75,7 @@ and only the first one that is found is read. :winp[os] {X} {Y} *E466* Put the GUI vim window at the given {X} and {Y} coordinates. The coordinates should specify the position in pixels of the - top left corner of the window. Does not work in all versions. - Does work in an (new) xterm |xterm-color|. + top left corner of the window. When the GUI window has not been opened yet, the values are remembered until the window is opened. The position is adjusted to make the window fit on the screen (if possible). diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt index f71f46bad3..7cba0b9894 100644 --- a/runtime/doc/help.txt +++ b/runtime/doc/help.txt @@ -148,28 +148,22 @@ Special issues ~ GUI ~ |gui.txt| Graphical User Interface (GUI) -|gui_w32.txt| Win32 GUI Interfaces ~ |if_cscop.txt| using Cscope with Vim |if_pyth.txt| Python interface |if_ruby.txt| Ruby interface -|debugger.txt| Interface with a debugger |sign.txt| debugging signs Versions ~ |vim_diff.txt| Main differences between Nvim and Vim |vi_diff.txt| Main differences between Vim and Vi - *sys-file-list* -Remarks about specific systems ~ -|os_win32.txt| MS-Windows *standard-plugin-list* Standard plugins ~ |pi_gzip.txt| Reading and writing compressed files |pi_netrw.txt| Reading and writing files over a network |pi_paren.txt| Highlight matching parens |pi_tar.txt| Tar file explorer -|pi_vimball.txt| Create a self-installing Vim script |pi_zip.txt| Zip archive explorer LOCAL ADDITIONS: *local-additions* diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt index 6741efabd8..5948b24667 100644 --- a/runtime/doc/helphelp.txt +++ b/runtime/doc/helphelp.txt @@ -6,9 +6,7 @@ Help on help files *helphelp* -1. Help commands |online-help| -2. Translated help files |help-translated| -3. Writing help files |help-writing| + Type <M-]> to see the table of contents. ============================================================================== 1. Help commands *online-help* @@ -25,12 +23,20 @@ Help on help files *helphelp* The 'helplang' option is used to select a language, if the main help file is available in several languages. + Type <M-]> to see the table of contents. + *{subject}* *E149* *E661* :h[elp] {subject} Like ":help", additionally jump to the tag {subject}. - {subject} can include wildcards like "*", "?" and + For example: > + :help options + +< {subject} can include wildcards such as "*", "?" and "[a-z]": :help z? jump to help for any "z" command :help z. jump to the help for "z." + But when a tag exists it is taken literally: + :help :? jump to help for ":?" + If there is no full match for the pattern, or there are several matches, the "best" match will be used. A sophisticated algorithm is used to decide which @@ -67,18 +73,19 @@ Help on help files *helphelp* example to find help for CTRL-V in Insert mode: > :help i^V < - To use a regexp |pattern|, first do ":help" and then + It is also possible to first do ":help" and then use ":tag {pattern}" in the help window. The ":tnext" command can then be used to jump to other matches, "tselect" to list matches and choose one. > - :help index| :tse z. + :help index + :tselect /.*mode < When there is no argument you will see matches for "help", to avoid listing all possible matches (that would be very slow). The number of matches displayed is limited to 300. - This command can be followed by '|' and another + The `:help` command can be followed by '|' and another command, but you don't need to escape the '|' inside a help command. So these both work: > :help | diff --git a/runtime/doc/if_cscop.txt b/runtime/doc/if_cscop.txt index 3ce1575c99..831b2c9840 100644 --- a/runtime/doc/if_cscop.txt +++ b/runtime/doc/if_cscop.txt @@ -12,15 +12,7 @@ a cscope query is just like jumping to any tag; it is saved on the tag stack so that with the right keyboard mappings, you can jump back and forth between functions as you normally would with |tags|. -1. Cscope introduction |cscope-intro| -2. Cscope related commands |cscope-commands| -3. Cscope options |cscope-options| -4. How to use cscope in Vim |cscope-howtouse| -5. Limitations |cscope-limitations| -6. Suggested usage |cscope-suggestions| -7. Availability & Information |cscope-info| - -This is currently for Unix and Win32 only. + Type <M-]> to see the table of contents. ============================================================================== 1. Cscope introduction *cscope-intro* diff --git a/runtime/doc/if_pyth.txt b/runtime/doc/if_pyth.txt index 6321175420..25da033190 100644 --- a/runtime/doc/if_pyth.txt +++ b/runtime/doc/if_pyth.txt @@ -6,18 +6,10 @@ The Python Interface to Vim *python* *Python* -1. Commands |python-commands| -2. The vim module |python-vim| -3. Buffer objects |python-buffer| -4. Range objects |python-range| -5. Window objects |python-window| -6. Tab page objects |python-tabpage| -7. vim.bindeval objects |python-bindeval-objects| -8. pyeval(), py3eval() Vim functions |python-pyeval| -9. Python 3 |python3| - See |provider-python| for more information. {Nvim} + Type <M-]> to see the table of contents. + ============================================================================== 1. Commands *python-commands* @@ -48,7 +40,11 @@ Example: > print 'EAT ME' EOF endfunction -< + +To see what version of Python you have: > + :python import sys + :python print(sys.version) + Note: Python is very sensitive to the indenting. Make sure the "class" line and "EOF" do not have any indent. @@ -692,6 +688,10 @@ functions to evaluate Python expressions and pass their values to VimL. The `:py3` and `:python3` commands work similar to `:python`. A simple check if the `:py3` command is working: > :py3 print("Hello") + +To see what version of Python you have: > + :py3 import sys + :py3 print(sys.version) < *:py3file* The `:py3file` command works similar to `:pyfile`. *:py3do* diff --git a/runtime/doc/if_ruby.txt b/runtime/doc/if_ruby.txt index 2474039d82..54d81a958d 100644 --- a/runtime/doc/if_ruby.txt +++ b/runtime/doc/if_ruby.txt @@ -5,18 +5,13 @@ The Ruby Interface to Vim *ruby* *Ruby* - -1. Commands |ruby-commands| -2. The VIM module |ruby-vim| -3. VIM::Buffer objects |ruby-buffer| -4. VIM::Window objects |ruby-window| -5. Global variables |ruby-globals| - *E266* *E267* *E268* *E269* *E270* *E271* *E272* *E273* The home page for ruby is http://www.ruby-lang.org/. You can find links for downloading Ruby there. + Type <M-]> to see the table of contents. + ============================================================================== 1. Commands *ruby-commands* @@ -54,6 +49,9 @@ Example Vim script: > EOF endfunction < +To see what version of Ruby you have: > + :ruby print RUBY_VERSION +< *:rubydo* *:rubyd* *E265* :[range]rubyd[o] {cmd} Evaluate Ruby command {cmd} for each line in the diff --git a/runtime/doc/indent.txt b/runtime/doc/indent.txt index 4f4b39f559..8e17de3fb0 100644 --- a/runtime/doc/indent.txt +++ b/runtime/doc/indent.txt @@ -6,8 +6,7 @@ This file is about indenting C programs and other files. -1. Indenting C style programs |C-indenting| -2. Indenting by expression |indent-expression| + Type <M-]> to see the table of contents. ============================================================================== 1. Indenting C style programs *C-indenting* diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt index a1df0a265d..c15587cffd 100644 --- a/runtime/doc/index.txt +++ b/runtime/doc/index.txt @@ -10,22 +10,13 @@ short description. The lists are sorted on ASCII value. Tip: When looking for certain functionality, use a search command. E.g., to look for deleting something, use: "/delete". -1. Insert mode |insert-index| -2. Normal mode |normal-index| - 2.1. Text objects |objects| - 2.2. Window commands |CTRL-W| - 2.3. Square bracket commands |[| - 2.4. Commands starting with 'g' |g| - 2.5. Commands starting with 'z' |z| -3. Visual mode |visual-index| -4. Command-line editing |ex-edit-index| -5. EX commands |ex-cmd-index| - For an overview of options see help.txt |option-list|. For an overview of built-in functions see |functions|. For a list of Vim variables see |vim-variable|. For a complete listing of all help items see |help-tags|. + Type <M-]> to see the table of contents. + ============================================================================== 1. Insert mode *insert-index* @@ -982,7 +973,7 @@ tag command action in Command-line editing mode ~ |c_CTRL-E| CTRL-E cursor to end of command-line |'cedit'| CTRL-F default value for 'cedit': opens the command-line window; otherwise not used - CTRL-G not used +|c_CTRL-G| CTRL-G next match when 'incsearch' is active |c_<BS>| <BS> delete the character in front of the cursor |c_digraph| {char1} <BS> {char2} enter digraph when 'digraph' is on @@ -1000,7 +991,7 @@ tag command action in Command-line editing mode ~ |c_CTRL-L| CTRL-L do completion on the pattern in front of the cursor and insert the longest common part |c_<CR>| <CR> execute entered command -|c_<CR>| CTRL-M same as <CR> +|c_CTRL-M| CTRL-M same as <CR> |c_CTRL-N| CTRL-N after using 'wildchar' with multiple matches: go to next match, otherwise: same as <Down> CTRL-O not used @@ -1015,7 +1006,7 @@ tag command action in Command-line editing mode ~ insert the contents of a register or object under the cursor literally CTRL-S (used for terminal control flow) - CTRL-T not used +|c_CTRL-T| CTRL-T previous match when 'incsearch' is active |c_CTRL-U| CTRL-U remove all characters |c_CTRL-V| CTRL-V insert next non-digit literally, insert three digit decimal number as a single byte. @@ -1024,7 +1015,7 @@ tag command action in Command-line editing mode ~ CTRL-Y copy (yank) modeless selection CTRL-Z not used (reserved for suspend) |c_<Esc>| <Esc> abandon command-line without executing it -|c_<Esc>| CTRL-[ same as <Esc> +|c_CTRL-[| CTRL-[ same as <Esc> |c_CTRL-\_CTRL-N| CTRL-\ CTRL-N go to Normal mode, abandon command-line |c_CTRL-\_CTRL-G| CTRL-\ CTRL-G go to mode specified with 'insertmode', abandon command-line @@ -1202,7 +1193,7 @@ tag command action ~ |:display| :di[splay] display registers |:djump| :dj[ump] jump to #define |:dl| :dl short for |:delete| with the 'l' flag -|:dl| :del[ete]l short for |:delete| with the 'l' flag +|:del| :del[ete]l short for |:delete| with the 'l' flag |:dlist| :dli[st] list #defines |:doautocmd| :do[autocmd] apply autocommands to current buffer |:doautoall| :doautoa[ll] apply autocommands for all loaded buffers @@ -1234,6 +1225,7 @@ tag command action ~ |:file| :f[ile] show or set the current file name |:files| :files list all files in the buffer list |:filetype| :filet[ype] switch file type detection on/off +|:filter| :filt[er] filter output of following command |:find| :fin[d] find file in 'path' and edit it |:finally| :fina[lly] part of a :try command |:finish| :fini[sh] quit sourcing a Vim script diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt index 8b8c05c070..9219f45c83 100644 --- a/runtime/doc/insert.txt +++ b/runtime/doc/insert.txt @@ -13,20 +13,11 @@ commands for inserting text in other ways. An overview of the most often used commands can be found in chapter 24 of the user manual |usr_24.txt|. -1. Special keys |ins-special-keys| -2. Special special keys |ins-special-special| -3. 'textwidth' and 'wrapmargin' options |ins-textwidth| -4. 'expandtab', 'smarttab' and 'softtabstop' options |ins-expandtab| -5. Replace mode |Replace-mode| -6. Virtual Replace mode |Virtual-Replace-mode| -7. Insert mode completion |ins-completion| -8. Insert mode commands |inserting| -9. Ex insert commands |inserting-ex| -10. Inserting a file |inserting-file| - Also see 'virtualedit', for moving the cursor to positions where there is no character. Useful for editing a table. + Type <M-]> to see the table of contents. + ============================================================================== 1. Special keys *ins-special-keys* diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt index a5f9106bb0..f9e97c4c38 100644 --- a/runtime/doc/intro.txt +++ b/runtime/doc/intro.txt @@ -6,14 +6,7 @@ Introduction to Vim *ref* *reference* -1. Introduction |intro| -2. Vim on the internet |internet| -3. Credits |credits| -4. Notation |notation| -5. Modes, introduction |vim-modes-intro| -6. Switching from mode to mode |mode-switching| -7. The window contents |window-contents| -8. Definitions |definitions| + Type <M-]> to see the table of contents. ============================================================================== 1. Introduction *intro* @@ -34,11 +27,6 @@ It can be accessed from within Vim with the <Help> or <F1> key and with the is not located in the default place. You can jump to subjects like with tags: Use CTRL-] to jump to a subject under the cursor, use CTRL-T to jump back. -This manual refers to Vim on various machines. There may be small differences -between different computers and terminals. Besides the remarks given in this -document, there is a separate document for each supported system, see -|sys-file-list|. - *pronounce* Vim is pronounced as one word, like Jim, not vi-ai-em. It's written with a capital, since it's a name, again like Jim. @@ -92,21 +80,18 @@ mention that. *mail-list* *maillist* There are several mailing lists for Vim: -<vim@vim.org> +<vim@vim.org> *vim-use* *vim_use* For discussions about using existing versions of Vim: Useful mappings, questions, answers, where to get a specific version, etc. There are quite a few people watching this list and answering questions, also for beginners. Don't hesitate to ask your question here. -<vim-dev@vim.org> *vim-dev* *vimdev* +<vim-dev@vim.org> *vim-dev* *vim_dev* *vimdev* For discussions about changing Vim: New features, porting, patches, beta-test versions, etc. -<vim-announce@vim.org> *vim-announce* +<vim-announce@vim.org> *vim-announce* *vim_announce* Announcements about new versions of Vim; also for beta-test versions and ports to different systems. This is a read-only list. -<vim-multibyte@vim.org> *vim-multibyte* - For discussions about using and improving the multi-byte aspects of - Vim. -<vim-mac@vim.org> *vim-mac* +<vim-mac@vim.org> *vim-mac* *vim_mac* For discussions about using and improving the Macintosh version of Vim. @@ -131,10 +116,7 @@ http://www.vim.org/maillist.php Bug reports: *bugs* *bug-reports* *bugreport.vim* -Send bug reports to: Vim Developers <vim-dev@vim.org> -This is a maillist, you need to become a member first and many people will see -the message. If you don't want that, e.g. because it is a security issue, -send it to <bugs@vim.org>, this only goes to the Vim maintainer (that's Bram). +Report bugs on GitHub: https://github.com/neovim/neovim/issues Please be brief; all the time that is spent on answering mail is subtracted from the time that is spent on improving Vim! Always give a reproducible @@ -453,7 +435,6 @@ notation meaning equivalent decimal value(s) ~ <M-...> alt-key or meta-key *META* *meta* *alt* *<M-* <A-...> same as <M-...> *<A-* <D-...> command-key or "super" key *<D-* -<t_xx> key with "xx" entry in termcap ----------------------------------------------------------------------- Note: The shifted cursor keys, the help key, and the undo key are only @@ -488,7 +469,6 @@ the ":map" command. The rules are: <S-F11> Shifted function key 11 <M-a> Meta- a ('a' with bit 8 set) <M-A> Meta- A ('A' with bit 8 set) - <t_kd> "kd" termcap entry (cursor down key) The <> notation uses <lt> to escape the special meaning of key names. Using a backslash also works, but only when 'cpoptions' does not include the 'B' flag. diff --git a/runtime/doc/job_control.txt b/runtime/doc/job_control.txt index 40fd83b52c..5f9654d83c 100644 --- a/runtime/doc/job_control.txt +++ b/runtime/doc/job_control.txt @@ -6,8 +6,7 @@ Nvim's facilities for job control *job-control* -1. Introduction |job-control-intro| -2. Usage |job-control-usage| + Type <M-]> to see the table of contents. ============================================================================== 1. Introduction *job-control-intro* diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt index db349eca71..16c044a21d 100644 --- a/runtime/doc/map.txt +++ b/runtime/doc/map.txt @@ -9,21 +9,7 @@ Key mapping, abbreviations and user-defined commands. This subject is introduced in sections |05.3|, |24.7| and |40.1| of the user manual. -1. Key mapping |key-mapping| - 1.1 MAP COMMANDS |:map-commands| - 1.2 Special arguments |:map-arguments| - 1.3 Mapping and modes |:map-modes| - 1.4 Listing mappings |map-listing| - 1.5 Mapping special keys |:map-special-keys| - 1.6 Special characters |:map-special-chars| - 1.7 What keys to map |map-which-keys| - 1.8 Examples |map-examples| - 1.9 Using mappings |map-typing| - 1.10 Mapping alt-keys |:map-alt-keys| - 1.11 Mapping an operator |:map-operator| -2. Abbreviations |abbreviations| -3. Local mappings and functions |script-local| -4. User-defined commands |user-commands| + Type <M-]> to see the table of contents. ============================================================================== 1. Key mapping *key-mapping* *mapping* *macro* @@ -437,6 +423,9 @@ with a space. Note: When using mappings for Visual mode, you can use the "'<" mark, which is the start of the last selected Visual area in the current buffer |'<|. +The |:filter| command can be used to select what mappings to list. The +pattern is matched against the {lhs} and {rhs} in the raw form. + *:map-verbose* When 'verbose' is non-zero, listing a key map will also display where it was last defined. Example: > @@ -450,42 +439,30 @@ See |:verbose-cmd| for more information. 1.5 MAPPING SPECIAL KEYS *:map-special-keys* -There are three ways to map a special key: +There are two ways to map a special key: 1. The Vi-compatible method: Map the key code. Often this is a sequence that starts with <Esc>. To enter a mapping like this you type ":map " and then you have to type CTRL-V before hitting the function key. Note that when - the key code for the key is in the termcap (the t_ options), it will - automatically be translated into the internal code and become the second - way of mapping (unless the 'k' flag is included in 'cpoptions'). + the key code for the key is in the termcap, it will automatically be + translated into the internal code and become the second way of mapping + (unless the 'k' flag is included in 'cpoptions'). 2. The second method is to use the internal code for the function key. To enter such a mapping type CTRL-K and then hit the function key, or use the form "#1", "#2", .. "#9", "#0", "<Up>", "<S-Down>", "<S-F7>", etc. (see table of keys |key-notation|, all keys from <Up> can be used). The first ten function keys can be defined in two ways: Just the number, like "#2", and with "<F>", like "<F2>". Both stand for function key 2. "#0" - refers to function key 10, defined with option 't_f10', which may be - function key zero on some keyboards. The <> form cannot be used when - 'cpoptions' includes the '<' flag. -3. Use the termcap entry, with the form <t_xx>, where "xx" is the name of the - termcap entry. Any string entry can be used. For example: > - :map <t_F3> G -< Maps function key 13 to "G". This does not work if 'cpoptions' includes - the '<' flag. - -The advantage of the second and third method is that the mapping will work on -different terminals without modification (the function key will be -translated into the same internal code or the actual key code, no matter what -terminal you are using. The termcap must be correct for this to work, and you -must use the same mappings). + refers to function key 10. The <> form cannot be used when 'cpoptions' + includes the '<' flag. DETAIL: Vim first checks if a sequence from the keyboard is mapped. If it -isn't the terminal key codes are tried (see |terminal-options|). If a -terminal code is found it is replaced with the internal code. Then the check -for a mapping is done again (so you can map an internal code to something -else). What is written into the script file depends on what is recognized. -If the terminal key code was recognized as a mapping the key code itself is -written to the script file. If it was recognized as a terminal code the -internal code is written to the script file. +isn't the terminal key codes are tried. If a terminal code is found it is +replaced with the internal code. Then the check for a mapping is done again +(so you can map an internal code to something else). What is written into the +script file depends on what is recognized. If the terminal key code was +recognized as a mapping the key code itself is written to the script file. If +it was recognized as a terminal code the internal code is written to the +script file. 1.6 SPECIAL CHARACTERS *:map-special-chars* @@ -720,9 +697,6 @@ special key: > Don't type a real <Esc>, Vim will recognize the key code and replace it with <F1> anyway. -Another problem may be that when keeping ALT or Meta pressed the terminal -prepends ESC instead of setting the 8th bit. See |:map-alt-keys|. - *recursive_mapping* If you include the {lhs} in the {rhs} you have a recursive mapping. When {lhs} is typed, it will be replaced with {rhs}. When the {lhs} which is @@ -762,46 +736,14 @@ in the original Vi, you would get back the text before the first undo). 1.10 MAPPING ALT-KEYS *:map-alt-keys* -In the GUI Vim handles the Alt key itself, thus mapping keys with ALT should -always work. But in a terminal Vim gets a sequence of bytes and has to figure -out whether ALT was pressed or not. - -By default Vim assumes that pressing the ALT key sets the 8th bit of a typed -character. Most decent terminals can work that way, such as xterm, aterm and -rxvt. If your <A-k> mappings don't work it might be that the terminal is -prefixing the character with an ESC character. But you can just as well type -ESC before a character, thus Vim doesn't know what happened (except for -checking the delay between characters, which is not reliable). - -As of this writing, some mainstream terminals like gnome-terminal and konsole -use the ESC prefix. There doesn't appear a way to have them use the 8th bit -instead. Xterm should work well by default. Aterm and rxvt should work well -when started with the "--meta8" argument. You can also tweak resources like -"metaSendsEscape", "eightBitInput" and "eightBitOutput". - -On the Linux console, this behavior can be toggled with the "setmetamode" -command. Bear in mind that not using an ESC prefix could get you in trouble -with other programs. You should make sure that bash has the "convert-meta" -option set to "on" in order for your Meta keybindings to still work on it -(it's the default readline behavior, unless changed by specific system -configuration). For that, you can add the line: > - - set convert-meta on - -to your ~/.inputrc file. If you're creating the file, you might want to use: > - - $include /etc/inputrc - -as the first line, if that file exists on your system, to keep global options. -This may cause a problem for entering special characters, such as the umlaut. -Then you should use CTRL-V before that character. - -Bear in mind that convert-meta has been reported to have troubles when used in -UTF-8 locales. On terminals like xterm, the "metaSendsEscape" resource can be -toggled on the fly through the "Main Options" menu, by pressing Ctrl-LeftClick -on the terminal; that's a good last resource in case you want to send ESC when -using other applications but not when inside VIM. - +In the GUI Nvim handles the |ALT| key itself, thus mapping keys with ALT +should always work. But in a terminal Nvim gets a sequence of bytes and has +to figure out whether ALT was pressed. Terminals may use ESC to indicate that +ALT was pressed. If ESC is followed by a {key} within 'ttimeoutlen' +milliseconds, the ESC is interpreted as: + <ALT-{key}> +otherwise it is interpreted as two key presses: + <ESC> {key} 1.11 MAPPING AN OPERATOR *:map-operator* @@ -1171,6 +1113,10 @@ scripts. " Command has the -register attribute b Command is local to current buffer (see below for details on attributes) + The list can be filtered on command name with + |:filter|, e.g., to list all commands with "Pyth" in + the name: > + filter Pyth command :com[mand] {cmd} List the user-defined commands that start with {cmd} diff --git a/runtime/doc/mbyte.txt b/runtime/doc/mbyte.txt index 708c05e241..2e2ca92656 100644 --- a/runtime/doc/mbyte.txt +++ b/runtime/doc/mbyte.txt @@ -14,26 +14,10 @@ For an introduction to the most common features, see |usr_45.txt| in the user manual. For changing the language of messages and menus see |mlang.txt|. -{not available when compiled without the |+multi_byte| feature} - - -1. Getting started |mbyte-first| -2. Locale |mbyte-locale| -3. Encoding |mbyte-encoding| -4. Using a terminal |mbyte-terminal| -5. Fonts on X11 |mbyte-fonts-X11| -6. Fonts on MS-Windows |mbyte-fonts-MSwin| -7. Input on X11 |mbyte-XIM| -8. Input on MS-Windows |mbyte-IME| -9. Input with a keymap |mbyte-keymap| -10. Using UTF-8 |mbyte-utf8| -11. Overview of options |mbyte-options| - -NOTE: This file contains UTF-8 characters. These may show up as strange -characters or boxes when using another encoding. + Type <M-]> to see the table of contents. ============================================================================== -1. Getting started *mbyte-first* +Getting started *mbyte-first* This is a summary of the multibyte features in Vim. If you are lucky it works as described and you can start using Vim without much trouble. If something @@ -89,8 +73,7 @@ be displayed and edited correctly. For the GUI you must select fonts that work with UTF-8. This is the difficult part. It depends on the system you are using, the locale and -a few other things. See the chapters on fonts: |mbyte-fonts-X11| for -X-Windows and |mbyte-fonts-MSwin| for MS-Windows. +a few other things. For X11 you can set the 'guifontset' option to a list of fonts that together cover the characters that are used. Example for Korean: > @@ -120,7 +103,7 @@ The options 'iminsert', 'imsearch' and 'imcmdline' can be used to chose the different input methods or disable them temporarily. ============================================================================== -2. Locale *mbyte-locale* +Locale *mbyte-locale* The easiest setup is when your whole system uses the locale you want to work in. But it's also possible to set the locale for one shell you are working @@ -209,7 +192,7 @@ Or specify $LANG when starting Vim: You could make a small shell script for this. ============================================================================== -3. Encoding *mbyte-encoding* +Encoding *mbyte-encoding* In Nvim UTF-8 is always used internally to encode characters. This applies to all the places where text is used, including buffers (files @@ -418,49 +401,7 @@ neither of them can be found Vim will still work but some conversions won't be possible. ============================================================================== -4. Using a terminal *mbyte-terminal* - -The GUI fully supports multi-byte characters. It is also possible in a -terminal, if the terminal supports the same encoding that Vim uses. Thus this -is less flexible. - -For example, you can run Vim in a xterm with added multi-byte support and/or -|XIM|. Examples are kterm (Kanji term) and hanterm (for Korean), Eterm -(Enlightened terminal) and rxvt. - -UTF-8 IN XFREE86 XTERM *UTF8-xterm* - -This is a short explanation of how to use UTF-8 character encoding in the -xterm that comes with XFree86 by Thomas Dickey (text by Markus Kuhn). - -Get the latest xterm version which has now UTF-8 support: - - http://invisible-island.net/xterm/xterm.html - -Compile it with "./configure --enable-wide-chars ; make" - -Also get the ISO 10646-1 version of various fonts, which is available on - - http://www.cl.cam.ac.uk/~mgk25/download/ucs-fonts.tar.gz - -and install the font as described in the README file. - -Now start xterm with > - - xterm -u8 -fn -misc-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso10646-1 -or, for bigger character: > - xterm -u8 -fn -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso10646-1 - -and you will have a working UTF-8 terminal emulator. Try both > - - cat utf-8-demo.txt - vim utf-8-demo.txt - -with the demo text that comes with ucs-fonts.tar.gz in order to see -whether there are any problems with UTF-8 in your xterm. - -============================================================================== -5. Fonts on X11 *mbyte-fonts-X11* +Fonts on X11 *mbyte-fonts-X11* Unfortunately, using fonts in X11 is complicated. The name of a single-byte font is a long string. For multi-byte fonts we need several of these... @@ -596,20 +537,7 @@ Also make sure that you set 'guifontset' before setting fonts for highlight groups. ============================================================================== -6. Fonts on MS-Windows *mbyte-fonts-MSwin* - -The simplest is to use the font dialog to select fonts and try them out. You -can find this at the "Edit/Select Font..." menu. Once you find a font name -that works well you can use this command to see its name: > - - :set guifont - -Then add a command to your |ginit.vim| file to set 'guifont': > - - :set guifont=courier_new:h12 - -============================================================================== -7. Input on X11 *mbyte-XIM* +Input on X11 *mbyte-XIM* X INPUT METHOD (XIM) BACKGROUND *XIM* *xim* *x-input-method* @@ -768,7 +696,7 @@ For example, when you are using kinput2 as |IM-server| and sh, > < ============================================================================== -8. Input on MS-Windows *mbyte-IME* +Input on MS-Windows *mbyte-IME* (Windows IME support) *multibyte-ime* *IME* @@ -842,7 +770,7 @@ Cursor color when IME or XIM is on *CursorIM* status is on. ============================================================================== -9. Input with a keymap *mbyte-keymap* +Input with a keymap *mbyte-keymap* When the keyboard doesn't produce the characters you want to enter in your text, you can use the 'keymap' option. This will translate one or more @@ -1090,7 +1018,7 @@ Combining forms: ﭏ 0xfb4f Xal alef-lamed ============================================================================== -10. Using UTF-8 *mbyte-utf8* *UTF-8* *utf-8* *utf8* +Using UTF-8 *mbyte-utf8* *UTF-8* *utf-8* *utf8* *Unicode* *unicode* The Unicode character set was designed to include all characters from other character sets. Therefore it is possible to write text in any language using @@ -1222,7 +1150,7 @@ not everybody is able to type a composing character. ============================================================================== -11. Overview of options *mbyte-options* +Overview of options *mbyte-options* These options are relevant for editing multi-byte files. Check the help in options.txt for detailed information. diff --git a/runtime/doc/message.txt b/runtime/doc/message.txt index d0bdba41ab..c6c6f49026 100644 --- a/runtime/doc/message.txt +++ b/runtime/doc/message.txt @@ -8,9 +8,7 @@ This file contains an alphabetical list of messages and error messages that Vim produces. You can use this if you don't understand what the message means. It is not complete though. -1. Old messages |:messages| -2. Error messages |error-messages| -3. Messages |messages| + Type <M-]> to see the table of contents. ============================================================================== 1. Old messages *:messages* *:mes* *message-history* @@ -39,10 +37,7 @@ back. Note: If the output has been stopped with "q" at the more prompt, it will only be displayed up to this point. The previous command output is cleared when another command produces output. - -If you are using translated messages, the first printed line tells who -maintains the messages or the translations. You can use this to contact the -maintainer when you spot a mistake. +The "g<" output is not redirected. If you want to find help on a specific (error) message, use the ID at the start of the message. For example, to get help on the message: > @@ -127,8 +122,9 @@ closed properly. Mostly harmless. Command too recursive This happens when an Ex command executes an Ex command that executes an Ex -command, etc. This is only allowed 200 times. When it's more there probably -is an endless loop. Probably a |:execute| or |:source| command is involved. +command, etc. The limit is 200 or the value of 'maxfuncdepth', whatever is +larger. When it's more there probably is an endless loop. Probably a +|:execute| or |:source| command is involved. *E254* > Cannot allocate color {name} diff --git a/runtime/doc/mlang.txt b/runtime/doc/mlang.txt index 187d8f029b..717ec9530c 100644 --- a/runtime/doc/mlang.txt +++ b/runtime/doc/mlang.txt @@ -11,11 +11,7 @@ multi-byte text see |multibyte|. The basics are explained in the user manual: |usr_45.txt|. -1. Messages |multilang-messages| -2. Menus |multilang-menus| -3. Scripts |multilang-scripts| - -Also see |help-translated| for multi-language help. + Type <M-]> to see the table of contents. ============================================================================== 1. Messages *multilang-messages* diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt index a89fabe107..99aa76bfe5 100644 --- a/runtime/doc/motion.txt +++ b/runtime/doc/motion.txt @@ -10,16 +10,6 @@ These commands move the cursor position. If the new position is off of the screen, the screen is scrolled to show the cursor (see also 'scrolljump' and 'scrolloff' options). -1. Motions and operators |operator| -2. Left-right motions |left-right-motions| -3. Up-down motions |up-down-motions| -4. Word motions |word-motions| -5. Text object motions |object-motions| -6. Text object selection |object-select| -7. Marks |mark-motions| -8. Jumps |jump-motions| -9. Various motions |various-motions| - General remarks: If you want to know where you are in the file use the "CTRL-G" command @@ -36,6 +26,8 @@ The 'virtualedit' option can be set to make it possible to move the cursor to positions where there is no character or within a multi-column character (like a tab). + Type <M-]> to see the table of contents. + ============================================================================== 1. Motions and operators *operator* diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index 3f3c41f566..856476c6ae 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -6,12 +6,7 @@ RPC API for Nvim *RPC* *rpc* *msgpack-rpc* -1. Introduction |rpc-intro| -2. API mapping |rpc-api| -3. Connecting |rpc-connecting| -4. Clients |rpc-api-client| -5. Types |rpc-types| -6. Remote UIs |rpc-remote-ui| + Type <M-]> to see the table of contents. ============================================================================== 1. Introduction *rpc-intro* @@ -33,7 +28,7 @@ programs can: The RPC API is like a more powerful version of Vim's `clientserver` feature. ============================================================================== - 2. API mapping *rpc-api* +2. API mapping *rpc-api* The Nvim C |API| is automatically exposed to the RPC API by the build system, which parses headers at src/nvim/api/*. A dispatch function is generated which @@ -197,7 +192,7 @@ prefix is stripped off. 5. Types *rpc-types* The Nvim C API uses custom types for all functions. |api-types| -For the purpose of mapping to msgpack, the types can be split into two groups: +At the RPC layer, the types can be split into two groups: - Basic types that map natively to msgpack (and probably have a default representation in msgpack-supported programming languages) @@ -219,15 +214,16 @@ Special types (msgpack EXT) ~ Window -> enum value kObjectTypeWindow Tabpage -> enum value kObjectTypeTabpage -An API method expecting one of these types may be passed an integer instead, -although they are not interchangeable. For example, a Buffer may be passed as -an integer, but not a Window or Tabpage. +API functions expecting one of the special EXT types may be passed an integer +instead, but not another EXT type. E.g. Buffer may be passed as an integer but +not as a Window or Tabpage. The EXT object data is the object id encoded as +a msgpack integer: For buffers this is the |bufnr()| and for windows the +|window-ID|. For tabpages the id is an internal handle, not the tabpage +number. + +To determine the type codes of the special EXT types, inspect the `types` key +of the |api-metadata| at runtime. Example JSON representation: > -The most reliable way of determining the type codes for the special Nvim types -is to inspect the `types` key of metadata dictionary returned by the -`nvim_get_api_info` method at runtime. Here's a sample JSON representation of -the `types` object: -> "types": { "Buffer": { "id": 0, @@ -242,7 +238,7 @@ the `types` object: "prefix": "nvim_tabpage_" } } -< + Even for statically compiled clients it is good practice to avoid hardcoding the type codes, because a client may be built against one Nvim version but connect to another with different type codes. @@ -251,9 +247,9 @@ connect to another with different type codes. 6. Remote UIs *rpc-remote-ui* GUIs can be implemented as external processes communicating with Nvim over the -RPC API. Currently the UI model consists of a terminal-like grid with one -single, monospace font size. Some elements (UI "widgets") can be drawn -separately from the grid. +RPC API. The UI model consists of a terminal-like grid with a single, +monospace font size. Some elements (UI "widgets") can be drawn separately from +the grid ("externalized"). After connecting to Nvim (usually a spawned, embedded instance) use the |nvim_ui_attach| API method to tell Nvim that your program wants to draw the @@ -264,19 +260,24 @@ a dictionary with these (optional) keys: colors. Set to false to use terminal color codes (at most 256 different colors). - `popupmenu_external` Instead of drawing the completion popupmenu on - the grid, Nvim will send higher-level events to - the ui and let it draw the popupmenu. - Defaults to false. + `ext_popupmenu` Externalize the popupmenu. |ui-ext-popupmenu| + `ext_tabline` Externalize the tabline. |ui-ext-tabline| + Externalized widgets will not be drawn by + Nvim; only high-level data will be published + in new UI event kinds. Nvim will then send msgpack-rpc notifications, with the method name "redraw" -and a single argument, an array of screen updates (described below). -These should be processed in order. Preferably the user should only be able to -see the screen state after all updates are processed (not any intermediate -state after processing only a part of the array). +and a single argument, an array of screen updates (described below). These +should be processed in order. Preferably the user should only be able to see +the screen state after all updates in the same "redraw" event are processed +(not any intermediate state after processing only a part of the array). -Screen updates are arrays. The first element a string describing the kind -of update. +Future versions of Nvim may add new update kinds and may append new parameters +to existing update kinds. Clients must be prepared to ignore such extensions +to be forward-compatible. |api-contract| + +Screen updates are tuples whose first element is the string name of the update +kind. ["resize", width, height] The grid is resized to `width` and `height` cells. @@ -387,11 +388,33 @@ of update. ["update_menu"] The menu mappings changed. -["mode_change", mode] - The mode changed. Currently sent when "insert", "replace", "cmdline" and - "normal" modes are entered. A client could for instance change the cursor - shape. - +["mode_info_set", cursor_style_enabled, mode_info] +`cursor_style_enabled` is a boolean indicating if the UI should set the cursor +style. `mode_info` is a list of mode property maps. The current mode is given +by the `mode_idx` field of the `mode_change` event. + +Each mode property map may contain these keys: + KEY DESCRIPTION ~ + `cursor_shape`: "block", "horizontal", "vertical" + `cell_percentage`: Cell % occupied by the cursor. + `blinkwait`, `blinkon`, `blinkoff`: See |cursor-blinking|. + `hl_id`: Cursor highlight group. + `hl_lm`: Cursor highlight group if 'langmap' is active. + `short_name`: Mode code name, see 'guicursor'. + `name`: Mode descriptive name. + `mouse_shape`: (To be implemented.) + +Some keys are missing in some modes. + +["mode_change", mode, mode_idx] +The mode changed. The first parameter `mode` is a string representing the +current mode. `mode_idx` is an index into the array received in the +`mode_info_set` event. UIs should change the cursor style according to the +properties specified in the corresponding item. The set of modes reported will +change in new versions of Nvim, for instance more submodes and temporary +states might be represented as separate modes. + + *ui-ext-popupmenu* ["popupmenu_show", items, selected, row, col] When `popupmenu_external` is set to true, nvim will not draw the popupmenu on the grid, instead when the popupmenu is to be displayed @@ -411,5 +434,12 @@ of update. ["popupmenu_hide"] The popupmenu is hidden. + *ui-ext-tabline* +["tabline_update", curtab, tabs] + Tabline was updated. UIs should present this data in a custom tabline + widget. + curtab: Current Tabpage + tabs: List of Dicts [{ "tab": Tabpage, "name": String }, ...] + ============================================================================== vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt index bd483e9949..2256791ec4 100644 --- a/runtime/doc/nvim.txt +++ b/runtime/doc/nvim.txt @@ -4,23 +4,25 @@ NVIM REFERENCE MANUAL -Nvim *nvim* *nvim-intro* +Nvim *nvim* *nvim-intro* -If you are new to Vim (and Nvim) see |help.txt| or type ":Tutor". -If you already use Vim (but not Nvim) see |nvim-from-vim| for a quickstart. +If you are new to Vim see |help.txt|, or type ":Tutor". +If you already use Vim see |nvim-from-vim| for a quickstart. Nvim is emphatically a fork of Vim, not a clone: compatibility with Vim is maintained where possible. See |vim_diff.txt| for the complete reference of differences from Vim. + Type <M-]> to see the table of contents. + ============================================================================== Transitioning from Vim *nvim-from-vim* -To start the transition, link your previous configuration so Nvim can use it: +To start the transition, create `~/.config/nvim/init.vim` with these contents: > - mkdir ~/.config - ln -s ~/.vim ~/.config/nvim - ln -s ~/.vimrc ~/.config/nvim/init.vim + set runtimepath+=~/.vim,~/.vim/after + set packpath+=~/.vim + source ~/.vimrc < Note: If your system sets `$XDG_CONFIG_HOME`, use that instead of `~/.config` in the code above. Nvim follows the XDG |base-directories| convention. diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt index 85325d3470..9f448ae3ba 100644 --- a/runtime/doc/nvim_terminal_emulator.txt +++ b/runtime/doc/nvim_terminal_emulator.txt @@ -15,6 +15,8 @@ Terminal buffers behave mostly like normal 'nomodifiable' buffers, except: - 'scrollback' controls how many off-screen lines are kept. - Terminal output is followed if the cursor is on the last line. + Type <M-]> to see the table of contents. + ============================================================================== Spawning *terminal-emulator-spawning* diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index c30a88f48d..e72241518c 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -6,11 +6,7 @@ Options *options* -1. Setting options |set-option| -2. Automatically setting options |auto-setting| -3. Options summary |option-summary| - -For an overview of options see help.txt |option-list|. +For an overview of options see quickref.txt |option-list|. Vim has a number of internal variables and switches which can be set to achieve special effects. These options come in three forms: @@ -18,6 +14,8 @@ achieve special effects. These options come in three forms: number has a numeric value string has a string value + Type <M-]> to see the table of contents. + ============================================================================== 1. Setting options *set-option* *E764* @@ -130,39 +128,6 @@ A few special texts: Last set from error handler ~ Option was cleared when evaluating it resulted in an error. -{not available when compiled without the |+eval| feature} - - *:set-termcap* *E522* -For {option} the form "t_xx" may be used to set a terminal option. This will -override the value from the termcap. You can then use it in a mapping. If -the "xx" part contains special characters, use the <t_xx> form: > - :set <t_#4>=^[Ot -This can also be used to translate a special code for a normal key. For -example, if Alt-b produces <Esc>b, use this: > - :set <M-b>=^[b -(the ^[ is a real <Esc> here, use CTRL-V <Esc> to enter it) -The advantage over a mapping is that it works in all situations. - -You can define any key codes, e.g.: > - :set t_xy=^[foo; -There is no warning for using a name that isn't recognized. You can map these -codes as you like: > - :map <t_xy> something -< *E846* -When a key code is not set, it's like it does not exist. Trying to get its -value will result in an error: > - :set t_kb= - :set t_kb - E846: Key code not set: t_kb - -The t_xx options cannot be set from a |modeline| or in the |sandbox|, for -security reasons. - -The listing from ":set" looks different from Vi. Long string options are put -at the end of the list. The number of options is quite large. The output of -"set all" probably does not fit on the screen, causing Vim to give the -|more-prompt|. - *option-backslash* To include white space in a string option value it has to be preceded with a backslash. To include a backslash you have to use two. Effectively this @@ -628,7 +593,7 @@ A jump table for the options with a short description can be found at |Q_op|. See Unicode Standard Annex #11 (http://www.unicode.org/reports/tr11). Vim may set this option automatically at startup time when Vim is - compiled with the |+termresponse| feature and if |t_u7| is set to the + compiled with the |+termresponse| feature and if t_u7 is set to the escape sequence to request cursor position report. *'autochdir'* *'acd'* *'noautochdir'* *'noacd'* @@ -2092,7 +2057,7 @@ A jump table for the options with a short description can be found at |Q_op|. uhex Show unprintable characters hexadecimal as <xx> instead of using ^C and ~C. - When neither "lastline" or "truncate" is included, a last line that + When neither "lastline" nor "truncate" is included, a last line that doesn't fit is replaced with "@" lines. *'eadirection'* *'ead'* @@ -2219,10 +2184,15 @@ A jump table for the options with a short description can be found at |Q_op|. *'exrc'* *'ex'* *'noexrc'* *'noex'* 'exrc' 'ex' boolean (default off) global - Enables the reading of .nvimrc and .exrc in the current directory. - If you switch this option on you should also consider setting the - 'secure' option (see |initialization|). Using this option comes - with a potential security risk, use with care! + Enables the reading of .vimrc and .exrc in the current directory. + Setting this option is a potential security leak. E.g., consider + unpacking a package or fetching files from github, a .vimrc in there + might be a trojan horse. BETTER NOT SET THIS OPTION! + Instead, define an autocommand in your .vimrc to set options for a + matching directory. + + If you do switch this option on you should also consider setting the + 'secure' option (see |initialization|). This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. Also see |init.vim| and |gui-init|. @@ -2765,8 +2735,7 @@ A jump table for the options with a short description can be found at |Q_op|. *'grepprg'* *'gp'* 'grepprg' 'gp' string (default "grep -n ", - Unix: "grep -n $* /dev/null", - Win32: "findstr /n" or "grep -n") + Unix: "grep -n $* /dev/null") global or local to buffer |global-local| Program to use for the |:grep| command. This option may contain '%' and '#' characters, which are expanded like when used in a command- @@ -2781,29 +2750,28 @@ A jump table for the options with a short description can be found at |Q_op|. |:vimgrepadd| and |:lgrepadd| like |:lvimgrepadd|. See also the section |:make_makeprg|, since most of the comments there apply equally to 'grepprg'. - For Win32, the default is "findstr /n" if "findstr.exe" can be found, - otherwise it's "grep -n". This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. *'guicursor'* *'gcr'* *E545* *E546* *E548* *E549* -'guicursor' 'gcr' string (default "n-v-c:block-Cursor/lCursor, - ve:ver35-Cursor, - o:hor50-Cursor, - i-ci:ver25-Cursor/lCursor, - r-cr:hor20-Cursor/lCursor, - sm:block-Cursor - -blinkwait175-blinkoff150-blinkon175") +'guicursor' 'gcr' string (default "n-v-c-sm:block,i-ci-ve:ver25,r-cr-o:hor20") global Configures the cursor style for each mode. Works in the GUI and some - terminals. Unset to disable: > - :set guicursor= -< + terminals. + With tmux you might need this in ~/.tmux.conf (see terminal-overrides in the tmux(1) manual page): > set -ga terminal-overrides ',*:Ss=\E[%p1%d q:Se=\E[2 q' -< - The option is a comma separated list of parts. Each part consists of a + +< To disable cursor-styling, reset the option: > + :set guicursor= + +< To enable mode shapes, "Cursor" highlight, and blinking: > + :set guicursor=n-v-c:block,i-ci-ve:ver25,r-cr:hor20,o:hor50 + \,a:blinkwait700-blinkoff400-blinkon250-Cursor/lCursor + \,sm:block-blinkwait175-blinkoff150-blinkon175 + +< The option is a comma separated list of parts. Each part consists of a mode-list and an argument-list: mode-list:argument-list,mode-list:argument-list,.. The mode-list is a dash separated list of these modes: @@ -2831,16 +2799,9 @@ A jump table for the options with a short description can be found at |Q_op|. the cursor starts blinking, blinkon is the time that the cursor is shown and blinkoff is the time that the cursor is not shown. The times are in msec. When one - of the numbers is zero, there is no blinking. The - default is: "blinkwait700-blinkon400-blinkoff250". - These numbers are used for a missing entry. This - means that blinking is enabled by default. To switch - blinking off you can use "blinkon0". The cursor only - blinks when Vim is waiting for input, not while - executing a command. - To make the cursor blink in an xterm, see - |xterm-blink|. - {group-name} + of the numbers is zero, there is no blinking. E.g.: > + :set guicursor=n:blinkon0 +< {group-name} a highlight group name, that sets the color and font for the cursor {group-name}/{group-name} @@ -3429,6 +3390,8 @@ A jump table for the options with a short description can be found at |Q_op|. original position when no match is found and when pressing <Esc>. You still need to finish the search command with <Enter> to move the cursor to the match. + You can use the CTRL-G and CTRL-T keys to move to the next and + previous match. |c_CTRL-G| |c_CTRL-T| Vim only searches for about half a second. With a complicated pattern and/or a lot of text the match may not be found. This is to avoid that Vim hangs while you are typing the pattern. @@ -3502,7 +3465,7 @@ A jump table for the options with a short description can be found at |Q_op|. if you want to use Vim as a modeless editor. These Insert mode commands will be useful: - Use the cursor keys to move around. - - Use CTRL-O to execute one Normal mode command |i_CTRL-O|). When + - Use CTRL-O to execute one Normal mode command |i_CTRL-O|. When this is a mapping, it is executed as if 'insertmode' was off. Normal mode remains active until the mapping is finished. - Use CTRL-L to execute a number of Normal mode commands, then use @@ -3692,6 +3655,8 @@ A jump table for the options with a short description can be found at |Q_op|. be able to execute Normal mode commands. This is the opposite of the 'keymap' option, where characters are mapped in Insert mode. + Also consider resetting 'langremap' to avoid 'langmap' applies to + characters resulting from a mapping. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. @@ -3916,10 +3881,11 @@ A jump table for the options with a short description can be found at |Q_op|. global Changes the special characters that can be used in search patterns. See |pattern|. - NOTE: To avoid portability problems with using patterns, always keep - this option at the default "on". Only switch it off when working with - old Vi scripts. In any other situation write patterns that work when - 'magic' is on. Include "\M" when you want to |/\M|. + WARNING: Switching this option off most likely breaks plugins! That + is because many patterns assume it's on and will fail when it's off. + Only switch it off when working with old Vi scripts. In any other + situation write patterns that work when 'magic' is on. Include "\M" + when you want to |/\M|. *'makeef'* *'mef'* 'makeef' 'mef' string (default: "") @@ -4004,6 +3970,8 @@ A jump table for the options with a short description can be found at |Q_op|. catches endless recursion. When using a recursive function with more depth, set 'maxfuncdepth' to a bigger number. But this will use more memory, there is the danger of failing when memory is exhausted. + Increasing this limit above 200 also changes the maximum for Ex + command resursion, see |E169|. See also |:function|. *'maxmapdepth'* *'mmd'* *E223* @@ -4115,7 +4083,7 @@ A jump table for the options with a short description can be found at |Q_op|. local to buffer When off the buffer contents cannot be changed. The 'fileformat' and 'fileencoding' options also can't be changed. - Can be reset with the |-M| command line argument. + Can be reset on startup with the |-M| command line argument. *'modified'* *'mod'* *'nomodified'* *'nomod'* 'modified' 'mod' boolean (default off) @@ -4408,7 +4376,7 @@ A jump table for the options with a short description can be found at |Q_op|. *'paste'* *'nopaste'* 'paste' boolean (default off) global - You probably don't have to set this option: |bracketed-paste-mode|. + This option is obsolete; |bracketed-paste-mode| is built-in. Put Vim in Paste mode. This is useful if you want to cut or copy some text from one window and paste it in Vim. This will avoid @@ -4686,6 +4654,7 @@ A jump table for the options with a short description can be found at |Q_op|. buffer, unless the 'Z' flag is in 'cpoptions'. When using the ":view" command the 'readonly' option is set for the newly edited buffer. + See 'modifiable' for disallowing changes to the buffer. *'redrawtime'* *'rdt'* 'redrawtime' 'rdt' number (default 2000) @@ -4885,7 +4854,9 @@ A jump table for the options with a short description can be found at |Q_op|. ordering. This is for preferences to overrule or add to the distributed defaults or system-wide settings (rarely needed). - More entries are added when using |packages|. + More entries are added when using |packages|. If it gets very long + then `:set rtp` will be truncated, use `:echo &rtp` to see the full + string. Note that, unlike 'path', no wildcards like "**" are allowed. Normal wildcards are allowed, but can significantly slow down searching for @@ -5028,6 +4999,8 @@ A jump table for the options with a short description can be found at |Q_op|. "inclusive" means that the last character of the selection is included in an operation. For example, when "x" is used to delete the selection. + When "old" is used and 'virtualedit' allows the cursor to move past + the end of line the line break still isn't included. Note that when "exclusive" is used and selecting from the end backwards, you cannot include the last character of a line, when starting in Normal mode and 'virtualedit' empty. @@ -5251,9 +5224,7 @@ A jump table for the options with a short description can be found at |Q_op|. security reasons. *'shellcmdflag'* *'shcf'* -'shellcmdflag' 'shcf' string (default: "-c"; - Windows, when 'shell' does not - contain "sh" somewhere: "/c") +'shellcmdflag' 'shcf' string (default: "-c"; Windows: "/c") global Flag passed to the shell to execute "!" and ":!" commands; e.g., "bash.exe -c ls" or "cmd.exe /c dir". For Windows @@ -5264,15 +5235,12 @@ A jump table for the options with a short description can be found at |Q_op|. See |option-backslash| about including spaces and backslashes. See |shell-unquoting| which talks about separating this option into multiple arguments. - Also see |dos-shell| for Windows. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. *'shellpipe'* *'sp'* 'shellpipe' 'sp' string (default ">", "| tee", "|& tee" or "2>&1| tee") global - {not available when compiled without the |+quickfix| - feature} String to be used to put the output of the ":make" command in the error file. See also |:make_makeprg|. See |option-backslash| about including spaces and backslashes. @@ -5314,7 +5282,7 @@ A jump table for the options with a short description can be found at |Q_op|. third-party shells on Windows systems, such as the MKS Korn Shell or bash, where it should be "\"". The default is adjusted according the value of 'shell', to reduce the need to set this option by the - user. See |dos-shell|. + user. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. @@ -5346,7 +5314,7 @@ A jump table for the options with a short description can be found at |Q_op|. *'shellslash'* *'ssl'* *'noshellslash'* *'nossl'* 'shellslash' 'ssl' boolean (default off) global - {only for MSDOS and MS-Windows} + {only for Windows} When set, a forward slash is used when expanding file names. This is useful when a Unix-like shell is used instead of command.com or cmd.exe. Backward slashes can still be typed, but they are changed to @@ -5363,10 +5331,7 @@ A jump table for the options with a short description can be found at |Q_op|. global When on, use temp files for shell commands. When off use a pipe. When using a pipe is not possible temp files are used anyway. - Currently a pipe is only supported on Unix and MS-Windows 2K and - later. You can check it with: > - :if has("filterpipe") -< The advantage of using a pipe is that nobody can read the temp file + The advantage of using a pipe is that nobody can read the temp file and the 'shell' command does not need to support redirection. The advantage of using a temp file is that the file type and encoding can be detected. @@ -5376,19 +5341,14 @@ A jump table for the options with a short description can be found at |Q_op|. |system()| does not respect this option, it always uses pipes. *'shellxescape'* *'sxe'* -'shellxescape' 'sxe' string (default: ""; - for Windows: "\"&|<>()@^") +'shellxescape' 'sxe' string (default: "") global When 'shellxquote' is set to "(" then the characters listed in this option will be escaped with a '^' character. This makes it possible to execute most external commands with cmd.exe. *'shellxquote'* *'sxq'* -'shellxquote' 'sxq' string (default: ""; - for Win32, when 'shell' is cmd.exe: "(" - for Win32, when 'shell' contains "sh" - somewhere: "\"" - for Unix, when using system(): "\"") +'shellxquote' 'sxq' string (default: "") global Quoting character(s), put around the command passed to the shell, for the "!" and ":!" commands. Includes the redirection. See @@ -5397,12 +5357,6 @@ A jump table for the options with a short description can be found at |Q_op|. When the value is '(' then ')' is appended. When the value is '"(' then ')"' is appended. When the value is '(' then also see 'shellxescape'. - This is an empty string by default on most systems, but is known to be - useful for on Win32 version, either for cmd.exe which automatically - strips off the first and last quote on a command, or 3rd-party shells - such as the MKS Korn Shell or bash, where it should be "\"". The - default is adjusted according the value of 'shell', to reduce the need - to set this option by the user. See |dos-shell|. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. @@ -6413,8 +6367,6 @@ A jump table for the options with a short description can be found at |Q_op|. *'title'* *'notitle'* 'title' boolean (default off, on when title can be restored) global - {not available when compiled without the |+title| - feature} When on, the title of the window will be set to the value of 'titlestring' (if it is not empty), or to: filename [+=-] (path) - VIM @@ -6426,16 +6378,10 @@ A jump table for the options with a short description can be found at |Q_op|. =+ indicates the file is read-only and modified (path) is the path of the file being edited - VIM the server name |v:servername| or "VIM" - Only works if the terminal supports setting window titles - (currently Win32 console, all GUI versions and terminals with a non- - empty 't_ts' option - this is Unix xterm by default, where 't_ts' is - taken from the builtin termcap). *'titlelen'* 'titlelen' number (default 85) global - {not available when compiled without the |+title| - feature} Gives the percentage of 'columns' to use for the length of the window title. When the title is longer, only the end of the path name is shown. A '<' character before the path name is used to indicate this. @@ -6449,8 +6395,6 @@ A jump table for the options with a short description can be found at |Q_op|. *'titleold'* 'titleold' string (default "Thanks for flying Vim") global - {only available when compiled with the |+title| - feature} This option will be used for the window title when exiting Vim if the original title cannot be restored. Only happens if 'title' is on or 'titlestring' is not empty. @@ -6459,13 +6403,8 @@ A jump table for the options with a short description can be found at |Q_op|. *'titlestring'* 'titlestring' string (default "") global - {not available when compiled without the |+title| - feature} When this option is not empty, it will be used for the title of the window. This happens only when the 'title' option is on. - Only works if the terminal supports setting window titles (currently - Win32 console, all GUI versions and terminals with a non-empty 't_ts' - option). When this option contains printf-style '%' items, they will be expanded according to the rules used for 'statusline'. Example: > diff --git a/runtime/doc/os_win32.txt b/runtime/doc/os_win32.txt index cd8ad3465a..4b012712fc 100644 --- a/runtime/doc/os_win32.txt +++ b/runtime/doc/os_win32.txt @@ -1,38 +1,11 @@ *os_win32.txt* Nvim - VIM REFERENCE MANUAL by George Reilly + NVIM REFERENCE MANUAL *win32* *Win32* *MS-Windows* -This file documents the idiosyncrasies of the Win32 version of Vim. - -The Win32 version of Vim works on Windows XP, Vista and Windows 7. -There are both console and GUI versions. - -The 32 bit version also runs on 64 bit MS-Windows systems. - -1. Known problems |win32-problems| -2. Startup |win32-startup| -3. Using the mouse |win32-mouse| -4. Win32 mini FAQ |win32-faq| - -Additionally, there are a number of common Win32 and DOS items: -File locations |dos-locations| -Using backslashes |dos-backslash| -Standard mappings |dos-standard-mappings| -Screen output and colors |dos-colors| -File formats |dos-file-formats| -:cd command |dos-:cd| -Interrupting |dos-CTRL-Break| -Temp files |dos-temp-files| -Shell option default |dos-shell| - -Win32 GUI |gui-w32| - -Credits: -The Win32 version was written by George V. Reilly <george@reilly.org>. -The GUI version was made by George V. Reilly and Robert Webb. +This file documents the Win32 version of Nvim. ============================================================================== 1. Known problems *win32-problems* diff --git a/runtime/doc/pattern.txt b/runtime/doc/pattern.txt index 1d0f42c222..f7f561dfa5 100644 --- a/runtime/doc/pattern.txt +++ b/runtime/doc/pattern.txt @@ -9,16 +9,7 @@ Patterns and search commands *pattern-searches* The very basics can be found in section |03.9| of the user manual. A few more explanations are in chapter 27 |usr_27.txt|. -1. Search commands |search-commands| -2. The definition of a pattern |search-pattern| -3. Magic |/magic| -4. Overview of pattern items |pattern-overview| -5. Multi items |pattern-multi-items| -6. Ordinary atoms |pattern-atoms| -7. Ignoring case in a pattern |/ignorecase| -8. Composing characters |patterns-composing| -9. Compare with Perl patterns |perl-patterns| -10. Highlighting matches |match-highlight| + Type <M-]> to see the table of contents. ============================================================================== 1. Search commands *search-commands* @@ -130,8 +121,7 @@ gD Goto global Declaration. When the cursor is on a ends before the cursor position. *CTRL-C* -CTRL-C Interrupt current (search) command. Use CTRL-Break on - Windows |dos-CTRL-Break|. +CTRL-C Interrupt current (search) command. In Normal mode, any pending command is aborted. *:noh* *:nohlsearch* @@ -354,8 +344,8 @@ For starters, read chapter 27 of the user manual |usr_27.txt|. */\%#=* *two-engines* *NFA* Vim includes two regexp engines: 1. An old, backtracking engine that supports everything. -2. A new, NFA engine that works much faster on some patterns, but does not - support everything. +2. A new, NFA engine that works much faster on some patterns, possibly slower + on some patterns. Vim will automatically select the right engine for you. However, if you run into a problem or want to specifically select one engine or the other, you can diff --git a/runtime/doc/pi_gzip.txt b/runtime/doc/pi_gzip.txt index 5b7a903f9c..f024db1260 100644 --- a/runtime/doc/pi_gzip.txt +++ b/runtime/doc/pi_gzip.txt @@ -25,6 +25,8 @@ with these extensions: *.bz2 bzip2 *.lzma lzma *.xz xz + *.lz lzip + *.zst zstd That's actually the only thing you need to know. There are no options. diff --git a/runtime/doc/pi_health.txt b/runtime/doc/pi_health.txt index 69833103d1..8354c0470f 100644 --- a/runtime/doc/pi_health.txt +++ b/runtime/doc/pi_health.txt @@ -2,10 +2,7 @@ Author: TJ DeVries <devries.timothyj@gmail.com> -============================================================================== -1. Introduction |health.vim-intro| -2. Commands and functions |health.vim-manual| -3. Create a healthcheck |health.vim-dev| + Type <M-]> to see the table of contents. ============================================================================== Introduction *healthcheck* *health.vim-intro* @@ -100,15 +97,12 @@ health#{plugin}#check() function in autoload/health/{plugin}.vim. |:CheckHealth| automatically finds and invokes such functions. If your plugin is named "jslint", then its healthcheck function must be > - health#jslint#check() -< -defined in this file on 'runtimepath': > +defined in this file on 'runtimepath': > autoload/health/jslint.vim -< -Here's a sample to get started: > +Here's a sample to get started: > function! health#jslint#check() abort call health#report_start('sanity checks') " perform arbitrary checks @@ -121,7 +115,7 @@ Here's a sample to get started: > \ ['npm install --save jslint']) endif endfunction -< + ============================================================================== vim:tw=78:ts=8:ft=help:fdm=marker diff --git a/runtime/doc/pi_netrw.txt b/runtime/doc/pi_netrw.txt index d0cfa70582..3e19f0b4af 100644 --- a/runtime/doc/pi_netrw.txt +++ b/runtime/doc/pi_netrw.txt @@ -530,7 +530,7 @@ variable (ex. scp uses the variable g:netrw_scp_cmd, which is defaulted to let g:netrw_sftp_cmd= '"c:\Program Files\PuTTY\psftp.exe"' < (note: it has been reported that windows 7 with putty v0.6's "-batch" option - doesn't work, so its best to leave it off for that system) + doesn't work, so it's best to leave it off for that system) See |netrw-p8| for more about putty, pscp, psftp, etc. @@ -1204,7 +1204,7 @@ The :NetrwMB command is available outside of netrw buffers (once netrw has been invoked in the session). The file ".netrwbook" holds bookmarks when netrw (and vim) is not active. By -default, its stored on the first directory on the user's |'runtimepath'|. +default, it's stored on the first directory on the user's |'runtimepath'|. Related Topics: |netrw-gb| how to return (go) to a bookmark @@ -1429,7 +1429,7 @@ be used in that count. *.netrwhist* See |g:netrw_dirhistmax| for how to control the quantity of history stack slots. The file ".netrwhist" holds history when netrw (and vim) is not -active. By default, its stored on the first directory on the user's +active. By default, it's stored on the first directory on the user's |'runtimepath'|. Related Topics: @@ -3269,7 +3269,7 @@ The user function is passed one argument; it resembles > fun! ExampleUserMapFunc(islocal) < -where a:islocal is 1 if its a local-directory system call or 0 when +where a:islocal is 1 if it's a local-directory system call or 0 when remote-directory system call. Use netrw#Expose("varname") to access netrw-internal (script-local) @@ -3593,7 +3593,7 @@ Example: Clear netrw's marked file list via a mapping on gu > *netrw-p16* P16. When editing remote files (ex. :e ftp://hostname/path/file), - under Windows I get an |E303| message complaining that its unable + under Windows I get an |E303| message complaining that it's unable to open a swap file. (romainl) It looks like you are starting Vim from a protected @@ -3647,7 +3647,7 @@ Example: Clear netrw's marked file list via a mapping on gu > P21. I've made a directory (or file) with an accented character, but netrw isn't letting me enter that directory/read that file: - Its likely that the shell or o/s is using a different encoding + It's likely that the shell or o/s is using a different encoding than you have vim (netrw) using. A patch to vim supporting "systemencoding" may address this issue in the future; for now, just have netrw use the proper encoding. For example: > diff --git a/runtime/doc/pi_zip.txt b/runtime/doc/pi_zip.txt index 64f0be1a08..c20bda1fa1 100644 --- a/runtime/doc/pi_zip.txt +++ b/runtime/doc/pi_zip.txt @@ -6,7 +6,7 @@ Author: Charles E. Campbell <NdrOchip@ScampbellPfamily.AbizM> (remove NOSPAM from Campbell's email first) -Copyright: Copyright (C) 2005-2012 Charles E Campbell *zip-copyright* +Copyright: Copyright (C) 2005-2015 Charles E Campbell *zip-copyright* The VIM LICENSE (see |copyright|) applies to the files in this package, including zipPlugin.vim, zip.vim, and pi_zip.vim. except use "zip.vim" instead of "VIM". Like anything else that's free, zip.vim @@ -33,6 +33,9 @@ Copyright: Copyright (C) 2005-2012 Charles E Campbell *zip-copyright* also write to the file. Currently, one may not make a new file in zip archives via the plugin. + *zip-x* + x : may extract a listed file when the cursor is atop it + OPTIONS *g:zip_nomax* @@ -61,6 +64,11 @@ Copyright: Copyright (C) 2005-2012 Charles E Campbell *zip-copyright* file; by default: > let g:zip_zipcmd= "zip" < + *g:zip_extractcmd* + This option specifies the program (and any options needed) used to + extract a file from a zip archive. By default, > + let g:zip_extractcmd= g:zip_unzipcmd +< PREVENTING LOADING~ If for some reason you do not wish to use vim to examine zipped files, @@ -83,8 +91,26 @@ Copyright: Copyright (C) 2005-2012 Charles E Campbell *zip-copyright* One can simply extend this line to accommodate additional extensions that should be treated as zip files. + Alternatively, one may change *g:zipPlugin_ext* in one's .vimrc. + Currently (11/30/15) it holds: > + + let g:zipPlugin_ext= '*.zip,*.jar,*.xpi,*.ja,*.war,*.ear,*.celzip, + \ *.oxt,*.kmz,*.wsz,*.xap,*.docx,*.docm,*.dotx,*.dotm,*.potx,*.potm, + \ *.ppsx,*.ppsm,*.pptx,*.pptm,*.ppam,*.sldx,*.thmx,*.xlam,*.xlsx,*.xlsm, + \ *.xlsb,*.xltx,*.xltm,*.xlam,*.crtx,*.vdw,*.glox,*.gcsx,*.gqsx,*.epub' + ============================================================================== 4. History *zip-history* {{{1 + v28 Oct 08, 2014 * changed the sanity checks for executables to reflect + the command actually to be attempted in zip#Read() + and zip#Write() + * added the extraction of a file capability + Nov 30, 2015 * added *.epub to the |g:zipPlugin_ext| list + Sep 13, 2016 * added *.apk to the |g:zipPlugin_ext| list and + sorted the suffices. + v27 Jul 02, 2013 * sanity check: zipfile must have "PK" as its first + two bytes. + * modified to allow zipfile: entries in quickfix lists v26 Nov 15, 2012 * (Jason Spiro) provided a lot of new extensions that are synonyms for .zip v25 Jun 27, 2011 * using keepj with unzip -Z diff --git a/runtime/doc/print.txt b/runtime/doc/print.txt index c5470d1469..01de3a5290 100644 --- a/runtime/doc/print.txt +++ b/runtime/doc/print.txt @@ -6,14 +6,7 @@ Printing *printing* -1. Introduction |print-intro| -2. Print options |print-options| -3. PostScript Printing |postscript-printing| -4. PostScript Printing Encoding |postscript-print-encoding| -5. PostScript CJK Printing |postscript-cjk-printing| -6. PostScript Printing Troubleshooting |postscript-print-trouble| -7. PostScript Utilities |postscript-print-util| -8. Formfeed Characters |printing-formfeed| + Type <M-]> to see the table of contents. ============================================================================== 1. Introduction *print-intro* diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt index eaa23de093..8d1dd0a6cd 100644 --- a/runtime/doc/provider.txt +++ b/runtime/doc/provider.txt @@ -8,6 +8,8 @@ Providers *provider* Nvim delegates some features to dynamic "providers". + Type <M-]> to see the table of contents. + ============================================================================== Python integration *provider-python* diff --git a/runtime/doc/quickfix.txt b/runtime/doc/quickfix.txt index 1bc5c31281..cad5bf98b5 100644 --- a/runtime/doc/quickfix.txt +++ b/runtime/doc/quickfix.txt @@ -6,15 +6,7 @@ This subject is introduced in section |30.1| of the user manual. -1. Using QuickFix commands |quickfix| -2. The error window |quickfix-window| -3. Using more than one list of errors |quickfix-error-lists| -4. Using :make |:make_makeprg| -5. Using :grep |grep| -6. Selecting a compiler |compiler-select| -7. The error format |error-file-format| -8. The directory stack |quickfix-directory-stack| -9. Specific error file formats |errorformats| + Type <M-]> to see the table of contents. ============================================================================= 1. Using QuickFix commands *quickfix* *Quickfix* *E42* @@ -872,7 +864,7 @@ need to write down a "todo" list. The Vim plugins in the "compiler" directory will set options to use the -selected compiler. For ":compiler" local options are set, for ":compiler!" +selected compiler. For `:compiler` local options are set, for `:compiler!` global options. *current_compiler* To support older Vim versions, the plugins always use "current_compiler" and diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt index a918a4d34a..128c70ee94 100644 --- a/runtime/doc/quickref.txt +++ b/runtime/doc/quickref.txt @@ -751,7 +751,7 @@ Short explanation of each option: *option-list* 'keywordprg' 'kp' program to use for the "K" command 'langmap' 'lmap' alphabetic characters for other language mode 'langmenu' 'lm' language to be used for the menus -'langnoremap' 'lnr' do not apply 'langmap' to mapped characters +'langremap' 'lrm' do apply 'langmap' to mapped characters 'laststatus' 'ls' tells when last window has status lines 'lazyredraw' 'lz' don't redraw while executing macros 'linebreak' 'lbr' wrap long lines at a blank @@ -988,7 +988,6 @@ Short explanation of each option: *option-list* |g_CTRL-G| g CTRL-G show cursor column, line, and character position |CTRL-C| CTRL-C during searches: Interrupt the search -|dos-CTRL-Break| CTRL-Break Windows: during searches: Interrupt the search |<Del>| <Del> while entering a count: delete last character |:version| :ve[rsion] show version information |:normal| :norm[al][!] {commands} @@ -1027,6 +1026,8 @@ Short explanation of each option: *option-list* |c_<Up>| <Up>/<Down> recall older/newer command-line that starts with current command |c_<S-Up>| <S-Up>/<S-Down> recall older/newer command-line from history +|c_CTRL-G| CTRL-G next match when 'incsearch' is active +|c_CTRL-T| CTRL-T previous match when 'incsearch' is active |:history| :his[tory] show older command-lines Context-sensitive completion on the command-line: diff --git a/runtime/doc/recover.txt b/runtime/doc/recover.txt index 8eded487c0..2b49af1c96 100644 --- a/runtime/doc/recover.txt +++ b/runtime/doc/recover.txt @@ -15,8 +15,7 @@ You can recover most of your changes from the files that Vim uses to store the contents of the file. Mostly you can recover your work with one command: vim -r filename -1. The swap file |swap-file| -2. Recovery |recovery| + Type <M-]> to see the table of contents. ============================================================================== 1. The swap file *swap-file* diff --git a/runtime/doc/remote.txt b/runtime/doc/remote.txt index b99aa6a859..bdc763b85f 100644 --- a/runtime/doc/remote.txt +++ b/runtime/doc/remote.txt @@ -6,9 +6,7 @@ Vim client-server communication *client-server* -1. Common functionality |clientserver| -2. X11 specific items |x11-clientserver| -3. MS-Windows specific items |w32-clientserver| + Type <M-]> to see the table of contents. ============================================================================== 1. Common functionality *clientserver* diff --git a/runtime/doc/remote_plugin.txt b/runtime/doc/remote_plugin.txt index 3c682e83f3..cc2efd3d1f 100644 --- a/runtime/doc/remote_plugin.txt +++ b/runtime/doc/remote_plugin.txt @@ -6,10 +6,7 @@ Nvim support for remote plugins *remote-plugin* -1. Introduction |remote-plugin-intro| -2. Plugin hosts |remote-plugin-hosts| -3. Example |remote-plugin-example| -4. Plugin manifest |remote-plugin-manifest| + Type <M-]> to see the table of contents. ============================================================================== 1. Introduction *remote-plugin-intro* diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt index b34d081ba9..0b3edc9bba 100644 --- a/runtime/doc/repeat.txt +++ b/runtime/doc/repeat.txt @@ -8,14 +8,7 @@ Repeating commands, Vim scripts and debugging *repeating* Chapter 26 of the user manual introduces repeating |usr_26.txt|. -1. Single repeats |single-repeat| -2. Multiple repeats |multi-repeat| -3. Complex repeats |complex-repeat| -4. Using Vim scripts |using-scripts| -5. Using Vim packages |packages| -6. Creating Vim packages |package-create| -7. Debugging scripts |debug-scripts| -8. Profiling |profiling| + Type <M-]> to see the table of contents. ============================================================================== 1. Single repeats *single-repeat* @@ -152,7 +145,7 @@ q Stops recording. :[addr]@: Repeat last command-line. First set cursor at line [addr] (default is current line). - *:@@* +:[addr]@ *:@@* :[addr]@@ Repeat the previous :@{0-9a-z"}. First set cursor at line [addr] (default is current line). @@ -357,8 +350,7 @@ terminal-independent two character codes. This means that they can be used in the same way on different kinds of terminals. The first character of a key code is 0x80 or 128, shown on the screen as "~@". The second one can be found in the list |key-notation|. Any of these codes can also be entered -with CTRL-V followed by the three digit decimal code. This does NOT work for -the <t_xx> termcap codes, these can only be used in mappings. +with CTRL-V followed by the three digit decimal code. *:source_crnl* *W15* Windows: Files that are read with ":source" normally have <CR><NL> <EOL>s. @@ -369,12 +361,6 @@ something like ":map <F1> :help^M", where "^M" is a <CR>. If the first line ends in a <CR>, but following ones don't, you will get an error message, because the <CR> from the first lines will be lost. -Mac Classic: Files that are read with ":source" normally have <CR> <EOL>s. -These always work. If you are using a file with <NL> <EOL>s (for example, a -file made on Unix), this will be recognized if 'fileformats' is not empty and -the first line does not end in a <CR>. Be careful not to use a file with <NL> -linebreaks which has a <CR> in first line. - On other systems, Vim expects ":source"ed files to end in a <NL>. These always work. If you are using a file with <CR><NL> <EOL>s (for example, a file made on Windows), all lines will have a trailing <CR>. This may cause diff --git a/runtime/doc/russian.txt b/runtime/doc/russian.txt index 7dd267ad50..e2c44ce54f 100644 --- a/runtime/doc/russian.txt +++ b/runtime/doc/russian.txt @@ -6,10 +6,7 @@ Russian language localization and support in Vim *russian* *Russian* -1. Introduction |russian-intro| -2. Russian keymaps |russian-keymap| -3. Localization |russian-l18n| -4. Known issues |russian-issues| + Type <M-]> to see the table of contents. =============================================================================== 1. Introduction *russian-intro* diff --git a/runtime/doc/scroll.txt b/runtime/doc/scroll.txt index fba5275f47..52e5cc9f0c 100644 --- a/runtime/doc/scroll.txt +++ b/runtime/doc/scroll.txt @@ -16,12 +16,7 @@ upwards in the buffer, the text in the window moves downwards on your screen. See section |03.7| of the user manual for an introduction. -1. Scrolling downwards |scroll-down| -2. Scrolling upwards |scroll-up| -3. Scrolling relative to cursor |scroll-cursor| -4. Scrolling horizontally |scroll-horizontal| -5. Scrolling synchronously |scroll-binding| -6. Scrolling with a mouse wheel |scroll-mouse-wheel| + Type <M-]> to see the table of contents. ============================================================================== 1. Scrolling downwards *scroll-down* @@ -108,7 +103,8 @@ z^ Without [count]: Redraw with the line just above the 3. Scrolling relative to cursor *scroll-cursor* The following commands reposition the edit window (the part of the buffer that -you see) while keeping the cursor on the same line: +you see) while keeping the cursor on the same line. Note that the 'scrolloff' +option may cause context lines to show above and below the cursor. *z<CR>* z<CR> Redraw, line [count] at top of window (default diff --git a/runtime/doc/sign.txt b/runtime/doc/sign.txt index e5a6b0be39..ced0608e8a 100644 --- a/runtime/doc/sign.txt +++ b/runtime/doc/sign.txt @@ -7,8 +7,7 @@ Sign Support Features *sign-support* -1. Introduction |sign-intro| -2. Commands |sign-commands| + Type <M-]> to see the table of contents. ============================================================================== 1. Introduction *sign-intro* *signs* @@ -188,7 +187,9 @@ JUMPING TO A SIGN *:sign-jump* *E157* If the file isn't displayed in window and the current file can not be |abandon|ed this fails. -:sign jump {id} buffer={nr} - Same, but use buffer {nr}. +:sign jump {id} buffer={nr} *E934* + Same, but use buffer {nr}. This fails if buffer {nr} does not + have a name. + vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/spell.txt b/runtime/doc/spell.txt index 08415f72a7..5c99db42ba 100644 --- a/runtime/doc/spell.txt +++ b/runtime/doc/spell.txt @@ -6,10 +6,7 @@ Spell checking *spell* -1. Quick start |spell-quickstart| -2. Remarks on spell checking |spell-remarks| -3. Generating a spell file |spell-mkspell| -4. Spell file format |spell-file-format| + Type <M-]> to see the table of contents. ============================================================================== 1. Quick start *spell-quickstart* *E756* diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index 2d1dd22222..477d927a12 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -6,15 +6,7 @@ Starting Vim *starting* -1. Vim arguments |vim-arguments| -2. Initialization |initialization| -3. $VIM and $VIMRUNTIME |$VIM| -4. Suspending |suspend| -5. Exiting |exiting| -6. Saving settings |save-settings| -7. Views and Sessions |views-sessions| -8. The ShaDa file |shada-file| -9. Base Directories |base-directories| + Type <M-]> to see the table of contents. ============================================================================== 1. Vim arguments *vim-arguments* @@ -181,6 +173,7 @@ argument. the executable "view" has the same effect as the -R argument. The 'updatecount' option will be set to 10000, meaning that the swap file will not be updated automatically very often. + See |-M| for disallowing modifications. *-m* -m Modifications not allowed to be written. The 'write' option @@ -425,7 +418,7 @@ accordingly. Vim proceeds in this order: - The environment variable EXINIT. The value of $EXINIT is used as an Ex command line. - c. If the 'exrc' option is on (which is not the default), the current + c. If the 'exrc' option is on (which is NOT the default), the current directory is searched for three files. The first that exists is used, the others are ignored. - The file ".nvimrc" (for Unix) @@ -518,7 +511,8 @@ accordingly. Vim proceeds in this order: The |v:vim_did_enter| variable is set to 1. The |VimEnter| autocommands are executed. -Some hints on using initializations: + +Some hints on using initializations ~ Standard setup: Create a vimrc file to set the default settings and mappings for all your edit @@ -540,17 +534,23 @@ the ":version" command. NOTE: System vimrc file needs specific compilation options (one needs to define SYS_VIMRC_FILE macros). If :version command does not show anything like this, consider contacting the nvim package maintainer. -Saving the current state of Vim to a file: + +Saving the current state of Vim to a file ~ + Whenever you have changed values of options or when you have created a mapping, then you may want to save them in a vimrc file for later use. See |save-settings| about saving the current state of settings to a file. -Avoiding setup problems for Vi users: + +Avoiding setup problems for Vi users ~ + Vi uses the variable EXINIT and the file "~/.exrc". So if you do not want to interfere with Vi, then use the variable VIMINIT and the file init.vim instead. -MS-DOS line separators: + +MS-DOS line separators: ~ + On Windows systems Vim assumes that all the vimrc files have <CR> <NL> pairs as line separators. This will give problems if you have a file with only <NL>s and have a line like ":map xx yy^M". The trailing ^M will be ignored. @@ -558,8 +558,10 @@ as line separators. This will give problems if you have a file with only The $MYVIMRC or $MYGVIMRC file will be set to the first found vimrc and/or gvimrc file. -Avoiding trojan horses: *trojan-horse* -While reading the vimrc or the exrc file in the current directory, some + +Avoiding trojan horses ~ + *trojan-horse* +While reading the "vimrc" or the "exrc" file in the current directory, some commands can be disabled for security reasons by setting the 'secure' option. This is always done when executing the command from a tags file. Otherwise it would be possible that you accidentally use a vimrc or tags file that somebody @@ -581,6 +583,8 @@ Be careful! part of the line in the tags file) is always done in secure mode. This works just like executing a command from a vimrc/exrc in the current directory. + +If Vim startup is slow ~ *slow-start* If Vim takes a long time to start up, use the |--startuptime| argument to find out what happens. @@ -590,6 +594,8 @@ while. You can find out if this is the problem by disabling ShaDa for a moment (use the Vim argument "-i NONE", |-i|). Try reducing the number of lines stored in a register with ":set shada='20,<50,s10". |shada-file|. + +Intro message ~ *:intro* When Vim starts without a file name, an introductory message is displayed (for those who don't know what Vim is). It is removed as soon as the display is @@ -721,7 +727,7 @@ There are several ways to exit Vim: - Use `:cquit`. Also when there are changes. When using `:cquit` or when there was an error message Vim exits with exit -code 1. Errors can be avoided by using `:silent!`. +code 1. Errors can be avoided by using `:silent!` or with `:catch`. ============================================================================== 6. Saving settings *save-settings* @@ -922,7 +928,7 @@ You might want to clean up your 'viewdir' directory now and then. To automatically save and restore views for *.c files: > au BufWinLeave *.c mkview - au BufWinEnter *.c silent loadview + au BufWinEnter *.c silent! loadview ============================================================================== 8. The ShaDa file *shada* *shada-file* @@ -1182,8 +1188,11 @@ running) you have additional options: *:o* *:ol* *:oldfiles* :o[ldfiles] List the files that have marks stored in the ShaDa file. This list is read on startup and only changes - afterwards with ":rshada!". Also see |v:oldfiles|. + afterwards with `:rshada!`. Also see |v:oldfiles|. The number can be used with |c_#<|. + The output can be filtered with |:filter|, e.g.: > + filter /\.vim/ oldfiles +< The filtering happens on the file name. :bro[wse] o[ldfiles][!] List file names as with |:oldfiles|, and then prompt diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt index f7c2c0e120..a45fa3096a 100644 --- a/runtime/doc/syntax.txt +++ b/runtime/doc/syntax.txt @@ -20,24 +20,7 @@ In the User Manual: |usr_06.txt| introduces syntax highlighting. |usr_44.txt| introduces writing a syntax file. -1. Quick start |:syn-qstart| -2. Syntax files |:syn-files| -3. Syntax loading procedure |syntax-loading| -4. Syntax file remarks |:syn-file-remarks| -5. Defining a syntax |:syn-define| -6. :syntax arguments |:syn-arguments| -7. Syntax patterns |:syn-pattern| -8. Syntax clusters |:syn-cluster| -9. Including syntax files |:syn-include| -10. Synchronizing |:syn-sync| -11. Listing syntax items |:syntax| -12. Highlight command |:highlight| -13. Linking groups |:highlight-link| -14. Cleaning up |:syn-clear| -15. Highlighting tags |tag-highlight| -16. Window-local syntax |:ownsyntax| -17. Color xterms |xterm-color| -18. When syntax is slow |:syntime| + Type <M-]> to see the table of contents. ============================================================================== 1. Quick start *:syn-qstart* @@ -1472,7 +1455,7 @@ algorithm should work in the vast majority of cases. In some cases, such as a file that begins with 500 or more full-line comments, the script may incorrectly decide that the fortran code is in fixed form. If that happens, just add a non-comment statement beginning anywhere in the first five columns -of the first twenty five lines, save (:w) and then reload (:e!) the file. +of the first twenty-five lines, save (:w) and then reload (:e!) the file. Tabs in fortran files ~ Tabs are not recognized by the Fortran standards. Tabs are not a good idea in @@ -2656,68 +2639,103 @@ your vimrc: *g:filetype_r* RUBY *ruby.vim* *ft-ruby-syntax* -There are a number of options to the Ruby syntax highlighting. + Ruby: Operator highlighting |ruby_operators| + Ruby: Whitespace errors |ruby_space_errors| + Ruby: Folding |ruby_fold| |ruby_foldable_groups| + Ruby: Reducing expensive operations |ruby_no_expensive| |ruby_minlines| + Ruby: Spellchecking strings |ruby_spellcheck_strings| -By default, the "end" keyword is colorized according to the opening statement -of the block it closes. While useful, this feature can be expensive; if you -experience slow redrawing (or you are on a terminal with poor color support) -you may want to turn it off by defining the "ruby_no_expensive" variable: > + *ruby_operators* + Ruby: Operator highlighting ~ - :let ruby_no_expensive = 1 +Operators can be highlighted by defining "ruby_operators": > + + :let ruby_operators = 1 < -In this case the same color will be used for all control keywords. + *ruby_space_errors* + Ruby: Whitespace errors ~ -If you do want this feature enabled, but notice highlighting errors while -scrolling backwards, which are fixed when redrawing with CTRL-L, try setting -the "ruby_minlines" variable to a value larger than 50: > +Whitespace errors can be highlighted by defining "ruby_space_errors": > - :let ruby_minlines = 100 + :let ruby_space_errors = 1 < -Ideally, this value should be a number of lines large enough to embrace your -largest class or module. +This will highlight trailing whitespace and tabs preceded by a space character +as errors. This can be refined by defining "ruby_no_trail_space_error" and +"ruby_no_tab_space_error" which will ignore trailing whitespace and tabs after +spaces respectively. -Highlighting of special identifiers can be disabled by removing the -rubyIdentifier highlighting: > + *ruby_fold* *ruby_foldable_groups* + Ruby: Folding ~ - :hi link rubyIdentifier NONE +Folding can be enabled by defining "ruby_fold": > + + :let ruby_fold = 1 < -This will prevent highlighting of special identifiers like "ConstantName", -"$global_var", "@@class_var", "@instance_var", "| block_param |", and -":symbol". +This will set the value of 'foldmethod' to "syntax" locally to the current +buffer or window, which will enable syntax-based folding when editing Ruby +filetypes. -Significant methods of Kernel, Module and Object are highlighted by default. -This can be disabled by defining "ruby_no_special_methods": > +Default folding is rather detailed, i.e., small syntax units like "if", "do", +"%w[]" may create corresponding fold levels. - :let ruby_no_special_methods = 1 +You can set "ruby_foldable_groups" to restrict which groups are foldable: > + + :let ruby_foldable_groups = 'if case %' < -This will prevent highlighting of important methods such as "require", "attr", -"private", "raise" and "proc". +The value is a space-separated list of keywords: + + keyword meaning ~ + -------- ------------------------------------- ~ + ALL Most block syntax (default) + NONE Nothing + if "if" or "unless" block + def "def" block + class "class" block + module "module" block + do "do" block + begin "begin" block + case "case" block + for "for", "while", "until" loops + { Curly bracket block or hash literal + [ Array literal + % Literal with "%" notation, e.g.: %w(STRING), %!STRING! + / Regexp + string String and shell command output (surrounded by ', ", `) + : Symbol + # Multiline comment + << Here documents + __END__ Source code after "__END__" directive + + *ruby_no_expensive* + Ruby: Reducing expensive operations ~ -Ruby operators can be highlighted. This is enabled by defining -"ruby_operators": > +By default, the "end" keyword is colorized according to the opening statement +of the block it closes. While useful, this feature can be expensive; if you +experience slow redrawing (or you are on a terminal with poor color support) +you may want to turn it off by defining the "ruby_no_expensive" variable: > - :let ruby_operators = 1 + :let ruby_no_expensive = 1 < -Whitespace errors can be highlighted by defining "ruby_space_errors": > +In this case the same color will be used for all control keywords. - :let ruby_space_errors = 1 -< -This will highlight trailing whitespace and tabs preceded by a space character -as errors. This can be refined by defining "ruby_no_trail_space_error" and -"ruby_no_tab_space_error" which will ignore trailing whitespace and tabs after -spaces respectively. + *ruby_minlines* -Folding can be enabled by defining "ruby_fold": > +If you do want this feature enabled, but notice highlighting errors while +scrolling backwards, which are fixed when redrawing with CTRL-L, try setting +the "ruby_minlines" variable to a value larger than 50: > - :let ruby_fold = 1 + :let ruby_minlines = 100 < -This will set the 'foldmethod' option to "syntax" and allow folding of -classes, modules, methods, code blocks, heredocs and comments. +Ideally, this value should be a number of lines large enough to embrace your +largest class or module. -Folding of multiline comments can be disabled by defining -"ruby_no_comment_fold": > + *ruby_spellcheck_strings* + Ruby: Spellchecking strings ~ - :let ruby_no_comment_fold = 1 +Ruby syntax will perform spellchecking of strings if you define +"ruby_spellcheck_strings": > + + :let ruby_spellcheck_strings = 1 < SCHEME *scheme.vim* *ft-scheme-syntax* @@ -2815,9 +2833,11 @@ vimrc file: > (Adapted from the html.vim help text by Claudio Fleiner <claudio@fleiner.com>) -SH *sh.vim* *ft-sh-syntax* *ft-bash-syntax* *ft-ksh-syntax* + *ft-posix-synax* *ft-dash-syntax* +SH *sh.vim* *ft-sh-syntax* *ft-bash-syntax* *ft-ksh-syntax* -This covers the "normal" Unix (Bourne) sh, bash and the Korn shell. +This covers syntax highlighting for the older Unix (Bourne) sh, and newer +shells such as bash, dash, posix, and the Korn shells. Vim attempts to determine which shell type is in use by specifying that various filenames are of specific types: > @@ -2826,28 +2846,31 @@ various filenames are of specific types: > bash: .bashrc* bashrc bash.bashrc .bash_profile* *.bash < If none of these cases pertain, then the first line of the file is examined -(ex. /bin/sh /bin/ksh /bin/bash). If the first line specifies a shelltype, -then that shelltype is used. However some files (ex. .profile) are known to -be shell files but the type is not apparent. Furthermore, on many systems -sh is symbolically linked to "bash" (Linux, Windows+cygwin) or "ksh" (Posix). +(ex. looking for /bin/sh /bin/ksh /bin/bash). If the first line specifies a +shelltype, then that shelltype is used. However some files (ex. .profile) are +known to be shell files but the type is not apparent. Furthermore, on many +systems sh is symbolically linked to "bash" (Linux, Windows+cygwin) or "ksh" +(Posix). -One may specify a global default by instantiating one of the following three +One may specify a global default by instantiating one of the following variables in your vimrc: - ksh: > + ksh: > let g:is_kornshell = 1 -< posix: (using this is the same as setting is_kornshell to 1) > +< posix: (using this is the nearly the same as setting g:is_kornshell to 1) > let g:is_posix = 1 < bash: > let g:is_bash = 1 < sh: (default) Bourne shell > let g:is_sh = 1 +< (dash users should use posix) + If there's no "#! ..." line, and the user hasn't availed himself/herself of a default sh.vim syntax setting as just shown, then syntax/sh.vim will assume the Bourne shell syntax. No need to quote RFCs or market penetration statistics in error reports, please -- just select the default version of the -sh your system uses in your vimrc. +sh your system uses and install the associated "let..." in your <.vimrc>. The syntax/sh.vim file provides several levels of syntax-based folding: > @@ -2856,7 +2879,7 @@ The syntax/sh.vim file provides several levels of syntax-based folding: > let g:sh_fold_enabled= 2 (enable heredoc folding) let g:sh_fold_enabled= 4 (enable if/do/for folding) > -then various syntax items (HereDocuments and function bodies) become +then various syntax items (ie. HereDocuments and function bodies) become syntax-foldable (see |:syn-fold|). You also may add these together to get multiple types of folding: > @@ -2880,14 +2903,14 @@ reduce this, the "sh_maxlines" internal variable can be set. Example: > The default is to use the twice sh_minlines. Set it to a smaller number to speed up displaying. The disadvantage is that highlight errors may appear. - *g:sh_isk* *g:sh_noisk* -The shell languages appear to let "." be part of words, commands, etc; -consequently it should be in the isk for sh.vim. As of v116 of syntax/sh.vim, -syntax/sh.vim will append the "." to |'iskeyword'| by default; you may control -this behavior with: > - let g:sh_isk = '..whatever characters you want as part of iskeyword' - let g:sh_noisk= 1 " otherwise, if this exists, the isk will NOT chg +syntax/sh.vim tries to flag certain problems as errors; usually things like +extra ']'s, 'done's, 'fi's, etc. If you find the error handling problematic +for your purposes, you may suppress such error highlighting by putting +the following line in your .vimrc: > + + let g:sh_no_error= 1 < + *sh-embed* *sh-awk* Sh: EMBEDDING LANGUAGES~ @@ -3189,11 +3212,11 @@ syntax highlighting script handles this with the following logic: * If g:tex_stylish exists and is 1 then the file will be treated as a "sty" file, so the "_" will be allowed as part of keywords - (irregardless of g:tex_isk) + (regardless of g:tex_isk) * Else if the file's suffix is sty, cls, clo, dtx, or ltx, then the file will be treated as a "sty" file, so the "_" will be allowed as part of keywords - (irregardless of g:tex_isk) + (regardless of g:tex_isk) * If g:tex_isk exists, then it will be used for the local 'iskeyword' * Else the local 'iskeyword' will be set to 48-57,a-z,A-Z,192-255 @@ -3421,6 +3444,8 @@ DEFINING CASE *:syn-case* *E390* "ignore". Note that any items before this are not affected, and all items until the next ":syntax case" command are affected. +:sy[ntax] case + Show either "syntax case match" or "syntax case ignore" (translated). SPELL CHECKING *:syn-spell* @@ -3438,6 +3463,11 @@ SPELL CHECKING *:syn-spell* To activate spell checking the 'spell' option must be set. +:sy[ntax] spell + Show either "syntax spell toplevel", "syntax spell notoplevel" or + "syntax spell default" (translated). + + SYNTAX ISKEYWORD SETTING *:syn-iskeyword* :sy[ntax] iskeyword [clear | {option}] @@ -3461,8 +3491,8 @@ SYNTAX ISKEYWORD SETTING *:syn-iskeyword* and also determines where |:syn-keyword| will be checked for a new match. - It is recommended when writing syntax files, to use this command - to the correct value for the specific syntax language and not change + It is recommended when writing syntax files, to use this command to + set the correct value for the specific syntax language and not change the 'iskeyword' option. DEFINING KEYWORDS *:syn-keyword* @@ -3520,7 +3550,11 @@ DEFINING KEYWORDS *:syn-keyword* DEFINING MATCHES *:syn-match* -:sy[ntax] match {group-name} [{options}] [excludenl] {pattern} [{options}] +:sy[ntax] match {group-name} [{options}] + [excludenl] + [keepend] + {pattern} + [{options}] This defines one match. @@ -3529,6 +3563,9 @@ DEFINING MATCHES *:syn-match* [excludenl] Don't make a pattern with the end-of-line "$" extend a containing match or region. Must be given before the pattern. |:syn-excludenl| + keepend Don't allow contained matches to go past a + match with the end pattern. See + |:syn-keepend|. {pattern} The search pattern that defines the match. See |:syn-pattern| below. Note that the pattern may match more than one @@ -3739,7 +3776,7 @@ Whether or not it is actually concealed depends on the value of the 'conceallevel' option. The 'concealcursor' option is used to decide whether concealable items in the current line are displayed unconcealed to be able to edit the line. -Another way to conceal text with with |matchadd()|. +Another way to conceal text is with |matchadd()|. concealends *:syn-concealends* @@ -4024,6 +4061,9 @@ IMPLICIT CONCEAL *:syn-conceal-implicit* off" returns to the normal state where the "conceal" flag must be given explicitly. +:sy[ntax] conceal + Show either "syntax conceal on" or "syntax conceal off" (translated). + ============================================================================== 7. Syntax patterns *:syn-pattern* *E401* *E402* @@ -4532,7 +4572,14 @@ in their own color. Doesn't work recursively, thus you can't use ":colorscheme" in a color scheme script. - After the color scheme has been loaded the + + To customize a colorscheme use another name, e.g. + "~/.vim/colors/mine.vim", and use `:runtime` to load + the original colorscheme: > + runtime colors/evening.vim + hi Statement ctermfg=Blue guifg=Blue + +< After the color scheme has been loaded the |ColorScheme| autocommand event is triggered. For info about writing a colorscheme file: > :edit $VIMRUNTIME/colors/README.txt @@ -4589,8 +4636,7 @@ mentioned for the default values. See |:verbose-cmd| for more information. *highlight-args* *E416* *E417* *E423* There are three types of terminals for highlighting: term a normal terminal (vt100, xterm) -cterm a color terminal (Windows console, color-xterm, these have the "Co" - termcap entry) +cterm a color terminal (Windows console, color-xterm) gui the GUI For each type the highlighting can be given. This makes it possible to use @@ -4630,21 +4676,12 @@ stop={term-list} *term-list* *highlight-stop* highlighted area. This should undo the "start" argument. Otherwise the screen will look messed up. - The {term-list} can have two forms: - - 1. A string with escape sequences. - This is any string of characters, except that it can't start with - "t_" and blanks are not allowed. The <> notation is recognized - here, so you can use things like "<Esc>" and "<Space>". Example: + {term-list} is a a string with escape sequences. This is any string of + characters, except that it can't start with "t_" and blanks are not + allowed. The <> notation is recognized here, so you can use things + like "<Esc>" and "<Space>". Example: start=<Esc>[27h;<Esc>[<Space>r; - 2. A list of terminal codes. - Each terminal code has the form "t_xx", where "xx" is the name of - the termcap entry. The codes have to be separated with commas. - White space is not allowed. Example: - start=t_C1,t_BL - The terminal codes must exist for this to work. - 2. highlight arguments for color terminals @@ -4669,7 +4706,7 @@ ctermbg={color-nr} *highlight-ctermbg* unpredictable. See your xterm documentation for the defaults. The colors for a color-xterm can be changed from the .Xdefaults file. Unfortunately this means that it's not possible to get the same colors - for each user. See |xterm-color| for info about color xterms. + for each user. The MSDOS standard colors are fixed (in a console window), so these have been used for the names. But the meaning of color names in X11 @@ -4803,10 +4840,7 @@ guisp={color-name} *highlight-guisp* Black White Orange Purple Violet - In the Win32 GUI version, additional system colors are available. See - |win32-colors|. - - You can also specify a color by its Red, Green and Blue values. + You can also specify a color by its RGB (red, green, blue) values. The format is "#rrggbb", where "rr" is the Red value "gg" is the Green value @@ -5165,32 +5199,6 @@ When splitting the window, the new window will use the original syntax. ============================================================================== 17. Color xterms *xterm-color* *color-xterm* -Most color xterms have only eight colors. If you don't get colors with the -default setup, it should work with these lines in your vimrc: > - :if &term =~ "xterm" - : if has("terminfo") - : set t_Co=8 - : set t_Sf=<Esc>[3%p1%dm - : set t_Sb=<Esc>[4%p1%dm - : else - : set t_Co=8 - : set t_Sf=<Esc>[3%dm - : set t_Sb=<Esc>[4%dm - : endif - :endif -< [<Esc> is a real escape, type CTRL-V <Esc>] - -You might want to change the first "if" to match the name of your terminal, -e.g. "dtterm" instead of "xterm". - -Note: Do these settings BEFORE doing ":syntax on". Otherwise the colors may -be wrong. - *xiterm* *rxvt* -The above settings have been mentioned to work for xiterm and rxvt too. -But for using 16 colors in an rxvt these should work with terminfo: > - :set t_AB=<Esc>[%?%p1%{8}%<%t25;%p1%{40}%+%e5;%p1%{32}%+%;%dm - :set t_AF=<Esc>[%?%p1%{8}%<%t22;%p1%{30}%+%e1;%p1%{22}%+%;%dm -< *colortest.vim* To test your color setup, a file has been included in the Vim distribution. To use it, execute this command: > @@ -5201,111 +5209,6 @@ output lighter foreground colors, even though the number of colors is defined at 8. Therefore Vim sets the "cterm=bold" attribute for light foreground colors, when 't_Co' is 8. - *xfree-xterm* -To get 16 colors or more, get the newest xterm version (which should be -included with XFree86 3.3 and later). You can also find the latest version -at: > - http://invisible-island.net/xterm/xterm.html -Here is a good way to configure it. This uses 88 colors and enables the -termcap-query feature, which allows Vim to ask the xterm how many colors it -supports. > - ./configure --disable-bold-color --enable-88-color --enable-tcap-query -If you only get 8 colors, check the xterm compilation settings. -(Also see |UTF8-xterm| for using this xterm with UTF-8 character encoding). - -This xterm should work with these lines in your vimrc (for 16 colors): > - :if has("terminfo") - : set t_Co=16 - : set t_AB=<Esc>[%?%p1%{8}%<%t%p1%{40}%+%e%p1%{92}%+%;%dm - : set t_AF=<Esc>[%?%p1%{8}%<%t%p1%{30}%+%e%p1%{82}%+%;%dm - :else - : set t_Co=16 - : set t_Sf=<Esc>[3%dm - : set t_Sb=<Esc>[4%dm - :endif -< [<Esc> is a real escape, type CTRL-V <Esc>] - -Without |+terminfo|, Vim will recognize these settings, and automatically -translate cterm colors of 8 and above to "<Esc>[9%dm" and "<Esc>[10%dm". -Colors above 16 are also translated automatically. - -For 256 colors this has been reported to work: > - - :set t_AB=<Esc>[48;5;%dm - :set t_AF=<Esc>[38;5;%dm - -Or just set the TERM environment variable to "xterm-color" or "xterm-16color" -and try if that works. - -You probably want to use these X resources (in your ~/.Xdefaults file): - XTerm*color0: #000000 - XTerm*color1: #c00000 - XTerm*color2: #008000 - XTerm*color3: #808000 - XTerm*color4: #0000c0 - XTerm*color5: #c000c0 - XTerm*color6: #008080 - XTerm*color7: #c0c0c0 - XTerm*color8: #808080 - XTerm*color9: #ff6060 - XTerm*color10: #00ff00 - XTerm*color11: #ffff00 - XTerm*color12: #8080ff - XTerm*color13: #ff40ff - XTerm*color14: #00ffff - XTerm*color15: #ffffff - Xterm*cursorColor: Black - -[Note: The cursorColor is required to work around a bug, which changes the -cursor color to the color of the last drawn text. This has been fixed by a -newer version of xterm, but not everybody is using it yet.] - -To get these right away, reload the .Xdefaults file to the X Option database -Manager (you only need to do this when you just changed the .Xdefaults file): > - xrdb -merge ~/.Xdefaults -< - *xterm-blink* *xterm-blinking-cursor* -To make the cursor blink in an xterm, see tools/blink.c. Or use Thomas -Dickey's xterm above patchlevel 107 (see above for where to get it), with -these resources: - XTerm*cursorBlink: on - XTerm*cursorOnTime: 400 - XTerm*cursorOffTime: 250 - XTerm*cursorColor: White - - *hpterm-color* -These settings work (more or less) for an hpterm, which only supports 8 -foreground colors: > - :if has("terminfo") - : set t_Co=8 - : set t_Sf=<Esc>[&v%p1%dS - : set t_Sb=<Esc>[&v7S - :else - : set t_Co=8 - : set t_Sf=<Esc>[&v%dS - : set t_Sb=<Esc>[&v7S - :endif -< [<Esc> is a real escape, type CTRL-V <Esc>] - - *Eterm* *enlightened-terminal* -These settings have been reported to work for the Enlightened terminal -emulator, or Eterm. They might work for all xterm-like terminals that use the -bold attribute to get bright colors. Add an ":if" like above when needed. > - :set t_Co=16 - :set t_AF=^[[%?%p1%{8}%<%t3%p1%d%e%p1%{22}%+%d;1%;m - :set t_AB=^[[%?%p1%{8}%<%t4%p1%d%e%p1%{32}%+%d;1%;m -< - *TTpro-telnet* -These settings should work for TTpro telnet. Tera Term Pro is a freeware / -open-source program for MS-Windows. > - set t_Co=16 - set t_AB=^[[%?%p1%{8}%<%t%p1%{40}%+%e%p1%{32}%+5;%;%dm - set t_AF=^[[%?%p1%{8}%<%t%p1%{30}%+%e%p1%{22}%+1;%;%dm -Also make sure TTpro's Setup / Window / Full Color is enabled, and make sure -that Setup / Font / Enable Bold is NOT enabled. -(info provided by John Love-Jensen <eljay@Adobe.COM>) - - ============================================================================== 18. When syntax is slow *:syntime* diff --git a/runtime/doc/tabpage.txt b/runtime/doc/tabpage.txt index c299d43927..8f1eb9d8cd 100644 --- a/runtime/doc/tabpage.txt +++ b/runtime/doc/tabpage.txt @@ -10,11 +10,7 @@ The commands which have been added to use multiple tab pages are explained here. Additionally, there are explanations for commands that work differently when used in combination with more than one tab page. -1. Introduction |tab-page-intro| -2. Commands |tab-page-commands| -3. Other items |tab-page-other| -4. Setting 'tabline' |setting-tabline| -5. Setting 'guitablabel' |setting-guitablabel| + Type <M-]> to see the table of contents. ============================================================================== 1. Introduction *tab-page-intro* @@ -54,6 +50,8 @@ right of the labels. In the GUI tab pages line you can use the right mouse button to open menu. |tabline-menu|. +For the related autocommands see |tabnew-autocmd|. + :[count]tabe[dit] *:tabe* *:tabedit* *:tabnew* :[count]tabnew Open a new tab page with an empty window, after the current @@ -129,10 +127,14 @@ something else. :tabc[lose][!] {count} Close tab page {count}. Fails in the same way as `:tabclose` above. > - :-tabclose " close the previous tab page - :+tabclose " close the next tab page - :1tabclose " close the first tab page - :$tabclose " close the last tab page + :-tabclose " close the previous tab page + :+tabclose " close the next tab page + :1tabclose " close the first tab page + :$tabclose " close the last tab page + :tabclose -2 " close the two previous tab page + :tabclose + " close the next tab page + :tabclose 3 " close the third tab page + :tabclose $ " close the last tab page < *:tabo* *:tabonly* :tabo[nly][!] Close all other tab pages. @@ -145,13 +147,20 @@ something else. never abandoned, so changes cannot get lost. > :tabonly " close all tab pages except the current one -:{count}tabo[nly][!] - Close all tab pages except the {count}th one. > - :.tabonly " as above - :-tabonly " close all tab pages except the previous one - :+tabonly " close all tab pages except the next one - :1tabonly " close all tab pages except the first one - :$tabonly " close all tab pages except the last one. +:tabo[nly][!] {count} + Close all tab pages except {count} one. > + :.tabonly " as above + :-tabonly " close all tab pages except the previous + " one + :+tabonly " close all tab pages except the next one + :1tabonly " close all tab pages except the first one + :$tabonly " close all tab pages except the last one + :tabonly - " close all tab pages except the previous + " one + :tabonly +2 " close all tab pages except the two next + " one + :tabonly 1 " close all tab pages except the first one + :tabonly $ " close all tab pages except the last one SWITCHING TO ANOTHER TAB PAGE: @@ -166,7 +175,20 @@ gt *i_CTRL-<PageDown>* *i_<C-PageDown>* Go to the next tab page. Wraps around from the last to the first one. +:{count}tabn[ext] :tabn[ext] {count} + Go to tab page {count}. The first tab page has number one. > + :-tabnext " go to the previous tab page + :+tabnext " go to the next tab page + :+2tabnext " go to the two next tab page + :1tabnext " go to the first tab page + :$tabnext " go to the last tab page + :tabnext $ " as above + :tabnext - " go to the previous tab page + :tabnext -1 " as above + :tabnext + " go to the next tab page + :tabnext +1 " as above + {count}<C-PageDown> {count}gt Go to tab page {count}. The first tab page has number one. @@ -195,6 +217,12 @@ Other commands: :tabs List the tab pages and the windows they contain. Shows a ">" for the current window. Shows a "+" for modified buffers. + For example: + Tab page 1 ~ + + tabpage.txt ~ + ex_docmd.c ~ + Tab page 2 ~ + > main.c ~ REORDERING TAB PAGES: @@ -273,6 +301,7 @@ Variables local to a tab page start with "t:". |tabpage-variable| Currently there is only one option local to a tab page: 'cmdheight'. + *tabnew-autocmd* The TabLeave and TabEnter autocommand events can be used to do something when switching from one tab page to another. The exact order depends on what you are doing. When creating a new tab page this works as if you create a new diff --git a/runtime/doc/tagsrch.txt b/runtime/doc/tagsrch.txt index 2c090a66fa..d5a4f4e627 100644 --- a/runtime/doc/tagsrch.txt +++ b/runtime/doc/tagsrch.txt @@ -8,12 +8,7 @@ Tags and special searches *tags-and-searches* See section |29.1| of the user manual for an introduction. -1. Jump to a tag |tag-commands| -2. Tag stack |tag-stack| -3. Tag match list |tag-matchlist| -4. Tags details |tag-details| -5. Tags file format |tags-file-format| -6. Include file searches |include-search| + Type <M-]> to see the table of contents. ============================================================================== 1. Jump to a tag *tag-commands* @@ -90,7 +85,7 @@ The ignore-case matches are not found for a ":tag" command when: - 'tagcase' is "followscs" and 'smartcase' option is on and the pattern contains an upper case character. -The gnore-case matches are found when: +The ignore-case matches are found when: - a pattern is used (starting with a "/") - for ":tselect" - when 'tagcase' is "followic" and 'ignorecase' is off @@ -432,9 +427,9 @@ The next file in the list is not used when: This also depends on whether case is ignored. Case is ignored when: - 'tagcase' is "followic" and 'ignorecase' is set - 'tagcase' is "ignore" -- 'tagcase' is "smart" and and the pattern only contains lower case +- 'tagcase' is "smart" and the pattern only contains lower case characters. -- 'tagcase' is "followscs" and 'smartcase' is set and and the pattern only +- 'tagcase' is "followscs" and 'smartcase' is set and the pattern only contains lower case characters. If case is not ignored, and the tags file only has a match without matching case, the next tags file is searched for a match with matching case. If no @@ -803,24 +798,24 @@ CTRL-W d Open a new window, with the cursor on the first *:search-args* Common arguments for the commands above: -[!] When included, find matches in lines that are recognized as comments. - When excluded, a match is ignored when the line is recognized as a - comment (according to 'comments'), or the match is in a C comment (after - "//" or inside /* */). Note that a match may be missed if a line is - recognized as a comment, but the comment ends halfway through the line. - And if the line is a comment, but it is not recognized (according to - 'comments') a match may be found in it anyway. Example: > +[!] When included, find matches in lines that are recognized as comments. + When excluded, a match is ignored when the line is recognized as a + comment (according to 'comments'), or the match is in a C comment + (after "//" or inside /* */). Note that a match may be missed if a + line is recognized as a comment, but the comment ends halfway the line. + And if the line is a comment, but it is not recognized (according to + 'comments') a match may be found in it anyway. Example: > /* comment foobar */ -< A match for "foobar" is found, because this line is not recognized as a - comment (even though syntax highlighting does recognize it). - Note: Since a macro definition mostly doesn't look like a comment, the - [!] makes no difference for ":dlist", ":dsearch" and ":djump". -[/] A pattern can be surrounded by '/'. Without '/' only whole words are - matched, using the pattern "\<pattern\>". Only after the second '/' a - next command can be appended with '|'. Example: > +< A match for "foobar" is found, because this line is not recognized as + a comment (even though syntax highlighting does recognize it). + Note: Since a macro definition mostly doesn't look like a comment, the + [!] makes no difference for ":dlist", ":dsearch" and ":djump". +[/] A pattern can be surrounded by '/'. Without '/' only whole words are + matched, using the pattern "\<pattern\>". Only after the second '/' a + next command can be appended with '|'. Example: > :isearch /string/ | echo "the last one" -< For a ":djump", ":dsplit", ":dlist" and ":dsearch" command the pattern - is used as a literal string, not as a search pattern. +< For a ":djump", ":dsplit", ":dlist" and ":dsearch" command the pattern + is used as a literal string, not as a search pattern. vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt index 56f57a3819..cdff8760fc 100644 --- a/runtime/doc/term.txt +++ b/runtime/doc/term.txt @@ -4,35 +4,25 @@ VIM REFERENCE MANUAL by Bram Moolenaar -Terminal information *terminal-info* +Terminal information Vim uses information about the terminal you are using to fill the screen and recognize what keys you hit. If this information is not correct, the screen may be messed up or keys may not be recognized. The actions which have to be performed on the screen are accomplished by outputting a string of -characters. Special keys produce a string of characters. These strings are -stored in the terminal options, see |terminal-options|. +characters. -NOTE: Most of this is not used when running the |GUI|. - -1. Startup |startup-terminal| -2. Terminal options |terminal-options| -3. Window size |window-size| -4. Slow and fast terminals |slow-fast-terminal| -5. Using the mouse |mouse-using| + Type <M-]> to see the table of contents. ============================================================================== -1. Startup *startup-terminal* +Startup *startup-terminal* When Vim is started a default terminal type is assumed. for MS-DOS this is the pc terminal, for Unix an ansi terminal. *termcap* *terminfo* *E557* *E558* *E559* On Unix the terminfo database or termcap file is used. This is referred to as -"termcap" in all the documentation. At compile time, when running configure, -the choice whether to use terminfo or termcap is done automatically. When -running Vim the output of ":version" will show |+terminfo| if terminfo is -used. Also see |xterm-screens|. +"termcap" in all the documentation. Settings depending on terminal *term-dependent-settings* @@ -45,25 +35,12 @@ can do this best in your vimrc. Example: > ... vt100, vt102 maps and settings ... endif < - *raw-terminal-mode* -For normal editing the terminal will be put into "raw" mode. The strings -defined with 't_ti' and 't_ks' will be sent to the terminal. Normally this -puts the terminal in a state where the termcap codes are valid and activates -the cursor and function keys. When Vim exits the terminal will be put back -into the mode it was before Vim started. The strings defined with 't_te' and -'t_ke' will be sent to the terminal. - *cs7-problem* Note: If the terminal settings are changed after running Vim, you might have an illegal combination of settings. This has been reported on Solaris 2.5 with "stty cs8 parenb", which is restored as "stty cs7 parenb". Use "stty cs8 -parenb -istrip" instead, this is restored correctly. -Some termcap entries are wrong in the sense that after sending 't_ks' the -cursor keys send codes different from the codes defined in the termcap. To -avoid this you can set 't_ks' (and 't_ke') to empty strings. This must be -done during initialization (see |initialization|), otherwise it's too late. - Many cursor key codes start with an <Esc>. Vim must find out if this is a single hit of the <Esc> key or the start of a cursor key sequence. It waits for a next character to arrive. If it does not arrive within one second a @@ -92,55 +69,6 @@ them as a cursor key. When you type you normally are not that fast, so they are recognized as individual typed commands, even though Vim receives the same sequence of bytes. - *vt100-function-keys* *xterm-function-keys* -An xterm can send function keys F1 to F4 in two modes: vt100 compatible or -not. Because Vim may not know what the xterm is sending, both types of keys -are recognized. The same happens for the <Home> and <End> keys. - normal vt100 ~ - <F1> t_k1 <Esc>[11~ <xF1> <Esc>OP *<xF1>-xterm* - <F2> t_k2 <Esc>[12~ <xF2> <Esc>OQ *<xF2>-xterm* - <F3> t_k3 <Esc>[13~ <xF3> <Esc>OR *<xF3>-xterm* - <F4> t_k4 <Esc>[14~ <xF4> <Esc>OS *<xF4>-xterm* - <Home> t_kh <Esc>[7~ <xHome> <Esc>OH *<xHome>-xterm* - <End> t_@7 <Esc>[4~ <xEnd> <Esc>OF *<xEnd>-xterm* - -When Vim starts, <xF1> is mapped to <F1>, <xF2> to <F2> etc. This means that -by default both codes do the same thing. If you make a mapping for <xF2>, -because your terminal does have two keys, the default mapping is overwritten, -thus you can use the <F2> and <xF2> keys for something different. - - *xterm-shifted-keys* -Newer versions of xterm support shifted function keys and special keys. Vim -recognizes most of them. Use ":set termcap" to check which are supported and -what the codes are. Mostly these are not in a termcap, they are only -supported by the builtin_xterm termcap. - - *xterm-modifier-keys* -Newer versions of xterm support Alt and Ctrl for most function keys. To avoid -having to add all combinations of Alt, Ctrl and Shift for every key a special -sequence is recognized at the end of a termcap entry: ";*X". The "X" can be -any character, often '~' is used. The ";*" stands for an optional modifier -argument. ";2" is Shift, ";3" is Alt, ";5" is Ctrl and ";9" is Meta (when -it's different from Alt). They can be combined. Examples: > - :set <F8>=^[[19;*~ - :set <Home>=^[[1;*H -Another speciality about these codes is that they are not overwritten by -another code. That is to avoid that the codes obtained from xterm directly -|t_RV| overwrite them. - *xterm-scroll-region* -The default termcap entry for xterm on Sun and other platforms does not -contain the entry for scroll regions. Add ":cs=\E[%i%d;%dr:" to the xterm -entry in /etc/termcap and everything should work. - - *xterm-end-home-keys* -On some systems (at least on FreeBSD with XFree86 3.1.2) the codes that the -<End> and <Home> keys send contain a <Nul> character. To make these keys send -the proper key code, add these lines to your ~/.Xdefaults file: - -*VT100.Translations: #override \n\ - <Key>Home: string("0x1b") string("[7~") \n\ - <Key>End: string("0x1b") string("[8~") - *xterm-8bit* *xterm-8-bit* Xterm can be run in a mode where it uses 8-bit escape sequences. The CSI code is used instead of <Esc>[. The advantage is that an <Esc> can quickly be @@ -151,309 +79,12 @@ For the builtin termcap entries, Vim checks if the 'term' option contains mouse and a few other things. You would normally set $TERM in your shell to "xterm-8bit" and Vim picks this up and adjusts to the 8-bit setting automatically. -When Vim receives a response to the |t_RV| (request version) sequence and it +When Vim receives a response to the "request version" sequence and it starts with CSI, it assumes that the terminal is in 8-bit mode and will convert all key sequences to their 8-bit variants. ============================================================================== -2. Terminal options *terminal-options* *termcap-options* *E436* - -The terminal options can be set just like normal options. But they are not -shown with the ":set all" command. Instead use ":set termcap". - -It is always possible to change individual strings by setting the -appropriate option. For example: > - :set t_ce=^V^[[K (CTRL-V, <Esc>, [, K) - -The options are listed below. The associated termcap code is always equal to -the last two characters of the option name. Only one termcap code is -required: Cursor motion, 't_cm'. - -The options 't_da', 't_db', 't_ms', 't_xs' represent flags in the termcap. -When the termcap flag is present, the option will be set to "y". But any -non-empty string means that the flag is set. An empty string means that the -flag is not set. 't_CS' works like this too, but it isn't a termcap flag. - -OUTPUT CODES - option meaning ~ - - t_AB set background color (ANSI) *t_AB* *'t_AB'* - t_AF set foreground color (ANSI) *t_AF* *'t_AF'* - t_AL add number of blank lines *t_AL* *'t_AL'* - t_al add new blank line *t_al* *'t_al'* - t_bc backspace character *t_bc* *'t_bc'* - t_cd clear to end of screen *t_cd* *'t_cd'* - t_ce clear to end of line *t_ce* *'t_ce'* - t_cl clear screen *t_cl* *'t_cl'* - t_cm cursor motion (required!) *E437* *t_cm* *'t_cm'* - t_Co number of colors *t_Co* *'t_Co'* - t_CS if non-empty, cursor relative to scroll region *t_CS* *'t_CS'* - t_cs define scrolling region *t_cs* *'t_cs'* - t_CV define vertical scrolling region *t_CV* *'t_CV'* - t_da if non-empty, lines from above scroll down *t_da* *'t_da'* - t_db if non-empty, lines from below scroll up *t_db* *'t_db'* - t_DL delete number of lines *t_DL* *'t_DL'* - t_dl delete line *t_dl* *'t_dl'* - t_fs set window title end (from status line) *t_fs* *'t_fs'* - t_ke exit "keypad transmit" mode *t_ke* *'t_ke'* - t_ks start "keypad transmit" mode *t_ks* *'t_ks'* - t_le move cursor one char left *t_le* *'t_le'* - t_mb blinking mode *t_mb* *'t_mb'* - t_md bold mode *t_md* *'t_md'* - t_me Normal mode (undoes t_mr, t_mb, t_md and color) *t_me* *'t_me'* - t_mr reverse (invert) mode *t_mr* *'t_mr'* - *t_ms* *'t_ms'* - t_ms if non-empty, cursor can be moved in standout/inverse mode - t_nd non destructive space character *t_nd* *'t_nd'* - t_op reset to original color pair *t_op* *'t_op'* - t_RI cursor number of chars right *t_RI* *'t_RI'* - t_Sb set background color *t_Sb* *'t_Sb'* - t_Sf set foreground color *t_Sf* *'t_Sf'* - t_se standout end *t_se* *'t_se'* - t_so standout mode *t_so* *'t_so'* - t_sr scroll reverse (backward) *t_sr* *'t_sr'* - t_te out of "termcap" mode *t_te* *'t_te'* - t_ti put terminal in "termcap" mode *t_ti* *'t_ti'* - t_ts set window title start (to status line) *t_ts* *'t_ts'* - t_ue underline end *t_ue* *'t_ue'* - t_us underline mode *t_us* *'t_us'* - t_Ce undercurl end *t_Ce* *'t_Ce'* - t_Cs undercurl mode *t_Cs* *'t_Cs'* - t_ut clearing uses the current background color *t_ut* *'t_ut'* - t_vb visual bell *t_vb* *'t_vb'* - t_ve cursor visible *t_ve* *'t_ve'* - t_vi cursor invisible *t_vi* *'t_vi'* - t_vs cursor very visible *t_vs* *'t_vs'* - *t_xs* *'t_xs'* - t_xs if non-empty, standout not erased by overwriting (hpterm) - t_ZH italics mode *t_ZH* *'t_ZH'* - t_ZR italics end *t_ZR* *'t_ZR'* - -Added by Vim (there are no standard codes for these): - t_IS set icon text start *t_IS* *'t_IS'* - t_IE set icon text end *t_IE* *'t_IE'* - t_WP set window position (Y, X) in pixels *t_WP* *'t_WP'* - t_WS set window size (height, width) in characters *t_WS* *'t_WS'* - t_SI start insert mode (bar cursor shape) *t_SI* *'t_SI'* - t_EI end insert mode (block cursor shape) *t_EI* *'t_EI'* - |termcap-cursor-shape| - t_RV request terminal version string (for xterm) *t_RV* *'t_RV'* - |xterm-8bit| |v:termresponse| |xterm-codes| - t_u7 request cursor position (for xterm) *t_u7* *'t_u7'* - see |'ambiwidth'| - -KEY CODES -Note: Use the <> form if possible - - option name meaning ~ - - t_ku <Up> arrow up *t_ku* *'t_ku'* - t_kd <Down> arrow down *t_kd* *'t_kd'* - t_kr <Right> arrow right *t_kr* *'t_kr'* - t_kl <Left> arrow left *t_kl* *'t_kl'* - <xUp> alternate arrow up *<xUp>* - <xDown> alternate arrow down *<xDown>* - <xRight> alternate arrow right *<xRight>* - <xLeft> alternate arrow left *<xLeft>* - <S-Up> shift arrow up - <S-Down> shift arrow down - t_%i <S-Right> shift arrow right *t_%i* *'t_%i'* - t_#4 <S-Left> shift arrow left *t_#4* *'t_#4'* - t_k1 <F1> function key 1 *t_k1* *'t_k1'* - <xF1> alternate F1 *<xF1>* - t_k2 <F2> function key 2 *<F2>* *t_k2* *'t_k2'* - <xF2> alternate F2 *<xF2>* - t_k3 <F3> function key 3 *<F3>* *t_k3* *'t_k3'* - <xF3> alternate F3 *<xF3>* - t_k4 <F4> function key 4 *<F4>* *t_k4* *'t_k4'* - <xF4> alternate F4 *<xF4>* - t_k5 <F5> function key 5 *<F5>* *t_k5* *'t_k5'* - t_k6 <F6> function key 6 *<F6>* *t_k6* *'t_k6'* - t_k7 <F7> function key 7 *<F7>* *t_k7* *'t_k7'* - t_k8 <F8> function key 8 *<F8>* *t_k8* *'t_k8'* - t_k9 <F9> function key 9 *<F9>* *t_k9* *'t_k9'* - t_k; <F10> function key 10 *<F10>* *t_k;* *'t_k;'* - t_F1 <F11> function key 11 *<F11>* *t_F1* *'t_F1'* - t_F2 <F12> function key 12 *<F12>* *t_F2* *'t_F2'* - t_F3 <F13> function key 13 *<F13>* *t_F3* *'t_F3'* - t_F4 <F14> function key 14 *<F14>* *t_F4* *'t_F4'* - t_F5 <F15> function key 15 *<F15>* *t_F5* *'t_F5'* - t_F6 <F16> function key 16 *<F16>* *t_F6* *'t_F6'* - t_F7 <F17> function key 17 *<F17>* *t_F7* *'t_F7'* - t_F8 <F18> function key 18 *<F18>* *t_F8* *'t_F8'* - t_F9 <F19> function key 19 *<F19>* *t_F9* *'t_F9'* - <S-F1> shifted function key 1 - <S-xF1> alternate <S-F1> *<S-xF1>* - <S-F2> shifted function key 2 *<S-F2>* - <S-xF2> alternate <S-F2> *<S-xF2>* - <S-F3> shifted function key 3 *<S-F3>* - <S-xF3> alternate <S-F3> *<S-xF3>* - <S-F4> shifted function key 4 *<S-F4>* - <S-xF4> alternate <S-F4> *<S-xF4>* - <S-F5> shifted function key 5 *<S-F5>* - <S-F6> shifted function key 6 *<S-F6>* - <S-F7> shifted function key 7 *<S-F7>* - <S-F8> shifted function key 8 *<S-F8>* - <S-F9> shifted function key 9 *<S-F9>* - <S-F10> shifted function key 10 *<S-F10>* - <S-F11> shifted function key 11 *<S-F11>* - <S-F12> shifted function key 12 *<S-F12>* - t_%1 <Help> help key *t_%1* *'t_%1'* - t_&8 <Undo> undo key *t_&8* *'t_&8'* - t_kI <Insert> insert key *t_kI* *'t_kI'* - t_kD <Del> delete key *t_kD* *'t_kD'* - t_kb <BS> backspace key *t_kb* *'t_kb'* - t_kB <S-Tab> back-tab (shift-tab) *<S-Tab>* *t_kB* *'t_kB'* - t_kh <Home> home key *t_kh* *'t_kh'* - t_#2 <S-Home> shifted home key *<S-Home>* *t_#2* *'t_#2'* - <xHome> alternate home key *<xHome>* - t_@7 <End> end key *t_@7* *'t_@7'* - t_*7 <S-End> shifted end key *<S-End>* *t_star7* *'t_star7'* - <xEnd> alternate end key *<xEnd>* - t_kP <PageUp> page-up key *t_kP* *'t_kP'* - t_kN <PageDown> page-down key *t_kN* *'t_kN'* - t_K1 <kHome> keypad home key *t_K1* *'t_K1'* - t_K4 <kEnd> keypad end key *t_K4* *'t_K4'* - t_K3 <kPageUp> keypad page-up key *t_K3* *'t_K3'* - t_K5 <kPageDown> keypad page-down key *t_K5* *'t_K5'* - t_K6 <kPlus> keypad plus key *<kPlus>* *t_K6* *'t_K6'* - t_K7 <kMinus> keypad minus key *<kMinus>* *t_K7* *'t_K7'* - t_K8 <kDivide> keypad divide *<kDivide>* *t_K8* *'t_K8'* - t_K9 <kMultiply> keypad multiply *<kMultiply>* *t_K9* *'t_K9'* - t_KA <kEnter> keypad enter key *<kEnter>* *t_KA* *'t_KA'* - t_KB <kPoint> keypad decimal point *<kPoint>* *t_KB* *'t_KB'* - t_KC <k0> keypad 0 *<k0>* *t_KC* *'t_KC'* - t_KD <k1> keypad 1 *<k1>* *t_KD* *'t_KD'* - t_KE <k2> keypad 2 *<k2>* *t_KE* *'t_KE'* - t_KF <k3> keypad 3 *<k3>* *t_KF* *'t_KF'* - t_KG <k4> keypad 4 *<k4>* *t_KG* *'t_KG'* - t_KH <k5> keypad 5 *<k5>* *t_KH* *'t_KH'* - t_KI <k6> keypad 6 *<k6>* *t_KI* *'t_KI'* - t_KJ <k7> keypad 7 *<k7>* *t_KJ* *'t_KJ'* - t_KK <k8> keypad 8 *<k8>* *t_KK* *'t_KK'* - t_KL <k9> keypad 9 *<k9>* *t_KL* *'t_KL'* - <Mouse> leader of mouse code *<Mouse>* - -Note about t_so and t_mr: When the termcap entry "so" is not present the -entry for "mr" is used. And vice versa. The same is done for "se" and "me". -If your terminal supports both inversion and standout mode, you can see two -different modes. If your terminal supports only one of the modes, both will -look the same. - - *keypad-comma* -The keypad keys, when they are not mapped, behave like the equivalent normal -key. There is one exception: if you have a comma on the keypad instead of a -decimal point, Vim will use a dot anyway. Use these mappings to fix that: > - :noremap <kPoint> , - :noremap! <kPoint> , -< *xterm-codes* -There is a special trick to obtain the key codes which currently only works -for xterm. When |t_RV| is defined and a response is received which indicates -an xterm with patchlevel 141 or higher, Vim uses special escape sequences to -request the key codes directly from the xterm. The responses are used to -adjust the various t_ codes. This avoids the problem that the xterm can -produce different codes, depending on the mode it is in (8-bit, VT102, -VT220, etc.). The result is that codes like <xF1> are no longer needed. -Note: This is only done on startup. If the xterm options are changed after -Vim has started, the escape sequences may not be recognized anymore. - - *xterm-resize* -Window resizing with xterm only works if the allowWindowOps resource is -enabled. On some systems and versions of xterm it's disabled by default -because someone thought it would be a security issue. It's not clear if this -is actually the case. - -To overrule the default, put this line in your ~/.Xdefaults or -~/.Xresources: -> - XTerm*allowWindowOps: true - -And run "xrdb -merge .Xresources" to make it effective. You can check the -value with the context menu (right mouse button while CTRL key is pressed), -there should be a tick at allow-window-ops. - - *termcap-colors* -Note about colors: The 't_Co' option tells Vim the number of colors available. -When it is non-zero, the 't_AB' and 't_AF' options are used to set the color. -If one of these is not available, 't_Sb' and 't_Sf' are used. 't_me' is used -to reset to the default colors. - - *termcap-cursor-shape* *termcap-cursor-color* -When Vim enters Insert mode the 't_SI' escape sequence is sent. When leaving -Insert mode 't_EI' is used. But only if both are defined. This can be used -to change the shape or color of the cursor in Insert mode. These are not -standard termcap/terminfo entries, you need to set them yourself. -Example for an xterm, this changes the color of the cursor: > - if &term =~ "xterm" - let &t_SI = "\<Esc>]12;purple\x7" - let &t_EI = "\<Esc>]12;blue\x7" - endif -NOTE: When Vim exits the shape for Normal mode will remain. The shape from -before Vim started will not be restored. - - *termcap-title* -The 't_ts' and 't_fs' options are used to set the window title if the terminal -allows title setting via sending strings. They are sent before and after the -title string, respectively. Similar 't_IS' and 't_IE' are used to set the -icon text. These are Vim-internal extensions of the Unix termcap, so they -cannot be obtained from an external termcap. However, the builtin termcap -contains suitable entries for xterm, so you don't need to set them here. - *hpterm* -If inversion or other highlighting does not work correctly, try setting the -'t_xs' option to a non-empty string. This makes the 't_ce' code be used to -remove highlighting from a line. This is required for "hpterm". Setting the -'weirdinvert' option has the same effect as making 't_xs' non-empty, and vice -versa. - - *scroll-region* -Some termcaps do not include an entry for 'cs' (scroll region), although the -terminal does support it. For example: xterm on a Sun. You can use the -builtin_xterm or define t_cs yourself. For example: > - :set t_cs=^V^[[%i%d;%dr -Where ^V is CTRL-V and ^[ is <Esc>. - -The vertical scroll region t_CV is not a standard termcap code. Vim uses it -internally in the GUI. But it can also be defined for a terminal, if you can -find one that supports it. The two arguments are the left and right column of -the region which to restrict the scrolling to. Just like t_cs defines the top -and bottom lines. Defining t_CV will make scrolling in vertically split -windows a lot faster. Don't set t_CV when t_da or t_db is set (text isn't -cleared when scrolling). - -Unfortunately it is not possible to deduce from the termcap how cursor -positioning should be done when using a scrolling region: Relative to the -beginning of the screen or relative to the beginning of the scrolling region. -Most terminals use the first method. The 't_CS' option should be set to any -string when cursor positioning is relative to the start of the scrolling -region. It should be set to an empty string otherwise. - -Note for xterm users: The shifted cursor keys normally don't work. You can - make them work with the xmodmap command and some mappings in Vim. - - Give these commands in the xterm: - xmodmap -e "keysym Up = Up F13" - xmodmap -e "keysym Down = Down F16" - xmodmap -e "keysym Left = Left F18" - xmodmap -e "keysym Right = Right F19" - - And use these mappings in Vim: - :map <t_F3> <S-Up> - :map! <t_F3> <S-Up> - :map <t_F6> <S-Down> - :map! <t_F6> <S-Down> - :map <t_F8> <S-Left> - :map! <t_F8> <S-Left> - :map <t_F9> <S-Right> - :map! <t_F9> <S-Right> - -Instead of, say, <S-Up> you can use any other command that you want to use the -shift-cursor-up key for. (Note: To help people that have a Sun keyboard with -left side keys F14 is not used because it is confused with the undo key; F15 -is not used, because it does a window-to-front; F17 is not used, because it -closes the window. On other systems you can probably use them.) - -============================================================================== -3. Window size *window-size* +Window size *window-size* [This is about the size of the whole window Vim is using, not a window that is created with the ":split" command.] @@ -477,7 +108,7 @@ One command can be used to set the screen size: Detects the screen size and redraws the screen. ============================================================================== -4. Slow and fast terminals *slow-fast-terminal* +Slow and fast terminals *slow-fast-terminal* *slow-terminal* If you have a fast terminal you may like to set the 'ruler' option. The @@ -511,7 +142,7 @@ is sent to the terminal at a time (does not work for MS-DOS). This makes the screen updating a lot slower, making it possible to see what is happening. ============================================================================== -5. Using the mouse *mouse-using* +Using the mouse *mouse-using* This section is about using the mouse on a terminal or a terminal window. How to use the mouse in a GUI window is explained in |gui-mouse|. For scrolling @@ -592,13 +223,9 @@ Bracketed paste mode allows terminal emulators to distinguish between typed text and pasted text. For terminal emulators that support it, this mode is enabled by default. Thus -you can paste text without Neovim giving any special meaning to it. Most -notably it won't try reindenting those lines. - -If your terminal emulator doesn't support it yet, you can get the old Vim -behaviour by enabling |'paste'| temporarily. - -NOTE: See https://cirw.in/blog/bracketed-paste for technical details. +you can paste text without Nvim giving any special meaning to it, e.g. it will +not auto-indent the pasted text. See https://cirw.in/blog/bracketed-paste for +technical details. *mouse-mode-table* *mouse-overview* A short overview of what the mouse buttons do, when 'mousemodel' is "extend": diff --git a/runtime/doc/tips.txt b/runtime/doc/tips.txt index e8dfbaea0b..9b34cd7599 100644 --- a/runtime/doc/tips.txt +++ b/runtime/doc/tips.txt @@ -13,22 +13,7 @@ http://www.vim.org Don't forget to browse the user manual, it also contains lots of useful tips |usr_toc.txt|. -Editing C programs |C-editing| -Finding where identifiers are used |ident-search| -Switching screens in an xterm |xterm-screens| -Scrolling in Insert mode |scroll-insert| -Smooth scrolling |scroll-smooth| -Correcting common typing mistakes |type-mistakes| -Counting words, lines, etc. |count-items| -Restoring the cursor position |restore-position| -Renaming files |rename-files| -Change a name in multiple files |change-name| -Speeding up external commands |speed-up| -Useful mappings |useful-mappings| -Compressing the help files |gzip-helpfile| -Hex editing |hex-editing| -Using <> notation in autocommands |autocmd-<>| -Highlighting matching parens |match-parens| + Type <M-]> to see the table of contents. ============================================================================== Editing C programs *C-editing* @@ -119,48 +104,6 @@ archive file on your closest gnu-ftp-mirror). [the idea for this comes from Andreas Kutschera] ============================================================================== -Switching screens in an xterm *xterm-screens* *xterm-save-screen* - -(From comp.editors, by Juergen Weigert, in reply to a question) - -:> Another question is that after exiting vim, the screen is left as it -:> was, i.e. the contents of the file I was viewing (editing) was left on -:> the screen. The output from my previous like "ls" were lost, -:> ie. no longer in the scrolling buffer. I know that there is a way to -:> restore the screen after exiting vim or other vi like editors, -:> I just don't know how. Helps are appreciated. Thanks. -: -:I imagine someone else can answer this. I assume though that vim and vi do -:the same thing as each other for a given xterm setup. - -They not necessarily do the same thing, as this may be a termcap vs. -terminfo problem. You should be aware that there are two databases for -describing attributes of a particular type of terminal: termcap and -terminfo. This can cause differences when the entries differ AND when of -the programs in question one uses terminfo and the other uses termcap -(also see |+terminfo|). - -In your particular problem, you are looking for the control sequences -^[[?47h and ^[[?47l. These switch between xterms alternate and main screen -buffer. As a quick workaround a command sequence like > - echo -n "^[[?47h"; vim ... ; echo -n "^[[?47l" -may do what you want. (My notation ^[ means the ESC character, further down -you'll see that the databases use \E instead). - -On startup, vim echoes the value of the termcap variable ti (terminfo: -smcup) to the terminal. When exiting, it echoes te (terminfo: rmcup). Thus -these two variables are the correct place where the above mentioned control -sequences should go. - -Compare your xterm termcap entry (found in /etc/termcap) with your xterm -terminfo entry (retrieved with "infocmp -C xterm"). Both should contain -entries similar to: > - :te=\E[2J\E[?47l\E8:ti=\E7\E[?47h: - -PS: If you find any difference, someone (your sysadmin?) should better check - the complete termcap and terminfo database for consistency. - -============================================================================== Scrolling in Insert mode *scroll-insert* If you are in insert mode and you want to see something that is just off the diff --git a/runtime/doc/undo.txt b/runtime/doc/undo.txt index e40be6b250..cbce868cec 100644 --- a/runtime/doc/undo.txt +++ b/runtime/doc/undo.txt @@ -8,12 +8,7 @@ Undo and redo *undo-redo* The basics are explained in section |02.5| of the user manual. -1. Undo and redo commands |undo-commands| -2. Two ways of undo |undo-two-ways| -3. Undo blocks |undo-blocks| -4. Undo branches |undo-branches| -5. Undo persistence |undo-persistence| -6. Remarks about undo |undo-remarks| + Type <M-]> to see the table of contents. ============================================================================== 1. Undo and redo commands *undo-commands* diff --git a/runtime/doc/usr_03.txt b/runtime/doc/usr_03.txt index f2e523e784..5a7f0cb0e5 100644 --- a/runtime/doc/usr_03.txt +++ b/runtime/doc/usr_03.txt @@ -182,7 +182,7 @@ the following: This tells you that you might want to fix something on line 33. So how do you find line 33? One way is to do "9999k" to go to the top of the file and "32j" -to go down thirty two lines. It is not a good way, but it works. A much +to go down thirty-two lines. It is not a good way, but it works. A much better way of doing things is to use the "G" command. With a count, this command positions you at the given line number. For example, "33G" puts you on line 33. (For a better way of going through a compiler's error list, see diff --git a/runtime/doc/usr_06.txt b/runtime/doc/usr_06.txt index fb02fe2683..48f672be78 100644 --- a/runtime/doc/usr_06.txt +++ b/runtime/doc/usr_06.txt @@ -55,8 +55,7 @@ There can be a number of reasons why you don't see colors: - Your terminal does not support colors. Vim will use bold, italic and underlined text, but this doesn't look very nice. You probably will want to try to get a terminal with - colors. For Unix, I recommend the xterm from the XFree86 project: - |xfree-xterm|. + colors. - Your terminal does support colors, but Vim doesn't know this. Make sure your $TERM setting is correct. For example, when using an @@ -68,9 +67,7 @@ There can be a number of reasons why you don't see colors: TERM=xterm-color; export TERM -< The terminal name must match the terminal you are using. If it - still doesn't work, have a look at |xterm-color|, which shows a few - ways to make Vim display colors (not only for an xterm). +< The terminal name must match the terminal you are using. - The file type is not recognized. Vim doesn't know all file types, and sometimes it's near to impossible diff --git a/runtime/doc/usr_22.txt b/runtime/doc/usr_22.txt index 8d11be11b2..255211f668 100644 --- a/runtime/doc/usr_22.txt +++ b/runtime/doc/usr_22.txt @@ -93,7 +93,7 @@ browser. This is what you get: > o................Browsing with a Horizontal Split...........|netrw-o| p................Use Preview Window.........................|netrw-p| P................Edit in Previous Window....................|netrw-p| - q................Listing Bookmarks and History..............|netrw-q| + q................Listing Bookmarks and History..............|netrw-qb| r................Reversing Sorting Order....................|netrw-r| < (etc) diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt index 10d2a8cddd..acb6fd0fa4 100644 --- a/runtime/doc/usr_41.txt +++ b/runtime/doc/usr_41.txt @@ -953,6 +953,7 @@ Various: *various-functions* luaeval() evaluate Lua expression py3eval() evaluate Python expression (|+python3|) pyeval() evaluate Python expression (|+python|) + pyxeval() evaluate |python_x| expression ============================================================================== *41.7* Defining a function diff --git a/runtime/doc/usr_toc.txt b/runtime/doc/usr_toc.txt index 0dce3eac83..ed14d78d22 100644 --- a/runtime/doc/usr_toc.txt +++ b/runtime/doc/usr_toc.txt @@ -48,9 +48,8 @@ Tuning Vim Reference manual |reference_toc| More detailed information for all commands -The user manual is available as a single, ready to print HTML and PDF file -here: - http://vimdoc.sf.net +The user manual is online: + https://neovim.io/doc/user ============================================================================== Getting Started ~ diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt index fd81064d5b..e8da7eeb89 100644 --- a/runtime/doc/various.txt +++ b/runtime/doc/various.txt @@ -6,8 +6,7 @@ Various commands *various* -1. Various commands |various-cmds| -2. Using Vim like less or more |less| + Type <M-]> to see the table of contents. ============================================================================== 1. Various commands *various-cmds* @@ -85,6 +84,8 @@ g8 Print the hex values of the bytes used in the on paper see |:hardcopy|. In the GUI you can use the File.Print menu entry. See |ex-flags| for [flags]. + The |:filter| command can be used to only show lines + matching a pattern. :[range]p[rint] {count} [flags] Print {count} lines, starting with [range] (default @@ -311,7 +312,6 @@ N *+comments* |'comments'| support B *+conceal* "conceal" support, see |conceal| |:syn-conceal| etc. B *+cscope* |cscope| support m *+cursorbind* |'cursorbind'| support -m *+cursorshape* |termcap-cursor-shape| support m *+debug* Compiled for debugging. N *+dialog_gui* Support for |:confirm| with GUI dialog. N *+dialog_con* Support for |:confirm| with console dialog. @@ -367,14 +367,12 @@ N *+statusline* Options 'statusline', 'rulerformat' and special formats of 'titlestring' and 'iconstring' N *+syntax* Syntax highlighting |syntax| N *+tablineat* 'tabline' option recognizing %@Func@ items. -N *+tag_binary* binary searching in tags file |tag-binary-search| +T *+tag_binary* binary searching in tags file |tag-binary-search| N *+tag_old_static* old method for static tags |tag-old-static| m *+tag_any_white* any white space allowed in tags file |tag-any-white| B *+termguicolors* 24-bit color in xterm-compatible terminals support - *+terminfo* uses |terminfo| instead of termcap N *+termresponse* support for |t_RV| and |v:termresponse| N *+textobjects* |text-objects| selection - *+tgetent* non-Unix only: able to use external termcap N *+timers* the |timer_start()| function N *+title* Setting the window 'title' and 'icon' N *+toolbar* |gui-toolbar| @@ -461,6 +459,29 @@ m *+xpm_w32* Win32 GUI only: pixmap support |w32-xpm-support| :redi[r] END End redirecting messages. + *:filt* *:filter* +:filt[er][!] {pat} {command} +:filt[er][!] /{pat}/ {command} + Restrict the output of {command} to lines matching + with {pat}. For example, to list only xml files: > + :filter /\.xml$/ oldfiles +< If the [!] is given, restrict the output of {command} + to lines that do NOT match {pat}. + + {pat} is a Vim search pattern. Instead of enclosing + it in / any non-ID character (see |'isident'|) can be + used, so long as it does not appear in {pat}. Without + the enclosing character the pattern cannot include the + bar character. + + The pattern is matched against the relevant part of + the output, not necessarily the whole line. Only some + commands support filtering, try it out to check if it + works. + + Only normal messages are filtered, error messages are + not. + *:sil* *:silent* *:silent!* :sil[ent][!] {command} Execute {command} silently. Normal messages will not be given or added to the message history. diff --git a/runtime/doc/vi_diff.txt b/runtime/doc/vi_diff.txt index 1a108caeaf..b8bfcaa586 100644 --- a/runtime/doc/vi_diff.txt +++ b/runtime/doc/vi_diff.txt @@ -6,8 +6,7 @@ Differences between Vim and Vi *vi-differences* -1. Limits |limits| -2. The most interesting additions |vim-additions| + Type <M-]> to see the table of contents. ============================================================================== 1. Limits *limits* @@ -60,7 +59,7 @@ Support for different systems. - Windows (XP SP 2 or greater) - OS X -Multi level undo. |undo| +Multi level persistent undo. |undo| 'u' goes backward in time, 'CTRL-R' goes forward again. Set option 'undolevels' to the number of changes to be remembered (default 1000). Set 'undolevels' to 0 for a Vi-compatible one level undo. Set it to @@ -71,6 +70,9 @@ Multi level undo. |undo| create a branch in the undo tree. This means you can go back to any state of the text, there is no risk of a change causing text to be lost forever. |undo-tree| + The undo information is stored in a file when the 'undofile' option is + set. This means you can exit Vim, start Vim on a previously edited + file and undo changes that were made before exiting Vim. Graphical User Interface (GUI). |gui| Included support for GUI: menu's, mouse, scrollbars, etc. You can @@ -124,6 +126,13 @@ Plugins. |add-plugin| right directory. That's an easy way to start using Vim scripts written by others. Plugins can be for all kind of files, or specifically for a filetype. + Packages make this even easier. |packages| + +Asynchronous communication and timers. |job-control| |timer| + Vim can exchange messages with other processes in the background. + Vim can start a job, communicate with it and stop it. |job-control| + Timers can fire once or repeatedly and invoke a function to do any + work. |timer| Repeat a series of commands. |q| "q{c}" starts recording typed characters into named register {c}. diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index 1fadefb8c7..e6184fd528 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -10,13 +10,7 @@ Throughout the help files, differences between Nvim and Vim are indicated via the "{Nvim}" tag. This document is a complete and centralized list of all these differences. -1. Configuration |nvim-configuration| -2. Defaults |nvim-defaults| -3. New features |nvim-features| -4. Changed features |nvim-features-changed| -5. Missing legacy features |nvim-features-missing| -6. Removed features |nvim-features-removed| - + Type <M-]> to see the table of contents. ============================================================================== 1. Configuration *nvim-configuration* @@ -65,7 +59,6 @@ these differences. ============================================================================== 3. New Features *nvim-features* - MAJOR COMPONENTS ~ Embedded terminal emulator |terminal-emulator| @@ -77,7 +70,6 @@ Remote plugins |remote-plugin| Python plugins |provider-python| Clipboard integration |provider-clipboard| - USER EXPERIENCE ~ Working intuitively and consistently is a major goal of Nvim. Examples: @@ -100,7 +92,7 @@ editor. Even "legacy" Python and Ruby plugins which use the old Vim interfaces FEATURES ~ -|bracketed-paste-mode| is built-in and enabled by default. +"Outline": Type <M-]> in |:Man| and |:help| pages to see a document outline. |META| (ALT) chords are recognized, even in the terminal. Any |<M-| mapping will work. Some examples: <M-1>, <M-2>, <M-BS>, <M-Del>, <M-Ins>, <M-/>, @@ -280,6 +272,11 @@ Ed-compatible mode: ":set noedcompatible" is ignored ":set edcompatible" is an error + *t_xx* *:set-termcap* *termcap-options* *t_AB* *t_Sb* *t_vb* *t_SI* +Nvim does not have special `t_XX` options nor <t_XX> keycodes to configure +terminal capabilities. Instead Nvim treats the terminal as any other UI. For +example, 'guicursor' sets the terminal cursor style if possible. + 'ttyfast': ":set ttyfast" is ignored ":set nottyfast" is an error diff --git a/runtime/doc/visual.txt b/runtime/doc/visual.txt index 9bad1a24a0..e9f5bf91f8 100644 --- a/runtime/doc/visual.txt +++ b/runtime/doc/visual.txt @@ -11,14 +11,7 @@ operator. It is the only way to select a block of text. This is introduced in section |04.4| of the user manual. -1. Using Visual mode |visual-use| -2. Starting and stopping Visual mode |visual-start| -3. Changing the Visual area |visual-change| -4. Operating on the Visual area |visual-operators| -5. Blockwise operators |blockwise-operators| -6. Repeating |visual-repeat| -7. Examples |visual-examples| -8. Select mode |Select-mode| + Type <M-]> to see the table of contents. ============================================================================== 1. Using Visual mode *visual-use* diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt index 4ed7b68194..1941ac0972 100644 --- a/runtime/doc/windows.txt +++ b/runtime/doc/windows.txt @@ -13,18 +13,7 @@ differently when used in combination with more than one window. The basics are explained in chapter 7 and 8 of the user manual |usr_07.txt| |usr_08.txt|. -1. Introduction |windows-intro| -2. Starting Vim |windows-starting| -3. Opening and closing a window |opening-window| -4. Moving cursor to other windows |window-move-cursor| -5. Moving windows around |window-moving| -6. Window resizing |window-resize| -7. Argument and buffer list commands |buffer-list| -8. Do a command in all buffers or windows |list-repeat| -9. Tag or file name under the cursor |window-tag| -10. The preview window |preview-window| -11. Using hidden buffers |buffer-hidden| -12. Special kinds of buffers |special-buffers| + Type <M-]> to see the table of contents. ============================================================================== 1. Introduction *windows-intro* *window* @@ -69,7 +58,7 @@ places where a Normal mode command can't be used or is inconvenient. The main Vim window can hold several split windows. There are also tab pages |tab-page|, each of which can hold multiple windows. - + *window-ID* *winid* *windowid* Each window has a unique identifier called the window ID. This identifier will not change within a Vim session. The |win_getid()| and |win_id2tabwin()| functions can be used to convert between the window/tab number and the @@ -287,7 +276,7 @@ CTRL-W CTRL-Q *CTRL-W_CTRL-Q* :1quit " quit the first window :$quit " quit the last window :9quit " quit the last window - " if there are less than 9 windows opened + " if there are fewer than 9 windows opened :-quit " quit the previous window :+quit " quit the next window :+2quit " quit the second next window @@ -1026,6 +1015,10 @@ list of buffers. |unlisted-buffer| h+ hidden buffers which are modified a+ active buffers which are modified + When using |:filter| the pattern is matched against the + displayed buffer name, e.g.: > + filter /\.vim/ ls +< *:bad* *:badd* :bad[d] [+lnum] {fname} Add file name {fname} to the buffer list, without loading it. |