diff options
Diffstat (limited to 'runtime/doc')
67 files changed, 4320 insertions, 2757 deletions
diff --git a/runtime/doc/Makefile b/runtime/doc/Makefile index 7423e63673..dabbcd08d9 100644 --- a/runtime/doc/Makefile +++ b/runtime/doc/Makefile @@ -6,32 +6,14 @@ AWK = awk -# Set to $(VIMTARGET) when executed from src/Makefile. -VIMEXE = vim - DOCS = $(wildcard *.txt) HTMLS = $(DOCS:.txt=.html) .SUFFIXES: .SUFFIXES: .c .o .txt .html -all: tags html - -# Use Vim to generate the tags file. Can only be used when Vim has been -# compiled and installed. Supports multiple languages. -vimtags: $(DOCS) - $(VIMEXE) -u NONE -es -c "helptags ++t ." -c quit - -# Use "doctags" to generate the tags file. Only works for English! -tags: doctags $(DOCS) - ./doctags $(DOCS) | LANG=C LC_ALL=C sort >tags - uniq -d -2 tags - -doctags: doctags.c - $(CC) doctags.c -o doctags - # Awk version of .txt to .html conversion. -html: noerrors tags $(HTMLS) +html: noerrors $(HTMLS) @if test -f errors.log; then cat errors.log; fi noerrors: @@ -54,5 +36,5 @@ tags.ref tags.html: tags $(AWK) -f maketags.awk tags >tags.html clean: - -rm -f doctags *.html tags.ref $(HTMLS) errors.log + -rm -f *.html tags.ref $(HTMLS) errors.log tags diff --git a/runtime/doc/api-funcs.txt b/runtime/doc/api-funcs.txt new file mode 100644 index 0000000000..706941fd12 --- /dev/null +++ b/runtime/doc/api-funcs.txt @@ -0,0 +1,716 @@ +*api-funcs.txt* Neovim API Function Reference {Nvim} + +Note: This documentation is generated from Neovim's API source code. + +Contents: + +1. Global Functions |api-global| +2. Buffer Functions |api-buffer| +3. Window Functions |api-window| +4. Tabpage Functions |api-tabpage| +5. UI Functions |api-ui| + +============================================================================== +1. Global Functions *api-global* + +nvim_command({command}) *nvim_command()* + Executes an ex-command. On VimL error: Returns the VimL error; + v:errmsg is not updated. + + Parameters:~ + {command} Ex-command string + +nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()* + Passes input keys to Nvim. On VimL error: Does not fail, but + updates v:errmsg. + + Parameters:~ + {keys} to be typed + {mode} mapping options + {escape_csi} If true, escape K_SPECIAL/CSI bytes in + `keys` + +nvim_input({keys}) *nvim_input()* + Passes keys to Nvim as raw user-input. On VimL error: Does not + fail, but updates v:errmsg. + + Unlike `nvim_feedkeys`, this uses a lower-level input buffer + and the call is not deferred. This is the most reliable way to + emulate real user input. + + Parameters:~ + {keys} to be typed + + Return:~ + Number of bytes actually written (can be fewer than + requested if the buffer becomes full). + + *nvim_replace_termcodes()* +nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special}) + Replaces any terminal codes with the internal representation + +nvim_command_output({str}) *nvim_command_output()* + TODO: Documentation + +nvim_eval({expr}) *nvim_eval()* + Evaluates a VimL expression (:help expression). Dictionaries + and Lists are recursively expanded. On VimL error: Returns a + generic error; v:errmsg is not updated. + + Parameters:~ + {expr} VimL expression string + + Return:~ + Evaluation result or expanded object + +nvim_call_function({fname}, {args}) *nvim_call_function()* + Calls a VimL function with the given arguments. On VimL error: + Returns a generic error; v:errmsg is not updated. + + Parameters:~ + {fname} Function to call + {args} Function arguments packed in an Array + + Return:~ + Result of the function call + +nvim_strwidth({str}) *nvim_strwidth()* + Calculates the number of display cells occupied by `text`. + <Tab> counts as one cell. + + Parameters:~ + {text} Some text + + Return:~ + Number of cells + +nvim_list_runtime_paths() *nvim_list_runtime_paths()* + Gets the paths contained in 'runtimepath'. + + Return:~ + List of paths + +nvim_set_current_dir({dir}) *nvim_set_current_dir()* + Changes the global working directory. + + Parameters:~ + {dir} Directory path + +nvim_get_current_line() *nvim_get_current_line()* + Gets the current line + + Parameters:~ + + Return:~ + Current line string + +nvim_set_current_line({line}) *nvim_set_current_line()* + Sets the current line + + Parameters:~ + {line} Line contents + +nvim_del_current_line() *nvim_del_current_line()* + Deletes the current line + + Parameters:~ + +nvim_get_var({name}) *nvim_get_var()* + Gets a global (g:) variable + + Parameters:~ + {name} Variable name + + Return:~ + Variable value + +nvim_set_var({name}, {value}) *nvim_set_var()* + Sets a global (g:) variable + + Parameters:~ + {name} Variable name + {value} Variable value + +nvim_del_var({name}) *nvim_del_var()* + Removes a global (g:) variable + + Parameters:~ + {name} Variable name + +nvim_get_vvar({name}) *nvim_get_vvar()* + Gets a v: variable + + Parameters:~ + {name} Variable name + + Return:~ + Variable value + +nvim_get_option({name}) *nvim_get_option()* + Gets an option value string + + Parameters:~ + {name} Option name + + Return:~ + Option value + +nvim_set_option({name}, {value}) *nvim_set_option()* + Sets an option value + + Parameters:~ + {name} Option name + {value} New option value + +nvim_out_write({str}) *nvim_out_write()* + Writes a message to vim output buffer + + Parameters:~ + {str} Message + +nvim_err_write({str}) *nvim_err_write()* + Writes a message to vim error buffer + + Parameters:~ + {str} Message + +nvim_err_writeln({str}) *nvim_err_writeln()* + Writes a message to vim error buffer. Appends a linefeed to + ensure all contents are written. + + Parameters:~ + {str} Message + +nvim_list_bufs() *nvim_list_bufs()* + Gets the current list of buffer handles + + Return:~ + List of buffer handles + +nvim_get_current_buf() *nvim_get_current_buf()* + Gets the current buffer + + Return:~ + Buffer handle + +nvim_set_current_buf({buffer}) *nvim_set_current_buf()* + Sets the current buffer + + Parameters:~ + {id} Buffer handle + +nvim_list_wins() *nvim_list_wins()* + Gets the current list of window handles + + Return:~ + List of window handles + +nvim_get_current_win() *nvim_get_current_win()* + Gets the current window + + Return:~ + Window handle + +nvim_set_current_win({window}) *nvim_set_current_win()* + Sets the current window + + Parameters:~ + {handle} Window handle + +nvim_list_tabpages() *nvim_list_tabpages()* + Gets the current list of tabpage handles + + Return:~ + List of tabpage handles + +nvim_get_current_tabpage() *nvim_get_current_tabpage()* + Gets the current tabpage + + Return:~ + Tabpage handle + +nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()* + Sets the current tabpage + + Parameters:~ + {handle} Tabpage handle + +nvim_subscribe({event}) *nvim_subscribe()* + Subscribes to event broadcasts + + Parameters:~ + {event} Event type string + +nvim_unsubscribe({event}) *nvim_unsubscribe()* + Unsubscribes to event broadcasts + + Parameters:~ + {event} Event type string + +nvim_get_color_by_name({name}) *nvim_get_color_by_name()* + TODO: Documentation + +nvim_get_color_map() *nvim_get_color_map()* + TODO: Documentation + +nvim_get_api_info() *nvim_get_api_info()* + TODO: Documentation + +nvim_call_atomic({calls}) *nvim_call_atomic()* + Call many api methods atomically + + This has two main usages: Firstly, to perform several requests + from an async context atomically, i.e. without processing + requests from other rpc clients or redrawing or allowing user + interaction in between. Note that api methods that could fire + autocommands or do event processing still might do so. For + instance invoking the :sleep command might call timer + callbacks. Secondly, it can be used to reduce rpc overhead + (roundtrips) when doing many requests in sequence. + + Parameters:~ + {calls} an array of calls, where each call is described + by an array with two elements: the request name, + and an array of arguments. + + Return:~ + an array with two elements. The first is an array of + return values. The second is NIL if all calls succeeded. + If a call resulted in an error, it is a three-element + array with the zero-based index of the call which resulted + in an error, the error type and the error message. If an + error ocurred, the values from all preceding calls will + still be returned. + + +============================================================================== +2. Buffer Functions *api-buffer* + +nvim_buf_line_count({buffer}) *nvim_buf_line_count()* + Gets the buffer line count + + Parameters:~ + {buffer} Buffer handle + + Return:~ + Line count + + *nvim_buf_get_lines()* +nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing}) + Retrieves a line range from the buffer + + Indexing is zero-based, end-exclusive. Negative indices are + interpreted as length+1+index, i e -1 refers to the index past + the end. So to get the last element set start=-2 and end=-1. + + Out-of-bounds indices are clamped to the nearest valid value, + unless `strict_indexing` is set. + + Parameters:~ + {buffer} Buffer handle + {start} First line index + {end} Last line index (exclusive) + {strict_indexing} Whether out-of-bounds should be an + error. + + Return:~ + Array of lines + + *nvim_buf_set_lines()* +nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, + {replacement}) + Replaces line range on the buffer + + Indexing is zero-based, end-exclusive. Negative indices are + interpreted as length+1+index, i e -1 refers to the index past + the end. So to change or delete the last element set start=-2 + and end=-1. + + To insert lines at a given index, set both start and end to + the same index. To delete a range of lines, set replacement to + an empty array. + + Out-of-bounds indices are clamped to the nearest valid value, + unless `strict_indexing` is set. + + Parameters:~ + {buffer} Buffer handle + {start} First line index + {end} Last line index (exclusive) + {strict_indexing} Whether out-of-bounds should be an + error. + {replacement} Array of lines to use as replacement + +nvim_buf_get_var({buffer}, {name}) *nvim_buf_get_var()* + Gets a buffer-scoped (b:) variable. + + Parameters:~ + {buffer} Buffer handle + {name} Variable name + + Return:~ + Variable value + +nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* + Sets a buffer-scoped (b:) variable + + Parameters:~ + {buffer} Buffer handle + {name} Variable name + {value} Variable value + +nvim_buf_del_var({buffer}, {name}) *nvim_buf_del_var()* + Removes a buffer-scoped (b:) variable + + Parameters:~ + {buffer} Buffer handle + {name} Variable name + +nvim_buf_get_option({buffer}, {name}) *nvim_buf_get_option()* + Gets a buffer option value + + Parameters:~ + {buffer} Buffer handle + {name} Option name + + Return:~ + Option value + +nvim_buf_set_option({buffer}, {name}, {value}) *nvim_buf_set_option()* + Sets a buffer option value. Passing 'nil' as value deletes the + option (only works if there's a global fallback) + + Parameters:~ + {buffer} Buffer handle + {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 + + Parameters:~ + {buffer} Buffer handle + + Return:~ + Buffer name + +nvim_buf_set_name({buffer}, {name}) *nvim_buf_set_name()* + Sets the full file name for a buffer + + Parameters:~ + {buffer} Buffer handle + {name} Buffer name + +nvim_buf_is_valid({buffer}) *nvim_buf_is_valid()* + Checks if a buffer is valid + + Parameters:~ + {buffer} Buffer handle + + Return:~ + true if the buffer is valid, false otherwise + +nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()* + Return a tuple (row,col) representing the position of the + named mark + + Parameters:~ + {buffer} Buffer handle + {name} Mark name + + Return:~ + (row, col) tuple + + *nvim_buf_add_highlight()* +nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line}, + {col_start}, {col_end}) + Adds a highlight to buffer. + + This can be used for plugins which dynamically generate + highlights to a buffer (like a semantic highlighter or + linter). The function adds a single highlight to a buffer. + Unlike matchaddpos() highlights follow changes to line + numbering (as lines are inserted/removed above the highlighted + line), like signs and marks do. + + "src_id" is useful for batch deletion/updating of a set of + highlights. When called with src_id = 0, an unique source id + is generated and returned. Succesive calls can pass in it as + "src_id" to add new highlights to the same source group. All + highlights in the same group can then be cleared with + nvim_buf_clear_highlight. If the highlight never will be + manually deleted pass in -1 for "src_id". + + If "hl_group" is the empty string no highlight is added, but a + new src_id is still returned. This is useful for an external + plugin to synchrounously request an unique src_id at + initialization, and later asynchronously add and clear + highlights in response to buffer changes. + + Parameters:~ + {buffer} Buffer handle + {src_id} Source group to use or 0 to use a new group, + or -1 for ungrouped highlight + {hl_group} Name of the highlight group to use + {line} Line to highlight + {col_start} Start of range of columns to highlight + {col_end} End of range of columns to highlight, or -1 + to highlight to end of line + + Return:~ + The src_id that was used + + *nvim_buf_clear_highlight()* +nvim_buf_clear_highlight({buffer}, {src_id}, {line_start}, {line_end}) + Clears highlights from a given source group and a range of + lines + + To clear a source group in the entire buffer, pass in 1 and -1 + to line_start and line_end respectively. + + Parameters:~ + {buffer} Buffer handle + {src_id} Highlight source group to clear, or -1 to + clear all. + {line_start} Start of range of lines to clear + {line_end} End of range of lines to clear (exclusive) + or -1 to clear to end of file. + + +============================================================================== +3. Window Functions *api-window* + +nvim_win_get_buf({window}) *nvim_win_get_buf()* + Gets the current buffer in a window + + Parameters:~ + {window} Window handle + + Return:~ + Buffer handle + +nvim_win_get_cursor({window}) *nvim_win_get_cursor()* + Gets the cursor position in the window + + Parameters:~ + {window} Window handle + + Return:~ + (row, col) tuple + +nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()* + Sets the cursor position in the window + + Parameters:~ + {window} Window handle + {pos} (row, col) tuple representing the new position + +nvim_win_get_height({window}) *nvim_win_get_height()* + Gets the window height + + Parameters:~ + {window} Window handle + + Return:~ + Height as a count of rows + +nvim_win_set_height({window}, {height}) *nvim_win_set_height()* + Sets the window height. This will only succeed if the screen + is split horizontally. + + Parameters:~ + {window} Window handle + {height} Height as a count of rows + +nvim_win_get_width({window}) *nvim_win_get_width()* + Gets the window width + + Parameters:~ + {window} Window handle + + Return:~ + Width as a count of columns + +nvim_win_set_width({window}, {width}) *nvim_win_set_width()* + Sets the window width. This will only succeed if the screen is + split vertically. + + Parameters:~ + {window} Window handle + {width} Width as a count of columns + +nvim_win_get_var({window}, {name}) *nvim_win_get_var()* + Gets a window-scoped (w:) variable + + Parameters:~ + {window} Window handle + {name} Variable name + + Return:~ + Variable value + +nvim_win_set_var({window}, {name}, {value}) *nvim_win_set_var()* + Sets a window-scoped (w:) variable + + Parameters:~ + {window} Window handle + {name} Variable name + {value} Variable value + +nvim_win_del_var({window}, {name}) *nvim_win_del_var()* + Removes a window-scoped (w:) variable + + Parameters:~ + {window} Window handle + {name} Variable name + +nvim_win_get_option({window}, {name}) *nvim_win_get_option()* + Gets a window option value + + Parameters:~ + {window} Window handle + {name} Option name + + Return:~ + Option value + +nvim_win_set_option({window}, {name}, {value}) *nvim_win_set_option()* + Sets a window option value. Passing 'nil' as value deletes the + option(only works if there's a global fallback) + + Parameters:~ + {window} Window handle + {name} Option name + {value} Option value + +nvim_win_get_position({window}) *nvim_win_get_position()* + Gets the window position in display cells. First position is + zero. + + Parameters:~ + {window} Window handle + + Return:~ + (row, col) tuple with the window position + +nvim_win_get_tabpage({window}) *nvim_win_get_tabpage()* + Gets the window tabpage + + Parameters:~ + {window} Window handle + + Return:~ + Tabpage that contains the window + +nvim_win_get_number({window}) *nvim_win_get_number()* + Gets the window number + + Parameters:~ + {window} Window handle + + Return:~ + Window number + +nvim_win_is_valid({window}) *nvim_win_is_valid()* + Checks if a window is valid + + Parameters:~ + {window} Window handle + + Return:~ + true if the window is valid, false otherwise + + +============================================================================== +4. Tabpage Functions *api-tabpage* + +nvim_tabpage_list_wins({tabpage}) *nvim_tabpage_list_wins()* + Gets the windows in a tabpage + + Parameters:~ + {tabpage} Tabpage + + Return:~ + List of windows in tabpage + +nvim_tabpage_get_var({tabpage}, {name}) *nvim_tabpage_get_var()* + Gets a tab-scoped (t:) variable + + Parameters:~ + {tabpage} Tabpage handle + {name} Variable name + + Return:~ + Variable value + +nvim_tabpage_set_var({tabpage}, {name}, {value}) *nvim_tabpage_set_var()* + Sets a tab-scoped (t:) variable + + Parameters:~ + {tabpage} Tabpage handle + {name} Variable name + {value} Variable value + +nvim_tabpage_del_var({tabpage}, {name}) *nvim_tabpage_del_var()* + Removes a tab-scoped (t:) variable + + Parameters:~ + {tabpage} Tabpage handle + {name} Variable name + +nvim_tabpage_get_win({tabpage}) *nvim_tabpage_get_win()* + Gets the current window in a tabpage + + Parameters:~ + {tabpage} Tabpage handle + + Return:~ + Window handle + +nvim_tabpage_get_number({tabpage}) *nvim_tabpage_get_number()* + Gets the tabpage number + + Parameters:~ + {tabpage} Tabpage handle + + Return:~ + Tabpage number + +nvim_tabpage_is_valid({tabpage}) *nvim_tabpage_is_valid()* + Checks if a tabpage is valid + + Parameters:~ + {tabpage} Tabpage handle + + Return:~ + true if the tabpage is valid, false otherwise + + +============================================================================== +5. UI Functions *api-ui* + +remote_ui_disconnect() *remote_ui_disconnect()* + TODO: Documentation + +nvim_ui_attach({width}, {height}, {options}) *nvim_ui_attach()* + TODO: Documentation + +nvim_ui_detach() *nvim_ui_detach()* + TODO: Documentation + +nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()* + TODO: Documentation + +nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()* + TODO: Documentation + + vim:tw=78:ts=8:ft=help:norl:
\ No newline at end of file diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index ca79465e0d..171b0124f6 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -1,31 +1,32 @@ -*api.txt* For Nvim. {Nvim} +*api.txt* {Nvim} NVIM REFERENCE MANUAL by Thiago de Arruda -The C API of Nvim *nvim-api* -1. Introduction |nvim-api-intro| -2. API Types |nvim-api-types| -3. API metadata |nvim-api-metadata| -4. Buffer highlighting |nvim-api-highlights| +C API for Nvim *API* *api* + +1. Introduction |api-intro| +2. API Types |api-types| +3. API metadata |api-metadata| +4. Buffer highlighting |api-highlights| ============================================================================== -1. Introduction *nvim-api-intro* +1. Introduction *api-intro* -Nvim defines a C API as the primary way for external code to interact with -the NVim core. In the present version of Nvim the API is primarily used by -external processes to interact with Nvim using the msgpack-rpc protocol, see -|msgpack-rpc|. The API will also be used from vimscript to access new Nvim core -features, but this is not implemented yet. Later on, Nvim might be embeddable -in C applications as libnvim, and the application will then control the -embedded instance by calling the C API directly. +Nvim exposes a public API for external code to interact with the Nvim core. +The API is used by external processes to interact with Nvim using the +msgpack-rpc protocol, see |msgpack-rpc|. The API is used from vimscript to +access some new Nvim core features. See |eval-api| for how api functions are +called from vimscript. Later on, Nvim might be embeddable in C applications as +libnvim, and the application will then control the embedded instance by calling +the C API directly. ============================================================================== -2. API Types *nvim-api-types* +2. API Types *api-types* Nvim's C API uses custom types for all functions. Some are just typedefs -around C99 standard types, and some are Nvim defined data structures. +around C99 standard types, and some are Nvim-defined data structures. Boolean -> bool Integer (signed 64-bit integer) -> int64_t @@ -46,19 +47,25 @@ Window -> enum value kObjectTypeWindow Tabpage -> enum value kObjectTypeTabpage ============================================================================== -3. API metadata *nvim-api-metadata* +3. API metadata *api-metadata* -Nvim exposes metadata about the API as a Dictionary with the following keys: +Nvim exposes API metadata as a Dictionary. Some items are described below: -functions calling signature of the API functions -types The custom handle types defined by Nvim -error_types The possible kinds of errors an API function can exit with. +version Nvim version, API level/compatibility +version.api_level Current API level +version.api_compatible API is backwards-compatible with this level +version.api_prerelease Declares the current API level as unstable > + (version.api_prerelease && fn.since == version.api_level) +functions API function signatures +{fn}.since API level where function {fn} was introduced +{fn}.deprecated_since API level where function {fn} was deprecated +types Custom handle types defined by Nvim +error_types Possible error types returned by API functions -This metadata is mostly useful for external programs accessing the api over -msgpack-api, see |msgpack-rpc-api|. +External programs ("clients") can use the metadata to discover the |rpc-api|. ============================================================================== -4. Buffer highlighting *nvim-api-highlights* +4. Buffer highlighting *api-highlights* Nvim allows plugins to add position-based highlights to buffers. This is similar to |matchaddpos()| but with some key differences. The added highlights @@ -72,10 +79,10 @@ Another use case are plugins that show output in an append-only buffer, and want to add highlights to the outputs. Highlight data cannot be preserved on writing and loading a buffer to file, nor in undo/redo cycles. -Highlights are registered using the |buffer_add_highlight| function, see the +Highlights are registered using the |nvim_buf_add_highlight| function, see the generated API documentation for details. If an external highlighter plugin is adding a large number of highlights in a batch, performance can be improved by -calling |buffer_add_highlight| as an asynchronous notification, after first +calling |nvim_buf_add_highlight| as an asynchronous notification, after first (synchronously) reqesting a source id. Here is an example using wrapper functions in the python client: > @@ -90,10 +97,19 @@ functions in the python client: buf.clear_highlight(src) < If the highlights don't need to be deleted or updated, just pass -1 as -src_id (this is the default in python). |buffer_clear_highlight| can be used -to clear highligts from a specific source, in a specific line range or the -entire buffer by passing in the line range 0, -1 (the later is the default +src_id (this is the default in python). |nvim_buf_clear_highlight| can be used +to clear highlights from a specific source, in a specific line range or the +entire buffer by passing in the line range 0, -1 (the latter is the default in python as used above). +An example of calling the api from vimscript: > + + call nvim_buf_set_lines(0, 0, 0, v:true, ["test text"]) + let src = nvim_buf_add_highlight(0, 0, "String", 1, 0, 4) + call nvim_buf_add_highlight(0, src, "Identifier", 0, 5, -1) + + " later + call nvim_buf_clear_highlight(0, src, 0, -1) +> ============================================================================== vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 25ae94f784..180127cd52 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -1,4 +1,4 @@ -*autocmd.txt* For Vim version 7.4. Last change: 2015 Dec 05 +*autocmd.txt* For Vim version 7.4. Last change: 2016 Jun 09 VIM REFERENCE MANUAL by Bram Moolenaar @@ -49,9 +49,6 @@ effects. Be careful not to destroy your text. ============================================================================== 2. Defining autocommands *autocmd-define* -Note: The ":autocmd" command cannot be followed by another command, since any -'|' is considered part of the command. - *:au* *:autocmd* :au[tocmd] [group] {event} {pat} [nested] {cmd} Add {cmd} to the list of commands that Vim will @@ -64,6 +61,12 @@ Note: The ":autocmd" command cannot be followed by another command, since any The special pattern <buffer> or <buffer=N> defines a buffer-local autocommand. See |autocmd-buflocal|. +Note: The ":autocmd" command can only be followed by another command when the +'|' appears before {cmd}. This works: > + :augroup mine | au! BufRead | augroup END +But this sees "augroup" as part of the defined command: > + :augroup mine | au BufRead * set tw=70 | augroup END + Note that special characters (e.g., "%", "<cword>") in the ":autocmd" arguments are not expanded when the autocommand is defined. These will be expanded when the Event is recognized, and the {cmd} is executed. The only @@ -256,7 +259,6 @@ Name triggered by ~ Options |FileType| when the 'filetype' option has been set |Syntax| when the 'syntax' option has been set -|EncodingChanged| after the 'encoding' option has been changed |TermChanged| after the value of 'term' has changed |OptionSet| after setting any option @@ -271,8 +273,10 @@ Name triggered by ~ |VimLeave| before exiting Vim, after writing the shada file Various +|DirChanged| after the |current-directory| was changed + |FileChangedShell| Vim notices that a file changed since editing started -|FileChangedShellPost| After handling a file changed since editing started +|FileChangedShellPost| after handling a file changed since editing started |FileChangedRO| before making the first change to a read-only file |ShellCmdPost| after executing a shell command @@ -292,6 +296,7 @@ Name triggered by ~ |CursorMoved| the cursor was moved in Normal mode |CursorMovedI| the cursor was moved in Insert mode +|WinNew| after creating a new window |WinEnter| after entering another window |WinLeave| before leaving a window |TabEnter| after entering another tab page @@ -542,6 +547,9 @@ CursorHold When the user doesn't press a key for the time *CursorHoldI* CursorHoldI Just like CursorHold, but in Insert mode. + Not triggered when waiting for another key, + e.g. after CTRL-V, and not when in CTRL-X mode + |insert_expand|. *CursorMoved* CursorMoved After the cursor was moved in Normal or Visual @@ -557,9 +565,12 @@ CursorMoved After the cursor was moved in Normal or Visual CursorMovedI After the cursor was moved in Insert mode. Not triggered when the popup menu is visible. Otherwise the same as CursorMoved. - *EncodingChanged* -EncodingChanged Fires off after the 'encoding' option has been - changed. Useful to set up fonts, for example. + *DirChanged* +DirChanged After the |current-directory| was changed. + Sets these |v:event| keys: + cwd: current working directory + scope: "global", "tab", "window" + Recursion is ignored. *FileAppendCmd* FileAppendCmd Before appending to a file. Should do the appending to the file. Use the '[ and '] @@ -618,9 +629,6 @@ FileChangedShell When Vim notices that the modification time of *FileChangedShellPost* FileChangedShellPost After handling a file that was changed outside of Vim. Can be used to update the statusline. - *FileEncoding* -FileEncoding Obsolete. It still works and is equivalent - to |EncodingChanged|. *FileReadCmd* FileReadCmd Before reading a file with a ":read" command. Should do the reading of the file. |Cmd-event| @@ -727,13 +735,12 @@ InsertCharPre When a character is typed in Insert mode, *TextYankPost* TextYankPost Just after a |yank| or |deleting| command, but not if the black hole register |quote_| is used nor - for |setreg()|. Pattern must be * because its - meaning may change in the future. + for |setreg()|. Pattern must be *. Sets these |v:event| keys: - operator - regcontents - regname - regtype + operator + regcontents + regname + regtype Recursion is ignored. It is not allowed to change the text |textlock|. *InsertEnter* @@ -912,8 +919,7 @@ TermClose When a terminal buffer ends. {Nvim} *TermOpen* TermOpen When a terminal buffer is starting. This can be used to configure the terminal emulator by - setting buffer variables. - See |nvim-terminal-emulator| for details. + setting buffer variables. |terminal-emulator| *TermResponse* TermResponse After the response to |t_RV| is received from the terminal. The value of |v:termresponse| @@ -948,7 +954,15 @@ VimEnter After doing all the startup stuff, including loading vimrc files, executing the "-c cmd" arguments, creating all windows and loading the buffers in them. - *VimLeave* + Just before this event is triggered the + |v:vim_did_enter| variable is set, so that you + can do: > + if v:vim_did_enter + call s:init() + else + au VimEnter * call s:init() + endif +< *VimLeave* VimLeave Before exiting Vim, just after writing the .shada file. Executed only once, like VimLeavePre. @@ -986,6 +1000,11 @@ WinLeave Before leaving a window. If the window to be WinLeave autocommands (but not for ":new"). Not used for ":qa" or ":q" when exiting Vim. + *WinNew* +WinNew When a new window was created. Not done for + the fist window, when Vim has just started. + Before a WinEnter event. + ============================================================================== 6. Patterns *autocmd-patterns* *{pat}* @@ -1223,6 +1242,8 @@ option will not cause any commands to be executed. argument is present. You probably want to use <nomodeline> for events that are not used when loading a buffer, such as |User|. + Processing modelines is also skipped when no + matching autocommands were executed. *:doautoa* *:doautoall* :doautoa[ll] [<nomodeline>] [group] {event} [fname] diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt index c8eb0705f6..31a46f53bb 100644 --- a/runtime/doc/change.txt +++ b/runtime/doc/change.txt @@ -1,4 +1,4 @@ -*change.txt* For Vim version 7.4. Last change: 2016 Jan 02 +*change.txt* For Vim version 7.4. Last change: 2016 Apr 12 VIM REFERENCE MANUAL by Bram Moolenaar @@ -97,10 +97,10 @@ These commands delete text. You can repeat them with the `.` command An exception for the d{motion} command: If the motion is not linewise, the start and end of the motion are not in the same line, and there are only -blanks before the start and after the end of the motion, the delete becomes -linewise. This means that the delete also removes the line of blanks that you -might expect to remain. Use the |o_v| operator to force the motion to be -characterwise. +blanks before the start and there are no non-blanks after the end of the +motion, the delete becomes linewise. This means that the delete also removes +the line of blanks that you might expect to remain. Use the |o_v| operator to +force the motion to be characterwise. Trying to delete an empty region of text (e.g., "d0" in the first column) is an error when 'cpoptions' includes the 'E' flag. @@ -108,7 +108,9 @@ is an error when 'cpoptions' includes the 'E' flag. *J* J Join [count] lines, with a minimum of two lines. Remove the indent and insert up to two spaces (see - below). + below). Fails when on the last line of the buffer. + If [count] is too big it is reduce to the number of + lines available. *v_J* {Visual}J Join the highlighted lines, with a minimum of two @@ -396,6 +398,11 @@ 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 @@ -806,7 +813,7 @@ Examples: > :s/abcde/abc^Mde/ modifies "abcde" to "abc", "de" (two lines) :s/$/\^M/ modifies "abcde" to "abcde^M" :s/\w\+/\u\0/g modifies "bla bla" to "Bla Bla" - :s/\w\+/\L\u/g modifies "BLA bla" to "Bla Bla" + :s/\w\+/\L\u\0/g modifies "BLA bla" to "Bla Bla" Note: "\L\u" can be used to capitalize the first letter of a word. This is not compatible with Vi and older versions of Vim, where the "\u" would cancel @@ -1157,7 +1164,7 @@ which does not specify a register. Additionally you can access it with the name '"'. This means you have to type two double quotes. Writing to the "" register writes to register "0. -2. Numbered registers "0 to "9 *quote_number* *quote0* *quote1* +2. Numbered registers "0 to "9 *quote_number* *quote0* *quote1* *quote2* *quote3* *quote4* *quote9* Vim fills these registers with text from yank and delete commands. Numbered register 0 contains the text from the most recent yank command, @@ -1245,7 +1252,7 @@ register. Use these registers for storing and retrieving the selected text for the GUI. See |quotestar| and |quoteplus|. When the clipboard is not available or not working, the unnamed register is used instead. For Unix systems and Mac OS X, -see |nvim-clipboard|. +see |primary-selection|. 9. Black hole register "_ *quote_* When writing to this register, nothing happens. This can be used to delete diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt new file mode 100644 index 0000000000..6997d331e4 --- /dev/null +++ b/runtime/doc/deprecated.txt @@ -0,0 +1,48 @@ +*deprecated.txt* {Nvim} + + + NVIM REFERENCE MANUAL + + +Nvim *deprecated* + +The items listed below are "deprecated". This means they will be removed in +the future. They should not be used in new scripts, and old scripts should be +updated. + +============================================================================== + +Normal commands ~ +*]f* +*[f* Same as "gf". + + +Commands ~ +*:rv* +*:rviminfo* Deprecated alias to |:rshada| command. +*:wv* +*:wviminfo* Deprecated alias to |:wshada| command. + + +Events ~ +*EncodingChanged* Never fired; 'encoding' is always "utf-8". +*FileEncoding* Never fired; equivalent to |EncodingChanged|. + +Highlight groups ~ +*hl-VisualNOS* Obsolete. |vim-differences| {Nvim} + +Functions ~ +*buffer_exists()* Obsolete name for |bufexists()|. +*buffer_name()* Obsolete name for |bufname()|. +*buffer_number()* Obsolete name for |bufnr()|. +*file_readable()* Obsolete name for |filereadable()|. +*highlight_exists()* Obsolete name for |hlexists()|. +*highlightID()* Obsolete name for |hlID()|. +*last_buffer_nr()* Obsolete name for bufnr("$"). + +Options ~ +*'fe'* 'fenc'+'enc' before Vim 6.0; no longer used. +*'vi'* +*'viminfo'* Deprecated alias to 'shada' option. + + vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 668790358b..b738da9bec 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -1,23 +1,19 @@ -*develop.txt* For Vim version 7.4. Last change: 2014 Mar 27 +*develop.txt* - VIM REFERENCE MANUAL by Bram Moolenaar + NVIM REFERENCE MANUAL -Development of Vim. *development* - -This text is important for those who want to be involved in further developing -Vim. +Development of Nvim. *development* 1. Design goals |design-goals| 2. Design decisions |design-decisions| -See the file "src/nvim/README.md" for a high-level overview of the source -code. +Nvim is open source software. Everybody is encouraged to contribute. + https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md -Vim is open source software. Everybody is encouraged to contribute to help -improving Vim. For sending patches a context diff "diff -c" is preferred. -Also see http://vim.wikia.com/wiki/How_to_make_and_submit_a_patch. +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 ============================================================================== 1. Design goals *design-goals* @@ -28,7 +24,7 @@ Note that quite a few items are contradicting. This is intentional. A balance must be found between them. -VIM IS... IMPROVED *design-improved* +NVIM IS... IMPROVED *design-improved* The IMproved bits of Vim should make it a better Vi, without becoming a completely different editor. Extensions are done with a "Vi spirit". @@ -49,7 +45,7 @@ completely different editor. Extensions are done with a "Vi spirit". implement and (3) someone actually implementing it. -VIM IS... MULTI PLATFORM *design-multi-platform* +NVIM IS... MULTI PLATFORM *design-multi-platform* Vim tries to help as many users on as many platforms as possible. - Support many kinds of terminals. The minimal demands are cursor positioning @@ -68,7 +64,7 @@ Vim tries to help as many users on as many platforms as possible. contradicts the previous item, these two must be balanced.] -VIM IS... WELL DOCUMENTED *design-documented* +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. @@ -76,9 +72,14 @@ VIM IS... WELL DOCUMENTED *design-documented* recommended. - 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 + differences from Vim. The {Nvim} annotation is also available + 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|. -VIM IS... HIGH SPEED AND SMALL IN SIZE *design-speed-size* +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. @@ -89,13 +90,11 @@ fast. possible. Useful commands may take longer. - Don't forget that some people use Vim over a slow connection. Minimize the communication overhead. -- Items that add considerably to the size and are not used by many people - should be a feature that can be disabled. - Vim is a component among other components. Don't turn it into a massive application, but have it work well together with other programs. -VIM IS... MAINTAINABLE *design-maintain* +NVIM IS... MAINTAINABLE *design-maintain* - The source code should not become a mess. It should be reliable code. - Use comments in a useful way! Quoting the function name and argument names @@ -106,7 +105,7 @@ VIM IS... MAINTAINABLE *design-maintain* knowledge spread to other parts of the code. -VIM IS... FLEXIBLE *design-flexible* +NVIM IS... FLEXIBLE *design-flexible* Vim should make it easy for users to work in their preferred styles rather than coercing its users into particular patterns of work. This can be for @@ -117,28 +116,35 @@ be used to adjust Vim to the desire of the user and its environment. 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 attempt to include everything but the kitchen sink, but some people use it -for plumbing." +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." ============================================================================== 2. Design decisions *design-decisions* -Folding - -Several forms of folding should be possible for the same buffer. For example, -have one window that shows the text with function bodies folded, another -window that shows a function body. +JARGON *dev-jargon* -Folding is a way to display the text. It should not change the text itself. -Therefore the folding has been implemented as a filter between the text stored -in a buffer (buffer lines) and the text displayed in a window (logical lines). +API client ~ +All external UIs and remote plugins (as opposed to regular Vim plugins) are +"clients" in general; but we call something an "API client" if its purpose is +to abstract or wrap the RPC API for the convenience of other applications +(just like a REST client or SDK such as boto3 for AWS: you can speak AWS REST +using an HTTP client like curl, but boto3 wraps that in a convenient python +interface). For example, the Nvim lua-client is an API client: + https://github.com/neovim/lua-client +Host ~ +A plugin "host" is both a client (of the Nvim API) and a server (of an +external platform, e.g. python). It is a remote plugin that hosts other +plugins. -Naming the window +Remote plugin ~ +Arbitrary code registered via |:UpdateRemotePlugins|, that runs in a separate +process and communicates with Nvim via the |api|. +Window ~ The word "window" is commonly used for several things: A window on the screen, the xterm window, a window inside Vim to view a buffer. To avoid confusion, other items that are sometimes called window have been @@ -152,111 +158,79 @@ 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* + +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 +a "provider" hook is exposed. + +Consider two examples of integration with external systems that are +implemented in Vim and are now decoupled from Nvim core as providers: + +1. In the Vim source code, clipboard logic accounts for more than 1k lines of + C source code (ui.c), to perform two tasks that are now accomplished with + shell commands such as xclip or pbcopy/pbpaste. + +2. Python scripting support: Vim has three files dedicated to embedding the + Python interpreter: if_python.c, if_python3.c and if_py_both.h. Together + these files sum about 9.5k lines of C source code. In contrast, Nvim Python + scripting is performed by an external host process implemented in ~2k lines + of Python. + +Ideally we could implement Python and clipboard integration in pure vimscript +and without touching the C code. But this is infeasible without compromising +backwards compatibility with Vim; that's where providers help. + +The provider framework helps call vimscript from C. It is composed of two +functions in eval.c: + +- eval_call_provider(name, method, arguments): calls provider#(name)#Call + with the method and arguments. +- eval_has_provider(name): Checks if a provider is implemented. Returns true + if the provider#(name)#Call function is implemented. Called by |has()| + (vimscript) to check if features are available. + +The provider#(name)#Call function implements integration with an external +system, because shell commands and |RPC| clients are easier to work with in +vimscript. + +For example, the Python provider is implemented by the +autoload/provider/python.vim script; the provider#python#Call function is only +defined if a valid external Python host is found. That works well with the +`has('python')` expression (normally used by Python plugins) because if the +Python host isn't installed then the plugin will "think" it is running in +a Vim compiled without the |+python| feature. + + +API *dev-api* + +Use this pattern to name new API functions: + nvim_{thing}_{action}_{arbitrary-qualifiers} + +If the function acts on an object then {thing} is the name of that object +(e.g. "buf" or "win"). If the function operates in a "global" context then +{thing} is usually omitted (but consider "namespacing" your global operations +with a {thing} that groups functions under a common concept). + +Use existing common {action} names if possible: + add Append to, or insert into, a collection + get Get a thing (or subset of things by some query) + set Set a thing + del Delete a thing (or group of things) + list Get all things + +Use consistent names for {thing} in all API functions. E.g. a buffer is called +"buf" everywhere, not "buffer" in some places and "buf" in others. + +Example: `nvim_get_current_line` acts on the global editor state; the common +{action} "get" is used but {thing} is omitted. + +Example: `nvim_buf_add_highlight` acts on a `Buffer` object (the first +parameter) and uses the common {action} "add". + +Example: `nvim_list_bufs` operates in a global context (first parameter is +_not_ a Buffer). The common {action} "list" indicates that it lists all +bufs (plural) in the global context. -Spell checking *develop-spell* - -When spell checking was going to be added to Vim a survey was done over the -available spell checking libraries and programs. Unfortunately, the result -was that none of them provided sufficient capabilities to be used as the spell -checking engine in Vim, for various reasons: - -- Missing support for multi-byte encodings. At least UTF-8 must be supported, - so that more than one language can be used in the same file. - Doing on-the-fly conversion is not always possible (would require iconv - support). -- For the programs and libraries: Using them as-is would require installing - them separately from Vim. That's mostly not impossible, but a drawback. -- Performance: A few tests showed that it's possible to check spelling on the - fly (while redrawing), just like syntax highlighting. But the mechanisms - used by other code are much slower. Myspell uses a hashtable, for example. - The affix compression that most spell checkers use makes it slower too. -- For using an external program like aspell a communication mechanism would - have to be setup. That's complicated to do in a portable way (Unix-only - would be relatively simple, but that's not good enough). And performance - will become a problem (lots of process switching involved). -- Missing support for words with non-word characters, such as "Etten-Leur" and - "et al.", would require marking the pieces of them OK, lowering the - reliability. -- Missing support for regions or dialects. Makes it difficult to accept - all English words and highlight non-Canadian words differently. -- Missing support for rare words. Many words are correct but hardly ever used - and could be a misspelled often-used word. -- For making suggestions the speed is less important and requiring to install - another program or library would be acceptable. But the word lists probably - differ, the suggestions may be wrong words. - - -Spelling suggestions *develop-spell-suggestions* - -For making suggestions there are two basic mechanisms: -1. Try changing the bad word a little bit and check for a match with a good - word. Or go through the list of good words, change them a little bit and - check for a match with the bad word. The changes are deleting a character, - inserting a character, swapping two characters, etc. -2. Perform soundfolding on both the bad word and the good words and then find - matches, possibly with a few changes like with the first mechanism. - -The first is good for finding typing mistakes. After experimenting with -hashtables and looking at solutions from other spell checkers the conclusion -was that a trie (a kind of tree structure) is ideal for this. Both for -reducing memory use and being able to try sensible changes. For example, when -inserting a character only characters that lead to good words need to be -tried. Other mechanisms (with hashtables) need to try all possible letters at -every position in the word. Also, a hashtable has the requirement that word -boundaries are identified separately, while a trie does not require this. -That makes the mechanism a lot simpler. - -Soundfolding is useful when someone knows how the words sounds but doesn't -know how it is spelled. For example, the word "dictionary" might be written -as "daktonerie". The number of changes that the first method would need to -try is very big, it's hard to find the good word that way. After soundfolding -the words become "tktnr" and "tkxnry", these differ by only two letters. - -To find words by their soundfolded equivalent (soundalike word) we need a list -of all soundfolded words. A few experiments have been done to find out what -the best method is. Alternatives: -1. Do the sound folding on the fly when looking for suggestions. This means - walking through the trie of good words, soundfolding each word and - checking how different it is from the bad word. This is very efficient for - memory use, but takes a long time. On a fast PC it takes a couple of - seconds for English, which can be acceptable for interactive use. But for - some languages it takes more than ten seconds (e.g., German, Catalan), - which is unacceptable slow. For batch processing (automatic corrections) - it's too slow for all languages. -2. Use a trie for the soundfolded words, so that searching can be done just - like how it works without soundfolding. This requires remembering a list - of good words for each soundfolded word. This makes finding matches very - fast but requires quite a lot of memory, in the order of 1 to 10 Mbyte. - For some languages more than the original word list. -3. Like the second alternative, but reduce the amount of memory by using affix - compression and store only the soundfolded basic word. This is what Aspell - does. Disadvantage is that affixes need to be stripped from the bad word - before soundfolding it, which means that mistakes at the start and/or end - of the word will cause the mechanism to fail. Also, this becomes slow when - the bad word is quite different from the good word. - -The choice made is to use the second mechanism and use a separate file. This -way a user with sufficient memory can get very good suggestions while a user -who is short of memory or just wants the spell checking and no suggestions -doesn't use so much memory. - - -Word frequency - -For sorting suggestions it helps to know which words are common. In theory we -could store a word frequency with the word in the dictionary. However, this -requires storing a count per word. That degrades word tree compression a lot. -And maintaining the word frequency for all languages will be a heavy task. -Also, it would be nice to prefer words that are already in the text. This way -the words that appear in the specific text are preferred for suggestions. - -What has been implemented is to count words that have been seen during -displaying. A hashtable is used to quickly find the word count. The count is -initialized from words listed in COMMON items in the affix file, so that it -also works when starting a new file. - -This isn't ideal, because the longer Vim is running the higher the counts -become. But in practice it is a noticeable improvement over not using the word -count. vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/diff.txt b/runtime/doc/diff.txt index 12bc655edc..6b45f8552f 100644 --- a/runtime/doc/diff.txt +++ b/runtime/doc/diff.txt @@ -1,12 +1,12 @@ -*diff.txt* For Vim version 7.4. Last change: 2015 Nov 01 +*diff.txt* For Vim version 7.4. Last change: 2016 Aug 24 VIM REFERENCE MANUAL by Bram Moolenaar *diff* *diff-mode* -This file describes |diff-mode|, which shows the differences between two, -three, or four versions of the same file. +This file describes the |+diff| feature: Showing differences between two to +eight versions of the same file. The basics are explained in section |08.7| of the user manual. @@ -109,7 +109,7 @@ To make these commands use a vertical split, prepend |:vertical|. Examples: > If you always prefer a vertical split include "vertical" in 'diffopt'. *E96* -There can be up to four buffers with 'diff' set. +There can be up to eight buffers with 'diff' set. Since the option values are remembered with the buffer, you can edit another file for a moment and come back to the same file and be in diff mode again. diff --git a/runtime/doc/doctags.c b/runtime/doc/doctags.c deleted file mode 100644 index 9213dd9c1e..0000000000 --- a/runtime/doc/doctags.c +++ /dev/null @@ -1,83 +0,0 @@ -/* vim:set ts=4 sw=4: - * this program makes a tags file for vim_ref.txt - * - * Usage: doctags vim_ref.txt vim_win.txt ... >tags - * - * A tag in this context is an identifier between stars, e.g. *c_files* - */ - -#include <stdio.h> -#include <string.h> -#include <ctype.h> -#include <stdlib.h> - -#define LINELEN 200 - - int -main(argc, argv) - int argc; - char **argv; -{ - char line[LINELEN]; - char *p1, *p2; - char *p; - FILE *fd; - - if (argc <= 1) - { - fprintf(stderr, "Usage: doctags docfile ... >tags\n"); - exit(1); - } - printf("help-tags\ttags\t1\n"); - while (--argc > 0) - { - ++argv; - fd = fopen(argv[0], "r"); - if (fd == NULL) - { - fprintf(stderr, "Unable to open %s for reading\n", argv[0]); - continue; - } - while (fgets(line, LINELEN, fd) != NULL) - { - p1 = strchr(line, '*'); /* find first '*' */ - while (p1 != NULL) - { - p2 = strchr(p1 + 1, '*'); /* find second '*' */ - if (p2 != NULL && p2 > p1 + 1) /* skip "*" and "**" */ - { - for (p = p1 + 1; p < p2; ++p) - if (*p == ' ' || *p == '\t' || *p == '|') - break; - /* - * Only accept a *tag* when it consists of valid - * characters, there is white space before it and is - * followed by a white character or end-of-line. - */ - if (p == p2 - && (p1 == line || p1[-1] == ' ' || p1[-1] == '\t') - && (strchr(" \t\n\r", p[1]) != NULL - || p[1] == '\0')) - { - *p2 = '\0'; - ++p1; - printf("%s\t%s\t/*", p1, argv[0]); - while (*p1) - { - /* insert backslash before '\\' and '/' */ - if (*p1 == '\\' || *p1 == '/') - putchar('\\'); - putchar(*p1); - ++p1; - } - printf("*\n"); - p2 = strchr(p2 + 1, '*'); /* find next '*' */ - } - } - p1 = p2; - } - } - fclose(fd); - } - return 0; -} diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt index c51286a350..5bfffac1f1 100644 --- a/runtime/doc/editing.txt +++ b/runtime/doc/editing.txt @@ -1,4 +1,4 @@ -*editing.txt* For Vim version 7.4. Last change: 2016 Jan 03 +*editing.txt* For Vim version 7.4. Last change: 2016 Aug 06 VIM REFERENCE MANUAL by Bram Moolenaar @@ -267,9 +267,6 @@ CTRL-^ Edit the alternate file. Mostly the alternate file is files. See |CTRL-^| above for further details. -[count]]f *]f* *[f* -[count][f Same as "gf". Deprecated. - *gf* *E446* *E447* [count]gf Edit the file whose name is under or after the cursor. Mnemonic: "goto file". @@ -358,7 +355,7 @@ These are the common ones: To avoid the special meaning of the wildcards prepend a backslash. However, on MS-Windows the backslash is a path separator and "path\[abc]" is still seen as a wildcard when "[" is in the 'isfname' option. A simple way to avoid this -is to use "path\[[]abc]". Then the file "path[abc]" literally. +is to use "path\[[]abc]", this matches the file "path\[abc]". *starstar-wildcard* Expanding "**" is possible on Unix, Win32, Mac OS/X and a few other systems. @@ -368,16 +365,21 @@ Note there are some commands where this works slightly differently, see Example: > :n **/*.txt Finds files: - ttt.txt - subdir/ttt.txt - a/b/c/d/ttt.txt -When non-wildcard characters are used these are only matched in the first -directory. Example: > - :n /usr/inc**/*.h + aaa.txt ~ + subdir/bbb.txt ~ + a/b/c/d/ccc.txt ~ +When non-wildcard characters are used right before or after "**" these are +only matched in the top directory. They are not used for directories further +down in the tree. For example: > + :n /usr/inc**/types.h Finds files: - /usr/include/types.h - /usr/include/sys/types.h - /usr/inc_old/types.h + /usr/include/types.h ~ + /usr/include/sys/types.h ~ + /usr/inc/old/types.h ~ +Note that the path with "/sys" is included because it does not need to match +"/inc". Thus it's like matching "/usr/inc*/*/*...", not +"/usr/inc*/inc*/inc*". + *backtick-expansion* *`-expansion* On Unix and a few other systems you can also use backticks for the file name argument, for example: > @@ -596,6 +598,7 @@ list of the current window. :0argadd x x a b c :1argadd x a x b c :$argadd x a b c x + And after the last one: :+2argadd y a b c x y There is no check for duplicates, it is possible to add a file to the argument list twice. @@ -946,7 +949,7 @@ the newly written file (it might be there but contain bogus data). In that case try recovery, because the swap file is synced to disk and might still be there. |:recover| -The directories given with the 'backupdir' option is used to put the backup +The directories given with the 'backupdir' option are used to put the backup file in. (default: same directory as the written file). Whether the backup is a new file, which is a copy of the original file, or the @@ -1043,10 +1046,12 @@ The names can be in upper- or lowercase. edited. See |:confirm| and 'confirm'. :q[uit]! Quit without writing, also when the current buffer has - changes. If this is the last window and there is a - modified hidden buffer, the current buffer is - abandoned and the first changed hidden buffer becomes - the current buffer. + changes. The buffer is unloaded, also when it has + 'hidden' set. + If this is the last window and there is a modified + hidden buffer, the current buffer is abandoned and the + first changed hidden buffer becomes the current + buffer. Use ":qall!" to exit always. :cq[uit] Quit always, without writing, and return an error @@ -1147,7 +1152,7 @@ Examples: > If you want to always use ":confirm", set the 'confirm' option. - *:browse* *:bro* *E338* *E614* *E615* *E616* *E578* + *:browse* *:bro* *E338* *E614* *E615* *E616* :bro[wse] {command} Open a file selection dialog for an argument to {command}. At present this works for |:e|, |:w|, |:wall|, |:wq|, |:wqall|, |:x|, |:xall|, |:exit|, diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index eebdabd154..9aa60657e0 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1,4 +1,4 @@ -*eval.txt* For Vim version 7.4. Last change: 2016 Jan 16 +*eval.txt* For Vim version 7.4. Last change: 2016 Aug 27 VIM REFERENCE MANUAL by Bram Moolenaar @@ -43,11 +43,15 @@ Number A 32 or 64 bit signed number. |expr-number| *Number* Float A floating point number. |floating-point-format| *Float* Examples: 123.456 1.15e-6 -1.1e3 + *E928* String A NUL terminated string of 8-bit unsigned characters (bytes). |expr-string| Examples: "ab\txx\"--" 'x-z''a,c' Funcref A reference to a function |Funcref|. Example: function("strlen") + It can be bound to a dictionary and arguments, it then works + like a Partial. + Example: function("Callback", [arg], myDict) List An ordered sequence of items |List|. Example: [1, 2, ['a', 'b']] @@ -100,18 +104,12 @@ When mixing Number and Float the Number is converted to Float. Otherwise there is no automatic conversion of Float. You can use str2float() for String to Float, printf() for Float to String and float2nr() for Float to Number. - *E706* *sticky-type-checking* -You will get an error if you try to change the type of a variable. You need -to |:unlet| it first to avoid this error. String and Number are considered -equivalent though, as well are Float and Number. Consider this sequence of -commands: > - :let l = "string" - :let l = 44 " changes type from String to Number - :let l = [1, 2, 3] " error! l is still a Number - :let l = 4.4 " changes type from Number to Float - :let l = "string" " error! - + *E891* *E892* *E893* *E894* +When expecting a Float a Number can also be used, but nothing else. + *no-type-checking* +You will not get an error if you try to change the type of a variable. + 1.2 Function references ~ *Funcref* *E695* *E718* A Funcref variable is obtained with the |function()| function. It can be used @@ -144,6 +142,40 @@ The name of the referenced function can be obtained with |string()|. > You can use |call()| to invoke a Funcref and use a list variable for the arguments: > :let r = call(Fn, mylist) +< + *Partial* +A Funcref optionally binds a Dictionary and/or arguments. This is also called +a Partial. This is created by passing the Dictionary and/or arguments to +function(). When calling the function the Dictionary and/or arguments will be +passed to the function. Example: > + + let Cb = function('Callback', ['foo'], myDict) + call Cb() + +This will invoke the function as if using: > + call myDict.Callback('foo') + +Note that binding a function to a Dictionary also happens when the function is +a member of the Dictionary: > + + let myDict.myFunction = MyFunction + call myDict.myFunction() + +Here MyFunction() will get myDict passed as "self". This happens when the +"myFunction" member is accessed. When assigning "myFunction" to otherDict +and calling it, it will be bound to otherDict: > + + let otherDict.myFunction = myDict.myFunction + call otherDict.myFunction() + +Now "self" will be "otherDict". But when the dictionary was bound explicitly +this won't happen: > + + let myDict.myFunction = function(MyFunction, myDict) + let otherDict.myFunction = myDict.myFunction + call otherDict.myFunction() + +Here "self" will be "myDict", because it was bound explitly. 1.3 Lists ~ @@ -410,7 +442,8 @@ only appear once. Examples: > A key is always a String. You can use a Number, it will be converted to a String automatically. Thus the String '4' and the number 4 will find the same entry. Note that the String '04' and the Number 04 are different, since the -Number will be converted to the String '4'. +Number will be converted to the String '4'. The empty string can be used as a +key. A value can be any expression. Using a Dictionary for a value creates a nested Dictionary: > @@ -750,22 +783,40 @@ A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not equal" and "is" can be used. This compares the key/values of the |Dictionary| recursively. Ignoring case means case is ignored when comparing item values. - *E693* *E694* -A |Funcref| can only be compared with a |Funcref| and only "equal" and "not -equal" can be used. Case is never ignored. + *E694* +A |Funcref| can only be compared with a |Funcref| and only "equal", "not +equal", "is" and "isnot" can be used. Case is never ignored. Whether +arguments or a Dictionary are bound (with a partial) matters. The +Dictionaries must also be equal (or the same, in case of "is") and the +arguments must be equal (or the same). + +To compare Funcrefs to see if they refer to the same function, ignoring bound +Dictionary and arguments, use |get()| to get the function name: > + if get(Part1, 'name') == get(Part2, 'name') + " Part1 and Part2 refer to the same function When using "is" or "isnot" with a |List| or a |Dictionary| this checks if the expressions are referring to the same |List| or |Dictionary| instance. A copy of a |List| is different from the original |List|. When using "is" without a |List| or a |Dictionary| it is equivalent to using "equal", using "isnot" equivalent to using "not equal". Except that a different type means the -values are different: "4 == '4'" is true, "4 is '4'" is false and "0 is []" is -false and not an error. "is#"/"isnot#" and "is?"/"isnot?" can be used to match -and ignore case. +values are different: > + echo 4 == '4' + 1 + echo 4 is '4' + 0 + echo 0 is [] + 0 +"is#"/"isnot#" and "is?"/"isnot?" can be used to match and ignore case. When comparing a String with a Number, the String is converted to a Number, -and the comparison is done on Numbers. This means that "0 == 'x'" is TRUE, -because 'x' converted to a Number is zero. +and the comparison is done on Numbers. This means that: > + echo 0 == 'x' + 1 +because 'x' converted to a Number is zero. However: > + echo 0 == 'x' + 0 +Inside a List or Dictionary this conversion is not used. When comparing two Strings, this is done with strcmp() or stricmp(). This results in the mathematical difference (comparing byte values), not @@ -858,11 +909,12 @@ These three can be repeated and mixed. Examples: expr8 *expr8* ----- expr8[expr1] item of String or |List| *expr-[]* *E111* + *subscript* 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 -an alternative. +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: text column numbers start with one! Example, to get the byte under the @@ -870,7 +922,7 @@ cursor: > :let c = getline(".")[col(".") - 1] If the length of the String is less than the index, the result is an empty -String. A negative index always results in an empty string (reason: backwards +String. A negative index always results in an empty string (reason: backward compatibility). Use [-1:] to get the last byte. If expr8 is a |List| then it results the item at index expr1. See |list-index| @@ -1022,8 +1074,8 @@ A string constant accepts these special characters: \x. byte specified with one hex number (must be followed by non-hex char) \X.. same as \x.. \X. same as \x. -\u.... character specified with up to 4 hex numbers, stored according to the - current value of 'encoding' (e.g., "\u02a4") +\u.... character specified with up to 4 hex numbers, stored as UTF-8 + (e.g., "\u02a4") \U.... same as \u but allows up to 8 hex numbers. \b backspace <BS> \e escape <Esc> @@ -1038,8 +1090,7 @@ A string constant accepts these special characters: utf-8 character, use \uxxxx as mentioned above. Note that "\xff" is stored as the byte 255, which may be invalid in some -encodings. Use "\u00ff" to store character 255 according to the current value -of 'encoding'. +encodings. Use "\u00ff" to store character 255 correctly as UTF-8. Note that "\000" and "\x00" force the end of the string. @@ -1299,6 +1350,10 @@ v:beval_winnr The number of the window, over which the mouse pointer is. Only window has number zero (unlike most other places where a 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:char* *char-variable* v:char Argument for evaluating 'formatexpr' and used for the typed character when using <expr> in an abbreviation |:map-<expr>|. @@ -1373,6 +1428,9 @@ v:dying Normally zero. When a deadly signal is caught it's set to < Note: if another deadly signal is caught when v:dying is one, VimLeave autocommands will not be executed. + *v:exiting* *exiting-variable* +v:exiting The exit value Nvim will use. Before exiting, it is |v:null|. + *v:errmsg* *errmsg-variable* v:errmsg Last given error message. It's allowed to set this variable. Example: > @@ -1420,7 +1478,7 @@ v:exception The value of the exception most recently caught and not *v:false* *false-variable* v:false Special value used to put "false" in JSON and msgpack. See - |json_encode()|. This value is converted to "false" when used + |json_encode()|. This value is converted to "v:false" when used as a String (e.g. in |expr5| with string concatenation operator) and to zero when used as a Number (e.g. in |expr5| or |expr7| when used with numeric operators). @@ -1548,6 +1606,10 @@ v:mouse_win Window number for a mouse click obtained with |getchar()|. First window has number 1, like with |winnr()|. The value is 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()|. + The value is zero when there was no mouse button click. + *v:mouse_lnum* *mouse_lnum-variable* v:mouse_lnum Line number for a mouse click obtained with |getchar()|. This is the text line number, not the screen line number. The @@ -1566,7 +1628,7 @@ v:msgpack_types Dictionary containing msgpack types used by |msgpackparse()| *v:null* *null-variable* v:null Special value used to put "null" in JSON and NIL in msgpack. - See |json_encode()|. This value is converted to "null" when + See |json_encode()|. This value is converted to "v:null" when used as a String (e.g. in |expr5| with string concatenation operator) and to zero when used as a Number (e.g. in |expr5| or |expr7| when used with numeric operators). @@ -1650,9 +1712,9 @@ v:scrollstart String describing the script or function that caused the hit-enter prompt. *v:servername* *servername-variable* + *$NVIM_LISTEN_ADDRESS* v:servername Default {Nvim} server address. Equivalent to - |$NVIM_LISTEN_ADDRESS| on startup, but may differ if the - latter is modified or unset. |serverstop()| + |$NVIM_LISTEN_ADDRESS| on startup. |serverstop()| Read-only. @@ -1704,6 +1766,21 @@ v:swapcommand Normal mode command to be executed after a file has been example, when jumping to a tag the value is ":tag tagname\r". For ":edit +cmd file" the value is ":cmd\r". + *v:t_TYPE* *v:t_bool* *t_bool-varialble* +v:t_bool Value of Boolean type. Read-only. See: |type()| + *v:t_dict* *t_dict-varialble* +v:t_dict Value of Dictionary type. Read-only. See: |type()| + *v:t_float* *t_float-varialble* +v:t_float Value of Float type. Read-only. See: |type()| + *v:t_func* *t_func-varialble* +v:t_func Value of Funcref type. Read-only. See: |type()| + *v:t_list* *t_list-varialble* +v:t_list Value of List type. Read-only. See: |type()| + *v:t_number* *t_number-varialble* +v:t_number Value of Number type. Read-only. See: |type()| + *v:t_string* *t_string-varialble* +v:t_string Value of String type. Read-only. See: |type()| + *v:termresponse* *termresponse-variable* v:termresponse The escape sequence returned by the terminal for the |t_RV| termcap entry. It is set when Vim receives an escape sequence @@ -1738,7 +1815,7 @@ v:throwpoint The point where the exception most recently caught and not *v:true* *true-variable* v:true Special value used to put "true" in JSON and msgpack. See - |json_encode()|. This value is converted to "true" when used + |json_encode()|. This value is converted to "v:true" when used as a String (e.g. in |expr5| with string concatenation operator) and to one when used as a Number (e.g. in |expr5| or |expr7| when used with numeric operators). @@ -1759,13 +1836,17 @@ v:version Version number of Vim: Major version number times 100 plus version 5.0 and 5.1 may have a patch 123, but these are completely different. + *v:vim_did_enter* *vim_did_enter-variable* +v:vim_did_enter Zero until most of startup is done. It is set to one just + before |VimEnter| autocommands are triggered. + *v:warningmsg* *warningmsg-variable* v:warningmsg Last given warning message. It's allowed to set this variable. *v:windowid* *windowid-variable* {Nvim} 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()|. + Note: for windows inside Vim use |winnr()| or |win_getid()|. ============================================================================== 4. Builtin Functions *functions* @@ -1780,6 +1861,7 @@ abs({expr}) Float or Number absolute value of {expr} acos({expr}) Float arc cosine of {expr} add({list}, {item}) List append {item} to |List| {list} and({expr}, {expr}) Number bitwise AND +api_info() Dict api metadata append({lnum}, {string}) Number append {string} below line {lnum} append({lnum}, {list}) Number append lines {list} below line {lnum} argc() Number number of files in the argument list @@ -1787,9 +1869,13 @@ argidx() Number current index in the argument list arglistid([{winnr} [, {tabnr}]]) Number argument list id argv({nr}) String {nr} entry of the argument list argv() List the argument list -assert_equal({exp}, {act} [, {msg}]) none assert {exp} equals {act} -assert_exception({error} [, {msg}]) none assert {error} is in v:exception +assert_equal({exp}, {act} [, {msg}]) none assert {exp} is equal to {act} +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_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} assert_true({actual} [, {msg}]) none assert {actual} is true asin({expr}) Float arc sine of {expr} atan({expr}) Float arc tangent of {expr} @@ -1802,6 +1888,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} 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} @@ -1843,6 +1930,7 @@ escape({string}, {chars}) String escape {chars} in {string} with '\' eval({string}) any evaluate {string} into its value eventhandler() Number TRUE if inside an event handler executable({expr}) Number 1 if executable {expr} exists +execute({command}) String execute and capture output of {command} exepath({expr}) String full path of the command {expr} exists({expr}) Number TRUE if {expr} exists extend({expr1}, {expr2} [, {expr3}]) @@ -1870,10 +1958,13 @@ foldlevel({lnum}) Number fold level at {lnum} foldtext() String line displayed for closed fold foldtextresult({lnum}) String text for closed fold at {lnum} foreground() Number bring the Vim window to the foreground -function({name}) Funcref reference to function {name} +function({name} [, {arglist}] [, {dict}]) + Funcref reference to function {name} 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 getbufline({expr}, {lnum} [, {end}]) List lines {lnum} to {end} of buffer {expr} getbufvar({expr}, {varname} [, {def}]) @@ -1885,8 +1976,10 @@ getcmdline() String return the current command-line getcmdpos() Number return cursor position in command-line getcmdtype() String return current command-line type getcmdwintype() String return current command-line window type +getcompletion({pat}, {type} [, {filtered}]) + List list of cmdline completion matches getcurpos() List position of the cursor -getcwd([{scope}]) String the current working directory +getcwd([{winnr} [, {tabnr}]]) String the current working directory getfontname([{name}]) String name of font being used getfperm({fname}) String file permissions of file {fname} getfsize({fname}) Number size in bytes of file {fname} @@ -1902,10 +1995,12 @@ getqflist() List list of quickfix items getreg([{regname} [, 1 [, {list}]]]) String or List contents of register getregtype([{regname}]) String type of register +gettabinfo( [{expr}]) List list of tab pages gettabvar({nr}, {varname} [, {def}]) any variable {varname} in tab {nr} or {def} gettabwinvar({tabnr}, {winnr}, {name} [, {def}]) any {name} in {winnr} in tab page {tabnr} +getwininfo( [{winid}]) List list of windows getwinposx() Number X coord in pixels of GUI Vim window getwinposy() Number Y coord in pixels of GUI Vim window getwinvar({nr}, {varname} [, {def}]) @@ -1917,10 +2012,11 @@ globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) String do glob({expr}) for all dirs in {path} has({feature}) Number TRUE if feature {feature} supported has_key({dict}, {key}) Number TRUE if {dict} has entry {key} -haslocaldir() Number TRUE if current window executed |:lcd| +haslocaldir([{winnr} [, {tabnr}]]) + Number TRUE if current window executed |:lcd| hasmapto({what} [, {mode} [, {abbr}]]) Number TRUE if mapping to {what} exists -histadd({history},{item}) String add an item to a history +histadd({history}, {item}) String add an item to a history histdel({history} [, {item}]) String remove an item from a history histget({history} [, {index}]) String get the item {index} from a history histnr({history}) Number highest index of a history @@ -1986,6 +2082,8 @@ matchlist({expr}, {pat}[, {start}[, {count}]]) List match and submatches of {pat} in {expr} 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} mkdir({name} [, {path} [, {prot}]]) @@ -1995,6 +2093,7 @@ msgpackdump({list}) List dump a list of objects to msgpack msgpackparse({list}) List parse msgpack to a list of objects nextnonblank({lnum}) Number line nr of non-blank line >= {lnum} nr2char({expr}[, {utf8}]) String single char with ASCII/UTF8 value {expr} +nvim_...({args}...) any call nvim |api| functions or({expr}, {expr}) Number bitwise OR pathshorten({expr}) String shorten directory names in a path pow({x}, {y}) Float {x} to the power of {y} @@ -2018,7 +2117,7 @@ remote_peek({serverid} [, {retvar}]) remote_read({serverid}) String read reply string remote_send({server}, {string} [, {idvar}]) String send key sequence -remove({list}, {idx} [, {end}]) any remove items {idx}-{end} from {list} +remove({list}, {idx} [, {end}]) any remove items {idx}-{end} from {list} remove({dict}, {key}) any remove entry {key} from {dict} rename({from}, {to}) Number rename (move) file from {from} to {to} repeat({expr}, {count}) String repeat {expr} {count} times @@ -2026,11 +2125,10 @@ resolve({filename}) String get filename a shortcut points to reverse({list}) List reverse {list} in-place round({expr}) Float round off {expr} rpcnotify({channel}, {event}[, {args}...]) - Sends a |msgpack-rpc| notification to {channel} + Sends an |RPC| notification to {channel} rpcrequest({channel}, {method}[, {args}...]) - Sends a |msgpack-rpc| request to {channel} -rpcstart({prog}[, {argv}]) Spawns {prog} and opens a |msgpack-rpc| channel -rpcstop({channel}) Closes a |msgpack-rpc| {channel} + Sends an |RPC| request to {channel} +rpcstop({channel}) Closes an |RPC| {channel} screenattr({row}, {col}) Number attribute at screen position screenchar({row}, {col}) Number character at screen position screencol() Number current cursor column @@ -2084,14 +2182,17 @@ sqrt({expr}) Float square root of {expr} str2float({expr}) Float convert String to Float str2nr({expr} [, {base}]) Number convert String to Number strchars({expr} [, {skipcc}]) Number character length of the String {expr} +strcharpart({str}, {start}[, {len}]) + String {len} characters of {str} at {start} strdisplaywidth({expr} [, {col}]) Number display length of the String {expr} strftime({format}[, {time}]) String time in specified format +strgetchar({str}, {index}) Number get char {index} from {str} stridx({haystack}, {needle}[, {start}]) Number index of {needle} in {haystack} string({expr}) String String representation of {expr} value strlen({expr}) Number length of the String {expr} -strpart({src}, {start}[, {len}]) - String {len} characters of {src} at {start} +strpart({str}, {start}[, {len}]) + String {len} characters of {str} at {start} strridx({haystack}, {needle} [, {start}]) Number last index of {needle} in {haystack} strtrans({expr}) String translate string to make it printable @@ -2108,15 +2209,18 @@ synconcealed({lnum}, {col}) List info about concealing synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col} system({cmd} [, {input}]) String output of shell command/filter {cmd} systemlist({cmd} [, {input}]) List output of shell command/filter {cmd} -tabpagebuflist([{arg}]) List list of buffer numbers in tab page +tabpagebuflist([{arg}]) List list of buffer numbers in tab page tabpagenr([{arg}]) Number number of current or last tab page tabpagewinnr({tabarg}[, {arg}]) Number number of current window in tab page taglist({expr}) List list of tags matching {expr} tagfiles() List tags files used -tempname() String name for a temporary file tan({expr}) Float tangent of {expr} tanh({expr}) Float hyperbolic tangent of {expr} +tempname() String name for a temporary file +timer_start({time}, {callback} [, {options}]) + Number create a timer +timer_stop({timer}) none stop a timer 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} @@ -2131,6 +2235,11 @@ values({dict}) List values in {dict} 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 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} @@ -2145,6 +2254,7 @@ writefile({list}, {fname} [, {flags}]) Number write list of lines to file {fname} xor({expr}, {expr}) Number bitwise XOR + abs({expr}) *abs()* Return the absolute value of {expr}. When {expr} evaluates to a |Float| abs() returns a |Float|. When {expr} can be @@ -2187,6 +2297,8 @@ and({expr}, {expr}) *and()* Example: > :let flag = and(bits, 0x80) +api_info() *api_info()* + Returns Dictionary of |api-metadata|. append({lnum}, {expr}) *append()* When {expr} is a |List|: Append each item of the |List| as a @@ -2208,7 +2320,7 @@ argidx() The result is the current index in the argument list. 0 is the first file. argc() - 1 is the last one. See |arglist|. *arglistid()* -arglistid([{winnr}, [ {tabnr} ]]) +arglistid([{winnr} [, {tabnr}]]) Return the argument list ID. This is a number which identifies the argument list being used. Zero is used for the global argument list. See |arglist|. @@ -2218,6 +2330,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. *argv()* argv([{nr}]) The result is the {nr}th file in the argument list of the @@ -2260,6 +2373,11 @@ assert_exception({error} [, {msg}]) *assert_exception()* call assert_exception('E492:') endtry +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|. + assert_false({actual} [, {msg}]) *assert_false()* When {actual} is not false an error message is added to |v:errors|, like with |assert_equal()|. @@ -2268,6 +2386,36 @@ assert_false({actual} [, {msg}]) *assert_false()* When {msg} is omitted an error in the form "Expected False but got {actual}" is produced. + *assert_match()* +assert_match({pattern}, {actual} [, {msg}]) + When {pattern} does not match {actual} an error message is + added to |v:errors|. + + {pattern} is used as with |=~|: The matching is always done + like 'magic' was set and 'cpoptions' is empty, no matter what + the actual value of 'magic' or 'cpoptions' is. + + {actual} is used as a string, automatic conversion applies. + Use "^" and "$" to match with the start and end of the text. + Use both to match the whole text. + + When {msg} is omitted an error in the form "Pattern {pattern} + does not match {actual}" is produced. + Example: > + assert_match('^f.*o$', 'foobar') +< Will result in a string to be added to |v:errors|: + test.vim line 12: Pattern '^f.*o$' does not match 'foobar' ~ + + *assert_notequal()* +assert_notequal({expected}, {actual} [, {msg}]) + The opposite of `assert_equal()`: add an error message to + |v:errors| when {expected} and {actual} are equal. + + *assert_notmatch()* +assert_notmatch({pattern}, {actual} [, {msg}]) + The opposite of `assert_match()`: add an error message to + |v:errors| when {pattern} matches {actual}. + assert_true({actual} [, {msg}]) *assert_true()* When {actual} is not true an error message is added to |v:errors|, like with |assert_equal()|. @@ -2354,8 +2502,6 @@ bufexists({expr}) *bufexists()* for MS-Windows 8.3 names in the form "c:\DOCUME~1" Use "bufexists(0)" to test for the existence of an alternate file name. - *buffer_exists()* - Obsolete name: buffer_exists(). buflisted({expr}) *buflisted()* The result is a Number, which is non-zero if a buffer called @@ -2394,8 +2540,6 @@ bufname({expr}) *bufname()* bufname(3) name of buffer 3 bufname("%") name of current buffer bufname("file2") name of buffer where "file2" matches. -< *buffer_name()* - Obsolete name: buffer_name(). *bufnr()* bufnr({expr} [, {create}]) @@ -2411,10 +2555,16 @@ bufnr({expr} [, {create}]) of existing buffers. Note that not all buffers with a smaller number necessarily exist, because ":bwipeout" may have removed them. Use bufexists() to test for the existence of a buffer. - *buffer_number()* - Obsolete name: buffer_number(). - *last_buffer_nr()* - Obsolete name for bufnr("$"): last_buffer_nr(). + +bufwinid({expr}) *bufwinid()* + 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: > + + echo "A window containing buffer 1 is " . (bufwinid(1)) +< + Only deals with the current tab page. bufwinnr({expr}) *bufwinnr()* The result is a Number, which is the number of the first @@ -2452,7 +2602,9 @@ byteidx({expr}, {nr}) *byteidx()* same: > let s = strpart(str, byteidx(str, 3)) echo strpart(s, 0, byteidx(s, 1)) -< If there are less than {nr} characters -1 is returned. +< Also see |strgetchar()| and |strcharpart()|. + + If there are less than {nr} characters -1 is returned. If there are exactly {nr} characters the length of the string in bytes is returned. @@ -2466,8 +2618,6 @@ byteidxcomp({expr}, {nr}) *byteidxcomp()* < The first and third echo result in 3 ('e' plus composing character is 3 bytes), the second echo results in 1 ('e' is one byte). - Only works different from byteidx() when 'encoding' is set to - a Unicode encoding. call({func}, {arglist} [, {dict}]) *call()* *E699* Call function {func} with the items in |List| {arglist} as @@ -2502,11 +2652,11 @@ char2nr({expr}[, {utf8}]) *char2nr()* Return number value of the first char in {expr}. Examples: > char2nr(" ") returns 32 char2nr("ABC") returns 65 -< When {utf8} is omitted or zero, the current 'encoding' is used. - Example for "utf-8": > char2nr("á") returns 225 char2nr("á"[0]) returns 195 -< With {utf8} set to 1, always treat as utf-8 characters. +< Non-ASCII characters are always treated as UTF-8 characters. + {utf8} has no effect, and exists only for + backwards-compatibility. A combining character is a separate character. |nr2char()| does the opposite. @@ -2745,6 +2895,7 @@ cursor({list}) When there is one argument {list} this is used as a |List| with two, three or four item: + [{lnum}, {col}] [{lnum}, {col}, {off}] [{lnum}, {col}, {off}, {curswant}] This is like the return value of |getpos()| or |getcurpos()|, @@ -2811,6 +2962,13 @@ dictwatcheradd({dict}, {pattern}, {callback}) *dictwatcheradd()* After this is called, every change on {dict} and on keys matching {pattern} will result in {callback} being invoked. + For example, to watch all global variables: > + silent! call dictwatcherdel(g:, '*', 'OnDictChanged') + function! OnDictChanged(d,k,z) + echomsg string(a:k) string(a:z) + endfunction + call dictwatcheradd(g:, '*', 'OnDictChanged') +< For now {pattern} only accepts very simple patterns that can contain a '*' at the end of the string, in which case it will match every key that begins with the substring before the '*'. @@ -2821,7 +2979,7 @@ dictwatcheradd({dict}, {pattern}, {callback}) *dictwatcheradd()* - The dictionary being watched. - The key which changed. - - A dictionary containg the new and old values for the key. + - A dictionary containing the new and old values for the key. The type of change can be determined by examining the keys present on the third argument: @@ -2920,6 +3078,31 @@ executable({expr}) *executable()* 0 does not exist -1 not implemented on this system +execute({command} [, {silent}]) *execute()* + Execute {command} and capture its output. + If {command} is a |String|, returns {command} output. + If {command} is a |List|, returns concatenated outputs. + Examples: > + echo execute('echon "foo"') +< foo > + echo execute(['echon "foo"', 'echon "bar"']) +< foobar + + The optional {silent} argument can have these values: + "" no `:silent` used + "silent" `:silent` used + "silent!" `:silent!` used + The default is 'silent'. Note that with "silent!", unlike + `:redir`, error messages are dropped. + + To get a list of lines use |split()| on the result: > + split(execute('args'), "\n") + +< This function is not available in the |sandbox|. + Note: If nested, an outer execute() will not observe output of + the inner calls. + Note: Text attributes (highlights) are not captured. + exepath({expr}) *exepath()* If {expr} is an executable and is either an absolute path, a relative path or found in $PATH, return the full path. @@ -3162,6 +3345,18 @@ feedkeys({string} [, {mode}]) *feedkeys()* if coming from a mapping. This matters for undo, opening folds, etc. 'i' Insert the string instead of appending (see above). + 'x' Execute commands until typeahead is empty. This is + similar to using ":normal!". You can call feedkeys() + several times without 'x' and then one time with 'x' + (possibly with an empty {string}) to execute all the + typeahead. Note that when Vim ends in Insert mode it + will behave as if <Esc> is typed, to avoid getting + stuck, waiting for a character to be typed before the + script continues. + '!' When used with 'x' will not end Insert mode. Can be + used in a test when a timer is set to exit Insert mode + a little later. Useful for testing CursorHoldI. + Return value is always 0. filereadable({file}) *filereadable()* @@ -3171,8 +3366,6 @@ filereadable({file}) *filereadable()* expression, which is used as a String. If you don't care about the file being readable you can use |glob()|. - *file_readable()* - Obsolete name: file_readable(). filewritable({file}) *filewritable()* @@ -3359,10 +3552,46 @@ foreground() Move the Vim window to the foreground. Useful when sent from {only in the Win32 GUI and console version} -function({name}) *function()* *E700* + *function()* *E700* *E922* *E923* +function({name} [, {arglist}] [, {dict}]) Return a |Funcref| variable that refers to function {name}. {name} can be a user defined function or an internal function. + When {arglist} or {dict} is present this creates a partial. + That mans the argument list and/or the dictionary is stored in + the Funcref and will be used when the Funcref is called. + + The arguments are passed to the function in front of other + arguments. Example: > + func Callback(arg1, arg2, name) + ... + let Func = function('Callback', ['one', 'two']) + ... + call Func('name') +< Invokes the function as with: > + call Callback('one', 'two', 'name') + +< The Dictionary is only useful when calling a "dict" function. + In that case the {dict} is passed in as "self". Example: > + function Callback() dict + echo "called for " . self.name + endfunction + ... + let context = {"name": "example"} + let Func = function('Callback', context) + ... + call Func() " will echo: called for example + +< The argument list and the Dictionary can be combined: > + function Callback(arg1, count) dict + ... + let context = {"name": "example"} + let Func = function('Callback', ['one'], context) + ... + call Func(500) +< Invokes the function as with: > + call context.Callback('one', 500) + garbagecollect([{atexit}]) *garbagecollect()* Cleanup unused |Lists| and |Dictionaries| that have circular @@ -3386,7 +3615,68 @@ get({dict}, {key} [, {default}]) Get item with key {key} from |Dictionary| {dict}. When this item is not available return {default}. Return zero when {default} is omitted. +get({func}, {what}) + Get item {what} from Funcref {func}. Possible values for + {what} are: + 'name' The function name + 'func' The function + 'dict' The dictionary + 'args' The list with arguments + + *getbufinfo()* +getbufinfo([{expr}]) +getbufinfo([{dict}]) + Get information about buffers as a List of Dictionaries. + + Without an argument information about all the buffers is + returned. + + When the argument is a Dictionary only the buffers matching + the specified criteria are returned. The following keys can + be specified in {dict}: + buflisted include only listed buffers. + bufloaded include only loaded buffers. + + Otherwise, {expr} specifies a particular buffer to return + information for. For the use of {expr}, see |bufname()| + above. If the buffer is found the returned List has one item. + Otherwise the result is an empty list. + + Each returned List item is a dictionary with the following + entries: + bufnr buffer number. + changed TRUE if the buffer is modified. + changedtick number of changes made to the buffer. + hidden TRUE if the buffer is hidden. + listed TRUE if the buffer is listed. + lnum current line number in buffer. + loaded TRUE if the buffer is loaded. + name full path to the file in the buffer. + signs list of signs placed in the buffer. + Each list item is a dictionary with + the following fields: + id sign identifier + lnum line number + name sign name + variables a reference to the dictionary with + buffer-local variables. + windows list of |window-ID|s that display this + buffer + Examples: > + for buf in getbufinfo() + echo buf.name + endfor + for buf in getbufinfo({'buflisted':1}) + if buf.changed + .... + endif + endfor +< + To get buffer-local options use: > + getbufvar({bufnr}, '&') + +< *getbufline()* getbufline({expr}, {lnum} [, {end}]) Return a |List| with the lines starting from {lnum} to {end} @@ -3418,6 +3708,10 @@ getbufvar({expr}, {varname} [, {def}]) *getbufvar()* must be used. When {varname} is empty returns a dictionary with all the buffer-local variables. + When {varname} is equal to "&" returns a dictionary with all + the buffer-local options. + Otherwise, when {varname} starts with "&" returns the value of + a buffer-local option. This also works for a global or buffer-local option, but it doesn't work for a global variable, window-local variable or window-local option. @@ -3458,8 +3752,8 @@ getchar([expr]) *getchar()* When the user clicks a mouse button, the mouse event will be returned. The position can then be found in |v:mouse_col|, - |v:mouse_lnum| and |v:mouse_win|. This example positions the - mouse as it would normally happen: > + |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|. This + example positions the mouse as it would normally happen: > let c = getchar() if c == "\<LeftMouse>" && v:mouse_win > 0 exe v:mouse_win . "wincmd w" @@ -3570,10 +3864,57 @@ getcmdwintype() *getcmdwintype()* values are the same as |getcmdtype()|. Returns an empty string when not in the command-line window. +getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* + Return a list of command-line completion matches. {type} + specifies what for. The following completion types are + supported: + + augroup autocmd groups + buffer buffer names + behave :behave suboptions + color color schemes + command Ex command (and arguments) + compiler compilers + cscope |:cscope| suboptions + dir directory names + environment environment variable names + event autocommand events + expression Vim expression + file file and directory names + file_in_path file and directory names in |'path'| + filetype filetype names |'filetype'| + function function name + help help subjects + highlight highlight groups + history :history suboptions + locale locale names (as output of locale -a) + mapping mapping name + menu menus + option options + shellcmd Shell command + sign |:sign| suboptions + syntax syntax file names |'syntax'| + syntime |:syntime| suboptions + tag tags + tag_listfiles tags, file names + user user names + var user variables + + If {pat} is an empty string, then all the matches are returned. + Otherwise only items matching {pat} are returned. See + |wildcards| for the use of special characters in {pat}. + + If the optional {filtered} flag is set to 1, then 'wildignore' + is applied to filter the results. Otherwise all the matches + are returned. The 'wildignorecase' option always applies. + + If there are no matches, an empty list is returned. An + invalid value for {type} produces an error. + *getcurpos()* getcurpos() Get the position of the cursor. This is like getpos('.'), but includes an extra item in the list: - [bufnum, lnum, col, off, curswant] + [bufnum, lnum, col, off, curswant] ~ The "curswant" number is the preferred column when moving the cursor vertically. This can be used to save and restore the cursor position: > @@ -3581,17 +3922,18 @@ getcurpos() Get the position of the cursor. This is like getpos('.'), but MoveTheCursorAround call setpos('.', save_cursor) < -getcwd([{window}[, {tab}]]) *getcwd()* +getcwd([{winnr}[, {tabnr}]]) *getcwd()* With no arguments the result is a String, which is the name of - the current effective working directory. With {window} or - {tab} the working directory of that scope is returned. + the current effective working directory. With {winnr} or + {tabnr} the working directory of that scope is returned. Tabs and windows are identified by their respective numbers, 0 means current tab or window. Missing argument implies 0. Thus the following are equivalent: > getcwd() getcwd(0) getcwd(0, 0) -< If {window} is -1 it is ignored, only the tab is resolved. +< If {winnr} is -1 it is ignored, only the tab is resolved. + {winnr} can be the window number or the window ID. getfsize({fname}) *getfsize()* @@ -3656,7 +3998,8 @@ getftype({fname}) *getftype()* getftype("/home") < Note that a type such as "link" will only be returned on systems that support it. On some systems only "dir" and - "file" are returned. + "file" are returned. On MS-Windows a symbolic link to a + directory returns "dir" instead of "link". *getline()* getline({lnum} [, {end}]) @@ -3685,7 +4028,9 @@ getline({lnum} [, {end}]) getloclist({nr}) *getloclist()* Returns a list with all the entries in the location list for - window {nr}. When {nr} is zero the current window is used. + 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 returned. For an invalid window number {nr}, an empty list is returned. Otherwise, same as |getqflist()|. @@ -3770,16 +4115,21 @@ getreg([{regname} [, 1 [, {list}]]]) *getreg()* The result is a String, which is the contents of register {regname}. Example: > :let cliptext = getreg('*') -< getreg('=') returns the last evaluated value of the expression +< When {regname} was not set the result is a empty string. + + getreg('=') returns the last evaluated value of the expression register. (For use in maps.) getreg('=', 1) returns the expression itself, so that it can be restored with |setreg()|. For other registers the extra argument is ignored, thus you can always give it. - If {list} is present and non-zero result type is changed to - |List|. Each list item is one text line. Use it if you care + + If {list} is present and non-zero, the result type is changed + to |List|. Each list item is one text line. Use it if you care about zero bytes possibly present inside register: without third argument both NLs and zero bytes are represented as NLs (see |NL-used-for-Nul|). + When the register was not set an empty list is returned. + If {regname} is not specified, |v:register| is used. @@ -3793,6 +4143,19 @@ getregtype([{regname}]) *getregtype()* <CTRL-V> is one character with value 0x16. If {regname} is not specified, |v:register| is used. +gettabinfo([{arg}]) *gettabinfo()* + If {arg} is not specified, then information about all the tab + pages is returned as a List. Each List item is a Dictionary. + Otherwise, {arg} specifies the tab page number and information + about that one is returned. If the tab page does not exist an + empty List is returned. + + Each List item is a Dictionary with the following entries: + nr tab page number. + variables a reference to the dictionary with + tabpage-local variables + windows List of window IDs in the tag page. + gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()* Get the value of a tab-local variable {varname} in tab page {tabnr}. |t:var| @@ -3806,13 +4169,16 @@ gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()* gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* Get the value of window-local variable {varname} in window {winnr} in tab page {tabnr}. - When {varname} starts with "&" get the value of a window-local - option. When {varname} is empty a dictionary with all window-local variables is returned. + When {varname} is equal to "&" get the values of all + window-local options in a Dictionary. + Otherwise, when {varname} starts with "&" get the value of a + window-local option. 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. 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 @@ -3833,6 +4199,31 @@ getwinposy() The result is a Number, which is the Y coordinate in pixels of the top of the GUI Vim window. The result will be -1 if the information is not available. +getwininfo([{winid}]) *getwininfo()* + Returns information about windows as a List with Dictionaries. + + If {winid} is given Information about the window with that ID + 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. + + Each List item is a Dictionary with the following entries: + bufnum 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 + variables a reference to the dictionary with + window-local variables + width window width + winid window ID + + To obtain all window-local variables use: > + gettabwinvar({tabnr}, {winnr}, '&') + getwinvar({winnr}, {varname} [, {def}]) *getwinvar()* Like |gettabwinvar()| for the current tabpage. Examples: > @@ -3929,7 +4320,7 @@ has_key({dict}, {key}) *has_key()* The result is a Number, which is 1 if |Dictionary| {dict} has an entry with key {key}. Zero otherwise. -haslocaldir([{window}[, {tab}]]) *haslocaldir()* +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. @@ -3940,7 +4331,8 @@ haslocaldir([{window}[, {tab}]]) *haslocaldir()* haslocaldir() haslocaldir(0) haslocaldir(0, 0) -< If {window} is -1 it is ignored, only the tab is resolved. +< {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()* The result is a Number, which is 1 if there is a mapping that @@ -4051,8 +4443,6 @@ hlexists({name}) *hlexists()* defined in some way. Not necessarily when highlighting has been defined for it, it may also have been used for a syntax item. - *highlight_exists()* - Obsolete name: highlight_exists(). *hlID()* hlID({name}) The result is a Number, which is the ID of the highlight group @@ -4062,8 +4452,6 @@ hlID({name}) The result is a Number, which is the ID of the highlight group group. For example, to get the background color of the "Comment" group: > :echo synIDattr(synIDtrans(hlID("Comment")), "bg") -< *highlightID()* - Obsolete name: highlightID(). hostname() *hostname()* The result is a String, which is the name of the machine on @@ -4081,11 +4469,7 @@ iconv({expr}, {from}, {to}) *iconv()* Most conversions require Vim to be compiled with the |+iconv| feature. Otherwise only UTF-8 to latin1 conversion and back can be done. - This can be used to display messages with special characters, - no matter what 'encoding' is set to. Write the message in - UTF-8 and use: > - echo iconv(utf8_str, "utf-8", &enc) -< Note that Vim uses UTF-8 for all Unicode encodings, conversion + Note that Vim uses UTF-8 for all Unicode encodings, conversion from/to UCS-2 is automatically changed to use UTF-8. You cannot use UCS-2 in a string anyway, because of the NUL bytes. {only available when compiled with the |+multi_byte| feature} @@ -4259,8 +4643,11 @@ items({dict}) *items()* order. jobclose({job}[, {stream}]) {Nvim} *jobclose()* - Close {job}'s {stream}, which can be one "stdin", "stdout" or - "stderr". If {stream} is omitted, all streams are closed. + Close {job}'s {stream}, which can be one of "stdin", "stdout", + "stderr" or "rpc" (closes the rpc channel for a job started + with the "rpc" option.) If {stream} is omitted, all streams + are closed. If the job is a pty job, this will then close the + pty master, sending SIGHUP to the job process. jobpid({job}) {Nvim} *jobpid()* Return the pid (process id) of {job}. @@ -4282,42 +4669,55 @@ jobsend({job}, {data}) {Nvim} *jobsend()* :call jobsend(j, ["abc", "123\n456", ""]) < will send "abc<NL>123<NUL>456<NL>". + If the job was started with the rpc option this function + cannot be used, instead use |rpcnotify()| and |rpcrequest()| + to communicate with the job. + jobstart({cmd}[, {opts}]) {Nvim} *jobstart()* - Spawns {cmd} as a job. If {cmd} is a |List|, it will be run - directly. If {cmd} is a |string|, it will be roughly - equivalent to > - :call jobstart(split(&shell) + split(&shellcmdflag) + ['{cmd}']) -< NOTE: read |shell-unquoting| before constructing any lists - with 'shell' or 'shellcmdflag' options. The above call is - only written to show the idea, one needs to perform unquoting - and do split taking quotes into account. - If passed, {opts} must be a dictionary with any of the - following keys: - - on_stdout: stdout event handler - - on_stderr: stderr event handler - - on_exit: exit event handler - - pty: If set, the job will be connected to a new pseudo - terminal, and the job streams are connected to the master - file descriptor. - - width: Width of the terminal screen(only if pty is set) - - height: Height of the terminal screen(only if pty is set) - - TERM: $TERM environment variable(only if pty is set) - - detach: Detach the job process from the nvim process. The - process won't get killed when nvim exists. If the process - dies before nvim exits, on_exit will still be invoked. - This option is only allowed for non-pty jobs. - Either funcrefs or function names can be passed as event - handlers. The {opts} object is also used as the "self" - argument for the callback, so the caller may pass arbitrary - data by setting other key.(see |Dictionary-function| for more - information). + 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']) +< + {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|) + on_exit : exit event handler (function name or |Funcref|) + cwd : Working directory of the job; defaults to + |current-directory|. + rpc : If set, |msgpack-rpc| will be used to communicate + with the job over stdin and stdout. "on_stdout" is + then ignored, but "on_stderr" can still be used. + pty : If set, the job will be connected to a new pseudo + terminal, and the job streams are connected to + the master file descriptor. "on_stderr" is ignored + as all output will be received on stdout. + + width : (pty only) Width of the terminal screen + height : (pty only) Height of the terminal screen + TERM : (pty only) $TERM environment variable + detach : (non-pty only) Detach the job process from the + nvim process. The process will not get killed + when nvim exits. If the process dies before + nvim exits, on_exit will still be invoked. + + {opts} is passed as |self| to the callback; the caller may + pass arbitrary data by setting other keys. Returns: - - The job ID on success, which is used by |jobsend()| and - |jobstop()| - - 0 when the job table is full or on invalid arguments - - -1 when {cmd}[0] is not executable. Will never fail if - {cmd} is a string unless 'shell' is not executable. - See |job-control| for more information. + - The job ID on success, which is used by |jobsend()| (or + |rpcnotify()| and |rpcrequest()| if "rpc" option was used) + and |jobstop()| + - 0 on invalid arguments or if the job table is full + - -1 if {cmd}[0] is not executable. + See |job-control| and |msgpack-rpc| for more information. jobstop({job}) {Nvim} *jobstop()* Stop a job created with |jobstart()| by sending a `SIGTERM` @@ -4359,9 +4759,7 @@ join({list} [, {sep}]) *join()* json_decode({expr}) *json_decode()* Convert {expr} from JSON object. Accepts |readfile()|-style list as the input, as well as regular string. May output any - Vim value. When 'encoding' is not UTF-8 string is converted - from UTF-8 to 'encoding', failing conversion fails - json_decode(). In the following cases it will output + Vim value. In the following cases it will output |msgpack-special-dict|: 1. Dictionary contains duplicate key. 2. Dictionary contains empty key. @@ -4369,33 +4767,22 @@ json_decode({expr}) *json_decode()* dictionary and for string will be emitted in case string with NUL byte was a dictionary key. - Note: function treats its input as UTF-8 always regardless of - 'encoding' value. This is needed because JSON source is - supposed to be external (e.g. |readfile()|) and JSON standard - allows only a few encodings, of which UTF-8 is recommended and - the only one required to be supported. Non-UTF-8 characters - are an error. + Note: function treats its input as UTF-8 always. The JSON + standard allows only a few encodings, of which UTF-8 is + recommended and the only one required to be supported. + Non-UTF-8 characters are an error. json_encode({expr}) *json_encode()* Convert {expr} into a JSON string. Accepts - |msgpack-special-dict| as the input. Converts from 'encoding' - to UTF-8 when encoding strings. Will not convert |Funcref|s, + |msgpack-special-dict| as the input. Will not convert |Funcref|s, mappings with non-string keys (can be created as |msgpack-special-dict|), values with self-referencing containers, strings which contain non-UTF-8 characters, pseudo-UTF-8 strings which contain codepoints reserved for surrogate pairs (such strings are not valid UTF-8 strings). - When converting 'encoding' is taken into account, if it is not - "utf-8", then conversion is performed before encoding strings. Non-printable characters are converted into "\u1234" escapes or special escapes like "\t", other are dumped as-is. - Note: all characters above U+0079 are considered non-printable - when 'encoding' is not UTF-8. This function always outputs - UTF-8 strings as required by the standard thus when 'encoding' - is not unicode resulting string will look incorrect if - "\u1234" notation is not used. - keys({dict}) *keys()* Return a |List| with all the keys of {dict}. The |List| is in arbitrary order. @@ -4497,9 +4884,9 @@ line2byte({lnum}) *line2byte()* Return the byte count from the start of the buffer for line {lnum}. This includes the end-of-line character, depending on the 'fileformat' option for the current buffer. The first - line returns 1. 'encoding' matters, 'fileencoding' is ignored. - This can also be used to get the byte count for the line just - below the last line: > + line returns 1. UTF-8 encoding is used, 'fileencoding' is + ignored. This can also be used to get the byte count for the + line just below the last line: > line2byte(line("$") + 1) < This is the buffer size plus one. If 'fileencoding' is empty it is the file size plus one. @@ -4737,8 +5124,8 @@ matchadd({group}, {pattern}[, {priority}[, {id} [, {dict}]]]) respectively. If the {id} argument is not specified or -1, |matchadd()| automatically chooses a free ID. - The optional {dict} argmument allows for further custom - values. Currently this is used to specify a match specifc + The optional {dict} argument allows for further custom + values. Currently this is used to specify a match specific conceal character that will be shown for |hl-Conceal| highlighted matches. The dict can have the following members: @@ -4854,6 +5241,24 @@ matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()* When {expr} is a |List| then the matching item is returned. The type isn't changed, it's not necessarily a String. +matchstrpos({expr}, {pat}[, {start}[, {count}]]) *matchstrpos()* + Same as |matchstr()|, but return the matched string, the start + position and the end position of the match. Example: > + :echo matchstrpos("testing", "ing") +< results in ["ing", 4, 7]. + When there is no match ["", -1, -1] is returned. + The {start}, if given, has the same meaning as for |match()|. > + :echo matchstrpos("testing", "ing", 2) +< results in ["ing", 4, 7]. > + :echo matchstrpos("testing", "ing", 5) +< result is ["", -1, -1]. + When {expr} is a |List| then the matching item, the index + of first item where {pat} matches, the start position and the + end position of the match are returned. > + :echo matchstrpos([1, '__x'], '\a') +< result is ["x", 1, 2, 3]. + 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 @@ -4923,7 +5328,7 @@ msgpackdump({list}) {Nvim} *msgpackdump()* (dictionary with zero items is represented by 0x80 byte in messagepack). - Limitations: *E951* *E952* *E953* + Limitations: *E5004* *E5005* 1. |Funcref|s cannot be dumped. 2. Containers that reference themselves cannot be dumped. 3. Dictionary keys are always dumped as STR strings. @@ -5018,15 +5423,26 @@ nr2char({expr}[, {utf8}]) *nr2char()* value {expr}. Examples: > nr2char(64) returns "@" nr2char(32) returns " " -< When {utf8} is omitted or zero, the current 'encoding' is used. - Example for "utf-8": > +< Example for "utf-8": > nr2char(300) returns I with bow character -< With {utf8} set to 1, always return utf-8 characters. +< UTF-8 encoding is always used, {utf8} option has no effect, + and exists only for backwards-compatibility. Note that a NUL character in the file is specified with nr2char(10), because NULs are represented with newline characters. nr2char(0) is a real NUL and terminates the string, thus results in an empty string. +nvim_...({...}) *nvim_...()* *eval-api* + Call nvim |api| functions. The type checking of arguments will + be stricter than for most other builtins. For instance, + if Integer is expected, a |Number| must be passed in, a + |String| will not be autoconverted. + Buffer numbers, as returned by |bufnr()| could be used as + first argument to nvim_buf_... functions. All functions + expecting an object (buffer, window or tabpage) can + also take the numerical value 0 to indicate the current + (focused) object. + or({expr}, {expr}) *or()* Bitwise OR on the two arguments. The arguments are converted to a number. A List, Dict or Float argument causes an error. @@ -5180,6 +5596,16 @@ printf({fmt}, {expr1} ...) *printf()* numeric field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result. + The 'h' modifier indicates the argument is 16 bits. + The 'l' modifier indicates the argument is 32 bits. + The 'L' modifier indicates the argument is 64 bits. + Generally, these modifiers are not useful. They are + ignored when type is known from the argument. + + i alias for d + D alias for ld + U alias for lu + O alias for lo *printf-c* c The Number argument is converted to a byte, and the @@ -5196,7 +5622,7 @@ printf({fmt}, {expr1} ...) *printf()* feature works just like 's'. *printf-f* *E807* - f The Float argument is converted into a string of the + f F The Float argument is converted into a string of the form 123.456. The precision specifies the number of digits after the decimal point. When the precision is zero the decimal point is omitted. When the precision @@ -5246,13 +5672,12 @@ pumvisible() *pumvisible()* This can be used to avoid some things that would remove the popup menu. - *E860* py3eval({expr}) *py3eval()* Evaluate Python expression {expr} and return its result converted to Vim data structures. Numbers and strings are returned as they are (strings are copied though, Unicode strings are additionally converted to - 'encoding'). + UTF-8). Lists are represented as Vim |List| type. Dictionaries are represented as Vim |Dictionary| type with keys converted to strings. @@ -5302,8 +5727,7 @@ readfile({fname} [, {binary} [, {max}]]) Otherwise: - CR characters that appear before a NL are removed. - Whether the last line ends in a NL or not does not matter. - - When 'encoding' is Unicode any UTF-8 byte order mark is - removed from the text. + - Any UTF-8 byte order mark is removed from the text. When {max} is given this specifies the maximum number of lines to be read. Useful if you only want to check the first ten lines of a file: > @@ -5325,14 +5749,20 @@ reltime([{start} [, {end}]]) *reltime()* the item depends on the system. It can be passed to |reltimestr()| to convert it to a string or |reltimefloat()| to convert to a float. - Without an argument it returns the current time. - With one argument is returns the time passed since the time + + Without an argument it returns the current "relative time", an + implementation-defined value meaningful only when used as an + argument to |reltime()|, |reltimestr()| and |reltimefloat()|. + + With one argument it returns the time passed since the time specified in the argument. With two arguments it returns the time passed between {start} and {end}. The {start} and {end} arguments must be values returned by reltime(). + Note: |localtime()| returns the current (non-relative) time. + reltimefloat({time}) *reltimefloat()* Return a Float that represents the time value of {time}. Unit of time is seconds. @@ -5504,31 +5934,31 @@ round({expr}) *round()* < -5.0 rpcnotify({channel}, {event}[, {args}...]) {Nvim} *rpcnotify()* - Sends {event} to {channel} via |msgpack-rpc| and returns - immediately. If {channel} is 0, the event is broadcast to all - channels. Example: > + Sends {event} to {channel} via |RPC| and returns immediately. + If {channel} is 0, the event is broadcast to all channels. + Example: > :au VimLeave call rpcnotify(0, "leaving") rpcrequest({channel}, {method}[, {args}...]) {Nvim} *rpcrequest()* Sends a request to {channel} to invoke {method} via - |msgpack-rpc| and blocks until a response is received. + |RPC| and blocks until a response is received. Example: > :let result = rpcrequest(rpc_chan, "func", 1, 2, 3) rpcstart({prog}[, {argv}]) {Nvim} *rpcstart()* - Spawns {prog} as a job (optionally passing the list {argv}), - and opens a |msgpack-rpc| channel with the spawned process's - stdin/stdout. It returns: - - The channel id on success, which is used by |rpcrequest()|, - |rpcnotify()| and |rpcstop()| - - 0 on failure. - Example: > - :let rpc_chan = rpcstart('prog', ['arg1', 'arg2']) + Deprecated. Replace > + :let id = rpcstart('prog', ['arg1', 'arg2']) +< with > + :let id = jobstart(['prog', 'arg1', 'arg2'], {'rpc': v:true}) rpcstop({channel}) {Nvim} *rpcstop()* - Closes a |msgpack-rpc| {channel}, possibly created via - |rpcstart()|. Also closes channels created by connections to - |$NVIM_LISTEN_ADDRESS|. + Closes an |RPC| {channel}. If the channel is a job + started with |jobstart()| the job is killed. + It is better to use |jobstop()| in this case, or use + |jobclose|(id, "rpc") to only close the channel without + killing the job. + Closes the socket connection if the channel was opened by + connecting to |v:servername|. screenattr(row, col) *screenattr()* Like screenchar(), but return the attribute. This is a rather @@ -5591,7 +6021,7 @@ search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()* 'ignorecase', 'smartcase' and 'magic' are used. - When the 'z' flag is not given seaching always starts in + When the 'z' flag is not given, searching always starts in column zero and then matches before the cursor are skipped. When the 'c' flag is present in 'cpo' the next search starts after the match. Without the 'c' flag the next search starts @@ -5906,11 +6336,13 @@ setline({lnum}, {text}) *setline()* setloclist({nr}, {list} [, {action}[, {title}]]) *setloclist()* Create or replace or add to the location list for window {nr}. - When {nr} is zero the current window is used. For a location - list window, the displayed location list is modified. For an - invalid window number {nr}, -1 is returned. If {title} is - given, it will be used to set |w:quickfix_title| after opening - the location window. + {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 + modified. For an invalid window number {nr}, -1 is returned. If + {title} is given, it will be used to set |w:quickfix_title| + after opening the location window. Otherwise, same as |setqflist()|. Also see |location-list|. @@ -5999,12 +6431,18 @@ setqflist({list} [, {action}[, {title}]]) *setqflist()* Note that the list is not exactly the same as what |getqflist()| returns. + *E927* If {action} is set to 'a', then the items from {list} are added to the existing quickfix list. If there is no existing - list, then a new list is created. If {action} is set to 'r', - then the items from the current quickfix list are replaced - with the items from {list}. If {action} is not present or is - set to ' ', then a new list is created. + list, then a new list is created. + + If {action} is set to 'r', then the items from the current + quickfix list are replaced with the items from {list}. This + can also be used to clear the list: > + :call setqflist([], 'r') +< + If {action} is not present or is set to ' ', then a new list + is created. If {title} is given, it will be used to set |w:quickfix_title| after opening the quickfix window. @@ -6017,7 +6455,7 @@ setqflist({list} [, {action}[, {title}]]) *setqflist()* *setreg()* -setreg({regname}, {value} [,{options}]) +setreg({regname}, {value} [, {options}]) Set the register {regname} to {value}. {value} may be any value returned by |getreg()|, including a |List|. @@ -6074,6 +6512,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. 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. @@ -6198,6 +6637,9 @@ sort({list} [, {func} [, {dict}]]) *sort()* *E702* sorted numerical. This is like 'n' but a string containing digits will be used as the number they represent. + When {func} is given and it is 'f' then all items will be + sorted numerical. All values must be a Number or a Float. + When {func} is a |Funcref| or a function name, this function is called to compare items. The function is invoked with two items as argument and must return zero if they are equal, 1 or @@ -6355,7 +6797,6 @@ strchars({expr} [, {skipcc}]) *strchars()* counted separately. When {skipcc} set to 1, Composing characters are ignored. Also see |strlen()|, |strdisplaywidth()| and |strwidth()|. - {skipcc} is only available after 7.4.755. For backward compatibility, you can define a wrapper function: > @@ -6373,6 +6814,13 @@ strchars({expr} [, {skipcc}]) *strchars()* endfunction endif < +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: > + strcharpart('abc', -1, 2) +< results in 'a'. strdisplaywidth({expr}[, {col}]) *strdisplaywidth()* The result is a Number, which is the number of display cells @@ -6406,6 +6854,12 @@ strftime({format} [, {time}]) *strftime()* < Not available on all systems. To check use: > :if exists("*strftime") +strgetchar({str}, {index}) *strgetchar()* + Get character {index} from {str}. This uses a character + index, not a byte index. Composing characters are considered + separate characters here. + Also see |strcharpart()| and |strchars()|. + stridx({haystack}, {needle} [, {start}]) *stridx()* The result is a Number, which gives the byte index in {haystack} of the first occurrence of the String {needle}. @@ -6443,8 +6897,7 @@ string({expr}) Return {expr} converted to a String. If {expr} is a Number, for infinite and NaN floating-point values representations which use |str2float()|. Strings are also dumped literally, only single quote is escaped, which does not allow using YAML - for parsing back binary strings (including text when - 'encoding' is not UTF-8). |eval()| should always work for + for parsing back binary strings. |eval()| should always work for strings and floats though and this is the only official method, use |msgpackdump()| or |json_encode()| if you need to share data with other application. @@ -6461,14 +6914,17 @@ strlen({expr}) The result is a Number, which is the length of the String strpart({src}, {start}[, {len}]) *strpart()* The result is a String, which is part of {src}, starting from byte {start}, with the byte length {len}. - When non-existing bytes are included, this doesn't result in - an error, the bytes are simply omitted. + To count characters instead of bytes use |strcharpart()|. + + When bytes are selected which do not exist, this doesn't + result in an error, the bytes are simply omitted. If {len} is missing, the copy continues from {start} till the end of the {src}. > strpart("abcdefg", 3, 2) == "de" strpart("abcdefg", -2, 4) == "ab" strpart("abcdefg", 5, 4) == "fg" strpart("abcdefg", 3) == "defg" + < Note: To get the first character, {start} must be 0. For example, to get three bytes under and after the cursor: > strpart(getline("."), col(".") - 1, 3) @@ -6574,9 +7030,9 @@ synID({lnum}, {col}, {trans}) *synID()* that's where the cursor can be in Insert mode, synID() returns zero. - When {trans} is non-zero, transparent items are reduced to the + When {trans} is |TRUE|, transparent items are reduced to the item that they reveal. This is useful when wanting to know - the effective color. When {trans} is zero, the transparent + the effective color. When {trans} is |FALSE|, the transparent item is returned. This is useful when wanting to know which syntax item is effective (e.g. inside parens). Warning: This function can be very slow. Best speed is @@ -6659,26 +7115,32 @@ synstack({lnum}, {col}) *synstack()* valid positions. system({cmd} [, {input}]) *system()* *E677* - Get the output of the shell command {cmd} as a |string|. {cmd} - will be run the same as in |jobstart()|. See |systemlist()| - to get the output as a |List|. - - When {input} is given and is a string this string is written - to a file and passed as stdin to the command. The string is - written as-is, you need to take care of using the correct line - separators yourself. - If {input} is given and is a |List| it is written to the file - in a way |writefile()| does with {binary} set to "b" (i.e. - with a newline between each list item with newlines inside - list items converted to NULs). - Pipes are not used. + Get the output of {cmd} as a |string| (use |systemlist()| to + get a |List|). {cmd} is treated exactly as in |jobstart()|. + Not to be used for interactive commands. + + If {input} is a string it is written to a pipe and passed as + stdin to the command. The string is written as-is, line + separators are not changed. + If {input} is a |List| it is written to the pipe as + |writefile()| does with {binary} set to "b" (i.e. with + a newline between each list item, and newlines inside list + items converted to NULs). + *E5677* + Note: system() cannot write to or read from backgrounded ("&") + shell commands, e.g.: > + :echo system("cat - &", "foo")) +< which is equivalent to: > + $ echo foo | bash -c 'cat - &' +< The pipes are disconnected (unless overridden by shell + redirection syntax) before input can reach it. Use + |jobstart()| instead. Note: Use |shellescape()| or |::S| with |expand()| or |fnamemodify()| to escape special characters in a command argument. Newlines in {cmd} may cause the command to fail. The characters in 'shellquote' and 'shellxquote' may also cause trouble. - This is not to be used for interactive commands. The result is a String. Example: > :let files = system("ls " . shellescape(expand('%:h'))) @@ -6693,9 +7155,6 @@ system({cmd} [, {input}]) *system()* *E677* The command executed is constructed using several options when {cmd} is a string: 'shell' 'shellcmdflag' {cmd} - The command will be executed in "cooked" mode, so that a - CTRL-C will interrupt the command (on Unix at least). - The resulting error code can be found in |v:shell_error|. This function will fail in |restricted-mode|. @@ -6816,7 +7275,7 @@ termopen({cmd}[, {opts}]) {Nvim} *termopen()* and `$TERM` is set to "xterm-256color". Returns the same values as |jobstart()|. - See |nvim-terminal-emulator| for more information. + See |terminal-emulator| for more information. tan({expr}) *tan()* Return the tangent of {expr}, measured in radians, as a |Float| @@ -6840,6 +7299,38 @@ tanh({expr}) *tanh()* < -0.761594 + *timer_start()* +timer_start({time}, {callback} [, {options}]) + Create a timer and return the timer ID. + + {time} is the waiting time in milliseconds. This is the + minimum time before invoking the callback. When the system is + 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 + 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. + + Example: > + func MyHandler(timer) + echo 'Handler called' + endfunc + let timer = timer_start(500, 'MyHandler', + \ {'repeat': 3}) +< This will invoke MyHandler() three times at 500 msec + intervals. + {only available when compiled with the |+timers| feature} + +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. + tolower({expr}) *tolower()* The result is a copy of the String given, with all uppercase characters turned into lowercase (just like applying |gu| to @@ -7039,11 +7530,40 @@ wildmenumode() *wildmenumode()* (Note, this needs the 'wildcharm' option set appropriately). +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. + +win_getid([{win} [, {tab}]]) *win_getid()* + 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. + Without {tab} use the current tab, otherwise the tab with + number {tab}. The first tab has number one. + Return zero if the window cannot be found. + +win_gotoid({expr}) *win_gotoid()* + Go to window with ID {expr}. This may also change the current + tabpage. + Return 1 if successful, 0 if the window cannot be found. + +win_id2tabwin({expr} *win_id2tabwin()* + Return a list with the tab number and window number of window + with ID {expr}: [tabnr, winnr]. + Return [0, 0] if the window cannot be found. + +win_id2win({expr}) *win_id2win()* + Return the window number of window with ID {expr}. + Return 0 if the window cannot be found in the current tabpage. + *winbufnr()* winbufnr({nr}) The result is a Number, which is the number of the buffer - associated with window {nr}. When {nr} is zero, the number of - the buffer in the current window is returned. When window - {nr} doesn't exist, -1 is returned. + associated with window {nr}. {nr} can be the window number or + 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. Example: > :echo "The file in the current window is " . bufname(winbufnr(0)) < @@ -7054,6 +7574,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. 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. @@ -7133,6 +7654,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. 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. @@ -7208,7 +7730,11 @@ There are four types of features: Example: > :if has("gui_running") < *has-patch* -3. Included patches. The "patch123" feature means that patch 123 has been +3. {Nvim} version. The "nvim-1.2.3" feature means that the Nvim version is + 1.2.3 or later. Example: > + :if has("nvim-1.2.3") +< +4. Included patches. The "patch123" feature means that patch 123 has been included. Note that this form does not check the version of Vim, you need to inspect |v:version| for that. Example (checking version 6.2.148 or later): > @@ -7216,7 +7742,7 @@ There are four types of features: < Note that it's possible for patch 147 to be omitted even though 148 is included. -4. Beyond a certain version or at a certain version and including a specific +5. Beyond a certain version or at a certain version and including a specific patch. The "patch-7.4.237" feature means that the Vim version is 7.5 or later, or it is version 7.4 and patch 237 was included. Note that this only works for patch 7.4.237 and later, before that you @@ -7247,7 +7773,7 @@ dialog_gui Compiled with GUI dialog support. digraphs Compiled with support for digraphs. eval Compiled with expression evaluation support. Always true, of course! -ex_extra Compiled with extra Ex commands |+ex_extra|. +ex_extra |+ex_extra|, always true now extra_search Compiled with support for |'incsearch'| and |'hlsearch'| farsi Compiled with Farsi support |farsi|. @@ -7288,6 +7814,7 @@ multi_byte Compiled with support for 'encoding' multi_byte_encoding 'encoding' is set to a multi-byte encoding. multi_byte_ime Compiled with support for IME input method. multi_lang Compiled with support for multiple languages. +nvim This is Nvim. |has-patch| ole Compiled with OLE automation support for Win32. path_extra Compiled with up/downwards search in 'path' and 'tags' persistent_undo Compiled with support for persistent undo history. @@ -7323,12 +7850,14 @@ termresponse Compiled with support for |t_RV| and |v:termresponse|. textobjects Compiled with support for |text-objects|. tgetent Compiled with tgetent support, able to use a termcap or terminfo file. +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. user_commands User-defined commands. vertsplit Compiled with vertically split windows |:vsplit|. vim_starting True while initial source'ing takes place. |startup| + *vim_starting* virtualedit Compiled with 'virtualedit' option. visual Compiled with Visual mode. visualextra Compiled with extra Visual mode commands. @@ -7953,7 +8482,7 @@ This does NOT work: > From Vim version 4.5 until 5.0, every Ex command in between the ":if" and ":endif" is ignored. These two commands were just to allow for future expansions in a - backwards compatible way. Nesting was allowed. Note + backward compatible way. Nesting was allowed. Note that any ":else" or ":elseif" was ignored, the "else" part was not executed either. @@ -8020,14 +8549,6 @@ This does NOT work: > endfor < Note that reordering the list (e.g., with sort() or reverse()) may have unexpected effects. - Note that the type of each list item should be - identical to avoid errors for the type of {var} - changing. Unlet the variable at the end of the loop - to allow multiple item types: > - for item in ["foo", ["bar"]] - echo item - unlet item " E706 without this - endfor :for [{var1}, {var2}, ...] in {listlist} :endfo[r] diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt index 76aa3a50ce..d15815191e 100644 --- a/runtime/doc/filetype.txt +++ b/runtime/doc/filetype.txt @@ -1,4 +1,4 @@ -*filetype.txt* For Vim version 7.4. Last change: 2015 Dec 06 +*filetype.txt* For Vim version 7.4. Last change: 2016 Jun 20 VIM REFERENCE MANUAL by Bram Moolenaar @@ -500,7 +500,7 @@ Options: avoid that a Subject line with "Vim:" in it will cause an error message. 'textwidth' is set to 72. This is often recommended for e-mail. -'formatoptions' is set to break text lines and to repeat the comment leader +'formatoptions' is set to break text lines and to repeat the comment leader in new lines, so that a leading ">" for quotes is repeated. You can also format quoted text with |gq|. @@ -512,37 +512,44 @@ Local mappings: MAN *ft-man-plugin* *:Man* *man.vim* -Displays a manual page in a nice way. Also see the user manual -|find-manpage|. +View manpages in Nvim. Supports highlighting, completion, locales, and +navigation. Also see |find-manpage|. -To start using the ":Man" command before any manual page was loaded, source -this script from your startup vimrc file: > +To use Nvim as a manpager: > + export MANPAGER="nvim -c 'set ft=man' -" - runtime ftplugin/man.vim +man.vim will always attempt to reuse the closest man window (above/left) but +otherwise create a split. -Options: -'iskeyword' the '.' character is added to be able to use CTRL-] on the - manual page name. +The case sensitivity of completion is controlled by 'fileignorecase'. Commands: -Man {name} Display the manual page for {name} in a window. -Man {number} {name} - Display the manual page for {name} in a section {number}. - -Global mapping: -<Leader>K Displays the manual page for the word under the cursor. +Man {name} Display the manpage for {name}. +Man {sect} {name} Display the manpage for {name} and section {sect}. +Man {name}({sect}) Alternate syntax which completes the section. +Man {sect} {name}({sect}) Used during completion to show the real section of + when the provided section is a prefix, e.g. 1m vs 1. +Man {path} Open the manpage specified by path. Prepend "./" if + page is in the current directory. +Man Open the manpage for the <cWORD> (man buffers) + or <cword> (non-man buffers) under the cursor. + +|:Man| accepts command modifiers. For example, to use a vertical split: > + :vertical Man printf Local mappings: -CTRL-] Jump to the manual page for the word under the cursor. -CTRL-T Jump back to the previous manual page. -q Same as ":quit" - -To enable folding use this: > - let g:ft_man_folding_enable = 1 -If you do not like the default folding, use an autocommand to add your desired -folding style instead. For example: > - autocmd FileType man setlocal foldmethod=indent foldenable +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. +q :quit if invoked as $MANPAGER, otherwise :close. +Variables: +*g:no_man_maps* Do not create mappings in manpage buffers. +*g:ft_man_folding_enable* Fold manpages with foldmethod=indent foldnestmax=1. +*b:man_default_sects* Comma-separated, ordered list of preferred sections. + For example in C one usually wants section 3 or 2: > + :let b:man_default_sections = '3,2' PDF *ft-pdf-plugin* diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt index 8d97678af2..1e8bb408d9 100644 --- a/runtime/doc/gui.txt +++ b/runtime/doc/gui.txt @@ -395,9 +395,9 @@ You may make selections with the mouse (see |gui-mouse-select|), or by using Vim's Visual mode (see |v|). If 'a' is present in 'guioptions', then whenever a selection is started (Visual or Select mode), or when the selection is changed, Vim becomes the owner of the windowing system's primary selection -(on MS-Windows the |gui-clipboard| is used). +(on MS-Windows the |clipboard| is used). - *clipboard* + *primary-selection* There is a special register for storing this selection, it is the "* register. Nothing is put in here unless the information about what text is selected is about to change (e.g. with a left mouse click somewhere), or when @@ -825,13 +825,13 @@ the <CR> key. |<>|) See section |42.4| in the user manual. - *:tmenu* *:tm* + *:tmenu* :tm[enu] {menupath} {rhs} Define a tip for a menu or tool. {only in X11 and Win32 GUI} :tm[enu] [menupath] List menu tips. {only in X11 and Win32 GUI} - *:tunmenu* *:tu* + *:tunmenu* :tu[nmenu] {menupath} Remove a tip for a menu or tool. {only in X11 and Win32 GUI} diff --git a/runtime/doc/gui_w32.txt b/runtime/doc/gui_w32.txt deleted file mode 100644 index 228be9eab2..0000000000 --- a/runtime/doc/gui_w32.txt +++ /dev/null @@ -1,437 +0,0 @@ -*gui_w32.txt* For Vim version 7.4. Last change: 2014 Dec 20 - - - VIM REFERENCE MANUAL by Bram Moolenaar - - -Vim's Win32 Graphical User Interface *gui-w32* *win32-gui* - -1. Starting the GUI |gui-w32-start| -2. Vim as default editor |vim-default-editor| -3. Using the clipboard |gui-clipboard| -4. Shell Commands |gui-shell-win32| -5. Special colors |win32-colors| -6. Windows dialogs & browsers |gui-w32-dialogs| -7. Command line arguments |gui-w32-cmdargs| -8. Various |gui-w32-various| - -Other relevant documentation: -|gui.txt| For generic items of the GUI. -|os_win32.txt| For Win32 specific items. - -============================================================================== -1. Starting the GUI *gui-w32-start* - -The Win32 GUI version of Vim will always start the GUI, no matter how you -start it or what it's called. - -The GUI will always run in the Windows subsystem. Mostly shells automatically -return with a command prompt after starting gvim. If not, you should use the -"start" command: > - start gvim [options] file .. - -Note: All fonts (bold, italic) must be of the same size!!! If you don't do -this, text will disappear or mess up the display. Vim does not check the font -sizes. It's the size in screen pixels that must be the same. Note that some -fonts that have the same point size don't have the same pixel size! -Additionally, the positioning of the fonts must be the same (ascent and -descent). - -The Win32 GUI has an extra menu item: "Edit/Select Font". It brings up the -standard Windows font selector. - -Setting the menu height doesn't work for the Win32 GUI. - - *gui-win32-maximized* -If you want Vim to start with a maximized window, add this command to your -vimrc or gvimrc file: > - au GUIEnter * simalt ~x -< -============================================================================== -2. Vim as default editor *vim-default-editor* - -To set Vim as the default editor for a file type: -1. Start a Windows Explorer -2. Choose View/Options -> File Types -3. Select the path to gvim for every file type that you want to use it for. - (you can also use three spaces in the file type field, for files without an - extension). - In the "open" action, use: > - gvim "%1" -< The quotes are required for using file names with embedded spaces. - You can also use this: > - gvim "%L" -< This should avoid short (8.3 character) file names in some situations. But - I'm not sure if this works everywhere. - -When you open a file in Vim by double clicking it, Vim changes to that -file's directory. - -If you want Vim to start full-screen, use this for the Open action: > - gvim -c "simalt ~x" "%1" - -Another method, which also works when you put Vim in another directory (e.g., -when you have got a new version): -1. select a file you want to use Vim with -2. <Shift-F10> -3. select "Open With..." menu entry -4. click "Other..." -5. browse to the (new) location of Vim and click "Open" -6. make "Always Use this program..." checked -7. <OK> - - *send-to-menu* *sendto* -You can also install Vim in the "Send To" menu: -1. Start a Windows Explorer -2. Navigate to your sendto directory: - Windows NT: %windir%\profiles\%user%\sendto (e.g. - "c:\winnt\profiles\mattha\sendto"). -3. Right-click in the file pane and select New->Shortcut -4. Follow the shortcut wizard, using the full path to VIM/GVIM. - -When you 'send a file to Vim', Vim changes to that file's directory. Note, -however, that any long directory names will appear in their short (MS-DOS) -form. This is a limitation of the Windows "Send To" mechanism. - - *notepad* -You could replace notepad.exe with gvim.exe, but that has a few side effects. -Some programs rely on notepad arguments, which are not recognized by Vim. For -example "notepad -p" is used by some applications to print a file. It's -better to leave notepad where it is and use another way to start Vim. - - *win32-popup-menu* -A more drastic approach is to install an "Edit with Vim" entry in the popup -menu for the right mouse button. With this you can edit any file with Vim. - -This can co-exist with the file associations mentioned above. The difference -is that the file associations will make starting Vim the default action. With -the "Edit with Vim" menu entry you can keep the existing file association for -double clicking on the file, and edit the file with Vim when you want. For -example, you can associate "*.mak" with your make program. You can execute -the makefile by double clicking it and use the "Edit with Vim" entry to edit -the makefile. - -You can select any files and right-click to see a menu option called "Edit -with gvim". Choosing this menu option will invoke gvim with the file you have -selected. If you select multiple files, you will find two gvim-related menu -options: -"Edit with multiple gvims" -- one gvim for each file in the selection -"Edit with single gvim" -- one gvim for all the files in the selection -And if there already is a gvim running: -"Edit with existing gvim" -- edit the file with the running gvim - -The "edit with existing Vim" entries can be disabled by adding an entry in the -registry under HKLM\Software\Vim\Gvim, named DisableEditWithExisting, and with -any value. - *install-registry* -You can add the "Edit with Vim" menu entry in an easy way by using the -"install.exe" program. It will add several registry entries for you. - -You can also do this by hand. This is complicated! Use the install.exe if -you can. - -1. Start the registry editor with "regedit". -2. Add these keys: - key value name value ~ - HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99} - {default} Vim Shell Extension - HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99}\InProcServer32 - {default} {path}\gvimext.dll - ThreadingModel Apartment - HKEY_CLASSES_ROOT\*\shellex\ContextMenuHandlers\gvim - {default} {51EEE242-AD87-11d3-9C1E-0090278BBD99} - HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Approved - {51EEE242-AD87-11d3-9C1E-0090278BBD99} - Vim Shell Extension - HKEY_LOCAL_MACHINE\Software\Vim\Gvim - path {path}\gvim.exe - HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\vim 5.6 - DisplayName Vim 5.6: Edit with Vim popup menu entry - UninstallString {path}\uninstal.exe - - Replace {path} with the path that leads to the executable. - Don't type {default}, this is the value for the key itself. - -To remove "Edit with Vim" from the popup menu, just remove the registry -entries mentioned above. The "uninstal.exe" program can do this for you. You -can also use the entry in the Windows standard "Add/Remove Programs" list. - -If you notice that this entry overrules other file type associations, set -those associations again by hand (using Windows Explorer, see above). This -only seems to happen on some Windows NT versions (Windows bug?). Procedure: -1. Find the name of the file type. This can be done by starting the registry - editor, and searching for the extension in \\HKEY_CLASSES_ROOT -2. In a Windows Explorer, use View/Options/File Types. Search for the file - type in the list and click "Edit". In the actions list, you can select on - to be used as the default (normally the "open" action) and click on the - "Set Default" button. - - -Vim in the "Open With..." context menu *win32-open-with-menu* - -If you use the Vim install program you have the choice to add Vim to the "Open -With..." menu. This means you can use Vim to edit many files. Not every file -(for unclear reasons...), thus the "Edit with Vim" menu entry is still useful. - -One reason to add this is to be able to edit HTML files directly from Internet -Explorer. To enable this use the "Tools" menu, "Internet Options..." entry. -In the dialog select the "Programs" tab and select Vim in the "HTML editor" -choice. If it's not there than installing didn't work properly. - -Doing this manually can be done with this script: - ----------------------------------------------------------- -REGEDIT4 - -[HKEY_CLASSES_ROOT\Applications\gvim.exe] - -[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell] - -[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell\edit] - -[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell\edit\command] -@="c:\\vim\\vim62\\gvim.exe \"%1\"" - -[HKEY_CLASSES_ROOT\.htm\OpenWithList\gvim.exe] - -[HKEY_CLASSES_ROOT\*\OpenWithList\gvim.exe] - ----------------------------------------------------------- - -Change the "c:\\vim\\vim62" bit to where gvim.exe is actually located. - -To uninstall this run the Vim uninstall program or manually delete the -registry entries with "regedit". - -============================================================================== -3. Using the clipboard *gui-clipboard* - -Windows has a clipboard, where you can copy text to, and paste text from. Vim -supports this in several ways. For other systems see |gui-selections|. - -The "* register reflects the contents of the clipboard. |quotestar| - -When the "unnamed" string is included in the 'clipboard' option, the unnamed -register is the same. Thus you can yank to and paste from the clipboard -without prepending "* to commands. - -The 'a' flag in 'guioptions' is not included by default. This means that text -is only put on the clipboard when an operation is performed on it. Just -Visually selecting text doesn't put it on the clipboard. When the 'a' flag is -included, the text is copied to the clipboard even when it is not operated -upon. - - *mswin.vim* -To use the standard MS-Windows way of CTRL-X, CTRL-C and CTRL-V, use the -$VIMRUNTIME/mswin.vim script. You could add this line to your _vimrc file: > - source $VIMRUNTIME/mswin.vim - -Since CTRL-C is used to copy the text to the clipboard, it can't be used to -cancel an operation. Use CTRL-Break for that. - -CTRL-Z is used for undo. This means you can't suspend Vim with this key, use -|:suspend| instead (if it's supported at all). - - *CTRL-V-alternative* *CTRL-Q* -Since CTRL-V is used to paste, you can't use it to start a blockwise Visual -selection. You can use CTRL-Q instead. You can also use CTRL-Q in Insert -mode and Command-line mode to get the old meaning of CTRL-V. But CTRL-Q -doesn't work for terminals when it's used for control flow. - -NOTE: The clipboard support still has a number of bugs. - -============================================================================== -4. Shell Commands *gui-shell-win32* - -Vim uses another window for external commands, to make it possible to run any -command. The external command gets its own environment for running, just like -it was started from a DOS prompt. - - *win32-vimrun* -Executing an external command is done indirectly by the "vimrun" command. The -"vimrun.exe" must be in the path for this to work. Or it must be in the same -directory as the Vim executable. If "vimrun" cannot be found, the command is -executed directly, but then the DOS window closes immediately after the -external command has finished. -WARNING: If you close this window with the "X" button, and confirm the -question if you really want to kill the application, Vim may be killed too! -(This does not apply to commands run asynchronously with ":!start".) - - *win32-!start* -Normally, Vim waits for a command to complete before continuing (this makes -sense for most shell commands which produce output for Vim to use). If you -want Vim to start a program and return immediately, you can use the following -syntax on W95 & NT: > - :!start [/min] {command} -The optional "/min" causes the window to be minimized. - -============================================================================== -5. Special colors *win32-colors* - -On Win32, the normal DOS colors can be used. See |dos-colors|. - -Additionally the system configured colors can also be used. These are known -by the names Sys_XXX, where XXX is the appropriate system color name, from the -following list (see the Win32 documentation for full descriptions). Case is -ignored. - -Sys_3DDKShadow Sys_3DFace Sys_BTNFace -Sys_3DHilight Sys_3DHighlight Sys_BTNHilight -Sys_BTNHighlight Sys_3DLight Sys_3DShadow -Sys_BTNShadow Sys_ActiveBorder Sys_ActiveCaption -Sys_AppWorkspace Sys_Background Sys_Desktop -Sys_BTNText Sys_CaptionText Sys_GrayText -Sys_Highlight Sys_HighlightText Sys_InactiveBorder -Sys_InactiveCaption Sys_InactiveCaptionText Sys_InfoBK -Sys_InfoText Sys_Menu Sys_MenuText -Sys_ScrollBar Sys_Window Sys_WindowFrame -Sys_WindowText - -Probably the most useful values are - Sys_Window Normal window background - Sys_WindowText Normal window text - Sys_Highlight Highlighted background - Sys_HighlightText Highlighted text - -These extra colors are also available: -Gray, Grey, LightYellow, SeaGreen, Orange, Purple, SlateBlue, Violet, - - *rgb.txt* -Additionally, colors defined by a "rgb.txt" file can be used. This file is -well known from X11. A few lines from it: > - - 255 218 185 peach puff - 205 133 63 peru - 255 181 197 pink - -This shows the layout of the file: First the R, G and B value as a decimal -number, followed by the name of the color. The four fields are separated by -spaces. - -You can get an rgb.txt file from any X11 distribution. It is located in a -directory like "/usr/X11R6/lib/X11/". For Vim it must be located in the -$VIMRUNTIME directory. Thus the file can be found with "$VIMRUNTIME/rgb.txt". - -============================================================================== - *gui-w32-dialogs* *dialog* -6. Windows dialogs & browsers - -The Win32 GUI can use familiar Windows components for some operations, as well -as the traditional interface shared with the console version. - - -6.1 Dialogs - -The dialogs displayed by the "confirm" family (i.e. the 'confirm' option, -|:confirm| command and |confirm()| function) are GUI-based rather than the -console-based ones used by other versions. The 'c' flag in 'guioptions' -changes this. - - -6.2 File Browsers - -When prepending ":browse" before file editing commands, a file requester is -used to allow you to select an existing file. See |:browse|. - -============================================================================== -7. Command line arguments *gui-w32-cmdargs* - -Analysis of a command line into parameters is not standardised in MS Windows. -Gvim has to provide logic to analyse a command line. This logic is likely to -be different from the default logic provided by a compilation system used to -build vim. The differences relate to unusual double quote (") usage. -The arguments "C:\My Music\freude.txt" and "+/Sch\"iller" are handled in the -same way. The argument "+/Sch""iller" may be handled different by gvim and -vim, depending what it was compiled with. - -The rules are: - a) A parameter is a sequence of graphic characters. - b) Parameters are separated by white space. - c) A parameter can be enclosed in double quotes to include white space. - d) A sequence of zero or more backslashes (\) and a double quote (") - is special. The effective number of backslashes is halved, rounded - down. An even number of backslashes reverses the acceptability of - spaces and tabs, an odd number of backslashes produces a literal - double quote. - -So: - " is a special double quote - \" is a literal double quote - \\" is a literal backslash and a special double quote - \\\" is a literal backslash and a literal double quote - \\\\" is 2 literal backslashes and a special double quote - \\\\\" is 2 literal backslashes and a literal double quote - etc. - -Example: > - gvim "C:\My Music\freude" +"set ignorecase" +/"\"foo\\" +\"bar\\\" - -opens "C:\My Music\freude" and executes the line mode commands: > - set ignorecase; /"foo\ and /bar\" - -============================================================================== -8. Various *gui-w32-various* - - *gui-w32-printing* -The "File/Print" menu prints the text with syntax highlighting, see -|:hardcopy|. If you just want to print the raw text and have a default -printer installed this should also work: > - :w >>prn - -Vim supports a number of standard MS Windows features. Some of these are -detailed elsewhere: see |'mouse'|, |win32-hidden-menus|. - - *drag-n-drop-win32* -You can drag and drop one or more files into the Vim window, where they will -be opened as normal. See |drag-n-drop|. - - *:simalt* *:sim* -:sim[alt] {key} simulate pressing {key} while holding Alt pressed. - {only for Win32 versions} - -Normally, Vim takes control of all Alt-<Key> combinations, to increase the -number of possible mappings. This clashes with the standard use of Alt as the -key for accessing menus. -The quick way of getting standard behavior is to set the 'winaltkeys' option -to "yes". This however prevents you from mapping Alt keys at all. -Another way is to set 'winaltkeys' to "menu". Menu shortcut keys are then -handled by windows, other ALT keys can be mapped. This doesn't allow a -dependency on the current state though. -To get round this, the :simalt command allows Vim (when 'winaltkeys' is not -"yes") to fake a Windows-style Alt keypress. You can use this to map Alt key -combinations (or anything else for that matter) to produce standard Windows -actions. Here are some examples: > - - :map <M-f> :simalt f<CR> -This makes Alt-F pop down the 'File' menu (with the stock Menu.vim) by -simulating the keystrokes Alt, F. > - :map <M-Space> :simalt ~<CR> -This maps Alt-Space to pop down the system menu for the Vim window. Note that -~ is used by simalt to represent the <Space> character. > - :map <C-n> :simalt ~n<CR> -Maps Control-N to produce the keys Alt-Space followed by N. This minimizes the -Vim window via the system menu. - -Note that the key changes depending on the language you are using. - - *intellimouse-wheel-problems* -When using the Intellimouse mouse wheel causes Vim to stop accepting input, go -to: - ControlPanel - Mouse - Wheel - UniversalScrolling - Exceptions - -And add gvim to the list of applications. This problem only appears to happen -with the Intellimouse driver 2.2 and when "Universal Scrolling" is turned on. - - -XPM support *w32-xpm-support* - -Gvim can be build on MS-Windows with support for XPM files. |+xpm_w32| -See the Make_mvc.mak file for instructions, search for XPM. - -To try out if XPM support works do this: > - :help - :exe 'sign define vimxpm icon=' . $VIMRUNTIME . '\\vim16x16.xpm' - :exe 'sign place 1 line=1 name=vimxpm file=' . expand('%:p') -< - - vim:tw=78:sw=4:ts=8:ft=help:norl: diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt index 19bcb35da8..a81d32831b 100644 --- a/runtime/doc/help.txt +++ b/runtime/doc/help.txt @@ -1,4 +1,4 @@ -*help.txt* For Vim version 7.4. Last change: 2015 Apr 15 +*help.txt* For Vim version 7.4. Last change: 2016 Mar 31 VIM - main help file k @@ -9,14 +9,14 @@ Close this window: Use ":q<Enter>". Jump to a subject: Position the cursor on a tag (e.g. |bars|) and hit CTRL-]. With the mouse: Double-click the left mouse button on a tag, e.g. |bars|. - Jump back: Type CTRL-T or CTRL-O (repeat to go further back). + Jump back: Type CTRL-T or CTRL-O. Repeat to go further back. Get specific help: It is possible to go directly to whatever you want help on, by giving an argument to the |:help| command. - It is possible to further specify the context: - *help-context* + Prepend something to specify the context: *help-context* + WHAT PREPEND EXAMPLE ~ - Normal mode command (nothing) :help x + Normal mode command :help x Visual mode command v_ :help v_u Insert mode command i_ :help i_<Esc> Command-line command : :help :quit @@ -24,6 +24,8 @@ Get specific help: It is possible to go directly to whatever you want help Vim command argument - :help -r Option ' :help 'textwidth' Regular expression / :help /[ + See |help-summary| for more contexts and an explanation. + Search for help: Type ":help word", then hit CTRL-D to see matching help entries for "word". Or use ":helpgrep word". |:helpgrep| @@ -152,6 +154,7 @@ 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 diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt index f3533b8815..ad1611133a 100644 --- a/runtime/doc/helphelp.txt +++ b/runtime/doc/helphelp.txt @@ -1,4 +1,4 @@ -*helphelp.txt* For Vim version 7.4. Last change: 2014 Sep 19 +*helphelp.txt* For Vim version 7.4. Last change: 2016 Apr 01 VIM REFERENCE MANUAL by Bram Moolenaar @@ -185,9 +185,12 @@ command: > < *:helpt* *:helptags* - *E154* *E150* *E151* *E152* *E153* *E670* + *E154* *E150* *E151* *E152* *E153* *E670* *E856* :helpt[ags] [++t] {dir} Generate the help tags file(s) for directory {dir}. + When {dir} is ALL then all "doc" directories in + 'runtimepath' will be used. + All "*.txt" and "*.??x" files in the directory and sub-directories are scanned for a help tag definition in between stars. The "*.??x" files are for @@ -196,9 +199,11 @@ command: > sorted. When there are duplicates an error message is given. An existing tags file is silently overwritten. + The optional "++t" argument forces adding the "help-tags" tag. This is also done when the {dir} is equal to $VIMRUNTIME/doc. + To rebuild the help tags in the runtime directory (requires write permission there): > :helptags $VIMRUNTIME/doc @@ -249,7 +254,9 @@ The second one finds the English user manual, even when 'helplang' is set to When using command-line completion for the ":help" command, the "@en" extension is only shown when a tag exists for multiple languages. When the -tag only exists for English "@en" is omitted. +tag only exists for English "@en" is omitted. When the first candidate has an +"@ab" extension and it matches the first language in 'helplang' "@ab" is also +omitted. When using |CTRL-]| or ":help!" in a non-English help file Vim will try to find the tag in the same language. If not found then 'helplang' will be used @@ -306,6 +313,10 @@ aligned on a line. When referring to an existing help tag and to create a hot-link, place the name between two bars (|) eg. |help-writing|. +When referring to a Vim command and to create a hot-link, place the +name between two backticks, eg. inside `:filetype`. You will see this is +highlighted as a command, like a code block (see below). + When referring to a Vim option in the help file, place the option name between two single quotes, eg. 'statusline' diff --git a/runtime/doc/if_cscop.txt b/runtime/doc/if_cscop.txt index 70f8d1c6f3..7482f5eebb 100644 --- a/runtime/doc/if_cscop.txt +++ b/runtime/doc/if_cscop.txt @@ -96,8 +96,8 @@ command does the same and also splits the window (short: "scs"). The available subcommands are: - *E563* *E564* *E566* *E568* *E569* *E622* *E623* - *E625* *E626* *E609* + *E563* *E564* *E566* *E568* *E622* *E623* *E625* + *E626* *E609* add : Add a new cscope database/connection. USAGE :cs add {file|dir} [pre-path] [flags] @@ -128,6 +128,7 @@ The available subcommands are: 6 or e: Find this egrep pattern 7 or f: Find this file 8 or i: Find files #including this file + 9 or a: Find places where this symbol is assigned a value For all types, except 4 and 6, leading white space for {name} is removed. For 4 and 6 there is exactly one space between {querytype} @@ -254,13 +255,13 @@ started will have no effect! {not available when compiled without the |+quickfix| feature} 'cscopequickfix' specifies whether to use quickfix window to show cscope results. This is a list of comma-separated values. Each item consists of -|cscope-find| command (s, g, d, c, t, e, f or i) and flag (+, - or 0). +|cscope-find| command (s, g, d, c, t, e, f, i or a) and flag (+, - or 0). '+' indicates that results must be appended to quickfix window, '-' implies previous results clearance, '0' or command absence - don't use quickfix. Search is performed from start until first command occurrence. The default value is "" (don't use quickfix anyway). The following value seems to be useful: > - :set cscopequickfix=s-,c-,d-,i-,t-,e- + :set cscopequickfix=s-,c-,d-,i-,t-,e-,a- < *cscopetag* *cst* If 'cscopetag' is set, the commands ":tag" and CTRL-] as well as "vim -t" @@ -418,6 +419,7 @@ Cscope Home Page (http://cscope.sourceforge.net/): > nmap <C-_>f :cs find f <C-R>=expand("<cfile>")<CR><CR> nmap <C-_>i :cs find i ^<C-R>=expand("<cfile>")<CR>$<CR> nmap <C-_>d :cs find d <C-R>=expand("<cword>")<CR><CR> + nmap <C-_>a :cs find a <C-R>=expand("<cword>")<CR><CR> " Using 'CTRL-spacebar' then a search type makes the vim window " split horizontally, with search result displayed in @@ -431,6 +433,7 @@ Cscope Home Page (http://cscope.sourceforge.net/): > nmap <C-Space>f :scs find f <C-R>=expand("<cfile>")<CR><CR> nmap <C-Space>i :scs find i ^<C-R>=expand("<cfile>")<CR>$<CR> nmap <C-Space>d :scs find d <C-R>=expand("<cword>")<CR><CR> + nmap <C-Space>a :scs find a <C-R>=expand("<cword>")<CR><CR> " Hitting CTRL-space *twice* before the search type does a vertical " split instead of a horizontal one @@ -449,6 +452,8 @@ Cscope Home Page (http://cscope.sourceforge.net/): > \:vert scs find i ^<C-R>=expand("<cfile>")<CR>$<CR> nmap <C-Space><C-Space>d \:vert scs find d <C-R>=expand("<cword>")<CR><CR> + nmap <C-Space><C-Space>a + \:vert scs find a <C-R>=expand("<cword>")<CR><CR> ============================================================================== 7. Cscope availability and information *cscope-info* diff --git a/runtime/doc/if_pyth.txt b/runtime/doc/if_pyth.txt index f6bd365299..b6fe234de4 100644 --- a/runtime/doc/if_pyth.txt +++ b/runtime/doc/if_pyth.txt @@ -16,7 +16,7 @@ The Python Interface to Vim *python* *Python* 8. pyeval(), py3eval() Vim functions |python-pyeval| 9. Python 3 |python3| -See |nvim-python| for more information. {Nvim} +See |provider-python| for more information. {Nvim} ============================================================================== 1. Commands *python-commands* @@ -699,7 +699,7 @@ if the `:py3` command is working: > :py3 print("Hello") < *:py3file* The `:py3file` command works similar to `:pyfile`. - *:py3do* *E863* + *:py3do* The `:py3do` command works similar to `:pydo`. *E880* diff --git a/runtime/doc/if_ruby.txt b/runtime/doc/if_ruby.txt new file mode 100644 index 0000000000..fdd63501ea --- /dev/null +++ b/runtime/doc/if_ruby.txt @@ -0,0 +1,185 @@ +*if_ruby.txt* + + + VIM REFERENCE MANUAL by Shugo Maeda + +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. + +============================================================================== +1. Commands *ruby-commands* + + *:ruby* *:rub* +:rub[y] {cmd} Execute Ruby command {cmd}. A command to try it out: > + :ruby print "Hello" + +:rub[y] << {endpattern} +{script} +{endpattern} + Execute Ruby script {script}. + {endpattern} must NOT be preceded by any white space. + If {endpattern} is omitted, it defaults to a dot '.' + like for the |:append| and |:insert| commands. This + form of the |:ruby| command is mainly useful for + including ruby code in vim scripts. + Note: This command doesn't work when the Ruby feature + wasn't compiled in. To avoid errors, see + |script-here|. + +Example Vim script: > + + function! RedGem() + ruby << EOF + class Garnet + def initialize(s) + @buffer = VIM::Buffer.current + vimputs(s) + end + def vimputs(s) + @buffer.append(@buffer.count,s) + end + end + gem = Garnet.new("pretty") + EOF + endfunction +< + + *:rubydo* *:rubyd* *E265* +:[range]rubyd[o] {cmd} Evaluate Ruby command {cmd} for each line in the + [range], with $_ being set to the text of each line in + turn, without a trailing <EOL>. Setting $_ will change + the text, but note that it is not possible to add or + delete lines using this command. + The default for [range] is the whole file: "1,$". + + *:rubyfile* *:rubyf* +:rubyf[ile] {file} Execute the Ruby script in {file}. This is the same as + ":ruby load 'file'", but allows file name completion. + +Executing Ruby commands is not possible in the |sandbox|. + +============================================================================== +2. The VIM module *ruby-vim* + +Ruby code gets all of its access to vim via the "VIM" module. + +Overview > + print "Hello" # displays a message + VIM.command(cmd) # execute an Ex command + num = VIM::Window.count # gets the number of windows + w = VIM::Window[n] # gets window "n" + cw = VIM::Window.current # gets the current window + num = VIM::Buffer.count # gets the number of buffers + b = VIM::Buffer[n] # gets buffer "n" + cb = VIM::Buffer.current # gets the current buffer + w.height = lines # sets the window height + w.cursor = [row, col] # sets the window cursor position + pos = w.cursor # gets an array [row, col] + name = b.name # gets the buffer file name + line = b[n] # gets a line from the buffer + num = b.count # gets the number of lines + b[n] = str # sets a line in the buffer + b.delete(n) # deletes a line + b.append(n, str) # appends a line after n + line = VIM::Buffer.current.line # gets the current line + num = VIM::Buffer.current.line_number # gets the current line number + VIM::Buffer.current.line = "test" # sets the current line number +< + +Module Functions: + + *ruby-message* +VIM::message({msg}) + Displays the message {msg}. + + *ruby-set_option* +VIM::set_option({arg}) + Sets a vim option. {arg} can be any argument that the ":set" command + accepts. Note that this means that no spaces are allowed in the + argument! See |:set|. + + *ruby-command* +VIM::command({cmd}) + Executes Ex command {cmd}. + + *ruby-evaluate* +VIM::evaluate({expr}) + Evaluates {expr} using the vim internal expression evaluator (see + |expression|). Returns the expression result as a string. + A |List| is turned into a string by joining the items and inserting + line breaks. + +============================================================================== +3. VIM::Buffer objects *ruby-buffer* + +VIM::Buffer objects represent vim buffers. + +Class Methods: + +current Returns the current buffer object. +count Returns the number of buffers. +self[{n}] Returns the buffer object for the number {n}. The first number + is 0. + +Methods: + +name Returns the name of the buffer. +number Returns the number of the buffer. +count Returns the number of lines. +length Returns the number of lines. +self[{n}] Returns a line from the buffer. {n} is the line number. +self[{n}] = {str} + Sets a line in the buffer. {n} is the line number. +delete({n}) Deletes a line from the buffer. {n} is the line number. +append({n}, {str}) + Appends a line after the line {n}. +line Returns the current line of the buffer if the buffer is + active. +line = {str} Sets the current line of the buffer if the buffer is active. +line_number Returns the number of the current line if the buffer is + active. + +============================================================================== +4. VIM::Window objects *ruby-window* + +VIM::Window objects represent vim windows. + +Class Methods: + +current Returns the current window object. +count Returns the number of windows. +self[{n}] Returns the window object for the number {n}. The first number + is 0. + +Methods: + +buffer Returns the buffer displayed in the window. +height Returns the height of the window. +height = {n} Sets the window height to {n}. +width Returns the width of the window. +width = {n} Sets the window width to {n}. +cursor Returns a [row, col] array for the cursor position. +cursor = [{row}, {col}] + Sets the cursor position to {row} and {col}. + +============================================================================== +5. Global variables *ruby-globals* + +There are two global variables. + +$curwin The current window object. +$curbuf The current buffer object. + +============================================================================== + vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/indent.txt b/runtime/doc/indent.txt index 6e96d9b816..496ccbc703 100644 --- a/runtime/doc/indent.txt +++ b/runtime/doc/indent.txt @@ -810,7 +810,7 @@ PHP indenting can be altered in several ways by modifying the values of some global variables: *php-comment* *PHP_autoformatcomment* -To not enable auto-formating of comments by default (if you want to use your +To not enable auto-formatting of comments by default (if you want to use your own 'formatoptions'): > :let g:PHP_autoformatcomment = 0 diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt index e6c1ccc0cf..7388652f16 100644 --- a/runtime/doc/index.txt +++ b/runtime/doc/index.txt @@ -1,4 +1,4 @@ -*index.txt* For Vim version 7.4. Last change: 2016 Jan 03 +*index.txt* For Vim version 7.4. Last change: 2016 Jun 12 VIM REFERENCE MANUAL by Bram Moolenaar @@ -48,6 +48,7 @@ tag char action in Insert mode ~ |i_CTRL-G_k| CTRL-G k line up, to column where inserting started |i_CTRL-G_k| CTRL-G <Up> line up, to column where inserting started |i_CTRL-G_u| CTRL-G u start new undoable edit +|i_CTRL-G_U| CTRL-G U don't break undo with next cursor movement |i_<BS>| <BS> delete character before the cursor |i_digraph| {char1}<BS>{char2} enter digraph (only when 'digraph' option set) @@ -857,6 +858,7 @@ tag command note action in Visual mode ~ ------------------------------------------------------------------------------ |v_CTRL-\_CTRL-N| CTRL-\ CTRL-N stop Visual mode |v_CTRL-\_CTRL-G| CTRL-\ CTRL-G go to mode specified with 'insertmode' +|v_CTRL-A| CTRL-A 2 add N to number in highlighted text |v_CTRL-C| CTRL-C stop Visual mode |v_CTRL-G| CTRL-G toggle between Visual mode and Select mode |v_<BS>| <BS> 2 Select mode: delete highlighted area @@ -865,6 +867,7 @@ tag command note action in Visual mode ~ command |v_CTRL-V| CTRL-V make Visual mode blockwise or stop Visual mode +|v_CTRL-X| CTRL-X 2 subtract N from number in highlighted text |v_<Esc>| <Esc> stop Visual mode |v_CTRL-]| CTRL-] jump to highlighted tag |v_!| !{filter} 2 filter the highlighted lines through the @@ -921,6 +924,8 @@ tag command note action in Visual mode ~ |v_a}| a} same as aB |v_c| c 2 delete highlighted area and start insert |v_d| d 2 delete highlighted area +|v_g_CTRL-A| g CTRL-A 2 add N to number in highlighted text +|v_g_CTRL-X| g CTRL-X 2 subtract N from number in highlighted text |v_gJ| gJ 2 join the highlighted lines without inserting spaces |v_gq| gq 2 format the highlighted lines @@ -1129,6 +1134,7 @@ tag command action ~ |:caddfile| :caddf[ile] add error message to current quickfix list |:call| :cal[l] call a function |:catch| :cat[ch] part of a :try command +|:cbottom| :cbo[ttom] scroll to the bottom of the quickfix window |:cbuffer| :cb[uffer] parse error messages and jump to first error |:cc| :cc go to specific error |:cclose| :ccl[ose] close quickfix window @@ -1146,8 +1152,9 @@ tag command action ~ |:chdir| :chd[ir] change directory |:checkpath| :che[ckpath] list included files |:checktime| :checkt[ime] check timestamp of loaded buffers -|:clist| :cl[ist] list all errors |:clast| :cla[st] go to the specified error, default last one +|:clearjumps| :cle[arjumps] clear the jump list +|:clist| :cl[ist] list all errors |:close| :clo[se] close current window |:cmap| :cm[ap] like ":map" but for Command-line mode |:cmapclear| :cmapc[lear] clear all mappings for Command-line mode @@ -1171,7 +1178,7 @@ tag command action ~ |:cpfile| :cpf[ile] go to last error in previous file |:cquit| :cq[uit] quit Vim with an error code |:crewind| :cr[ewind] go to the specified error, default first one -|:cscope| :cs[cope] execute cscope command +|:cscope| :cs[cope] execute cscope command |:cstag| :cst[ag] use cscope to jump to a tag |:cunmap| :cu[nmap] like ":unmap" but for Command-line mode |:cunabbrev| :cuna[bbrev] like ":unabbrev" but for Command-line mode @@ -1286,11 +1293,12 @@ tag command action ~ |:last| :la[st] go to the last file in the argument list |:language| :lan[guage] set the language (locale) |:later| :lat[er] go to newer change, redo +|:lbottom| :lbo[ttom] scroll to the bottom of the location window |:lbuffer| :lb[uffer] parse locations and jump to first location |:lcd| :lc[d] change directory locally |:lchdir| :lch[dir] change directory locally |:lclose| :lcl[ose] close location window -|:lcscope| :lcs[cope] like ":cscope" but uses location list +|:lcscope| :lcs[cope] like ":cscope" but uses location list |:ldo| :ld[o] execute command in valid location list entries |:lfdo| :lfd[o] execute command in each file in location list |:left| :le[ft] left align lines @@ -1341,7 +1349,7 @@ tag command action ~ |:marks| :marks list all marks |:match| :mat[ch] define a match to highlight |:menu| :me[nu] enter a new menu item -|:menutranslate| :menut[ranslate] add a menu translation item +|:menutranslate| :menut[ranslate] add a menu translation item |:messages| :mes[sages] view previously displayed messages |:mkexrc| :mk[exrc] write current mappings and settings to a file |:mksession| :mks[ession] write session info to a file @@ -1378,6 +1386,8 @@ tag command action ~ |:ounmap| :ou[nmap] like ":unmap" but for Operator-pending mode |:ounmenu| :ounme[nu] remove menu for Operator-pending mode |:ownsyntax| :ow[nsyntax] set new local syntax highlight for this window +|:packadd| :pa[ckadd] add a plugin from 'packpath' +|:packloadall| :packl[oadall] load all packages under 'packpath' |:pclose| :pc[lose] close preview window |:pedit| :ped[it] edit file in the preview window |:print| :p[rint] print lines @@ -1494,7 +1504,7 @@ tag command action ~ |:stop| :st[op] suspend the editor or escape to a shell |:stag| :sta[g] split window and jump to a tag |:startinsert| :star[tinsert] start Insert mode -|:startgreplace| :startg[replace] start Virtual Replace mode +|:startgreplace| :startg[replace] start Virtual Replace mode |:startreplace| :startr[eplace] start Replace mode |:stopinsert| :stopi[nsert] stop Insert mode |:stjump| :stj[ump] do ":tjump" and split window @@ -1515,14 +1525,14 @@ tag command action ~ |:tabdo| :tabdo execute command in each tab page |:tabedit| :tabe[dit] edit a file in a new tab page |:tabfind| :tabf[ind] find file in 'path', edit it in a new tab page -|:tabfirst| :tabfir[st] got to first tab page -|:tablast| :tabl[ast] got to last tab page +|:tabfirst| :tabfir[st] go to first tab page +|:tablast| :tabl[ast] go to last tab page |:tabmove| :tabm[ove] move tab page to other position |:tabnew| :tabnew edit a file in a new tab page |:tabnext| :tabn[ext] go to next tab page |:tabonly| :tabo[nly] close all tab pages except the current one |:tabprevious| :tabp[revious] go to previous tab page -|:tabrewind| :tabr[ewind] got to first tab page +|:tabrewind| :tabr[ewind] go to first tab page |:tabs| :tabs list the tab pages and what they contain |:tab| :tab create new tab when opening new window |:tag| :ta[g] jump to tag diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt index f931dfa341..a82e17c857 100644 --- a/runtime/doc/insert.txt +++ b/runtime/doc/insert.txt @@ -1,4 +1,4 @@ -*insert.txt* For Vim version 7.4. Last change: 2015 Sep 15 +*insert.txt* For Vim version 7.4. Last change: 2016 Jan 31 VIM REFERENCE MANUAL by Bram Moolenaar @@ -1436,7 +1436,7 @@ original HTML files completion of tags (and only tags) isn't context aware. RUBY *ft-ruby-omni* {Nvim} -NOTE: Completion for ruby code is not currently provided by Nvim. +NOTE: |compl-omni| for Ruby code requires |provider-ruby| to be installed. Ruby completion will parse your buffer on demand in order to provide a list of completions. These completions will be drawn from modules loaded by 'require' diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt index cbe017e051..786097dd74 100644 --- a/runtime/doc/intro.txt +++ b/runtime/doc/intro.txt @@ -450,7 +450,7 @@ notation meaning equivalent decimal value(s) ~ <k0> - <k9> keypad 0 to 9 *keypad-0* *keypad-9* <S-...> shift-key *shift* *<S-* <C-...> control-key *control* *ctrl* *<C-* -<M-...> alt-key or meta-key *meta* *alt* *<M-* +<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 diff --git a/runtime/doc/job_control.txt b/runtime/doc/job_control.txt index 587eba4162..1aa7ce06d6 100644 --- a/runtime/doc/job_control.txt +++ b/runtime/doc/job_control.txt @@ -40,7 +40,7 @@ for details. Job control is achieved by calling a combination of the |jobstart()|, |jobsend()| and |jobstop()| functions. Here's an example: > - function s:JobHandler(job_id, data, event) + function! s:JobHandler(job_id, data, event) dict if a:event == 'stdout' let str = self.shell.' stdout: '.join(a:data) elseif a:event == 'stderr' @@ -84,28 +84,41 @@ Here's what is happening: program. 2: The event type, which is "stdout", "stderr" or "exit". + Note: Buffered stdout/stderr data which has not been flushed by the sender + will not trigger the "stdout" callback (but if the process ends, the + "exit" callback will be triggered). + For example, "ruby -e" buffers output, so small strings will be + buffered unless "auto-flushing" ($stdout.sync=true) is enabled. > + function! Receive(job_id, data, event) + echom printf('%s: %s',a:event,string(a:data)) + endfunction + call jobstart(['ruby', '-e', + \ '$stdout.sync = true; 5.times do sleep 1 and puts "Hello Ruby!" end'], + \ {'on_stdout': 'Receive'}) +< https://github.com/neovim/neovim/issues/1592 + The options dictionary is passed as the "self" variable to the callback function. Here's a more object-oriented version of the above: > let Shell = {} - function Shell.on_stdout(job_id, data) + function Shell.on_stdout(job_id, data) dict call append(line('$'), self.get_name().' stdout: '.join(a:data)) endfunction - function Shell.on_stderr(job_id, data) + function Shell.on_stderr(job_id, data) dict call append(line('$'), self.get_name().' stderr: '.join(a:data)) endfunction - function Shell.on_exit(job_id, data) + function Shell.on_exit(job_id, data) dict call append(line('$'), self.get_name().' exited') endfunction - function Shell.get_name() + function Shell.get_name() dict return 'shell '.self.name endfunction - function Shell.new(name, ...) + function Shell.new(name, ...) dict let instance = extend(copy(g:Shell), {'name': a:name}) let argv = ['bash'] if a:0 > 0 diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt index 464c700a4d..53b152dc06 100644 --- a/runtime/doc/map.txt +++ b/runtime/doc/map.txt @@ -1,4 +1,4 @@ -*map.txt* For Vim version 7.4. Last change: 2014 Dec 08 +*map.txt* For Vim version 7.4. Last change: 2016 Jul 06 VIM REFERENCE MANUAL by Bram Moolenaar @@ -55,6 +55,7 @@ modes. :im[ap] {lhs} {rhs} |mapmode-i| *:im* *:imap* :lm[ap] {lhs} {rhs} |mapmode-l| *:lm* *:lmap* :cm[ap] {lhs} {rhs} |mapmode-c| *:cm* *:cmap* +:tm[ap] {lhs} {rhs} |mapmode-t| *:tm* *:tmap* Map the key sequence {lhs} to {rhs} for the modes where the map command applies. The result, including {rhs}, is then further scanned for mappings. This @@ -71,6 +72,7 @@ modes. :ino[remap] {lhs} {rhs} |mapmode-i| *:ino* *:inoremap* :ln[oremap] {lhs} {rhs} |mapmode-l| *:ln* *:lnoremap* :cno[remap] {lhs} {rhs} |mapmode-c| *:cno* *:cnoremap* +:tno[remap] {lhs} {rhs} |mapmode-t| *:tno* *:tnoremap* Map the key sequence {lhs} to {rhs} for the modes where the map command applies. Disallow mapping of {rhs}, to avoid nested and recursive mappings. Often @@ -87,6 +89,7 @@ modes. :iu[nmap] {lhs} |mapmode-i| *:iu* *:iunmap* :lu[nmap] {lhs} |mapmode-l| *:lu* *:lunmap* :cu[nmap] {lhs} |mapmode-c| *:cu* *:cunmap* +:tu[nmap] {lhs} |mapmode-t| *:tu* *:tunmap* Remove the mapping of {lhs} for the modes where the map command applies. The mapping may remain defined for other modes where it applies. @@ -105,6 +108,7 @@ modes. :imapc[lear] |mapmode-i| *:imapc* *:imapclear* :lmapc[lear] |mapmode-l| *:lmapc* *:lmapclear* :cmapc[lear] |mapmode-c| *:cmapc* *:cmapclear* +:tmapc[lear] |mapmode-t| *:tmapc* *:tmapclear* Remove ALL mappings for the modes where the map command applies. Use the <buffer> argument to remove buffer-local @@ -121,6 +125,7 @@ modes. :im[ap] |mapmode-i| :lm[ap] |mapmode-l| :cm[ap] |mapmode-c| +:tm[ap] |mapmode-t| List all key mappings for the modes where the map command applies. Note that ":map" and ":map!" are used most often, because they include the other modes. @@ -135,6 +140,7 @@ modes. :im[ap] {lhs} |mapmode-i| *:imap_l* :lm[ap] {lhs} |mapmode-l| *:lmap_l* :cm[ap] {lhs} |mapmode-c| *:cmap_l* +:tm[ap] {lhs} |mapmode-t| *:tmap_l* List the key mappings for the key sequences starting with {lhs} in the modes where the map command applies. @@ -288,9 +294,9 @@ as a special key. 1.3 MAPPING AND MODES *:map-modes* - *mapmode-nvo* *mapmode-n* *mapmode-v* *mapmode-o* + *mapmode-nvo* *mapmode-n* *mapmode-v* *mapmode-o* *mapmode-t* -There are six sets of mappings +There are seven sets of mappings - For Normal mode: When typing commands. - For Visual mode: When typing commands while the Visual area is highlighted. - For Select mode: like Visual mode but typing text replaces the selection. @@ -298,6 +304,7 @@ There are six sets of mappings etc.). See below: |omap-info|. - For Insert mode. These are also used in Replace mode. - For Command-line mode: When entering a ":" or "/" command. +- For Terminal mode: When typing in a |:terminal| buffer. Special case: While typing a count for a command in Normal mode, mapping zero is disabled. This makes it possible to map zero without making it impossible @@ -316,6 +323,7 @@ Overview of which map command works in which mode. More details below. :imap :inoremap :iunmap Insert :lmap :lnoremap :lunmap Insert, Command-line, Lang-Arg :cmap :cnoremap :cunmap Command-line +:tmap :tnoremap :tunmap Terminal COMMANDS MODES ~ @@ -481,7 +489,7 @@ internal code is written to the script file. 1.6 SPECIAL CHARACTERS *:map-special-chars* - *map_backslash* + *map_backslash* *map-backslash* Note that only CTRL-V is mentioned here as a special character for mappings and abbreviations. When 'cpoptions' does not contain 'B', a backslash can also be used like CTRL-V. The <> notation can be fully used then |<>|. But @@ -492,21 +500,21 @@ To map a backslash, or use a backslash literally in the {rhs}, the special sequence "<Bslash>" can be used. This avoids the need to double backslashes when using nested mappings. - *map_CTRL-C* + *map_CTRL-C* *map-CTRL-C* Using CTRL-C in the {lhs} is possible, but it will only work when Vim is waiting for a key, not when Vim is busy with something. When Vim is busy CTRL-C interrupts/breaks the command. When using the GUI version on MS-Windows CTRL-C can be mapped to allow a Copy command to the clipboard. Use CTRL-Break to interrupt Vim. - *map_space_in_lhs* + *map_space_in_lhs* *map-space_in_lhs* To include a space in {lhs} precede it with a CTRL-V (type two CTRL-Vs for each space). - *map_space_in_rhs* + *map_space_in_rhs* *map-space_in_rhs* If you want a {rhs} that starts with a space, use "<Space>". To be fully Vi compatible (but unreadable) don't use the |<>| notation, precede {rhs} with a single CTRL-V (you have to type CTRL-V two times). - *map_empty_rhs* + *map_empty_rhs* *map-empty-rhs* You can create an empty {rhs} by typing nothing after a single CTRL-V (you have to type CTRL-V two times). Unfortunately, you cannot do this in a vimrc file. @@ -581,7 +589,7 @@ Upper and lowercase differences are ignored. It is not possible to put a comment after these commands, because the '"' character is considered to be part of the {lhs} or {rhs}. - *map_bar* + *map_bar* *map-bar* Since the '|' character is used to separate a map command from the next command, you will have to do something special to include a '|' in {rhs}. There are three methods: @@ -599,7 +607,7 @@ When 'b' is present in 'cpoptions', "\|" will be recognized as a mapping ending in a '\' and then another command. This is Vi compatible, but illogical when compared to other commands. - *map_return* + *map_return* *map-return* When you have a mapping that contains an Ex command, you need to put a line terminator after it to have it executed. The use of <CR> is recommended for this (see |<>|). Example: > @@ -1260,6 +1268,7 @@ completion can be enabled: -complete=mapping mapping name -complete=menu menus -complete=option options + -complete=packadd optional package |pack-add| names -complete=shellcmd Shell command -complete=sign |:sign| suboptions -complete=syntax syntax file names |'syntax'| @@ -1344,7 +1353,7 @@ Possible attributes are: Note that -range=N and -count=N are mutually exclusive - only one should be specified. - *E889* *:command-addr* + *:command-addr* It is possible that the special characters in the range like `.`, `$` or `%` which by default correspond to the current line, last line and the whole buffer, relate to arguments, (loaded) buffers, windows or tab pages. @@ -1398,6 +1407,27 @@ The valid escape sequences are <bang> (See the '-bang' attribute) Expands to a ! if the command was executed with a ! modifier, otherwise expands to nothing. + *<mods>* + <mods> The command modifiers, if specified. Otherwise, expands to + nothing. Supported modifiers are |:aboveleft|, |:belowright|, + |:botright|, |:browse|, |:confirm|, |:hide|, |:keepalt|, + |:keepjumps|, |:keepmarks|, |:keeppatterns|, |:lockmarks|, + |:noswapfile|, |:silent|, |:tab|, |:topleft|, |:verbose|, and + |:vertical|. + Examples: > + command! -nargs=+ -complete=file MyEdit + \ for f in expand(<q-args>, 0, 1) | + \ exe '<mods> split ' . f | + \ endfor + + function! SpecialEdit(files, mods) + for f in expand(a:files, 0, 1) + exe a:mods . ' split ' . f + endfor + endfunction + command! -nargs=+ -complete=file Sedit + \ call SpecialEdit(<q-args>, <q-mods>) +< *<reg>* *<register>* <reg> (See the '-register' attribute) The optional register, if specified. Otherwise, expands to nothing. <register> diff --git a/runtime/doc/mbyte.txt b/runtime/doc/mbyte.txt index c87ed317d4..355a1da423 100644 --- a/runtime/doc/mbyte.txt +++ b/runtime/doc/mbyte.txt @@ -1,4 +1,4 @@ -*mbyte.txt* For Vim version 7.4. Last change: 2013 May 18 +*mbyte.txt* For Vim version 7.4. Last change: 2016 Jul 21 VIM REFERENCE MANUAL by Bram Moolenaar et al. @@ -70,29 +70,24 @@ See |mbyte-locale| for details. ENCODING -If your locale works properly, Vim will try to set the 'encoding' option -accordingly. If this doesn't work you can overrule its value: > +Nvim always uses UTF-8 internally. Thus 'encoding' option is always set +to "utf-8" and cannot be changed. - :set encoding=utf-8 +All the text that is used inside Vim will be in UTF-8. Not only the text in +the buffers, but also in registers, variables, etc. -See |encoding-values| for a list of acceptable values. - -The result is that all the text that is used inside Vim will be in this -encoding. Not only the text in the buffers, but also in registers, variables, -etc. 'encoding' is read-only after startup because changing it would make the -existing text invalid. - -You can edit files in another encoding than what 'encoding' is set to. Vim +You can edit files in different encodings than UTF-8. Nvim will convert the file when you read it and convert it back when you write it. See 'fileencoding', 'fileencodings' and |++enc|. DISPLAY AND FONTS -If you are working in a terminal (emulator) you must make sure it accepts the -same encoding as which Vim is working with. +If you are working in a terminal (emulator) you must make sure it accepts +UTF-8, the encoding which Vim is working with. Otherwise only ASCII can +be displayed and edited correctly. -For the GUI you must select fonts that work with the current 'encoding'. This +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. @@ -216,10 +211,9 @@ You could make a small shell script for this. ============================================================================== 3. Encoding *mbyte-encoding* -Vim uses the 'encoding' option to specify how characters are identified and -encoded when they are used inside Vim. This applies to all the places where -text is used, including buffers (files loaded into memory), registers and -variables. +In Nvim UTF-8 is always used internally to encode characters. + This applies to all the places where text is used, including buffers (files + loaded into memory), registers and variables. *charset* *codeset* Charset is another name for encoding. There are subtle differences, but these @@ -240,7 +234,7 @@ matter what language is used. Thus you might see the right text even when the encoding was set wrong. *encoding-names* -Vim can use many different character encodings. There are three major groups: +Vim can edit files in different character encodings. There are three major groups: 1 8bit Single-byte encodings, 256 different characters. Mostly used in USA and Europe. Example: ISO-8859-1 (Latin1). All @@ -255,11 +249,10 @@ u Unicode Universal encoding, can replace all others. ISO 10646. Millions of different characters. Example: UTF-8. The relation between bytes and screen cells is complex. -Other encodings cannot be used by Vim internally. But files in other +Only UTF-8 is used by Vim internally. But files in other encodings can be edited by using conversion, see 'fileencoding'. -Note that all encodings must use ASCII for the characters up to 128. -Supported 'encoding' values are: *encoding-values* +Recognized 'fileencoding' values include: *encoding-values* 1 latin1 8-bit characters (ISO 8859-1, also used for cp1252) 1 iso-8859-n ISO_8859 variant (n = 2 to 15) 1 koi8-r Russian @@ -311,11 +304,11 @@ u ucs-4 32 bit UCS-4 encoded Unicode (ISO/IEC 10646-1) u ucs-4le like ucs-4, little endian The {name} can be any encoding name that your system supports. It is passed -to iconv() to convert between the encoding of the file and the current locale. +to iconv() to convert between UTF-8 and the encoding of the file. For MS-Windows "cp{number}" means using codepage {number}. Examples: > - :set encoding=8bit-cp1252 - :set encoding=2byte-cp932 + :set fileencoding=8bit-cp1252 + :set fileencoding=2byte-cp932 The MS-Windows codepage 1252 is very similar to latin1. For practical reasons the same encoding is used and it's called latin1. 'isprint' can be used to @@ -337,8 +330,7 @@ u ucs-2be same as ucs-2 (big endian) u ucs-4be same as ucs-4 (big endian) u utf-32 same as ucs-4 u utf-32le same as ucs-4le - default stands for the default value of 'encoding', depends on the - environment + default the encoding of the current locale. For the UCS codes the byte order matters. This is tricky, use UTF-8 whenever you can. The default is to use big-endian (most significant byte comes @@ -363,13 +355,12 @@ or when conversion is not possible: CONVERSION *charset-conversion* Vim will automatically convert from one to another encoding in several places: -- When reading a file and 'fileencoding' is different from 'encoding' -- When writing a file and 'fileencoding' is different from 'encoding' +- When reading a file and 'fileencoding' is different from "utf-8" +- When writing a file and 'fileencoding' is different from "utf-8" - When displaying messages and the encoding used for LC_MESSAGES differs from - 'encoding' (requires a gettext version that supports this). + "utf-8" (requires a gettext version that supports this). - When reading a Vim script where |:scriptencoding| is different from - 'encoding'. -- When reading or writing a |shada| file. + "utf-8". Most of these require the |+iconv| feature. Conversion for reading and writing files may also be specified with the 'charconvert' option. @@ -408,11 +399,11 @@ Useful utilities for converting the charset: *mbyte-conversion* -When reading and writing files in an encoding different from 'encoding', +When reading and writing files in an encoding different from "utf-8", conversion needs to be done. These conversions are supported: - All conversions between Latin-1 (ISO-8859-1), UTF-8, UCS-2 and UCS-4 are handled internally. -- For MS-Windows, when 'encoding' is a Unicode encoding, conversion from and +- For MS-Windows, conversion from and to any codepage should work. - Conversion specified with 'charconvert' - Conversion with the iconv library, if it is available. @@ -468,8 +459,6 @@ and you will have a working UTF-8 terminal emulator. Try both > 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. -For Vim you may need to set 'encoding' to "utf-8". - ============================================================================== 5. Fonts on X11 *mbyte-fonts-X11* @@ -860,15 +849,16 @@ text, you can use the 'keymap' option. This will translate one or more (English) characters to another (non-English) character. This only happens when typing text, not when typing Vim commands. This avoids having to switch between two keyboard settings. +{only available when compiled with the |+keymap| feature} The value of the 'keymap' option specifies a keymap file to use. The name of this file is one of these two: - keymap/{keymap}_{encoding}.vim + keymap/{keymap}_utf-8.vim keymap/{keymap}.vim -Here {keymap} is the value of the 'keymap' option and {encoding} of the -'encoding' option. The file name with the {encoding} included is tried first. +Here {keymap} is the value of the 'keymap' option. +The file name with "utf-8" included is tried first. 'runtimepath' is used to find these files. To see an overview of all available keymap files, use this: > @@ -950,7 +940,7 @@ this is unusual. But you can use various ways to specify the character: > A <char-0141> octal value x <Space> special key name -The characters are assumed to be encoded for the current value of 'encoding'. +The characters are assumed to be encoded in UTF-8. It's possible to use ":scriptencoding" when all characters are given literally. That doesn't work when using the <char-> construct, because the conversion is done on the keymap file, not on the resulting character. @@ -1170,21 +1160,13 @@ Useful commands: message is truncated, use ":messages"). - "g8" shows the bytes used in a UTF-8 character, also the composing characters, as hex numbers. -- ":set encoding=utf-8 fileencodings=" forces using UTF-8 for all files. The - default is to use the current locale for 'encoding' and set 'fileencodings' - to automatically detect the encoding of a file. +- ":set fileencodings=" forces using UTF-8 for all files. The + default is to automatically detect the encoding of a file. STARTING VIM -If your current locale is in an utf-8 encoding, Vim will automatically start -in utf-8 mode. - -If you are using another locale: > - - set encoding=utf-8 - -You might also want to select the font used for the menus. Unfortunately this +You might want to select the font used for the menus. Unfortunately this doesn't always work. See the system specific remarks below, and 'langmenu'. @@ -1245,10 +1227,9 @@ not everybody is able to type a composing character. These options are relevant for editing multi-byte files. Check the help in options.txt for detailed information. -'encoding' Encoding used for the keyboard and display. It is also the - default encoding for files. +'encoding' Internal text encoding, always "utf-8". -'fileencoding' Encoding of a file. When it's different from 'encoding' +'fileencoding' Encoding of a file. When it's different from "utf-8" conversion is done when reading or writing the file. 'fileencodings' List of possible encodings of a file. When opening a file diff --git a/runtime/doc/message.txt b/runtime/doc/message.txt index 114bb61d99..fd66a5dafb 100644 --- a/runtime/doc/message.txt +++ b/runtime/doc/message.txt @@ -1,4 +1,4 @@ -*message.txt* For Vim version 7.4. Last change: 2013 Feb 23 +*message.txt* For Vim version 7.4. Last change: 2016 Jul 14 VIM REFERENCE MANUAL by Bram Moolenaar @@ -19,6 +19,15 @@ The ":messages" command can be used to view previously given messages. This is especially useful when messages have been overwritten or truncated. This depends on the 'shortmess' option. + :messages Show all messages. + + :{count}messages Show the {count} most recent messages. + + :messages clear Clear all messages. + + :{count}messages clear Clear messages, keeping only the {count} most + recent ones. + The number of remembered messages is fixed at 20 for the tiny version and 200 for other versions. @@ -58,9 +67,9 @@ If you are lazy, it also works without the shift key: > When an error message is displayed, but it is removed before you could read it, you can see it again with: > :echo errmsg -or view a list of recent messages with: > +Or view a list of recent messages with: > :messages - +See `:messages` above. LIST OF MESSAGES *E222* *E228* *E232* *E256* *E293* *E298* *E304* *E317* @@ -656,6 +665,12 @@ You must be using an awful lot of buffers. It's now possible that two buffers have the same number, which causes various problems. You might want to exit Vim and restart it. + *E931* > + Buffer cannot be registered + +Out of memory or a duplicate buffer number. May habben after W14. Looking up +a buffer will not always work, better restart Vim. + *E296* *E297* > Seek error in swap file write Write error in swap file diff --git a/runtime/doc/mlang.txt b/runtime/doc/mlang.txt index 5f4642274c..a2be3cfd49 100644 --- a/runtime/doc/mlang.txt +++ b/runtime/doc/mlang.txt @@ -1,4 +1,4 @@ -*mlang.txt* For Vim version 7.4. Last change: 2012 Jan 15 +*mlang.txt* For Vim version 7.4. Last change: 2016 Jan 16 VIM REFERENCE MANUAL by Bram Moolenaar @@ -94,13 +94,15 @@ If you used the self-installing .exe file, message translations should work already. Otherwise get the libintl.dll file if you don't have it yet: http://sourceforge.net/projects/gettext +Or: + https://mlocati.github.io/gettext-iconv-windows/ This also contains tools xgettext, msgformat and others. libintl.dll should be placed in same directory with (g)vim.exe, or some -place where PATH environment value describe. Message files (vim.mo) -have to be placed in "$VIMRUNTIME/lang/xx/LC_MESSAGES", where "xx" is the -abbreviation of the language (mostly two letters). +place where PATH environment value describe. Vim also finds libintl-8.dll. +Message files (vim.mo) have to be placed in "$VIMRUNTIME/lang/xx/LC_MESSAGES", +where "xx" is the abbreviation of the language (mostly two letters). If you write your own translations you need to generate the .po file and convert it to a .mo file. You need to get the source distribution and read diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt index 7f84f2d2a3..606fd53fee 100644 --- a/runtime/doc/motion.txt +++ b/runtime/doc/motion.txt @@ -1,4 +1,4 @@ -*motion.txt* For Vim version 7.4. Last change: 2015 Jun 06 +*motion.txt* For Vim version 7.4. Last change: 2016 Jul 12 VIM REFERENCE MANUAL by Bram Moolenaar @@ -569,7 +569,7 @@ i[ "inner [] block", select [count] '[' ']' blocks. This When used in Visual mode it is made characterwise. a) *v_a)* *a)* *a(* -a( *v_ab* *v_a(* *ab* +a( *vab* *v_ab* *v_a(* *ab* ab "a block", select [count] blocks, from "[count] [(" to the matching ')', including the '(' and ')' (see |[(|). Does not include white space outside of the @@ -577,7 +577,7 @@ ab "a block", select [count] blocks, from "[count] [(" to When used in Visual mode it is made characterwise. i) *v_i)* *i)* *i(* -i( *v_ib* *v_i(* *ib* +i( *vib* *v_ib* *v_i(* *ib* ib "inner block", select [count] blocks, from "[count] [(" to the matching ')', excluding the '(' and ')' (see |[(|). @@ -1013,6 +1013,9 @@ CTRL-I Go to [count] newer cursor position in jump list *:ju* *:jumps* :ju[mps] Print the jump list (not a motion command). + *:cle* *:clearjumps* +:cle[arjumps] Clear the jump list of the current window. + *jumplist* Jumps are remembered in a jump list. With the CTRL-O and CTRL-I command you can go to cursor positions before older jumps, and back again. Thus you can diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index bafb9dfc2c..c074eb43ff 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -1,97 +1,93 @@ -*msgpack_rpc.txt* For Nvim. {Nvim} +*msgpack_rpc.txt* {Nvim} NVIM REFERENCE MANUAL by Thiago de Arruda -The Msgpack-RPC Interface to Nvim *msgpack-rpc* +RPC API for Nvim *RPC* *rpc* *msgpack-rpc* -1. Introduction |msgpack-rpc-intro| -2. API mapping |msgpack-rpc-api| -3. Connecting |msgpack-rpc-connecting| -4. Clients |msgpack-rpc-clients| -5. Types |msgpack-rpc-types| -6. Wrapping methods |msgpack-rpc-wrap-methods| -7. Vimscript functions |msgpack-rpc-vim-functions| +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| ============================================================================== -1. Introduction *msgpack-rpc-intro* +1. Introduction *rpc-intro* -The primary way to control a running Nvim instance is through -MessagePack-RPC, a messaging protocol that uses the MessagePack serialization -format: https://github.com/msgpack/msgpack/blob/7498cf3/spec.md. -From now on, we refer to the protocol as msgpack-rpc. +The primary way to control Nvim programmatically is the RPC API, which speaks +MessagePack-RPC ("msgpack-rpc"), a messaging protocol that uses the +MessagePack serialization format: + https://github.com/msgpack/msgpack/blob/0b8f5ac/spec.md -At this point, only plugins use msgpack-rpc, but eventually even user -interaction will happen through it, since user interfaces will be separate -programs that control a headless Nvim instance. +All kinds of Nvim "clients" use the RPC API: user interfaces (GUIs), remote +plugins, scripts like "nvr" (https://github.com/mhinz/neovim-remote), and even +`nvim` itself can control other `nvim` instances. By connecting to the RPC API +programs can: -By connecting to the msgpack-rpc interface, programs can: + - Call any API function + - Listen for events + - Receive remote calls from Nvim -- Call any Nvim API function -- Listen for Nvim events -- Receive remote calls from Nvim - -Nvim's msgpack-rpc interface is like a more powerful version of Vim's -`clientserver` feature. +The RPC API is like a more powerful version of Vim's `clientserver` feature. ============================================================================== -2. API mapping *msgpack-rpc-api* + 2. API mapping *rpc-api* -The Nvim C API, see |nvim-api|, is automatically exposed to the msgpack-rpc -interface by the build system, which parses headers at src/nvim/api from the -project root. A dispatch function is generated, which matches msgpack-rpc method -names with non-static API functions, converting/validating arguments and return -values back to msgpack. +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 +matches RPC API method names with public API functions, converting/validating +arguments and return values back to msgpack. -Client libraries will normally provide wrappers that hide msgpack-rpc details -from programmers. The wrappers can be automatically generated by reading -bundled API metadata from a compiled Nvim instance. +Client libraries (|api-client|s) normally provide wrappers that hide +msgpack-rpc details from application developers. The wrappers can be +automatically generated by reading bundled API metadata from a compiled Nvim +instance. -There are two ways to obtain API metadata: +There are three ways to obtain API metadata: -1. By connecting to a running Nvim instance and calling `vim_get_api_info` - via msgpack-rpc. This is best for clients written in dynamically-typed - languages, which can define functions at runtime. + 1. Connect to a running Nvim instance and call `nvim_get_api_info` via + msgpack-rpc. This is best for clients written in dynamic languages which + can define functions at runtime. -2. By starting Nvim with the `--api-info` command-line option, which makes Nvim - dump a blob of msgpack metadata to standard output and exit. This is best - for clients written in statically-typed languages, which require a separate - compilation step. + 2. Start Nvim with the |--api-info| option. Useful for clients written in + statically-compiled languages. -Here's a simple way to get human-readable description of the API (requires -Python and the `pyyaml`/`msgpack-python` pip packages): -> - nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))' > api.yaml + 3. Use the |api_info()| vimscript function. + +To get a human-readable list of API functions: > + :new|put =map(api_info().functions, 'v:val.name') +< +To get a formatted dump of the API using python (requires the `pyyaml` and +`msgpack-python` packages): > + nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))' < ============================================================================== -3. Connecting *msgpack-rpc-connecting* +3. Connecting *rpc-connecting* -There are four ways to open msgpack-rpc streams to Nvim: +There are several ways to open a msgpack-rpc channel to an Nvim instance: -1. Through Nvim's stdin/stdout when it's started with the `--embed` option. - This is how other programs can embed Nvim. + 1. Through stdin/stdout when `nvim` is started with `--embed`. This is how + applications can embed Nvim. -2. Through the stdin/stdout of a program spawned by the |rpcstart()| function. + 2. Through stdin/stdout of some other process spawned by |jobstart()|. + Set the "rpc" key to |v:true| in the options dict to use the job's stdin + and stdout as a single msgpack channel that is processed directly by + Nvim. Then it is not possible to process raw data to or from the + process's stdin and stdout. stderr can still be used, though. - *$NVIM_LISTEN_ADDRESS* -3. Through the socket automatically created with each instance. To get the - socket location for a running Nvim instance (which is random by default), - see the |$NVIM_LISTEN_ADDRESS| environment variable: -> - :echo $NVIM_LISTEN_ADDRESS -< - See also |v:servername|. + 3. Through the socket automatically created with each instance. The socket + location is stored in |v:servername|. -4. Through a TCP/IP socket. To make Nvim listen on a TCP/IP socket, set the - |$NVIM_LISTEN_ADDRESS| environment variable in a shell before starting Nvim: -> + 4. Through a TCP/IP socket. To make Nvim listen on a TCP/IP socket, set the + |$NVIM_LISTEN_ADDRESS| environment variable before starting Nvim: > NVIM_LISTEN_ADDRESS=127.0.0.1:6666 nvim < -Connecting to the socket is the easiest way a programmer can test the API, which -can be done through any msgpack-rpc client library or fully-featured Nvim client -(which we'll see in the next section). Here's a Ruby script that prints 'hello -world!' in the current Nvim instance: +Connecting to the socket is the easiest way a programmer can test the API, +which can be done through any msgpack-rpc client library or full-featured +|api-client|. Here's a Ruby script that prints 'hello world!' in the current +Nvim instance: > #!/usr/bin/env ruby # Requires msgpack-rpc: gem install msgpack-rpc @@ -109,7 +105,7 @@ world!' in the current Nvim instance: require 'msgpack/rpc/transport/unix' nvim = MessagePack::RPC::Client.new(MessagePack::RPC::UNIXTransport.new, ENV['NVIM_LISTEN_ADDRESS']) - result = nvim.call(:vim_command, 'echo "hello world!"') + result = nvim.call(:nvim_command, 'echo "hello world!"') < A better way is to use the Python REPL with the `neovim` package, where API functions can be called interactively: @@ -118,72 +114,110 @@ functions can be called interactively: >>> nvim = attach('socket', path='[address]') >>> nvim.command('echo "hello world!"') < -One can also spawn and connect to an embedded Nvim instance via |rpcstart()| +You can also embed an Nvim instance via |jobstart()|, and communicate using +|rpcrequest()| and |rpcnotify()|: > - let vim = rpcstart('nvim', ['--embed']) - echo rpcrequest(vim, 'vim_eval', '"Hello " . "world!"') - call rpcstop(vim) + let nvim = jobstart(['nvim', '--embed'], {'rpc': v:true}) + echo rpcrequest(nvim, 'nvim_eval', '"Hello " . "world!"') + call jobstop(nvim) < ============================================================================== -4. Implementing new clients *msgpack-rpc-clients* - -Nvim is still in alpha, so there's no in-depth documentation explaining how to -properly implement a client library yet. The Python client (the pip package -"neovim") will always be up-to-date with the latest API changes, so its source -code is the best documentation currently available. There are some guidelines -however: - -- Separate the transport layer from the rest of the library. See - |msgpack-rpc-connecting| for details on how clients can connect to Nvim. -- Use a MessagePack library that implements at least version 5 of the - MessagePack spec, which supports the `bin` and `ext` types used by Nvim. -- Read API metadata in order to create client-side wrappers for all - msgpack-rpc methods. -- Use a single-threaded event loop library/pattern. -- Use a fiber/coroutine library for the language being used for implementing a - client. These greatly simplify concurrency and allow the library to expose a - blocking API on top of a non-blocking event loop without the complexity that - comes with preemptive multitasking. -- Don't assume anything about the order that responses to msgpack-rpc requests - will arrive. -- Clients should expect msgpack-rpc requests, which need to be handled - immediately because Nvim is blocked while waiting for the client response. -- Clients should expect to receive msgpack-rpc notifications, but these don't - need to be handled immediately because they won't block Nvim (although they - should probably be handled immediately anyway). - -Most of the complexity could be handled by a msgpack-rpc library that supports -server to client requests and notifications, but it's not clear if this is part -of the msgpack-rpc spec. At least the Ruby msgpack-rpc library does not seem -to support it: - +4. Implementing API clients *rpc-api-client* *api-client* + +"API clients" wrap the Nvim API to provide idiomatic "SDKs" for their +respective platforms (see |dev-jargon|). You can build a new API client for +your favorite platform or programming language. + +Existing API clients are listed here: + https://github.com/neovim/neovim/wiki/Related-projects#api-clients + +The Python client is the reference implementation for API clients. It is +always up-to-date with the Nvim API, so its source code and test suite are +authoritative references. + https://github.com/neovim/python-client + +API client implementation guidelines ~ + + - Separate the transport layer from the rest of the library. See + |rpc-connecting| for details on how clients can connect to Nvim. + - Use a MessagePack library that implements at least version 5 of the + MessagePack spec, which supports the `bin` and `ext` types used by Nvim. + - Read API metadata in order to create client-side wrappers for all + msgpack-rpc methods. + - Use a single-threaded event loop library/pattern. + - Use a fiber/coroutine library for the language being used for implementing + a client. These greatly simplify concurrency and allow the library to + expose a blocking API on top of a non-blocking event loop without the + complexity that comes with preemptive multitasking. + - Don't assume anything about the order that responses to msgpack-rpc + requests will arrive. + - Clients should expect msgpack-rpc requests, which need to be handled + immediately because Nvim is blocked while waiting for the client response. + - Clients should expect to receive msgpack-rpc notifications, but these + don't need to be handled immediately because they won't block Nvim + (although they should probably be handled immediately anyway). + +Note: Most of the complexity could be handled by a msgpack-rpc library that +supports server to client requests and notifications, but it's not clear if +this is part of the msgpack-rpc spec. At least the Ruby msgpack-rpc library +does not seem to support it: https://github.com/msgpack-rpc/msgpack-rpc-ruby/blob/master/lib/msgpack/rpc/transport/tcp.rb#L150-L158 +API metadata object ~ + +API clients exist to hide msgpack-rpc details. The API metadata object +contains information that makes this task easier (see also |rpc-types|): + + - The "version" key contains the Nvim version, API level, and API + backwards-compatibility level. + - The "functions" key contains a list of metadata objects for individual + functions. + - Each function metadata object has |rpc-types| information about the return + value and parameters. These can be used for generating strongly-typed APIs + in static languages. + - Container types may be decorated with type/size constraints, e.g. + ArrayOf(Buffer) or ArrayOf(Integer, 2). This can be useful to generate + even more strongly-typed APIs. + - Functions that are considered to be methods that operate on instances of + Nvim special types (msgpack EXT) will have the `"method"` attribute set to + `true`. The reciever type is the type of the first argument. The method + names are prefixed with `nvim_` plus a shortened type name, e.g. + `nvim_buf_get_lines` represents the `get_lines` method of a Buffer instance. + - Global functions have `"method"` set to `false` and are prefixed with just + `nvim_`, e.g. `nvim_get_buffers`. + +So for an object-oriented language, an API client contains the classes +representing Nvim special types, and the methods of each class could be +defined by stripping the prefix for the type as defined in the `types` metadata +(this will always be the first two "_"-separated parts of the function name). +There could also be a singleton Vim class with methods where the `nvim_` +prefix is stripped off. + ============================================================================== -5. Types *msgpack-rpc-types* +5. Types *rpc-types* -Nvim's C API uses custom types for all functions, se |nvim-api-types|. -For the purpose of mapping to msgpack, he types can be split into two groups: +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: -- Basic types that map natively to msgpack (and probably have a default - representation in msgpack-supported programming languages) -- Special Nvim types that map to msgpack EXT with custom type codes. + - Basic types that map natively to msgpack (and probably have a default + representation in msgpack-supported programming languages) + - Special Nvim types that map to msgpack EXT with custom type codes. -Basic type mapping: +Basic types ~ -Nil -> msgpack nil -Boolean -> msgpack boolean -Integer (signed 64-bit integer) -> msgpack integer -Float (IEEE 754 double precision) -> msgpack float -String -> msgpack string -Array -> msgpack array -Dictionary -> msgpack map + Nil -> msgpack nil + Boolean -> msgpack boolean + Integer (signed 64-bit integer) -> msgpack integer + Float (IEEE 754 double precision) -> msgpack float + String -> msgpack string + Array -> msgpack array + Dictionary -> msgpack map -Special Nvim types that use msgpack EXT: +Special types (msgpack EXT) ~ -Buffer -> enum value kObjectTypeBuffer -Window -> enum value kObjectTypeWindow -Tabpage -> enum value kObjectTypeTabpage + Buffer -> enum value kObjectTypeBuffer + 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 @@ -191,70 +225,193 @@ an integer, but not a Window or Tabpage. 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 -`vim_get_api_info` method at runtime. Here's an example JSON representation of +`nvim_get_api_info` method at runtime. Here's a sample JSON representation of the `types` object: > "types": { "Buffer": { - "id": 0 + "id": 0, + "prefix": "nvim_buf_" }, "Window": { - "id": 1 + "id": 1, + "prefix": "nvim_win_" }, "Tabpage": { - "id": 2 + "id": 2, + "prefix": "nvim_tabpage_" } } < -Even for statically compiled clients, it's a 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. - -============================================================================== -6. Wrapping methods *msgpack-rpc-wrap-methods* - -As mentioned before, clients should provide an API that hides msgpack-rpc -details from programmers, and the API metadata object contains information -that makes this task easier: - -- The "functions" key contains a list of metadata objects for individual - functions. -- Each function metadata object has type information about the return value - and parameters. These can be used for generating strongly-typed APIs in - static languages. -- Container types may be decorated with type/size constraints, e.g. - ArrayOf(Buffer) or ArrayOf(Integer, 2). This can be useful to generate even - more strongly-typed APIs. -- Methods that operate instances of Nvim's types are prefixed with the type - name in lower case, e.g. `buffer_get_line` represents the `get_line` method - of a Buffer instance. -- Global methods are prefixed with `vim`, e.g. `vim_get_buffers`. - -So, for an object-oriented language, a client library would have the classes -that represent Nvim's types, and the methods of each class could be defined -by inspecting the method name prefix. There could also be a singleton Vim -class with methods mapped to functions prefixed with `vim_` +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. ============================================================================== -7. Vimscript functions *msgpack-rpc-vim-functions* - -Four msgpack-rpc functions are available in Vimscript: - -1. |rpcstart()|: Similarly to |jobstart()|, this will spawn a co-process with - its standard handles connected to Nvim. The difference is that it's not - possible to process raw data to or from the process's stdin, stdout, or - stderr. This is because the job's stdin and stdout are used as a single - msgpack channel that is processed directly by Nvim. - -2. |rpcstop()|: Same as |jobstop()|, but operates on handles returned by - |rpcstart()|. - -3. |rpcrequest()|: Sends a msgpack-rpc request to the process. - -4. |rpcnotify()|: Sends a msgpack-rpc notification to the process. - -The last two functions may also be used with channels created from -connections to |$NVIM_LISTEN_ADDRESS|. +6. Remote UIs *rpc-remote-ui* + +Nvim allows Graphical user interfaces to be implemented by separate processes +communicating with Nvim over the RPC API. Currently the ui model conists of a +terminal-like grid with one single, monospace font size, with a few elements +that could be drawn separately from the grid (for the momemnt only the popup +menu) + +After connecting to a nvim instance (typically a spawned, embedded instance) +use the |nvim_ui_attach|(width, height, options) API method to tell nvim that your +program wants to draw the nvim screen on a grid with "width" times +"height" cells. "options" should be a dictionary with the following (all +optional) keys: + `rgb`: Controls what color format to use. + Set to true (default) to use 24-bit rgb + 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. + +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). + +Screen updates are arrays. The first element a string describing the kind +of update. + +["resize", width, height] + The grid is resized to `width` and `height` cells. + +["clear"] + Clear the screen. + +["eol_clear"] + Clear from the cursor position to the end of the current line. + +["cursor_goto", row, col] + Move the cursor to position (row, col). Currently, the same cursor is + used to define the position for text insertion and the visible cursor. + However, only the last cursor position, after processing the entire + array in the "redraw" event, is intended to be a visible cursor + position. + +["update_fg", color] +["update_bg", color] +["update_sp", color] + Set the default foreground, background and special colors + respectively. + +["highlight_set", attrs] + Set the attributes that the next text put on the screen will have. + `attrs` is a dict with the keys below. Any absent key is reset + to its default value. Color defaults are set by the `update_fg` etc + updates. All boolean keys default to false. + + `foreground`: foreground color. + `background`: backround color. + `special`: color to use for underline and undercurl, when present. + `reverse`: reverse video. Foreground and background colors are + switched. + `italic`: italic text. + `bold`: bold text. + `underline`: underlined text. The line has `special` color. + `undercurl`: undercurled text. The curl has `special` color. + +["put", text] + The (utf-8 encoded) string `text` is put at the cursor position + (and the cursor is advanced), with the highlights as set by the + last `highlight_set` update. + +["set_scroll_region", top, bot, left, right] + Define the scroll region used by `scroll` below. + +["scroll", count] + Scroll the text in the scroll region. The diagrams below illustrate + what will happen, depending on the scroll direction. "=" is used to + represent the SR(scroll region) boundaries and "-" the moved rectangles. + Note that dst and src share a common region. + + If count is bigger than 0, move a rectangle in the SR up, this can + happen while scrolling down. +> + +-------------------------+ + | (clipped above SR) | ^ + |=========================| dst_top | + | dst (still in SR) | | + +-------------------------+ src_top | + | src (moved up) and dst | | + |-------------------------| dst_bot | + | src (cleared) | | + +=========================+ src_bot +< + If count is less than zero, move a rectangle in the SR down, this can + happen while scrolling up. +> + +=========================+ src_top + | src (cleared) | | + |------------------------ | dst_top | + | src (moved down) and dst| | + +-------------------------+ src_bot | + | dst (still in SR) | | + |=========================| dst_bot | + | (clipped below SR) | v + +-------------------------+ +< +["set_title", title] +["set_icon", icon] + Set the window title, and icon (minimized) window title, respectively. + In windowing systems not distinguishing between the two, "set_icon" + can be ignored. + +["mouse_on"] +["mouse_off"] + Tells the client whether mouse support, as determined by |'mouse'| + option, is considered to be active in the current mode. This is mostly + useful for a terminal frontend, or other situations where nvim mouse + would conflict with other usages of the mouse. It is safe for a client + to ignore this and always send mouse events. + +["busy_on"] +["busy_off"] + Nvim started or stopped being busy, and possibly not responsible to user + input. This could be indicated to the user by hiding the cursor. + +["suspend"] + |:suspend| command or |Ctrl-Z| mapping is used. A terminal client (or other + client where it makes sense) could suspend itself. Other clients can + safely ignore it. + +["bell"] +["visual_bell"] + Notify the user with an audible or visual bell, respectively. + +["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. + +["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 + this update is sent. `items` is an array of the items to show, the + items are themselves arrays of the form [word, kind, menu, info] + as defined at |complete-items|, except that `word` is replaced by + `abbr` if present. `selected` is the initially selected item, either a + zero-based index into the array of items, or -1 if no item is + selected. `row` and `col` is the anchor position, where the first + character of the completed word will be. + +["popupmenu_select", selected] + An item in the currently displayed popupmenu is selected. `selected` + is either a zero-based index into the array of items from the last + `popupmenu_show` event, or -1 if no item is selected. + +["popupmenu_hide"] + The popupmenu is hidden. ============================================================================== vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt index a7c512d1dc..7dfbbd0cf0 100644 --- a/runtime/doc/nvim.txt +++ b/runtime/doc/nvim.txt @@ -1,24 +1,59 @@ -*nvim.txt* For Nvim. {Nvim} +*nvim.txt* {Nvim} - NVIM REFERENCE MANUAL *nvim* + NVIM REFERENCE MANUAL -Introduction to Nvim *nvim-intro* +Nvim *nvim* *nvim-intro* -This is an introduction for Vim users who are just getting started with Nvim. -It is not meant for Vim beginners. For a basic introduction to Vim, -see |help.txt|. +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. -1. Transitioning from Vim |nvim-from-vim| -2. Differences from Vim |vim-differences| -3. Msgpack-RPC |msgpack-rpc| -4. Job control |job-control| -5. Python plugins |nvim-python| -6. Clipboard integration |nvim-clipboard| -7. Remote plugins |remote-plugin| -8. Provider infrastructure |nvim-provider| -9. Integrated terminal emulator |nvim-terminal-emulator| +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. + +============================================================================== +Transitioning from Vim *nvim-from-vim* + +To start the transition, link your previous configuration so Nvim can use it: +> + mkdir ~/.config + ln -s ~/.vim ~/.config/nvim + ln -s ~/.vimrc ~/.config/nvim/init.vim +< +Note: If your system sets `$XDG_CONFIG_HOME`, use that instead of `~/.config` +in the code above. Nvim follows the XDG |base-directories| convention. + +See |provider-python| and |provider-clipboard| for additional software you +might need to use some features. + +Your Vim configuration might not be entirely compatible with Nvim. For a +full list of differences between Vim and Nvim see |vim-differences|. + +The |'ttymouse'| option, for example, was removed from Nvim (mouse support +should work without it). If you use the same |vimrc| for Vim and Nvim, +consider guarding |'ttymouse'| in your configuration like so: +> + if !has('nvim') + set ttymouse=xterm2 + endif +< +Conversely, if you have Nvim specific configuration items, you could do +this: +> + if has('nvim') + tnoremap <Esc> <C-\><C-n> + endif +< +For a more granular approach use |exists()|: +> + if exists(':tnoremap') + tnoremap <Esc> <C-\><C-n> + endif +< +Now you should be able to explore Nvim more comfortably. Check |nvim-features| +for more information. ============================================================================== vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/nvim_clipboard.txt b/runtime/doc/nvim_clipboard.txt deleted file mode 100644 index 078382c7a7..0000000000 --- a/runtime/doc/nvim_clipboard.txt +++ /dev/null @@ -1,63 +0,0 @@ -*nvim_clipboard.txt* For Nvim. {Nvim} - - - NVIM REFERENCE MANUAL by Thiago de Arruda - - -Clipboard integration for Nvim *nvim-clipboard* - -1. Intro |nvim-clipboard-intro| -2. X11 selection mechanism |nvim-clipboard-x11| - -============================================================================== -1. Intro *nvim-clipboard-intro* - -Nvim has no direct connection to the system clipboard. Instead, it is -accessible through the |nvim-provider| infrastructure, which transparently -uses shell commands for communicating with the clipboard. - -Clipboard access is implicitly enabled if any of the following clipboard tools -is found in your `$PATH`. - -- xclip -- xsel (newer alternative to xclip) -- pbcopy/pbpaste (only for Mac OS X) -- lemonade (useful for SSH machine) - https://github.com/pocke/lemonade -- doitclient (another option for SSH setups from the maintainer of PuTTY) - http://www.chiark.greenend.org.uk/~sgtatham/doit/ - -The presence of a suitable clipboard tool implicitly enables the '+' and '*' -registers. - -If you want to ALWAYS use the clipboard for ALL operations (as opposed -to interacting with the '+' and/or '*' registers explicitly), set the -following option: -> - set clipboard+=unnamedplus -< -See 'clipboard' for details and more options. - -============================================================================== -2. X11 selection mechanism *nvim-clipboard-x11* *x11-selection* - -The clipboard providers for X11 store text in what is known as "selections". -Selections are "owned" by an application, so when the application is closed, -the selection text is lost. - -The contents of selections are held by the originating application (e.g., upon -a copy), and only passed on to another application when that other application -asks for them (e.g., upon a paste). - - *quoteplus* *quote+* - -There are three documented X11 selections: `PRIMARY`, `SECONDARY`, and `CLIPBOARD`. -`CLIPBOARD` is typically used in X11 applications for copy/paste operations -(`Ctrl-c`/`v`), while `PRIMARY` is used for the last selected text, which is -generally inserted with the middle mouse button. - -Nvim's X11 clipboard providers only utilize the `PRIMARY` and `CLIPBOARD` -selections, used for the '*' and '+' registers, respectively. - -============================================================================== - vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/nvim_from_vim.txt b/runtime/doc/nvim_from_vim.txt deleted file mode 100644 index 299eeb05f5..0000000000 --- a/runtime/doc/nvim_from_vim.txt +++ /dev/null @@ -1,50 +0,0 @@ -*nvim_from_vim.txt* For Nvim. {Nvim} - - - NVIM REFERENCE MANUAL - - -Transitioning from Vim *nvim-from-vim* - -Nvim is emphatically a fork of Vim, so compatibility to Vim should be pretty -good. - -To start the transition, link your previous configuration so Nvim can use -it: -> - mkdir -p ${XDG_CONFIG_HOME:=$HOME/.config} - ln -s ~/.vim $XDG_CONFIG_HOME/nvim - ln -s ~/.vimrc $XDG_CONFIG_HOME/nvim/init.vim -< -See |nvim-intro|, especially |nvim-python| and |nvim-clipboard|, for -additional software you might need to install to use all of Nvim's features. - -Your Vim configuration might not be entirely compatible with Nvim. For a -full list of differences between Vim and Nvim, see |vim-differences|. - -The |'ttymouse'| option, for example, was removed from Nvim (mouse support -should work without it). If you use the same |vimrc| for Vim and Nvim, -consider guarding |'ttymouse'| in your configuration like so: -> - if !has('nvim') - set ttymouse=xterm2 - endif -< -Conversely, if you have Nvim specific configuration items, you could do -this: -> - if has('nvim') - tnoremap <Esc> <C-\><C-n> - endif -< -For a more granular approach, use |exists()|: -> - if exists(':tnoremap') - tnoremap <Esc> <C-\><C-n> - endif -< -Now you should be able to explore Nvim more comfortably. Check |nvim| for more -information. - -============================================================================== - vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/nvim_provider.txt b/runtime/doc/nvim_provider.txt deleted file mode 100644 index 91cd5fbfc7..0000000000 --- a/runtime/doc/nvim_provider.txt +++ /dev/null @@ -1,76 +0,0 @@ -*nvim_provider.txt* For Nvim. {Nvim} - - - NVIM REFERENCE MANUAL by Thiago de Arruda - - -Nvim provider infrastructure *nvim-provider* - -First of all, this document is meant to be read by developers interested in -contributing to the refactoring effort. If you are a normal user or plugin -developer looking to learn about Nvim |msgpack-rpc| infrastructure for -implementing plugins in other programming languages, see |remote-plugin|. -For instructions on how to enable Python plugins, see |nvim-python|. For -clipboard, see |nvim-clipboard|. - -Instead of doing everything by itself, Nvim aims to simplify its own -maintenance by delegating as much work as possible to external systems. But -some Vim components are too tightly coupled and in some cases the refactoring -work necessary to swap in-house implementations by code that integrates to -other systems is too great. Nvim provider infrastructure is a facility that -aims to make this task simpler. - -To understand why the provider infrastructure is useful, let us consider two -examples of integration with external systems that are implemented in Vim and -are now decoupled from Nvim core as providers: - -The first example is clipboard integration: in the original Vim source code, -clipboard functions account for more than 1k lines of C source code (and that -is just on ui.c), all to perform two tasks that are now accomplished with -simple shell commands such as xclip or pbcopy/pbpaste. - -The other example is Python scripting support: Vim has three files dedicated to -embedding the Python interpreter: if_python.c, if_python3.c and if_py_both.h. -Together these files sum about 9.5k lines of C source code. On Nvim, Python -scripting is performed by an external host process that is running 2k sloc -Python program. - -In a perfect world, we would implement Python and clipboard integration in -pure vimscript and without touching the C code. Unfortunately we can't achieve -these goals without severely compromising backwards compatibility with Vim. -That's where providers come to the rescue. - -In essence, this infrastructure is a simple framework that simplifies the task -of calling vimscript from C code, making it simpler to rewrite C functions that -interact with external systems in pure vimscript. It is composed of two -functions in eval.c: - -- eval_call_provider(name, method, arguments): Call a provider(name) method - with arguments -- eval_has_provider(name): Checks if a provider is implemented - -What these functions do is simple: - -- eval_call_provider will call the provider#(name)#Call function passing in - the method and arguments. -- eval_has_provider will return true if the provider#(name)#Call function is - implemented, and is called by the "has" vimscript function to check if - features are available. - -The basic idea is that the provider#(name)#Call function should implement -integration with an external system, because calling shell commands and -|msgpack-rpc| clients (Nvim only) is easier to do in vimscript. - -Now, back to the Python example. Instead of modifying vimscript to allow for -the definition of lowercase functions and commands (for the |:python|, -|:pyfile|, and |:pydo| commands, and the |pyeval()| function), which would -break backwards compatibility with Vim, we implemented the -autoload/provider/python.vim script and the provider#python#Call function -that is only defined if an external Python host is started successfully. - -That works well with the `has('python')` expression (normally used by Python -plugins) because if the Python host isn't installed then the plugin will -"think" it is running in a Vim compiled without |+python| feature. - -============================================================================== - vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/nvim_python.txt b/runtime/doc/nvim_python.txt deleted file mode 100644 index a2fc968db4..0000000000 --- a/runtime/doc/nvim_python.txt +++ /dev/null @@ -1,95 +0,0 @@ -*nvim_python.txt* For Nvim. {Nvim} - - - NVIM REFERENCE MANUAL by Thiago de Arruda - - -Python plugins and scripting in Nvim *nvim-python* - -1. Introduction |nvim-python-intro| -2. Quickstart |nvim-python-quickstart| - -============================================================================== -1. Introduction *nvim-python-intro* - -Through external Python 2/3 interpreters connected via |msgpack-rpc|, Nvim -offers some support for the legacy |python-vim| and |python3| interfaces. - -Note: For now only the old Vim 7.3 API is supported. - -============================================================================== -2. Quickstart *nvim-python-quickstart* - -If you used a package manager to install Nvim, there's a good chance that -it also provides the `neovim` Python package. If it doesn't, follow these -steps to install the package with Python's package manager, `pip`. - -Note: Depending on your system, `pip` might refer to Python 2 or Python 3, - which is why the following instructions mention `pip2` or `pip3` - explicitly. If one of these is not available for you, maybe `pip` - is what you want. - -To use Vim Python 2/3 plugins with Nvim, do the following: - -- For Python 2 plugins, make sure an interpreter for Python 2.6 or 2.7 is - available in your `$PATH`, then install the `neovim` Python package systemwide: - > - $ sudo pip2 install neovim -< - or for the current user: -> - $ pip2 install --user neovim -< -- For Python 3 plugins, make sure an interpreter for Python 3.3 or above is - available in your `$PATH`, then install the `neovim` Python package systemwide: - > - $ sudo pip3 install neovim -< - or for the current user: -> - $ pip3 install --user neovim -< -Note: If you previously installed the package, get the latest version by - appending the `--upgrade` flag to the commands above. - -============================================================================== - *g:python_host_prog* - -To point Nvim to a specific Python 2 interpreter, set |g:python_host_prog|: -> - let g:python_host_prog = '/path/to/python' -< - *g:python3_host_prog* - -To point Nvim to a specific Python 3 interpreter, set |g:python3_host_prog|: -> - let g:python3_host_prog = '/path/to/python3' -< - *g:loaded_python_provider* - -To disable Python 2 interface, set `g:loaded_python_provider` to 1: -> - let g:loaded_python_provider = 1 -< - *g:loaded_python3_provider* - -To disable Python 3 interface, set `g:loaded_python3_provider` to 1: -> - let g:loaded_python3_provider = 1 -< - *g:python_host_skip_check* - -To disable Python 2 interpreter check, set `g:python_host_skip_check` to 1: -Note: If you disable Python 2 check, you must install neovim module properly. -> - let g:python_host_skip_check = 1 -< - *g:python3_host_skip_check* - -To disable Python 3 interpreter check, set `g:python3_host_skip_check` to 1: -Note: If you disable Python 3 check, you must install neovim module properly. -> - let g:python3_host_skip_check = 1 -< -============================================================================== - vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt index 6ef3aaebaa..8f7dc0dbf0 100644 --- a/runtime/doc/nvim_terminal_emulator.txt +++ b/runtime/doc/nvim_terminal_emulator.txt @@ -1,34 +1,31 @@ -*nvim_terminal_emulator.txt* For Nvim. {Nvim} +*terminal_emulator.txt* {Nvim} NVIM REFERENCE MANUAL by Thiago de Arruda -Nvim integrated terminal emulator *nvim-terminal-emulator* +Embedded terminal emulator *terminal-emulator* -1. Introduction |nvim-terminal-emulator-introduction| -2. Spawning |nvim-terminal-emulator-spawning| -3. Input |nvim-terminal-emulator-input| -4. Configuration |nvim-terminal-emulator-configuration| +1. Introduction |terminal-emulator-intro| +2. Spawning |terminal-emulator-spawning| +3. Input |terminal-emulator-input| +4. Configuration |terminal-emulator-configuration| +5. Status Variables |terminal-emulator-status| ============================================================================== -1. Introduction *nvim-terminal-emulator-introduction* +1. Introduction *terminal-emulator-intro* -One feature that distinguishes Nvim from Vim is that it implements a mostly -complete VT220/xterm-like terminal emulator. The terminal is presented to the -user as a special buffer type, one that is asynchronously updated to mirror -the virtual terminal display as data is received from the program connected -to it. For most purposes, terminal buffers behave a lot like normal buffers -with 'nomodifiable' set. +Nvim offers a mostly complete VT220/xterm terminal emulator. The terminal is +presented as a special buffer type, asynchronously updated to mirror the +virtual terminal display as data is received from the program connected to it. +For most purposes, terminal buffers behave a lot like normal buffers with +'nomodifiable' set. - -The implementation is powered by libvterm[1], a powerful abstract terminal -emulation library. - -[1]: http://www.leonerd.org.uk/code/libvterm/ +The implementation is powered by libvterm, a powerful abstract terminal +emulation library. http://www.leonerd.org.uk/code/libvterm/ ============================================================================== -2. Spawning *nvim-terminal-emulator-spawning* +2. Spawning *terminal-emulator-spawning* There are 3 ways to create a terminal buffer: @@ -37,16 +34,22 @@ There are 3 ways to create a terminal buffer: - By editing a file with a name matching `term://(.{-}//(\d+:)?)?\zs.*`. For example: > - :e term://bash - :vsp term://top + :edit term://bash + :vsplit term://top < + Note: The "term://" pattern is handled by a BufReadCmd handler, so the + |autocmd-nested| modifier is required to use it in an autocmd. > + autocmd VimEnter * nested split term://sh +< This is only mentioned for reference; you should use the |:terminal| + command instead. + When the terminal spawns the program, the buffer will start to mirror the terminal display and change its name to `term://$CWD//$PID:$COMMAND`. Note that |:mksession| will "save" the terminal buffers by restarting all programs when the session is restored. ============================================================================== -3. Input *nvim-terminal-emulator-input* +3. Input *terminal-emulator-input* Sending input is possible by entering terminal mode, which is achieved by pressing any key that would enter insert mode in a normal buffer (|i| or |a| @@ -90,7 +93,7 @@ Mouse input is also fully supported, and has the following behavior: the terminal wont lose focus and the hovered window will be scrolled. ============================================================================== -4. Configuration *nvim-terminal-emulator-configuration* +4. Configuration *terminal-emulator-configuration* Terminal buffers can be customized through the following global/buffer-local variables (set via the |TermOpen| autocmd): @@ -111,4 +114,25 @@ The terminal cursor can be highlighted via |hl-TermCursor| and |hl-TermCursorNC|. ============================================================================== +5. Status Variables *terminal-emulator-status* + +Terminal buffers maintain some information about the terminal in buffer-local +variables: + +- *b:term_title* The settable title of the terminal, typically displayed in + the window title or tab title of a graphical terminal emulator. Programs + running in the terminal can set this title via an escape sequence. +- *b:terminal_job_id* The nvim job ID of the job running in the terminal. See + |job-control| for more information. +- *b:terminal_job_pid* The PID of the top-level process running in the + terminal. + +These variables will have a value by the time the TermOpen autocmd runs, and +will continue to have a value for the lifetime of the terminal buffer, making +them suitable for use in 'statusline'. For example, to show the terminal title +as the status line: +> + :autocmd TermOpen * setlocal statusline=%{b:term_title} +< +============================================================================== vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 83ae96a651..97d56af369 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -1,4 +1,4 @@ -*options.txt* For Vim version 7.4. Last change: 2016 Jan 03 +*options.txt* For Vim version 7.4. Last change: 2016 Jul 12 VIM REFERENCE MANUAL by Bram Moolenaar @@ -52,7 +52,6 @@ achieve special effects. These options come in three forms: :se[t] all& Set all options to their default value. The values of these options are not changed: 'columns' - 'encoding' 'lines' Warning: This may have a lot of side effects. @@ -247,10 +246,10 @@ global value, which is used for new buffers. With ":set" both the local and global value is changed. With "setlocal" only the local value is changed, thus this value is not used when editing a new buffer. -When editing a buffer that has been edited before, the last used window -options are used again. If this buffer has been edited in this window, the -values from back then are used. Otherwise the values from the window where -the buffer was edited last are used. +When editing a buffer that has been edited before, the options from the window +that was last closed are used again. If this buffer has been edited in this +window, the values from back then are used. Otherwise the values from the +last closed window where the buffer was edited last are used. It's possible to set a local window option specifically for a type of buffer. When you edit another buffer in the same window, you don't want to keep @@ -497,6 +496,7 @@ For example, to use a modeline only for Vim 7.0: To use a modeline for Vim after version 7.2: /* vim>702: set cole=2: */ ~ There can be no blanks between "vim" and the ":". +The modeline is ignored if {vers} does not fit in an integer. {Nvim} The number of lines that are checked can be set with the 'modelines' option. @@ -614,7 +614,6 @@ A jump table for the options with a short description can be found at |Q_op|. global {only available when compiled with the |+multi_byte| feature} - Only effective when 'encoding' is "utf-8" or another Unicode encoding. Tells Vim what to do with characters with East Asian Width Class Ambiguous (such as Euro, Registered Sign, Copyright Sign, Greek letters, Cyrillic letters). @@ -667,7 +666,6 @@ A jump table for the options with a short description can be found at |Q_op|. - Set the 'keymap' option to "arabic"; in Insert mode CTRL-^ toggles between typing English and Arabic key mapping. - Set the 'delcombine' option - Note that 'encoding' must be "utf-8" for working with Arabic text. Resetting this option will: - Reset the 'rightleft' option. @@ -899,7 +897,7 @@ A jump table for the options with a short description can be found at |Q_op|. - The backup file will be created in the first directory in the list where this is possible. The directory must exist, Vim will not create it for you. - - Empty means that no backup file will be created ( 'patchmode' is + - Empty means that no backup file will be created ('patchmode' is impossible!). Writing may fail because of this. - A directory "." means to put the backup file in the same directory as the edited file. @@ -1077,8 +1075,7 @@ A jump table for the options with a short description can be found at |Q_op|. {not available when compiled without the |+linebreak| feature} This option lets you choose which characters might cause a line - break if 'linebreak' is on. Only works for ASCII and also for 8-bit - characters when 'encoding' is an 8-bit encoding. + break if 'linebreak' is on. Only works for ASCII characters. *'breakindent'* *'bri'* 'breakindent' 'bri' boolean (default off) @@ -1158,22 +1155,14 @@ A jump table for the options with a short description can be found at |Q_op|. *'buftype'* *'bt'* *E382* 'buftype' 'bt' string (default: "") local to buffer - {not available when compiled without the |+quickfix| - feature} The value of this option specifies the type of a buffer: <empty> normal buffer - nofile buffer which is not related to a file and will not be - written - nowrite buffer which will not be written - acwrite buffer which will always be written with BufWriteCmd - autocommands. - quickfix quickfix buffer, contains list of errors |:cwindow| - or list of locations |:lwindow| - help help buffer (you are not supposed to set this - manually) - terminal terminal buffer, this is set automatically when a - terminal is created. See |nvim-terminal-emulator| for - more information. + acwrite buffer will always be written with |BufWriteCmd|s + help help buffer (do not set this manually) + nofile buffer is not related to a file, will not be written + nowrite buffer will not be written + quickfix list of errors |:cwindow| or locations |:lwindow| + terminal |terminal-emulator| buffer This option is used together with 'bufhidden' and 'swapfile' to specify special kinds of buffers. See |special-buffers|. @@ -1214,11 +1203,9 @@ A jump table for the options with a short description can be found at |Q_op|. Specifies details about changing the case of letters. It may contain these words, separated by a comma: internal Use internal case mapping functions, the current - locale does not change the case mapping. This only - matters when 'encoding' is a Unicode encoding, - "latin1" or "iso-8859-15". When "internal" is - omitted, the towupper() and towlower() system library - functions are used when available. + locale does not change the case mapping. When + "internal" is omitted, the towupper() and towlower() + system library functions are used when available. keepascii For the ASCII characters (0x00 to 0x7f) use the US case mapping, the current locale is not effective. This probably only matters for Turkish. @@ -1251,8 +1238,8 @@ A jump table for the options with a short description can be found at |Q_op|. Only non-printable keys are allowed. The key can be specified as a single character, but it is difficult to type. The preferred way is to use the <> notation. Examples: > - :set cedit=<C-Y> - :set cedit=<Esc> + :exe "set cedit=\<C-Y>" + :exe "set cedit=\<Esc>" < |Nvi| also has this option, but it only uses the first character. See |cmdwin|. @@ -1271,13 +1258,12 @@ A jump table for the options with a short description can be found at |Q_op|. file to convert from. You will have to save the text in a file first. The expression must return zero or an empty string for success, non-zero for failure. - The possible encoding names encountered are in 'encoding'. + See |encoding-names| for possible encoding names. Additionally, names given in 'fileencodings' and 'fileencoding' are used. Conversion between "latin1", "unicode", "ucs-2", "ucs-4" and "utf-8" is done internally by Vim, 'charconvert' is not used for this. - 'charconvert' is also used to convert the shada file, if 'encoding' is - not "utf-8". Also used for Unicode conversion. + Also used for Unicode conversion. Example: > set charconvert=CharConvert() fun CharConvert() @@ -1292,8 +1278,6 @@ A jump table for the options with a short description can be found at |Q_op|. v:fname_in name of the input file v:fname_out name of the output file Note that v:fname_in and v:fname_out will never be the same. - Note that v:charconvert_from and v:charconvert_to may be different - from 'encoding'. Vim internally uses UTF-8 instead of UCS-2 or UCS-4. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. @@ -1353,7 +1337,7 @@ A jump table for the options with a short description can be found at |Q_op|. used regardless of whether "unnamed" is in 'clipboard' or not. The clipboard register can always be explicitly accessed using the "* notation. Also see - |gui-clipboard|. + |clipboard|. *clipboard-unnamedplus* unnamedplus A variant of the "unnamed" flag which uses the @@ -1363,7 +1347,7 @@ A jump table for the options with a short description can be found at |Q_op|. register. When "unnamed" is also included to the option, yank and delete operations (but not put) will additionally copy the text into register - '*'. See |nvim-clipboard|. + '*'. See |clipboard|. *clipboard-autoselect* autoselect Works like the 'a' flag in 'guioptions': If present, @@ -1450,9 +1434,6 @@ A jump table for the options with a short description can be found at |Q_op|. comment text. Currently only used to add markers for folding, see |fold-marker|. - *'compatible'* *'cp'* *'nocompatible'* *'nocp'* -'compatible' 'cp' Removed. |vim-differences| {Nvim} - *'complete'* *'cpt'* *E535* 'complete' 'cpt' string (default: ".,w,b,u,t") local to buffer @@ -1460,7 +1441,7 @@ A jump table for the options with a short description can be found at |Q_op|. when CTRL-P or CTRL-N are used. It is also used for whole-line completion |i_CTRL-X_CTRL-L|. It indicates the type of completion and the places to scan. It is a comma separated list of flags: - . scan the current buffer ( 'wrapscan' is ignored) + . scan the current buffer ('wrapscan' is ignored) w scan buffers from other windows b scan other loaded buffers that are in the buffer list u scan the unloaded buffers that are in the buffer list @@ -1602,7 +1583,7 @@ A jump table for the options with a short description can be found at |Q_op|. line, the remaining space is filled in the normal manner. See 'preserveindent'. - *'cpoptions'* *'cpo'* + *'cpoptions'* *'cpo'* *cpo* 'cpoptions' 'cpo' string (Vim default: "aABceFs", Vi default: all flags) global @@ -1849,9 +1830,6 @@ A jump table for the options with a short description can be found at |Q_op|. the cursor would skip over it and jump to the following occurrence. - *'cryptmethod'* *'cm'* -'cryptmethod' Removed. |vim-differences| {Nvim} - *'cscopepathcomp'* *'cspc'* 'cscopepathcomp' 'cspc' number (default 0) global @@ -2117,11 +2095,17 @@ A jump table for the options with a short description can be found at |Q_op|. Change the way text is displayed. This is comma separated list of flags: lastline When included, as much as possible of the last line - in a window will be displayed. When not included, a - last line that doesn't fit is replaced with "@" lines. + in a window will be displayed. "@@@" is put in the + last columns of the last screen line to indicate the + rest of the line is not displayed. + truncate Like "lastline", but "@@@" is displayed in the first + column of the last screen line. Overrules "lastline". uhex Show unprintable characters hexadecimal as <xx> instead of using ^C and ~C. + When neither "lastline" or "truncate" is included, a last line that + doesn't fit is replaced with "@" lines. + *'eadirection'* *'ead'* 'eadirection' 'ead' string (default "both") global @@ -2130,48 +2114,24 @@ A jump table for the options with a short description can be found at |Q_op|. hor horizontally, height of windows is not affected both width and height of windows is affected - *'ed'* *'edcompatible'* *'noed'* *'noedcompatible'* -'edcompatible' 'ed' Removed. |vim-differences| {Nvim} - - *'encoding'* *'enc'* *E543* -'encoding' 'enc' string (default: "utf-8") + *'emoji'* *'emo'* +'emoji' 'emo' boolean (default: on) global + {not in Vi} {only available when compiled with the |+multi_byte| feature} - Sets the character encoding used inside Vim. It applies to text in - the buffers, registers, Strings in expressions, text stored in the - shada file, etc. It sets the kind of characters which Vim can work - with. See |encoding-names| for the possible values. + When on all Unicode emoji characters are considered to be full width. - 'encoding' cannot be changed after startup, because (1) it causes - non-ASCII text inside Vim to become invalid, and (2) it complicates - runtime logic. The recommended 'encoding' is "utf-8". Remote plugins - and GUIs only support utf-8. See |multibyte|. - The character encoding of files can be different from 'encoding'. + *'encoding'* *'enc'* *E543* +'encoding' 'enc' Removed. |vim-differences| {Nvim} + Nvim always uses UTF-8 internally. RPC communication + (remote plugins/GUIs) must use UTF-8 strings. + + The character encoding of files can be different than UTF-8. This is specified with 'fileencoding'. The conversion is done with iconv() or as specified with 'charconvert'. - If you need to know whether 'encoding' is a multi-byte encoding, you - can use: > - if has("multi_byte_encoding") -< - When you set this option, it fires the |EncodingChanged| autocommand - event so that you can set up fonts if necessary. - - When the option is set, the value is converted to lowercase. Thus - you can set it with uppercase values too. Underscores are translated - to '-' signs. - When the encoding is recognized, it is changed to the standard name. - For example "Latin-1" becomes "latin1", "ISO_88592" becomes - "iso-8859-2" and "utf8" becomes "utf-8". - - When "unicode", "ucs-2" or "ucs-4" is used, Vim internally uses utf-8. - You don't notice this while editing, but it does matter for the - |shada-file|. And Vim expects the terminal to use utf-8 too. Thus - setting 'encoding' to one of these values instead of utf-8 only has - effect for encoding used for files when 'fileencoding' is empty. - *'endofline'* *'eol'* *'noendofline'* *'noeol'* 'endofline' 'eol' boolean (default on) local to buffer @@ -2298,20 +2258,14 @@ A jump table for the options with a short description can be found at |Q_op|. feature} Sets the character encoding for the file of this buffer. - When 'fileencoding' is different from 'encoding', conversion will be + When 'fileencoding' is different from "utf-8", conversion will be done when writing the file. For reading see below. - When 'fileencoding' is empty, the same value as 'encoding' will be - used (no conversion when reading or writing a file). - Conversion will also be done when 'encoding' and 'fileencoding' are - both a Unicode encoding and 'fileencoding' is not utf-8. That's - because internally Unicode is always stored as utf-8. - WARNING: Conversion can cause loss of information! When - 'encoding' is "utf-8" or another Unicode encoding, conversion - is most likely done in a way that the reverse conversion - results in the same text. When 'encoding' is not "utf-8" some - characters may be lost! - - See 'encoding' for the possible values. Additionally, values may be + When 'fileencoding' is empty, the file will be saved with utf-8 + encoding. (no conversion when reading or writing a file). + WARNING: Conversion to a non-Unicode encoding can cause loss of + information! + + See |encoding-names| for the possible values. Additionally, values may be specified that can be handled by the converter, see |mbyte-conversion|. @@ -2324,8 +2278,8 @@ A jump table for the options with a short description can be found at |Q_op|. Prepending "8bit-" and "2byte-" has no meaning here, they are ignored. When the option is set, the value is converted to lowercase. Thus you can set it with uppercase values too. '_' characters are - replaced with '-'. If a name is recognized from the list for - 'encoding', it is replaced by the standard name. For example + replaced with '-'. If a name is recognized from the list at + |encoding-names|, it is replaced by the standard name. For example "ISO8859-2" becomes "iso-8859-2". When this option is set, after starting to edit a file, the 'modified' @@ -2338,11 +2292,6 @@ A jump table for the options with a short description can be found at |Q_op|. This option can not be changed when 'modifiable' is off. - *'fe'* - NOTE: Before version 6.0 this option specified the encoding for the - whole of Vim, this was a mistake. Now use 'encoding' instead. The - old short name was 'fe', which is no longer used. - *'fileencodings'* *'fencs'* 'fileencodings' 'fencs' string (default: "ucs-bom,utf-8,default,latin1") global @@ -2353,12 +2302,8 @@ A jump table for the options with a short description can be found at |Q_op|. mentioned character encoding. If an error is detected, the next one in the list is tried. When an encoding is found that works, 'fileencoding' is set to it. If all fail, 'fileencoding' is set to - an empty string, which means the value of 'encoding' is used. - WARNING: Conversion can cause loss of information! When - 'encoding' is "utf-8" (or one of the other Unicode variants) - conversion is most likely done in a way that the reverse - conversion results in the same text. When 'encoding' is not - "utf-8" some non-ASCII characters may be lost! You can use + an empty string, which means that UTF-8 is used. + WARNING: Conversion can cause loss of information! You can use the |++bad| argument to specify what is done with characters that can't be converted. For an empty file or a file with only ASCII characters most encodings @@ -2384,11 +2329,11 @@ A jump table for the options with a short description can be found at |Q_op|. because Vim cannot detect an error, thus the encoding is always accepted. The special value "default" can be used for the encoding from the - environment. It is useful when 'encoding' is set to "utf-8" and - your environment uses a non-latin1 encoding, such as Russian. - When 'encoding' is "utf-8" and a file contains an illegal byte - sequence it won't be recognized as UTF-8. You can use the |8g8| - command to find the illegal byte sequence. + environment. It is useful when your environment uses a non-latin1 + encoding, such as Russian. + When a file contains an illegal UTF-8 byte sequence it won't be + recognized as "utf-8". You can use the |8g8| command to find the + illegal byte sequence. WRONG VALUES: WHAT'S WRONG: latin1,utf-8 "latin1" will always be used utf-8,ucs-bom,latin1 BOM won't be recognized in an utf-8 @@ -2459,8 +2404,8 @@ A jump table for the options with a short description can be found at |Q_op|. file only, the option is not changed. When 'binary' is set, the value of 'fileformats' is not used. - Note that when Vim starts up with an empty buffer this option is not - used. Set 'fileformat' in your vimrc instead. + When Vim starts up with an empty buffer the first item is used. You + can overrule this by setting 'fileformat' in your .vimrc. For systems with a Dos-like <EOL> (<CR><NL>), when reading files that are ":source"ed and for vimrc files, automatic <EOL> detection may be @@ -2515,17 +2460,17 @@ A jump table for the options with a short description can be found at |Q_op|. item default Used for ~ stl:c ' ' or '^' statusline of the current window - stlnc:c ' ' or '-' statusline of the non-current windows + stlnc:c ' ' or '=' statusline of the non-current windows vert:c '|' vertical separators |:vsplit| fold:c '-' filling 'foldtext' diff:c '-' deleted lines of the 'diff' option Any one that is omitted will fall back to the default. For "stl" and - "stlnc" the space will be used when there is highlighting, '^' or '-' + "stlnc" the space will be used when there is highlighting, '^' or '=' otherwise. Example: > - :set fillchars=stl:^,stlnc:-,vert:\|,fold:-,diff:- + :set fillchars=stl:^,stlnc:=,vert:\|,fold:-,diff:- < This is similar to the default, except that these characters will also be used when there is highlighting. @@ -2737,6 +2682,40 @@ A jump table for the options with a short description can be found at |Q_op|. It is not allowed to change text or jump to another window while evaluating 'foldtext' |textlock|. + *'formatexpr'* *'fex'* +'formatexpr' 'fex' string (default "") + local to buffer + {not available when compiled without the |+eval| + feature} + Expression which is evaluated to format a range of lines for the |gq| + operator or automatic formatting (see 'formatoptions'). When this + option is empty 'formatprg' is used. + + The |v:lnum| variable holds the first line to be formatted. + The |v:count| variable holds the number of lines to be formatted. + The |v:char| variable holds the character that is going to be + inserted if the expression is being evaluated due to + automatic formatting. This can be empty. Don't insert + it yet! + + Example: > + :set formatexpr=mylang#Format() +< This will invoke the mylang#Format() function in the + autoload/mylang.vim file in 'runtimepath'. |autoload| + + The expression is also evaluated when 'textwidth' is set and adding + text beyond that limit. This happens under the same conditions as + when internal formatting is used. Make sure the cursor is kept in the + same spot relative to the text then! The |mode()| function will + return "i" or "R" in this situation. + + When the expression evaluates to non-zero Vim will fall back to using + the internal format mechanism. + + The expression will be evaluated in the |sandbox| when set from a + modeline, see |sandbox-option|. That stops the option from working, + since changing the buffer text is not allowed. + *'formatoptions'* *'fo'* 'formatoptions' 'fo' string (default: "tcqj", Vi default: "vt") local to buffer @@ -2775,40 +2754,6 @@ A jump table for the options with a short description can be found at |Q_op|. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. - *'formatexpr'* *'fex'* -'formatexpr' 'fex' string (default "") - local to buffer - {not available when compiled without the |+eval| - feature} - Expression which is evaluated to format a range of lines for the |gq| - operator or automatic formatting (see 'formatoptions'). When this - option is empty 'formatprg' is used. - - The |v:lnum| variable holds the first line to be formatted. - The |v:count| variable holds the number of lines to be formatted. - The |v:char| variable holds the character that is going to be - inserted if the expression is being evaluated due to - automatic formatting. This can be empty. Don't insert - it yet! - - Example: > - :set formatexpr=mylang#Format() -< This will invoke the mylang#Format() function in the - autoload/mylang.vim file in 'runtimepath'. |autoload| - - The expression is also evaluated when 'textwidth' is set and adding - text beyond that limit. This happens under the same conditions as - when internal formatting is used. Make sure the cursor is kept in the - same spot relative to the text then! The |mode()| function will - return "i" or "R" in this situation. - - When the expression evaluates to non-zero Vim will fall back to using - the internal format mechanism. - - The expression will be evaluated in the |sandbox| when set from a - modeline, see |sandbox-option|. That stops the option from working, - since changing the buffer text is not allowed. - *'fsync'* *'fs'* 'fsync' 'fs' boolean (default on) global @@ -3047,8 +2992,7 @@ A jump table for the options with a short description can be found at |Q_op|. Note: The size of these fonts must be exactly twice as wide as the one specified with 'guifont' and the same height. - 'guifontwide' is only used when 'encoding' is set to "utf-8" and - 'guifontset' is empty or invalid. + 'guifontwide' is only used when 'guifontset' is empty or invalid. When 'guifont' is set and a valid font is found in it and 'guifontwide' is empty Vim will attempt to find a matching double-width font and set 'guifontwide' to it. @@ -3097,7 +3041,7 @@ A jump table for the options with a short description can be found at |Q_op|. The same applies to the modeless selection. *'go-P'* 'P' Like autoselect but using the "+ register instead of the "* - register. + register. *'go-A'* 'A' Autoselect for the modeless selection. Like 'a', but only applies to the modeless selection. @@ -3165,9 +3109,6 @@ A jump table for the options with a short description can be found at |Q_op|. removing it after the GUI has started has no effect. - *'guipty'* *'noguipty'* -'guipty' Removed. |vim-differences| {Nvim} - *'guitablabel'* *'gtl'* 'guitablabel' 'gtl' string (default empty) global @@ -3328,8 +3269,6 @@ A jump table for the options with a short description can be found at |Q_op|. - no highlighting : use a highlight group The default is used for occasions that are not included. - If you want to change what the display modes do, see |dos-colors| - for an example. When using the ':' display mode, this must be followed by the name of a highlight group. A highlight group can be used to define any type of highlighting, including using color. See |:highlight| on how to @@ -3414,12 +3353,6 @@ A jump table for the options with a short description can be found at |Q_op|. Can be overruled by using "\c" or "\C" in the pattern, see |/ignorecase|. - *'imactivatefunc'* *'imaf'* -'imactivatefunc' 'imaf' Removed. |vim-differences| {Nvim} - - *'imactivatekey'* *'imak'* -'imactivatekey' 'imak' Removed. |vim-differences| {Nvim} - *'imcmdline'* *'imc'* *'noimcmdline'* *'noimc'* 'imcmdline' 'imc' boolean (default off) global @@ -3476,8 +3409,17 @@ A jump table for the options with a short description can be found at |Q_op|. The value is set to 1 when it is not -1 and setting the 'keymap' option to a valid keymap name. - *'imstatusfunc'* *'imsf'* -'imstatusfunc' 'imsf' Removed. |vim-differences| {Nvim} + *'inccommand'* *'icm'* +'inccommand' 'icm' string (default "") + global + + "nosplit": Shows the effects of a command incrementally, as you type. + "split" : Also shows partial off-screen results in a preview window. + + Works for |:substitute|, |:smagic|, |:snomagic|. |hl-Substitute| + + If the preview is too slow (exceeds 'redrawtime') then 'inccommand' is + automatically disabled until |Command-line-mode| is done. *'include'* *'inc'* 'include' 'inc' string (default "^\s*#\s*include") @@ -3696,6 +3638,8 @@ A jump table for the options with a short description can be found at |Q_op|. '*', '"' and '|' (so that CTRL-] on a command finds the help for that command). When the 'lisp' option is on the '-' character is always included. + This option also influences syntax highlighting, unless the syntax + uses |:syn-iskeyword|. *'isprint'* *'isp'* 'isprint' 'isp' string (default: "@,161-255") @@ -3713,7 +3657,7 @@ A jump table for the options with a short description can be found at |Q_op|. 128 - 159 "~@" - "~_" 160 - 254 "| " - "|~" 255 "~?" - When 'encoding' is a Unicode one, illegal bytes from 128 to 255 are + Illegal bytes from 128 to 255 (invalid UTF-8) are displayed as <xx>, with the hexadecimal value of the byte. When 'display' contains "uhex" all unprintable characters are displayed as <xx>. @@ -3733,9 +3677,6 @@ A jump table for the options with a short description can be found at |Q_op|. Insert two spaces after a '.', '?' and '!' with a join command. Otherwise only one space is inserted. - *'key'* -'key' Removed. |vim-differences| {Nvim} - *'keymap'* *'kmp'* *E544* 'keymap' 'kmp' string (default "") local to buffer @@ -3960,6 +3901,7 @@ A jump table for the options with a short description can be found at |Q_op|. global Strings to use in 'list' mode and for the |:list| command. It is a comma separated list of string settings. + *lcs-eol* eol:c Character to show at the end of each line. When omitted, there is no extra character at the end of the @@ -3994,8 +3936,7 @@ A jump table for the options with a short description can be found at |Q_op|. omitted. The characters ':' and ',' should not be used. UTF-8 characters can - be used when 'encoding' is "utf-8", otherwise only printable - characters are allowed. All characters must be single width. + be used. All characters must be single width. Examples: > :set lcs=tab:>-,trail:- @@ -4014,9 +3955,6 @@ A jump table for the options with a short description can be found at |Q_op|. Note that using the "-u NONE" and "--noplugin" command line arguments reset this option. |-u| |--noplugin| - *'macatsui'* *'nomacatsui'* -'macatsui' Removed. |vim-differences| {Nvim} - *'magic'* *'nomagic'* 'magic' boolean (default on) global @@ -4095,7 +4033,6 @@ A jump table for the options with a short description can be found at |Q_op|. {only available when compiled with the |+multi_byte| feature} The maximum number of combining characters supported for displaying. - Only used when 'encoding' is "utf-8". The default is OK for most languages. Hebrew may require 4. Maximum value is 6. Even when this option is set to 2 you can still edit text with more @@ -4239,6 +4176,7 @@ A jump table for the options with a short description can be found at |Q_op|. written. A ":set nomodified" command also resets the original values to the current values and the 'modified' option will be reset. + Similarly for 'eol' and 'bomb'. This option is not set when a change is made to the buffer as the result of a BufNewFile, BufRead/BufReadPost, BufWritePost, FileAppendPost or VimLeave autocommand event. See |gzip-example| for @@ -4399,9 +4337,8 @@ A jump table for the options with a short description can be found at |Q_op|. *'mousetime'* *'mouset'* 'mousetime' 'mouset' number (default 500) global - Only for GUI, Windows and Unix with xterm. Defines the maximum - time in msec between two mouse clicks for the second click to be - recognized as a multi click. + Defines the maximum time in msec between two mouse clicks for the + second click to be recognized as a multi click. *'nrformats'* *'nf'* 'nrformats' 'nf' string (default "bin,hex") @@ -4411,7 +4348,7 @@ A jump table for the options with a short description can be found at |Q_op|. respectively; see |CTRL-A| for more info on these commands. alpha If included, single alphabetical characters will be incremented or decremented. This is useful for a list with a - letter index a), b), etc. *octal-nrformats* + letter index a), b), etc. *octal-nrformats* octal If included, numbers that start with a zero will be considered to be octal. Example: Using CTRL-A on "007" results in "010". hex If included, numbers starting with "0x" or "0X" will be @@ -4441,7 +4378,7 @@ A jump table for the options with a short description can be found at |Q_op|. relative to the cursor. Together with 'number' there are these four combinations (cursor in line 3): - 'nonu' 'nu' 'nonu' 'nu' + 'nonu' 'nu' 'nonu' 'nu' 'nornu' 'nornu' 'rnu' 'rnu' |apple | 1 apple | 2 apple | 2 apple @@ -4500,6 +4437,12 @@ A jump table for the options with a short description can be found at |Q_op|. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. + *'packpath'* *'pp'* +'packpath' 'pp' string (default: see 'runtimepath') + {not in Vi} + Directories used to find packages. See |packages|. + + *'paragraphs'* *'para'* 'paragraphs' 'para' string (default "IPLPPPQPP TPHPLIPpLpItpplpipbp") global @@ -4793,8 +4736,8 @@ A jump table for the options with a short description can be found at |Q_op|. global {only available when compiled with the |+reltime| feature} - The time in milliseconds for redrawing the display. This applies to - searching for patterns for 'hlsearch' and |:match| highlighting. + Time in milliseconds for redrawing the display. Applies to + 'hlsearch', 'inccommand' and |:match| highlighting. When redrawing takes more than this many milliseconds no further matches will be highlighted. This is used to avoid that Vim hangs when using a very complicated pattern. @@ -4854,9 +4797,6 @@ A jump table for the options with a short description can be found at |Q_op|. For the ":substitute" command the number of substitutions is used instead of the number of lines. - *'restorescreen'* *'rs'* *'norestorescreen'* *'nors'* -'restorescreen' 'rs' Removed. |vim-differences| {Nvim} - *'revins'* *'ri'* *'norevins'* *'nori'* 'revins' 'ri' boolean (default off) global @@ -4937,7 +4877,7 @@ A jump table for the options with a short description can be found at |Q_op|. $XDG_CONFIG_DIRS[1]/nvim, $XDG_CONFIG_DIRS[2]/nvim, … - $XDG_DATA_HOME/nvim, + $XDG_DATA_HOME/nvim/site, $XDG_DATA_DIRS[1]/nvim/site, $XDG_DATA_DIRS[2]/nvim/site, … @@ -4945,7 +4885,7 @@ A jump table for the options with a short description can be found at |Q_op|. … $XDG_DATA_DIRS[2]/nvim/site/after, $XDG_DATA_DIRS[1]/nvim/site/after, - $XDG_DATA_HOME/nvim/after, + $XDG_DATA_HOME/nvim/site/after, … $XDG_CONFIG_DIRS[2]/nvim/after, $XDG_CONFIG_DIRS[1]/nvim/after, @@ -4964,6 +4904,7 @@ A jump table for the options with a short description can be found at |Q_op|. keymap/ key mapping files |mbyte-keymap| lang/ menu translations |:menutrans| menu.vim GUI menus |menu.vim| + pack/ packages |:packadd| plugin/ plugin scripts |write-plugin| print/ files for printing |postscript-print-encoding| spell/ spell checking files |spell| @@ -4990,6 +4931,8 @@ 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|. + Note that, unlike 'path', no wildcards like "**" are allowed. Normal wildcards are allowed, but can significantly slow down searching for runtime files. For speed, use as few items as possible and avoid @@ -5257,10 +5200,10 @@ A jump table for the options with a short description can be found at |Q_op|. has been used since the last search command. *shada-n* n Name of the shada file. The name must immediately follow - the 'n'. Must be the last one! If the "-i" argument was - given when starting Vim, that file name overrides the one - given here with 'shada'. Environment variables are expanded - when opening the file, not when setting the option. + the 'n'. Must be at the end of the option! If the "-i" + argument was given when starting Vim, that file name overrides + the one given here with 'shada'. Environment variables are + expanded when opening the file, not when setting the option. *shada-r* r Removable media. The argument is a string (up to the next ','). This parameter can be given several times. Each @@ -5466,6 +5409,7 @@ A jump table for the options with a short description can be found at |Q_op|. The |FilterReadPre|, |FilterReadPost| and |FilterWritePre|, |FilterWritePost| autocommands event are not triggered when 'shelltemp' is off. + |system()| does not respect this option, it always uses pipes. *'shellxescape'* *'sxe'* 'shellxescape' 'sxe' string (default: ""; @@ -5564,9 +5508,6 @@ A jump table for the options with a short description can be found at |Q_op|. shm=a Abbreviation, but no loss of information. shm=at Abbreviation, and truncate message when necessary. - *'shortname'* *'sn'* *'noshortname'* *'nosn'* -'shortname' 'sn' Removed. |vim-differences| {Nvim} - *'showbreak'* *'sbr'* *E595* 'showbreak' 'sbr' string (default "") global @@ -5683,10 +5624,18 @@ A jump table for the options with a short description can be found at |Q_op|. Example: Try this together with 'sidescroll' and 'listchars' as in the following example to never allow the cursor to move - onto the "extends" character: + onto the "extends" character: > :set nowrap sidescroll=1 listchars=extends:>,precedes:< :set sidescrolloff=1 +< + *'signcolumn'* *'scl'* +'signcolumn' 'scl' string (default "auto") + local to window + Whether or not to draw the signcolumn. Valid values are: + "auto" only when there is a sign to display + "no" never + "yes" always *'smartcase'* *'scs'* *'nosmartcase'* *'noscs'* @@ -5837,9 +5786,6 @@ A jump table for the options with a short description can be found at |Q_op|. (_xx is an underscore, two letters and followed by a non-letter). This is mainly for testing purposes. You must make sure the correct encoding is used, Vim doesn't check it. - When 'encoding' is set the word lists are reloaded. Thus it's a good - idea to set 'spelllang' after setting 'encoding' to avoid loading the - files twice. How the related spell files are found is explained here: |spell-load|. If the |spellfile.vim| plugin is active and you use a language name @@ -5955,7 +5901,7 @@ A jump table for the options with a short description can be found at |Q_op|. The option consists of printf style '%' items interspersed with normal text. Each status line item is of the form: %-0{minwid}.{maxwid}{item} - All fields except the {item} is optional. A single percent sign can + All fields except the {item} are optional. A single percent sign can be given as "%%". Up to 80 items can be specified. *E541* When the option starts with "%!" then it is used as an expression, @@ -6068,7 +6014,8 @@ A jump table for the options with a short description can be found at |Q_op|. feature use `has('tablineat')`. < - Where to truncate line if too long. Default is at the start. No width fields allowed. - = - Separation point between left and right aligned items. + = - Separation point between alignment sections. Each section will + be separated by an equal number of spaces. No width fields allowed. # - Set highlight group. The name must follow and then a # again. Thus use %#HLname# for highlight group HLname. The same @@ -6179,9 +6126,6 @@ A jump table for the options with a short description can be found at |Q_op|. This option is used together with 'bufhidden' and 'buftype' to specify special kinds of buffers. See |special-buffers|. - *'swapsync'* *'sws'* -'swapsync' 'sws' Removed. |vim-differences| {Nvim} - *'switchbuf'* *'swb'* 'switchbuf' 'swb' string (default "") global @@ -6405,9 +6349,6 @@ A jump table for the options with a short description can be found at |Q_op|. Resetting this option is useful when using a ":tag" command in a mapping which should not change the tagstack. - *'term'* *E529* *E530* *E531* -'term' Removed. |vim-differences| {Nvim} - *'termbidi'* *'tbidi'* *'notermbidi'* *'notbidi'* 'termbidi' 'tbidi' boolean (default off) @@ -6421,9 +6362,6 @@ A jump table for the options with a short description can be found at |Q_op|. 'arabicshape' is ignored, but 'rightleft' isn't changed automatically. For further details see |arabic.txt|. - *'termencoding'* *'tenc'* -'termencoding' 'tenc' Removed. |vim-differences| {Nvim} - *'termguicolors'* *'tgc'* 'termguicolors' 'tgc' boolean (default off) global @@ -6461,6 +6399,7 @@ A jump table for the options with a short description can be found at |Q_op|. non-keyword characters (white space is preferred). Maximum line length is 510 bytes. To obtain a file to be used here, check out this ftp site: + [Sorry this link doesn't work anymore, do you know the right one?] ftp://ftp.ox.ac.uk/pub/wordlists/ First get the README file. To include a comma in a file name precede it with a backslash. Spaces after a comma are ignored, otherwise spaces are included in the file @@ -6577,28 +6516,10 @@ A jump table for the options with a short description can be found at |Q_op|. to be garbled (e.g., when it contains a CR or NL character). {not available when compiled without the |+statusline| feature} - *'toolbar'* *'tb'* -'toolbar' 'tb' Removed. |vim-differences| {Nvim} - - *'toolbariconsize'* *'tbis'* -'toolbariconsize' 'tbis' Removed. |vim-differences| {Nvim} - - *'ttybuiltin'* *'tbi'* *'nottybuiltin'* *'notbi'* -'ttybuiltin' 'tbi' Removed. |vim-differences| {Nvim} - *'ttyfast'* *'tf'* *'nottyfast'* *'notf'* 'ttyfast' 'tf' Removed. |vim-differences| {Nvim} - *'ttymouse'* *'ttym'* -'ttymouse' 'ttym' Removed. |vim-differences| {Nvim} - - *'ttyscroll'* *'tsl'* -'ttyscroll' 'tsl' Removed. |vim-differences| {Nvim} - - *'ttytype'* *'tty'* -'ttytype' 'tty' Alias for 'term'. Removed. |vim-differences| {Nvim} - - *'undodir'* *'udir'* *E926* + *'undodir'* *'udir'* *E5003* 'undodir' 'udir' string (default "$XDG_DATA_HOME/nvim/undo") global {only when compiled with the |+persistent_undo| feature} @@ -6752,12 +6673,6 @@ A jump table for the options with a short description can be found at |Q_op|. with Unix. The Unix version of Vim cannot source dos format scripts, but the Windows version of Vim can source unix format scripts. - *'viminfo'* *'vi'* -'viminfo' 'vi' string - global - Deprecated alias for 'shada' option. Is kept for compatibility - reasons. - *'virtualedit'* *'ve'* 'virtualedit' 've' string (default "") global @@ -6803,9 +6718,6 @@ A jump table for the options with a short description can be found at |Q_op|. Give a warning message when a shell command is used while the buffer has been changed. - *'weirdinvert'* *'wiv'* *'noweirdinvert'* *'nowiv'* -'weirdinvert' 'wiv' Removed. |vim-differences| {Nvim} - *'whichwrap'* *'ww'* 'whichwrap' 'ww' string (Vim default: "b,s", Vi default: "") global @@ -7162,7 +7074,7 @@ A jump table for the options with a short description can be found at |Q_op|. *'writedelay'* *'wd'* 'writedelay' 'wd' number (default 0) global - The number of microseconds to wait for each character sent to the + The number of milliseconds to wait for each character sent to the screen. When non-zero, characters are sent to the terminal one by one. For debugging purposes. diff --git a/runtime/doc/os_win32.txt b/runtime/doc/os_win32.txt index 3c7ca4e36a..5dc276c9df 100644 --- a/runtime/doc/os_win32.txt +++ b/runtime/doc/os_win32.txt @@ -1,4 +1,4 @@ -*os_win32.txt* For Vim version 7.4. Last change: 2014 Sep 25 +*os_win32.txt* For Vim version 7.4. Last change: 2016 Mar 05 VIM REFERENCE MANUAL by George Reilly @@ -75,6 +75,31 @@ The directory of the Vim executable is appended to $PATH. This is mostly to make "!xxd" work, as it is in the Tools menu. And it also means that when executable() returns 1 the executable can actually be executed. +Quotes in file names *win32-quotes* + +Quotes inside a file name (or any other command line argument) can be escaped +with a backslash. E.g. > + vim -c "echo 'foo\"bar'" + +Alternatively use three quotes to get one: > + vim -c "echo 'foo"""bar'" + +The quotation rules are: + +1. A `"` starts quotation. +2. Another `"` or `""` ends quotation. If the quotation ends with `""`, a `"` + is produced at the end of the quoted string. + +Examples, with [] around an argument: + "foo" -> [foo] + "foo"" -> [foo"] + "foo"bar -> [foobar] + "foo" bar -> [foo], [bar] + "foo""bar -> [foo"bar] + "foo"" bar -> [foo"], [bar] + "foo"""bar" -> [foo"bar] + + ============================================================================== 3. Using the mouse *win32-mouse* diff --git a/runtime/doc/pattern.txt b/runtime/doc/pattern.txt index 5897f756d8..f3f5bcbd66 100644 --- a/runtime/doc/pattern.txt +++ b/runtime/doc/pattern.txt @@ -1,4 +1,4 @@ -*pattern.txt* For Vim version 7.4. Last change: 2016 Jan 03 +*pattern.txt* For Vim version 7.4. Last change: 2016 Jun 08 VIM REFERENCE MANUAL by Bram Moolenaar @@ -573,7 +573,7 @@ An atom can be followed by an indication of how many times the atom can be matched and in what way. This is called a multi. See |/multi| for an overview. - */star* */\star* *E56* + */star* */\star* * (use \* when 'magic' is not set) Matches 0 or more of the preceding atom, as many as possible. Example 'nomagic' matches ~ @@ -593,7 +593,7 @@ overview. the end of the file and then tries matching "END", backing up one character at a time. - */\+* *E57* + */\+* \+ Matches 1 or more of the preceding atom, as many as possible. Example matches ~ ^.\+$ any non-empty line @@ -608,7 +608,7 @@ overview. \? Just like \=. Cannot be used when searching backwards with the "?" command. - */\{* *E58* *E60* *E554* *E870* + */\{* *E60* *E554* *E870* \{n,m} Matches n to m of the preceding atom, as many as possible \{n} Matches n of the preceding atom \{n,} Matches at least n of the preceding atom, as many as possible @@ -947,14 +947,18 @@ $ At end of pattern or in front of "\|", "\)" or "\n" ('magic' on): < When 'hlsearch' is set and you move the cursor around and make changes this will clearly show when the match is updated or not. To match the text up to column 17: > - /.*\%17v -< Column 17 is included, because that's where the "\%17v" matches, - even though this is a |/zero-width| match. Adding a dot to match the - next character has the same result: > - /.*\%17v. + /^.*\%17v +< Column 17 is not included, because this is a |/zero-width| match. To + include the column use: > + /^.*\%17v. < This command does the same thing, but also matches when there is no character in column 17: > - /.*\%<18v. + /^.*\%<18v. +< Note that without the "^" to anchor the match in the first column, + this will also highlight column 17: > + /.*\%17v +< Column 17 is highlighted by 'hlsearch' because there is another match + where ".*" matches zero characters. < Character classes: @@ -1071,8 +1075,8 @@ x A single character, with no special meaning, matches itself belonging to that character class. The following character classes are supported: Name Contents ~ -*[:alnum:]* [:alnum:] letters and digits -*[:alpha:]* [:alpha:] letters +*[:alnum:]* [:alnum:] ASCII letters and digits +*[:alpha:]* [:alpha:] ASCII letters *[:blank:]* [:blank:] space and tab characters *[:cntrl:]* [:cntrl:] control characters *[:digit:]* [:digit:] decimal digits @@ -1080,7 +1084,7 @@ x A single character, with no special meaning, matches itself *[:lower:]* [:lower:] lowercase letters (all letters when 'ignorecase' is used) *[:print:]* [:print:] printable characters including space -*[:punct:]* [:punct:] punctuation characters +*[:punct:]* [:punct:] ASCII punctuation characters *[:space:]* [:space:] whitespace characters *[:upper:]* [:upper:] uppercase letters (all letters when 'ignorecase' is used) @@ -1096,8 +1100,9 @@ x A single character, with no special meaning, matches itself '/', alphabetic, numeric, '_' or '~'. These items only work for 8-bit characters, except [:lower:] and [:upper:] also work for multi-byte characters when using the new - regexp engine. In the future these items may work for multi-byte - characters. + regexp engine. See |two-engines|. In the future these items may + work for multi-byte characters. For now, to get all "alpha" + characters you can use: [[:lower:][:upper:]]. */[[=* *[==]* - An equivalence class. This means that characters are matched that have almost the same meaning, e.g., when ignoring accents. This diff --git a/runtime/doc/pi_health.txt b/runtime/doc/pi_health.txt new file mode 100644 index 0000000000..69833103d1 --- /dev/null +++ b/runtime/doc/pi_health.txt @@ -0,0 +1,127 @@ +*pi_health.txt* Healthcheck framework + +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| + +============================================================================== +Introduction *healthcheck* *health.vim-intro* + +Troubleshooting user configuration problems is a time-consuming task that +developers want to minimize. health.vim provides a simple framework for plugin +authors to hook into, and for users to invoke, to check and report the user's +configuration and environment. Type this command to try it: > + + :CheckHealth +< +For example, some users have broken or unusual Python setups, which breaks the +|:python| command. |:CheckHealth| detects several common Python configuration +problems and reports them. If the Neovim Python module is not installed, it +shows a warning: > + + You have not installed the Neovim Python module + You might want to try `pip install Neovim` +< +Plugin authors are encouraged to add healthchecks, see |health.vim-dev|. + +============================================================================== +Commands and functions *health.vim-manual* + +Commands +------------------------------------------------------------------------------ + *:CheckHealth* +:CheckHealth Run all healthchecks and show the output in a new + tabpage. These healthchecks are included by default: + - python2 + - python3 + - ruby + - remote plugin + +:CheckHealth {plugins} + Run healthchecks for one or more plugins. E.g. to run + only the standard Nvim healthcheck: > + :CheckHealth nvim +< To run the healthchecks for the "foo" and "bar" plugins + (assuming these plugins are on your 'runtimepath' and + they have implemented health#foo#check() and + health#bar#check(), respectively): > + :CheckHealth foo bar +< +Functions +------------------------------------------------------------------------------ + +health.vim functions are for creating new healthchecks. They mostly just do +some layout and formatting, to give users a consistent presentation. + +health#report_start({name}) *health#report_start* + Starts a new report. Most plugins should call this only once, but if + you want different sections to appear in your report, call this once + per section. + +health#report_info({msg}) *health#report_info* + Displays an informational message. + +health#report_ok({msg}) *health#report_ok* + Displays a "success" message. + +health#report_warn({msg}, [{suggestions}]) *health#report_warn* + Displays a warning. {suggestions} is an optional List of suggestions. + +health#report_error({msg}, [{suggestions}]) *health#report_error* + Displays an error. {suggestions} is an optional List of suggestions. + +health#{plugin}#check() *health.user_checker* + This is the form of a healthcheck definition. Call the above functions + from this function, then |:CheckHealth| does the rest. Example: > + + function! health#my_plug#check() abort + silent call s:check_environment_vars() + silent call s:check_python_configuration() + endfunction +< + The function will be found and called automatically when the user + invokes |:CheckHealth|. + + All output will be captured from the healthcheck. Use the + health#report_* functions so that your healthcheck has a format + consistent with the standard healthchecks. + +============================================================================== +Create a healthcheck *health.vim-dev* + +Healthchecks are functions that check the health of the system. Neovim has +built-in checkers, found in $VIMRUNTIME/autoload/health/. + +To add a new checker for your own plugin, simply define a +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': > + + autoload/health/jslint.vim +< +Here's a sample to get started: > + + function! health#jslint#check() abort + call health#report_start('sanity checks') + " perform arbitrary checks + " ... + + if looks_good + call health#report_ok('found required dependencies') + else + call health#report_error('cannot find jslint', + \ ['npm install --save jslint']) + endif + endfunction +< +============================================================================== + +vim:tw=78:ts=8:ft=help:fdm=marker diff --git a/runtime/doc/pi_msgpack.txt b/runtime/doc/pi_msgpack.txt index 95d6ff7467..d695ac42cb 100644 --- a/runtime/doc/pi_msgpack.txt +++ b/runtime/doc/pi_msgpack.txt @@ -128,6 +128,11 @@ msgpack#eval({string}, {dict}) *msgpack#eval()* always evaluated to |msgpack-special-dict| values, as well as hexadecimal digits. When evaluating maps order of keys is preserved. + Note that in addition to regular integer representations that may be + obtained using |msgpack#string()| msgpack#eval() also supports C-style + “character†integer constants like `'/'` (equivalent to + `char2nr('/')`: `47`). This also allows `'\0'` (number is decimal). + *msgpack#equal* msgpack#equal({msgpack-value}, {msgpack-value}) *msgpack#equal()* Returns 1 if given values are equal, 0 otherwise. When comparing diff --git a/runtime/doc/pi_netrw.txt b/runtime/doc/pi_netrw.txt index 1705010ff2..f740143c61 100644 --- a/runtime/doc/pi_netrw.txt +++ b/runtime/doc/pi_netrw.txt @@ -1,4 +1,4 @@ -*pi_netrw.txt* For Vim version 7.4. Last change: 2015 Oct 31 +*pi_netrw.txt* For Vim version 7.4. Last change: 2016 Apr 20 ------------------------------------------------ NETRW REFERENCE MANUAL by Charles E. Campbell @@ -6,7 +6,7 @@ Author: Charles E. Campbell <NdrOchip@ScampbellPfamily.AbizM> (remove NOSPAM from Campbell's email first) -Copyright: Copyright (C) 1999-2015 Charles E Campbell *netrw-copyright* +Copyright: Copyright (C) 2016 Charles E Campbell *netrw-copyright* The VIM LICENSE applies to the files in this package, including netrw.vim, pi_netrw.txt, netrwFileHandlers.vim, netrwSettings.vim, and syntax/netrw.vim. Like anything else that's free, netrw.vim and its @@ -48,9 +48,10 @@ Copyright: Copyright (C) 1999-2015 Charles E Campbell *netrw-copyright* Introduction To Browsing............................|netrw-intro-browse| Quick Reference: Maps...............................|netrw-browse-maps| Quick Reference: Commands...........................|netrw-browse-cmds| + Banner Display......................................|netrw-I| Bookmarking A Directory.............................|netrw-mb| Browsing............................................|netrw-cr| - Squeezing the Current Tree-Listing Directory......|:netrw-s-cr| + Squeezing the Current Tree-Listing Directory........|netrw-s-cr| Browsing With A Horizontally Split Window...........|netrw-o| Browsing With A New Tab.............................|netrw-t| Browsing With A Vertically Split Window.............|netrw-v| @@ -75,11 +76,13 @@ Copyright: Copyright (C) 1999-2015 Charles E Campbell *netrw-copyright* Making The Browsing Directory The Current Directory.|netrw-c| Marking Files.......................................|netrw-mf| Unmarking Files.....................................|netrw-mF| + Marking Files By Location List......................|netrw-qL| Marking Files By QuickFix List......................|netrw-qF| Marking Files By Regular Expression.................|netrw-mr| Marked Files: Arbitrary Shell Command...............|netrw-mx| Marked Files: Arbitrary Shell Command, En Bloc......|netrw-mX| Marked Files: Arbitrary Vim Command.................|netrw-mv| + Marked Files: Argument List.........................|netrw-ma| |netrw-mA| Marked Files: Compression And Decompression.........|netrw-mz| Marked Files: Copying...............................|netrw-mc| Marked Files: Diff..................................|netrw-md| @@ -1111,6 +1114,7 @@ QUICK REFERENCE: MAPS *netrw-browse-maps* {{{2 qb List bookmarked directories and history |netrw-qb| qf Display information on file |netrw-qf| qF Mark files using a quickfix list |netrw-qF| + qL Mark files using a |location-list| |netrw-qL| r Reverse sorting order |netrw-r| R Rename the designated file(s)/directory(ies) |netrw-R| s Select sorting style: by name, time, or file size |netrw-s| @@ -1160,6 +1164,14 @@ QUICK REFERENCE: COMMANDS *netrw-explore-cmds* *netrw-browse-cmds* {{{2 :Texplore[!] [dir] Tab & Explore..........................|netrw-explore| :Vexplore[!] [dir] Vertical Split & Explore...............|netrw-explore| + +BANNER DISPLAY *netrw-I* + +One may toggle the banner display on and off by pressing "I". + +Also See: |g:netrw_banner| + + BOOKMARKING A DIRECTORY *netrw-mb* *netrw-bookmark* *netrw-bookmarks* {{{2 One may easily "bookmark" the currently browsed directory by using > @@ -1201,7 +1213,7 @@ Related Topics: |g:netrw_home| controls where .netrwbook is kept -BROWSING *netrw-cr* {{{2 +BROWSING *netrw-enter* *netrw-cr* {{{2 Browsing is simple: move the cursor onto a file or directory of interest. Hitting the <cr> (the return key) will select the file or directory. @@ -1242,11 +1254,21 @@ The price for such re-use is that when changes are made (such as new files are introduced into a directory), the listing may become out-of-date. One may always refresh directory listing buffers by pressing ctrl-L (see |netrw-ctrl-l|). - *:netrw-s-cr* - Squeezing the Current Tree-Listing Directory~ - When the tree listing style is enabled (see |netrw-i|) and one is using - gvim, then the <s-cr> mapping may be used to squeeze (close) the - directory currently containing the cursor. + + *netrw-s-cr* +Squeezing the Current Tree-Listing Directory~ + +When the tree listing style is enabled (see |netrw-i|) and one is using +gvim, then the <s-cr> mapping may be used to squeeze (close) the +directory currently containing the cursor. + +Otherwise, one may remap a key combination of one's own choice to get +this effect: > + + nmap <buffer> <silent> <nowait> YOURKEYCOMBO <Plug>NetrwTreeSqueeze +< +Put this line in $HOME/ftplugin/netrw/netrw.vim; it needs to be generated +for netrw buffers only. Related topics: |netrw-ctrl-r| |netrw-o| |netrw-p| @@ -1495,11 +1517,13 @@ One may also use visual mode (see |visual-start|) to select the text that the special handler will use. Normally gx uses expand("<cfile>") to pick up the text under the cursor; one may change what |expand()| uses via the |g:netrw_gx| variable. Alternatively, one may select the text to be used by -gx via first making a visual selection (see |visual-block|). +gx via first making a visual selection (see |visual-block|) or by changing +the |'isfname'| option (which is global, so netrw doesn't modify it). Associated setting variables: |g:netrw_gx| control how gx picks up the text under the cursor |g:netrw_nogx| prevent gx map while editing + |g:netrw_suppress_gx_mesg| controls gx's suppression of browser messages *netrw_filehandler* @@ -1713,8 +1737,9 @@ Also see: |g:netrw_alto| |g:netrw_altv| |g:netrw_winsize| EXPLORING WITH STARS AND PATTERNS {{{2 When Explore, Sexplore, Hexplore, or Vexplore are used with one of the -following four patterns Explore generates a list of files which satisfy -the request. > +following four patterns Explore generates a list of files which satisfy the +request for the local file system. These exploration patterns will not work +with remote file browsing. */filepat files in current directory which satisfy filepat **/filepat files in current directory or below which satisfy the @@ -2079,15 +2104,22 @@ Netrw provides several ways to mark files: :MF *.c < - * Note that :MF uses |<f-args>| to break the line - at spaces. + (Note that :MF uses |<f-args>| to break the line + at spaces) + + * Mark files using the |argument-list| (|netrw-mA|) + + * Mark files based upon a |location-list| (|netrw-qL|) * Mark files based upon the quickfix list (|netrw-qF|) + (|quickfix-error-lists|) The following netrw maps make use of marked files: |netrw-a| Hide marked files/directories |netrw-D| Delete marked files/directories + |netrw-ma| Move marked files' names to |arglist| + |netrw-mA| Move |arglist| filenames to marked file list |netrw-mb| Append marked files to bookmarks |netrw-mB| Delete marked files from bookmarks |netrw-mc| Copy marked files to target @@ -2146,8 +2178,14 @@ UNMARKING FILES *netrw-mF* {{{2 The "mF" command will unmark all files in the current buffer. One may also use mf (|netrw-mf|) on a specific, already marked, file to unmark just that file. +MARKING FILES BY LOCATION LIST *netrw-qL* {{{2 + (also see |netrw-mf|) + +One may convert |location-list|s into a marked file list using "qL". +You may then proceed with commands such as me (|netrw-me|) to edit them. -MARKING FILES BY QUICKFIX LIST *netrw-qF* {{{2 + +MARKING FILES BY QUICKFIX LIST *netrw-qF* {{{2 (also see |netrw-mf|) One may convert |quickfix-error-lists| into a marked file list using "qF". @@ -2223,6 +2261,16 @@ The command that will be run with this example: tar cf mynewtarball.tar 'file1' 'file2' ... +MARKED FILES: ARGUMENT LIST *netrw-ma* *netrw-mA* + (See |netrw-mf| and |netrw-mr| for how to mark files) + (uses the global marked-file list) + +Using ma, one moves filenames from the marked file list to the argument list. +Using mA, one moves filenames from the argument list to the marked file list. + +See Also: |netrw-qF| |argument-list| |:args| + + MARKED FILES: COMPRESSION AND DECOMPRESSION *netrw-mz* {{{2 (See |netrw-mf| and |netrw-mr| for how to mark files) (uses the local marked file list) @@ -2232,7 +2280,7 @@ If any marked files are decompressed, then "mz" will compress them using the command specified by |g:netrw_compress|; by default, that's "gzip". -For decompression, netrw provides a |Dictionary| of suffices and their +For decompression, netrw uses a |Dictionary| of suffices and their associated decompressing utilities; see |g:netrw_decompress|. Remember that one can mark multiple files by regular expression @@ -2287,7 +2335,7 @@ The command will ask for the requested pattern; one may then enter: > pattern < With /pattern/, editing will start with the first item on the |quickfix| list -that vimgrep sets up (see |:copen|, |:cnext|, |:cprevious|). The |:vimgrep| +that vimgrep sets up (see |:copen|, |:cnext|, |:cprevious|, |:cclose|). The |:vimgrep| command is in use, so without 'g' each line is added to quickfix list only once; with 'g' every match is included. @@ -2756,6 +2804,16 @@ your browsing preferences. (see also: |netrw-settings|) evaluation will be suppressed (see |'ballooneval'|) + *g:netrw_sizestyle* not defined: actual bytes (default) + ="b" : actual bytes (default) + ="h" : human-readable (ex. 5k, 4m, 3g) + uses 1000 base + ="H" : human-readable (ex. 5K, 4M, 3G) + uses 1024 base + The long listing (|netrw-i|) and query-file + maps (|netrw-qf|) will display file size + using the specified style. + *g:netrw_usetab* if this variable exists and is non-zero, then the <tab> map supporting shrinking/expanding a Lexplore or netrw window will be enabled. @@ -2872,6 +2930,13 @@ your browsing preferences. (see also: |netrw-settings|) such as listing, file removal, etc. default: ssh + *g:netrw_suppress_gx_mesg* =1 : browsers sometimes produce messages + which are normally unwanted intermixed + with the page. + However, when using links, for example, + those messages are what the browser produces. + By setting this option to 0, netrw will not + suppress browser messages. *g:netrw_tmpfile_escape* =' &;' escape() is applied to all temporary files @@ -3024,14 +3089,14 @@ These will: Related: if you like this idea, you may also find :Lexplore (|netrw-:Lexplore|) or |g:netrw_chgwin| of interest -Also see: |g:netrw_chgwin| |netrw-P| |'previewwindow'| +Also see: |g:netrw_chgwin| |netrw-P| |'previewwindow'| |CTRL-W_z| |:pclose| PREVIOUS WINDOW *netrw-P* *netrw-prvwin* {{{2 -To edit a file or directory in the previously used (last accessed) window (see -:he |CTRL-W_p|), press a "P". If there's only one window, then the one window -will be horizontally split (by default). +To edit a file or directory under the cursor in the previously used (last +accessed) window (see :he |CTRL-W_p|), press a "P". If there's only one +window, then the one window will be horizontally split (by default). If there's more than one window, the previous window will be re-used on the selected file/directory. If the previous window's associated buffer @@ -3170,7 +3235,7 @@ only if your terminal supports differentiating <c-tab> from a plain * Else bring up a |:Lexplore| window If |g:netrw_usetab| exists or is zero, or if there is a pre-existing mapping -for <c-tab>, then the <tab> will not be mapped. One may map something other +for <c-tab>, then the <c-tab> will not be mapped. One may map something other than a <c-tab>, too: (but you'll still need to have had g:netrw_usetab set) > nmap <unique> (whatever) <Plug>NetrwShrink @@ -3637,13 +3702,13 @@ called netrw.vimrc with the following contents: > < Then run netrw as follows: > - vim -u netrw.vimrc --noplugins [some path here] + vim -u netrw.vimrc --noplugins -i NONE [some path here] < Perform whatever netrw commands you need to, and check that the problem is still present. This procedure sidesteps any issues due to personal .vimrc -settings and other plugins. If the problem does not appear, then you need -to determine what setting in your .vimrc is causing the conflict with netrw -or which plugin. +settings, .viminfo file, and other plugins. If the problem does not appear, +then you need to determine which setting in your .vimrc is causing the +conflict with netrw or which plugin(s) is/are involved. Step 3: If the problem still is present, then get a debugging trace from netrw: @@ -3698,6 +3763,54 @@ netrw: ============================================================================== 12. History *netrw-history* {{{1 + v156: Feb 18, 2016 * Changed =~ to =~# where appropriate + Feb 23, 2016 * s:ComposePath(base,subdir) now uses + fnameescape() on the base portion + Mar 01, 2016 * (gt_macki) reported where :Explore would + make file unlisted. Fixed (tst943) + Apr 04, 2016 * (reported by John Little) netrw normally + suppresses browser messages, but sometimes + those "messages" are what is wanted. + See |g:netrw_suppress_gx_mesg| + Apr 06, 2016 * (reported by Carlos Pita) deleting a remote + file was giving an error message. Fixed. + Apr 08, 2016 * (Charles Cooper) had a problem with an + undefined b:netrw_curdir. He also provided + a fix. + Apr 20, 2016 * Changed s:NetrwGetBuffer(); now uses + dictionaries. Also fixed the "No Name" + buffer problem. + v155: Oct 29, 2015 * (Timur Fayzrakhmanov) reported that netrw's + mapping of ctrl-l was not allowing refresh of + other windows when it was done in a netrw + window. + Nov 05, 2015 * Improved s:TreeSqueezeDir() to use search() + instead of a loop + * NetrwBrowse() will return line to + w:netrw_bannercnt if cursor ended up in + banner + Nov 16, 2015 * Added a <Plug>NetrwTreeSqueeze (|netrw-s-cr|) + Nov 17, 2015 * Commented out imaps -- perhaps someone can + tell me how they're useful and should be + retained? + Nov 20, 2015 * Added |netrw-ma| and |netrw-mA| support + Nov 20, 2015 * gx (|netrw-gx|) on an url downloaded the + file in addition to simply bringing up the + url in a browser. Fixed. + Nov 23, 2015 * Added |g:netrw_sizestyle| support + Nov 27, 2015 * Inserted a lot of <c-u>s into various netrw + maps. + Jan 05, 2016 * |netrw-qL| implemented to mark files based + upon |location-list|s; similar to |netrw-qF|. + Jan 19, 2016 * using - call delete(directoryname,"d") - + instead of using g:netrw_localrmdir if + v7.4 + patch#1107 is available + Jan 28, 2016 * changed to using |winsaveview()| and + |winrestview()| + Jan 28, 2016 * s:NetrwTreePath() now does a save and + restore of view + Feb 08, 2016 * Fixed a tree-listing problem with remote + directories v154: Feb 26, 2015 * (Yuri Kanivetsky) reported a situation where a file was not treated properly as a file due to g:netrw_keepdir == 1 @@ -3858,7 +3971,7 @@ netrw: handling. * |:Lexplore| path: will be used to update a left-side netrw browsing directory. - Mar 12, 2014 * |:netrw-s-cr|: use <s-cr> to close + Mar 12, 2014 * |netrw-s-cr|: use <s-cr> to close tree directory implemented Mar 13, 2014 * (Tony Mechylynck) reported that using the browser with ftp on a directory, diff --git a/runtime/doc/pi_vimball.txt b/runtime/doc/pi_vimball.txt deleted file mode 100644 index bbc74988ca..0000000000 --- a/runtime/doc/pi_vimball.txt +++ /dev/null @@ -1,273 +0,0 @@ -*pi_vimball.txt* For Vim version 7.4. Last change: 2012 Jan 17 - - ---------------- - Vimball Archiver - ---------------- - -Author: Charles E. Campbell, Jr. <NdrOchip@ScampbellPfamily.AbizM> - (remove NOSPAM from Campbell's email first) -Copyright: (c) 2004-2012 by Charles E. Campbell, Jr. *Vimball-copyright* - The VIM LICENSE (see |copyright|) applies to the files in this - package, including vimballPlugin.vim, vimball.vim, and pi_vimball.txt. - except use "vimball" instead of "VIM". Like anything else that's free, - vimball.vim and its associated files are provided *as is* and comes with - no warranty of any kind, either expressed or implied. No guarantees - of merchantability. No guarantees of suitability for any purpose. By - using this plugin, you agree that in no event will the copyright - holder be liable for any damages resulting from the use of this - software. Use at your own risk! - -============================================================================== -1. Contents *vba* *vimball* *vimball-contents* - - 1. Contents......................................: |vimball-contents| - 2. Vimball Introduction..........................: |vimball-intro| - 3. Vimball Manual................................: |vimball-manual| - MkVimball.....................................: |:MkVimball| - UseVimball....................................: |:UseVimball| - RmVimball.....................................: |:RmVimball| - 4. Vimball History...............................: |vimball-history| - - -============================================================================== -2. Vimball Introduction *vimball-intro* - - Vimball is intended to make life simpler for users of plugins. All - a user needs to do with a vimball is: > - vim someplugin.vba - :so % - :q -< and the plugin and all its components will be installed into their - appropriate directories. Note that one doesn't need to be in any - particular directory when one does this. Plus, any help for the - plugin will also be automatically installed. - - If a user has decided to use the AsNeeded plugin, vimball is smart - enough to put scripts nominally intended for .vim/plugin/ into - .vim/AsNeeded/ instead. - - Removing a plugin that was installed with vimball is really easy: > - vim - :RmVimball someplugin -< This operation is not at all easy for zips and tarballs, for example. - - Vimball examines the user's |'runtimepath'| to determine where to put - the scripts. The first directory mentioned on the runtimepath is - usually used if possible. Use > - :echo &rtp -< to see that directory. - - -============================================================================== -3. Vimball Manual *vimball-manual* - -MAKING A VIMBALL *:MkVimball* - :[range]MkVimball[!] filename [path] - - The range is composed of lines holding paths to files to be included - in your new vimball, omitting the portion of the paths that is - normally specified by the runtimepath (|'rtp'|). As an example: > - plugin/something.vim - doc/something.txt -< using > - :[range]MkVimball filename -< - on this range of lines will create a file called "filename.vba" which - can be used by Vimball.vim to re-create these files. If the - "filename.vba" file already exists, then MkVimball will issue a - warning and not create the file. Note that these paths are relative - to your .vim (vimfiles) directory, and the files should be in that - directory. The vimball plugin normally uses the first |'runtimepath'| - directory that exists as a prefix; don't use absolute paths, unless - the user has specified such a path. - - If you use the exclamation point (!), then MkVimball will create the - "filename.vba" file, overwriting it if it already exists. This - behavior resembles that for |:w|. - - If you wish to force slashes into the filename, that can also be done - by using the exclamation mark (ie. :MkVimball! path/filename). - - The tip at http://vim.wikia.com/wiki/Using_VimBall_with_%27Make%27 - has a good idea on how to automate the production of vimballs using - make. - - -MAKING DIRECTORIES VIA VIMBALLS *g:vimball_mkdir* - - First, the |mkdir()| command is tried (not all systems support it). - - If it doesn't exist, then if g:vimball_mkdir doesn't exist, it is set - as follows: > - |g:netrw_local_mkdir|, if it exists - "mkdir" , if it is executable - "makedir" , if it is executable - Otherwise , it is undefined. -< One may explicitly specify the directory making command using - g:vimball_mkdir. This command is used to make directories that - are needed as indicated by the vimball. - - -CONTROLLING THE VIMBALL EXTRACTION DIRECTORY *g:vimball_home* - - You may override the use of the |'runtimepath'| by specifying a - variable, g:vimball_home. - - *vimball-extract* - vim filename.vba - - Simply editing a Vimball will cause Vimball.vim to tell the user to - source the file to extract its contents. - - Extraction will only proceed if the first line of a putative vimball - file holds the "Vimball Archiver by Charles E. Campbell, Jr., Ph.D." - line. - -LISTING FILES IN A VIMBALL *:VimballList* - - :VimballList - - This command will tell Vimball to list the files in the archive, along - with their lengths in lines. - -MANUALLY INVOKING VIMBALL EXTRACTION *:UseVimball* - - :UseVimball [path] - - This command is contained within the vimball itself; it invokes the - vimball#Vimball() routine which is responsible for unpacking the - vimball. One may choose to execute it by hand instead of sourcing - the vimball; one may also choose to specify a path for the - installation, thereby overriding the automatic choice of the first - existing directory on the |'runtimepath'|. - -REMOVING A VIMBALL *:RmVimball* - - :RmVimball vimballfile [path] - - This command removes all files generated by the specified vimball - (but not any directories it may have made). One may choose a path - for de-installation, too (see |'runtimepath'|); otherwise, the - default is the first existing directory on the |'runtimepath'|. - To implement this, a file (.VimballRecord) is made in that directory - containing a record of what files need to be removed for all vimballs - used thus far. - -PREVENTING LOADING - - If for some reason you don't want to be able to extract plugins - using vimballs: you may prevent the loading of vimball.vim by - putting the following two variables in your <.vimrc>: > - - let g:loaded_vimballPlugin= 1 - let g:loaded_vimball = 1 -< -WINDOWS *vimball-windows* - - Many vimball files are compressed with gzip. Windows, unfortunately, - does not come provided with a tool to decompress gzip'ped files. - Fortunately, there are a number of tools available for Windows users - to un-gzip files: -> - Item Tool/Suite Free Website - ---- ---------- ---- ------- - 7zip tool y http://www.7-zip.org/ - Winzip tool n http://www.winzip.com/downwz.htm - unxutils suite y http://unxutils.sourceforge.net/ - cygwin suite y http://www.cygwin.com/ - GnuWin32 suite y http://gnuwin32.sourceforge.net/ - MinGW suite y http://www.mingw.org/ -< - -============================================================================== -4. Vimball History *vimball-history* {{{1 - - 34 : Sep 22, 2011 * "UseVimball path" now supports a non-full path by - prepending the current directory to it. - 33 : Apr 02, 2011 * Gave priority to *.vmb over *.vba - * Changed silent! to sil! (shorter) - * Safed |'swf'| setting (during vimball extraction, - its now turned off) - 32 : May 19, 2010 * (Christian Brabandt) :so someplugin.vba and - :so someplugin.vba.gz (and the other supported - compression types) now works - * (Jan Steffens) added support for xz compression - * fenc extraction was erroneously picking up the - end of the line number when no file encoding - was present. Fixed. - * By request, beginning the switchover from the vba - extension to vmb. Currently both are supported; - MkVimball, however, now will create *.vmb files. - Feb 11, 2011 * motoyakurotsu reported an error with vimball's - handling of zero-length files - 30 : Dec 08, 2008 * fnameescape() inserted to protect error - messaging using corrupted filenames from - causing problems - * RmVimball supports filenames that would - otherwise be considered to have "magic" - characters (ie. Abc[1].vba) - Feb 18, 2009 * s:Escape(), g:vimball_shq, and g:netrw_shq - removed (shellescape() used directly) - Oct 05, 2009 * (Nikolai Weibull) suggested that MkVimball - be allowed to use slashes in the filename. - 26 : May 27, 2008 * g:vimball_mkdir usage installed. Makes the - $HOME/.vim (or $HOME\vimfiles) directory if - necessary. - May 30, 2008 * (tnx to Bill McCarthy) found and fixed a bug: - vimball wasn't updating plugins to AsNeeded/ - when it should - 25 : Mar 24, 2008 * changed vimball#Vimball() to recognize doc/*.??x - files as help files, too. - Apr 18, 2008 * RmVimball command is now protected by saving and - restoring settings -- in particular, acd was - causing problems as reported by Zhang Shuhan - 24 : Nov 15, 2007 * g:vimball_path_escape used by s:Path() to - prevent certain characters from causing trouble - (defunct: |fnameescape()| and |shellescape()| - now used instead) - 22 : Mar 21, 2007 * uses setlocal instead of set during BufEnter - 21 : Nov 27, 2006 * (tnx to Bill McCarthy) vimball had a header - handling problem and it now changes \s to /s - 20 : Nov 20, 2006 * substitute() calls have all had the 'e' flag - removed. - 18 : Aug 01, 2006 * vimballs now use folding to easily display their - contents. - * if a user has AsNeeded/somefile, then vimball - will extract plugin/somefile to the AsNeeded/ - directory - 17 : Jun 28, 2006 * changes all \s to /s internally for Windows - 16 : Jun 15, 2006 * A. Mechelynck's idea to allow users to specify - installation root paths implemented for - UseVimball, MkVimball, and RmVimball. - * RmVimball implemented - 15 : Jun 13, 2006 * bugfix - 14 : May 26, 2006 * bugfixes - 13 : May 01, 2006 * exists("&acd") used to determine if the acd - option exists - 12 : May 01, 2006 * bugfix - the |'acd'| option is not always defined - 11 : Apr 27, 2006 * VimballList would create missing subdirectories that - the vimball specified were needed. Fixed. - 10 : Apr 27, 2006 * moved all setting saving/restoration to a pair of - functions. Included some more settings in them - which frequently cause trouble. - 9 : Apr 26, 2006 * various changes to support Windows' predilection - for backslashes and spaces in file and directory - names. - 7 : Apr 25, 2006 * bypasses foldenable - * uses more exe and less norm! (:yank :put etc) - * does better at insuring a "Press ENTER" prompt - appears to keep its messages visible - 4 : Mar 31, 2006 * BufReadPost seems to fire twice; BufReadEnter - only fires once, so the "Source this file..." - message is now issued only once. - 3 : Mar 20, 2006 * removed query, now requires sourcing to be - extracted (:so %). Message to that effect - included. - * :VimballList now shows files that would be - extracted. - 2 : Mar 20, 2006 * query, :UseVimball included - 1 : Mar 20, 2006 * initial release - - -============================================================================== -vim:tw=78:ts=8:ft=help:fdm=marker diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt new file mode 100644 index 0000000000..3cd53e3e50 --- /dev/null +++ b/runtime/doc/provider.txt @@ -0,0 +1,133 @@ +*provider.txt* {Nvim} + + + NVIM REFERENCE MANUAL by Thiago de Arruda + + +Providers *provider* + +Nvim delegates some features to dynamic "providers". + +============================================================================== +Python integration *provider-python* + +Nvim supports the Vim legacy |python-vim| and |python3| interfaces via +external Python interpreters connected via |RPC|. +Note: Only the Vim 7.3 API is supported; bindeval (Vim 7.4) is not. + +PYTHON QUICKSTART ~ + +If you used a package manager to install Nvim, you might already have the +required `neovim` Python package. Run |:CheckHealth| to see if your system is +up-to-date. + +Following are steps to install the package with Python's `pip` tool. + +Note: Depending on your system, `pip` might refer to Python 2 or Python 3, + which is why the following instructions mention `pip2` or `pip3` + explicitly. If one of these is not available, try `pip`. + +To use Vim Python 2/3 plugins with Nvim: + +- For Python 2 plugins, make sure an interpreter for Python 2.6 or 2.7 is + available in your `$PATH`, then install the `neovim` Python package systemwide: > + $ sudo pip2 install --upgrade neovim +< + or for the current user: > + $ pip2 install --user --upgrade neovim +< +- For Python 3 plugins, make sure an interpreter for Python 3.3 or above is + available in your `$PATH`, then install the `neovim` Python package systemwide: > + $ sudo pip3 install --upgrade neovim +< + or for the current user: > + $ pip3 install --user --upgrade neovim +< +Note: The `--upgrade` flag ensures you have the latest version even if + a previous version was already installed. + +PYTHON PROVIDER CONFIGURATION ~ + *g:python_host_prog* + *g:python3_host_prog* +Program to use for evaluating Python code. Setting this makes startup faster. > + let g:python_host_prog = '/path/to/python' + let g:python3_host_prog = '/path/to/python3' +< + *g:loaded_python_provider* +To disable Python 2 support: > + let g:loaded_python_provider = 1 +< + *g:loaded_python3_provider* +To disable Python 3 support: > + let g:loaded_python3_provider = 1 + + +============================================================================== +Ruby integration *provider-ruby* + +Nvim supports the Vim legacy |ruby-vim| interface via external Ruby +interpreters connected via |RPC|. + +Run |:CheckHealth| to see if your system is up-to-date. + +RUBY QUICKSTART ~ + +To use Vim Ruby plugins with Nvim, just install the latest `neovim` RubyGem: > + $ gem install neovim + +RUBY PROVIDER CONFIGURATION ~ + *g:loaded_ruby_provider* +To disable Ruby support: > + let g:loaded_ruby_provider = 1 + + +============================================================================== +Clipboard integration *provider-clipboard* *clipboard* + +Nvim has no direct connection to the system clipboard. Instead it is +accessible through a |provider| which transparently uses shell commands for +communicating with the clipboard. + +Clipboard access is implicitly enabled if any of the following clipboard tools +are found in your `$PATH`. + + - xclip + - xsel (newer alternative to xclip) + - pbcopy/pbpaste (Mac OS X) + - lemonade (for SSH) https://github.com/pocke/lemonade + - doitclient (for SSH) http://www.chiark.greenend.org.uk/~sgtatham/doit/ + +The presence of a suitable clipboard tool implicitly enables the '+' and '*' +registers. + +If you want to ALWAYS use the clipboard for ALL operations (as opposed +to interacting with the '+' and/or '*' registers explicitly), set the +following option: +> + set clipboard+=unnamedplus +< +See 'clipboard' for details and more options. + +============================================================================== +X11 selection mechanism *clipboard-x11* *x11-selection* + +The clipboard providers for X11 store text in what is known as "selections". +Selections are "owned" by an application, so when the application is closed, +the selection text is lost. + +The contents of selections are held by the originating application (e.g., upon +a copy), and only passed on to another application when that other application +asks for them (e.g., upon a paste). + + *quoteplus* *quote+* + +There are three documented X11 selections: `PRIMARY`, `SECONDARY`, and `CLIPBOARD`. +`CLIPBOARD` is typically used in X11 applications for copy/paste operations +(`Ctrl-c`/`v`), while `PRIMARY` is used for the last selected text, which is +generally inserted with the middle mouse button. + +Nvim's X11 clipboard providers only utilize the `PRIMARY` and `CLIPBOARD` +selections, used for the '*' and '+' registers, respectively. + +============================================================================== + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/quickfix.txt b/runtime/doc/quickfix.txt index ff4fded0d9..0b7907e364 100644 --- a/runtime/doc/quickfix.txt +++ b/runtime/doc/quickfix.txt @@ -1,4 +1,4 @@ -*quickfix.txt* For Vim version 7.4. Last change: 2015 Sep 08 +*quickfix.txt* For Vim version 7.4. Last change: 2016 Jul 07 VIM REFERENCE MANUAL by Bram Moolenaar @@ -30,10 +30,14 @@ positions in files. For example, |:vimgrep| finds pattern matches. You can use the positions in a script with the |getqflist()| function. Thus you can do a lot more than the edit/compile/fix cycle! -You should save your compiler's error messages to a file and start vim with -"vim -q filename". An easy way to do this is with the |:make| command (see -below). The 'errorformat' option should be set to match the error messages -from your compiler (see |errorformat| below). +If you have the error messages in a file you can start Vim with: > + vim -q filename + +From inside Vim an easy way to run a command and handle the output is with the +|:make| command (see below). + +The 'errorformat' option should be set to match the error messages from your +compiler (see |errorformat| below). *location-list* *E776* A location list is similar to a quickfix list and contains a list of positions @@ -42,13 +46,21 @@ have a separate location list. A location list can be associated with only one window. The location list is independent of the quickfix list. When a window with a location list is split, the new window gets a copy of the -location list. When there are no references to a location list, the location -list is destroyed. +location list. When there are no longer any references to a location list, +the location list is destroyed. The following quickfix commands can be used. The location list commands are similar to the quickfix commands, replacing the 'c' prefix in the quickfix command with 'l'. + *E924* +If the current window was closed by an |autocommand| while processing a +location list command, it will be aborted. + + *E925* *E926* +If the current quickfix or location list was changed by an |autocommand| while +processing a quickfix or location list command, it will be aborted. + *:cc* :cc[!] [nr] Display error [nr]. If [nr] is omitted, the same error is displayed again. Without [!] this doesn't @@ -255,9 +267,23 @@ command with 'l'. The 'switchbuf' settings are respected when jumping to a buffer. +:cl[ist] +{count} List the current and next {count} valid errors. This + is similar to ":clist from from+count", where "from" + is the current error position. + :cl[ist]! [from] [, [to]] List all errors. +:cl[ist]! +{count} List the current and next {count} error lines. This + is useful to see unrecognized lines after the current + one. For example, if ":clist" shows: + 8384 testje.java:252: error: cannot find symbol ~ + Then using ":cl! +3" shows the reason: + 8384 testje.java:252: error: cannot find symbol ~ + 8385: ZexitCode = Fmainx(); ~ + 8386: ^ ~ + 8387: symbol: method Fmainx() ~ + *:lli* *:llist* :lli[st] [from] [, [to]] Same as ":clist", except the location list for the @@ -302,7 +328,7 @@ EXECUTE A COMMAND IN ALL THE BUFFERS IN QUICKFIX OR LOCATION LIST: etc. < When the current file can't be |abandon|ed and the [!] is not present, the command fails. - When an error is detected excecution stops. + When an error is detected execution stops. The last buffer (or where an error occurred) becomes the current buffer. {cmd} can contain '|' to concatenate several commands. @@ -406,6 +432,17 @@ EXECUTE A COMMAND IN ALL THE BUFFERS IN QUICKFIX OR LOCATION LIST: :lw[indow] [height] Same as ":cwindow", except use the window showing the location list for the current window. + *:cbo* *:cbottom* +:cbo[ttom] Put the cursor in the last line of the quickfix window + and scroll to make it visible. This is useful for + when errors are added by an asynchronous callback. + Only call it once in a while if there are many + updates to avoid a lot of redrawing. + + *:lbo* *:lbottom* +:lbo[ttom] Same as ":cbottom", except use the window showing the + location list for the current window. + Normally the quickfix window is at the bottom of the screen. If there are vertical splits, it's at the bottom of the rightmost column of windows. To make it always occupy the full width: > @@ -441,6 +478,9 @@ expression. The BufWinEnter event is also triggered, again using "quickfix" for the buffer name. +Note: When adding to an existing quickfix list the autocommand are not +triggered. + Note: Making changes in the quickfix window has no effect on the list of errors. 'modifiable' is off to avoid making changes. If you delete or insert lines anyway, the relation between the text and the error number is messed up. @@ -1489,12 +1529,6 @@ However, to properly parse such a complex file, an external filter should be used. See the description further above how to make such a filter known by Vim. - *errorformat-Perl* -In $VIMRUNTIME/tools you can find the efm_perl.pl script, which filters Perl -error messages into a format that quickfix mode will understand. See the -start of the file about how to use it. (This script is deprecated, see -|compiler-perl|.) - vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt index 8e40628e25..a7644fab84 100644 --- a/runtime/doc/quickref.txt +++ b/runtime/doc/quickref.txt @@ -1,4 +1,4 @@ -*quickref.txt* For Vim version 7.4. Last change: 2015 Nov 10 +*quickref.txt* For Vim version 7.4. Last change: 2016 Aug 12 VIM REFERENCE MANUAL by Bram Moolenaar @@ -794,6 +794,7 @@ Short explanation of each option: *option-list* 'omnifunc' 'ofu' function for filetype-specific completion 'opendevice' 'odev' allow reading/writing devices on MS-Windows 'operatorfunc' 'opfunc' function to be called for |g@| operator +'packpath' 'pp' list of directories used for packages 'paragraphs' 'para' nroff macros that separate paragraphs 'paste' allow pasting text 'pastetoggle' 'pt' key code that causes 'paste' to toggle @@ -812,6 +813,7 @@ Short explanation of each option: *option-list* 'printmbcharset' 'pmbcs' CJK character set to be used for :hardcopy 'printmbfont' 'pmbfn' font names to be used for CJK output of :hardcopy 'printoptions' 'popt' controls the format of :hardcopy output +'prompt' 'prompt' enable prompt in Ex mode 'pumheight' 'ph' maximum height of the popup menu 'pythondll' name of the Python 2 dynamic library 'pythonthreedll' name of the Python 3 dynamic library @@ -860,6 +862,7 @@ Short explanation of each option: *option-list* 'showtabline' 'stal' tells when the tab pages line is displayed 'sidescroll' 'ss' minimum number of columns to scroll horizontal 'sidescrolloff' 'siso' min. nr. of columns to left and right of cursor +'signcolumn' 'scl' when to display the sign column 'smartcase' 'scs' no ignore case when pattern has uppercase 'smartindent' 'si' smart autoindenting for C programs 'smarttab' 'sta' use 'shiftwidth' when inserting <Tab> diff --git a/runtime/doc/quotes.txt b/runtime/doc/quotes.txt deleted file mode 100644 index c35fb2f139..0000000000 --- a/runtime/doc/quotes.txt +++ /dev/null @@ -1,275 +0,0 @@ -*quotes.txt* For Vim version 7.4. Last change: 2010 Nov 03 - - - VIM REFERENCE MANUAL by Bram Moolenaar - - - *quotes* -Here are some nice quotes about Vim that I collected from news and mail. - - -vim (vim) noun - Ebullient vitality and energy. [Latin, accusative of vis, -strength] (Dictionary) - -Vim is so much better than vi that a great many of my old vi :map's became -immediately obsolete! (Tony Nugent, Australia) - -Coming with a very GUI mindset from Windows, I always thought of people using -Vi as some kind of outer space alien in human clothes. Once I tried I really -got addicted by its power and now I found myself typing Vim keypresses in the -oddest places! That's why I would like to see Vim embedded in every -application which deals with text editing. (José Fonseca) - -I was a 12-year emacs user who switched to Vim about a year ago after finally -giving up on the multiple incompatible versions, flaky contributed packages, -disorganized keystrokes, etc. And it was one of the best moves I ever made. -(Joel Burton) - -Although all of the programs were used during the preparation of the new and -revised material, most of the editing was done with Vim versions 4.5 and 5.0 -under GNU-Linux (Redhat 4.2). (Arnold Robbins, Israel, author of "Learning -the Vi editor") - -Out of all the open software i've ever seen and used, and i've seen a lot, Vim -is the best, most useful and highest quality to work with, second only to the -linux kernel itself. (Peter Jay Salzman) - -It's well worth noting that the _entirety_ of SourceForge was written using -Vim and its nifty PHP syntax highlighting. I think the entire SF.net tech -staff uses Vim and we're all excited to have you aboard! (Tim Perdue) - -Vim is one of a select bunch of tools for which I have no substitute. It is -a brilliant piece of work! (Biju Chacko) - -A previous girlfriend of mine switched to emacs. Needless to say, the -relationship went nowhere. (Geoffrey Mann) - -I rarely think about Vim, in the same way that I guess a fish rarely thinks -about water. It's the environment in which everything else happens. I'm a -fairly busy system administrator working on a lot of different platforms. Vim -is the only thing that's consistent across all my systems, and it's just about -the only thing that doesn't break from time to time. When a new system comes -in the door without Vim, I install it right away. Great to have a tool that's -the same everywhere, that's completely reliable, so I can ignore it and think -about other things. (Pete Schaeffer) - -Having recently succeeded in running Vim via telnet through a Nokia -Communicator, I can now report that it works nicely on a Palm Pilot too. -(Allan Kelly, Scotland) - -You've done a tremendous job with 'VIM', Bram! The more I use it, the more -impressed I get (I am an old 'vi' die hard who once started out with early -versions of 'emacs' in the late 1970's and was relieved by finding 'vi' in the -first UNIX I came across in 1983). In my opinion, it's about time 'VIM' -replace 'emacs' as the standard for top editors. (Bo Thide', Sweden) - -I love and use VIM heavily too. (Larry Wall) - -Vi is like a Ferrari, if you're a beginner, it handles like a bitch, but once -you get the hang of it, it's small, powerful and FAST! (Unknown) -VIM is like a new model Ferrari, and sounds like one too - "VIIIIIIMMM!" -(Stephen Riehm, Germany) - -Schon bei Nutzung eines Bruchteils der VIM-Funktionen wird der Benutzer recht -schnell die Vorzuege dieses Editors kennen- und schaetzenlernen. -Translated: Even when only using a fraction of VIM-functions, the user will -quickly get used to and appreciate the advantages of this editor. (Garry -Glendown, conclusion of an article on VIM in iX magazine 9/1998) - -I've recently acquired the O'Reilly book on VI (it also discusses VIM -in-depth), and I'm amazed at just how powerful this application is. (Jeffrey -Rankin) - -This guide was written using the Windows 9.x distribution of GVIM, which is -quite possibly the greatest thing to come along since God created the naked -girl. (Michael DiBernardo) - -Boy, I thought I knew almost everything about VIM, but every time I browse the -online documentation, I hit upon a minor but cool aspect of a VIM feature that -I didn't know before! I must say the documentation is one the finest I've -ever seen in a product -- even better than most commercial products. -(Gautam Mudunuri) - -VIM 4.5 is really a fantastic editor. It has sooooo many features and more -importantly, the defaults are so well thought out that you really don't have -to change anything!! Words cannot express my amazement and gratitude to the -creators of VIM. Keep it up. (Vikas, USA) - -I wonder how long it will be before people will refer to other Vi editors as -VIM clones? (Darren Hiebert) - -I read about [auto-positioning-in-file-based-on-the-errors-from-make] in one -of those "Perfect Programmer's Editor" threads and was delighted to discover -that VIM already supports it. (Brendan Macmillan, Australia) - -I just discovered VIM (5.0) and I'm telling everyone I know about it! -I tell them VIM stands for VI for the new (M)illenium. Thanks so much! -(Matt F. Valentine) - -I think from now on "vi" should be called "Vim Imitation", not the other way -around. (Rungun Ramanathan) - -The Law of VIM: -For each member b of the possible behaviour space B of program P, there exists -a finite time t before which at least one user u in the total user space U of -program P will request b becomes a member of the allowed behaviour space B' -(B' <= B). -In other words: Sooner or later everyone wants everything as an option. -(Negri) - -Whenever I move to a new computing platform, the first thing I do is to port -VIM. Lately, I am simply stunned by its ease of compilation using the -configure facility. (A.M. Sabuncu, Turkey) - -The options are really excellent and very powerful. (Anish Maharaj) - -The Spring user-interface designs are in, and word from the boutiques is that -80x24 text-only mode is back with a *vengeance! Vi editor clone VIM burst onto -March desk-tops with a dazzling show of pastel syntax highlights for its 5.0 -look. Strident and customizable, VIM raises eyebrows with its interpretation -of the classic Vi single-key macro collection. -http://www.ntk.net/index.cgi?back=archive98/now0327.txt&line=179#l - -I just wanted to take this opportunity to let you know that VIM 5 ROCKS! -Syntax highlighting: how did I survive without it?! Thank you for creating -mankind's best editor! (Mun Johl, USA) - -Thanks again for VIM. I use it every day on Linux. (Eric Foster-Johnson, -author of the book "UNIX Programming Tools") - -The BEST EDITOR EVER (Stuart Woolford) - -I have used most of VIM's fancy features at least once, many frequently, and I -can honestly say that I couldn't live with anything less anymore. My -productivity has easily doubled compared to what it was when I used vi. -(Sitaram Chamarty) - -I luv VIM. It is incredible. I'm naming my first-born Vimberly. (Jose -Unpingco, USA) - -Hint: "VIM" is "vi improved" - much better! (Sven Guckes, Germany) - -I use VIM every day. I spend more time in VIM than in any other program... -It's the best vi clone there is. I think it's great. (Craig Sanders, -Australia) - -I strongly advise using VIM--its infinite undo/redo saved me much grief. -(Terry Brown) - -Thanks very much for writing what in my opinion is the finest text editor on -the planet. If I were to get another cat, I would name it "Vim". -(Bob Sheehan, USA) - -I typed :set all and the screen FILLED up with options. A whole screen of -things to be set and unset. I saw some of my old friends like wrapmargin, -modelines and showmode, but the screen was FILLED with new friends! I love -them all! I love VIM! I'm so happy that I've found this editor! I feel -like how I once felt when I started using vi after a couple of years of using -ed. I never thought I'd forsake my beloved ed, but vi ... oh god, vi was -great. And now, VIM. (Peter Jay Salzman, USA) - -I am really happy with such a wonderful software package. Much better than -almost any expensive, off the shelf program. (Jeff Walker) - -Whenever I reread the VIM documentation I'm overcome with excitement at the -power of the editor. (William Edward Webber, Australia) - -Hurrah for VIM!! It is "at your fingertips" like vi, and has the extensions -that vi sorely needs: highlighting for executing commands on blocks, an easily -navigable and digestible help screen, and more. (Paul Pax) - -The reason WHY I don't have this amazingly useful macro anymore, is that I -now use VIM - and this is built in!! (Stephen Riehm, Germany) - -I am a user of VIM and I love it. I use it to do all my programming, C, -C++, HTML what ever. (Tim Allwine) - -I discovered VIM after years of struggling with the original vi, and I just -can't live without it anymore. (Emmanuel Mogenet, USA) - -Emacs has not a bit of chance to survive so long as VIM is around. Besides, -it also has the most detailed software documentation I have ever seen---much -better than most commercial software! (Leiming Qian) - -This version of VIM will just blow people apart when they discover just how -fantastic it is! (Tony Nugent, Australia) - -I took your advice & finally got VIM & I'm really impressed. Instant convert. -(Patrick Killelea, USA) - -VIM is by far my favorite piece of shareware and I have been particularly -pleased with version 3.0. This is really a solid piece of work. (Robert -Colon, USA) - -VIM is a joy to use, it is so well thought and practical that I wonder why -anybody would use visual development tools. VIM is powerful and elegant, it -looks deceptively simple but is almost as complex as a 747 (especially when I -look at my growing vimrc), keep up that wonderful job, VIM is a centerpiece -of the free software world. (Louis-David Mitterand, USA) - -I cannot believe how great it is to use VIM. I think the guys at work are -getting tired of hearing me bragging about it. Others eyes are lighting up. -(Rick Croote) - -Emacs takes way too much time to start up and run, it is too big and bulky for -effective use and the interface is more confusing than it is of any help. VIM -however is short, it is fast, it is powerful, it has a good interface and it -is all purpose. (Paal Ditlefsen Ekran) - -From the first time I got VIM3.0, I was very enthusiastic. It has almost no -problems. The swapfile handling and the backup possibilities are robust, also -the protection against editing one file twice. It is very compatible to the -real VI (and that is a MUST, because my brain is trained over years in using -it). (Gert van Antwerpen, Holland) - -Visual mode in VIM is a very powerful thing! (Tony Nugent, Australia) - -I have to say that VIM is =THE= single greatest piece of source code to ever -come across the net (Jim Battle, USA). - -In fact, if you do want to get a new vi I'd suggest VIM-3.0. This is, by -far, the best version of vi I've ever seen (Albert W. Schueller). - -I should mention that VIM is a very good editor and can compete with anything -(Ilya Beloozerov). - -To tell the truth sometimes I used elvis, vile, xvi, calvin, etc. And this is -the reason that I can state that VIM is the best! (Ferenc Deak, Hungary) - -VIM is by far the best editor that I have used in a long time, and I have -looked at just about every thing that is available for every platform that I -use. VIM is the best on all of them. (Guy L. Oliver) - -VIM is the greatest editor since the stone chisel. (Jose Unpingco, USA) - -I would like to say that with VIM I am finally making the 'emacs to vi' -transition - as an Editor it is so much better in many ways: keyboard layout, -memory usage, text alteration to name 3. (Mark Adam) - -In fact, now if I want to know what a particular setting does in vi, I fire up -VIM and check out its help! (Nikhil Patel, USA) - -As a vi user, VIM has made working with text a far more pleasant task than -before I encountered this program. (Steinar Knutsen, Norway) - -I use VIM since version 3.0. Since that time, it is the ONLY editor I use, -with Solaris, Linux and OS/2 Warp. I suggest all my friends to use VIM, they -try, and they continue using it. VIM is really the best software I have ever -downloaded from the Internet, and the best editor I know of. (Marco -Eccettuato, Italy) - - -In summary: - __ ___ _ _ _ ___ _____ ` - \ \ / (_)_ __ ___ (_)___ | | | |/ _ \_ _| ` - \ \ / /| | '_ ` _ \ | / __| | |_| | | | || | ` - \ V / | | | | | | | | \__ \ | _ | |_| || | ` - \_/ |_|_| |_| |_| |_|___/ |_| |_|\___/ |_| ` - ____ _____ _ _ _____ _____ _ _ ` - / ___|_ _| | | | ___| ___| | | ` - \___ \ | | | | | | |_ | |_ | | | ` - ___) || | | |_| | _| | _| |_|_| ` - |____/ |_| \___/|_| |_| (_|_) (Tony Nugent, Australia) ` - - - vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/remote_plugin.txt b/runtime/doc/remote_plugin.txt index 139fcd83b9..dddc021d68 100644 --- a/runtime/doc/remote_plugin.txt +++ b/runtime/doc/remote_plugin.txt @@ -16,8 +16,8 @@ Nvim support for remote plugins *remote-plugin* Extensibility is a primary goal of Nvim. Any programming language may be used to extend Nvim without changes to Nvim itself. This is achieved with remote -plugins, coprocesses that have a direct communication channel (via -|msgpack-rpc|) with the Nvim process. +plugins, coprocesses that have a direct communication channel (via |RPC|) with +the Nvim process. Even though these plugins run in separate processes they can call, be called, and receive events just as if the plugin's code were executed in the main @@ -33,9 +33,9 @@ check whether a plugin host is available for their chosen programming language. Plugin hosts are programs that provide a high-level environment for plugins, taking care of most boilerplate involved in defining commands, autocmds, and -functions that are implemented over |msgpack-rpc| connections. Hosts are -loaded only when one of their registered plugins require it, keeping Nvim's -startup as fast as possible, even if many plugins/hosts are installed. +functions that are implemented over |RPC| connections. Hosts are loaded only +when one of their registered plugins require it, keeping Nvim's startup as +fast as possible, even if many plugins/hosts are installed. ============================================================================== 3. Example *remote-plugin-example* @@ -93,22 +93,22 @@ approach with |rpcnotify()|, meaning return values or exceptions raised in the handler function are ignored. To test the above plugin, it must be saved in "rplugin/python" in a -'runtimepath' directory (~/.config/nvim/rplugin/python/limit.py for example). -Then, the remote plugin manifest must be generated with -`:UpdateRemotePlugins`. +'runtimepath' directory (~/.config/nvim/rplugin/python/limit.py for example). +Then, the remote plugin manifest must be generated with +|:UpdateRemotePlugins|. ============================================================================== 4. Remote plugin manifest *remote-plugin-manifest* + *:UpdateRemotePlugins* Just installing remote plugins to "rplugin/{host}" isn't enough for them to be -automatically loaded when required. You must execute `:UpdateRemotePlugins` +automatically loaded when required. You must execute |:UpdateRemotePlugins| every time a remote plugin is installed, updated, or deleted. -`:UpdateRemotePlugins` generates the remote plugin manifest, a special +|:UpdateRemotePlugins| generates the remote plugin manifest, a special Vimscript file containing declarations for all Vimscript entities (commands/autocommands/functions) defined by all remote plugins, with each -entity associated with the host and plugin path. The manifest is a generated -extension to the user's vimrc (it even has the vimrc filename prepended). +entity associated with the host and plugin path. Manifest declarations are just calls to the `remote#host#RegisterPlugin` function, which takes care of bootstrapping the host as soon as the declared @@ -125,10 +125,20 @@ the example, say the Java plugin is a semantic completion engine for Java code. If it defines the autocommand "BufEnter *.java", then the Java host is spawned only when Nvim loads a buffer matching "*.java". -If the explicit call to `:UpdateRemotePlugins` seems incovenient, try to see it +If the explicit call to |:UpdateRemotePlugins| seems incovenient, try to see it like this: It's a way to provide IDE capabilities in Nvim while still keeping it fast and lightweight for general use. It's also analogous to the |:helptags| command. + *$NVIM_RPLUGIN_MANIFEST* +Unless $NVIM_RPLUGIN_MANIFEST is set the manifest will be written to a file +named `rplugin.vim` at: + + Unix ~ + $XDG_DATA_HOME/nvim/ or ~/.local/share/nvim/ + + Windows ~ + $LOCALAPPDATA/nvim/ or ~/AppData/Local/nvim/ + ============================================================================== vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt index 343d3e62cf..ef98556260 100644 --- a/runtime/doc/repeat.txt +++ b/runtime/doc/repeat.txt @@ -1,4 +1,4 @@ -*repeat.txt* For Vim version 7.4. Last change: 2016 Jan 16 +*repeat.txt* For Vim version 7.4. Last change: 2016 Jul 21 VIM REFERENCE MANUAL by Bram Moolenaar @@ -8,12 +8,14 @@ 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. Debugging scripts |debug-scripts| -6. Profiling |profiling| +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| ============================================================================== 1. Single repeats *single-repeat* @@ -68,8 +70,8 @@ examples. The global commands work by first scanning through the [range] lines and marking each line where a match occurs (for a multi-line pattern, only the start of the match matters). -In a second scan the [cmd] is executed for each marked line with its line -number prepended. For ":v" and ":g!" the command is executed for each not +In a second scan the [cmd] is executed for each marked line, as if the cursor +was in that line. For ":v" and ":g!" the command is executed for each not marked line. If a line is deleted its mark disappears. The default for [range] is the whole buffer (1,$). Use "CTRL-C" to interrupt the command. If an error message is given for a line, the command for that @@ -173,10 +175,12 @@ For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. commands. *:ru* *:runtime* -:ru[ntime][!] {file} .. +:ru[ntime][!] [where] {file} .. Read Ex commands from {file} in each directory given - by 'runtimepath'. There is no error for non-existing - files. Example: > + by 'runtimepath' and/or 'packpath'. There is no error + for non-existing files. + + Example: > :runtime syntax/c.vim < There can be multiple {file} arguments, separated by @@ -190,6 +194,15 @@ For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. When it is not included only the first found file is sourced. + When [where] is omitted only 'runtimepath' is used. + Other values: + START search under "start" in 'packpath' + OPT search under "opt" in 'packpath' + PACK search under "start" and "opt" in + 'packpath' + ALL first use 'runtimepath', then search + under "start" and "opt" in 'packpath' + When {file} contains wildcards it is expanded to all matching files. Example: > :runtime! plugin/*.vim @@ -203,6 +216,59 @@ For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. When 'verbose' is two or higher, there is a message about each searched file. + *:pa* *:packadd* *E919* +:pa[ckadd][!] {name} Search for an optional plugin directory in 'packpath' + and source any plugin files found. The directory must + match: + pack/*/opt/{name} ~ + The directory is added to 'runtimepath' if it wasn't + there yet. + If the directory pack/*/opt/{name}/after exists it is + added at the end of 'runtimepath'. + + Note that {name} is the directory name, not the name + of the .vim file. All the files matching the pattern + pack/*/opt/{name}/plugin/**/*.vim ~ + will be sourced. This allows for using subdirectories + below "plugin", just like with plugins in + 'runtimepath'. + + If the filetype detection was not enabled yet (this + is usually done with a "syntax enable" or "filetype + on" command in your .vimrc file), this will also look + for "{name}/ftdetect/*.vim" files. + + When the optional ! is added no plugin files or + ftdetect scripts are loaded, only the matching + directories are added to 'runtimepath'. This is + useful in your .vimrc. The plugins will then be + loaded during initialization, see |load-plugins|. + + Also see |pack-add|. + + *:packl* *:packloadall* +:packl[oadall][!] Load all packages in the "start" directory under each + entry in 'packpath'. + + First all the directories found are added to + 'runtimepath', then the plugins found in the + directories are sourced. This allows for a plugin to + depend on something of another plugin, e.g. an + "autoload" directory. See |packload-two-steps| for + how this can be useful. + + This is normally done automatically during startup, + after loading your .vimrc file. With this command it + can be done earlier. + + Packages will be loaded only once. After this command + it won't happen again. When the optional ! is added + this command will load packages even when done before. + + An error only causes sourcing the script where it + happens to be aborted, further plugins will be loaded. + See |packages|. + :scripte[ncoding] [encoding] *:scripte* *:scriptencoding* *E167* Specify the character encoding used in the script. The following lines will be converted from [encoding] @@ -220,7 +286,9 @@ For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. ... not converted ... < When conversion isn't supported by the system, there - is no error message and no conversion is done. + is no error message and no conversion is done. When a + line can't be converted there is no error and the + original line is kept. Don't use "ucs-2" or "ucs-4", scripts cannot be in these encodings (they would contain NUL bytes). @@ -373,7 +441,189 @@ Rationale: < Therefore the unusual leading backslash is used. ============================================================================== -5. Debugging scripts *debug-scripts* +5. Using Vim packages *packages* + +A Vim package is a directory that contains one or more plugins. The +advantages over normal plugins: +- A package can be downloaded as an archive and unpacked in its own directory. + Thus the files are not mixed with files of other plugins. That makes it + easy to update and remove. +- A package can be a git, mercurial, etc. repository. That makes it really + easy to update. +- A package can contain multiple plugins that depend on each other. +- A package can contain plugins that are automatically loaded on startup and + ones that are only loaded when needed with `:packadd`. + + +Using a package and loading automatically ~ + +Let's assume your Vim files are in the "~/.local/share/nvim/site" directory +and you want to add a package from a zip archive "/tmp/foopack.zip": + % mkdir -p ~/.local/share/nvim/site/pack/foo + % cd ~/.local/share/nvim/site/pack/foo + % unzip /tmp/foopack.zip + +The directory name "foo" is arbitrary, you can pick anything you like. + +You would now have these files under ~/.local/share/nvim/site: + pack/foo/README.txt + pack/foo/start/foobar/plugin/foo.vim + pack/foo/start/foobar/syntax/some.vim + pack/foo/opt/foodebug/plugin/debugger.vim + +When Vim starts up, after processing your .vimrc, it scans all directories in +'packpath' for plugins under the "pack/*/start" directory. First all those +directories are added to 'runtimepath'. Then all the plugins are loaded. +See |packload-two-steps| for how these two steps can be useful. + +In the example Vim will find "pack/foo/start/foobar/plugin/foo.vim" and adds +"~/.local/share/nvim/site/pack/foo/start/foobar" to 'runtimepath'. + +If the "foobar" plugin kicks in and sets the 'filetype' to "some", Vim will +find the syntax/some.vim file, because its directory is in 'runtimepath'. + +Vim will also load ftdetect files, if there are any. + +Note that the files under "pack/foo/opt" are not loaded automatically, only the +ones under "pack/foo/start". See |pack-add| below for how the "opt" directory +is used. + +Loading packages automatically will not happen if loading plugins is disabled, +see |load-plugins|. + +To load packages earlier, so that 'runtimepath' gets updated: > + :packloadall +This also works when loading plugins is disabled. The automatic loading will +only happen once. + +If the package has an "after" directory, that directory is added to the end of +'runtimepath', so that anything there will be loaded later. + + +Using a single plugin and loading it automatically ~ + +If you don't have a package but a single plugin, you need to create the extra +directory level: + % mkdir -p ~/.local/share/nvim/site/pack/foo/start/foobar + % cd ~/.local/share/nvim/site/pack/foo/start/foobar + % unzip /tmp/someplugin.zip + +You would now have these files: + pack/foo/start/foobar/plugin/foo.vim + pack/foo/start/foobar/syntax/some.vim + +From here it works like above. + + +Optional plugins ~ + *pack-add* +To load an optional plugin from a pack use the `:packadd` command: > + :packadd foodebug +This searches for "pack/*/opt/foodebug" in 'packpath' and will find +~/.local/share/nvim/site/pack/foo/opt/foodebug/plugin/debugger.vim and source +it. + +This could be done if some conditions are met. For example, depending on +whether Vim supports a feature or a dependency is missing. + +You can also load an optional plugin at startup, by putting this command in +your |.vimrc|: > + :packadd! foodebug +The extra "!" is so that the plugin isn't loaded if Vim was started with +|--noplugin|. + +It is perfectly normal for a package to only have files in the "opt" +directory. You then need to load each plugin when you want to use it. + + +Where to put what ~ + +Since color schemes, loaded with `:colorscheme`, are found below +"pack/*/start" and "pack/*/opt", you could put them anywhere. We recommend +you put them below "pack/*/opt", for example +".vim/pack/mycolors/opt/dark/colors/very_dark.vim". + +Filetype plugins should go under "pack/*/start", so that they are always +found. Unless you have more than one plugin for a file type and want to +select which one to load with `:packadd`. E.g. depending on the compiler +version: > + if foo_compiler_version > 34 + packadd foo_new + else + packadd foo_old + endif + +The "after" directory is most likely not useful in a package. It's not +disallowed though. + +============================================================================== +6. Creating Vim packages *package-create* + +This assumes you write one or more plugins that you distribute as a package. + +If you have two unrelated plugins you would use two packages, so that Vim +users can chose what they include or not. Or you can decide to use one +package with optional plugins, and tell the user to add the ones he wants with +`:packadd`. + +Decide how you want to distribute the package. You can create an archive or +you could use a repository. An archive can be used by more users, but is a +bit harder to update to a new version. A repository can usually be kept +up-to-date easily, but it requires a program like "git" to be available. +You can do both, github can automatically create an archive for a release. + +Your directory layout would be like this: + start/foobar/plugin/foo.vim " always loaded, defines commands + start/foobar/plugin/bar.vim " always loaded, defines commands + start/foobar/autoload/foo.vim " loaded when foo command used + start/foobar/doc/foo.txt " help for foo.vim + start/foobar/doc/tags " help tags + opt/fooextra/plugin/extra.vim " optional plugin, defines commands + opt/fooextra/autoload/extra.vim " loaded when extra command used + opt/fooextra/doc/extra.txt " help for extra.vim + opt/fooextra/doc/tags " help tags + +This allows for the user to do: > + mkdir ~/.local/share/nvim/site/pack/myfoobar + cd ~/.local/share/nvim/site/pack/myfoobar + git clone https://github.com/you/foobar.git + +Here "myfoobar" is a name that the user can choose, the only condition is that +it differs from other packages. + +In your documentation you explain what the plugins do, and tell the user how +to load the optional plugin: > + :packadd! fooextra + +You could add this packadd command in one of your plugins, to be executed when +the optional plugin is needed. + +Run the `:helptags` command to generate the doc/tags file. Including this +generated file in the package means that the user can drop the package in his +pack directory and the help command works right away. Don't forget to re-run +the command after changing the plugin help: > + :helptags path/start/foobar/doc + :helptags path/opt/fooextra/doc + + +Dependencies between plugins ~ + *packload-two-steps* +Suppose you have two plugins that depend on the same functionality. You can +put the common functionality in an autoload directory, so that it will be +found automatically. Your package would have these files: + + pack/foo/start/one/plugin/one.vim > + call foolib#getit() +< pack/foo/start/two/plugin/two.vim > + call foolib#getit() +< pack/foo/start/lib/autoload/foolib.vim > + func foolib#getit() + +This works, because loading packages will first add all found directories to +'runtimepath' before sourcing the plugins. + +============================================================================== +7. Debugging scripts *debug-scripts* Besides the obvious messages that you can add to your scripts to find out what they are doing, Vim offers a debug mode. This allows you to step through a @@ -484,7 +734,7 @@ Additionally, these commands can be used: About the additional commands in debug mode: - There is no command-line completion for them, you get the completion for the normal Ex commands only. -- You can shorten them, up to a single character, unless more then one command +- You can shorten them, up to a single character, unless more than one command starts with the same letter. "f" stands for "finish", use "fr" for "frame". - Hitting <CR> will repeat the previous one. When doing another command, this is reset (because it's not clear what you want to repeat). @@ -597,7 +847,7 @@ OBSCURE user, don't use typeahead for debug commands. ============================================================================== -6. Profiling *profile* *profiling* +8. Profiling *profile* *profiling* Profiling means that Vim measures the time that is spent on executing functions and/or scripts. The |+profile| feature is required for this. diff --git a/runtime/doc/sign.txt b/runtime/doc/sign.txt index 44a5361c5d..fd1fe8dce3 100644 --- a/runtime/doc/sign.txt +++ b/runtime/doc/sign.txt @@ -1,4 +1,4 @@ -*sign.txt* For Vim version 7.4. Last change: 2014 May 07 +*sign.txt* For Vim version 7.4. Last change: 2016 Aug 12 VIM REFERENCE MANUAL by Gordon Prieur @@ -40,8 +40,10 @@ There are two steps in using signs: When signs are defined for a file, Vim will automatically add a column of two characters to display them in. When the last sign is unplaced the column -disappears again. The color of the column is set with the SignColumn group -|hl-SignColumn|. Example to set the color: > +disappears again. This behavior can be changed with the 'signcolumn' option. + +The color of the column is set with the SignColumn group |hl-SignColumn|. +Example to set the color: > :highlight SignColumn guibg=darkgrey diff --git a/runtime/doc/spell.txt b/runtime/doc/spell.txt index 752444a3bd..0902d5d10f 100644 --- a/runtime/doc/spell.txt +++ b/runtime/doc/spell.txt @@ -1,4 +1,4 @@ -*spell.txt* For Vim version 7.4. Last change: 2014 Sep 19 +*spell.txt* VIM REFERENCE MANUAL by Bram Moolenaar @@ -11,10 +11,6 @@ Spell checking *spell* 3. Generating a spell file |spell-mkspell| 4. Spell file format |spell-file-format| -Note: There also is a vimspell plugin. If you have it you can do ":help -vimspell" to find about it. But you will probably want to get rid of the -plugin and use the 'spell' option instead, it works better. - ============================================================================== 1. Quick start *spell-quickstart* *E756* @@ -1373,6 +1369,14 @@ the item name. Case is always ignored. The Hunspell feature to use three arguments and flags is not supported. + *spell-NOCOMPOUNDSUGS* +This item indicates that using compounding to make suggestions is not a good +idea. Use this when compounding is used with very short or one-character +words. E.g. to make numbers out of digits. Without this flag creating +suggestions would spend most time trying all kind of weird compound words. + + NOCOMPOUNDSUGS ~ + *spell-SYLLABLE* The SYLLABLE item defines characters or character sequences that are used to count the number of syllables in a word. Example: @@ -1625,4 +1629,111 @@ WORDCHARS (Hunspell) *spell-WORDCHARS* is no need to separate words before checking them (using a trie instead of a hashtable). +============================================================================== +5. Spell checker design *develop-spell* + +When spell checking was going to be added to Vim a survey was done over the +available spell checking libraries and programs. Unfortunately, the result +was that none of them provided sufficient capabilities to be used as the spell +checking engine in Vim, for various reasons: + +- Missing support for multi-byte encodings. At least UTF-8 must be supported, + so that more than one language can be used in the same file. + Doing on-the-fly conversion is not always possible (would require iconv + support). +- For the programs and libraries: Using them as-is would require installing + them separately from Vim. That's mostly not impossible, but a drawback. +- Performance: A few tests showed that it's possible to check spelling on the + fly (while redrawing), just like syntax highlighting. But the mechanisms + used by other code are much slower. Myspell uses a hashtable, for example. + The affix compression that most spell checkers use makes it slower too. +- For using an external program like aspell a communication mechanism would + have to be setup. That's complicated to do in a portable way (Unix-only + would be relatively simple, but that's not good enough). And performance + will become a problem (lots of process switching involved). +- Missing support for words with non-word characters, such as "Etten-Leur" and + "et al.", would require marking the pieces of them OK, lowering the + reliability. +- Missing support for regions or dialects. Makes it difficult to accept + all English words and highlight non-Canadian words differently. +- Missing support for rare words. Many words are correct but hardly ever used + and could be a misspelled often-used word. +- For making suggestions the speed is less important and requiring to install + another program or library would be acceptable. But the word lists probably + differ, the suggestions may be wrong words. + + +Spelling suggestions *develop-spell-suggestions* + +For making suggestions there are two basic mechanisms: +1. Try changing the bad word a little bit and check for a match with a good + word. Or go through the list of good words, change them a little bit and + check for a match with the bad word. The changes are deleting a character, + inserting a character, swapping two characters, etc. +2. Perform soundfolding on both the bad word and the good words and then find + matches, possibly with a few changes like with the first mechanism. + +The first is good for finding typing mistakes. After experimenting with +hashtables and looking at solutions from other spell checkers the conclusion +was that a trie (a kind of tree structure) is ideal for this. Both for +reducing memory use and being able to try sensible changes. For example, when +inserting a character only characters that lead to good words need to be +tried. Other mechanisms (with hashtables) need to try all possible letters at +every position in the word. Also, a hashtable has the requirement that word +boundaries are identified separately, while a trie does not require this. +That makes the mechanism a lot simpler. + +Soundfolding is useful when someone knows how the words sounds but doesn't +know how it is spelled. For example, the word "dictionary" might be written +as "daktonerie". The number of changes that the first method would need to +try is very big, it's hard to find the good word that way. After soundfolding +the words become "tktnr" and "tkxnry", these differ by only two letters. + +To find words by their soundfolded equivalent (soundalike word) we need a list +of all soundfolded words. A few experiments have been done to find out what +the best method is. Alternatives: +1. Do the sound folding on the fly when looking for suggestions. This means + walking through the trie of good words, soundfolding each word and + checking how different it is from the bad word. This is very efficient for + memory use, but takes a long time. On a fast PC it takes a couple of + seconds for English, which can be acceptable for interactive use. But for + some languages it takes more than ten seconds (e.g., German, Catalan), + which is unacceptable slow. For batch processing (automatic corrections) + it's too slow for all languages. +2. Use a trie for the soundfolded words, so that searching can be done just + like how it works without soundfolding. This requires remembering a list + of good words for each soundfolded word. This makes finding matches very + fast but requires quite a lot of memory, in the order of 1 to 10 Mbyte. + For some languages more than the original word list. +3. Like the second alternative, but reduce the amount of memory by using affix + compression and store only the soundfolded basic word. This is what Aspell + does. Disadvantage is that affixes need to be stripped from the bad word + before soundfolding it, which means that mistakes at the start and/or end + of the word will cause the mechanism to fail. Also, this becomes slow when + the bad word is quite different from the good word. + +The choice made is to use the second mechanism and use a separate file. This +way a user with sufficient memory can get very good suggestions while a user +who is short of memory or just wants the spell checking and no suggestions +doesn't use so much memory. + + +Word frequency + +For sorting suggestions it helps to know which words are common. In theory we +could store a word frequency with the word in the dictionary. However, this +requires storing a count per word. That degrades word tree compression a lot. +And maintaining the word frequency for all languages will be a heavy task. +Also, it would be nice to prefer words that are already in the text. This way +the words that appear in the specific text are preferred for suggestions. + +What has been implemented is to count words that have been seen during +displaying. A hashtable is used to quickly find the word count. The count is +initialized from words listed in COMMON items in the affix file, so that it +also works when starting a new file. + +This isn't ideal, because the longer Vim is running the higher the counts +become. But in practice it is a noticeable improvement over not using the word +count. + vim:tw=78:sw=4:ts=8:ft=help:norl: diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index 46efe1996a..9284aaea58 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -1,4 +1,4 @@ -*starting.txt* For Vim version 7.4. Last change: 2015 Jan 15 +*starting.txt* For Vim version 7.4. Last change: 2016 Jul 03 VIM REFERENCE MANUAL by Bram Moolenaar @@ -10,9 +10,11 @@ Starting Vim *starting* 2. Initialization |initialization| 3. $VIM and $VIMRUNTIME |$VIM| 4. Suspending |suspend| -5. Saving settings |save-settings| -6. Views and Sessions |views-sessions| -7. The ShaDa file |shada-file| +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| ============================================================================== 1. Vim arguments *vim-arguments* @@ -40,6 +42,7 @@ filename One or more file names. The first one will be the current nvim -- -filename < All arguments after the "--" will be interpreted as file names, no other options or "+command" argument can follow. + For behavior of quotes on MS-Windows, see |win32-quotes|. *--* - This argument can mean two things, depending on whether Ex @@ -195,7 +198,8 @@ argument. -Z Restricted mode. All commands that make use of an external shell are disabled. This includes suspending with CTRL-Z, ":sh", filtering, the system() function, backtick expansion, - delete(), rename(), mkdir(), writefile(), libcall(), etc. + delete(), rename(), mkdir(), writefile(), libcall(), + jobstart(), etc. *-e* -e Start Vim in Ex mode |Q|. @@ -349,6 +353,9 @@ argument. *-W* -W {scriptout} Like -w, but do not append, overwrite an existing file. + *--api-info* +--api-info Print msgpack-encoded |api-metadata| and exit. + ============================================================================== 2. Initialization *initialization* *startup* @@ -377,7 +384,7 @@ accordingly. Vim proceeds in this order: name, "init.vim" is Neovim specific location for vimrc file. Also see |vimrc-intro|. - Places for your personal initializations: + Places for your personal initializations (see |base-directories|): Unix $XDG_CONFIG_HOME/nvim/init.vim (default for $XDG_CONFIG_HOME is ~/.config) Windows $XDG_CONFIG_HOME/nvim/init.vim @@ -459,6 +466,11 @@ accordingly. Vim proceeds in this order: commands from the command line have not been executed yet. You can use "--cmd 'set noloadplugins'" |--cmd|. + Packages are loaded. These are plugins, as above, but found in the + "start" directory of each entry in 'packpath'. Every plugin directory + found is added in 'runtimepath' and then the plugins are sourced. See + |packages|. + 7. Set 'shellpipe' and 'shellredir' The 'shellpipe' and 'shellredir' options are set according to the value of the 'shell' option, unless they have been set before. @@ -494,8 +506,9 @@ accordingly. Vim proceeds in this order: 14. Execute startup commands If a "-t" flag was given to Vim, the tag is jumped to. The commands given with the |-c| and |+cmd| arguments are executed. - The starting flag is reset, has("vim_starting") will now return zero. If the 'insertmode' option is set, Insert mode is entered. + The starting flag is reset, has("vim_starting") will now return zero. + The |v:vim_did_enter| variable is set to 1. The |VimEnter| autocommands are executed. Some hints on using initializations: @@ -696,7 +709,20 @@ can't paste it in another application (since Vim is going to sleep an attempt to get the selection would make the program hang). ============================================================================== -5. Saving settings *save-settings* +5. Exiting *exiting* + +There are several ways to exit Vim: +- Close the last window with `:quit`. Only when there are no changes. +- Close the last window with `:quit!`. Also when there are changes. +- Close all windows with `:qall`. Only when there are no changes. +- Close all windows with `:qall!`. Also when there are changes. +- 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!`. + +============================================================================== +6. Saving settings *save-settings* Mostly you will edit your vimrc files manually. This gives you the greatest flexibility. There are a few commands to generate a vimrc file automatically. @@ -753,7 +779,7 @@ these steps: You need to escape special characters, esp. spaces. ============================================================================== -6. Views and Sessions *views-sessions* +7. Views and Sessions *views-sessions* This is introduced in sections |21.4| and |21.5| of the user manual. @@ -897,7 +923,7 @@ To automatically save and restore views for *.c files: > au BufWinEnter *.c silent loadview ============================================================================== -7. The ShaDa file *shada* *shada-file* +8. The ShaDa file *shada* *shada-file* If you exit Vim and later start it again, you would normally lose a lot of information. The ShaDa file can be used to remember that information, which @@ -1059,7 +1085,7 @@ even if other entries (with known name/type/etc) are merged. |shada-merging| SHADA FILE NAME *shada-file-name* - The default name of the ShaDa file is "$XDG_DATA_HOME/nvim/shada/main.shada" - for Unix. Default for $XDG_DATA_HOME is ~/.local/share. + for Unix. Default for $XDG_DATA_HOME is ~/.local/share. |base-directories| - The 'n' flag in the 'shada' option can be used to specify another ShaDa file name |'shada'|. - The "-i" Vim argument can be used to set another file name, |-i|. When the @@ -1109,7 +1135,7 @@ files for different types of files (e.g., C code) and load them based on the file name, using the ":autocmd" command (see |:autocmd|). More information on ShaDa file format is contained in |shada-format| section. - *E136* *E138* *shada-error-handling* + *E136* *E929* *shada-error-handling* Some errors make Neovim leave temporary file named `{basename}.tmp.X` (X is any free letter from `a` to `z`) while normally it will create this file, write to it and then rename `{basename}.tmp.X` to `{basename}`. Such errors @@ -1129,7 +1155,7 @@ include: Do not forget to remove the temporary file or replace the target file with temporary one after getting one of the above errors or all attempts to create -a ShaDa file may fail with |E138|. If you got one of them when using +a ShaDa file may fail with |E929|. If you got one of them when using |:wshada| (and not when exiting Neovim: i.e. when you have Neovim session running) you have additional options: @@ -1153,9 +1179,6 @@ running) you have additional options: already set (registers, marks, |v:oldfiles|, etc.) will be overwritten. - *:rv* *:rviminfo* -:rv[iminfo][!] [file] Deprecated alias to |:rshada| command. - *:wsh* *:wshada* *E137* :wsh[ada][!] [file] Write to ShaDa file [file] (default: see above). The information in the file is first read in to make @@ -1164,22 +1187,18 @@ running) you have additional options: internal info is written (also disables safety checks described in |shada-error-handling|). If 'shada' is empty, marks for up to 100 files will be written. - When you get error "E138: All .tmp.X files exist, + When you get error "E929: All .tmp.X files exist, cannot write ShaDa file!" check that no old temp files were left behind (e.g. ~/.local/share/nvim/shada/main.shada.tmp*). Note: Executing :wshada will reset all |'quote| marks. - *:wv* *:wviminfo* -:wv[iminfo][!] [file] Deprecated alias to |:wshada| command. - *:o* *:ol* *:oldfiles* -:o[ldfiles][!] List the files that have marks stored in the ShaDa +: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|. The number can be used with |c_#<|. - Use ! to get a file selection prompt. :bro[wse] o[ldfiles][!] List file names as with |:oldfiles|, and then prompt @@ -1346,4 +1365,40 @@ file when reading and include: either contains more then one MessagePack object or it does not contain complete MessagePack object. +============================================================================== +9. Base Directories *base-directories* *xdg* + +Nvim conforms to the XDG Base Directory Specification for application +configuration and data file locations. This just means Nvim looks for some +optional settings and uses them if they exist, otherwise defaults are chosen. +https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html + +CONFIGURATION DIRECTORY *$XDG_CONFIG_HOME* + + Base directory default: + Unix: ~/.config + Windows: ~/AppData/Local + + Nvim directory: + Unix: ~/.config/nvim/ + Windows: ~/AppData/Local/nvim/ + +DATA DIRECTORY *$XDG_DATA_HOME* + + Base directory default: + Unix: ~/.local/share + Windows: ~/AppData/Local + + Nvim directory: + Unix: ~/.local/share/nvim/ + Windows: ~/AppData/Local/nvim-data/ + +Note on Windows the configuration and data directory defaults are the same +(for lack of an alternative), but the sub-directory for data is named +"nvim-data" to separate it from the configuration sub-directory "nvim". + +Throughout other sections of the user manual, the defaults are used as generic +placeholders, e.g. where "~/.config" is mentioned it should be understood to +mean "$XDG_CONFIG_HOME or ~/.config". + vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt index 81ba639dbe..e59f567826 100644 --- a/runtime/doc/syntax.txt +++ b/runtime/doc/syntax.txt @@ -1,4 +1,4 @@ -*syntax.txt* For Vim version 7.4. Last change: 2015 Dec 19 +*syntax.txt* For Vim version 7.4. Last change: 2016 Aug 10 VIM REFERENCE MANUAL by Bram Moolenaar @@ -936,26 +936,29 @@ To disable them use ":unlet". Example: > :unlet c_comment_strings Variable Highlight ~ -c_gnu GNU gcc specific items -c_comment_strings strings and numbers inside a comment -c_space_errors trailing white space and spaces before a <Tab> -c_no_trail_space_error ... but no trailing spaces -c_no_tab_space_error ... but no spaces before a <Tab> -c_no_bracket_error don't highlight {}; inside [] as errors -c_no_curly_error don't highlight {}; inside [] and () as errors; +*c_gnu* GNU gcc specific items +*c_comment_strings* strings and numbers inside a comment +*c_space_errors* trailing white space and spaces before a <Tab> +*c_no_trail_space_error* ... but no trailing spaces +*c_no_tab_space_error* ... but no spaces before a <Tab> +*c_no_bracket_error* don't highlight {}; inside [] as errors +*c_no_curly_error* don't highlight {}; inside [] and () as errors; except { and } in first column -c_curly_error highlight a missing }; this forces syncing from the + Default is to highlight them, otherwise you + can't spot a missing ")". +*c_curly_error* highlight a missing }; this forces syncing from the start of the file, can be slow -c_no_ansi don't do standard ANSI types and constants -c_ansi_typedefs ... but do standard ANSI types -c_ansi_constants ... but do standard ANSI constants -c_no_utf don't highlight \u and \U in strings -c_syntax_for_h for *.h files use C syntax instead of C++ and use objc +*c_no_ansi* don't do standard ANSI types and constants +*c_ansi_typedefs* ... but do standard ANSI types +*c_ansi_constants* ... but do standard ANSI constants +*c_no_utf* don't highlight \u and \U in strings +*c_syntax_for_h* for *.h files use C syntax instead of C++ and use objc syntax instead of objcpp -c_no_if0 don't highlight "#if 0" blocks as comments -c_no_cformat don't highlight %-formats in strings -c_no_c99 don't highlight C99 standard items -c_no_c11 don't highlight C11 standard items +*c_no_if0* don't highlight "#if 0" blocks as comments +*c_no_cformat* don't highlight %-formats in strings +*c_no_c99* don't highlight C99 standard items +*c_no_c11* don't highlight C11 standard items +*c_no_bsd* don't highlight BSD specific types When 'foldmethod' is set to "syntax" then /* */ comments and { } blocks will become a fold. If you don't want comments to become a fold use: > @@ -1037,6 +1040,21 @@ This works immediately. CLOJURE *ft-clojure-syntax* +The default syntax groups can be augmented through the +*g:clojure_syntax_keywords* and *b:clojure_syntax_keywords* variables. The +value should be a |Dictionary| of syntax group names to a |List| of custom +identifiers: +> + let g:clojure_syntax_keywords = { + \ 'clojureMacro': ["defproject", "defcustom"], + \ 'clojureFunc': ["string/join", "string/replace"] + \ } +< +Refer to the Clojure syntax script for valid syntax group names. + +If the |buffer-variable| *b:clojure_syntax_without_core_keywords* is set, only +language constants and special forms are matched. + Setting *g:clojure_fold* enables folding Clojure code via the syntax engine. Any list, vector, or map that extends over more than one line can be folded using the standard Vim |fold-commands|. @@ -1569,15 +1587,6 @@ as Fvwm2 configuration files, add the following: > :au! BufNewFile,BufRead /etc/X11/fvwm2/* let b:fvwm_version = 2 | \ set filetype=fvwm -If you'd like Vim to highlight all valid color names, tell it where to -find the color database (rgb.txt) on your system. Do this by setting -"rgb_file" to its location. Assuming your color database is located -in /usr/X11/lib/X11/, you should add the line > - - :let rgb_file = "/usr/X11/lib/X11/rgb.txt" - -to your vimrc file. - GSP *gsp.vim* *ft-gsp-syntax* @@ -2886,7 +2895,7 @@ You may wish to embed languages into sh. I'll give an example courtesy of Lorance Stinson on how to do this with awk as an example. Put the following file into $HOME/.config/nvim/after/syntax/sh/awkembed.vim: > - " AWK Embedding: {{{1 + " AWK Embedding: " ============== " Shamelessly ripped from aspperl.vim by Aaron Hope. if exists("b:current_syntax") @@ -3345,6 +3354,13 @@ Note that schemas are not actually limited to plain scalars, but this is the only difference between schemas defined in YAML specification and the only difference defined in the syntax file. + +ZSH *zsh.vim* *ft-zsh-syntax* + +The syntax script for zsh allows for syntax-based folding: > + + :let g:zsh_fold_enable = 1 + ============================================================================== 5. Defining a syntax *:syn-define* *E410* @@ -3422,6 +3438,32 @@ SPELL CHECKING *:syn-spell* To activate spell checking the 'spell' option must be set. +SYNTAX ISKEYWORD SETTING *:syn-iskeyword* + +:sy[ntax] iskeyword [clear | {option}] + This defines the keyword characters. It's like the 'iskeyword' option + for but only applies to syntax highlighting. + + clear: Syntax specific iskeyword setting is disabled and the + buffer-local 'iskeyword' setting is used. + {option} Set the syntax 'iskeyword' option to a new value. + + Example: > + :syntax iskeyword @,48-57,192-255,$,_ +< + This would set the syntax specific iskeyword option to include all + alphabetic characters, plus the numeric characters, all accented + characters and also includes the "_" and the "$". + + If no argument is given, the current value will be output. + + Setting this option influences what |/\k| matches in syntax patterns + 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 + the 'iskeyword' option. DEFINING KEYWORDS *:syn-keyword* @@ -3453,6 +3495,7 @@ DEFINING KEYWORDS *:syn-keyword* isn't, the keyword will never be recognized. Multi-byte characters can also be used. These do not have to be in 'iskeyword'. + See |:syn-iskeyword| for defining syntax specific iskeyword settings. A keyword always has higher priority than a match or region, the keyword is used if more than one item matches. Keywords do not nest @@ -4484,9 +4527,9 @@ in their own color. :colo[rscheme] {name} Load color scheme {name}. This searches 'runtimepath' for the file "colors/{name}.vim". The first one that is found is loaded. - To see the name of the currently active color scheme: > - :colo -< The name is also stored in the g:colors_name variable. + Also searches all plugins in 'packpath', first below + "start" and then under "opt". + Doesn't work recursively, thus you can't use ":colorscheme" in a color scheme script. After the color scheme has been loaded the @@ -4727,6 +4770,10 @@ font={font-name} *highlight-font* All fonts used, except for Menu and Tooltip, should be of the same character size as the default font! Otherwise redrawing problems will occur. + To use a font name with an embedded space or other special character, + put it in single quotes. The single quote cannot be used then. + Example: > + :hi comment font='Monospace 10' guifg={color-name} *highlight-guifg* guibg={color-name} *highlight-guibg* @@ -4817,6 +4864,9 @@ SignColumn column where |signs| are displayed *hl-IncSearch* IncSearch 'incsearch' highlighting; also used for the text replaced with ":s///c" + *hl-Substitute* +Substitute |:substitute| replacement text highlighting + *hl-LineNr* LineNr Line number for ":number" and ":#" commands, and when 'number' or 'relativenumber' option is set. @@ -4848,6 +4898,10 @@ PmenuSbar Popup menu: scrollbar. PmenuThumb Popup menu: Thumb of the scrollbar. *hl-Question* Question |hit-enter| prompt and yes/no questions + *hl-QuickFixLine* +QuickFixLine The selected |quickfix| item in the quickfix window. + |hl-CursorLine| is combined with this when the cursor is on + the currently selected quickfix item. *hl-Search* Search Last search pattern highlighting (see 'hlsearch'). Also used for highlighting the current line in the quickfix @@ -4887,8 +4941,6 @@ TabLineSel tab pages line, active tab page label Title titles for output from ":set all", ":autocmd" etc. *hl-Visual* Visual Visual mode selection - *hl-VisualNOS* -VisualNOS Removed. |vim-differences| {Nvim} *hl-WarningMsg* WarningMsg warning messages *hl-WildMenu* @@ -4992,6 +5044,9 @@ defaults back: > :syntax reset +It is a bit of a wrong name, since it does not reset any syntax items, it only +affects the highlighting. + This doesn't change the colors for the 'highlight' option. Note that the syntax colors that you set in your vimrc file will also be reset diff --git a/runtime/doc/tabpage.txt b/runtime/doc/tabpage.txt index 70e6953211..4ab5b3c759 100644 --- a/runtime/doc/tabpage.txt +++ b/runtime/doc/tabpage.txt @@ -83,14 +83,21 @@ In the GUI tab pages line you can use the right mouse button to open menu. Execute {cmd} and when it opens a new window open a new tab page instead. Doesn't work for |:diffsplit|, |:diffpatch|, |:execute| and |:normal|. - When [count] is omitted the tab page appears after the current - one. - When [count] is specified the new tab page comes after tab - page [count]. Use ":0tab cmd" to get the new tab page as the - first one. + If [count] is given the new tab page appears after the tab + page [count] otherwise the new tab page will appear after the + current one. Examples: > - :tab split " opens current buffer in new tab page - :tab help gt " opens tab page with help for "gt" + :tab split " opens current buffer in new tab page + :tab help gt " opens tab page with help for "gt" + :.tab help gt " as above + :+tab help " opens tab page with help after the next + " tab page + :-tab help " opens tab page with help before the + " current one + :0tab help " opens tab page with help before the + " first one + :$tab help " opens tab page with help after the last + " one CTRL-W gf Open a new tab page and edit the file name under the cursor. See |CTRL-W_gf|. @@ -140,7 +147,7 @@ something else. :{count}tabo[nly][!] Close all tab pages except the {count}th one. > - :.tabonly " 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 diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt index 7d47368ba3..08ffee7a2f 100644 --- a/runtime/doc/term.txt +++ b/runtime/doc/term.txt @@ -473,7 +473,7 @@ correct values. One command can be used to set the screen size: - *:mod* *:mode* *E359* *E362* + *:mod* *:mode* :mod[e] Detects the screen size and redraws the screen. diff --git a/runtime/doc/usr_02.txt b/runtime/doc/usr_02.txt index 6a288f8965..c10643940d 100644 --- a/runtime/doc/usr_02.txt +++ b/runtime/doc/usr_02.txt @@ -1,4 +1,4 @@ -*usr_02.txt* For Vim version 7.4. Last change: 2015 Apr 12 +*usr_02.txt* For Vim version 7.4. Last change: 2016 Jan 16 VIM USER MANUAL - by Bram Moolenaar @@ -397,7 +397,15 @@ original version of the file. Everything you always wanted to know can be found in the Vim help files. Don't be afraid to ask! - To get generic help use this command: > + +If you know what you are looking for, it is usually easier to search for it +using the help system, instead of using Google. Because the subjects follow +a certain style guide. + +Also the help has the advantage of belonging to your particular Vim version. +You won't see help for commands added later. These would not work for you. + +To get generic help use this command: > :help @@ -471,7 +479,7 @@ example, use the following command: > :help 'number' -The table with all mode prefixes can be found here: |help-context|. +The table with all mode prefixes can be found below: |help-summary|. Special keys are enclosed in angle brackets. To find help on the up-arrow key in Insert mode, for instance, use this command: > @@ -488,64 +496,191 @@ You can use the error ID at the start to find help about it: > Summary: *help-summary* > - :help -< Gives you very general help. Scroll down to see a list of all - helpfiles, including those added locally (i.e. not distributed - with Vim). > - :help user-toc.txt -< Table of contents of the User Manual. > - :help :subject -< Ex-command "subject", for instance the following: > - :help :help -< Help on getting help. > - :help abc -< normal-mode command "abc". > - :help CTRL-B -< Control key <C-B> in Normal mode. > - :help i_abc - :help i_CTRL-B -< The same in Insert mode. > - :help v_abc - :help v_CTRL-B -< The same in Visual mode. > - :help c_abc - :help c_CTRL-B -< The same in Command-line mode. > - :help 'subject' -< Option 'subject'. > - :help subject() -< Function "subject". > - :help -subject -< Command-line argument "-subject". > - :help +subject -< Compile-time feature "+subject". > - :help /* -< Regular expression item "*" > - :help EventName -< Autocommand event "EventName". > - :help digraphs.txt -< The top of the helpfile "digraph.txt". - Similarly for any other helpfile. > - :help pattern<Tab> -< Find a help tag starting with "pattern". Repeat <Tab> for - others. > - :help pattern<Ctrl-D> -< See all possible help tag matches "pattern" at once. > - :helpgrep pattern -< Search the whole text of all help files for pattern "pattern". - Jumps to the first match. Jump to other matches with: > - :cn -< next match > - :cprev - :cN -< previous match > - :cfirst - :clast -< first or last match > - :copen - :cclose -< open/close the quickfix window; press <Enter> to jump - to the item under the cursor + +1) Use Ctrl-D after typing a topic and let Vim show all available topics. + Or press Tab to complete: > + :help some<Tab> +< More information on how to use the help: > + :help helphelp + +2) Follow the links in bars to related help. You can go from the detailed + help to the user documentation, which describes certain commands more from + a user perspective and less detailed. E.g. after: > + :help pattern.txt +< You can see the user guide topics |03.9| and |usr_27.txt| in the + introduction. + +3) Options are enclosed in single apostrophes. To go to the help topic for the + list option: > + :help 'list' +< If you only know you are looking for a certain option, you can also do: > + :help options.txt +< to open the help page which describes all option handling and then search + using regular expressions, e.g. textwidth. + Certain options have their own namespace, e.g.: > + :help cpo-<letter> +< for the corresponding flag of the 'cpoptions' settings, substitute <letter> + by a specific flag, e.g.: > + :help cpo-; +< And for the guioption flags: > + :help go-<letter> + +4) Normal mode commands do not have a prefix. To go to the help page for the + "gt" command: > + :help gt + +5) Insert mode commands start with i_. Help for deleting a word: > + :help i_CTRL-W + +6) Visual mode commands start with v_. Help for jumping to the other side of + the Visual area: > + :help v_o + +7) Command line editing and arguments start with c_. Help for using the + command argument %: > + :help c_% + +8) Ex-commands always start with ":", so to go to the :s command help: > + :help :s + +9) Commands specifically for debugging start with ">". To go to to the help + for the "cont" debug command: > + :help >cont + +10) Key combinations. They usually start with a single letter indicating + the mode for which they can be used. E.g.: > + :help i_CTRL-X +< takes you to the family of Ctrl-X commands for insert mode which can be + used to auto complete different things. Note, that certain keys will + always be written the same, e.g. Control will always be CTRL. + For normal mode commands there is no prefix and the topic is available at + :h CTRL-<Letter>. E.g. > + :help CTRL-W +< In contrast > + :help c_CTRL-R +< will describe what the Ctrl-R does when entering commands in the Command + line and > + :help v_Ctrl-A +< talks about incrementing numbers in visual mode and > + :help g_CTRL-A +< talks about the g<C-A> command (e.g. you have to press "g" then <Ctrl-A>). + Here the "g" stand for the normal command "g" which always expects a second + key before doing something similar to the commands starting with "z" + +11) Regexp items always start with /. So to get help for the "\+" quantifier + in Vim regexes: > + :help /\+ +< If you need to know everything about regular expressions, start reading + at: > + :help pattern.txt + +12) Registers always start with "quote". To find out about the special ":" + register: > + :help quote: + +13) Vim Script (VimL) is available at > + :help eval.txt +< Certain aspects of the language are available at :h expr-X where "X" is a + single letter. E.g. > + :help expr-! +< will take you to the topic describing the "!" (Not) operator for + VimScript. + Also important is > + :help function-list +< to find a short description of all functions available. Help topics for + VimL functions always include the "()", so: > + :help append() +< talks about the append VimL function rather than how to append text in the + current buffer. + +14) Mappings are talked about in the help page :h |map.txt|. Use > + :help mapmode-i +< to find out about the |:imap| command. Also use :map-topic + to find out about certain subtopics particular for mappings. e.g: > + :help :map-local +< for buffer-local mappings or > + :help map-bar +< for how the '|' is handled in mappings. + +15) Command definitions are talked about :h command-topic, so use > + :help command-bar +< to find out about the '!' argument for custom commands. + +16) Window management commands always start with CTRL-W, so you find the + corresponding help at :h CTRL-W_letter. E.g. > + :help CTRL-W_p +< for moving the previous accessed window. You can also access > + :help windows.txt +< and read your way through if you are looking for window handling + commands. + +17) Use |:helpgrep| to search in all help pages (and also of any installed + plugins). See |:helpgrep| for how to use it. + To search for a topic: > + :helpgrep topic +< This takes you to the first match. To go to the next one: > + :cnext +< All matches are available in the quickfix window which can be opened + with: > + :copen +< Move around to the match you like and press Enter to jump to that help. + +18) The user manual. This describes help topics for beginners in a rather + friendly way. Start at |usr_toc.txt| to find the table of content (as you + might have guessed): > + :help usr_toc.txt +< Skim over the contents to find interesting topics. The "Digraphs" and + "Entering special characters" items are in chapter 24, so to go to that + particular help page: > + :help usr_24.txt +< Also if you want to access a certain chapter in the help, the chapter + number can be accessed directly like this: > + :help 10.1 +< goes to chapter 10.1 in |usr_10.txt| and talks about recording macros. + +19) Highlighting groups. Always start with hl-groupname. E.g. > + :help hl-WarningMsg +< talks about the WarningMsg highlighting group. + +20) Syntax highlighting is namespaced to :syn-topic e.g. > + :help :syn-conceal +< talks about the conceal argument for the :syn command. + +21) Quickfix commands usually start with :c while location list commands + usually start with :l + +22) Autocommand events can be found by their name: > + :help BufWinLeave +< To see all possible events: > + :help autocommands-events + +23) Command-line switches always start with "-". So for the help of the -f + command switch of Vim use: > + :help -f + +24) Optional features always start with "+". To find out about the + conceal feature use: > + :help +conceal + +25) Documentation for included filetype specific functionality is usually + available in the form ft-<filetype>-<functionality>. So > + :help ft-c-syntax +< talks about the C syntax file and the option it provides. Sometimes, + additional sections for omni completion > + :help ft-php-omni +< or filetype plugins > + :help ft-tex-plugin +< are available. + +26) Error and Warning codes can be looked up directly in the help. So > + :help E297 +< takes you exactly to the description of the swap error message and > + :help W10 +< talks about the warning "Changing a readonly file". + Sometimes however, those error codes are not described, but rather are + listed at the Vim command that usually causes this. So: > + :help E128 +< takes you to the |:function| command ============================================================================== diff --git a/runtime/doc/usr_03.txt b/runtime/doc/usr_03.txt index b8f65d9309..943d7b528c 100644 --- a/runtime/doc/usr_03.txt +++ b/runtime/doc/usr_03.txt @@ -1,4 +1,4 @@ -*usr_03.txt* For Vim version 7.4. Last change: 2015 Dec 12 +*usr_03.txt* For Vim version 7.4. Last change: 2016 Jan 05 VIM USER MANUAL - by Bram Moolenaar @@ -414,8 +414,8 @@ in "the" use: > /the\> The "\>" item is a special marker that only matches at the end of a word. -Similarly "\<" only matches at the begin of a word. Thus to search for the -word "the" only: > +Similarly "\<" only matches at the beginning of a word. Thus to search for +the word "the" only: > /\<the\> diff --git a/runtime/doc/usr_05.txt b/runtime/doc/usr_05.txt index 5aecf33557..f920fd4591 100644 --- a/runtime/doc/usr_05.txt +++ b/runtime/doc/usr_05.txt @@ -1,4 +1,4 @@ -*usr_05.txt* For Vim version 7.4. Last change: 2012 Nov 20 +*usr_05.txt* For Vim version 7.4. Last change: 2016 Mar 28 VIM USER MANUAL - by Bram Moolenaar @@ -12,10 +12,11 @@ Vim's capabilities. Or define your own macros. |05.1| The vimrc file |05.2| The example vimrc file explained |05.3| Simple mappings -|05.4| Adding a plugin -|05.5| Adding a help file -|05.6| The option window -|05.7| Often used options +|05.4| Adding a package +|05.5| Adding a plugin +|05.6| Adding a help file +|05.7| The option window +|05.8| Often used options Next chapter: |usr_06.txt| Using syntax highlighting Previous chapter: |usr_04.txt| Making small changes @@ -245,7 +246,47 @@ The ":map" command (with no arguments) lists your current mappings. At least the ones for Normal mode. More about mappings in section |40.1|. ============================================================================== -*05.4* Adding a plugin *add-plugin* *plugin* +*05.4* Adding a package *add-package* *vimball-install* + +A package is a set of files that you can add to Vim. There are two kinds of +packages: optional and automatically loaded on startup. + +The Vim distribution comes with a few packages that you can optionally use. +For example, the vimball plugin. This plugin supports creating and using +vimballs (self-installing Vim plugin archives). + +To start using the vimball plugin, add one line to your vimrc file: > + packadd vimball + +That's all! You can also type the command to try it out. Now you can find +help about this plugin: > + :help vimball + +This works, because when `:packadd` loaded the plugin it also added the +package directory in 'runtimepath', so that the help file can be found. The +tags for vimball's help are already created. If you need to generate the help +tags for a package, see the `:helptags` command. + +You can find packages on the Internet in various places. It usually comes as +an archive or as a repository. For an archive you can follow these steps: + 1. create the package directory: > + mkdir -p ~/.local/share/nvim/site/pack/fancy +< "fancy" can be any name of your liking. Use one that describes the + package. + 2. unpack the archive in that directory. This assumes the top + directory in the archive is "start": > + cd ~/.local/share/nvim/site/pack/fancy + unzip /tmp/fancy.zip +< If the archive layout is different make sure that you end up with a + path like this: + ~/.local/share/nvim/site/pack/fancy/start/fancytext/plugin/fancy.vim ~ + Here "fancytext" is the name of the package, it can be anything + else. + +More information about packages can be found here: |packages|. + +============================================================================== +*05.5* Adding a plugin *add-plugin* *plugin* Vim's functionality can be extended by adding plugins. A plugin is nothing more than a Vim script file that is loaded automatically when Vim starts. You @@ -299,10 +340,9 @@ Then copy the file to your plugin directory: Example for Unix (assuming you didn't have a plugin directory yet): > mkdir -p ~/.local/share/nvim/site/plugin - cp /usr/local/share/vim/vim60/macros/justify.vim ~/.local/share/nvim/site/plugin + cp /tmp/yourplugin.vim ~/.local/share/nvim/site/plugin -That's all! Now you can use the commands defined in this plugin to justify -text. +That's all! Now you can use the commands defined in this plugin. Instead of putting plugins directly into the plugin/ directory, you may better organize them by putting them into subdirectories under plugin/. @@ -384,7 +424,7 @@ Further reading: |new-filetype| How to detect a new file type. ============================================================================== -*05.5* Adding a help file *add-local-help* +*05.6* Adding a help file *add-local-help* If you are lucky, the plugin you installed also comes with a help file. We will explain how to install the help file, so that you can easily find help @@ -417,7 +457,7 @@ them through the tag. For writing a local help file, see |write-local-help|. ============================================================================== -*05.6* The option window +*05.7* The option window If you are looking for an option that does what you want, you can search in the help files here: |options|. Another way is by using this command: > @@ -456,7 +496,7 @@ border. This is what the 'scrolloff' option does, it specifies an offset from the window border where scrolling starts. ============================================================================== -*05.7* Often used options +*05.8* Often used options There are an awful lot of options. Most of them you will hardly ever use. Some of the more useful ones will be mentioned here. Don't forget you can diff --git a/runtime/doc/usr_12.txt b/runtime/doc/usr_12.txt index 237abae55f..f64a230576 100644 --- a/runtime/doc/usr_12.txt +++ b/runtime/doc/usr_12.txt @@ -237,19 +237,8 @@ simple way: Move the cursor to the word you want to find help on and press > K -Vim will run the external "man" program on the word. If the man page is -found, it is displayed. This uses the normal pager to scroll through the text -(mostly the "more" program). When you get to the end pressing <Enter> will -get you back into Vim. - -A disadvantage is that you can't see the man page and the text you are working -on at the same time. There is a trick to make the man page appear in a Vim -window. First, load the man filetype plugin: > - - :runtime! ftplugin/man.vim - -Put this command in your vimrc file if you intend to do this often. Now you -can use the ":Man" command to open a window on a man page: > +Nvim will run |:Man| on the word. If the man page is found, it is displayed. +You can also use the |:Man| command to open a window on a man page: > :Man csh @@ -267,15 +256,14 @@ window. To display a man page for the word under the cursor, use this: > - \K + K -(If you redefined the <Leader>, use it instead of the backslash). For example, you want to know the return value of "strstr()" while editing this line: if ( strstr (input, "aap") == ) ~ -Move the cursor to somewhere on "strstr" and type "\K". A window will open +Move the cursor to somewhere on "strstr" and type "K". A window will open to display the man page for strstr(). ============================================================================== diff --git a/runtime/doc/usr_25.txt b/runtime/doc/usr_25.txt index 23d76a8b0f..24420353dd 100644 --- a/runtime/doc/usr_25.txt +++ b/runtime/doc/usr_25.txt @@ -1,4 +1,4 @@ -*usr_25.txt* For Vim version 7.4. Last change: 2014 Oct 29 +*usr_25.txt* For Vim version 7.4. Last change: 2016 Mar 28 VIM USER MANUAL - by Bram Moolenaar @@ -196,12 +196,16 @@ Vim has no built-in way of justifying text. However, there is a neat macro package that does the job. To use this package, execute the following command: > - :runtime macros/justify.vim + :packadd justify + +Or put this line in your |vimrc|: > + + packadd! justify This Vim script file defines a new visual command "_j". To justify a block of text, highlight the text in Visual mode and then execute "_j". Look in the file for more explanations. To go there, do "gf" on this name: -$VIMRUNTIME/macros/justify.vim. +$VIMRUNTIME/pack/dist/opt/justify/plugin/justify.vim. An alternative is to filter the text through an external program. Example: > diff --git a/runtime/doc/usr_29.txt b/runtime/doc/usr_29.txt index e495aad06d..9eb66ce83c 100644 --- a/runtime/doc/usr_29.txt +++ b/runtime/doc/usr_29.txt @@ -1,4 +1,4 @@ -*usr_29.txt* For Vim version 7.4. Last change: 2008 Jun 28 +*usr_29.txt* For Vim version 7.4. Last change: 2016 Feb 27 VIM USER MANUAL - by Bram Moolenaar diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt index fc8419a522..191b0871f4 100644 --- a/runtime/doc/usr_41.txt +++ b/runtime/doc/usr_41.txt @@ -1,4 +1,4 @@ -*usr_41.txt* For Vim version 7.4. Last change: 2015 Nov 30 +*usr_41.txt* For Vim version 7.4. Last change: 2016 Aug 07 VIM USER MANUAL - by Bram Moolenaar @@ -592,6 +592,7 @@ String manipulation: *string-functions* match() position where a pattern matches in a string matchend() position where a pattern match ends in a string matchstr() match of a pattern in a string + matchstrpos() match and positions of a pattern in a string matchlist() like matchstr() and also return submatches stridx() first index of a short string in a long string strridx() last index of a short string in a long string @@ -601,13 +602,16 @@ String manipulation: *string-functions* strdisplaywidth() size of string when displayed, deals with tabs substitute() substitute a pattern match with a string submatch() get a specific match in ":s" and substitute() - strpart() get part of a string + strpart() get part of a string using byte index + strcharpart() get part of a string using char index + strgetchar() get character from a string using char index expand() expand special keywords iconv() convert text from one encoding to another byteidx() byte index of a character in a string byteidxcomp() like byteidx() but count composing characters repeat() repeat a string multiple times eval() evaluate a string expression + execute() execute an Ex command and get the output List manipulation: *list-functions* get() get an item without error for wrong index @@ -731,11 +735,14 @@ Working with text in the current buffer: *text-functions* searchpair() find the other end of a start/skip/end searchpairpos() find the other end of a start/skip/end searchdecl() search for the declaration of a name + getcharsearch() return character search information + setcharsearch() set character search information *system-functions* *file-functions* System functions and manipulation of files: glob() expand wildcards globpath() expand wildcards in a number of directories + glob2regpat() convert a glob pattern into a search pattern findfile() find a file in a list of directories finddir() find a directory in a list of directories resolve() find out where a shortcut points to @@ -747,6 +754,7 @@ System functions and manipulation of files: filereadable() check if a file can be read filewritable() check if a file can be written to getfperm() get the permissions of a file + setfperm() set the permissions of a file getftype() get the kind of a file isdirectory() check if a directory exists getfsize() get the size of a file @@ -768,6 +776,7 @@ Date and Time: *date-functions* *time-functions* strftime() convert time to a string reltime() get the current or elapsed time accurately reltimestr() convert reltime() result to a string + reltimefloat() convert reltime() result to a Float *buffer-functions* *window-functions* *arg-functions* Buffers, windows and the argument list: @@ -784,9 +793,18 @@ Buffers, windows and the argument list: tabpagenr() get the number of a tab page tabpagewinnr() like winnr() for a specified tab page winnr() get the window number for the current window + bufwinid() get the window ID of a specific buffer bufwinnr() get the window number of a specific buffer winbufnr() get the buffer number of a specific window getbufline() get a list of lines from the specified buffer + win_findbuf() find windows containing a buffer + win_getid() get window ID of a window + win_gotoid() go to window with ID + win_id2tabwin() get tab and window nr from window ID + win_id2win() get window nr from window ID + getbufinfo() get a list with buffer information + gettabinfo() get a list with tab page information + getwininfo() get a list with window information Command line: *command-line-functions* getcmdline() get the current command line @@ -794,6 +812,7 @@ Command line: *command-line-functions* setcmdpos() set position of the cursor in the command line getcmdtype() return the current command-line type getcmdwintype() return the current command-line window type + getcompletion() list of command-line completion matches Quickfix and location lists: *quickfix-functions* getqflist() list of quickfix errors @@ -889,9 +908,19 @@ Mappings: *mapping-functions* wildmenumode() check if the wildmode is active Testing: *test-functions* - assert_equal() assert that two expressions values are equal + assert_equal() assert that two expressions values are equal + assert_notequal() assert that two expressions values are not equal + assert_inrange() assert that an expression is inside a range + assert_match() assert that a pattern matches the value + assert_notmatch() assert that a pattern does not match the value assert_false() assert that an expression is false assert_true() assert that an expression is true + assert_exception() assert that a command throws an exception + assert_fails() assert that a function call fails + +Timers: *timer-functions* + timer_start() create a timer + timer_stop() stop a timer Various: *various-functions* mode() get current editing mode @@ -916,12 +945,13 @@ Various: *various-functions* shiftwidth() effective value of 'shiftwidth' + wordcount() get byte/word/char count of buffer + taglist() get list of matching tags tagfiles() get a list of tags files py3eval() evaluate Python expression (|+python3|) pyeval() evaluate Python expression (|+python|) - wordcount() get byte/word/char count of buffer ============================================================================== *41.7* Defining a function @@ -1389,9 +1419,9 @@ Now we can instantiate a Dutch translation object: > And a German translator: > :let uk2de = copy(transdict) - :let uk2de.words = {'one': 'ein', 'two': 'zwei', 'three': 'drei'} + :let uk2de.words = {'one': 'eins', 'two': 'zwei', 'three': 'drei'} :echo uk2de.translate('three one') -< drei ein ~ +< drei eins ~ You see that the copy() function is used to make a copy of the "transdict" Dictionary and then the copy is changed to add the words. The original @@ -2224,7 +2254,7 @@ This construct makes sure the function is only defined once: > :endif < -UNDO *undo_ftplugin* +UNDO *undo_indent* *undo_ftplugin* When the user does ":setfiletype xyz" the effect of the previous filetype should be undone. Set the b:undo_ftplugin variable to the commands that will @@ -2239,6 +2269,9 @@ global value. That is mostly the best way to reset the option value. This does require removing the "C" flag from 'cpoptions' to allow line continuation, as mentioned above |use-cpo-save|. +For undoing the effect of an indent script, the b:undo_indent variable should +be set accordingly. + FILE NAME diff --git a/runtime/doc/usr_toc.txt b/runtime/doc/usr_toc.txt index 77ea462a23..e021b806e3 100644 --- a/runtime/doc/usr_toc.txt +++ b/runtime/doc/usr_toc.txt @@ -1,4 +1,4 @@ -*usr_toc.txt* For Vim version 7.4. Last change: 2010 Jul 20 +*usr_toc.txt* For Vim version 7.4. Last change: 2016 Mar 25 VIM USER MANUAL - by Bram Moolenaar @@ -101,10 +101,11 @@ Read this from start to end to learn the essential commands. |05.1| The vimrc file |05.2| The example vimrc file explained |05.3| Simple mappings - |05.4| Adding a plugin - |05.5| Adding a help file - |05.6| The option window - |05.7| Often used options + |05.4| Adding a package + |05.5| Adding a plugin + |05.6| Adding a help file + |05.7| The option window + |05.8| Often used options |usr_06.txt| Using syntax highlighting |06.1| Switching it on diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt index af4224993f..7d08a6f32a 100644 --- a/runtime/doc/various.txt +++ b/runtime/doc/various.txt @@ -1,4 +1,4 @@ -*various.txt* For Vim version 7.4. Last change: 2015 Nov 15 +*various.txt* For Vim version 7.4. Last change: 2016 Jul 09 VIM REFERENCE MANUAL by Bram Moolenaar @@ -220,7 +220,7 @@ g8 Print the hex values of the bytes used in the Like |:enew|, it will fail if the current buffer is modified, but can be forced with "!". See |termopen()| - and |nvim-terminal-emulator| for more information. + and |terminal-emulator|. To switch to terminal mode automatically: > @@ -255,14 +255,20 @@ g8 Print the hex values of the bytes used in the backslashes are before the newline, only one is removed. - On Unix the command normally runs in a non-interactive - shell. If you want an interactive shell to be used - (to use aliases) set 'shellcmdflag' to "-ic". + The command runs in a non-interactive shell connected + to a pipe (not a terminal). Use |:terminal| to run an + interactive shell connected to a terminal. + For Win32 also see |:!start|. After the command has been executed, the timestamp and size of the current file is checked |timestamp|. + If the command produces too much output some lines may + be skipped so the command can execute quickly. No + data is lost, this only affects the display. The last + few lines are always displayed (never skipped). + Vim redraws the screen after the command is finished, because it may have printed any text. This requires a hit-enter prompt, so that you can read any messages. @@ -319,8 +325,7 @@ N *+dialog_con* Support for |:confirm| with console dialog. N *+dialog_con_gui* Support for |:confirm| with GUI and console dialog. N *+digraphs* |digraphs| *E196* N *+eval* expression evaluation |eval.txt| -N *+ex_extra* Vim's extra Ex commands: |:center|, |:left|, - |:normal|, |:retab| and |:right| +N *+ex_extra* always on now, used to be for Vim's extra Ex commands N *+extra_search* |'hlsearch'| and |'incsearch'| options. B *+farsi* |farsi| language N *+file_in_path* |gf|, |CTRL-W_f| and |<cfile>| @@ -376,6 +381,7 @@ B *+termguicolors* 24-bit color in xterm-compatible terminals support 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| N *+user_commands* User-defined commands. |user-commands| @@ -410,14 +416,18 @@ m *+xpm_w32* Win32 GUI only: pixmap support |w32-xpm-support| shown on the screen. When [!] is included, an existing file is overwritten. When [!] is omitted, and {file} exists, this command fails. + Only one ":redir" can be active at a time. Calls to ":redir" will close any active redirection before - starting redirection to the new target. + starting redirection to the new target. For recursive + use check out |execute()|. + To stop the messages and commands from being echoed to the screen, put the commands in a function and call it with ":silent call Function()". - An alternative is to use the 'verbosefile' option, - this can be used in combination with ":redir". + Alternatives are the 'verbosefile' option or + |execute()| function, these can be used in combination + with ":redir". :redi[r] >> {file} Redirect messages to file {file}. Append if {file} already exists. @@ -449,13 +459,15 @@ m *+xpm_w32* Win32 GUI only: pixmap support |w32-xpm-support| redirection starts, if the variable is removed or locked or the variable type is changed, then further command output messages will cause errors. + To get the output of one command the |execute()| + function can be used. :redi[r] =>> {var} Append messages to an existing variable. Only string variables can be used. :redi[r] END End redirecting messages. - *:sil* *:silent* + *:sil* *:silent* *:silent!* :sil[ent][!] {command} Execute {command} silently. Normal messages will not be given or added to the message history. When [!] is added, error messages will also be diff --git a/runtime/doc/vi_diff.txt b/runtime/doc/vi_diff.txt index ec35694c9e..54ef8fecb2 100644 --- a/runtime/doc/vi_diff.txt +++ b/runtime/doc/vi_diff.txt @@ -1,4 +1,4 @@ -*vi_diff.txt* For Vim version 7.4. Last change: 2015 Nov 01 +*vi_diff.txt* For Vim version 7.4. Last change: 2016 Feb 12 VIM REFERENCE MANUAL by Bram Moolenaar diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index 508712ca75..20002c1118 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -12,8 +12,8 @@ these differences. 1. Configuration |nvim-configuration| 2. Defaults |nvim-defaults| -3. Changed features |nvim-features-changed| -4. New features |nvim-features-new| +3. New features |nvim-features| +4. Changed features |nvim-features-changed| 5. Missing legacy features |nvim-features-missing| 6. Removed features |nvim-features-removed| @@ -36,9 +36,10 @@ these differences. - 'autoindent' is set by default - 'autoread' is set by default - 'backspace' defaults to "indent,eol,start" +- 'backupdir' defaults to .,~/.local/share/nvim/backup (|xdg|) - 'complete' doesn't include "i" +- 'directory' defaults to ~/.local/share/nvim/swap// (|xdg|), auto-created - 'display' defaults to "lastline" -- 'encoding' defaults to "utf-8" - 'formatoptions' defaults to "tcqj" - 'history' defaults to 10000 (the maximum) - 'hlsearch' is set by default @@ -46,7 +47,6 @@ these differences. - 'langnoremap' is set by default - 'laststatus' defaults to 2 (statusline is always shown) - 'listchars' defaults to "tab:> ,trail:-,nbsp:+" -- 'mouse' defaults to "a" - 'nocompatible' is always set - 'nrformats' defaults to "bin,hex" - 'sessionoptions' doesn't include "options" @@ -54,11 +54,94 @@ these differences. - 'tabpagemax' defaults to 50 - 'tags' defaults to "./tags;,tags" - 'ttyfast' is always set +- 'undodir' defaults to ~/.local/share/nvim/undo (|xdg|), auto-created - 'viminfo' includes "!" - 'wildmenu' is set by default ============================================================================== -3. Changed features *nvim-features-changed* +3. New Features *nvim-features* + + +MAJOR COMPONENTS ~ + +Embedded terminal emulator |terminal-emulator| +RPC API |RPC| +Shared data |shada| +XDG base directories |xdg| +Job control |job-control| +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: + +- Nvim does not have `-X`, a platform-specific option "sometimes" available in + Vim (with potential surprises: http://stackoverflow.com/q/14635295). Nvim + avoids features that cannot be provided on all platforms--instead that is + delegated to external plugins/extensions. + +- Test-only globals and functions such as test_autochdir(), test_settime(), + etc., are not exposed (because they don't exist). + +ARCHITECTURE ~ + +External plugins run in separate processes. |remote-plugin| This improves +stability and allows those plugins to perform tasks without blocking the +editor. Even "legacy" Python and Ruby plugins which use the old Vim interfaces +(|if_py| and |if_ruby|) run out-of-process. + + +FEATURES ~ + +|bracketed-paste-mode| is built-in and enabled by default. + +|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-/>, +<M-\>, <M-Space>, <M-Enter>, <M-=>, <M-->, <M-?>, <M-$>, ... +META chords are case-sensitive: <M-a> and <M-A> are two different keycodes. + +Some `CTRL-SHIFT-...` key chords are distinguished from `CTRL-...` variants +(even in the terminal). Specifically, the following are known to work: + <C-Tab>, <C-S-Tab>, <C-BS>, <C-S-BS>, <C-Enter>, <C-S-Enter> + +Options: + 'inccommand' shows results while typing a |:substitute| command + 'statusline' supports unlimited alignment sections + 'tabline' %@Func@foo%X can call any function on mouse-click + +Variables: + |v:event| + |v:windowid| is always available (for use by external UIs) + +Commands: + |:CheckHealth| + |:drop| is available on all platforms + |:Man| is available by default, with many improvements such as completion + +Functions: + |dictwatcheradd()| notifies a callback whenever a |Dict| is modified + |dictwatcherdel()| + |execute()| works with |:redir| + |msgpackdump()|, |msgpackparse()| provide msgpack de/serialization + +Events: + |DirChanged| + |TabNewEntered| + |TermClose| + |TermOpen| + |TextYankPost| + +Highlight groups: + |hl-QuickFixLine| + |hl-Substitute| + |hl-TermCursor| + |hl-TermCursorNC| + +============================================================================== +4. Changed features *nvim-features-changed* Nvim always builds with all features, in contrast to Vim which may have certain features removed/added at compile-time. This is like if Vim's "HUGE" @@ -68,7 +151,16 @@ build). If a Python interpreter is available on your `$PATH`, |:python| and |:python3| are always available and may be used simultaneously in separate plugins. The `neovim` pip package must be installed to use Python plugins in Nvim (see -|nvim-python|). +|provider-python|). + +|:!| does not support "interactive" commands. Use |:terminal| instead. +(GUI Vim has a similar limitation, see ":help gui-pty" in Vim.) + +|system()| does not support writing/reading "backgrounded" commands. |E5677| + +Nvim may throttle (skip) messages from shell commands (|:!|, |:grep|, |:make|) +if there is too much output. No data is lost, this only affects display and +makes things faster. |:terminal| output is never throttled. |mkdir()| behaviour changed: 1. Assuming /tmp/foo does not exist and /tmp can be written to @@ -78,7 +170,7 @@ are always available and may be used simultaneously in separate plugins. The 'p')) mkdir() will silently exit. In Vim this was an error. 3. mkdir() error messages now include strerror() text when mkdir fails. -'encoding' cannot be changed after startup. +'encoding' is always "utf-8". |string()| and |:echo| behaviour changed: 1. No maximum recursion depth limit is applied to nested container @@ -127,7 +219,6 @@ Additional differences: compatibility reasons. - |:wviminfo| was renamed to |:wshada|, |:rviminfo| to |:rshada|. Old commands are still kept. -- |:oldfiles| supports !. - When writing (|:wshada| without bang or at exit) it merges much more data, and does this according to the timestamp. Vim merges only marks. |shada-merging| @@ -141,47 +232,13 @@ Additional differences: - ShaDa file keeps search direction (|v:searchforward|), viminfo does not. ============================================================================== -4. New Features *nvim-features-new* - -See |nvim-intro| for a list of Nvim's largest new features. - -|bracketed-paste-mode| is built-in and enabled by default. - -Meta (alt) chords are recognized (even in the terminal). - <M-1>, <M-2>, ... - <M-BS>, <M-Del>, <M-Ins>, ... - <M-/>, <M-\>, ... - <M-Space>, <M-Enter>, <M-=>, <M-->, <M-?>, <M-$>, ... - - Note: Meta chords are case-sensitive (<M-a> is distinguished from <M-A>). - -Some `CTRL-SHIFT-...` key chords are distinguished from `CTRL-...` variants -(even in the terminal). Specifically, the following are known to work: - <C-Tab>, <C-S-Tab> - <C-BS>, <C-S-BS> - <C-Enter>, <C-S-Enter> - -Events: - |TabNew| - |TabNewEntered| - |TabClosed| - |TermOpen| - |TermClose| - -Highlight groups: - |hl-EndOfBuffer| - |hl-TermCursor| - |hl-TermCursorNC| - -============================================================================== 5. Missing legacy features *nvim-features-missing* - *if_ruby* *if_lua* *if_perl* *if_mzscheme* *if_tcl* + *if_lua* *if_perl* *if_mzscheme* *if_tcl* These legacy Vim features may be implemented in the future, but they are not planned for the current milestone. -- vim.bindeval() (new feature in Vim 7.4 Python interface) -- |if_ruby| +- |if_py|: vim.bindeval() and vim.Function() are not supported - |if_lua| - |if_perl| - |if_mzscheme| @@ -192,10 +249,12 @@ planned for the current milestone. These features are in Vim, but have been intentionally removed from Nvim. -Vi-compatible mode: + *'cp'* *'nocompatible'* *'nocp'* *'compatible'* +Nvim is always "non-compatible" with Vi. ":set nocompatible" is ignored ":set compatible" is an error + *'ed'* *'edcompatible'* *'noed'* *'noedcompatible'* Ed-compatible mode: ":set noedcompatible" is ignored ":set edcompatible" is an error @@ -205,8 +264,8 @@ Ed-compatible mode: ":set nottyfast" is an error Encryption support: - 'cryptmethod' - 'key' + *'cryptmethod'* *'cm'* + *'key'* MS-DOS support: 'bioskey' @@ -215,29 +274,43 @@ MS-DOS support: Highlight groups: |hl-VisualNOS| +Test functions: + test_alloc_fail() + test_autochdir() + test_disable_char_avail() + test_garbagecollect_now() + test_null_channel() + test_null_dict() + test_null_job() + test_null_list() + test_null_partial() + test_null_string() + test_settime() + Other options: 'antialias' - 'cpoptions' ('g', 'w', 'H', '*', '-', 'j', and all POSIX flags were removed) - 'guioptions' (only the 't' flag was removed) - 'guipty' - 'imactivatefunc' - 'imactivatekey' - 'imstatusfunc' - 'macatsui' - 'restorescreen' + 'cpoptions' ("g", "w", "H", "*", "-", "j", and all POSIX flags were removed) + 'encoding' ("utf-8" is always used) + 'guioptions' "t" flag was removed + *'guipty'* (Nvim uses pipes and PTYs consistently on all platforms.) + *'imactivatefunc'* *'imaf'* + *'imactivatekey'* *'imak'* + *'imstatusfunc'* *'imsf'* + *'macatsui'* + *'restorescreen'* *'rs'* *'norestorescreen'* *'nors'* 'shelltype' - 'shortname' - 'swapsync' - 'term' - 'termencoding' (Vim 7.4.852 also removed this for Windows) + *'shortname'* *'sn'* *'noshortname'* *'nosn'* + *'swapsync'* *'sws'* + *'term'* *E529* *E530* *E531* + *'termencoding'* *'tenc'* (Vim 7.4.852 also removed this for Windows) 'textauto' 'textmode' - 'toolbar' - 'toolbariconsize' - 'ttybuiltin' - 'ttymouse' - 'ttyscroll' - 'ttytype' + *'toolbar'* *'tb'* + *'toolbariconsize'* *'tbis'* + *'ttybuiltin'* *'tbi'* *'nottybuiltin'* *'notbi'* + *'ttymouse'* *'ttym'* + *'ttyscroll'* *'tsl'* + *'ttytype'* *'tty'* 'weirdinvert' Other commands: @@ -247,6 +320,7 @@ Other commands: :mode (no longer accepts an argument) :open :shell + :smile :tearoff Other compile-time features: diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt index 51b73223b6..5b94626e36 100644 --- a/runtime/doc/windows.txt +++ b/runtime/doc/windows.txt @@ -1,4 +1,4 @@ -*windows.txt* For Vim version 7.4. Last change: 2015 Nov 14 +*windows.txt* For Vim version 7.4. Last change: 2016 Jun 10 VIM REFERENCE MANUAL by Bram Moolenaar @@ -70,6 +70,16 @@ 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. +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 +identifier. There is also the window number, which may change whenever +windows are opened or closed, see |winnr()|. + +Each buffer has a unique number and the number will not change within a Vim +session. The |bufnr()| and |bufname()| functions can be used to convert +between a buffer name and the buffer number. + ============================================================================== 2. Starting Vim *windows-starting* @@ -707,8 +717,8 @@ can also get to them with the buffer list commands, like ":bnext". *:bufdo* :[range]bufdo[!] {cmd} Execute {cmd} in each buffer in the buffer list or if [range] is given only for buffers for which their - buffer name is in the [range]. It works like doing - this: > + buffer number is in the [range]. It works like doing + this: > :bfirst :{cmd} :bnext |