diff options
Diffstat (limited to 'runtime/doc')
77 files changed, 2654 insertions, 1704 deletions
diff --git a/runtime/doc/arabic.txt b/runtime/doc/arabic.txt index a3d979e519..df91b8d065 100644 --- a/runtime/doc/arabic.txt +++ b/runtime/doc/arabic.txt @@ -72,7 +72,7 @@ Arabic requires ISO-8859-6 as well as Presentation Form-B fonts (without Form-B, Arabic will _NOT_ be usable). It is highly recommended that users search for so-called 'ISO-10646-1' fonts. Do an Internet search or check www.arabeyes.org for further -info on where to attain the necessary Arabic fonts. +info on where to obtain the necessary Arabic fonts. Font Installation @@ -118,7 +118,7 @@ o Setting the appropriate character Encoding > :set encoding=utf-8 < - to your vimrc file (entering the command manually into you VIM + to your vimrc file (entering the command manually into your Vim window is highly discouraged). In short, include ':set encoding=utf-8' to your vimrc file. diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 01b21aa085..bf94383ec4 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -215,6 +215,8 @@ BufAdd Just after creating a new buffer which is added to the buffer list, or adding a buffer to the buffer list, a buffer in the buffer list was renamed. + Not triggered for the initial buffers created + during startup. Before |BufEnter|. NOTE: Current buffer "%" may be different from the buffer being created "<afile>". @@ -461,7 +463,7 @@ CompleteDone After Insert mode completion is done. Either *CursorHold* CursorHold When the user doesn't press a key for the time - specified with 'updatetime'. Not re-triggered + specified with 'updatetime'. Not triggered until the user has pressed a key (i.e. doesn't fire every 'updatetime' ms if you leave Vim to make some coffee. :) See |CursorHold-example| @@ -707,7 +709,7 @@ InsertEnter Just before starting Insert mode. Also for string. *InsertLeavePre* InsertLeavePre Just before leaving Insert mode. Also when - using CTRL-O |i_CTRL-O|. Be caseful not to + using CTRL-O |i_CTRL-O|. Be careful not to change mode or use `:normal`, it will likely cause trouble. *InsertLeave* @@ -1207,8 +1209,8 @@ name! :aug[roup]! {name} Delete the autocmd group {name}. Don't use this if there is still an autocommand using this group! You will get a warning if doing - it anyway. when the group is the current group - you will get error E936. + it anyway. When the group is the current + group you will get error E936. To enter autocommands for a specific group, use this method: 1. Select the group with ":augroup {name}". @@ -1267,9 +1269,18 @@ option will not cause any commands to be executed. *:doautoa* *:doautoall* :doautoa[ll] [<nomodeline>] [group] {event} [fname] Like ":doautocmd", but apply the autocommands to each - loaded buffer. Note that [fname] is used to select - the autocommands, not the buffers to which they are - applied. + loaded buffer. The current buffer is done last. + + Note that [fname] is used to select the autocommands, + not the buffers to which they are applied. Example: > + augroup mine + autocmd! + autocmd FileType * echo expand('<amatch>') + augroup END + doautoall mine FileType Loaded-Buffer +< Sourcing this script, you'll see as many + "Loaded-Buffer" echoed as there are loaded buffers. + Careful: Don't use this for autocommands that delete a buffer, change to another buffer or change the contents of a buffer; the result is unpredictable. diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt index 310d244fbc..19a8be1102 100644 --- a/runtime/doc/change.txt +++ b/runtime/doc/change.txt @@ -141,7 +141,7 @@ commands, except "gJ", delete any leading white space on the next line. If the 'joinspaces' option is on, these commands insert two spaces after a '.', '!' or '?'. The 'B' and 'M' flags in 'formatoptions' change the behavior for inserting -spaces before and after a multi-byte character |fo-table|. +spaces before and after a multibyte character |fo-table|. The '[ mark is set at the end of the first line that was joined, '] at the end of the resulting line. @@ -197,7 +197,7 @@ gR Enter Virtual Replace mode: Each character you type start insert (for {Visual} see |Visual-mode|). *v_r* -{Visual}["x]r{char} Replace all selected characters by {char}. +{Visual}r{char} Replace all selected characters by {char}. *v_C* {Visual}["x]C Delete the highlighted lines [into register x] and @@ -610,6 +610,8 @@ Directory for temporary files is created in the first suitable directory of: |cmdline-ranges|. See |:s_flags| for [flags]. + The delimiter doesn't need to be /, see + |pattern-delimiter|. :[range]s[ubstitute] [flags] [count] :[range]&[&][flags] [count] *:&* @@ -621,6 +623,8 @@ Directory for temporary files is created in the first suitable directory of: The space between `:substitute` and the 'c', 'g', 'i', 'I' and 'r' flags isn't required, but in scripts it's a good idea to keep it to avoid confusion. + Also see the two and three letter commands to repeat + :substitute below |:substitute-repeat|. :[range]~[&][flags] [count] *:~* Repeat last substitute with same substitute string @@ -744,7 +748,7 @@ This deletes "TESTING" from all lines, but only one per line. For compatibility with Vi these two exceptions are allowed: "\/{string}/" and "\?{string}?" do the same as "//{string}/r". "\&{string}&" does the same as "//{string}/". - *E146* + *pattern-delimiter* *E146* Instead of the '/' which surrounds the pattern and replacement string, you can use any other single-byte character, but not an alphanumeric character, '\', '"' or '|'. This is useful if you want to include a '/' in the search @@ -841,20 +845,26 @@ either the first or second pattern in parentheses did not match, so either *:sge* *:sgi* *:sgI* *:sgl* *:sgn* *:sgp* *:sgr* *:sI* *:si* *:sic* *:sIc* *:sie* *:sIe* *:sIg* *:sIl* *:sin* *:sIn* *:sIp* *:sip* *:sIr* *:sir* *:sr* *:src* *:srg* *:sri* *:srI* *:srl* - *:srn* *:srp* + *:srn* *:srp* *:substitute-repeat* 2-letter and 3-letter :substitute commands ~ +These commands repeat the previous `:substitute` command with the given flags. +The first letter is always "s", followed by one or two of the possible flag +characters. For example `:sce` works like `:s///ce`. The table lists the +possible combinations, not all flags are possible, because the command is +short for another command. + List of :substitute commands | c e g i I n p l r - | c :sc :sce :scg :sci :scI :scn :scp :scl --- + | c :sc :sce :scg :sci :scI :scn :scp :scl | e | g :sgc :sge :sg :sgi :sgI :sgn :sgp :sgl :sgr - | i :sic :sie --- :si :siI :sin :sip --- :sir + | i :sic :sie :si :siI :sin :sip :sir | I :sIc :sIe :sIg :sIi :sI :sIn :sIp :sIl :sIr | n | p | l - | r :src --- :srg :sri :srI :srn :srp :srl :sr + | r :src :srg :sri :srI :srn :srp :srl :sr Exceptions: :scr is `:scriptnames` @@ -959,9 +969,9 @@ inside of strings can change! Also see 'softtabstop' option. > 5. Copying and moving text *copy-move* *quote* -"{a-zA-Z0-9.%#:-"} Use register {a-zA-Z0-9.%#:-"} for next delete, yank - or put (use uppercase character to append with - delete and yank) ({.%#:} only work with put). +"{register} Use {register} for next delete, yank or put. Use + an uppercase character to append with delete and yank. + Registers ".", "%", "#" and ":" only work with put. *:reg* *:registers* :reg[isters] Display the type and contents of all numbered and @@ -1140,7 +1150,7 @@ Rationale: In Vi the "y" command followed by a backwards motion would With a linewise yank command the cursor is put in the first line, but the column is unmodified, thus it may not be on the first yanked character. -There are ten types of registers: *registers* *E354* +There are ten types of registers: *registers* *{register}* *E354* 1. The unnamed register "" 2. 10 numbered registers "0 to "9 3. The small delete register "- @@ -1400,7 +1410,7 @@ text. Put it in your autoload directory, e.g. ~/.vim/autoload/format.vim: > func! format#Format() " only reformat on explicit gq command if mode() != 'n' - " fall back to Vims internal reformatting + " fall back to Vim's internal reformatting return 1 endif let lines = getline(v:lnum, v:lnum + v:count - 1) @@ -1573,23 +1583,31 @@ can separate the option letters with commas for readability. letter meaning when present in 'formatoptions' ~ + *fo-t* t Auto-wrap text using textwidth + *fo-c* c Auto-wrap comments using textwidth, inserting the current comment leader automatically. + *fo-r* r Automatically insert the current comment leader after hitting <Enter> in Insert mode. + *fo-o* o Automatically insert the current comment leader after hitting 'o' or 'O' in Normal mode. + *fo-q* q Allow formatting of comments with "gq". Note that formatting will not change blank lines or lines containing only the comment leader. A new paragraph starts after such a line, or when the comment leader changes. + *fo-w* w Trailing white space indicates a paragraph continues in the next line. A line that ends in a non-white character ends a paragraph. + *fo-a* a Automatic formatting of paragraphs. Every time text is inserted or deleted the paragraph will be reformatted. See |auto-format|. When the 'c' flag is present this only happens for recognized comments. + *fo-n* n When formatting text, recognize numbered lists. This actually uses the 'formatlistpat' option, thus any kind of list can be used. The indent of the text after the number is used for the next line. The @@ -1600,6 +1618,7 @@ n When formatting text, recognize numbered lists. This actually uses 1. the first item wraps 2. the second item +< *fo-2* 2 When formatting text, use the indent of the second line of a paragraph for the rest of the paragraph, instead of the indent of the first line. This supports paragraphs in which the first line has a @@ -1609,36 +1628,46 @@ n When formatting text, recognize numbered lists. This actually uses second line of the same paragraph third line. < This also works inside comments, ignoring the comment leader. + *fo-v* v Vi-compatible auto-wrapping in insert mode: Only break a line at a blank that you have entered during the current insert command. (Note: this is not 100% Vi compatible. Vi has some "unexpected features" or bugs in this area. It uses the screen column instead of the line column.) + *fo-b* b Like 'v', but only auto-wrap if you enter a blank at or before the wrap margin. If the line was longer than 'textwidth' when you started the insert, or you do not enter a blank in the insert before reaching 'textwidth', Vim does not perform auto-wrapping. + *fo-l* l Long lines are not broken in insert mode: When a line was longer than 'textwidth' when the insert command started, Vim does not automatically format it. -m Also break at a multi-byte character above 255. This is useful for + *fo-m* +m Also break at a multibyte character above 255. This is useful for Asian text where every character is a word on its own. -M When joining lines, don't insert a space before or after a multi-byte + *fo-M* +M When joining lines, don't insert a space before or after a multibyte character. Overrules the 'B' flag. -B When joining lines, don't insert a space between two multi-byte + *fo-B* +B When joining lines, don't insert a space between two multibyte characters. Overruled by the 'M' flag. + *fo-1* 1 Don't break a line after a one-letter word. It's broken before it instead (if possible). + *fo-]* ] Respect textwidth rigorously. With this flag set, no line can be longer than textwidth, unless line-break-prohibition rules make this impossible. Mainly for CJK scripts and works only if 'encoding' is "utf-8". + *fo-j* j Where it makes sense, remove a comment leader when joining lines. For example, joining: int i; // the index ~ // in the list ~ Becomes: int i; // the index in the list ~ + *fo-p* p Don't break lines at single spaces that follow periods. This is intended to complement 'joinspaces' and |cpo-J|, for prose with sentences separated by two spaces. For example, with 'textwidth' set @@ -1696,7 +1725,7 @@ Some examples: Automatic formatting *auto-format* *autoformat* When the 'a' flag is present in 'formatoptions' text is formatted -automatically when inserting text or deleting text. This works nice for +automatically when inserting text or deleting text. This works nicely for editing text paragraphs. A few hints on how to use this: - You need to properly define paragraphs. The simplest is paragraphs that are @@ -1783,6 +1812,8 @@ found here: |sort()|, |uniq()|. When /{pattern}/ is specified and there is no [r] flag the text matched with {pattern} is skipped, so that you sort on what comes after the match. + 'ignorecase' applies to the pattern, but 'smartcase' + is not used. Instead of the slash any non-letter can be used. For example, to sort on the second comma-separated field: > diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt index 098245b5a8..ae43aeeb25 100644 --- a/runtime/doc/cmdline.txt +++ b/runtime/doc/cmdline.txt @@ -119,7 +119,7 @@ CTRL-K {char1} {char2} *c_CTRL-K* enter digraph (see |digraphs|). When {char1} is a special key, the code for that key is inserted in <> form. -CTRL-R {0-9a-z"%#:-=.} *c_CTRL-R* *c_<C-R>* +CTRL-R {register} *c_CTRL-R* *c_<C-R>* Insert the contents of a numbered or named register. Between typing CTRL-R and the second character '"' will be displayed to indicate that you are expected to enter the name of a @@ -178,8 +178,8 @@ CTRL-R CTRL-L *c_CTRL-R_CTRL-L* *c_<C-R>_<C-L>* *c_CTRL-R_CTRL-R* *c_<C-R>_<C-R>* *c_CTRL-R_CTRL-O* *c_<C-R>_<C-O>* -CTRL-R CTRL-R {0-9a-z"%#:-=. CTRL-F CTRL-P CTRL-W CTRL-A CTRL-L} -CTRL-R CTRL-O {0-9a-z"%#:-=. CTRL-F CTRL-P CTRL-W CTRL-A CTRL-L} +CTRL-R CTRL-R {register CTRL-F CTRL-P CTRL-W CTRL-A CTRL-L} +CTRL-R CTRL-O {register CTRL-F CTRL-P CTRL-W CTRL-A CTRL-L} Insert register or object under the cursor. Works like |c_CTRL-R| but inserts the text literally. For example, if register a contains "xy^Hz" (where ^H is a backspace), @@ -443,6 +443,10 @@ emulate it. For example, this mimics autolist=ambiguous: This will find the longest match with the first 'wildchar', then list all matching files with the next. + *complete-script-local-functions* +When completing user function names, prepend "s:" to find script-local +functions. + *suffixes* For file name completion you can use the 'suffixes' option to set a priority between files with almost the same name. If there are multiple matches, @@ -553,14 +557,17 @@ followed by another Vim command: :command :cscope :debug + :eval :folddoopen :folddoclosed :function :global :help + :helpgrep :lcscope :ldo :lfdo + :lhelpgrep :make :normal :perlfile @@ -572,6 +579,7 @@ followed by another Vim command: :read ! :scscope :sign + :terminal :vglobal :windo :write ! @@ -752,7 +760,7 @@ three lines: > < Visual Mode and Range *v_:* - + *:star-visual-range* {Visual}: Starts a command-line with the Visual selected lines as a range. The code `:'<,'>` is used for this range, which makes it possible to select a similar line from the command-line @@ -824,34 +832,37 @@ it, no matter how many backslashes. \\# \# Also see |`=|. - *:<cword>* *<cword>* *:<cWORD>* *<cWORD>* - *:<cexpr>* *<cexpr>* *:<cfile>* *<cfile>* - *:<afile>* *<afile>* *:<abuf>* *<abuf>* - *:<amatch>* *<amatch>* - *:<sfile>* *<sfile>* *:<slnum>* *<slnum>* - *:<sflnum>* *<sflnum>* *E499* *E500* + *E499* *E500* Note: these are typed literally, they are not special keys! + *:<cword>* *<cword>* <cword> is replaced with the word under the cursor (like |star|) + *:<cWORD>* *<cWORD>* <cWORD> is replaced with the WORD under the cursor (see |WORD|) + *:<cexpr>* *<cexpr>* <cexpr> is replaced with the word under the cursor, including more to form a C expression. E.g., when the cursor is on "arg" of "ptr->arg" then the result is "ptr->arg"; when the cursor is on "]" of "list[idx]" then the result is "list[idx]". This is used for |v:beval_text|. + *:<cfile>* *<cfile>* <cfile> is replaced with the path name under the cursor (like what |gf| uses) + *:<afile>* *<afile>* <afile> When executing autocommands, is replaced with the file name of the buffer being manipulated, or the file for a read or write. *E495* + *:<abuf>* *<abuf>* <abuf> When executing autocommands, is replaced with the currently effective buffer number (for ":r file" and ":so file" it is the current buffer, the file being read/sourced is not in a buffer). *E496* + *:<amatch>* *<amatch>* <amatch> When executing autocommands, is replaced with the match for which this autocommand was executed. *E497* It differs from <afile> only when the file name isn't used to match with (for FileType, Syntax and SpellFileMissing events). + *:<sfile>* *<sfile>* <sfile> When executing a ":source" command, is replaced with the file name of the sourced file. *E498* When executing a function, is replaced with: @@ -860,10 +871,12 @@ Note: these are typed literally, they are not special keys! "function {function-name1}[{lnum}]..{function-name2}[{lnum}]" Note that filename-modifiers are useless when <sfile> is used inside a function. + *:<slnum>* *<slnum>* <slnum> When executing a ":source" command, is replaced with the line number. *E842* When executing a function it's the line number relative to the start of the function. + *:<sflnum>* *<sflnum>* <sflnum> When executing a script, is replaced with the line number. It differs from <slnum> in that <sflnum> is replaced with the script line number in any situation. *E961* @@ -898,7 +911,7 @@ These modifiers can be given, in this order: separator is removed. Thus ":p:h" on a directory name results on the directory name itself (without trailing slash). When the file name is an absolute path (starts with "/" for - Unix; "x:\" for Windows), that part is not removed. + Unix; "x:\" for Win32), that part is not removed. When there is no head (path is relative to current directory) the result is empty. :t Tail of the file name (last component of the name). Must @@ -1074,7 +1087,8 @@ CTRL-C Continue in Command-line mode. The command-line under the in Normal mode. There is no redraw, thus the window will remain visible. :quit Discard the command line and go back to Normal mode. - ":close", ":exit", ":xit" and CTRL-\ CTRL-N also work. + ":close", CTRL-W c, ":exit", ":xit" and CTRL-\ CTRL-N also + work. :qall Quit Vim, unless there are changes in some buffer. :qall! Quit Vim, discarding changes to any buffer. diff --git a/runtime/doc/diff.txt b/runtime/doc/diff.txt index 3544882ceb..a9e2a0d522 100644 --- a/runtime/doc/diff.txt +++ b/runtime/doc/diff.txt @@ -57,11 +57,12 @@ reset to the global value. The options can still be overruled from a modeline when re-editing the file. However, 'foldmethod' and 'wrap' won't be set from a modeline when 'diff' is set. +See `:diffoff` for an easy way to revert the options. The differences shown are actually the differences in the buffer. Thus if you make changes after loading a file, these will be included in the displayed diffs. You might have to do ":diffupdate" now and then, not all changes are -immediately taken into account. +immediately taken into account, especially when using an external diff command. In your vimrc file you could do something special when Vim was started in diff mode. You could use a construct like this: > diff --git a/runtime/doc/digraph.txt b/runtime/doc/digraph.txt index 271b8c2597..b7dc16341d 100644 --- a/runtime/doc/digraph.txt +++ b/runtime/doc/digraph.txt @@ -30,6 +30,8 @@ An alternative is using the 'keymap' option. it is the Unicode character, see |digraph-encoding|. Example: > :digr e: 235 a: 228 +< You can use `:exe` to enter a hex number: > + :exe 'digr += ' .. 0x2A72 < Avoid defining a digraph with '_' (underscore) as the first character, it has a special meaning in the future. diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt index aa964a521f..4700af41b7 100644 --- a/runtime/doc/editing.txt +++ b/runtime/doc/editing.txt @@ -63,10 +63,14 @@ g CTRL-G Prints the current position of the cursor in five ways: Column, Line, Word, Character and Byte. If the number of Characters and Bytes is the same then the Character position is omitted. + If there are characters in the line that take more than one position on the screen (<Tab> or special - character), both the "real" column and the screen - column are shown, separated with a dash. + character), or characters using more than one byte per + column (characters above 0x7F when 'encoding' is + utf-8), both the byte column and the screen column are + shown, separated by a dash. + Also see the 'ruler' option and the |wordcount()| function. @@ -298,10 +302,13 @@ CTRL-^ Edit the alternate file. Mostly the alternate file is *gF* [count]gF Same as "gf", except if a number follows the file name, then the cursor is positioned on that line in - the file. The file name and the number must be - separated by a non-filename (see 'isfname') and - non-numeric character. White space between the - filename, the separator and the number are ignored. + the file. + The file name and the number must be separated by a + non-filename (see 'isfname') and non-numeric + character. " line " is also recognized, like it is + used in the output of `:verbose command UserCmd` + White space between the filename, the separator and + the number are ignored. Examples: eval.c:10 ~ eval.c @ 20 ~ @@ -439,6 +446,9 @@ This edits the same file again with 'fileformat' set to "unix". > :w ++enc=latin1 newfile This writes the current buffer to "newfile" in latin1 format. +The message given when writing a file will show "[converted]" when +'fileencoding' or the value specified with ++enc differs from 'encoding'. + There may be several ++opt arguments, separated by white space. They must all appear before any |+cmd| argument. @@ -508,15 +518,16 @@ If you start editing a new file and the 'fileformats' option is not empty (which is the default), Vim will try to detect whether the lines in the file are separated by the specified formats. When set to "unix,dos", Vim will check for lines with a single <NL> (as used on Unix) or by a <CR><NL> pair -(Windows). Only when ALL lines end in <CR><NL>, 'fileformat' is set to "dos", -otherwise it is set to "unix". When 'fileformats' includes "mac", and no <NL> -characters are found in the file, 'fileformat' is set to "mac". +(MS-Windows). Only when ALL lines end in <CR><NL>, 'fileformat' is +set to "dos", otherwise it is set to "unix". When 'fileformats' includes +"mac", and no <NL> characters are found in the file, 'fileformat' is set to +"mac". -If the 'fileformat' option is set to "dos" on non-Windows systems the message -"[dos format]" is shown to remind you that something unusual is happening. On -Windows systems you get the message "[unix format]" if 'fileformat' is set to -"unix". On all systems but the Macintosh you get the message "[mac format]" -if 'fileformat' is set to "mac". +If the 'fileformat' option is set to "dos" on non-MS-Windows systems the +message "[dos format]" is shown to remind you that something unusual is +happening. On MS-Windows systems you get the message "[unix format]" if +'fileformat' is set to "unix". On all systems but the Macintosh you get the +message "[mac format]" if 'fileformat' is set to "mac". If the 'fileformats' option is empty and DOS format is used, but while reading a file some lines did not end in <CR><NL>, "[CR missing]" will be included in @@ -607,7 +618,7 @@ list of the current window. :args ## x < This will add the "x" item and sort the new list. -:argd[elete] {pattern} .. *:argd* *:argdelete* *E480* +:argd[elete] {pattern} .. *:argd* *:argdelete* *E480* *E610* Delete files from the argument list that match the {pattern}s. {pattern} is used like a file pattern, see |file-pattern|. "%" can be used to delete the @@ -617,7 +628,7 @@ list of the current window. Example: > :argdel *.obj -:[range]argd[elete] Delete the {range} files from the argument list. +:[range]argd[elete] Delete the [range] files from the argument list. Example: > :10,$argdel < Deletes arguments 10 and further, keeping 1-9. > @@ -965,7 +976,7 @@ to write anyway add a '!' to the command. *write-permissions* When writing a new file the permissions are read-write. For unix the mask is -0666 with additionally umask applied. When writing a file that was read Vim +0o666 with additionally umask applied. When writing a file that was read Vim will preserve the permissions, but clear the s-bit. *write-readonly* @@ -984,7 +995,7 @@ original file fails, there will be an error message telling you that you lost the original file. *DOS-format-write* -If the 'fileformat' is "dos", <CR> <NL> is used for <EOL>. This is default +If the 'fileformat' is "dos", <CR><NL> is used for <EOL>. This is default for Windows. On other systems the message "[dos format]" is shown to remind you that an unusual <EOL> was used. *Unix-format-write* @@ -1018,11 +1029,11 @@ When the file name is actually a device name, Vim will not make a backup (that would be impossible). You need to use "!", since the device already exists. Example for Unix: > :w! /dev/lpt0 -and Windows: > +and MS-Windows: > :w! lpt0 For Unix a device is detected when the name doesn't refer to a normal file or a directory. A fifo or named pipe also looks like a device to Vim. -For Windows the device is detected by its name: +For MS-Windows the device is detected by its name: CON CLOCK$ NUL @@ -1036,9 +1047,9 @@ The names can be in upper- or lowercase. *:q* *:quit* :q[uit] Quit the current window. Quit Vim if this is the last - window. This fails when changes have been made and - Vim refuses to |abandon| the current buffer, and when - the last file in the argument list has not been + |edit-window|. This fails when changes have been made + and Vim refuses to |abandon| the current buffer, and + when the last file in the argument list has not been edited. If there are other tab pages and quitting the last window in the current tab page the current tab page is @@ -1063,18 +1074,22 @@ The names can be in upper- or lowercase. code. See |:cq|. *:wq* -:wq [++opt] Write the current file and quit. Writing fails when - the file is read-only or the buffer does not have a - name. Quitting fails when the last file in the - argument list has not been edited. - -:wq! [++opt] Write the current file and quit. Writing fails when - the current buffer does not have a name. - -:wq [++opt] {file} Write to {file} and quit. Quitting fails when the +:wq [++opt] Write the current file and close the window. If this + was the last |edit-window| Vim quits. + Writing fails when the file is read-only or the buffer + does not have a name. Quitting fails when the last + file in the argument list has not been edited. + +:wq! [++opt] Write the current file and close the window. If this + was the last |edit-window| Vim quits. Writing fails + when the current buffer does not have a name. + +:wq [++opt] {file} Write to {file} and close the window. If this was the + last |edit-window| Vim quits. Quitting fails when the last file in the argument list has not been edited. -:wq! [++opt] {file} Write to {file} and quit. +:wq! [++opt] {file} Write to {file} and close the current window. Quit + Vim if this was the last |edit-window|. :[range]wq[!] [++opt] [file] Same as above, but only write the lines in [range]. @@ -1091,10 +1106,10 @@ The names can be in upper- or lowercase. Same as :xit. *ZZ* -ZZ Write current file, if modified, and quit (same as - ":x"). (Note: If there are several windows for the - current file, the file is written if it was modified - and the window is closed). +ZZ Write current file, if modified, and close the current + window (same as ":x"). + If there are several windows for the current file, + only the current window is closed. *ZQ* ZQ Quit without checking for changes (same as ":q!"). @@ -1195,13 +1210,13 @@ For versions of Vim where browsing is not supported, the command is executed unmodified. *browsefilter* -For Windows you can modify the filters that are used in the browse dialog. By -setting the g:browsefilter or b:browsefilter variables, you can change the -filters globally or locally to the buffer. The variable is set to a string in -the format "{filter label}\t{pattern};{pattern}\n" where {filter label} is the -text that appears in the "Files of Type" comboBox, and {pattern} is the -pattern which filters the filenames. Several patterns can be given, separated -by ';'. +For MS-Windows you can modify the filters that are used in the browse +dialog. By setting the g:browsefilter or b:browsefilter variables, you can +change the filters globally or locally to the buffer. The variable is set to +a string in the format "{filter label}\t{pattern};{pattern}\n" where {filter +label} is the text that appears in the "Files of Type" comboBox, and {pattern} +is the pattern which filters the filenames. Several patterns can be given, +separated by ';'. For example, to have only Vim files in the dialog, you could use the following command: > @@ -1248,7 +1263,7 @@ exist, the next-higher scope in the hierarchy applies. Does not change the meaning of an already opened file, because its full path name is remembered. Files from the |arglist| may change though! - On Windows this also changes the active drive. + On MS-Windows this also changes the active drive. To change to the directory of the current file: > :cd %:h < @@ -1279,7 +1294,7 @@ exist, the next-higher scope in the hierarchy applies. *:lch* *:lchdir* :lch[dir][!] Same as |:lcd|. - *:lcd-* + *:lcd-* :lc[d][!] - Change to the previous current directory (before the previous ":lcd {path}" command). @@ -1323,7 +1338,7 @@ to 0, 'modeline' off, 'expandtab' off). Setting the 'binary' option has the same effect. Don't forget to do this before reading the file. There are a few things to remember when editing binary files: -- When editing executable files the number of characters must not change. +- When editing executable files the number of bytes must not change. Use only the "R" or "r" command to change text. Do not delete characters with "x" or by backspacing. - Set the 'textwidth' option to 0. Otherwise lines will unexpectedly be @@ -1335,8 +1350,8 @@ There are a few things to remember when editing binary files: It is also possible that you get an "out of memory" error when reading the file. - Make sure the 'binary' option is set BEFORE loading the - file. Otherwise both <CR> <NL> and <NL> are considered to end a line - and when the file is written the <NL> will be replaced with <CR> <NL>. + file. Otherwise both <CR><NL> and <NL> are considered to end a line + and when the file is written the <NL> will be replaced with <CR><NL>. - <Nul> characters are shown on the screen as ^@. You can enter them with "CTRL-V CTRL-@" or "CTRL-V 000". - To insert a <NL> character in the file split a line. When writing the @@ -1372,7 +1387,7 @@ focus. If you want to automatically reload a file when it has been changed outside of Vim, set the 'autoread' option. This doesn't work at the moment you write the file though, only when the file wasn't changed inside of Vim. - + *ignore-timestamp* If you do not want to be asked or automatically reload the file, you can use this: > set buftype=nofile diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index b8dcfd0ff4..b4630a97bb 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -17,7 +17,9 @@ Using expressions is introduced in chapter 41 of the user manual |usr_41.txt|. *E712* There are six types of variables: -Number A 32 or 64 bit signed number. |expr-number| *Number* + *Number* *Integer* +Number A 32 or 64 bit signed number. |expr-number| + The number of bits is available in |v:numbersize|. Examples: -123 0x10 0177 0b1011 Float A floating point number. |floating-point-format| *Float* @@ -73,8 +75,9 @@ base, use |str2nr()|. *TRUE* *FALSE* *Boolean* For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE. -You can also use |v:false| and |v:true|. When TRUE is returned from a -function it is the Number one, FALSE is the number zero. +You can also use |v:false| and |v:true|. +When TRUE is returned from a function it is the Number one, FALSE is the +number zero. Note that in the command: > :if "foo" @@ -110,7 +113,7 @@ You will not get an error if you try to change the type of a variable. 1.2 Function references ~ - *Funcref* *E695* *E718* + *Funcref* *E695* *E718* A Funcref variable is obtained with the |function()| function, the |funcref()| function or created with the lambda expression |expr-lambda|. It can be used in an expression in the place of a function name, before the parenthesis @@ -536,6 +539,8 @@ adict. Weeding out entries from a Dictionary can be done with |filter()|: > :call filter(dict, 'v:val =~ "x"') This removes all entries from "dict" with a value not matching 'x'. +This can also be used to remove all entries: > + call filter(dict, 0) Dictionary function ~ @@ -688,7 +693,7 @@ Example: > All expressions within one level are parsed from left to right. -expr1 *expr1* *E109* +expr1 *expr1* *trinary* *E109* ----- expr2 ? expr1 : expr1 @@ -941,11 +946,14 @@ in any order. E.g., these are all possible: expr8[expr1] item of String or |List| *expr-[]* *E111* *subscript* - +In legacy Vim script: 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, or use `split()` to turn the string into a list of characters. +expr1'th single byte from expr8. expr8 is used as a String (a number is +automatically converted to a String), expr1 as a Number. This doesn't +recognize multibyte encodings, see `byteidx()` for an alternative, or use +`split()` to turn the string into a list of characters. Example, to get the +byte under the cursor: > + :let c = getline(".")[col(".") - 1] 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 @@ -968,10 +976,13 @@ error. expr8[expr1a : expr1b] substring or sublist *expr-[:]* -If expr8 is a Number or String this results in the substring with the bytes -from expr1a to and including expr1b. expr8 is used as a String, expr1a and -expr1b are used as a Number. This doesn't recognize multi-byte encodings, see -|byteidx()| for computing the indexes. +If expr8 is a String this results in the substring with the bytes or +characters from expr1a to and including expr1b. expr8 is used as a String, +expr1a and expr1b are used as a Number. + +In legacy Vim script the indexes are byte indexes. This doesn't recognize +multibyte encodings, see |byteidx()| for computing the indexes. If expr8 is +a Number it is first converted to a String. If expr1a is omitted zero is used. If expr1b is omitted the length of the string minus one is used. @@ -984,6 +995,7 @@ expr1b is smaller than expr1a the result is an empty string. Examples: > :let c = name[-1:] " last byte of a string + :let c = name[0:-1] " the whole string :let c = name[-2:-2] " last but one byte of a string :let s = line(".")[4:] " from the fifth byte to the end :let s = s[:-3] " remove last two bytes @@ -1237,7 +1249,7 @@ the following ways: The arguments are optional. Example: > :let F = {-> 'error function'} - :echo F() + :echo F('ignored') < error function *closure* Lambda expressions can access outer scope variables and arguments. This is @@ -1292,6 +1304,7 @@ An internal variable is explicitly destroyed with the ":unlet" command Using a name that is not an internal variable or refers to a variable that has been destroyed results in an error. + *variable-scope* There are several name spaces for variables. Which one is to be used is specified by what is prepended: @@ -1664,6 +1677,9 @@ v:fcs_choice What should happen after a |FileChangedShell| event was The default is empty. If another (invalid) value is used then Vim behaves like it is empty, there is no warning message. + *v:fname* *fname-variable* +v:fname The file name set by 'includeexpr'. Empty otherwise. + *v:fname_in* *fname_in-variable* v:fname_in The name of the input file. Valid while evaluating: option used for ~ @@ -1792,6 +1808,16 @@ v:null Special value used to put "null" in JSON and NIL in msgpack. operator) and to zero when used as a Number (e.g. in |expr5| or |expr7| when used with numeric operators). Read-only. + *v:numbermax* *numbermax-variable* +v:numbermax Maximum value of a number. + + *v:numbermin* *numbermin-variable* +v:numbermin Minimum value of a number (negative) + + *v:numbersize* *numbersize-variable* +v:numbersize Number of bits in a Number. This is normally 64, but on some + systems it may be 32. + *v:oldfiles* *oldfiles-variable* v:oldfiles List of file names that is loaded from the |shada| file on startup. These are the files that Vim remembers marks for. @@ -2189,12 +2215,14 @@ getjumplist([{winnr} [, {tabnr}]]) List list of jump list items getline({lnum}) String line {lnum} of current buffer getline({lnum}, {end}) List lines {lnum} to {end} of current buffer -getloclist({nr} [, {what}]) List list of location list items +getloclist({nr}) List list of location list items +getloclist({nr}, {what}) Dict get specific location list properties getmarklist([{expr}]) List list of global/local marks getmatches([{win}]) List list of current matches getpid() Number process ID of Vim getpos({expr}) List position of cursor, mark, etc. -getqflist([{what}]) List list of quickfix items +getqflist() List list of quickfix items +getqflist({what}) Dict get specific quickfix list properties getreg([{regname} [, 1 [, {list}]]]) String or List contents of register getregtype([{regname}]) String type of register @@ -2377,12 +2405,15 @@ setcmdpos({pos}) Number set cursor position in command-line setenv({name}, {val}) none set environment variable setfperm({fname}, {mode} Number set {fname} file permissions to {mode} setline({lnum}, {line}) Number set line {lnum} to {line} -setloclist({nr}, {list}[, {action}[, {what}]]) +setloclist({nr}, {list} [, {action}]) Number modify location list using {list} +setloclist({nr}, {list}, {action}, {what}) + Number modify specific location list props setmatches({list} [, {win}]) Number restore a list of matches setpos({expr}, {list}) Number set the {expr} position to {list} -setqflist({list}[, {action}[, {what}]] - Number modify quickfix list using {list} +setqflist({list} [, {action}]) Number modify quickfix list using {list} +setqflist({list}, {action}, {what}) + Number modify specific quickfix list props setreg({n}, {v}[, {opt}]) Number set register to value and type settabvar({nr}, {varname}, {val}) set {varname} in tab page {nr} to {val} settabwinvar({tabnr}, {winnr}, {varname}, {val}) set {varname} in window @@ -2506,9 +2537,10 @@ win_id2tabwin({expr}) List get tab and window nr from |window-ID| win_id2win({expr}) Number get window nr from |window-ID| win_screenpos({nr}) List get screen position of window {nr} win_splitmove({nr}, {target} [, {options}]) - none move window {nr} to split of {target} + Number move window {nr} to split of {target} winbufnr({nr}) Number buffer number of window {nr} wincol() Number window column of the cursor +windowsversion() String MS-Windows OS version winheight({nr}) Number height of window {nr} winlayout([{tabnr}]) List layout of windows in tab {tabnr} winline() Number window line of the cursor @@ -2585,6 +2617,9 @@ append({lnum}, {text}) *append()* appendbufline({expr}, {lnum}, {text}) *appendbufline()* Like |append()| but append the text in buffer {expr}. + This function works only for loaded buffers. First call + |bufload()| if needed. + For the use of {expr}, see |bufname()|. {lnum} is used like with |append()|. Note that using |line()| @@ -2626,7 +2661,7 @@ arglistid([{winnr} [, {tabnr}]]) {winnr} can be the window number or the |window-ID|. *argv()* -argv([{nr} [, {winid}]) +argv([{nr} [, {winid}]]) The result is the {nr}th file in the argument list. See |arglist|. "argv(0)" is the first one. Example: > :let i = 0 @@ -2641,123 +2676,6 @@ argv([{nr} [, {winid}]) The {winid} argument specifies the window ID, see |argc()|. For the Vim command line arguments see |v:argv|. -assert_beeps({cmd}) *assert_beeps()* - Run {cmd} and add an error message to |v:errors| if it does - NOT produce a beep or visual bell. - Also see |assert_fails()|, |assert_nobeep()| and - |assert-return|. - - *assert_equal()* -assert_equal({expected}, {actual}, [, {msg}]) - When {expected} and {actual} are not equal an error message is - added to |v:errors| and 1 is returned. Otherwise zero is - returned |assert-return|. - There is no automatic conversion, the String "4" is different - from the Number 4. And the number 4 is different from the - Float 4.0. The value of 'ignorecase' is not used here, case - always matters. - When {msg} is omitted an error in the form "Expected - {expected} but got {actual}" is produced. - Example: > - assert_equal('foo', 'bar') -< Will result in a string to be added to |v:errors|: - test.vim line 12: Expected 'foo' but got 'bar' ~ - - *assert_equalfile()* -assert_equalfile({fname-one}, {fname-two} [, {msg}]) - When the files {fname-one} and {fname-two} do not contain - exactly the same text an error message is added to |v:errors|. - Also see |assert-return|. - When {fname-one} or {fname-two} does not exist the error will - mention that. - -assert_exception({error} [, {msg}]) *assert_exception()* - When v:exception does not contain the string {error} an error - message is added to |v:errors|. Also see |assert-return|. - This can be used to assert that a command throws an exception. - Using the error number, followed by a colon, avoids problems - with translations: > - try - commandthatfails - call assert_false(1, 'command should have failed') - catch - call assert_exception('E492:') - endtry - -assert_fails({cmd} [, {error} [, {msg}]]) *assert_fails()* - Run {cmd} and add an error message to |v:errors| if it does - NOT produce an error. Also see |assert-return|. - When {error} is given it must match in |v:errmsg|. - Note that beeping is not considered an error, and some failing - commands only beep. Use |assert_beeps()| for those. - -assert_false({actual} [, {msg}]) *assert_false()* - When {actual} is not false an error message is added to - |v:errors|, like with |assert_equal()|. - Also see |assert-return|. - A value is false when it is zero or |v:false|. When "{actual}" - is not a number or |v:false| the assert fails. - When {msg} is omitted an error in the form - "Expected False but got {actual}" is produced. - -assert_inrange({lower}, {upper}, {actual} [, {msg}]) *assert_inrange()* - This asserts number and |Float| values. When {actual} is lower - than {lower} or higher than {upper} an error message is added - to |v:errors|. Also see |assert-return|. - When {msg} is omitted an error in the form - "Expected range {lower} - {upper}, 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|. Also see |assert-return|. - - {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_nobeep({cmd}) *assert_nobeep()* - Run {cmd} and add an error message to |v:errors| if it - produces a beep or visual bell. - Also see |assert_beeps()|. - - *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. - Also see |assert-return|. - - *assert_notmatch()* -assert_notmatch({pattern}, {actual} [, {msg}]) - The opposite of `assert_match()`: add an error message to - |v:errors| when {pattern} matches {actual}. - Also see |assert-return|. - -assert_report({msg}) *assert_report()* - Report a test failure directly, using {msg}. - Always returns one. - -assert_true({actual} [, {msg}]) *assert_true()* - When {actual} is not true an error message is added to - |v:errors|, like with |assert_equal()|. - Also see |assert-return|. - A value is |TRUE| when it is a non-zero number or |v:true|. - When {actual} is not a number or |v:true| the assert fails. - When {msg} is omitted an error in the form "Expected True but - got {actual}" is produced. - asin({expr}) *asin()* Return the arc sine of {expr} measured in radians, as a |Float| in the range of [-pi/2, pi/2]. @@ -2770,6 +2688,9 @@ asin({expr}) *asin()* < -0.523599 +assert_ functions are documented here: |assert-functions-details| + + atan({expr}) *atan()* Return the principal value of the arc tangent of {expr}, in the range [-pi/2, +pi/2] radians, as a |Float|. @@ -2901,7 +2822,7 @@ bufnr([{expr} [, {create}]]) the ":ls" command. For the use of {expr}, see |bufname()| above. If the buffer doesn't exist, -1 is returned. Or, if the - {create} argument is present and not zero, a new, unlisted, + {create} argument is present and TRUE, a new, unlisted, buffer is created and its number is returned. bufnr("$") is the last buffer: > :let last_buffer = bufnr("$") @@ -2945,8 +2866,8 @@ byteidx({expr}, {nr}) *byteidx()* Return byte index of the {nr}'th character in the string {expr}. Use zero for the first character, it then returns zero. - This function is only useful when there are multibyte - characters, otherwise the returned value is equal to {nr}. + If there are no multibyte characters the returned value is + equal to {nr}. Composing characters are not counted separately, their byte length is added to the preceding base character. See |byteidxcomp()| below for counting composing characters @@ -2973,6 +2894,8 @@ 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 differently 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 @@ -3166,7 +3089,7 @@ complete_check() *complete_check()* *complete_info()* complete_info([{what}]) - Returns a Dictionary with information about Insert mode + Returns a |Dictionary| with information about Insert mode completion. See |ins-completion|. The items are: mode Current completion mode name string. @@ -3198,7 +3121,7 @@ complete_info([{what}]) "function" User defined completion |i_CTRL-X_CTRL-U| "omni" Omni completion |i_CTRL-X_CTRL-O| "spell" Spelling suggestions |i_CTRL-X_s| - "eval" |complete()| completion + "eval" |complete()| completion "unknown" Other internal modes If the optional {what} list argument is supplied, then only @@ -3237,7 +3160,7 @@ confirm({msg} [, {choices} [, {default} [, {type}]]]) not need to be the first letter: > confirm("file has been modified", "&Save\nSave &All") < For the console, the first letter of each choice is used as - the default shortcut key. + the default shortcut key. Case is ignored. The optional {default} argument is the number of the choice that is made if the user hits <CR>. Use 1 to make the first @@ -3418,6 +3341,7 @@ deepcopy({expr}[, {noref}]) *deepcopy()* *E698* copy, and vice versa. When an item is a |List|, a copy for it is made, recursively. Thus changing an item in the copy does not change the contents of the original |List|. + When {noref} is omitted or zero a contained |List| or |Dictionary| is only copied once. All references point to this single copy. With {noref} set to 1 every occurrence of a @@ -3442,14 +3366,18 @@ delete({fname} [, {flags}]) *delete()* Note: on MS-Windows it is not possible to delete a directory that is being used. - The result is a Number, which is 0 if the delete operation was - successful and -1 when the deletion failed or partly failed. + The result is a Number, which is 0/false if the delete + operation was successful and -1/true when the deletion failed + or partly failed. deletebufline({expr}, {first}[, {last}]) *deletebufline()* Delete lines {first} to {last} (inclusive) from buffer {expr}. If {last} is omitted then delete line {first} only. On success 0 is returned, on failure 1 is returned. + This function works only for loaded buffers. First call + |bufload()| if needed. + For the use of {expr}, see |bufname()| above. {first} and {last} are used like with |setline()|. Note that @@ -3533,6 +3461,12 @@ diff_hlID({lnum}, {col}) *diff_hlID()* The highlight ID can be used with |synIDattr()| to obtain syntax information about the highlighting. +empty({expr}) *empty()* + Return the Number 1 if {expr} is empty, zero otherwise. + A |List| or |Dictionary| is empty when it does not have any + items. A Number is empty when its value is zero. Special + variable is empty when it is |v:false| or |v:null|. + environ() *environ()* Return all of environment variables as dictionary. You can check if an environment variable exists like this: > @@ -3541,12 +3475,6 @@ environ() *environ()* use this: > :echo index(keys(environ()), 'HOME', 0, 1) != -1 -empty({expr}) *empty()* - Return the Number 1 if {expr} is empty, zero otherwise. - A |List| or |Dictionary| is empty when it does not have any - items. A Number is empty when its value is zero. Special - variable is empty when it is |v:false| or |v:null|. - escape({string}, {chars}) *escape()* Escape the characters in {chars} that occur in {string} with a backslash. Example: > @@ -3574,16 +3502,15 @@ executable({expr}) *executable()* arguments. executable() uses the value of $PATH and/or the normal searchpath for programs. *PATHEXT* - On Windows the ".exe", ".bat", etc. can - optionally be included. Then the extensions in $PATHEXT are - tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be - found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is - used. A dot by itself can be used in $PATHEXT to try using - the name without an extension. When 'shell' looks like a - Unix shell, then the name is also tried without adding an - extension. - On Windows it only checks if the file exists and - is not a directory, not if it's really executable. + On MS-Windows the ".exe", ".bat", etc. can optionally be + included. Then the extensions in $PATHEXT are tried. Thus if + "foo.exe" does not exist, "foo.exe.bat" can be found. If + $PATHEXT is not set then ".exe;.com;.bat;.cmd" is used. A dot + by itself can be used in $PATHEXT to try using the name + without an extension. When 'shell' looks like a Unix shell, + then the name is also tried without adding an extension. + On MS-Windows it only checks if the file exists and is not a + directory, not if it's really executable. On Windows an executable in the same directory as Vim is always found (it is added to $PATH at |startup|). The result is a Number: @@ -3810,8 +3737,8 @@ expandcmd({expr}) *expandcmd()* Expand special items in {expr} like what is done for an Ex command such as `:edit`. This expands special keywords, like with |expand()|, and environment variables, anywhere in - {expr}. Returns the expanded string. - Example: > + {expr}. "~user" and "~/path" are only expanded at the start. + Returns the expanded string. Example: > :echo expandcmd('make %<.o') < extend({expr1}, {expr2} [, {expr3}]) *extend()* @@ -3819,10 +3746,10 @@ extend({expr1}, {expr2} [, {expr3}]) *extend()* |Dictionaries|. If they are |Lists|: Append {expr2} to {expr1}. - If {expr3} is given insert the items of {expr2} before item - {expr3} in {expr1}. When {expr3} is zero insert before the - first item. When {expr3} is equal to len({expr1}) then - {expr2} is appended. + If {expr3} is given insert the items of {expr2} before the + item with index {expr3} in {expr1}. When {expr3} is zero + insert before the first item. When {expr3} is equal to + len({expr1}) then {expr2} is appended. Examples: > :echo sort(extend(mylist, [7, 5])) :call extend(mylist, [2, 3], 1) @@ -3987,7 +3914,7 @@ flatten({list} [, {maxdepth}]) *flatten()* a very large number. The {list} is changed in place, make a copy first if you do not want that. - *E964* + *E900* {maxdepth} means how deep in nested lists changes are made. {list} is not modified when {maxdepth} is 0. {maxdepth} must be positive number. @@ -4073,7 +4000,8 @@ fnamemodify({fname}, {mods}) *fnamemodify()* :echo fnamemodify("main.c", ":p:h") < results in: > /home/mool/vim/vim/src -< Note: Environment variables don't work in {fname}, use +< If {mods} is empty then {fname} is returned. + Note: Environment variables don't work in {fname}, use |expand()| first then. foldclosed({lnum}) *foldclosed()* @@ -4237,7 +4165,7 @@ getbufinfo([{dict}]) Without an argument information about all the buffers is returned. - When the argument is a Dictionary only the buffers matching + 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. @@ -4251,28 +4179,36 @@ getbufinfo([{dict}]) Each returned List item is a dictionary with the following entries: - bufnr buffer number. + bufnr Buffer number. changed TRUE if the buffer is modified. - changedtick number of changes made to the buffer. + changedtick Number of changes made to the buffer. hidden TRUE if the buffer is hidden. - lastused timestamp in seconds, like + lastused Timestamp in seconds, like |localtime()|, when the buffer was last used. listed TRUE if the buffer is listed. - lnum current line number in buffer. - linecount number of lines in the buffer (only + lnum Line number used for the buffer when + opened in the current window. + Only valid if the buffer has been + displayed in the window in the past. + If you want the line number of the + last known cursor position in a given + window, use |line()|: > + :echo line('.', {winid}) +< + linecount Number of lines in the buffer (only valid when loaded) loaded TRUE if the buffer is loaded. - name full path to the file in the buffer. - signs list of signs placed in the buffer. + 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 + variables A reference to the dictionary with buffer-local variables. - windows list of |window-ID|s that display this + windows List of |window-ID|s that display this buffer Examples: > @@ -4318,9 +4254,9 @@ getbufvar({expr}, {varname} [, {def}]) *getbufvar()* The result is the value of option or local buffer variable {varname} in buffer {expr}. Note that the name without "b:" must be used. - When {varname} is empty returns a dictionary with all the + When {varname} is empty returns a |Dictionary| with all the buffer-local variables. - When {varname} is equal to "&" returns a dictionary with all + 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. @@ -4390,7 +4326,9 @@ getchar([expr]) *getchar()* endif < There is no prompt, you will somehow have to make clear to the - user that a character has to be typed. + user that a character has to be typed. The screen is not + redrawn, e.g. when resizing the window. + There is no mapping for the character. Key codes are replaced, thus when the user presses the <Del> key you get the code for the <Del> key, not the raw character @@ -4510,7 +4448,7 @@ getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* highlight highlight groups history :history suboptions locale locale names (as output of locale -a) - mapclear buffer argument + mapclear buffer argument mapping mapping name menu menus messages |:messages| suboptions @@ -4543,10 +4481,11 @@ getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* *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] ~ - The "curswant" number is the preferred column when moving the + includes an extra "curswant" in the list: + [0, lnum, col, off, curswant] ~ + The "curswant" number is the preferred column when moving the cursor vertically. Also see |getpos()|. + The first "bufnum" item is always zero. This can be used to save and restore the cursor position: > let save_cursor = getcurpos() @@ -4683,7 +4622,7 @@ getline({lnum} [, {end}]) < To get lines from another buffer see |getbufline()| getloclist({nr},[, {what}]) *getloclist()* - Returns a list with all the entries in the location list for + Returns a |List| with all the entries in the location list for window {nr}. {nr} can be the window number or the |window-ID|. When {nr} is zero the current window is used. @@ -4699,7 +4638,16 @@ getloclist({nr},[, {what}]) *getloclist()* field is applicable only when called from a location list window. See |location-list-file-window| for more details. -getmarklist([{expr}] *getmarklist()* + Returns a |Dictionary| with default values if there is no + location list for the window {nr}. + Returns an empty Dictionary if window {nr} does not exist. + + Examples (See also |getqflist-examples|): > + :echo getloclist(3, {'all': 0}) + :echo getloclist(5, {'filewinid': 0}) + + +getmarklist([{expr}]) *getmarklist()* Without the {expr} argument returns a |List| with information about all the global marks. |mark| @@ -4707,7 +4655,7 @@ getmarklist([{expr}] *getmarklist()* local marks defined in buffer {expr}. For the use of {expr}, see |bufname()|. - Each item in the retuned List is a |Dict| with the following: + Each item in the returned List is a |Dict| with the following: name - name of the mark prefixed by "'" pos - a |List| with the position of the mark: [bufnum, lnum, col, off] @@ -4760,6 +4708,10 @@ getpos({expr}) Get the position for {expr}. For possible values of {expr} Note that for '< and '> Visual mode matters: when it is "V" (visual line mode) the column of '< is zero and the column of '> is a large number. + The column number in the returned List is the byte position + within the line. + The column number can be very large, e.g. 2147483647, in which + case it means "after the end of the line". This can be used to save and restore the position of a mark: > let save_a_mark = getpos("'a") ... @@ -4768,7 +4720,7 @@ getpos({expr}) Get the position for {expr}. For possible values of {expr} getqflist([{what}]) *getqflist()* - Returns a list with all the current quickfix errors. Each + Returns a |List| with all the current quickfix errors. Each list item is a dictionary with these entries: bufnr number of buffer that has the file name, use bufname() to get the name @@ -4890,12 +4842,12 @@ getregtype([{regname}]) *getregtype()* 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. + 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: + Each List item is a |Dictionary| with the following entries: tabnr tab page number. variables a reference to the dictionary with tabpage-local variables @@ -4917,7 +4869,7 @@ gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* 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. + 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:". @@ -4966,17 +4918,17 @@ gettagstack([{nr}]) *gettagstack()* See |tagstack| for more information about the tag stack. getwininfo([{winid}]) *getwininfo()* - Returns information about windows as a List with Dictionaries. + 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. + is returned, as a |List| with one item. If the window does not + exist the result is an empty list. Without {winid} information about all the windows in all the tab pages is returned. - Each List item is a Dictionary with the following entries: - botline last displayed buffer line + Each List item is a |Dictionary| with the following entries: + botline last complete displayed buffer line bufnr number of buffer in the window height window height (excluding winbar) loclist 1 if showing a location list @@ -4989,13 +4941,15 @@ getwininfo([{winid}]) *getwininfo()* width window width winbar 1 if the window has a toolbar, 0 otherwise - wincol leftmost screen column of the window + wincol leftmost screen column of the window; + "col" from |win_screenpos()| winid |window-ID| winnr window number - winrow topmost screen column of the window + winrow topmost screen line of the window; + "row" from |win_screenpos()| getwinpos([{timeout}]) *getwinpos()* - The result is a list with two numbers, the result of + The result is a |List| with two numbers, the result of |getwinposx()| and |getwinposy()| combined: [x-pos, y-pos] {timeout} can be used to specify how long to wait in msec for @@ -5042,7 +4996,7 @@ glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()* 'suffixes' affect the ordering of matches. 'wildignorecase' always applies. - When {list} is present and it is |TRUE| the result is a List + When {list} is present and it is |TRUE| the result is a |List| with all matching files. The advantage of using a List is, you also get filenames containing newlines correctly. Otherwise the result is a String and when there are several @@ -5100,7 +5054,7 @@ globpath({path}, {expr} [, {nosuf} [, {list} [, {allinks}]]]) one of the patterns in 'wildignore' will be skipped and 'suffixes' affect the ordering of matches. - When {list} is present and it is |TRUE| the result is a List + When {list} is present and it is |TRUE| the result is a |List| with all matching files. The advantage of using a List is, you also get filenames containing newlines correctly. Otherwise the result is a String and when there are several matches, @@ -5121,6 +5075,16 @@ has({feature}) Returns 1 if {feature} is supported, 0 otherwise. The {feature} argument is a feature name like "nvim-0.2.1" or "win32", see below. See also |exists()|. + If the code has a syntax error, then Nvim may skip the rest + of the line and miss |:endif|. > + if has('feature') | let x = this->breaks->without->the->feature | endif +< + Put |:if| and |:endif| on separate lines to avoid the + syntax error. > + if has('feature') + let x = this->breaks->without->the->feature + endif +< Vim's compile-time feature-names (prefixed with "+") are not recognized because Nvim is always compiled with all possible features. |feature-compile| @@ -5166,8 +5130,8 @@ has({feature}) Returns 1 if {feature} is supported, 0 otherwise. The 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. + The result is a Number, which is TRUE if |Dictionary| {dict} + has an entry with key {key}. FALSE otherwise. haslocaldir([{winnr}[, {tabnr}]]) *haslocaldir()* The result is a Number, which is 1 when the tabpage or window @@ -5185,16 +5149,16 @@ haslocaldir([{winnr}[, {tabnr}]]) *haslocaldir()* 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 - contains {what} in somewhere in the rhs (what it is mapped to) - and this mapping exists in one of the modes indicated by - {mode}. + The result is a Number, which is TRUE if there is a mapping + that contains {what} in somewhere in the rhs (what it is + mapped to) and this mapping exists in one of the modes + indicated by {mode}. When {abbr} is there and it is |TRUE| use abbreviations instead of mappings. Don't forget to specify Insert and/or Command-line mode. Both the global mappings and the mappings local to the current buffer are checked for a match. - If no matching mapping is found 0 is returned. + If no matching mapping is found FALSE is returned. The following characters are recognized in {mode}: n Normal mode v Visual mode @@ -5225,8 +5189,8 @@ histadd({history}, {item}) *histadd()* character is sufficient. If {item} does already exist in the history, it will be shifted to become the newest entry. - The result is a Number: 1 if the operation was successful, - otherwise 0 is returned. + The result is a Number: TRUE if the operation was successful, + otherwise FALSE is returned. Example: > :call histadd("input", strftime("%Y %b %d")) @@ -5245,8 +5209,8 @@ histdel({history} [, {item}]) *histdel()* an index, see |:history-indexing|. The respective entry will be removed if it exists. - The result is a Number: 1 for a successful operation, - otherwise 0 is returned. + The result is TRUE for a successful operation, otherwise FALSE + is returned. Examples: Clear expression register history: > @@ -5289,7 +5253,7 @@ histnr({history}) *histnr()* :let inp_index = histnr("expr") < hlexists({name}) *hlexists()* - The result is a Number, which is non-zero if a highlight group + The result is a Number, which is TRUE if a highlight group called {name} exists. This is when the group has been defined in some way. Not necessarily when highlighting has been defined for it, it may also have been used for a syntax @@ -5464,10 +5428,11 @@ inputlist({textlist}) *inputlist()* displayed, one string per line. The user will be prompted to enter a number, which is returned. The user can also select an item by clicking on it with the - mouse. For the first string 0 is returned. When clicking - above the first item a negative number is returned. When - clicking on the prompt one more than the length of {textlist} - is returned. + mouse, if the mouse is enabled in the command line ('mouse' is + "a" or includes "c"). For the first string 0 is returned. + When clicking above the first item a negative number is + returned. When clicking on the prompt one more than the + length of {textlist} is returned. Make sure {textlist} has less than 'lines' entries, otherwise it won't work. It's a good idea to put the entry number at the start of the string. And put a prompt in the first item. @@ -5479,7 +5444,7 @@ inputrestore() *inputrestore()* Restore typeahead that was saved with a previous |inputsave()|. Should be called the same number of times inputsave() is called. Calling it more often is harmless though. - Returns 1 when there is nothing to restore, 0 otherwise. + Returns TRUE when there is nothing to restore, FALSE otherwise. inputsave() *inputsave()* Preserve typeahead (also from mappings) and clear it, so that @@ -5487,7 +5452,7 @@ inputsave() *inputsave()* followed by a matching inputrestore() after the prompt. Can be used several times, in which case there must be just as many inputrestore() calls. - Returns 1 when out of memory, 0 otherwise. + Returns TRUE when out of memory, FALSE otherwise. inputsecret({prompt} [, {text}]) *inputsecret()* This function acts much like the |input()| function with but @@ -6086,6 +6051,10 @@ match({expr}, {pat} [, {start} [, {count}]]) *match()* The 'ignorecase' option is used to set the ignore-caseness of the pattern. 'smartcase' is NOT used. The matching is always done like 'magic' is set and 'cpoptions' is empty. + Note that a match at the start is preferred, thus when the + pattern is using "*" (any number of matches) it tends to find + zero matches at the start instead of a number of matches + further down in the text. *matchadd()* *E798* *E799* *E801* *E957* matchadd({group}, {pattern}[, {priority}[, {id} [, {dict}]]]) @@ -6151,7 +6120,8 @@ matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) to be used when fast match additions and deletions are required, for example to highlight matching parentheses. *E5030* *E5031* - The list {pos} can contain one of these items: + {pos} is a list of positions. Each position can be one of + these: - A number. This whole line will be highlighted. The first line has number 1. - A list with one number, e.g., [23]. The whole line with this @@ -6168,7 +6138,7 @@ matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) ignored, as well as entries with negative column numbers and lengths. - The maximum number of positions is 8. + The maximum number of positions in {pos} is 8. Example: > :highlight MyGroup ctermbg=green guibg=green @@ -6177,8 +6147,7 @@ matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) :call matchdelete(m) < Matches added by |matchaddpos()| are returned by - |getmatches()| with an entry "pos1", "pos2", etc., with the - value a list like the {pos} item. + |getmatches()|. matcharg({nr}) *matcharg()* Selects the {nr} match item, as set with a |:match|, @@ -6262,9 +6231,9 @@ matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()* *max()* max({expr}) Return the maximum value of all items in {expr}. - {expr} can be a list or a dictionary. For a dictionary, - it returns the maximum of all values in the dictionary. - If {expr} is neither a list nor a dictionary, or one of the + {expr} can be a |List| or a |Dictionary|. For a Dictionary, + it returns the maximum of all values in the Dictionary. + If {expr} is neither a List nor a Dictionary, or one of the items in {expr} cannot be used as a Number this results in an error. An empty |List| or |Dictionary| results in zero. @@ -6316,9 +6285,9 @@ menu_get({path}, {modes}) *menu_get()* *min()* min({expr}) Return the minimum value of all items in {expr}. - {expr} can be a list or a dictionary. For a dictionary, - it returns the minimum of all values in the dictionary. - If {expr} is neither a list nor a dictionary, or one of the + {expr} can be a |List| or a |Dictionary|. For a Dictionary, + it returns the minimum of all values in the Dictionary. + If {expr} is neither a List nor a Dictionary, or one of the items in {expr} cannot be used as a Number this results in an error. An empty |List| or |Dictionary| results in zero. @@ -6340,6 +6309,10 @@ mkdir({name} [, {path} [, {prot}]]) If you try to create an existing directory with {path} set to "p" mkdir() will silently exit. + The function result is a Number, which is TRUE if the call was + successful or FALSE if the directory creation failed or partly + failed. + *mode()* mode([expr]) Return a string that indicates the current mode. If [expr] is supplied and it evaluates to a non-zero Number or @@ -6800,15 +6773,15 @@ prompt_setprompt({buf}, {text}) *prompt_setprompt()* call prompt_setprompt(bufnr(''), 'command: ') pum_getpos() *pum_getpos()* - If the popup menu (see |ins-completion-menu|) is not visible, - returns an empty |Dictionary|, otherwise, returns a - |Dictionary| with the following keys: - height nr of items visible - width screen cells - row top screen row (0 first row) - col leftmost screen column (0 first col) - size total nr of items - scrollbar |TRUE| if visible + If the popup menu (see |ins-completion-menu|) is not visible, + returns an empty |Dictionary|, otherwise, returns a + |Dictionary| with the following keys: + height nr of items visible + width screen cells + row top screen row (0 first row) + col leftmost screen column (0 first col) + size total nr of items + scrollbar |TRUE| if scrollbar is visible The values are the same as in |v:event| during |CompleteChanged|. @@ -6931,10 +6904,10 @@ reg_recording() *reg_recording()* Returns an empty string string when not recording. See |q|. reltime([{start} [, {end}]]) *reltime()* - Return an item that represents a time value. The format of - 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. + Return an item that represents a time value. The item is a + list with items that depend on the system. + The item 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 "relative time", an implementation-defined value meaningful only when used as an @@ -6944,6 +6917,7 @@ reltime([{start} [, {end}]]) *reltime()* 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(). @@ -7065,7 +7039,7 @@ remove({list}, {idx} [, {end}]) *remove()* Without {end}: Remove the item at {idx} from |List| {list} and return the item. With {end}: Remove items from {idx} to {end} (inclusive) and - return a List with these items. When {idx} points to the same + return a |List| with these items. When {idx} points to the same item as {end} a list with one item is returned. When {end} points to an item before {idx} this is an error. See |list-index| for possible values of {idx} and {end}. @@ -7240,11 +7214,16 @@ search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()* 'ignorecase', 'smartcase' and 'magic' are used. - 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 - one column further. + When the 'z' flag is not given, forward 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 one column further. This matters for + overlapping matches. + When searching backwards and the 'z' flag is given then the + search starts in column zero, thus no match in the current + line will be found (unless wrapping around the end of the + file). When the {stopline} argument is given then the search stops after searching this line. This is useful to restrict the @@ -7436,6 +7415,7 @@ server2client({clientid}, {string}) *server2client()* Send a reply string to {clientid}. The most recent {clientid} that sent a string can be retrieved with expand("<client>"). Note: + Returns zero for success, -1 for failure. This id has to be stored before the next command can be received. I.e. before returning from the received command and before calling any commands that waits for input. @@ -7484,13 +7464,24 @@ serverstop({address}) *serverstop()* address returned by |serverlist()|. setbufline({expr}, {lnum}, {text}) *setbufline()* - Set line {lnum} to {text} in buffer {expr}. To insert - lines use |append()|. + Set line {lnum} to {text} in buffer {expr}. This works like + |setline()| for the specified buffer. + + This function works only for loaded buffers. First call + |bufload()| if needed. + + To insert lines use |appendbufline()|. + Any text properties in {lnum} are cleared. + + {text} can be a string to set one line, or a list of strings + to set multiple lines. If the list extends below the last + line then those lines are added. For the use of {expr}, see |bufname()| above. {lnum} is used like with |setline()|. - This works like |setline()| for the specified buffer. + When {lnum} is just below the last line the {text} will be + added below the last line. On success 0 is returned, on failure 1 is returned. If {expr} is not a valid buffer or {lnum} is not valid, an @@ -7541,8 +7532,8 @@ setcmdpos({pos}) *setcmdpos()* before inserting the resulting text. When the number is too big the cursor is put at the end of the line. A number smaller than one has undefined results. - Returns 0 when successful, 1 when not editing the command - line. + Returns FALSE when successful, TRUE when not editing the + command line. setenv({name}, {val}) *setenv()* Set environment variable {name} to {val}. @@ -7573,10 +7564,10 @@ setline({lnum}, {text}) *setline()* {lnum} is used like with |getline()|. When {lnum} is just below the last line the {text} will be - added as a new line. + added below the last line. - If this succeeds, 0 is returned. If this fails (most likely - because {lnum} is invalid) 1 is returned. + If this succeeds, FALSE is returned. If this fails (most likely + because {lnum} is invalid) TRUE is returned. Example: > :call setline(5, strftime("%c")) @@ -7601,6 +7592,8 @@ setloclist({nr}, {list}[, {action}[, {what}]]) *setloclist()* Otherwise, same as |setqflist()|. Also see |location-list|. + For {action} see |setqflist-action|. + If the optional {what} dictionary argument is supplied, then only the items listed in {what} are set. Refer to |setqflist()| for the list of supported keys in {what}. @@ -7666,7 +7659,12 @@ setpos({expr}, {list}) setqflist({list} [, {action}[, {what}]]) *setqflist()* Create or replace or add to the quickfix list. - When {what} is not present, use the items in {list}. Each + If the optional {what} dictionary argument is supplied, then + only the items listed in {what} are set. The first {list} + argument is ignored. See below for the supported items in + {what}. + *setqflist-what* + When {what} is not present, the items in {list} are used. Each item must be a dictionary. Non-dictionary items in {list} are ignored. Each dictionary item can contain the following entries: @@ -7702,7 +7700,7 @@ setqflist({list} [, {action}[, {what}]]) *setqflist()* Note that the list is not exactly the same as what |getqflist()| returns. - {action} values: *E927* + {action} values: *setqflist-action* *E927* 'a' The items from {list} are added to the existing quickfix list. If there is no existing list, then a new list is created. @@ -7721,10 +7719,7 @@ setqflist({list} [, {action}[, {what}]]) *setqflist()* freed. To add a new quickfix list at the end of the stack, set "nr" in {what} to "$". - If the optional {what} dictionary argument is supplied, then - only the items listed in {what} are set. The first {list} - argument is ignored. The following items can be specified in - {what}: + The following items can be specified in dictionary {what}: context quickfix list context. See |quickfix-context| efm errorformat to use when parsing text from "lines". If this is not present, then the @@ -7768,10 +7763,12 @@ setqflist({list} [, {action}[, {what}]]) *setqflist()* *setreg()* setreg({regname}, {value} [, {options}]) Set the register {regname} to {value}. + {value} may be any value returned by |getreg()|, including a |List|. If {options} contains "a" or {regname} is upper case, then the value is appended. + {options} can also contain a register type specification: "c" or "v" |charwise| mode "l" or "V" |linewise| mode @@ -7860,18 +7857,10 @@ settagstack({nr}, {dict} [, {action}]) *settagstack()* Returns zero for success, -1 for failure. - Examples: - Set current index of the tag stack to 4: > - call settagstack(1005, {'curidx' : 4}) - -< Empty the tag stack of window 3: > + Examples (for more examples see |tagstack-examples|): + Empty the tag stack of window 3: > call settagstack(3, {'items' : []}) -< Push a new item onto the tag stack: > - let pos = [bufnr('myfile.txt'), 10, 1, 0] - let newtag = [{'tagname' : 'mytag', 'from' : pos}] - call settagstack(2, {'items' : newtag}, 'a') - < Save and restore the tag stack: > let stack = gettagstack(1003) " do something else @@ -7938,362 +7927,17 @@ shiftwidth([{col}]) *shiftwidth()* 'vartabstop' feature. If no {col} argument is given, column 1 will be assumed. -sign_define({name} [, {dict}]) *sign_define()* -sign_define({list}) - Define a new sign named {name} or modify the attributes of an - existing sign. This is similar to the |:sign-define| command. - - Prefix {name} with a unique text to avoid name collisions. - There is no {group} like with placing signs. - - The {name} can be a String or a Number. The optional {dict} - argument specifies the sign attributes. The following values - are supported: - icon full path to the bitmap file for the sign. - linehl highlight group used for the whole line the - sign is placed in. - text text that is displayed when there is no icon - or the GUI is not being used. - texthl highlight group used for the text item - numhl highlight group used for 'number' column at the - associated line. Overrides |hl-LineNr|, - |hl-CursorLineNr|. - - If the sign named {name} already exists, then the attributes - of the sign are updated. - - The one argument {list} can be used to define a list of signs. - Each list item is a dictionary with the above items in {dict} - and a 'name' item for the sign name. - - Returns 0 on success and -1 on failure. When the one argument - {list} is used, then returns a List of values one for each - defined sign. - - Examples: > - call sign_define("mySign", { - \ "text" : "=>", - \ "texthl" : "Error", - \ "linehl" : "Search"}) - call sign_define([ - \ {'name' : 'sign1', - \ 'text' : '=>'}, - \ {'name' : 'sign2', - \ 'text' : '!!'} - \ ]) -< -sign_getdefined([{name}]) *sign_getdefined()* - Get a list of defined signs and their attributes. - This is similar to the |:sign-list| command. - - If the {name} is not supplied, then a list of all the defined - signs is returned. Otherwise the attribute of the specified - sign is returned. - - Each list item in the returned value is a dictionary with the - following entries: - icon full path to the bitmap file of the sign - linehl highlight group used for the whole line the - sign is placed in. - name name of the sign - text text that is displayed when there is no icon - or the GUI is not being used. - texthl highlight group used for the text item - numhl highlight group used for 'number' column at the - associated line. Overrides |hl-LineNr|, - |hl-CursorLineNr|. - - Returns an empty List if there are no signs and when {name} is - not found. - - Examples: > - " Get a list of all the defined signs - echo sign_getdefined() - - " Get the attribute of the sign named mySign - echo sign_getdefined("mySign") -< -sign_getplaced([{expr} [, {dict}]]) *sign_getplaced()* - Return a list of signs placed in a buffer or all the buffers. - This is similar to the |:sign-place-list| command. - - If the optional buffer name {expr} is specified, then only the - list of signs placed in that buffer is returned. For the use - of {expr}, see |bufname()|. The optional {dict} can contain - the following entries: - group select only signs in this group - id select sign with this identifier - lnum select signs placed in this line. For the use - of {lnum}, see |line()|. - If {group} is '*', then signs in all the groups including the - global group are returned. If {group} is not supplied or is an - empty string, then only signs in the global group are - returned. If no arguments are supplied, then signs in the - global group placed in all the buffers are returned. - See |sign-group|. - - Each list item in the returned value is a dictionary with the - following entries: - bufnr number of the buffer with the sign - signs list of signs placed in {bufnr}. Each list - item is a dictionary with the below listed - entries - - The dictionary for each sign contains the following entries: - group sign group. Set to '' for the global group. - id identifier of the sign - lnum line number where the sign is placed - name name of the defined sign - priority sign priority - - The returned signs in a buffer are ordered by their line - number and priority. - - Returns an empty list on failure or if there are no placed - signs. - - Examples: > - " Get a List of signs placed in eval.c in the - " global group - echo sign_getplaced("eval.c") - - " Get a List of signs in group 'g1' placed in eval.c - echo sign_getplaced("eval.c", {'group' : 'g1'}) - - " Get a List of signs placed at line 10 in eval.c - echo sign_getplaced("eval.c", {'lnum' : 10}) - - " Get sign with identifier 10 placed in a.py - echo sign_getplaced("a.py", {'id' : 10}) - - " Get sign with id 20 in group 'g1' placed in a.py - echo sign_getplaced("a.py", {'group' : 'g1', - \ 'id' : 20}) - - " Get a List of all the placed signs - echo sign_getplaced() -< - *sign_jump()* -sign_jump({id}, {group}, {expr}) - Open the buffer {expr} or jump to the window that contains - {expr} and position the cursor at sign {id} in group {group}. - This is similar to the |:sign-jump| command. - - For the use of {expr}, see |bufname()|. - - Returns the line number of the sign. Returns -1 if the - arguments are invalid. - - Example: > - " Jump to sign 10 in the current buffer - call sign_jump(10, '', '') -< - *sign_place()* -sign_place({id}, {group}, {name}, {expr} [, {dict}]) - Place the sign defined as {name} at line {lnum} in file or - buffer {expr} and assign {id} and {group} to sign. This is - similar to the |:sign-place| command. - - If the sign identifier {id} is zero, then a new identifier is - allocated. Otherwise the specified number is used. {group} is - the sign group name. To use the global sign group, use an - empty string. {group} functions as a namespace for {id}, thus - two groups can use the same IDs. Refer to |sign-identifier| - and |sign-group| for more information. - - {name} refers to a defined sign. - {expr} refers to a buffer name or number. For the accepted - values, see |bufname()|. - - The optional {dict} argument supports the following entries: - lnum line number in the file or buffer - {expr} where the sign is to be placed. - For the accepted values, see |line()|. - priority priority of the sign. See - |sign-priority| for more information. - - If the optional {dict} is not specified, then it modifies the - placed sign {id} in group {group} to use the defined sign - {name}. - - Returns the sign identifier on success and -1 on failure. - - Examples: > - " Place a sign named sign1 with id 5 at line 20 in - " buffer json.c - call sign_place(5, '', 'sign1', 'json.c', - \ {'lnum' : 20}) - - " Updates sign 5 in buffer json.c to use sign2 - call sign_place(5, '', 'sign2', 'json.c') - - " Place a sign named sign3 at line 30 in - " buffer json.c with a new identifier - let id = sign_place(0, '', 'sign3', 'json.c', - \ {'lnum' : 30}) - - " Place a sign named sign4 with id 10 in group 'g3' - " at line 40 in buffer json.c with priority 90 - call sign_place(10, 'g3', 'sign4', 'json.c', - \ {'lnum' : 40, 'priority' : 90}) -< - *sign_placelist()* -sign_placelist({list}) - Place one or more signs. This is similar to the - |sign_place()| function. The {list} argument specifies the - List of signs to place. Each list item is a dict with the - following sign attributes: - buffer buffer name or number. For the accepted - values, see |bufname()|. - group sign group. {group} functions as a namespace - for {id}, thus two groups can use the same - IDs. If not specified or set to an empty - string, then the global group is used. See - |sign-group| for more information. - id sign identifier. If not specified or zero, - then a new unique identifier is allocated. - Otherwise the specified number is used. See - |sign-identifier| for more information. - lnum line number in the buffer {expr} where the - sign is to be placed. For the accepted values, - see |line()|. - name name of the sign to place. See |sign_define()| - for more information. - priority priority of the sign. When multiple signs are - placed on a line, the sign with the highest - priority is used. If not specified, the - default value of 10 is used. See - |sign-priority| for more information. - - If {id} refers to an existing sign, then the existing sign is - modified to use the specified {name} and/or {priority}. - - Returns a List of sign identifiers. If failed to place a - sign, the corresponding list item is set to -1. - - Examples: > - " Place sign s1 with id 5 at line 20 and id 10 at line - " 30 in buffer a.c - let [n1, n2] = sign_place([ - \ {'id' : 5, - \ 'name' : 's1', - \ 'buffer' : 'a.c', - \ 'lnum' : 20}, - \ {'id' : 10, - \ 'name' : 's1', - \ 'buffer' : 'a.c', - \ 'lnum' : 30} - \ ]) - - " Place sign s1 in buffer a.c at line 40 and 50 - " with auto-generated identifiers - let [n1, n2] = sign_place([ - \ {'name' : 's1', - \ 'buffer' : 'a.c', - \ 'lnum' : 40}, - \ {'name' : 's1', - \ 'buffer' : 'a.c', - \ 'lnum' : 50} - \ ]) -< -sign_undefine([{name}]) *sign_undefine()* -sign_undefine({list}) - Deletes a previously defined sign {name}. This is similar to - the |:sign-undefine| command. If {name} is not supplied, then - deletes all the defined signs. - - The one argument {list} can be used to undefine a list of - signs. Each list item is the name of a sign. - - Returns 0 on success and -1 on failure. For the one argument - {list} call, returns a list of values one for each undefined - sign. - - Examples: > - " Delete a sign named mySign - call sign_undefine("mySign") +sign_ functions are documented here: |sign-functions-details| - " Delete signs 'sign1' and 'sign2' - call sign_undefine(["sign1", "sign2"]) - - " Delete all the signs - call sign_undefine() -< -sign_unplace({group} [, {dict}]) *sign_unplace()* - Remove a previously placed sign in one or more buffers. This - is similar to the |:sign-unplace| command. - - {group} is the sign group name. To use the global sign group, - use an empty string. If {group} is set to '*', then all the - groups including the global group are used. - The signs in {group} are selected based on the entries in - {dict}. The following optional entries in {dict} are - supported: - buffer buffer name or number. See |bufname()|. - id sign identifier - If {dict} is not supplied, then all the signs in {group} are - removed. - - Returns 0 on success and -1 on failure. - - Examples: > - " Remove sign 10 from buffer a.vim - call sign_unplace('', {'buffer' : "a.vim", 'id' : 10}) - - " Remove sign 20 in group 'g1' from buffer 3 - call sign_unplace('g1', {'buffer' : 3, 'id' : 20}) - - " Remove all the signs in group 'g2' from buffer 10 - call sign_unplace('g2', {'buffer' : 10}) - - " Remove sign 30 in group 'g3' from all the buffers - call sign_unplace('g3', {'id' : 30}) - - " Remove all the signs placed in buffer 5 - call sign_unplace('*', {'buffer' : 5}) - - " Remove the signs in group 'g4' from all the buffers - call sign_unplace('g4') - - " Remove sign 40 from all the buffers - call sign_unplace('*', {'id' : 40}) - - " Remove all the placed signs from all the buffers - call sign_unplace('*') -< -sign_unplacelist({list}) *sign_unplacelist()* - Remove previously placed signs from one or more buffers. This - is similar to the |sign_unplace()| function. - - The {list} argument specifies the List of signs to remove. - Each list item is a dict with the following sign attributes: - buffer buffer name or number. For the accepted - values, see |bufname()|. If not specified, - then the specified sign is removed from all - the buffers. - group sign group name. If not specified or set to an - empty string, then the global sign group is - used. If set to '*', then all the groups - including the global group are used. - id sign identifier. If not specified, then all - the signs in the specified group are removed. - - Returns a List where an entry is set to 0 if the corresponding - sign was successfully removed or -1 on failure. - - Example: > - " Remove sign with id 10 from buffer a.vim and sign - " with id 20 from buffer b.vim - call sign_unplace([{'id' : 10, 'buffer' : "a.vim"}, - \ {'id' : 20, 'buffer' : 'b.vim'}]) -< simplify({filename}) *simplify()* Simplify the file name as much as possible without changing the meaning. Shortcuts (on MS-Windows) or symbolic links (on Unix) are not resolved. If the first path component in {filename} designates the current directory, this will be valid for the result as well. A trailing path separator is - not removed either. + not removed either. On Unix "//path" is unchanged, but + "///path" is simplified to "/path" (this follows the Posix + standard). Example: > simplify("./dir/.././/file/") == "./file/" < Note: The combination "dir/.." is only removed if "dir" is @@ -8359,7 +8003,7 @@ sort({list} [, {func} [, {dict}]]) *sort()* *E702* ignored. When {func} is given and it is 'n' then all items will be - sorted numerical (Implementation detail: This uses the + sorted numerical (Implementation detail: this uses the strtod() function to parse numbers, Strings, Lists, Dicts and Funcrefs will be considered as being 0). @@ -8552,7 +8196,7 @@ str2list({expr} [, {utf8}]) *str2list()* < |list2str()| does the opposite. When {utf8} is omitted or zero, the current 'encoding' is used. - With {utf8} set to 1, always treat the String as utf-8 + With {utf8} set to TRUE, always treat the String as utf-8 characters. With utf-8 composing characters are handled properly: > str2list("á") returns [97, 769] @@ -8596,7 +8240,8 @@ strchars({expr} [, {skipcc}]) *strchars()* < strcharpart({src}, {start} [, {len}]) *strcharpart()* Like |strpart()| but using character index and length instead - of byte index and length. + of byte index and length. Composing characters are counted + separately. When a character index is used where a character does not exist it is assumed to be one character. For example: > strcharpart('abc', -1, 2) @@ -8860,7 +8505,7 @@ swapname({expr}) *swapname()* The result is the swap file path of the buffer {expr}. For the use of {expr}, see |bufname()| above. If buffer {expr} is the current buffer, the result is equal to - |:swapname| (unless no swap file). + |:swapname| (unless there is no swap file). If buffer {expr} has no swap file, returns an empty string. synID({lnum}, {col}, {trans}) *synID()* @@ -8929,7 +8574,7 @@ synIDtrans({synID}) *synIDtrans()* ":highlight link" are followed. synconcealed({lnum}, {col}) *synconcealed()* - The result is a List with currently three items: + The result is a |List| with currently three items: 1. The first item in the list is 0 if the character at the position {lnum} and {col} is not part of a concealable region, 1 if it is. @@ -9033,6 +8678,10 @@ systemlist({cmd} [, {input} [, {keepempty}]]) *systemlist()* unless {keepempty} is non-zero. Note that on MS-Windows you may get trailing CR characters. + To see the difference between "echo hello" and "echo -n hello" + use |system()| and |split()|: > + echo split(system('echo hello'), '\n', 1) +< Returns an empty string on error. @@ -9081,7 +8730,7 @@ tagfiles() Returns a |List| with the file names used to search for tags taglist({expr} [, {filename}]) *taglist()* - Returns a list of tags matching the regular expression {expr}. + Returns a |List| of tags matching the regular expression {expr}. If {filename} is passed it is used to prioritize the results in the same way that |:tselect| does. See |tag-priority|. @@ -9146,11 +8795,7 @@ termopen({cmd}[, {opts}]) *termopen()* See |terminal| for more information. -test_garbagecollect_now() *test_garbagecollect_now()* - Like |garbagecollect()|, but executed right away. This must - only be called directly to avoid any structure to exist - internally, and |v:testing| must have been set before calling - any function. +test_ functions are documented here: |test-functions-details| tan({expr}) *tan()* Return the tangent of {expr}, measured in radians, as a |Float| @@ -9182,7 +8827,7 @@ timer_info([{id}]) returned. When {id} is omitted information about all timers is returned. - For each timer the information is stored in a Dictionary with + For each timer the information is stored in a |Dictionary| with these items: "id" the timer ID "time" time the timer was started with @@ -9359,7 +9004,7 @@ undotree() *undotree()* undo blocks. The first item in the "entries" list is the oldest undo item. - Each List item is a Dictionary with these items: + Each List item is a |Dictionary| with these items: "seq" Undo sequence number. Same as what appears in |:undolist|. "time" Timestamp when the change happened. Use @@ -9479,7 +9124,7 @@ wildmenumode() *wildmenumode()* win_findbuf({bufnr}) *win_findbuf()* - Returns a list with |window-ID|s for windows that contain + Returns a |List| with |window-ID|s for windows that contain buffer {bufnr}. When there is none the list is empty. win_getid([{win} [, {tab}]]) *win_getid()* @@ -9512,7 +9157,7 @@ win_gettype([{nr}]) *win_gettype()* 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. + Return TRUE if successful, FALSE if the window cannot be found. win_id2tabwin({expr} *win_id2tabwin()* Return a list with the tab number and window number of window @@ -9527,21 +9172,23 @@ win_screenpos({nr}) *win_screenpos()* Return the screen position of window {nr} as a list with two numbers: [row, col]. The first window always has position [1, 1], unless there is a tabline, then it is [2, 1]. - {nr} can be the window number or the |window-ID|. + {nr} can be the window number or the |window-ID|. Use zero + for the current window. Return [0, 0] if the window cannot be found in the current tabpage. win_splitmove({nr}, {target} [, {options}]) *win_splitmove()* - Move the window {nr} to a new split of the window {target}. + Move the window {nr} to a new split of the window {target}. This is similar to moving to {target}, creating a new window using |:split| but having the same contents as window {nr}, and then closing {nr}. Both {nr} and {target} can be window numbers or |window-ID|s. + Both must be in the current tab page. Returns zero for success, non-zero for failure. - {options} is a Dictionary with the following optional entries: + {options} is a |Dictionary| with the following optional entries: "vertical" When TRUE, the split is created vertically, like with |:vsplit|. "rightbelow" When TRUE, the split is made below or to the @@ -9605,11 +9252,12 @@ winlayout([{tabnr}]) *winlayout()* " Two horizontally split windows :echo winlayout() ['col', [['leaf', 1000], ['leaf', 1001]]] - " Three horizontally split windows, with two - " vertically split windows in the middle window + " The second tab page, with three horizontally split + " windows, with two vertically split windows in the + " middle window :echo winlayout(2) - ['col', [['leaf', 1002], ['row', ['leaf', 1003], - ['leaf', 1001]]], ['leaf', 1000]] + ['col', [['leaf', 1002], ['row', [['leaf', 1003], + ['leaf', 1001]]], ['leaf', 1000]]] < *winline()* winline() The result is a Number, which is the screen line of the cursor @@ -9621,6 +9269,7 @@ winline() The result is a Number, which is the screen line of the cursor *winnr()* winnr([{arg}]) The result is a Number, which is the number of the current window. The top window has number 1. + Returns zero for a popup window. The optional argument {arg} supports the following values: $ the number of the last window (the window @@ -9690,7 +9339,8 @@ winsaveview() Returns a |Dictionary| that contains information to restore curswant column for vertical movement topline first line in the window topfill filler lines, only in diff mode - leftcol first column displayed + leftcol first column displayed; only used when + 'wrap' is off skipcol columns skipped Note that no option values are saved. @@ -9995,8 +9645,8 @@ It is allowed to define another function inside a function body. You can provide default values for positional named arguments. This makes them optional for function calls. When a positional argument is not specified at a call, the default expression is used to initialize it. -This only works for functions declared with |function|, not for lambda -expressions |expr-lambda|. +This only works for functions declared with |function|, not for +lambda expressions |expr-lambda|. Example: > function Something(key, value = 10) @@ -10025,9 +9675,10 @@ Example that does NOT work: > :function NoGood(first = a:second, second = 10) :endfunction < -When not using "...", the number of arguments in a function call must be equal -to the number of mandatory named arguments. When using "...", the number of -arguments may be larger. +When not using "...", the number of arguments in a function call must be at +least equal to the number of mandatory named arguments. When using "...", the +number of arguments may be larger than the total of mandatory and optional +arguments. *local-variables* Inside a function local variables can be used. These will disappear when the @@ -10179,8 +9830,9 @@ be used to pass settings to the autoload script before it's loaded: > Note that when you make a mistake and call a function that is supposed to be defined in an autoload script, but the script doesn't actually define the -function, the script will be sourced every time you try to call the function. -And you will get an error message every time. +function, you will get an error message for the missing function. If you fix +the autoload script it won't be automatically loaded again. Either restart +Vim or manually source the script. Also note that if you have two script files, and one calls a function in the other and vice versa, before the used function is defined, it won't work. @@ -10357,7 +10009,7 @@ This does NOT work: > Like above, but append/add/subtract the value for each |List| item. -:let [{name}, ..., ; {lastname}] = {expr1} +:let [{name}, ..., ; {lastname}] = {expr1} *E452* Like |:let-unpack| above, but the |List| may have more items than there are names. A list of the remaining items is assigned to {lastname}. If there are no @@ -10373,20 +10025,22 @@ This does NOT work: > *:let=<<* *:let-heredoc* *E990* *E991* *E172* *E221* -:let {var-name} =<< [trim] {marker} +:let {var-name} =<< [trim] {endmarker} text... text... -{marker} - Set internal variable {var-name} to a List containing - the lines of text bounded by the string {marker}. - {marker} cannot start with a lower case character. - The last line should end only with the {marker} string - without any other character. Watch out for white - space after {marker}! +{endmarker} + Set internal variable {var-name} to a |List| + containing the lines of text bounded by the string + {endmarker}. + {endmarker} cannot start with a lower case character. + The last line should end only with the {endmarker} + string without any other character. Watch out for + white space after {endmarker}! Without "trim" any white space characters in the lines of text are preserved. If "trim" is specified before - {marker}, then indentation is stripped so you can do: > + {endmarker}, then indentation is stripped so you can + do: > let text =<< trim END if ok echo 'done' @@ -10400,23 +10054,31 @@ text... non-empty text line is stripped from the input lines. All leading indentation exactly matching the leading indentation before `let` is stripped from the line - containing {marker}. Note that the difference between - space and tab matters here. + containing {endmarker}. Note that the difference + between space and tab matters here. If {var-name} didn't exist yet, it is created. Cannot be followed by another command, but can be followed by a comment. + To avoid line continuation to be applied, consider + adding 'C' to 'cpoptions': > + set cpo+=C + let var =<< END + \ leading backslash + END + set cpo-=C +< Examples: > let var1 =<< END - Sample text 1 - Sample text 2 - Sample text 3 - END + Sample text 1 + Sample text 2 + Sample text 3 + END let data =<< trim DATA - 1 2 3 4 - 5 6 7 8 + 1 2 3 4 + 5 6 7 8 DATA < *E121* @@ -10496,8 +10158,8 @@ text... it can no longer be changed (until it is unlocked). A locked variable can be deleted: > :lockvar v - :let v = 'asdf' " fails! - :unlet v + :let v = 'asdf' " fails! + :unlet v " works < *E741* *E940* If you try to change a locked variable you get an error message: "E741: Value is locked: {name}". @@ -10541,21 +10203,6 @@ text... Unlock the internal variable {name}. Does the opposite of |:lockvar|. - *:eval* -:eval {expr} Evaluate {expr} and discard the result. Example: > - :eval append(Filter(Getlist()), '$') - -< The expression is supposed to have a side effect, - since the resulting value is not used. In the example - the `append()` call appends the List with text to the - buffer. This is similar to `:call` but works with any - expression. - - The command can be shortened to `:ev` or `:eva`, but - these are hard to recognize and therefore not to be - used. - - :if {expr1} *:if* *:end* *:endif* *:en* *E171* *E579* *E580* :en[dif] Execute the commands until the next matching ":else" or ":endif" if {expr1} evaluates to non-zero. @@ -10673,11 +10320,11 @@ text... ":endtry" is reached thereafter, the next (dynamically) surrounding ":try" is checked for a corresponding ":finally" etc. Then the script - processing is terminated. (Whether a function - definition has an "abort" argument does not matter.) + processing is terminated. Whether a function + definition has an "abort" argument does not matter. Example: > - :try | edit too much | finally | echo "cleanup" | endtry - :echo "impossible" " not reached, script terminated above + try | call Unknown() | finally | echomsg "cleanup" | endtry + echomsg "not reached" < Moreover, an error or interrupt (dynamically) inside ":try" and ":endtry" is converted to an exception. It @@ -10694,8 +10341,8 @@ text... error exception is not caught, always beginning with the error number. Examples: > - :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry - :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry + try | sleep 100 | catch /^Vim:Interrupt$/ | endtry + try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry < *:cat* *:catch* *E603* *E604* *E605* :cat[ch] /{pattern}/ The following commands until the next |:catch|, @@ -10849,18 +10496,36 @@ text... And to get a beep: > :exe "normal \<Esc>" < + *:eval* +:eval {expr} Evaluate {expr} and discard the result. Example: > + :eval append(Filter(Getlist()), '$') + +< The expression is supposed to have a side effect, + since the resulting value is not used. In the example + the `append()` call appends the List with text to the + buffer. This is similar to `:call` but works with any + expression. + + The command can be shortened to `:ev` or `:eva`, but + these are hard to recognize and therefore not to be + used. + + The command cannot be followed by "|" and another + command, since "|" is seen as part of the expression. + + *:exe* *:execute* :exe[cute] {expr1} .. Executes the string that results from the evaluation of {expr1} as an Ex command. Multiple arguments are concatenated, with a space in - between. To avoid the extra space use the "." + between. To avoid the extra space use the ".." operator to concatenate strings into one argument. {expr1} is used as the processed command, command line editing keys are not recognized. Cannot be followed by a comment. Examples: > :execute "buffer" nextbuf - :execute "normal" count . "w" + :execute "normal" count .. "w" < ":execute" can be used to append a command to commands that don't accept a '|'. Example: > @@ -10876,8 +10541,8 @@ text... file names. The |fnameescape()| function can be used for Vim commands, |shellescape()| for |:!| commands. Examples: > - :execute "e " . fnameescape(filename) - :execute "!ls " . shellescape(filename, 1) + :execute "e " .. fnameescape(filename) + :execute "!ls " .. shellescape(filename, 1) < Note: The executed string may be any command-line, but starting or ending "if", "while" and "for" does not diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt index 1fce37c594..36ed6bbac1 100644 --- a/runtime/doc/filetype.txt +++ b/runtime/doc/filetype.txt @@ -136,6 +136,7 @@ can be used to overrule the filetype used for certain extensions: *.w g:filetype_w |ft-cweb-syntax| *.i g:filetype_i |ft-progress-syntax| *.p g:filetype_p |ft-pascal-syntax| + *.pp g:filetype_pp |ft-pascal-syntax| *.sh g:bash_is_sh |ft-sh-syntax| *.tex g:tex_flavor |ft-tex-plugin| @@ -263,13 +264,13 @@ all loaded. For example, if this command: > produces this output: - runtimepath=/etc/vim,~/.config/nvim,/usr/local/share/vim/vim60 ~ + runtimepath=/etc/vim,~/.config/nvim,/usr/local/share/vim/vim82 ~ then Vim will load all plugins in these directories and below: /etc/vim/plugin/ ~ ~/.config/nvim/plugin/ ~ - /usr/local/share/vim/vim60/plugin/ ~ + /usr/local/share/vim/vim82/plugin/ ~ Note that the last one is the value of $VIMRUNTIME which has been expanded. @@ -353,6 +354,13 @@ ways to change this: 3. Docs for the default filetype plugins. *ftplugin-docs* +AWK *ft-awk-plugin* + +Support for features specific to GNU Awk, like @include, can be enabled by +setting: > + let g:awk_is_gawk = 1 + + CHANGELOG *ft-changelog-plugin* Allows for easy entrance of Changelog entries in Changelog files. There are @@ -568,6 +576,13 @@ So `groff`'s pre-formatting output will be the same as with `g:man_hardwrap=0` i To disable bold highlighting: > :highlight link manBold Normal + +MARKDOWN *ft-markdown-plugin* + +To enable folding use this: > + let g:markdown_folding = 1 +< + PDF *ft-pdf-plugin* Two maps, <C-]> and <C-T>, are provided to simulate a tag stack for navigating diff --git a/runtime/doc/ft_ps1.txt b/runtime/doc/ft_ps1.txt new file mode 100644 index 0000000000..df1480b929 --- /dev/null +++ b/runtime/doc/ft_ps1.txt @@ -0,0 +1,64 @@ +*ps1.txt* A Windows PowerShell syntax plugin for Vim + +Author: Peter Provost <https://www.github.com/PProvost> +License: Apache 2.0 +URL: https://github.com/PProvost/vim-ps1 + +INTRODUCTION *ps1-syntax* + +This plugin provides Vim syntax, indent and filetype detection for Windows +PowerShell scripts, modules, and XML configuration files. + + +ABOUT *ps1-about* + +Grab the latest version or report a bug on GitHub: + +https://github.com/PProvost/vim-ps1 + + +FOLDING *ps1-folding* + +The ps1 syntax file provides syntax folding (see |:syn-fold|) for script blocks +and digital signatures in scripts. + +When 'foldmethod' is set to "syntax" then function script blocks will be +folded unless you use the following in your .vimrc or before opening a script: > + + :let g:ps1_nofold_blocks = 1 +< +Digital signatures in scripts will also be folded unless you use: > + + :let g:ps1_nofold_sig = 1 +< +Note: syntax folding might slow down syntax highlighting significantly, +especially for large files. + + +COMPILER *ps1-compiler* + +The powershell `:compiler` script configures |:make| to execute the script in +PowerShell. + +It tries to pick a smart default PowerShell command: `pwsh` if available and +`powershell` otherwise, but you can customize the command: > + + :let g:ps1_makeprg_cmd = '/path/to/pwsh' +< +To configure whether to show the exception type information: > + + :let g:ps1_efm_show_error_categories = 1 +< + +KEYWORD LOOKUP *ps1-keyword* + +To look up keywords using PowerShell's Get-Help, press the |K| key. For more +convenient paging, the pager `less` should be installed, which is included in +many Linux distributions and in macOS. + +Many other distributions are available for Windows like +https://chocolatey.org/packages/less/. Make sure `less` is in a directory +listed in the `PATH` environment variable, which chocolatey above does. + +------------------------------------------------------------------------------ + vim:ft=help: diff --git a/runtime/doc/ft_raku.txt b/runtime/doc/ft_raku.txt new file mode 100644 index 0000000000..26ada8a140 --- /dev/null +++ b/runtime/doc/ft_raku.txt @@ -0,0 +1,126 @@ +*vim-raku.txt* The Raku programming language filetype + + *vim-raku* + +Vim-raku provides syntax highlighting, indentation, and other support for +editing Raku programs. + +1. Using Unicode in your Raku files |raku-unicode| + +============================================================================== +1. Using Unicode in your Raku files *raku-unicode* + +Defining new operators using Unicode symbols is a good way to make your +Raku program easy to read. See: +https://perl6advent.wordpress.com/2012/12/18/day-18-formulas-resistance-is-futile/ + +While Raku does define ASCII alternatives for some common operators (see +https://docs.raku.org/language/unicode_ascii), using the full range of +Unicode operators is highly desirable. Your operating system provides input +facilities, but using the features built in to Vim may be preferable. + +The natural way to produce these symbols in Vim is to use digraph shortcuts +(:help |digraphs-use|). Many of them are defined; type `:digraphs` to get +the list. A convenient way to read the list of digraphs is to save them in a +file. From the shell: > + vim +'redir >/tmp/vim-digraphs-listing.txt' +digraphs +'redir END' +q + +Some of them are available with standard Vim digraphs: + << « /0 ∅ !< ≮ ~ + >> » Ob ∘ !> ≯ ~ + ., … 00 ∞ (C ⊂ ~ + (U ∩ -: ÷ )C ⊃ ~ + )U ∪ (_ ⊆ >= ≥ ~ + ?= ≅ )_ ⊇ =< ≤ ~ + (- ∈ ?= ≅ != ≠ ~ + -) ∋ ?- ≃ ~ + +The Greek alphabet is available with '*' followed by a similar Latin symbol: + *p π ~ + *t τ ~ + *X × ~ + +Numbers, subscripts and superscripts are available with 's' and 'S': + 0s ₀ 0S ⁰ ~ + 1s ₁ 1S ¹ ~ + 2s ₂ 9S ⁹ ~ + +But some don´t come defined by default. Those are digraph definitions you can +add in your ~/.vimrc file. > + exec 'digraph \\ '.char2nr('∖') + exec 'digraph \< '.char2nr('≼') + exec 'digraph \> '.char2nr('≽') + exec 'digraph (L '.char2nr('⊈') + exec 'digraph )L '.char2nr('⊉') + exec 'digraph (/ '.char2nr('⊄') + exec 'digraph )/ '.char2nr('⊅') + exec 'digraph )/ '.char2nr('⊅') + exec 'digraph U+ '.char2nr('⊎') + exec 'digraph 0- '.char2nr('⊖') + " Euler's constant + exec 'digraph ne '.char2nr('𝑒') + " Raku's atomic operations marker + exec 'digraph @@ '.char2nr('⚛') + +Alternatively, you can write Insert mode abbreviations that convert ASCII- +based operators into their single-character Unicode equivalent. > + iabbrev <buffer> !(<) ⊄ + iabbrev <buffer> !(<=) ⊈ + iabbrev <buffer> !(>) ⊅ + iabbrev <buffer> !(>=) ⊉ + iabbrev <buffer> !(cont) ∌ + iabbrev <buffer> !(elem) ∉ + iabbrev <buffer> != ≠ + iabbrev <buffer> (&) ∩ + iabbrev <buffer> (+) ⊎ + iabbrev <buffer> (-) ∖ + iabbrev <buffer> (.) ⊍ + iabbrev <buffer> (<) ⊂ + iabbrev <buffer> (<+) ≼ + iabbrev <buffer> (<=) ⊆ + iabbrev <buffer> (>) ⊃ + iabbrev <buffer> (>+) ≽ + iabbrev <buffer> (>=) ⊇ + iabbrev <buffer> (\|) ∪ + iabbrev <buffer> (^) ⊖ + iabbrev <buffer> (atomic) ⚛ + iabbrev <buffer> (cont) ∋ + iabbrev <buffer> (elem) ∈ + iabbrev <buffer> * × + iabbrev <buffer> **0 ⁰ + iabbrev <buffer> **1 ¹ + iabbrev <buffer> **2 ² + iabbrev <buffer> **3 ³ + iabbrev <buffer> **4 ⁴ + iabbrev <buffer> **5 ⁵ + iabbrev <buffer> **6 ⁶ + iabbrev <buffer> **7 ⁷ + iabbrev <buffer> **8 ⁸ + iabbrev <buffer> **9 ⁹ + iabbrev <buffer> ... … + iabbrev <buffer> / ÷ + iabbrev <buffer> << « + iabbrev <buffer> <<[=]<< «=« + iabbrev <buffer> <<[=]>> «=» + iabbrev <buffer> <= ≤ + iabbrev <buffer> =~= ≅ + iabbrev <buffer> >= ≥ + iabbrev <buffer> >> » + iabbrev <buffer> >>[=]<< »=« + iabbrev <buffer> >>[=]>> »=» + iabbrev <buffer> Inf ∞ + iabbrev <buffer> atomic-add-fetch ⚛+= + iabbrev <buffer> atomic-assign ⚛= + iabbrev <buffer> atomic-fetch ⚛ + iabbrev <buffer> atomic-dec-fetch --⚛ + iabbrev <buffer> atomic-fetch-dec ⚛-- + iabbrev <buffer> atomic-fetch-inc ⚛++ + iabbrev <buffer> atomic-inc-fetch ++⚛ + iabbrev <buffer> atomic-sub-fetch ⚛−= + iabbrev <buffer> e 𝑒 + iabbrev <buffer> o ∘ + iabbrev <buffer> pi π + iabbrev <buffer> set() ∅ + iabbrev <buffer> tau τ +< + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/ft_sql.txt b/runtime/doc/ft_sql.txt index 324e2e44af..f38c8edbf3 100644 --- a/runtime/doc/ft_sql.txt +++ b/runtime/doc/ft_sql.txt @@ -308,7 +308,7 @@ can create any of the following: > ~/.config/nvim/indent/sqlite.vim No changes are necessary to the SQLSetType function. It will automatically -pickup the new SQL files and load them when you issue the SQLSetType command. +pick up the new SQL files and load them when you issue the SQLSetType command. ============================================================================== @@ -338,8 +338,8 @@ The defaults static maps are: > imap <buffer> <C-C>T <C-\><C-O>:call sqlcomplete#Map('sqlType')<CR><C-X><C-O> imap <buffer> <C-C>s <C-\><C-O>:call sqlcomplete#Map('sqlStatement')<CR><C-X><C-O> -The use of "<C-C>" can be user chosen by using the following in your -|init.vim| as it may not work properly on all platforms: > +The use of "<C-C>" can be user chosen by using the following in your |init.vim| +as it may not work properly on all platforms: > let g:ftplugin_sql_omni_key = '<C-C>' > The static maps (which are based on the syntax highlight groups) follow this @@ -515,10 +515,10 @@ beginning with those characters. > 4.3.2 Column Completion: *sql-completion-columns* The SQL completion plugin can also display a list of columns for particular -tables. The column completion is trigger via <C-C>c. +tables. The column completion is triggered via <C-C>c. NOTE: The following example uses <Right> to trigger a column list while - the popup window is active. + the popup window is active. Example of using column completion: - Press <C-C>t again to display the list of tables. @@ -723,7 +723,7 @@ your platform (often a case on *nix) you define the following variable in your |init.vim|: > let g:omni_sql_no_default_maps = 1 -Do no edit ftplugin/sql.vim directly! If you change this file your changes +Do not edit ftplugin/sql.vim directly! If you change this file your changes will be over written on future updates. Vim has a special directory structure which allows you to make customizations without changing the files that are included with the Vim distribution. If you wish to customize the maps diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt index 0df776010b..0f1fa2b7a7 100644 --- a/runtime/doc/gui.txt +++ b/runtime/doc/gui.txt @@ -180,19 +180,12 @@ This does require the |+menu| feature enabled at compile time. Creating New Menus *creating-menus* *:me* *:menu* *:noreme* *:noremenu* - *:am* *:amenu* *:an* *:anoremenu* - *:nme* *:nmenu* *:nnoreme* *:nnoremenu* - *:ome* *:omenu* *:onoreme* *:onoremenu* - *:vme* *:vmenu* *:vnoreme* *:vnoremenu* - *:xme* *:xmenu* *:xnoreme* *:xnoremenu* - *:sme* *:smenu* *:snoreme* *:snoremenu* - *:ime* *:imenu* *:inoreme* *:inoremenu* - *:cme* *:cmenu* *:cnoreme* *:cnoremenu* *E330* *E327* *E331* *E336* *E333* *E328* *E329* *E337* *E792* To create a new menu item, use the ":menu" commands. They are mostly like -the ":map" set of commands but the first argument is a menu item name, given -as a path of menus and submenus with a '.' between them, e.g.: > +the ":map" set of commands (see |map-modes|), but the first argument is a menu +item name, given as a path of menus and submenus with a '.' between them, +e.g.: > :menu File.Save :w<CR> :inoremenu File.Save <C-O>:w<CR> @@ -221,6 +214,7 @@ With the shortcut "F" (while keeping the <Alt> key pressed), and then "O", this menu can be used. The second part is shown as "Open :e". The ":e" is right aligned, and the "O" is underlined, to indicate it is the shortcut. + *:am* *:amenu* *:an* *:anoremenu* The ":amenu" command can be used to define menu entries for all modes at once. To make the command work correctly, a character is automatically inserted for some modes: @@ -253,9 +247,38 @@ expression register: > :amenu Insert.foobar "='foobar'<CR>P +The special text <Cmd> begins a "command menu", it executes the command +directly without changing modes. Where you might use ":...<CR>" you can +instead use "<Cmd>...<CR>". See |<Cmd>| for more info. Example: > + anoremenu File.Next <Cmd>next<CR> + Note that <Esc> in Cmdline mode executes the command, like in a mapping. This is Vi compatible. Use CTRL-C to quit Cmdline mode. + *:nme* *:nmenu* *:nnoreme* *:nnoremenu* *:nunme* *:nunmenu* +Menu commands starting with "n" work in Normal mode. |mapmode-n| + + *:ome* *:omenu* *:onoreme* *:onoremenu* *:ounme* *:ounmenu* +Menu commands starting with "o" work in Operator-pending mode. |mapmode-o| + + *:vme* *:vmenu* *:vnoreme* *:vnoremenu* *:vunme* *:vunmenu* +Menu commands starting with "v" work in Visual mode. |mapmode-v| + + *:xme* *:xmenu* *:xnoreme* *:xnoremenu* *:xunme* *:xunmenu* +Menu commands starting with "x" work in Visual and Select mode. |mapmode-x| + + *:sme* *:smenu* *:snoreme* *:snoremenu* *:sunme* *:sunmenu* +Menu commands starting with "s" work in Select mode. |mapmode-s| + + *:ime* *:imenu* *:inoreme* *:inoremenu* *:iunme* *:iunmenu* +Menu commands starting with "i" work in Insert mode. |mapmode-i| + + *:cme* *:cmenu* *:cnoreme* *:cnoremenu* *:cunme* *:cunmenu* +Menu commands starting with "c" work in Cmdline mode. |mapmode-c| + + *:tlm* *:tlmenu* *:tln* *:tlnoremenu* *:tlu* *:tlunmenu* +Menu commands starting with "tl" work in Terminal mode. |mapmode-t| + *:menu-<silent>* *:menu-silent* To define a menu which will not be echoed on the command line, add "<silent>" as the first argument. Example: > @@ -431,6 +454,8 @@ Special characters in the list, just before the rhs: * The menu was defined with "nore" to disallow remapping. & The menu was defined with "<script>" to allow remapping script-local mappings only. +s The menu was defined with "<silent>" to avoid showing what it is + mapped to when triggered. - The menu was disabled. Note that hitting <Tab> while entering a menu name after a menu command may @@ -461,13 +486,6 @@ Deleting Menus *delete-menus* *:unme* *:unmenu* *:aun* *:aunmenu* - *:nunme* *:nunmenu* - *:ounme* *:ounmenu* - *:vunme* *:vunmenu* - *:xunme* *:xunmenu* - *:sunme* *:sunmenu* - *:iunme* *:iunmenu* - *:cunme* *:cunmenu* To delete a menu item or a whole submenu, use the unmenu commands, which are analogous to the unmap commands. Eg: > :unmenu! Edit.Paste diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt index 203699435b..8b096ff28b 100644 --- a/runtime/doc/help.txt +++ b/runtime/doc/help.txt @@ -30,7 +30,7 @@ Get specific help: It is possible to go directly to whatever you want help help entries for "word". Or use ":helpgrep word". |:helpgrep| - Getting started: Do the Vim tutor, a 20 minute interactive training for the + Getting started: Do the Vim tutor, a 30-minute interactive course for the basic commands, see |vimtutor|. Read the user manual from start to end: |usr_01.txt| @@ -40,7 +40,7 @@ through the help of many others. See |credits|. *doc-file-list* *Q_ct* BASIC: |quickref| Overview of the most common commands you will use -|tutor| 20 minutes training course for beginners +|tutor| 30-minute interactive course for beginners |copying| About copyrights |iccf| Helping poor children in Uganda |sponsor| Sponsor Vim development, become a registered Vim user @@ -132,6 +132,7 @@ Advanced editing ~ |lua.txt| Lua API Special issues ~ +|testing.txt| testing Vim and Vim scripts |print.txt| printing |remote.txt| using Vim as a server or client @@ -147,7 +148,7 @@ Programming language support ~ Language support ~ |digraph.txt| list of available digraphs -|mbyte.txt| multi-byte text support +|mbyte.txt| multibyte text support |mlang.txt| non-English language support |rileft.txt| right-to-left editing mode |arabic.txt| Arabic language support and editing diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt index ba6dd02a29..7643d84017 100644 --- a/runtime/doc/helphelp.txt +++ b/runtime/doc/helphelp.txt @@ -92,9 +92,9 @@ Help on help files *helphelp* :help k| only < Note that a space before the '|' is seen as part of the ":help" argument. - You can also use <LF> or <CR> to separate the help + You can also use <NL> or <CR> to separate the help command from a following command. You need to type - CTRL-V first to insert the <LF> or <CR>. Example: > + CTRL-V first to insert the <NL> or <CR>. Example: > :help so<C-V><CR>only < @@ -103,7 +103,11 @@ Help on help files *helphelp* current file. See |help-translated|. *:helpc* *:helpclose* -:helpc[lose] Close one help window, if there is one. +:helpc[lose] Close one help window, if there is one. + Vim will try to restore the window layout (including + cursor position) to the same layout it was before + opening the help window initially. This might cause + triggering several autocommands. *:helpg* *:helpgrep* :helpg[rep] {pattern}[@xx] @@ -155,9 +159,31 @@ When no argument is given to |:help| the file given with the 'helpfile' option will be opened. Otherwise the specified tag is searched for in all "doc/tags" files in the directories specified in the 'runtimepath' option. +If you would like to open the help in the current window, see this tip: +|help-curwin|. + The initial height of the help window can be set with the 'helpheight' option (default 20). +When the help buffer is created, several local options are set to make sure +the help text is displayed as it was intended: + 'iskeyword' nearly all ASCII chars except ' ', '*', '"' and '|' + 'foldmethod' "manual" + 'tabstop' 8 + 'arabic' off + 'binary' off + 'buflisted' off + 'cursorbind' off + 'diff' off + 'foldenable' off + 'list' off + 'modifiable' off + 'number' off + 'relativenumber' off + 'rightleft' off + 'scrollbind' off + 'spell' off + Jump to specific subjects by using tags. This can be done in two ways: - Use the "CTRL-]" command while standing on the name of a command or option. This only works when the tag is a keyword. "<C-Leftmouse>" and @@ -364,4 +390,17 @@ highlighting. So do these: You can find the details in $VIMRUNTIME/syntax/help.vim + *inclusion* +Vim is for everybody, no matter race, gender or anything. Some people make a +big deal about using "he" or "his" when referring to the user, thinking it +means we assume the user is male. That is not the case, it's just a habit of +writing help text, which quite often is many years old. Also, a lot of the +text is written by contributors for whom English is not their first language. +We do not make any assumptions about the gender of the user, no matter how the +text is phrased. Some people have suggested using "they", but that is not +regular English. We do not want to spend much time on this discussion. The +goal is that the reader understands how Vim works, the exact wording is +secondary. + + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/if_perl.txt b/runtime/doc/if_perl.txt index f1d07ddb20..ddcf220844 100644 --- a/runtime/doc/if_perl.txt +++ b/runtime/doc/if_perl.txt @@ -22,14 +22,15 @@ See |provider-perl| for more information. :[range]perl << [endmarker] {script} {endmarker} - Execute perl script {script}. Useful for including - perl code in Vim scripts. Requires perl, see - |script-here|. + Execute perl script {script}. + The {endmarker} after {script} must NOT be preceded by + any white space. -The {endmarker} below the {script} must NOT be preceded by any white space. + If [endmarker] is omitted, it defaults to a dot '.' + like for the |:append| and |:insert| commands. -If [endmarker] is omitted from after the "<<", a dot '.' must be used after -{script}, like for the |:append| and |:insert| commands. + Useful for including perl code in Vim scripts. + Requires perl, see |script-here|. Example: > function! MyVimMethod() diff --git a/runtime/doc/if_pyth.txt b/runtime/doc/if_pyth.txt index ed3bdcf277..dc46fa515a 100644 --- a/runtime/doc/if_pyth.txt +++ b/runtime/doc/if_pyth.txt @@ -189,20 +189,20 @@ vim.eval(str) *python-eval* # a number. vim.strwidth(str) *python-strwidth* - Like |strwidth()|: returns number of display cells str occupies, tab + Like |strwidth()|: returns number of display cells str occupies, tab is counted as one cell. vim.foreach_rtp(callable) *python-foreach_rtp* - Call the given callable for each path in 'runtimepath' until either - callable returns something but None, the exception is raised or there - are no longer paths. If stopped in case callable returned non-None, + Call the given callable for each path in 'runtimepath' until either + callable returns something but None, the exception is raised or there + are no longer paths. If stopped in case callable returned non-None, vim.foreach_rtp function returns the value returned by callable. vim.chdir(*args, **kwargs) *python-chdir* vim.fchdir(*args, **kwargs) *python-fchdir* Run os.chdir or os.fchdir, then all appropriate vim stuff. - Note: you should not use these functions directly, use os.chdir and - os.fchdir instead. Behavior of vim.fchdir is undefined in case + Note: you should not use these functions directly, use os.chdir and + os.fchdir instead. Behavior of vim.fchdir is undefined in case os.fchdir does not exist. Error object of the "vim" module @@ -237,15 +237,15 @@ vim.windows *python-windows* :py w in vim.windows # Membership test :py n = len(vim.windows) # Number of elements :py for w in vim.windows: # Sequential access -< Note: vim.windows object always accesses current tab page. - |python-tabpage|.windows objects are bound to parent |python-tabpage| - object and always use windows from that tab page (or throw vim.error - in case tab page was deleted). You can keep a reference to both - without keeping a reference to vim module object or |python-tabpage|, +< Note: vim.windows object always accesses current tab page. + |python-tabpage|.windows objects are bound to parent |python-tabpage| + object and always use windows from that tab page (or throw vim.error + in case tab page was deleted). You can keep a reference to both + without keeping a reference to vim module object or |python-tabpage|, they will not lose their properties in this case. vim.tabpages *python-tabpages* - A sequence object providing access to the list of vim tab pages. The + A sequence object providing access to the list of vim tab pages. The object supports the following operations: > :py t = vim.tabpages[i] # Indexing (read-only) :py t in vim.tabpages # Membership test @@ -266,12 +266,12 @@ vim.current *python-current* "current range". A range is a bit like a buffer, but with all access restricted to a subset of lines. See |python-range| for more details. - Note: When assigning to vim.current.{buffer,window,tabpage} it expects - valid |python-buffer|, |python-window| or |python-tabpage| objects - respectively. Assigning triggers normal (with |autocommand|s) - switching to given buffer, window or tab page. It is the only way to - switch UI objects in python: you can't assign to - |python-tabpage|.window attribute. To switch without triggering + Note: When assigning to vim.current.{buffer,window,tabpage} it expects + valid |python-buffer|, |python-window| or |python-tabpage| objects + respectively. Assigning triggers normal (with |autocommand|s) + switching to given buffer, window or tab page. It is the only way to + switch UI objects in python: you can't assign to + |python-tabpage|.window attribute. To switch without triggering autocommands use > py << EOF saved_eventignore = vim.options['eventignore'] @@ -284,11 +284,11 @@ vim.current *python-current* < vim.vars *python-vars* vim.vvars *python-vvars* - Dictionary-like objects holding dictionaries with global (|g:|) and + Dictionary-like objects holding dictionaries with global (|g:|) and vim (|v:|) variables respectively. vim.options *python-options* - Object partly supporting mapping protocol (supports setting and + Object partly supporting mapping protocol (supports setting and getting items) providing a read-write access to global options. Note: unlike |:set| this provides access only to global options. You cannot use this object to obtain or set local options' values or @@ -299,7 +299,7 @@ vim.options *python-options* buffer-local options and |python-window| objects to access to window-local options. - Type of this object is available via "Options" attribute of vim + Type of this object is available via "Options" attribute of vim module. Output from Python *python-output* @@ -320,10 +320,10 @@ Output from Python *python-output* *python2-directory* *python3-directory* *pythonx-directory* Python 'runtimepath' handling *python-special-path* -In python vim.VIM_SPECIAL_PATH special directory is used as a replacement for -the list of paths found in 'runtimepath': with this directory in sys.path and -vim.path_hooks in sys.path_hooks python will try to load module from -{rtp}/python2 (or python3) and {rtp}/pythonx (for both python versions) for +In python vim.VIM_SPECIAL_PATH special directory is used as a replacement for +the list of paths found in 'runtimepath': with this directory in sys.path and +vim.path_hooks in sys.path_hooks python will try to load module from +{rtp}/python2 (or python3) and {rtp}/pythonx (for both python versions) for each {rtp} found in 'runtimepath'. Implementation is similar to the following, but written in C: > @@ -351,8 +351,8 @@ Implementation is similar to the following, but written in C: > fmr = find_module(fullname, path) return load_module(fullname, *fmr) - # It uses vim module itself in place of VimPathFinder class: it does not - # matter for python which object has find_module function attached to as + # It uses vim module itself in place of VimPathFinder class: it does not + # matter for python which object has find_module function attached to as # an attribute. class VimPathFinder(object): @classmethod @@ -375,28 +375,28 @@ Implementation is similar to the following, but written in C: > sys.path_hooks.append(hook) vim.VIM_SPECIAL_PATH *python-VIM_SPECIAL_PATH* - String constant used in conjunction with vim path hook. If path hook - installed by vim is requested to handle anything but path equal to - vim.VIM_SPECIAL_PATH constant it raises ImportError. In the only other + String constant used in conjunction with vim path hook. If path hook + installed by vim is requested to handle anything but path equal to + vim.VIM_SPECIAL_PATH constant it raises ImportError. In the only other case it uses special loader. - Note: you must not use value of this constant directly, always use + Note: you must not use value of this constant directly, always use vim.VIM_SPECIAL_PATH object. vim.find_module(...) *python-find_module* vim.path_hook(path) *python-path_hook* - Methods or objects used to implement path loading as described above. - You should not be using any of these directly except for vim.path_hook - in case you need to do something with sys.meta_path. It is not - guaranteed that any of the objects will exist in the future vim + Methods or objects used to implement path loading as described above. + You should not be using any of these directly except for vim.path_hook + in case you need to do something with sys.meta_path. It is not + guaranteed that any of the objects will exist in the future vim versions. vim._get_paths *python-_get_paths* - Methods returning a list of paths which will be searched for by path - hook. You should not rely on this method being present in future + Methods returning a list of paths which will be searched for by path + hook. You should not rely on this method being present in future versions, but can use it for debugging. - It returns a list of {rtp}/python2 (or {rtp}/python3) and + It returns a list of {rtp}/python2 (or {rtp}/python3) and {rtp}/pythonx directories for each {rtp} in 'runtimepath'. ============================================================================== @@ -425,21 +425,21 @@ line numbers, which start from 1. This is particularly relevant when dealing with marks (see below) which use vim line numbers. The buffer object attributes are: - b.vars Dictionary-like object used to access + b.vars Dictionary-like object used to access |buffer-variable|s. - b.options Mapping object (supports item getting, setting and - deleting) that provides access to buffer-local options - and buffer-local values of |global-local| options. Use - |python-window|.options if option is window-local, - this object will raise KeyError. If option is - |global-local| and local value is missing getting it + b.options Mapping object (supports item getting, setting and + deleting) that provides access to buffer-local options + and buffer-local values of |global-local| options. Use + |python-window|.options if option is window-local, + this object will raise KeyError. If option is + |global-local| and local value is missing getting it will return None. b.name String, RW. Contains buffer name (full path). - Note: when assigning to b.name |BufFilePre| and + Note: when assigning to b.name |BufFilePre| and |BufFilePost| autocommands are launched. b.number Buffer number. Can be used as |python-buffers| key. Read-only. - b.valid True or False. Buffer object becomes invalid when + b.valid True or False. Buffer object becomes invalid when corresponding buffer is wiped out. The buffer object methods are: @@ -527,16 +527,16 @@ Window attributes are: This is a tuple, (row,col). height (read-write) The window height, in rows width (read-write) The window width, in columns - vars (read-only) The window |w:| variables. Attribute is - unassignable, but you can change window + vars (read-only) The window |w:| variables. Attribute is + unassignable, but you can change window variables this way - options (read-only) The window-local options. Attribute is - unassignable, but you can change window - options this way. Provides access only to - window-local options, for buffer-local use - |python-buffer| and for global ones use - |python-options|. If option is |global-local| - and local value is missing getting it will + options (read-only) The window-local options. Attribute is + unassignable, but you can change window + options this way. Provides access only to + window-local options, for buffer-local use + |python-buffer| and for global ones use + |python-options|. If option is |global-local| + and local value is missing getting it will return None. number (read-only) Window number. The first window has number 1. This is zero in case it cannot be determined @@ -545,7 +545,7 @@ Window attributes are: row, col (read-only) On-screen window position in display cells. First position is zero. tabpage (read-only) Window tab page. - valid (read-write) True or False. Window object becomes invalid + valid (read-write) True or False. Window object becomes invalid when corresponding window is closed. The height attribute is writable only if the screen is split horizontally. @@ -556,21 +556,21 @@ Window object type is available using "Window" attribute of vim module. ============================================================================== Tab page objects *python-tabpage* -Tab page objects represent vim tab pages. You can obtain them in a number of +Tab page objects represent vim tab pages. You can obtain them in a number of ways: - via vim.current.tabpage (|python-current|) - from indexing vim.tabpages (|python-tabpages|) -You can use this object to access tab page windows. They have no methods and +You can use this object to access tab page windows. They have no methods and no sequence or other interfaces. Tab page attributes are: - number The tab page number like the one returned by + number The tab page number like the one returned by |tabpagenr()|. windows Like |python-windows|, but for current tab page. vars The tab page |t:| variables. window Current tabpage window. - valid True or False. Tab page object becomes invalid when + valid True or False. Tab page object becomes invalid when corresponding tab page is closed. TabPage object type is available using "TabPage" attribute of vim module. @@ -578,7 +578,7 @@ TabPage object type is available using "TabPage" attribute of vim module. ============================================================================== pyeval() and py3eval() Vim functions *python-pyeval* -To facilitate bi-directional interface, you can use |pyeval()| and |py3eval()| +To facilitate bi-directional interface, you can use |pyeval()| and |py3eval()| functions to evaluate Python expressions and pass their values to Vim script. |pyxeval()| is also available. @@ -586,17 +586,28 @@ functions to evaluate Python expressions and pass their values to Vim script. Python 3 *python3* *:py3* *:python3* -The `:py3` and `:python3` commands work similar to `:python`. A simple check -if the `:py3` command is working: > - :py3 print("Hello") +:[range]py3 {stmt} +:[range]py3 << [endmarker] +{script} +{endmarker} -To see what version of Python you have: > - :py3 import sys - :py3 print(sys.version) +:[range]python3 {stmt} +:[range]python3 << [endmarker] +{script} +{endmarker} + The `:py3` and `:python3` commands work similar to `:python`. A + simple check if the `:py3` command is working: > + :py3 print("Hello") +< + To see what version of Python you have: > + :py3 import sys + :py3 print(sys.version) < *:py3file* -The `:py3file` command works similar to `:pyfile`. +:[range]py3f[ile] {file} + The `:py3file` command works similar to `:pyfile`. *:py3do* -The `:py3do` command works similar to `:pydo`. +:[range]py3do {body} + The `:py3do` command works similar to `:pydo`. *E880* Raising SystemExit exception in python isn't endorsed way to quit vim, use: > diff --git a/runtime/doc/if_ruby.txt b/runtime/doc/if_ruby.txt index c8d2409549..02edd50ae8 100644 --- a/runtime/doc/if_ruby.txt +++ b/runtime/doc/if_ruby.txt @@ -19,14 +19,14 @@ downloading Ruby there. :rub[y] {cmd} Execute Ruby command {cmd}. A command to try it out: > :ruby print "Hello" -:rub[y] << [endpattern] +:rub[y] << [endmarker] {script} -{endpattern} +{endmarker} Execute Ruby script {script}. - The {endpattern} after {script} must NOT be preceded - by any white space. + The {endmarker} after {script} must NOT be preceded by + any white space. - If [endpattern] is omitted, it defaults to a dot '.' + If [endmarker] is omitted, it defaults to a dot '.' like for the |:append| and |:insert| commands. This form of the |:ruby| command is mainly useful for diff --git a/runtime/doc/indent.txt b/runtime/doc/indent.txt index f2278f8453..dfd81d7170 100644 --- a/runtime/doc/indent.txt +++ b/runtime/doc/indent.txt @@ -410,11 +410,11 @@ The examples below assume a 'shiftwidth' of 4. < *cino-(* (N When in unclosed parentheses, indent N characters from the line - with the unclosed parentheses. Add a 'shiftwidth' for every + with the unclosed parenthesis. Add a 'shiftwidth' for every extra unclosed parentheses. When N is 0 or the unclosed - parentheses is the first non-white character in its line, line + parenthesis is the first non-white character in its line, line up with the next non-white character after the unclosed - parentheses. (default 'shiftwidth' * 2). + parenthesis. (default 'shiftwidth' * 2). cino= cino=(0 > if (c1 && (c2 || if (c1 && (c2 || @@ -435,7 +435,7 @@ The examples below assume a 'shiftwidth' of 4. < *cino-U* UN When N is non-zero, do not ignore the indenting specified by - ( or u in case that the unclosed parentheses is the first + ( or u in case that the unclosed parenthesis is the first non-white character in its line. (default 0). cino= or cino=(s cino=(s,U1 > @@ -448,8 +448,8 @@ The examples below assume a 'shiftwidth' of 4. *cino-w* wN When in unclosed parentheses and N is non-zero and either using "(0" or "u0", respectively, or using "U0" and the unclosed - parentheses is the first non-white character in its line, line - up with the character immediately after the unclosed parentheses + parenthesis is the first non-white character in its line, line + up with the character immediately after the unclosed parenthesis rather than the first non-white character. (default 0). cino=(0 cino=(0,w1 > @@ -460,11 +460,11 @@ The examples below assume a 'shiftwidth' of 4. < *cino-W* WN When in unclosed parentheses and N is non-zero and either - using "(0" or "u0", respectively and the unclosed parentheses is + using "(0" or "u0", respectively and the unclosed parenthesis is the last non-white character in its line and it is not the - closing parentheses, indent the following line N characters + closing parenthesis, indent the following line N characters relative to the outer context (i.e. start of the line or the - next unclosed parentheses). (default: 0). + next unclosed parenthesis). (default: 0). cino=(0 cino=(0,W4 > a_long_line( a_long_line( @@ -491,8 +491,8 @@ The examples below assume a 'shiftwidth' of 4. < *cino-m* mN When N is non-zero, line up a line starting with a closing - parentheses with the first character of the line with the - matching opening parentheses. (default 0). + parenthesis with the first character of the line with the + matching opening parenthesis. (default 0). cino=(s cino=(s,m1 > c = c1 && ( c = c1 && ( @@ -506,7 +506,7 @@ The examples below assume a 'shiftwidth' of 4. < *cino-M* MN When N is non-zero, line up a line starting with a closing - parentheses with the first character of the previous line. + parenthesis with the first character of the previous line. (default 0). cino= cino=M1 > @@ -528,7 +528,7 @@ The examples below assume a 'shiftwidth' of 4. < *javascript-cinoptions* *javascript-indenting* *cino-J* JN Indent JavaScript object declarations correctly by not confusing - them with labels. The value 'N' is currently unused but must be + them with labels. The value 'N' is currently unused but must be non-zero (e.g. 'J1'). If you enable this you probably also want to set |cino-j|. > @@ -537,7 +537,7 @@ The examples below assume a 'shiftwidth' of 4. that: this, some: ok, }, - "bar":{ + "bar":{ a : 2, b: "123abc", x: 4, @@ -565,7 +565,7 @@ The examples below assume a 'shiftwidth' of 4. recognize preprocessor lines; right-shifting lines that start with "#" does not work. - + *cino-P* PN When N is non-zero recognize C pragmas, and indent them like any other code; does not concern other preprocessor directives. When N is zero (default): don't recognize C pragmas, treating @@ -606,14 +606,14 @@ the use of square and curly brackets, and otherwise by community convention. These conventions are not universally followed, so the Clojure indent script offers a few configurable options, listed below. -If the current vim does not include |searchpairpos()|, the indent script falls +If the current vim does not include searchpairpos(), the indent script falls back to normal 'lisp' indenting, and the following options are ignored. *g:clojure_maxlines* -Set maximum scan distance of |searchpairpos()|. Larger values trade -performance for correctness when dealing with very long forms. A value of 0 -will scan without limits. +Set maximum scan distance of searchpairpos(). Larger values trade performance +for correctness when dealing with very long forms. A value of 0 will scan +without limits. > " Default let g:clojure_maxlines = 100 @@ -814,6 +814,16 @@ Detail: <!-- --> : -1 +MATLAB *ft-matlab-indent* *matlab-indent* *matlab-indenting* + +The setting Function indenting format in MATLAB Editor/Debugger Language +Preferences corresponds to: > + :let g:MATLAB_function_indent = {0, 1 or 2 (default)} + +Where 0 is for Classic, 1 for Indent nested functions and 2 for Indent all +functions. + + PHP *ft-php-indent* *php-indent* *php-indenting* NOTE: PHP files will be indented correctly only if PHP |syntax| is active. @@ -887,7 +897,7 @@ To automatically remove '\r' characters when the 'fileformat' is set to Unix: > *PHP_BracesAtCodeLevel* To indent braces at the same level than the code they contain: > :let g:PHP_BracesAtCodeLevel = 1 - + This will give the following result: > if ($foo) { @@ -951,10 +961,12 @@ Function call arguments will indent 1 extra level. For two-space indentation: > ------------- *PHP_IndentFunctionDeclarationParameters* -Extra indentation levels to add to arguments in multi-line function definitions. > +Extra indentation levels to add to arguments in multi-line function +definitions. > let g:PHP_IndentFunctionDeclarationParameters = 1 -Function arguments in declarations will indent 1 extra level. For two-space indentation: > +Function arguments in declarations will indent 1 extra level. For two-space +indentation: > function call_the_thing( $with_this, @@ -980,7 +992,7 @@ Indent after a nested paren: > Indent for a continuation line: > let g:pyindent_continue = 'shiftwidth() * 2' -The method uses |searchpair()| to look back for unclosed parenthesis. This +The method uses |searchpair()| to look back for unclosed parentheses. This can sometimes be slow, thus it timeouts after 150 msec. If you notice the indenting isn't correct, you can set a larger timeout in msec: > let g:pyindent_searchpair_timeout = 500 diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt index c824a9f9f6..e7d891bc33 100644 --- a/runtime/doc/index.txt +++ b/runtime/doc/index.txt @@ -61,22 +61,26 @@ tag char action in Insert mode ~ the cursor |i_CTRL-Q| CTRL-Q same as CTRL-V, unless used for terminal control flow -|i_CTRL-R| CTRL-R {0-9a-z"%#*:=} +|i_CTRL-SHIFT-Q| CTRL-SHIFT-Q {char} + like CTRL-Q unless |modifyOtherKeys| is active +|i_CTRL-R| CTRL-R {register} insert the contents of a register -|i_CTRL-R_CTRL-R| CTRL-R CTRL-R {0-9a-z"%#*:=} +|i_CTRL-R_CTRL-R| CTRL-R CTRL-R {register} insert the contents of a register literally -|i_CTRL-R_CTRL-O| CTRL-R CTRL-O {0-9a-z"%#*:=} +|i_CTRL-R_CTRL-O| CTRL-R CTRL-O {register} insert the contents of a register literally and don't auto-indent -|i_CTRL-R_CTRL-P| CTRL-R CTRL-P {0-9a-z"%#*:=} +|i_CTRL-R_CTRL-P| CTRL-R CTRL-P {register} insert the contents of a register literally and fix indent. - CTRL-S (used for terminal control flow) + CTRL-S not used or used for terminal control flow |i_CTRL-T| CTRL-T insert one shiftwidth of indent in current line |i_CTRL-U| CTRL-U delete all entered characters in the current line |i_CTRL-V| CTRL-V {char} insert next non-digit literally +|i_CTRL-SHIFT-V| CTRL-SHIFT-V {char} + like CTRL-V unless |modifyOtherKeys| is active |i_CTRL-V_digit| CTRL-V {number} insert three digit decimal number as a single byte. |i_CTRL-W| CTRL-W delete word before the cursor @@ -203,9 +207,9 @@ tag char note action in Normal mode ~ |CTRL-N| CTRL-N 1 same as "j" |CTRL-O| CTRL-O 1 go to N older entry in jump list |CTRL-P| CTRL-P 1 same as "k" - CTRL-Q (used for terminal control flow) + CTRL-Q not used, or used for terminal control flow |CTRL-R| CTRL-R 2 redo changes which were undone with 'u' - CTRL-S (used for terminal control flow) + CTRL-S not used, or used for terminal control flow |CTRL-T| CTRL-T jump to N older Tag in tag list |CTRL-U| CTRL-U scroll N lines Upwards (default: half a screen) @@ -231,8 +235,7 @@ tag char note action in Normal mode ~ 2 filter Nmove text through the {filter} command |!!| !!{filter} 2 filter N lines through the {filter} command -|quote| "{a-zA-Z0-9.%#:-"} use register {a-zA-Z0-9.%#:-"} for next - delete, yank or put (uppercase to append) +|quote| "{register} use {register} for next delete, yank or put ({.%#:} only work with put) |#| # 1 search backward for the Nth occurrence of the ident under the cursor @@ -350,8 +353,8 @@ tag char note action in Normal mode ~ register x] |Y| ["x]Y yank N lines [into register x]; synonym for "yy" -|ZZ| ZZ store current file if modified, and exit -|ZQ| ZQ exit current file always +|ZZ| ZZ write if buffer changed and close window +|ZQ| ZQ close window without writing |[| [{char} square bracket command (see |[| below) \ not used |]| ]{char} square bracket command (see |]| below) @@ -768,10 +771,10 @@ tag char note action in Normal mode ~ lines down |gk| gk 1 like "k", but when 'wrap' on go N screen lines up -|gn| gn 1,2 find the next match with the last used - search pattern and Visually select it |gm| gm 1 go to character at middle of the screenline |gM| gM 1 go to character at middle of the text line +|gn| gn 1,2 find the next match with the last used + search pattern and Visually select it |go| go 1 cursor to byte N in the buffer |gp| ["x]gp 2 put the text [from register x] after the cursor N times, leave the cursor after it @@ -816,7 +819,7 @@ tag char note action in Normal mode ~ |zD| zD delete folds recursively |zE| zE eliminate all folds |zF| zF create a fold for N lines -|zG| zG mark word as good spelled word +|zG| zG temporarily mark word as correctly spelled |zH| zH when 'wrap' off scroll half a screenwidth to the right |zL| zL when 'wrap' off scroll half a screenwidth @@ -825,7 +828,7 @@ tag char note action in Normal mode ~ |zN| zN set 'foldenable' |zO| zO open folds recursively |zR| zR set 'foldlevel' to the deepest fold -|zW| zW mark word as wrong (bad) spelled word +|zW| zW temporarily mark word as incorrectly spelled |zX| zX re-apply 'foldlevel' |z^| z^ cursor on line N (default line above window), otherwise like "z-" @@ -837,7 +840,7 @@ tag char note action in Normal mode ~ position the cursor at the end (right side) of the screen |zf| zf{motion} create a fold for Nmove text -|zg| zg mark word as good spelled word +|zg| zg permanently mark word as correctly spelled |zh| zh when 'wrap' off scroll screen N characters to the right |zi| zi toggle 'foldenable' @@ -858,7 +861,7 @@ tag char note action in Normal mode ~ |zuW| zuW undo |zW| |zuG| zuG undo |zG| |zv| zv open enough folds to view the cursor line -|zw| zw mark word as wrong (bad) spelled word +|zw| zw permanently mark word as incorrectly spelled |zx| zx re-apply 'foldlevel' and do "zv" |zz| zz redraw, cursor line at center of window |z<Left>| z<Left> same as "zh" @@ -1044,7 +1047,7 @@ tag command action in Command-line editing mode ~ |c_CTRL-R_CTRL-O| CTRL-R CTRL-O {regname} insert the contents of a register or object under the cursor literally - CTRL-S (used for terminal control flow) + CTRL-S not used, or used for terminal control flow |c_CTRL-T| CTRL-T previous match when 'incsearch' is active |c_CTRL-U| CTRL-U remove all characters |c_CTRL-V| CTRL-V insert next non-digit literally, insert three @@ -1232,11 +1235,11 @@ tag command action ~ |:cunmenu| :cunme[nu] remove menu for Command-line mode |:cwindow| :cw[indow] open or close quickfix window |:delete| :d[elete] delete lines -|:delmarks| :delm[arks] delete marks |:debug| :deb[ug] run a command in debugging mode |:debuggreedy| :debugg[reedy] read debug mode commands from normal input |:delcommand| :delc[ommand] delete user-defined command |:delfunction| :delf[unction] delete a user function +|:delmarks| :delm[arks] delete marks |:diffupdate| :dif[fupdate] update 'diff' buffers |:diffget| :diffg[et] remove differences in current buffer |:diffoff| :diffo[ff] switch off diff mode @@ -1248,7 +1251,6 @@ tag command action ~ |:display| :di[splay] display registers |:djump| :dj[ump] jump to #define |:dl| :dl short for |:delete| with the 'l' flag -|:del| :del[ete]l short for |:delete| with the 'l' flag |:dlist| :dli[st] list #defines |:doautocmd| :do[autocmd] apply autocommands to current buffer |:doautoall| :doautoa[ll] apply autocommands for all loaded buffers @@ -1269,7 +1271,7 @@ tag command action ~ |:emenu| :em[enu] execute a menu by name |:endif| :en[dif] end previous :if |:endfor| :endfo[r] end previous :for -|:endfunction| :endf[unction] end of a user function +|:endfunction| :endf[unction] end of a user function started with :function |:endtry| :endt[ry] end previous :try |:endwhile| :endw[hile] end previous :while |:enew| :ene[w] edit a new, unnamed buffer @@ -1674,7 +1676,7 @@ tag command action ~ |:wqall| :wqa[ll] write all changed buffers and quit Vim |:wshada| :wsh[ada] write to ShaDa file |:wundo| :wu[ndo] write undo information to a file -|:xit| :x[it] write if buffer changed and quit window or Vim +|:xit| :x[it] write if buffer changed and close window |:xall| :xa[ll] same as ":wqall" |:xmapclear| :xmapc[lear] remove all mappings for Visual mode |:xmap| :xm[ap] like ":map" but for Visual mode diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt index 6902ed5fd4..c8a4168ab2 100644 --- a/runtime/doc/insert.txt +++ b/runtime/doc/insert.txt @@ -95,7 +95,7 @@ CTRL-K {char1} [char2] CTRL-N Find next keyword (see |i_CTRL-N|). CTRL-P Find previous keyword (see |i_CTRL-P|). -CTRL-R {0-9a-z"%#*+:.-=} *i_CTRL-R* +CTRL-R {register} *i_CTRL-R* Insert the contents of a register. Between typing CTRL-R and the second character, '"' will be displayed to indicate that you are expected to enter the name of a register. @@ -132,7 +132,7 @@ CTRL-R {0-9a-z"%#*+:.-=} *i_CTRL-R* sequence will be broken. See |registers| about registers. -CTRL-R CTRL-R {0-9a-z"%#*+/:.-=} *i_CTRL-R_CTRL-R* +CTRL-R CTRL-R {register} *i_CTRL-R_CTRL-R* Insert the contents of a register. Works like using a single CTRL-R, but the text is inserted literally, not as if typed. This differs when the register contains characters like <BS>. @@ -143,8 +143,10 @@ CTRL-R CTRL-R {0-9a-z"%#*+/:.-=} *i_CTRL-R_CTRL-R* you also want to avoid these, use CTRL-R CTRL-O, see below. The '.' register (last inserted text) is still inserted as typed. + After this command, the '.' register contains the text from + the register as if it was inserted by typing it. -CTRL-R CTRL-O {0-9a-z"%#*+/:.-=} *i_CTRL-R_CTRL-O* +CTRL-R CTRL-O {register} *i_CTRL-R_CTRL-O* Insert the contents of a register literally and don't auto-indent. Does the same as pasting with the mouse |<MiddleMouse>|. When the register is linewise this will @@ -152,13 +154,19 @@ CTRL-R CTRL-O {0-9a-z"%#*+/:.-=} *i_CTRL-R_CTRL-O* Does not replace characters! The '.' register (last inserted text) is still inserted as typed. + After this command, the '.' register contains the command + typed and not the text. I.e., the literals "^R^O" and not the + text from the register. -CTRL-R CTRL-P {0-9a-z"%#*+/:.-=} *i_CTRL-R_CTRL-P* +CTRL-R CTRL-P {register} *i_CTRL-R_CTRL-P* Insert the contents of a register literally and fix the indent, like |[<MiddleMouse>|. Does not replace characters! The '.' register (last inserted text) is still inserted as typed. + After this command, the '.' register contains the command + typed and not the text. I.e., the literals "^R^P" and not the + text from the register. *i_CTRL-T* CTRL-T Insert one shiftwidth of indent at the start of the current @@ -284,6 +292,7 @@ If you enter a value of 10, it will end up in the file as a 0. The 10 is a the buffer to a file, the <NL> character is translated into <Nul>. The <NL> character is written at the end of each line. Thus if you want to insert a <NL> character in a file you will have to make a line break. +Also see 'fileformat'. *i_CTRL-X* *insert_expand* CTRL-X enters a sub-mode where several commands can be used. Most of these @@ -358,7 +367,7 @@ CTRL-\ CTRL-O like CTRL-O but don't move the cursor *i_CTRL-\_CTRL-O* CTRL-L when 'insertmode' is set: go to Normal mode *i_CTRL-L* CTRL-G u break undo sequence, start new change *i_CTRL-G_u* CTRL-G U don't break undo with next left/right cursor *i_CTRL-G_U* - movement, if the cursor stays within + movement, if the cursor stays within the same the line ----------------------------------------------------------------------- @@ -1760,6 +1769,7 @@ a Append text after the cursor [count] times. If the *A* A Append text at the end of the line [count] times. + For using "A" in Visual block mode see |v_b_A|. <insert> or *i* *insert* *<Insert>* i Insert text before the cursor [count] times. @@ -1772,6 +1782,7 @@ I Insert text before the first non-blank in the line When the 'H' flag is present in 'cpoptions' and the line only contains blanks, insert start just before the last blank. + For using "I" in Visual block mode see |v_b_I|. *gI* gI Insert text in column 1 [count] times. @@ -1937,11 +1948,11 @@ If the 'fileformats' option is not empty Vim tries to recognize the type of changed, the detected format is only used while reading the file. A similar thing happens with 'fileencodings'. -On non-Windows systems the message "[dos format]" is shown if -a file is read in DOS format, to remind you that something unusual is done. -On Macintosh and Windows the message "[unix format]" is shown if -a file is read in Unix format. -On non-Macintosh systems, the message "[Mac format]" is shown if a file is +On non-Win32 systems the message "[dos format]" is shown if a file is read in +DOS format, to remind you that something unusual is done. +On Macintosh and Win32 the message "[unix format]" is shown if a file is read +in Unix format. +On non-Macintosh systems, the message "[mac format]" is shown if a file is read in Mac format. An example on how to use ":r !": > diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt index d858985e3f..925b3e5dbb 100644 --- a/runtime/doc/intro.txt +++ b/runtime/doc/intro.txt @@ -139,11 +139,11 @@ Vim would never have become what it is now, without the help of these people! Flemming Madsen X11 client-server, various features and patches Tony Mechelynck answers many user questions Paul Moore Python interface extensions, many patches - Katsuhito Nagano Work on multi-byte versions - Sung-Hyun Nam Work on multi-byte versions + Katsuhito Nagano Work on multibyte versions + Sung-Hyun Nam Work on multibyte versions Vince Negri Win32 GUI and generic console enhancements Steve Oualline Author of the first Vim book |frombook| - Dominique Pelle valgrind reports and many fixes + Dominique Pelle Valgrind reports and many fixes A.Politz Many bug reports and some fixes George V. Reilly Win32 port, Win32 GUI start-off Stephen Riehm bug collector @@ -324,7 +324,7 @@ notation meaning equivalent decimal value(s) ~ <CSI> command sequence intro ALT-Esc 155 *<CSI>* <xCSI> CSI when typed in the GUI *<xCSI>* -<EOL> end-of-line (can be <CR>, <LF> or <CR><LF>, +<EOL> end-of-line (can be <CR>, <NL> or <CR><NL>, depends on system and 'fileformat') *<EOL>* <Ignore> cancel wait-for-character *<Ignore>* <NOP> no-op: do nothing (useful in mappings) *<Nop>* diff --git a/runtime/doc/makehtml.awk b/runtime/doc/makehtml.awk index 6e93c01c54..50f5611fa7 100644 --- a/runtime/doc/makehtml.awk +++ b/runtime/doc/makehtml.awk @@ -65,7 +65,7 @@ substr($0,length($0),1) == "~" { print "<B><FONT COLOR=\"PURPLE\">" substr($0,1, # #ad hoc code # -/^"\|\& / {gsub(/\|/,"\\|"); } +/^"\|& / {gsub(/\|/,"\\|"); } / = b / {gsub(/ b /," \\b "); } # # one letter tag diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt index 73ac3763d0..ee42edf154 100644 --- a/runtime/doc/map.txt +++ b/runtime/doc/map.txt @@ -176,6 +176,12 @@ whether to use the "," mapping or the longer one. To avoid this add the <nowait> argument. Then the mapping will be used when it matches, Vim does not wait for more characters to be typed. However, if the characters were already typed they are used. +Note that this works when the <nowait> mapping fully matches and is found +before any partial matches. This works when: +- There is only one matching buffer-local mapping, since these are always + found before global mappings. +- There is another buffer-local mapping that partly matches, but it is + defined earlier (last defined mapping is found first). *:map-<silent>* *:map-silent* To define a mapping which will not be echoed on the command line, add @@ -217,14 +223,23 @@ have a look at |maparg()|. If the first argument to one of these commands is "<expr>" and it is used to define a new mapping or abbreviation, the argument is an expression. The expression is evaluated to obtain the {rhs} that is used. Example: > - :inoremap <expr> . InsertDot() -The result of the InsertDot() function will be inserted. It could check the + :inoremap <expr> . <SID>InsertDot() +The result of the s:InsertDot() function will be inserted. It could check the text before the cursor and start omni completion when some condition is met. +Using a script-local function is preferred, to avoid polluting the global +namespace. Use <SID> in the RHS so that the script that the mapping was +defined in can be found. For abbreviations |v:char| is set to the character that was typed to trigger the abbreviation. You can use this to decide how to expand the {lhs}. You should not either insert or change the v:char. - + +In case you want the mapping to not do anything, you can have the expression +evaluate to an empty string. If something changed that requires Vim to +go through the main loop (e.g. to update the display), return "\<Ignore>". +This is similar to "nothing" but makes Vim return from the loop that waits for +input. + Also, keep in mind that the expression may be evaluated when looking for typeahead, before the previous command has been executed. For example: > func StoreColumn() @@ -233,8 +248,8 @@ typeahead, before the previous command has been executed. For example: > endfunc nnoremap <expr> x StoreColumn() nmap ! f!x -You will notice that g:column has the value from before executing "fx", -because "z" is evaluated before "fx" is executed. +You will notice that g:column has the value from before executing "f!", +because "x" is evaluated before "f!" is executed. This can be solved by inserting <Ignore> before the character that is expression-mapped: > nmap ! f!<Ignore>x @@ -277,15 +292,8 @@ Here is an example that inserts a list number that increases: > CTRL-L inserts the next number, CTRL-R resets the count. CTRL-R returns an empty string, so that nothing is inserted. -Note that there are some tricks to make special keys work and escape CSI bytes -in the text. The |:map| command also does this, thus you must avoid that it -is done twice. This does not work: > - :imap <expr> <F3> "<Char-0x611B>" -Because the <Char- sequence is escaped for being a |:imap| argument and then -again for using <expr>. This does work: > - :imap <expr> <F3> "\u611B" -Using 0x80 as a single byte before other text does not work, it will be seen -as a special key. +Note that using 0x80 as a single byte before other text does not work, it will +be seen as a special key. *<Cmd>* *:map-cmd* The <Cmd> pseudokey begins a "command mapping", which executes the command @@ -301,14 +309,17 @@ preserved, so tricks with |gv| are not needed. Commands can be invoked directly in cmdline-mode (which would otherwise require timer hacks). Unlike <expr> mappings, there are no special restrictions on the <Cmd> -command: it is executed as if an (unrestricted) |autocmd| was invoked or an -async event event was processed. +command: it is executed as if an (unrestricted) |autocommand| was invoked +or an async event event was processed. Note: - Because <Cmd> avoids mode-changes (unlike ":") it does not trigger |CmdlineEnter| and |CmdlineLeave| events. This helps performance. - For the same reason, |keycodes| like <C-R><C-W> are interpreted as plain, unmapped keys. +- The command is not echo'ed, no need for <silent>. +- In Visual mode you can use `line('v')` and `col('v')` to get one end of the + Visual area, the cursor is at the other end. - In select-mode, |:map| and |:vmap| command mappings are executed in visual-mode. Use |:smap| to handle select-mode. @@ -382,6 +393,8 @@ Some commands work both in Insert mode and Command-line mode, some not: :cmap :cnoremap :cunmap :cmapclear - yes - :lmap :lnoremap :lunmap :lmapclear yes* yes* yes* +* If 'iminsert' is 1, see |language-mapping| below. + The original Vi did not have separate mappings for Normal/Visual/Operator-pending mode and for Insert/Command-line mode. Therefore the ":map" and ":map!" commands enter and display mappings for @@ -599,7 +612,7 @@ construct can be used: <Char-033> character 27 <Char-0x7f> character 127 <S-Char-114> character 114 ('r') shifted ('R') -This is useful to specify a (multi-byte) character in a 'keymap' file. +This is useful to specify a (multibyte) character in a 'keymap' file. Upper and lowercase differences are ignored. *map-comments* @@ -788,7 +801,7 @@ otherwise it is interpreted as two key presses: 1.11 MAPPING AN OPERATOR *:map-operator* An operator is used before a {motion} command. To define your own operator -you must create mapping that first sets the 'operatorfunc' option and then +you must create a mapping that first sets the 'operatorfunc' option and then invoke the |g@| operator. After the user types the {motion} command the specified function will be called. @@ -806,35 +819,47 @@ g@{motion} Call the function set by the 'operatorfunc' option. Here is an example that counts the number of spaces with <F4>: > - nmap <silent> <F4> :set opfunc=CountSpaces<CR>g@ - vmap <silent> <F4> :<C-U>call CountSpaces(visualmode(), 1)<CR> + nnoremap <expr> <F4> CountSpaces() + xnoremap <expr> <F4> CountSpaces() + " doubling <F4> works on a line + nnoremap <expr> <F4><F4> CountSpaces() .. '_' - function! CountSpaces(type, ...) - let sel_save = &selection - let &selection = "inclusive" - let reg_save = @@ - - if a:0 " Invoked from Visual mode, use gv command. - silent exe "normal! gvy" - elseif a:type == 'line' - silent exe "normal! '[V']y" - else - silent exe "normal! `[v`]y" + function CountSpaces(type = '') abort + if a:type == '' + set opfunc=CountSpaces + return 'g@' endif - echomsg strlen(substitute(@@, '[^ ]', '', 'g')) - - let &selection = sel_save - let @@ = reg_save + let sel_save = &selection + let reg_save = getreginfo('"') + let cb_save = &clipboard + let visual_marks_save = [getpos("'<"), getpos("'>")] + + try + set clipboard= selection=inclusive + let commands = #{line: "'[V']y", char: "`[v`]y", block: "`[\<c-v>`]y"} + silent exe 'noautocmd keepjumps normal! ' .. get(commands, a:type, '') + echom getreg('"')->count(' ') + finally + call setreg('"', reg_save) + call setpos("'<", visual_marks_save[0]) + call setpos("'>", visual_marks_save[1]) + let &clipboard = cb_save + let &selection = sel_save + endtry endfunction +An <expr> mapping is used to be able to fetch any prefixed count and register. +This also avoids using a command line, which would trigger CmdlineEnter and +CmdlineLeave autocommands. + Note that the 'selection' option is temporarily set to "inclusive" to be able to yank exactly the right text by using Visual mode from the '[ to the '] mark. -Also note that there is a separate mapping for Visual mode. It removes the -"'<,'>" range that ":" inserts in Visual mode and invokes the function with -visualmode() and an extra argument. +Also note that the 'clipboard' option is temporarily emptied to avoid +clobbering the `"*` or `"+` registers, if its value contains the item `unnamed` +or `unnamedplus`. ============================================================================== 2. Abbreviations *abbreviations* *Abbreviations* @@ -973,7 +998,8 @@ See |:verbose-cmd| for more information. See |:map-<buffer>| for the optional <buffer> argument. *:una* *:unabbreviate* -:una[bbreviate] {lhs} Remove abbreviation for {lhs} from the list. If none +:una[bbreviate] [<buffer>] {lhs} + Remove abbreviation for {lhs} from the list. If none is found, remove abbreviations in which {lhs} matches with the {rhs}. This is done so that you can even remove abbreviations after expansion. To avoid @@ -988,7 +1014,8 @@ See |:verbose-cmd| for more information. same as ":ab", but for Command-line mode only. *:cuna* *:cunabbrev* -:cuna[bbrev] {lhs} same as ":una", but for Command-line mode only. +:cuna[bbrev] [<buffer>] {lhs} + Same as ":una", but for Command-line mode only. *:cnorea* *:cnoreabbrev* :cnorea[bbrev] [<expr>] [<buffer>] [lhs] [rhs] @@ -1000,7 +1027,8 @@ See |:verbose-cmd| for more information. same as ":ab", but for Insert mode only. *:iuna* *:iunabbrev* -:iuna[bbrev] {lhs} same as ":una", but for insert mode only. +:iuna[bbrev] [<buffer>] {lhs} + Same as ":una", but for insert mode only. *:inorea* *:inoreabbrev* :inorea[bbrev] [<expr>] [<buffer>] [lhs] [rhs] @@ -1100,9 +1128,9 @@ Otherwise, using "<SID>" outside of a script context is an error. If you need to get the script number to use in a complicated script, you can use this function: > - function s:SID() - return matchstr(expand('<sfile>'), '<SNR>\zs\d\+\ze_SID$') - endfun + func s:ScriptNumber() + return matchstr(expand('<SID>'), '<SNR>\zs\d\+\ze_') + endfunc The "<SNR>" will be shown when listing functions and mappings. This is useful to find out what they are defined to. @@ -1175,15 +1203,15 @@ last defined. Example: > See |:verbose-cmd| for more information. *E174* *E182* -:com[mand][!] [{attr}...] {cmd} {rep} +:com[mand][!] [{attr}...] {cmd} {repl} Define a user command. The name of the command is - {cmd} and its replacement text is {rep}. The command's - attributes (see below) are {attr}. If the command - already exists, an error is reported, unless a ! is - specified, in which case the command is redefined. - There is one exception: When sourcing a script again, - a command that was previously defined in that script - will be silently replaced. + {cmd} and its replacement text is {repl}. The + command's attributes (see below) are {attr}. If the + command already exists, an error is reported, unless a + ! is specified, in which case the command is + redefined. There is one exception: When sourcing a + script again, a command that was previously defined in + that script will be silently replaced. :delc[ommand] {cmd} *:delc* *:delcommand* *E184* @@ -1390,11 +1418,11 @@ feature. Use the full name for new scripts. Replacement text ~ -The replacement text for a user defined command is scanned for special escape -sequences, using <...> notation. Escape sequences are replaced with values -from the entered command line, and all other text is copied unchanged. The -resulting string is executed as an Ex command. To avoid the replacement use -<lt> in place of the initial <. Thus to include "<bang>" literally use +The replacement text {repl} for a user defined command is scanned for special +escape sequences, using <...> notation. Escape sequences are replaced with +values from the entered command line, and all other text is copied unchanged. +The resulting string is executed as an Ex command. To avoid the replacement +use <lt> in place of the initial <. Thus to include "<bang>" literally use "<lt>bang>". The valid escape sequences are @@ -1412,7 +1440,7 @@ 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>* *<q-mods>* *:command-modifiers* <mods> The command modifiers, if specified. Otherwise, expands to nothing. Supported modifiers are |:aboveleft|, |:belowright|, |:botright|, |:browse|, |:confirm|, |:hide|, |:keepalt|, diff --git a/runtime/doc/mbyte.txt b/runtime/doc/mbyte.txt index a6410a09cb..a6c797a860 100644 --- a/runtime/doc/mbyte.txt +++ b/runtime/doc/mbyte.txt @@ -22,7 +22,7 @@ Getting started *mbyte-first* This is a summary of the multibyte features in Vim. If you are lucky it works as described and you can start using Vim without much trouble. If something doesn't work you will have to read the rest. Don't be surprised if it takes -quite a bit of work and experimenting to make Vim use all the multi-byte +quite a bit of work and experimenting to make Vim use all the multibyte features. Unfortunately, every system has its own way to deal with multibyte languages and it is quite complicated. @@ -85,12 +85,12 @@ You can also set 'guifont' alone, the Nvim GUI will try to find a matching INPUT -There are several ways to enter multi-byte characters: +There are several ways to enter multibyte characters: - For X11 XIM can be used. See |XIM|. - For MS-Windows IME can be used. See |IME|. - For all systems keymaps can be used. See |mbyte-keymap|. -The options 'iminsert', 'imsearch' and 'imcmdline' can be used to chose +The options 'iminsert', 'imsearch' and 'imcmdline' can be used to choose the different input methods or disable them temporarily. ============================================================================== @@ -103,8 +103,8 @@ in, or just use a certain locale inside Vim. WHAT IS A LOCALE? *locale* -There are many of languages in the world. And there are different cultures -and environments at least as much as the number of languages. A linguistic +There are many languages in the world. And there are different cultures and +environments at least as many as the number of languages. A linguistic environment corresponding to an area is called "locale". This includes information about the used language, the charset, collating order for sorting, date format, currency format and so on. For Vim only the language and charset @@ -198,11 +198,11 @@ encoded with one byte, we call this a single-byte encoding. The most often used one is called "latin1". This limits the number of characters to 256. Some of these are control characters, thus even fewer can be used for text. -When some characters use two or more bytes, we call this a multi-byte +When some characters use two or more bytes, we call this a multibyte encoding. This allows using much more than 256 characters, which is required for most East Asian languages. -Most multi-byte encodings use one byte for the first 127 characters. These +Most multibyte encodings use one byte for the first 127 characters. These are equal to ASCII, which makes it easy to exchange plain-ASCII text, no matter what language is used. Thus you might see the right text even when the encoding was set wrong. @@ -400,7 +400,7 @@ is suitable for complex input, such as CJK. of the two ways: FrontEnd system and BackEnd system. In the FrontEnd system, input events are snatched by the |IM-server| first, then |IM-server| give the application the result of input. On the other hand, the BackEnd - system works reverse order. MS Windows adopt BackEnd system. In X, most of + system works reverse order. MS-Windows adopt BackEnd system. In X, most of |IM-server|s adopt FrontEnd system. The demerit of BackEnd system is the large overhead in communication, but it provides safe synchronization with no restrictions on applications. @@ -512,7 +512,7 @@ input_server_name is your |IM-server| name (check your |IM-server| your_input_style is one of |OverTheSpot|, |OffTheSpot|, |Root|. See also |xim-input-style|. -*international may not necessary if you use X11R6. +*international may not be necessary if you use X11R6. *.inputMethod and *.preeditType are optional if you use X11R6. For example, when you are using kinput2 as |IM-server|, > @@ -921,7 +921,7 @@ not everybody is able to type a composing character. ============================================================================== Overview of options *mbyte-options* -These options are relevant for editing multi-byte files. +These options are relevant for editing multibyte files. 'fileencoding' Encoding of a file. When it's different from "utf-8" conversion is done when reading or writing the file. @@ -941,7 +941,7 @@ These options are relevant for editing multi-byte files. ============================================================================== -Contributions specifically for the multi-byte features by: +Contributions specifically for the multibyte features by: Chi-Deok Hwang <hwang@mizi.co.kr> SungHyun Nam <goweol@gmail.com> K.Nagano <nagano@atese.advantest.co.jp> diff --git a/runtime/doc/message.txt b/runtime/doc/message.txt index 745160da8a..6fbd9ec922 100644 --- a/runtime/doc/message.txt +++ b/runtime/doc/message.txt @@ -17,13 +17,14 @@ 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. + :mes[sages] Show all messages. - :{count}messages Show the {count} most recent messages. + :{count}mes[sages] Show the {count} most recent messages. - :messages clear Clear all messages. + :mes[sages] clear Clear all messages. - :{count}messages clear Clear messages, keeping only the {count} most + :{count}mes[sages] 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 @@ -67,7 +68,7 @@ Or view a list of recent messages with: > See `:messages` above. LIST OF MESSAGES - *E222* *E228* *E232* *E256* *E293* *E298* *E304* *E317* + *E222* *E228* *E232* *E293* *E298* *E304* *E317* *E318* *E356* *E438* *E439* *E440* *E316* *E320* *E322* *E323* *E341* *E473* *E570* *E685* *E292* > Add to read buffer @@ -761,6 +762,9 @@ and the screen is about to be redrawn: -> Press <Enter> or <Space> to redraw the screen and continue, without that key being used otherwise. -> Press ':' or any other Normal mode command character to start that command. + Note that after an external command some special keys, such as the cursor + keys, may not work normally, because the terminal is still set to a state + for executing the external command. -> Press 'k', <Up>, 'u', 'b' or 'g' to scroll back in the messages. This works the same way as at the |more-prompt|. Only works when 'more' is on. -> Pressing 'j', 'f', 'd' or <Down> is ignored when messages scrolled off the diff --git a/runtime/doc/mlang.txt b/runtime/doc/mlang.txt index 5217b2c160..b57d2b592a 100644 --- a/runtime/doc/mlang.txt +++ b/runtime/doc/mlang.txt @@ -7,7 +7,7 @@ Multi-language features *multilang* *multi-lang* This is about using messages and menus in various languages. For editing -multi-byte text see |multibyte|. +multibyte text see |multibyte|. The basics are explained in the user manual: |usr_45.txt|. diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt index a6c072e489..9f8acff88a 100644 --- a/runtime/doc/motion.txt +++ b/runtime/doc/motion.txt @@ -182,11 +182,14 @@ l or *l* *^* ^ To the first non-blank character of the line. - |exclusive| motion. + |exclusive| motion. Any count is ignored. *$* *<End>* *<kEnd>* $ or <End> To the end of the line. When a count is given also go - [count - 1] lines downward. |inclusive| motion. + [count - 1] lines downward, or as far is possible. + |inclusive| motion. If a count of 2 of larger is + given and the cursor is on the last line, that is an + error an the cursor doesn't move. In Visual mode the cursor goes to just after the last character in the line. When 'virtualedit' is active, "$" may move the cursor @@ -478,10 +481,11 @@ a set of section macros, specified by the pairs of characters in the 'sections' option. The default is "SHNHH HUnhsh", which defines a section to start at the nroff macros ".SH", ".NH", ".H", ".HU", ".nh" and ".sh". -The "]" and "[" commands stop at the '{' or '}' in the first column. This is -useful to find the start or end of a function in a C program. Note that the -first character of the command determines the search direction and the -second character the type of brace found. +The "]]" and "[[" commands stop at the '{' in the first column. This is +useful to find the start of a function in a C program. To search for a '}' in +the first column, the end of a C function, use "][" (forward) or "[]" +(backward). Note that the first character of the command determines the +search direction. If your '{' or '}' are not in the first column, and you would like to use "[[" and "]]" anyway, try these mappings: > @@ -944,6 +948,7 @@ These commands are not marks themselves, but jump to a mark: - numbered marks '0 - '9 - last insert position '^ - last change position '. + - last affected text area '[ and '] - the Visual area '< and '> - line numbers in placed signs - line numbers in quickfix positions @@ -1024,11 +1029,11 @@ The maximum number of entries is fixed at 100. For example, after three jump commands you have this jump list: - jump line col file/text ~ - 3 1 0 some text ~ - 2 70 0 another line ~ - 1 1154 23 end. ~ - > ~ + jump line col file/text ~ + 3 1 0 some text ~ + 2 70 0 another line ~ + 1 1154 23 end. ~ + > ~ The "file/text" column shows the file name, or the text at the jump if it is in the current file (an indent is removed and a long line is truncated to fit @@ -1037,11 +1042,11 @@ in the window). You are currently in line 1167. If you then use the CTRL-O command, the cursor is put in line 1154. This results in: - jump line col file/text ~ - 2 1 0 some text ~ - 1 70 0 another line ~ - > 0 1154 23 end. ~ - 1 1167 0 foo bar ~ + jump line col file/text ~ + 2 1 0 some text ~ + 1 70 0 another line ~ + > 0 1154 23 end. ~ + 1 1167 0 foo bar ~ The pointer will be set at the last used jump position. The next CTRL-O command will use the entry above it, the next CTRL-I command will use the @@ -1068,12 +1073,12 @@ that calling setpos() does not do this. After the CTRL-O command that got you into line 1154 you could give another jump command (e.g., "G"). The jump list would then become: - jump line col file/text ~ - 4 1 0 some text ~ - 3 70 0 another line ~ - 2 1167 0 foo bar ~ - 1 1154 23 end. ~ - > ~ + jump line col file/text ~ + 4 1 0 some text ~ + 3 70 0 another line ~ + 2 1167 0 foo bar ~ + 1 1154 23 end. ~ + > ~ The line numbers will be adjusted for deleted and inserted lines. This fails if you stop editing a file without writing, like with ":n!". @@ -1168,13 +1173,13 @@ sequence of small changes in a line, for example "xxxxx", adds many positions to the change list. When 'textwidth' is zero 'wrapmargin' is used. When that also isn't set a fixed number of 79 is used. Detail: For the computations bytes are used, not characters, to avoid a speed penalty (this only matters -for multi-byte encodings). +for multibyte encodings). Note that when text has been inserted or deleted the cursor position might be a bit different from the position of the change. Especially when lines have been deleted. -When the |:keepjumps| command modifier is used the position of a change is not +When the `:keepjumps` command modifier is used the position of a change is not remembered. *:changes* @@ -1215,7 +1220,7 @@ remembered. #if, #ifdef, #else, #elif, #endif C preprocessor conditionals (when the cursor is on the # or no ([{ - following) + is following) For other items the matchit plugin can be used, see |matchit|. This plugin also helps to skip matches in comments. @@ -1244,19 +1249,19 @@ remembered. #if/#else/#endif makes the movement linewise. *[(* -[( go to [count] previous unmatched '('. +[( Go to [count] previous unmatched '('. |exclusive| motion. *[{* -[{ go to [count] previous unmatched '{'. +[{ Go to [count] previous unmatched '{'. |exclusive| motion. *])* -]) go to [count] next unmatched ')'. +]) Go to [count] next unmatched ')'. |exclusive| motion. *]}* -]} go to [count] next unmatched '}'. +]} Go to [count] next unmatched '}'. |exclusive| motion. The above four commands can be used to go to the start or end of the current @@ -1304,17 +1309,21 @@ file looks like this: > body_two(); } } + +[To try this out copy the text and put it in a new buffer, the help text above +confuses the jump commands] + Starting with the cursor on "body_two()", using "[m" will jump to the '{' at the start of "method_two()" (obviously this is much more useful when the method is long!). Using "2[m" will jump to the start of "method_one()". Using "3[m" will jump to the start of the class. *[#* -[# go to [count] previous unmatched "#if" or "#else". +[# Go to [count] previous unmatched "#if" or "#else". |exclusive| motion. *]#* -]# go to [count] next unmatched "#else" or "#endif". +]# Go to [count] next unmatched "#else" or "#endif". |exclusive| motion. These two commands work in C programs that contain #if/#else/#endif @@ -1322,11 +1331,11 @@ constructs. It brings you to the start or end of the #if/#else/#endif where the current line is included. You can then use "%" to go to the matching line. *[star* *[/* -[* or [/ go to [count] previous start of a C comment "/*". +[* or [/ Go to [count] previous start of a C comment "/*". |exclusive| motion. *]star* *]/* -]* or ]/ go to [count] next end of a C comment "*/". +]* or ]/ Go to [count] next end of a C comment "*/". |exclusive| motion. diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 63a9db9d0d..269080e750 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -144,11 +144,11 @@ the option value, use '\"' instead. This example sets the 'titlestring' option to 'hi "there"': > :set titlestring=hi\ \"there\" -For Windows backslashes in file names are mostly not removed. More -precise: For options that expect a file name (those where environment -variables are expanded) a backslash before a normal file name character is not -removed. But a backslash before a special character (space, backslash, comma, -etc.) is used like explained above. +For Win32 backslashes in file names are mostly not removed. More precise: For +options that expect a file name (those where environment variables are +expanded) a backslash before a normal file name character is not removed. But +a backslash before a special character (space, backslash, comma, etc.) is used +like explained above. There is one special situation, when the value starts with "\\": > :set dir=\\machine\path results in "\\machine\path" :set dir=\\\\machine\\path results in "\\machine\path" @@ -394,10 +394,11 @@ to set options automatically for one or more files: *modeline* *vim:* *vi:* *ex:* *E520* There are two forms of modelines. The first form: - [text]{white}{vi:|vim:|ex:}[white]{options} + [text{white}]{vi:|vim:|ex:}[white]{options} -[text] any text or empty -{white} at least one blank character (<Space> or <Tab>) +[text{white}] empty or any text followed by at least one blank + character (<Space> or <Tab>); "ex:" always requires at + least one blank character {vi:|vim:|ex:} the string "vi:", "vim:" or "ex:" [white] optional white space {options} a list of option settings, separated with white space @@ -410,10 +411,11 @@ Examples: The second form (this is compatible with some versions of Vi): - [text]{white}{vi:|vim:|Vim:|ex:}[white]se[t] {options}:[text] + [text{white}]{vi:|vim:|Vim:|ex:}[white]se[t] {options}:[text] -[text] any text or empty -{white} at least one blank character (<Space> or <Tab>) +[text{white}] empty or any text followed by at least one blank + character (<Space> or <Tab>); "ex:" always requires at + least one blank character {vi:|vim:|Vim:|ex:} the string "vi:", "vim:", "Vim:" or "ex:" [white] optional white space se[t] the string "set " or "se " (note the space); When @@ -474,9 +476,9 @@ If an error is detected the rest of the line is skipped. If you want to include a ':' in a set command precede it with a '\'. The backslash in front of the ':' will be removed. Example: - /* vi:set dir=c\:\tmp: */ ~ -This sets the 'dir' option to "c:\tmp". Only a single backslash before the -':' is removed. Thus to include "\:" you have to specify "\\:". + /* vi:set fillchars=stl\:^,vert\:\|: */ ~ +This sets the 'fillchars' option to "stl:^,vert:\|". Only a single backslash +before the ':' is removed. Thus to include "\:" you have to specify "\\:". *E992* No other commands than "set" are supported, for security reasons (somebody might create a Trojan horse text file with modelines). And not all options @@ -589,9 +591,9 @@ A jump table for the options with a short description can be found at |Q_op|. (or Vim is run inside an xterm invoked with "-cjkwidth" option.), this option should be set to "double" to match the width perceived by Vim with the width of glyphs in the font. Perhaps it also has - to be set to "double" under CJK Windows XP when the system locale is - set to one of CJK locales. - See Unicode Standard Annex #11 (http://www.unicode.org/reports/tr11). + to be set to "double" under CJK MS-Windows when the system locale is + set to one of CJK locales. See Unicode Standard Annex #11 + (http://www.unicode.org/reports/tr11). Vim may set this option automatically at startup time when Vim is compiled with the |+termresponse| feature and if t_u7 is set to the @@ -836,9 +838,9 @@ A jump table for the options with a short description can be found at |Q_op|. impossible!). Writing may fail because of this. - A directory "." means to put the backup file in the same directory as the edited file. - - A directory starting with "./" (or ".\" for Windows) means to - put the backup file relative to where the edited file is. The - leading "." is replaced with the path name of the edited file. + - A directory starting with "./" (or ".\" for MS-Windows) means to put + the backup file relative to where the edited file is. The leading + "." is replaced with the path name of the edited file. ("." inside a directory name has no special meaning). - Spaces after the comma are ignored, other spaces are considered part of the directory name. To have a space at the start of a directory @@ -944,7 +946,7 @@ A jump table for the options with a short description can be found at |Q_op|. (mostly used in |Normal-mode| or |Cmdline-mode|). esc hitting <Esc> in |Normal-mode|. ex In |Visual-mode|, hitting |Q| results in an error. - hangul Error occurred when using hangul input. + hangul Ignored. insertmode Pressing <Esc> in 'insertmode'. lang Calling the beep module for Lua/Mzscheme/TCL. mess No output available for |g<|. @@ -1100,6 +1102,7 @@ A jump table for the options with a short description can be found at |Q_op|. This option is used together with 'bufhidden' and 'swapfile' to specify special kinds of buffers. See |special-buffers|. + Also see |win_gettype()|, which returns the type of the window. Be careful with changing this option, it can have many side effects! @@ -1392,7 +1395,7 @@ A jump table for the options with a short description can be found at |Q_op|. *'completeslash'* *'csl'* 'completeslash' 'csl' string (default: "") local to buffer - {not in Vi} {only for MS-Windows} + {only for MS-Windows} When this option is set it overrules 'shellslash' for completion: - When this option is set to "slash", a forward slash is used for path completion in insert mode. This is useful when editing HTML tag, or @@ -1855,7 +1858,7 @@ A jump table for the options with a short description can be found at |Q_op|. "x" delete each combining character on its own. When it is off (the default) the character along with its combining characters are deleted. - Note: When 'delcombine' is set "xx" may work different from "2x"! + Note: When 'delcombine' is set "xx" may work differently from "2x"! This is useful for Arabic, Hebrew and many other languages where one may have combining characters overtop of base characters, and want @@ -2009,6 +2012,8 @@ A jump table for the options with a short description can be found at |Q_op|. 'directory' 'dir' string (default "$XDG_DATA_HOME/nvim/swap//") global List of directory names for the swap file, separated with commas. + + Possible items: - The swap file will be created in the first directory where this is possible. If it is not possible in any directory, but last directory listed in the option does not exist, it is created. @@ -2018,13 +2023,14 @@ A jump table for the options with a short description can be found at |Q_op|. the edited file. On Unix, a dot is prepended to the file name, so it doesn't show in a directory listing. On MS-Windows the "hidden" attribute is set and a dot prepended if possible. - - A directory starting with "./" (or ".\" for Windows) means to - put the swap file relative to where the edited file is. The leading - "." is replaced with the path name of the edited file. + - A directory starting with "./" (or ".\" for MS-Windows) means to put + the swap file relative to where the edited file is. The leading "." + is replaced with the path name of the edited file. - For Unix and Win32, if a directory ends in two path separators "//", the swap file name will be built from the complete path to the file - with all path separators substituted to percent '%' signs. This will - ensure file name uniqueness in the preserve directory. + with all path separators replaced by percent '%' signs (including + the colon following the drive letter on Win32). This will ensure + file name uniqueness in the preserve directory. On Win32, it is also possible to end with "\\". However, When a separating comma is following, you must use "//", since "\\" will include the comma in the file name. Therefore it is recommended to @@ -2044,9 +2050,10 @@ A jump table for the options with a short description can be found at |Q_op|. the same file twice will result in a warning. Using "/tmp" on Unix is discouraged: When the system crashes you lose the swap file. "/var/tmp" is often not cleared when rebooting, thus is a better - choice than "/tmp". But it can contain a lot of files, your swap - files get lost in the crowd. That is why a "tmp" directory in your - home directory is tried first. + choice than "/tmp". But others on the computer may be able to see the + files, and it can contain a lot of files, your swap files get lost in + the crowd. That is why a "tmp" directory in your home directory is + tried first. The use of |:set+=| and |:set-=| is preferred when adding or removing directories from the list. This avoids problems when a future version uses another default. @@ -2086,7 +2093,9 @@ A jump table for the options with a short description can be found at |Q_op|. 'emoji' 'emo' boolean (default: on) global When on all Unicode emoji characters are considered to be full width. - + This excludes "text emoji" characters, which are normally displayed as + single width. Unfortunately there is no good specification for this + and it has been determined on trial-and-error basis. *'encoding'* *'enc'* *E543* 'encoding' 'enc' @@ -2283,7 +2292,7 @@ A jump table for the options with a short description can be found at |Q_op|. local to buffer This gives the <EOL> of the current buffer, which is used for reading/writing the buffer from/to a file: - dos <CR> <NL> + dos <CR><NL> unix <NL> mac <CR> When "dos" is used, CTRL-Z at the end of a file is ignored. @@ -2970,7 +2979,7 @@ A jump table for the options with a short description can be found at |Q_op|. *'go-v'* 'v' Use a vertical button layout for dialogs. When not included, a horizontal layout is preferred, but when it doesn't fit a - vertical layout is used anyway. + vertical layout is used anyway. Not supported in GTK 3. *'go-p'* 'p' Use Pointer callbacks for X11 GUI. This is required for some window managers. If the cursor is not blinking or hollow at @@ -3013,7 +3022,7 @@ A jump table for the options with a short description can be found at |Q_op|. < *'helpfile'* *'hf'* -'helpfile' 'hf' string (default (MSDOS) "$VIMRUNTIME\doc\help.txt" +'helpfile' 'hf' string (default (MS-Windows) "$VIMRUNTIME\doc\help.txt" (others) "$VIMRUNTIME/doc/help.txt") global Name of the main help file. All distributed help files should be @@ -3420,7 +3429,8 @@ A jump table for the options with a short description can be found at |Q_op|. Keywords are used in searching and recognizing with many commands: "w", "*", "[i", etc. It is also used for "\k" in a |pattern|. See 'isfname' for a description of the format of this option. For '@' - characters above 255 check the "word" character class. + characters above 255 check the "word" character class (any character + that is not white space or punctuation). For C programs you could use "a-z,A-Z,48-57,_,.,-,>". For a help file it is set to all non-blank printable characters except '*', '"' and '|' (so that CTRL-] on a command finds the help for that @@ -3527,8 +3537,8 @@ A jump table for the options with a short description can be found at |Q_op|. be able to execute Normal mode commands. This is the opposite of the 'keymap' option, where characters are mapped in Insert mode. - Also consider resetting 'langremap' to avoid 'langmap' applies to - characters resulting from a mapping. + Also consider setting 'langremap' to off, to prevent 'langmap' from + applying to characters resulting from a mapping. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. @@ -3545,7 +3555,7 @@ A jump table for the options with a short description can be found at |Q_op|. characters. Example: "abc;ABC" Example: "aA,fgh;FGH,cCdDeE" Special characters need to be preceded with a backslash. These are - ";", ',' and backslash itself. + ";", ',', '"', '|' and backslash itself. This will allow you to activate vim actions without having to switch back and forth between the languages. Your language characters will @@ -3719,8 +3729,10 @@ A jump table for the options with a short description can be found at |Q_op|. *lcs-lead* lead:c Character to show for leading spaces. When omitted, leading spaces are blank. Overrides the "space" - setting for leading spaces. - *lcs-trail* + setting for leading spaces. You can combine it with + "tab:", for example: > + :set listchars+=tab:>-,lead:. +< *lcs-trail* trail:c Character to show for trailing spaces. When omitted, trailing spaces are blank. Overrides the "space" setting for trailing spaces. @@ -3769,6 +3781,8 @@ A jump table for the options with a short description can be found at |Q_op|. Only switch it off when working with old Vi scripts. In any other situation write patterns that work when 'magic' is on. Include "\M" when you want to |/\M|. + In |Vim9| script the value of 'magic' is ignored, patterns behave like + it is always set. *'makeef'* *'mef'* 'makeef' 'mef' string (default: "") @@ -3827,7 +3841,7 @@ A jump table for the options with a short description can be found at |Q_op|. jump between two double quotes. The characters must be separated by a colon. The pairs must be separated by a comma. Example for including '<' and - '>' (HTML): > + '>' (for HTML): > :set mps+=<:> < A more exotic example, to jump between the '=' and ';' in an @@ -3994,7 +4008,7 @@ A jump table for the options with a short description can be found at |Q_op|. the |more-prompt|. When this option is off there are no pauses, the listing continues until finished. - *'mouse'* *E538* + *'mouse'* 'mouse' string (default "") global @@ -4205,6 +4219,15 @@ A jump table for the options with a short description can be found at |Q_op|. bin If included, numbers starting with "0b" or "0B" will be considered to be binary. Example: Using CTRL-X on "0b1000" subtracts one, resulting in "0b0111". + unsigned If included, numbers are recognized as unsigned. Thus a + leading dash or negative sign won't be considered as part of + the number. Examples: + Using CTRL-X on "2020" in "9-2020" results in "9-2019" + (without "unsigned" it would become "9-2021"). + Using CTRL-A on "2020" in "9-2020" results in "9-2021" + (without "unsigned" it would become "9-2019"). + Using CTRL-X on "0" or CTRL-A on "18446744073709551615" + (2^64 - 1) has no effect, overflow is prevented. Numbers which simply begin with a digit in the range 1-9 are always considered decimal. This also happens for numbers that are not recognized as octal or hex. @@ -4747,7 +4770,7 @@ A jump table for the options with a short description can be found at |Q_op|. screen. If the statusline is given by 'statusline' (i.e. not empty), this option takes precedence over 'ruler' and 'rulerformat' If the number of characters displayed is different from the number of - bytes in the text (e.g., for a TAB or a multi-byte character), both + bytes in the text (e.g., for a TAB or a multibyte character), both the text column (byte number) and the screen column are shown, separated with a dash. For an empty line "0-1" is shown. @@ -5166,8 +5189,7 @@ A jump table for the options with a short description can be found at |Q_op|. security reasons. *'shell'* *'sh'* *E91* -'shell' 'sh' string (default $SHELL or "sh", - Windows: "cmd.exe") +'shell' 'sh' string (default $SHELL or "sh", Win32: "cmd.exe") global Name of the shell to use for ! and :! commands. When changing the value also check these options: 'shellpipe', 'shellslash' @@ -5176,8 +5198,8 @@ A jump table for the options with a short description can be found at |Q_op|. See |option-backslash| about including spaces and backslashes. Environment variables are expanded |:set_env|. - If the name of the shell contains a space, you might need to enclose - it in quotes. Example: > + If the name of the shell contains a space, you need to enclose it in + quotes. Example with quotes: > :set shell=\"c:\program\ files\unix\sh.exe\"\ -f < Note the backslash before each quote (to avoid starting a comment) and each space (to avoid ending the option value), so better use |:let-&| @@ -5218,9 +5240,9 @@ A jump table for the options with a short description can be found at |Q_op|. 'shellcmdflag' 'shcf' string (default: "-c"; Windows: "/s /c") global Flag passed to the shell to execute "!" and ":!" commands; e.g., - `bash.exe -c ls` or `cmd.exe /s /c "dir"`. For Windows - systems, the default is set according to the value of 'shell', to - reduce the need to set this option by the user. + `bash.exe -c ls` or `cmd.exe /s /c "dir"`. For MS-Windows, the + default is set according to the value of 'shell', to reduce the need + to set this option by the user. On Unix it can have more than one flag. Each white space separated part is passed as an argument to the shell command. See |option-backslash| about including spaces and backslashes. @@ -5230,7 +5252,8 @@ A jump table for the options with a short description can be found at |Q_op|. security reasons. *'shellpipe'* *'sp'* -'shellpipe' 'sp' string (default ">", "| tee", "|& tee" or "2>&1| tee") +'shellpipe' 'sp' string (default ">", ">%s 2>&1", "| tee", "|& tee" or + "2>&1| tee") global String to be used to put the output of the ":make" command in the error file. See also |:make_makeprg|. See |option-backslash| about @@ -5238,15 +5261,15 @@ A jump table for the options with a short description can be found at |Q_op|. The name of the temporary file can be represented by "%s" if necessary (the file name is appended automatically if no %s appears in the value of this option). - For Windows the default is ">". The output is directly saved in a file - and not echoed to the screen. - For Unix the default it "| tee". The stdout of the compiler is saved + For MS-Windows the default is ">%s 2>&1". The output is directly + saved in a file and not echoed to the screen. + For Unix the default is "| tee". The stdout of the compiler is saved in a file and echoed to the screen. If the 'shell' option is "csh" or "tcsh" after initializations, the default becomes "|& tee". If the - 'shell' option is "sh", "ksh", "mksh", "pdksh", "zsh" or "bash" the - default becomes "2>&1| tee". This means that stderr is also included. - Before using the 'shell' option a path is removed, thus "/bin/sh" uses - "sh". + 'shell' option is "sh", "ksh", "mksh", "pdksh", "zsh", "zsh-beta", + "bash" or "fish" the default becomes "2>&1| tee". This means that + stderr is also included. Before using the 'shell' option a path is + removed, thus "/bin/sh" uses "sh". The initialization of this option is done after reading the vimrc and the other initializations, so that when the 'shell' option is set there, the 'shellpipe' option changes automatically, unless it was @@ -5286,13 +5309,13 @@ A jump table for the options with a short description can be found at |Q_op|. The name of the temporary file can be represented by "%s" if necessary (the file name is appended automatically if no %s appears in the value of this option). - The default is ">". For Unix, if the 'shell' option is "csh", "tcsh" - or "zsh" during initializations, the default becomes ">&". If the - 'shell' option is "sh", "ksh" or "bash" the default becomes - ">%s 2>&1". This means that stderr is also included. - For Win32, the Unix checks are done and additionally "cmd" is checked - for, which makes the default ">%s 2>&1". Also, the same names with - ".exe" appended are checked for. + The default is ">". For Unix, if the 'shell' option is "csh" or + "tcsh" during initializations, the default becomes ">&". If the + 'shell' option is "sh", "ksh", "mksh", "pdksh", "zsh", "zsh-beta", + "bash" or "fish", the default becomes ">%s 2>&1". This means that + stderr is also included. For Win32, the Unix checks are done and + additionally "cmd" is checked for, which makes the default ">%s 2>&1". + Also, the same names with ".exe" appended are checked for. The initialization of this option is done after reading the vimrc and the other initializations, so that when the 'shell' option is set there, the 'shellredir' option changes automatically unless it was @@ -5305,11 +5328,11 @@ A jump table for the options with a short description can be found at |Q_op|. *'shellslash'* *'ssl'* *'noshellslash'* *'nossl'* 'shellslash' 'ssl' boolean (default off) global - {only for Windows} + {only for MS-Windows} When set, a forward slash is used when expanding file names. This is - useful when a Unix-like shell is used instead of command.com or - cmd.exe. Backward slashes can still be typed, but they are changed to - forward slashes by Vim. + useful when a Unix-like shell is used instead of cmd.exe. Backward + slashes can still be typed, but they are changed to forward slashes by + Vim. Note that setting or resetting this option has no effect for some existing file names, thus this option needs to be set before opening any file for best results. This might change in the future. @@ -5887,8 +5910,8 @@ A jump table for the options with a short description can be found at |Q_op|. N N Printer page number. (Only works in the 'printheader' option.) l N Line number. L N Number of lines in buffer. - c N Column number. - v N Virtual column number. + c N Column number (byte index). + v N Virtual column number (screen column). V N Virtual column number as -{num}. Not displayed if equal to 'c'. p N Percentage through file in lines as in |CTRL-G|. P S Percentage through file of displayed window. This is like the @@ -5897,7 +5920,9 @@ A jump table for the options with a short description can be found at |Q_op|. a S Argument list status as in default title. ({current} of {max}) Empty if the argument file count is zero or one. { NF Evaluate expression between '%{' and '}' and substitute result. - Note that there is no '%' before the closing '}'. + Note that there is no '%' before the closing '}'. The + expression cannot contain a '}' character, call a function to + work around that. See |stl-%{| below. ( - Start of item group. Can be used for setting the width and alignment of a section. Must be followed by %) somewhere. ) - End of item group. No width fields allowed. @@ -5960,13 +5985,13 @@ A jump table for the options with a short description can be found at |Q_op|. :set statusline=...%(\ [%M%R%H]%)... < Beware that an expression is evaluated each and every time the status line is displayed. - *g:actual_curbuf* *g:actual_curwin* - The current buffer and current window will be set temporarily to that - of the window (and buffer) whose statusline is currently being drawn. - The expression will evaluate in this context. The variable - "g:actual_curbuf" is set to the `bufnr()` number of the real current - buffer and "g:actual_curwin" to the |window-ID| of the real current - window. These values are strings. + *stl-%{* *g:actual_curbuf* *g:actual_curwin* + While evaluating %{} the current buffer and current window will be set + temporarily to that of the window (and buffer) whose statusline is + currently being drawn. The expression will evaluate in this context. + The variable "g:actual_curbuf" is set to the `bufnr()` number of the + real current buffer and "g:actual_curwin" to the |window-ID| of the + real current window. These values are strings. The 'statusline' option will be evaluated in the |sandbox| if set from a modeline, see |sandbox-option|. @@ -6504,8 +6529,8 @@ A jump table for the options with a short description can be found at |Q_op|. 'undolevels' 'ul' number (default 1000) global or local to buffer |global-local| Maximum number of changes that can be undone. Since undo information - is kept in memory, higher numbers will cause more memory to be used - (nevertheless, a single change can use an unlimited amount of memory). + is kept in memory, higher numbers will cause more memory to be used. + Nevertheless, a single change can already use a large amount of memory. Set to 0 for Vi compatibility: One level of undo and "u" undoes itself: > set ul=0 @@ -6608,7 +6633,7 @@ A jump table for the options with a short description can be found at |Q_op|. >= 14 Anything pending in a ":finally" clause. >= 15 Every executed Ex command from a script (truncated at 200 characters). - >= 16 Every executed Ex command + >= 16 Every executed Ex command. This option can also be set with the "-V" argument. See |-V|. This option is also set by the |:verbose| command. @@ -6713,8 +6738,8 @@ A jump table for the options with a short description can be found at |Q_op|. ":map <BS> X" to make backspace delete the character in front of the cursor. When 'l' is included and it is used after an operator at the end of a - line then it will not move to the next line. This makes "dl", "cl", - "yl" etc. work normally. + line (not an empty line) then it will not move to the next line. This + makes "dl", "cl", "yl" etc. work normally. *'wildchar'* *'wc'* 'wildchar' 'wc' number (Vim default: <Tab>, Vi default: CTRL-E) @@ -6808,23 +6833,31 @@ A jump table for the options with a short description can be found at |Q_op|. part specifies what to do for each consecutive use of 'wildchar'. The first part specifies the behavior for the first use of 'wildchar', The second part for the second use, etc. - These are the possible values for each part: + + Each part consists of a colon separated list consisting of the + following possible values: "" Complete only the first match. "full" Complete the next full match. After the last match, the original string is used and then the first match - again. + again. Will also start 'wildmenu' if it is enabled. "longest" Complete till longest common string. If this doesn't result in a longer string, use the next part. - "longest:full" Like "longest", but also start 'wildmenu' if it is - enabled. "list" When more than one match, list all matches. + "lastused" When completing buffer names and more than one buffer + matches, sort buffers by time last used (other than + the current buffer). + When there is only a single match, it is fully completed in all cases. + + Examples of useful colon-separated values: + "longest:full" Like "longest", but also start 'wildmenu' if it is + enabled. Will not complete to the next full match. "list:full" When more than one match, list all matches and complete first match. "list:longest" When more than one match, list all matches and complete till longest common string. - "list:lastused" When more than one buffer matches, sort buffers - by time last used (other than the current buffer). - When there is only a single match, it is fully completed in all cases. + "list:lastused" When more than one buffer matches, list all matches + and sort buffers by time last used (other than the + current buffer). Examples: > :set wildmode=full @@ -6882,15 +6915,15 @@ A jump table for the options with a short description can be found at |Q_op|. *'window'* *'wi'* 'window' 'wi' number (default screen height - 1) global - Window height. Do not confuse this with the height of the Vim window, - use 'lines' for that. - Used for |CTRL-F| and |CTRL-B| when there is only one window and the - value is smaller than 'lines' minus one. The screen will scroll - 'window' minus two lines, with a minimum of one. + Window height used for |CTRL-F| and |CTRL-B| when there is only one + window and the value is smaller than 'lines' minus one. The screen + will scroll 'window' minus two lines, with a minimum of one. When 'window' is equal to 'lines' minus one CTRL-F and CTRL-B scroll in a much smarter way, taking care of wrapping lines. When resizing the Vim window, the value is smaller than 1 or more than or equal to 'lines' it will be set to 'lines' minus 1. + Note: Do not confuse this with the height of the Vim window, use + 'lines' for that. *'winheight'* *'wh'* *E591* 'winheight' 'wh' number (default 1) @@ -7049,6 +7082,8 @@ A jump table for the options with a short description can be found at |Q_op|. fail (and make sure not to exit Vim until the write was successful). See |backup-table| for another explanation. When the 'backupskip' pattern matches, a backup is not made anyway. + Depending on 'backupcopy' the backup is a new file or the original + file renamed (and a new file is written). *'writedelay'* *'wd'* 'writedelay' 'wd' number (default 0) diff --git a/runtime/doc/pattern.txt b/runtime/doc/pattern.txt index 7129c6cd58..e74f3b72bf 100644 --- a/runtime/doc/pattern.txt +++ b/runtime/doc/pattern.txt @@ -219,7 +219,7 @@ This is like executing two search commands after each other, except that: *last-pattern* The last used pattern and offset are remembered. They can be used to repeat the search, possibly in another direction or with another count. Note that -two patterns are remembered: One for 'normal' search commands and one for the +two patterns are remembered: One for "normal" search commands and one for the substitute command ":s". Each time an empty pattern is given, the previously used pattern is used. However, if there is no previous search command, a previous substitute pattern is used, if possible. @@ -351,8 +351,8 @@ For starters, read chapter 27 of the user manual |usr_27.txt|. */atom* 5. An atom can be one of a long list of items. Many atoms match one character in the text. It is often an ordinary character or a character class. - Braces can be used to make a pattern into an atom. The "\z(\)" construct - is only for syntax highlighting. + Parentheses can be used to make a pattern into an atom. The "\z(\)" + construct is only for syntax highlighting. atom ::= ordinary-atom |/ordinary-atom| or \( pattern \) |/\(| @@ -384,15 +384,19 @@ the pattern will not match. This is only useful when debugging Vim. ============================================================================== 3. Magic */magic* -Some characters in the pattern are taken literally. They match with the same -character in the text. When preceded with a backslash however, these -characters get a special meaning. +Some characters in the pattern, such as letters, are taken literally. They +match exactly the same character in the text. When preceded with a backslash +however, these characters may get a special meaning. For example, "a" matches +the letter "a", while "\a" matches any alphabetic character. Other characters have a special meaning without a backslash. They need to be -preceded with a backslash to match literally. +preceded with a backslash to match literally. For example "." matches any +character while "\." matches a dot. If a character is taken literally or not depends on the 'magic' option and the -items mentioned next. +items in the pattern mentioned next. The 'magic' option should always be set, +but it can be switched off for Vi compatibility. We mention the effect of +'nomagic' here for completeness, but we recommend against using that. */\m* */\M* Use of "\m" makes the pattern after it be interpreted as if 'magic' is set, ignoring the actual value of the 'magic' option. @@ -401,30 +405,28 @@ Use of "\M" makes the pattern after it be interpreted as if 'nomagic' is used. Use of "\v" means that after it, all ASCII characters except '0'-'9', 'a'-'z', 'A'-'Z' and '_' have special meaning: "very magic" -Use of "\V" means that after it, only a backslash and terminating character -(usually / or ?) have special meaning: "very nomagic" +Use of "\V" means that after it, only a backslash and the terminating +character (usually / or ?) have special meaning: "very nomagic" Examples: after: \v \m \M \V matches ~ 'magic' 'nomagic' - $ $ $ \$ matches end-of-line - . . \. \. matches any character + a a a a literal 'a' + \a \a \a \a any alphabetic character + . . \. \. any character + \. \. . . literal dot + $ $ $ \$ end-of-line * * \* \* any number of the previous atom ~ ~ \~ \~ latest substitute string - () \(\) \(\) \(\) grouping into an atom - | \| \| \| separating alternatives - \a \a \a \a alphabetic character + () \(\) \(\) \(\) group as an atom + | \| \| \| nothing: separates alternatives \\ \\ \\ \\ literal backslash - \. \. . . literal dot - \{ { { { literal '{' - a a a a literal 'a' + \{ { { { literal curly brace {only Vim supports \m, \M, \v and \V} -It is recommended to always keep the 'magic' option at the default setting, -which is 'magic'. This avoids portability problems. To make a pattern immune -to the 'magic' option being set or not, put "\m" or "\M" at the start of the -pattern. +If you want to you can make a pattern immune to the 'magic' option being set +or not by putting "\m" or "\M" at the start of the pattern. ============================================================================== 4. Overview of pattern items *pattern-overview* @@ -666,7 +668,7 @@ overview. Note that using "\&" works the same as using "\@=": "foo\&.." is the same as "\(foo\)\@=..". But using "\&" is easier, you don't need the - braces. + parentheses. */\@!* @@ -787,11 +789,12 @@ An ordinary atom can be: ^beep( the start of the C function "beep" (probably). */\^* -\^ Matches literal '^'. Can be used at any position in the pattern. +\^ Matches literal '^'. Can be used at any position in the pattern, but + not inside []. */\_^* \_^ Matches start-of-line. |/zero-width| Can be used at any position in - the pattern. + the pattern, but not inside []. Example matches ~ \_s*\_^foo white space and blank lines and then "foo" at start-of-line @@ -802,12 +805,13 @@ $ At end of pattern or in front of "\|", "\)" or "\n" ('magic' on): |/zero-width| */\$* -\$ Matches literal '$'. Can be used at any position in the pattern. +\$ Matches literal '$'. Can be used at any position in the pattern, but + not inside []. */\_$* \_$ Matches end-of-line. |/zero-width| Can be used at any position in the - pattern. Note that "a\_$b" never matches, since "b" cannot match an - end-of-line. Use "a\nb" instead |/\n|. + pattern, but not inside []. Note that "a\_$b" never matches, since + "b" cannot match an end-of-line. Use "a\nb" instead |/\n|. Example matches ~ foo\_$\_s* "foo" at end-of-line and following white space and blank lines @@ -830,8 +834,9 @@ $ At end of pattern or in front of "\|", "\)" or "\n" ('magic' on): |/zero-width| */\zs* -\zs Matches at any position, and sets the start of the match there: The - next char is the first char of the whole match. |/zero-width| +\zs Matches at any position, but not inside [], and sets the start of the + match there: The next char is the first char of the whole match. + |/zero-width| Example: > /^\s*\zsif < matches an "if" at the start of a line, ignoring white space. @@ -842,8 +847,9 @@ $ At end of pattern or in front of "\|", "\)" or "\n" ('magic' on): This cannot be followed by a multi. *E888* */\ze* -\ze Matches at any position, and sets the end of the match there: The - previous char is the last char of the whole match. |/zero-width| +\ze Matches at any position, but not inside [], and sets the end of the + match there: The previous char is the last char of the whole match. + |/zero-width| Can be used multiple times, the last one encountered in a matching branch is used. Example: "end\ze\(if\|for\)" matches the "end" in "endif" and @@ -928,7 +934,7 @@ $ At end of pattern or in front of "\|", "\)" or "\n" ('magic' on): These three can be used to match specific columns in a buffer or string. The "23" can be any column number. The first column is 1. Actually, the column is the byte number (thus it's not exactly right - for multi-byte characters). + for multibyte characters). WARNING: When inserting or deleting text Vim does not automatically update the matches. This means Syntax highlighting quickly becomes wrong. @@ -983,7 +989,7 @@ Character classes: \p printable character (see 'isprint' option) */\p* \P like "\p", but excluding digits */\P* -NOTE: the above also work for multi-byte characters. The ones below only +NOTE: the above also work for multibyte characters. The ones below only match ASCII characters, as indicated by the range. *whitespace* *white-space* @@ -1054,8 +1060,8 @@ x A single character, with no special meaning, matches itself [] (with 'nomagic': \[]) */[]* */\[]* */\_[]* */collection* \_[] - A collection. This is a sequence of characters enclosed in brackets. - It matches any single character in the collection. + A collection. This is a sequence of characters enclosed in square + brackets. It matches any single character in the collection. Example matches ~ [xyz] any 'x', 'y' or 'z' [a-zA-Z]$ any alphabetic character at the end of a line @@ -1114,15 +1120,16 @@ x A single character, with no special meaning, matches itself *[:ident:]* [:ident:] identifier character (same as "\i") *[:keyword:]* [:keyword:] keyword character (same as "\k") *[:fname:]* [:fname:] file name character (same as "\f") - The brackets in character class expressions are additional to the - brackets delimiting a collection. For example, the following is a - plausible pattern for a Unix filename: "[-./[:alnum:]_~]\+" That is, - a list of at least one character, each of which is either '-', '.', - '/', alphabetic, numeric, '_' or '~'. + The square brackets in character class expressions are additional to + the square brackets delimiting a collection. For example, the + following is a plausible pattern for a UNIX filename: + "[-./[:alnum:]_~]\+". That is, a list of at least one character, + each of which is either '-', '.', '/', 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 + [:upper:] also work for multibyte characters when using the new regexp engine. See |two-engines|. In the future these items may - work for multi-byte characters. For now, to get all "alpha" + work for multibyte characters. For now, to get all "alpha" characters you can use: [[:lower:][:upper:]]. The "Func" column shows what library function is used. The @@ -1161,7 +1168,7 @@ x A single character, with no special meaning, matches itself \b <BS> \n line break, see above |/[\n]| \d123 decimal number of character - \o40 octal number of character up to 0377 + \o40 octal number of character up to 0o377 \x20 hexadecimal number of character up to 0xff \u20AC hex. number of multibyte character up to 0xffff \U1234 hex. number of multibyte character up to 0xffffffff @@ -1198,7 +1205,8 @@ x A single character, with no special meaning, matches itself \%d123 Matches the character specified with a decimal number. Must be followed by a non-digit. \%o40 Matches the character specified with an octal number up to 0377. - Numbers below 040 must be followed by a non-octal digit or a non-digit. + Numbers below 0o40 must be followed by a non-octal digit or a + non-digit. \%x2a Matches the character specified with up to two hexadecimal characters. \%u20AC Matches the character specified with up to four hexadecimal characters. @@ -1245,8 +1253,8 @@ When working with expression evaluation, a <NL> character in the pattern matches a <NL> in the string. The use of "\n" (backslash n) to match a <NL> doesn't work there, it only works to match text in the buffer. - *pattern-multi-byte* -Patterns will also work with multi-byte characters, mostly as you would + *pattern-multi-byte* *pattern-multibyte* +Patterns will also work with multibyte characters, mostly as you would expect. But invalid bytes may cause trouble, a pattern with an invalid byte will probably never match. @@ -1267,7 +1275,7 @@ not match in "càt" (where the a has the composing character 0x0300), but 0xe1, it does not have a compositing character). It does match "cat" (where the a is just an a). -When a composing character appears at the start of the pattern of after an +When a composing character appears at the start of the pattern or after an item that doesn't include the composing character, a match is found at any character that includes this composing character. diff --git a/runtime/doc/pi_netrw.txt b/runtime/doc/pi_netrw.txt index 7312ab721b..5adafd7877 100644 --- a/runtime/doc/pi_netrw.txt +++ b/runtime/doc/pi_netrw.txt @@ -437,9 +437,13 @@ settings are described below, in |netrw-browser-options|, and in *g:netrw_silent* =0 : transfers done normally =1 : transfers done silently - *g:netrw_use_errorwindow* =1 : messages from netrw will use a separate one + *g:netrw_use_errorwindow* =2: messages from netrw will use a popup window + Move the mouse and pause to remove the popup window. + (default value if popup windows are availble) + =1 : messages from netrw will use a separate one line window. This window provides reliable - delivery of messages. (default) + delivery of messages. + (default value if popup windows are not availble) =0 : messages from netrw will use echoerr ; messages don't always seem to show up this way, but one doesn't have to quit the window. @@ -725,6 +729,8 @@ just as easily as if they were local files! > See |netrw-activate| for more on how to encourage your vim to use plugins such as netrw. +For password-free use of scp:, see |netrw-ssh-hack|. + ============================================================================== 7. Ex Commands *netrw-ex* {{{1 @@ -1063,7 +1069,7 @@ QUICK HELP *netrw-quickhelp* {{{2 Reverse sorting order.........................|netrw-r| - *netrw-quickmap* *netrw-quickmaps* + *netrw-quickmap* *netrw-quickmaps* QUICK REFERENCE: MAPS *netrw-browse-maps* {{{2 > --- ----------------- ---- @@ -1080,7 +1086,7 @@ QUICK REFERENCE: MAPS *netrw-browse-maps* {{{2 a Cycles between normal display, |netrw-a| hiding (suppress display of files matching g:netrw_list_hide) and showing (display only files which match g:netrw_list_hide) - c Make browsing directory the current directory |netrw-c| + cd Make browsing directory the current directory |netrw-cd| C Setting the editing window |netrw-C| d Make a directory |netrw-d| D Attempt to remove the file(s)/directory(ies) |netrw-D| @@ -2098,7 +2104,7 @@ the two directories the same, use the "cd" map (type cd). That map will set Vim's notion of the current directory to netrw's current browsing directory. -*netrw-c* : This map's name has been changed from "c" to cd (see |netrw-cd|). +|netrw-cd|: This map's name was changed from "c" to cd (see |netrw-cd|). This change was done to allow for |netrw-cb| and |netrw-cB| maps. Associated setting variable: |g:netrw_keepdir| @@ -2752,7 +2758,7 @@ your browsing preferences. (see also: |netrw-settings|) =0 keep the current directory the same as the browsing directory. The current browsing directory is contained in - b:netrw_curdir (also see |netrw-c|) + b:netrw_curdir (also see |netrw-cd|) *g:netrw_keepj* ="keepj" (default) netrw attempts to keep the |:jumps| table unaffected. @@ -3053,7 +3059,7 @@ your browsing preferences. (see also: |netrw-settings|) (see |netrw-c-tab|). *g:netrw_xstrlen* Controls how netrw computes string lengths, - including multibyte characters' string + including multi-byte characters' string length. (thanks to N Weibull, T Mechelynck) =0: uses Vim's built-in strlen() =1: number of codepoints (Latin a + combining @@ -3123,7 +3129,8 @@ a file using the local browser (by putting the cursor on it) and pressing Related topics: * To see what the current directory is, use |:pwd| - * To make the currently browsed directory the current directory, see |netrw-c| + * To make the currently browsed directory the current directory, see + |netrw-cd| * To automatically make the currently browsed directory the current directory, see |g:netrw_keepdir|. @@ -3798,9 +3805,15 @@ netrw: or http://vim.sourceforge.net/scripts/script.php?script_id=120 - Decho.vim is provided as a "vimball"; see |vimball-intro|. + Decho.vim is provided as a "vimball"; see |vimball-intro|. You + should edit the Decho.vba.gz file and source it in: > - 2. Edit the <netrw.vim> file by typing: > + vim Decho.vba.gz + :so % + :q +< + 2. To turn on debug tracing in netrw, then edit the <netrw.vim> + file by typing: > vim netrw.vim :DechoOn @@ -3822,14 +3835,34 @@ netrw: read/write your file over the network in a separate tab or server vim window. - To save the file, use > + Change the netrw.vimrc file to include the Decho plugin: > + + set nocp + so $HOME/.vim/plugin/Decho.vim + so $HOME/.vim/plugin/netrwPlugin.vim +< + You should continue to run vim with > + + vim -u netrw.vimrc --noplugins -i NONE [some path here] +< + to avoid entanglements with options and other plugins. + + To save the file: under linux, the output will be in a separate + remote server window; in it, just save the file with > + + :w! DBG + +< Under a vim that doesn't support clientserver, your debugging + output will appear in another tab: > :tabnext :set bt= :w! DBG +< + Furthermore, it'd be helpful if you would type > -< Furthermore, it'd be helpful if you would type > :Dsep <command> + < where <command> is the command you're about to type next, thereby making it easier to associate which part of the debugging trace is due to which command. @@ -3837,17 +3870,34 @@ netrw: Please send that information to <netrw.vim>'s maintainer along with the o/s you're using and the vim version that you're using (see |:version|) (remove the embedded NOSPAM first) > + NcampObell@SdrPchip.AorgM-NOSPAM < ============================================================================== 12. History *netrw-history* {{{1 + v170: Mar 11, 2020 * (reported by Reiner Herrmann) netrw+tree + would not hide with the ^\..* pattern + correctly. + * (Marcin Szamotulski) NetrwOptionRestore + did not restore options correctly that + had a single quote in the option string. + Apr 13, 2020 * implemented error handling via popup + windows (see |popup_beval()|) + Apr 30, 2020 * (reported by Manatsu Takahashi) while + using Lexplore, a modified file could + be overwritten. Sol'n: will not overwrite, + but will emit an |E37| (although one cannot + add an ! to override) + Jun 07, 2020 * (reported by Jo Totland) repeatedly invoking + :Lexplore and quitting it left unused + hidden buffers. Netrw will now set netrw + buffers created by :Lexplore to |bh|=wipe. v169: Dec 20, 2019 * (reported by amkarthik) that netrw's x (|netrw-x|) would throw an error when attempting to open a local directory. v168: Dec 12, 2019 * scp timeout error message not reported, hopefully now fixed (Shane Xb Qian) - v167: Nov 29, 2019 * netrw does a save&restore on @* and @+. That causes problems with the clipboard. Now restores occurs only if @* or @+ have @@ -4305,4 +4355,4 @@ netrw: ============================================================================== Modelines: {{{1 - vim:tw=78:ts=8:noet:ft=help:norl:fdm=marker +vim:tw=78:ts=8:ft=help:noet:norl:fdm=marker diff --git a/runtime/doc/pi_zip.txt b/runtime/doc/pi_zip.txt index 7a5e7166ba..c715644847 100644 --- a/runtime/doc/pi_zip.txt +++ b/runtime/doc/pi_zip.txt @@ -4,7 +4,7 @@ | Zip File Interface | +====================+ -Author: Charles E. Campbell <NdrOchip@ScampbellPfamily.AbizM> +Author: Charles E. Campbell <NcampObell@SdrPchip.AorgM-NOSPAM> (remove NOSPAM from Campbell's email first) Copyright: Copyright (C) 2005-2015 Charles E Campbell *zip-copyright* The VIM LICENSE (see |copyright|) applies to the files in this @@ -33,10 +33,11 @@ Copyright: Copyright (C) 2005-2015 Charles E Campbell *zip-copyright* also write to the file. Currently, one may not make a new file in zip archives via the plugin. + COMMANDS~ *zip-x* - x : may extract a listed file when the cursor is atop it + x : extract a listed file when the cursor is atop it - OPTIONS + OPTIONS~ *g:zip_nomax* @@ -101,6 +102,10 @@ Copyright: Copyright (C) 2005-2015 Charles E Campbell *zip-copyright* ============================================================================== 4. History *zip-history* {{{1 + v29 Apr 02, 2017 * (Klartext) reported that an encrypted zip file could + opened but the swapfile held unencrypted contents. + The solution is to edit the contents of a zip file + using the |:noswapfile| modifier. v28 Oct 08, 2014 * changed the sanity checks for executables to reflect the command actually to be attempted in zip#Read() and zip#Write() @@ -149,4 +154,4 @@ Copyright: Copyright (C) 2005-2015 Charles E Campbell *zip-copyright* v1 Sep 15, 2005 * Initial release, had browsing, reading, and writing ============================================================================== -vim:tw=78:ts=8:noet:ft=help:fdm=marker +vim:tw=78:ts=8:ft=help:noet:norl:fdm=marker diff --git a/runtime/doc/print.txt b/runtime/doc/print.txt index d744735b96..e7de5b9ee3 100644 --- a/runtime/doc/print.txt +++ b/runtime/doc/print.txt @@ -101,7 +101,7 @@ If 'printencoding' is empty or Vim cannot find the file then it will use encoding file. If Vim is unable to find a character encoding file then it will use the "latin1" print character encoding file. -When 'encoding' is set to a multi-byte encoding, Vim will try to convert +When 'encoding' is set to a multibyte encoding, Vim will try to convert characters to the printing encoding for printing (if 'printencoding' is empty then the conversion will be to latin1). Conversion to a printing encoding other than latin1 will require Vim to be compiled with the |+iconv| feature. @@ -251,7 +251,7 @@ Japanese text you would do the following; > :set printmbcharset=JIS_X_1983 If 'printmbcharset' is not one of the above values then it is assumed to -specify a custom multi-byte character set and no check will be made that it is +specify a custom multibyte character set and no check will be made that it is compatible with the value for 'printencoding'. Vim will look for a file defining the character set in the "print" directory in 'runtimepath'. @@ -286,7 +286,7 @@ printing of characters in the ASCII code range. a:yes Use ASCII character set for codes in the ASCII a:no (default) code range. -The following is an example of specifying two multi-byte fonts, one for normal +The following is an example of specifying two multibyte fonts, one for normal and italic printing and one for bold and bold-italic printing, and using Courier to print codes in the ASCII code range but using the national character set: > @@ -402,10 +402,10 @@ There are currently a number of limitations with PostScript printing: possible to get all the characters in an encoding to print by installing a new version of the Courier font family. -- Multi-byte support - Currently Vim will try to convert multi-byte characters +- Multi-byte support - Currently Vim will try to convert multibyte characters to the 8-bit encoding specified by 'printencoding' (or latin1 if it is empty). Any characters that are not successfully converted are shown as - unknown characters. Printing will fail if Vim cannot convert the multi-byte + unknown characters. Printing will fail if Vim cannot convert the multibyte to the 8-bit encoding. ============================================================================== @@ -490,7 +490,7 @@ print ASCII text using the national character set you may see some unexpected characters. If you want true ASCII code printing then you need to configure Vim to output ASCII characters for the ASCII code range with 'printmbfont'. -It is possible to define your own multi-byte character set although this +It is possible to define your own multibyte character set although this should not be attempted lightly. A discussion on the process if beyond the scope of these help files. You can find details on CMap (character map) files in the document 'Adobe CMap and CIDFont Files Specification, Version 1.0', @@ -597,22 +597,15 @@ X11 http://www.cs.wisc.edu/~ghost/gv/ -Windows +MS-Windows - GSview. Obtainable from: http://www.cs.wisc.edu/~ghost/gsview/ -DOS - -- ps_view. Obtainable from: - - ftp://ftp.pg.gda.pl/pub/TeX/support/ps_view/ - ftp://ftp.dante.de/tex-archive/support/ps_view/ - Linux -- GSview. Linux version of the popular Windows previewer. +- GSview. Linux version of the popular MS-Windows previewer. Obtainable from: http://www.cs.wisc.edu/~ghost/gsview/ diff --git a/runtime/doc/quickfix.txt b/runtime/doc/quickfix.txt index fab3b11430..db6b759af6 100644 --- a/runtime/doc/quickfix.txt +++ b/runtime/doc/quickfix.txt @@ -225,8 +225,7 @@ processing a quickfix or location list command, it will be aborted. e.g., a compiler will not compile the same file again, `git commit` will abort the committing process, `fc` (built-in for shells like bash and zsh) will not - execute the command, etc. will not compile the same - file again. + execute the command, etc. {N} can also be zero, in which case Vim exits normally. WARNING: All changes in files are lost. It works like @@ -311,7 +310,7 @@ processing a quickfix or location list command, it will be aborted. *:cex* *:cexpr* *E777* :cex[pr][!] {expr} Create a quickfix list using the result of {expr} and jump to the first error. - If {expr} is a String, then each new-line terminated + If {expr} is a String, then each newline terminated line in the String is processed using the global value of 'errorformat' and the result is added to the quickfix list. @@ -484,7 +483,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 execution stops. + When going to the next entry fails execution stops. The last buffer (or where an error occurred) becomes the current buffer. {cmd} can contain '|' to concatenate several commands. @@ -926,11 +925,11 @@ or simpler > "$*" can be given multiple times, for example: > :set makeprg=gcc\ -o\ $*\ $* -The 'shellpipe' option defaults to ">" on Windows. This means that the output -of the compiler is saved in a file and not shown on the screen directly. For -Unix "| tee" is used. The compiler output is shown on the screen and saved in -a file the same time. Depending on the shell used "|& tee" or "2>&1| tee" is -the default, so stderr output will be included. +The 'shellpipe' option defaults to ">%s 2>&1" for Win32. +This means that the output of the compiler is saved in a file and not shown on +the screen directly. For Unix "| tee" is used. The compiler output is shown +on the screen and saved in a file the same time. Depending on the shell used +"|& tee" or "2>&1| tee" is the default, so stderr output will be included. If 'shellpipe' is empty, the {errorfile} part will be omitted. This is useful for compilers that write to an errorfile themselves. @@ -995,8 +994,6 @@ commands can be combined to create a NewGrep command: > the error list to the matches. Files matching 'wildignore' are ignored; files in 'suffixes' are searched last. - Without the 'g' flag each line is added only once. - With 'g' every match is added. {pattern} is a Vim search pattern. Instead of enclosing it in / any non-ID character (see @@ -1007,6 +1004,28 @@ commands can be combined to create a NewGrep command: > 'smartcase' is not used. If {pattern} is empty (e.g. // is specified), the last used search pattern is used. |last-pattern| + + Flags: + 'g' Without the 'g' flag each line is added only + once. With 'g' every match is added. + + 'j' Without the 'j' flag Vim jumps to the first + match. With 'j' only the quickfix list is + updated. With the [!] any changes in the current + buffer are abandoned. + + 'f' When the 'f' flag is specified, fuzzy string + matching is used to find matching lines. In this + case, {pattern} is treated as a literal string + instead of a regular expression. See + |matchfuzzy()| for more info about fuzzy + matching. + + |QuickFixCmdPre| and |QuickFixCmdPost| are triggered. + A file that is opened for matching may use a buffer + number, but it is reused if possible to avoid + consuming buffer numbers. + :{count}vim[grep] ... When a number is put before the command this is used as the maximum number of matches to find. Use @@ -1014,11 +1033,6 @@ commands can be combined to create a NewGrep command: > Useful if you only want to check if there is a match and quit quickly when it's found. - Without the 'j' flag Vim jumps to the first match. - With 'j' only the quickfix list is updated. - With the [!] any changes in the current buffer are - abandoned. - Every second or so the searched file name is displayed to give you an idea of the progress made. Examples: > @@ -1090,7 +1104,7 @@ id-utils) in a similar way to its compiler integration (see |:make| above). allowed with |:bufdo|. An example that uses the argument list and avoids errors for files without matches: > - :silent argdo try + :silent argdo try \ | grepadd! something % \ | catch /E480:/ \ | endtry" @@ -1266,7 +1280,7 @@ You can force the compiler to ignore makefiles by defining b:tex_ignore_makefile or g:tex_ignore_makefile variable (they are checked for existence only). -If the compiler chose not to use make, it need to choose a right program for +If the compiler chose not to use make, it needs to choose a right program for processing your input. If b:tex_flavor or g:tex_flavor (in this precedence) variable exists, it defines TeX flavor for :make (actually, this is the name of executed command), and if both variables do not exist, it defaults to @@ -1658,7 +1672,7 @@ special problem here is that it doesn't print information on leaving the directory and that it doesn't print the absolute path. To solve the problem with relative paths and missing "leave directory" -messages Vim uses following algorithm: +messages Vim uses the following algorithm: 1) Check if the given directory is a subdirectory of the current directory. If this is true, store it as the current directory. diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt index 4a47fd4b57..fb20a583c9 100644 --- a/runtime/doc/quickref.txt +++ b/runtime/doc/quickref.txt @@ -292,7 +292,7 @@ moving around: |i_CTRL-A| CTRL-A insert previously inserted text |i_CTRL-@| CTRL-@ insert previously inserted text and stop Insert mode -|i_CTRL-R| CTRL-R {0-9a-z%#:.-="} insert the contents of a register +|i_CTRL-R| CTRL-R {register} insert the contents of a register |i_CTRL-N| CTRL-N insert next match of identifier before the cursor @@ -621,7 +621,7 @@ Short explanation of each option: *option-list* 'binary' 'bin' read/write/edit file in binary mode 'bomb' prepend a Byte Order Mark to the file 'breakat' 'brk' characters that may cause a line break -'breakindent' 'bri' wrapped line repeats indent +'breakindent' 'bri' wrapped line repeats indent 'breakindentopt' 'briopt' settings for 'breakindent' 'browsedir' 'bsdir' which directory to start browsing in 'bufhidden' 'bh' what to do when buffer is no longer in window @@ -680,7 +680,7 @@ Short explanation of each option: *option-list* 'eventignore' 'ei' autocommand events that are ignored 'expandtab' 'et' use spaces when <Tab> is inserted 'exrc' 'ex' read .nvimrc and .exrc in the current directory -'fileencoding' 'fenc' file encoding for multi-byte text +'fileencoding' 'fenc' file encoding for multibyte text 'fileencodings' 'fencs' automatically detected character encodings 'fileformat' 'ff' file format used for file I/O 'fileformats' 'ffs' automatically detected values for 'fileformat' @@ -869,6 +869,7 @@ Short explanation of each option: *option-list* 'spellcapcheck' 'spc' pattern to locate end of a sentence 'spellfile' 'spf' files where |zg| and |zw| store words 'spelllang' 'spl' language(s) to do spell checking for +'spelloptions' 'spo' options for spell checking 'spellsuggest' 'sps' method(s) used to suggest spelling corrections 'splitbelow' 'sb' new window from split is below the current one 'splitright' 'spr' new window is put right of the current one @@ -1014,8 +1015,7 @@ Short explanation of each option: *option-list* three digits) |c_CTRL-K| CTRL-K {char1} {char2} enter digraph (See |Q_di|) -|c_CTRL-R| CTRL-R {0-9a-z"%#:-=} - insert the contents of a register +|c_CTRL-R| CTRL-R {register} insert the contents of a register |c_<Left>| <Left>/<Right> cursor left/right |c_<S-Left>| <S-Left>/<S-Right> cursor one word left/right diff --git a/runtime/doc/recover.txt b/runtime/doc/recover.txt index 7789d4bdbc..9ef5a37452 100644 --- a/runtime/doc/recover.txt +++ b/runtime/doc/recover.txt @@ -56,13 +56,13 @@ Disadvantages: directories (although Vim tries to avoid that by comparing the path name). This will result in bogus ATTENTION warning messages. - When you use your home directory, and somebody else tries to edit the same - file, he will not see your swap file and will not get the ATTENTION warning - message. + file, that user will not see your swap file and will not get the ATTENTION + warning message. If you want to put swap files in a fixed place, put a command resembling the following ones in your vimrc: :set dir=~/tmp (for Unix) - :set dir=c:\\tmp (for Windows) + :set dir=c:\\tmp (for Win32) This is also very handy when editing files on floppy. Of course you will have to create that "tmp" directory for this to work! @@ -106,8 +106,9 @@ If you want to make sure that your changes are in the swap file use this command: *:pre* *:preserve* *E313* *E314* -:pre[serve] Write all text for all buffers into swap file. The - original file is no longer needed for recovery. +:pre[serve] Write all text for the current buffer into its swap + file. The original file is no longer needed for + recovery. This sets a flag in the current buffer. A Vim swap file can be recognized by the first six characters: "b0VIM ". After that comes the version number, e.g., "3.0". diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt index 3a7337d2e8..b237d70760 100644 --- a/runtime/doc/repeat.txt +++ b/runtime/doc/repeat.txt @@ -70,7 +70,7 @@ 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 line is aborted and the global command continues with the next marked or unmarked line. - *E147* + *E147* When the command is used recursively, it only works on one line. Giving a range is then not allowed. This is useful to find all lines that match a pattern and do not match another pattern: > @@ -117,6 +117,11 @@ q{0-9a-zA-Z"} Record typed characters into register {0-9a-zA-Z"} recorded macro and the yank will overwrite the recorded macro. + Note: The recording happens while you type, replaying + the register happens as if the keys come from a + mapping. This matters, for example, for undo, which + only syncs when commands were typed. + q Stops recording. Implementation note: The 'q' that stops recording is not stored in the register, unless it was the result @@ -129,7 +134,7 @@ q Stops recording. used. The register is executed like a mapping, that means that the difference between 'wildchar' and 'wildcharm' - applies. + applies, and undo might not be synced in the same way. For "@=" you are prompted to enter an expression. The result of the expression is then executed. See also |@:|. @@ -153,7 +158,7 @@ q Stops recording. [addr] (default is current line). :[addr]@ *:@@* -:[addr]@@ Repeat the previous :@{0-9a-z"}. First set cursor at +:[addr]@@ Repeat the previous :@{register}. First set cursor at line [addr] (default is current line). ============================================================================== @@ -206,10 +211,10 @@ For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. When {file} contains wildcards it is expanded to all matching files. Example: > - :runtime! plugin/*.vim + :runtime! plugin/**/*.vim < This is what Vim uses to load the plugin files when starting up. This similar command: > - :runtime plugin/*.vim + :runtime plugin/**/*.vim < would source the first file only. When 'verbose' is one or higher, there is a message @@ -248,6 +253,9 @@ For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. directories are added to 'runtimepath'. This is useful in your .vimrc. The plugins will then be loaded during initialization, see |load-plugins|. + Note that for ftdetect scripts to be loaded + you will need to write `filetype plugin indent on` + AFTER all `packadd!` commands. Also see |pack-add|. @@ -366,7 +374,7 @@ nested as deep as the number of files that can be opened at one time (about You can use the "<sfile>" string (literally, this is not a special key) inside of the sourced file, in places where a file name is expected. It will be replaced by the file name of the sourced file. For example, if you have a -"other.vimrc" file in the same directory as your |init.vim| file, you can +"other.vimrc" file in the same directory as your |init.vim| file, you can source it from your |init.vim| file with this command: > :source <sfile>:h/other.vimrc @@ -388,7 +396,7 @@ because the <CR> from the first lines will be lost. On other systems, Vim expects ":source"ed files to end in a <NL>. These always work. If you are using a file with <CR><NL> <EOL>s (for example, a -file made on Windows), all lines will have a trailing <CR>. This may cause +file made on MS-Windows), all lines will have a trailing <CR>. This may cause problems for some commands (e.g., mappings). There is no automatic <EOL> detection, because it's common to start with a line that defines a mapping that ends in a <CR>, which will confuse the automaton. @@ -505,7 +513,7 @@ When Vim starts up, after processing your .vimrc, it scans all directories in 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 +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 @@ -591,8 +599,8 @@ 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 +users can choose what they include or not. Or you can decide to use one +package with optional plugins, and tell the user to add the preferred ones with `:packadd`. Decide how you want to distribute the package. You can create an archive or @@ -613,9 +621,9 @@ Your directory layout would be like this: 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 + mkdir ~/.local/share/nvim/site/pack + cd ~/.local/share/nvim/site/pack + git clone https://github.com/you/foobar.git myfoobar Here "myfoobar" is a name that the user can choose, the only condition is that it differs from other packages. @@ -628,7 +636,7 @@ 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 +generated file in the package means that the user can drop the package in the 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 @@ -815,7 +823,7 @@ DEFINING BREAKPOINTS valid in the script where it has been defined and if that script is called from several other scripts, this will stop whenever that particular variable will become visible or - unaccessible again. + inaccessible again. The [lnum] is the line number of the breakpoint. Vim will stop at or after this line. When omitted line 1 is used. diff --git a/runtime/doc/rileft.txt b/runtime/doc/rileft.txt index 550a696de0..d45a2dce7e 100644 --- a/runtime/doc/rileft.txt +++ b/runtime/doc/rileft.txt @@ -64,7 +64,7 @@ o Invocations + 'rightleft' ('rl') sets window orientation to right-to-left. + 'delcombine' ('deco'), boolean, if editing UTF-8 encoded languages, allows one to remove a composing character which gets superimposed - on those that proceeded them (some languages require this). + on those that preceded them (some languages require this). + 'rightleftcmd' ('rlc') sets the command-line within certain modes (such as search) to be utilized in right-to-left orientation as well. diff --git a/runtime/doc/sign.txt b/runtime/doc/sign.txt index e3ba4ba181..e8ed29c1a4 100644 --- a/runtime/doc/sign.txt +++ b/runtime/doc/sign.txt @@ -42,8 +42,8 @@ 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. 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: > +The color of the column is set with the SignColumn highlight group +|hl-SignColumn|. Example to set the color: > :highlight SignColumn guibg=darkgrey < @@ -68,9 +68,13 @@ other plugins using signs. *sign-priority* Each placed sign is assigned a priority value. When multiple signs are placed on the same line, the attributes of the sign with the highest priority is used -independent of the sign group. The default priority for a sign is 10. The +independently of the sign group. The default priority for a sign is 10. The priority is assigned at the time of placing a sign. +When two signs with the same priority are present, and one has an icon or text +in the signcolumn while the other has line highlighting, then both are +displayed. + When the line on which the sign is placed is deleted, the sign is moved to the next line (or the last line of the buffer, if there is no next line). When the delete is undone the sign does not move back. @@ -127,6 +131,9 @@ See |sign_define()| for the equivalent Vim script function. texthl={group} Highlighting group used for the text item. + Example: > + :sign define MySign text=>> texthl=Search linehl=DiffText +< DELETING A SIGN *:sign-undefine* *E155* @@ -136,7 +143,9 @@ See |sign_undefine()| for the equivalent Vim script function. Deletes a previously defined sign. If signs with this {name} are still placed this will cause trouble. - + Example: > + :sign undefine MySign +< LISTING SIGNS *:sign-list* *E156* @@ -190,6 +199,10 @@ See |sign_place()| for the equivalent Vim script function. Same, but use buffer {nr}. If the buffer argument is not given, place the sign in the current buffer. + Example: > + :sign place 10 line=99 name=sign3 + :sign place 10 line=99 name=sign3 buffer=3 +< *E885* :sign place {id} name={name} file={fname} Change the placed sign {id} in file {fname} to use the defined @@ -202,10 +215,17 @@ See |sign_place()| for the equivalent Vim script function. "priority={prio}" attribute can be used to change the priority of an existing sign. + Example: > + :sign place 23 name=sign1 file=/path/to/edit.py +< :sign place {id} name={name} [buffer={nr}] Same, but use buffer {nr}. If the buffer argument is not given, use the current buffer. + Example: > + :sign place 23 name=sign1 + :sign place 23 name=sign1 buffer=7 +< REMOVING SIGNS *:sign-unplace* *E159* @@ -337,4 +357,363 @@ See |sign_jump()| for the equivalent Vim script function. Same but jump to the sign in group {group} +============================================================================== +3. Functions *sign-functions-details* + +sign_define({name} [, {dict}]) *sign_define()* +sign_define({list}) + Define a new sign named {name} or modify the attributes of an + existing sign. This is similar to the |:sign-define| command. + + Prefix {name} with a unique text to avoid name collisions. + There is no {group} like with placing signs. + + The {name} can be a String or a Number. The optional {dict} + argument specifies the sign attributes. The following values + are supported: + icon full path to the bitmap file for the sign. + linehl highlight group used for the whole line the + sign is placed in. + text text that is displayed when there is no icon + or the GUI is not being used. + texthl highlight group used for the text item + numhl highlight group used for 'number' column at the + associated line. Overrides |hl-LineNr|, + |hl-CursorLineNr|. + + If the sign named {name} already exists, then the attributes + of the sign are updated. + + The one argument {list} can be used to define a list of signs. + Each list item is a dictionary with the above items in {dict} + and a "name" item for the sign name. + + Returns 0 on success and -1 on failure. When the one argument + {list} is used, then returns a List of values one for each + defined sign. + + Examples: > + call sign_define("mySign", { + \ "text" : "=>", + \ "texthl" : "Error", + \ "linehl" : "Search"}) + call sign_define([ + \ {'name' : 'sign1', + \ 'text' : '=>'}, + \ {'name' : 'sign2', + \ 'text' : '!!'} + \ ]) +< +sign_getdefined([{name}]) *sign_getdefined()* + Get a list of defined signs and their attributes. + This is similar to the |:sign-list| command. + + If the {name} is not supplied, then a list of all the defined + signs is returned. Otherwise the attribute of the specified + sign is returned. + + Each list item in the returned value is a dictionary with the + following entries: + icon full path to the bitmap file of the sign + linehl highlight group used for the whole line the + sign is placed in. + name name of the sign + text text that is displayed when there is no icon + or the GUI is not being used. + texthl highlight group used for the text item + numhl highlight group used for 'number' column at the + associated line. Overrides |hl-LineNr|, + |hl-CursorLineNr|. + + Returns an empty List if there are no signs and when {name} is + not found. + + Examples: > + " Get a list of all the defined signs + echo sign_getdefined() + + " Get the attribute of the sign named mySign + echo sign_getdefined("mySign") +< +sign_getplaced([{expr} [, {dict}]]) *sign_getplaced()* + Return a list of signs placed in a buffer or all the buffers. + This is similar to the |:sign-place-list| command. + + If the optional buffer name {expr} is specified, then only the + list of signs placed in that buffer is returned. For the use + of {expr}, see |bufname()|. The optional {dict} can contain + the following entries: + group select only signs in this group + id select sign with this identifier + lnum select signs placed in this line. For the use + of {lnum}, see |line()|. + If {group} is '*', then signs in all the groups including the + global group are returned. If {group} is not supplied or is an + empty string, then only signs in the global group are + returned. If no arguments are supplied, then signs in the + global group placed in all the buffers are returned. + See |sign-group|. + + Each list item in the returned value is a dictionary with the + following entries: + bufnr number of the buffer with the sign + signs list of signs placed in {bufnr}. Each list + item is a dictionary with the below listed + entries + + The dictionary for each sign contains the following entries: + group sign group. Set to '' for the global group. + id identifier of the sign + lnum line number where the sign is placed + name name of the defined sign + priority sign priority + + The returned signs in a buffer are ordered by their line + number and priority. + + Returns an empty list on failure or if there are no placed + signs. + + Examples: > + " Get a List of signs placed in eval.c in the + " global group + echo sign_getplaced("eval.c") + + " Get a List of signs in group 'g1' placed in eval.c + echo sign_getplaced("eval.c", {'group' : 'g1'}) + + " Get a List of signs placed at line 10 in eval.c + echo sign_getplaced("eval.c", {'lnum' : 10}) + + " Get sign with identifier 10 placed in a.py + echo sign_getplaced("a.py", {'id' : 10}) + + " Get sign with id 20 in group 'g1' placed in a.py + echo sign_getplaced("a.py", {'group' : 'g1', + \ 'id' : 20}) + + " Get a List of all the placed signs + echo sign_getplaced() +< + *sign_jump()* +sign_jump({id}, {group}, {expr}) + Open the buffer {expr} or jump to the window that contains + {expr} and position the cursor at sign {id} in group {group}. + This is similar to the |:sign-jump| command. + + For the use of {expr}, see |bufname()|. + + Returns the line number of the sign. Returns -1 if the + arguments are invalid. + + Example: > + " Jump to sign 10 in the current buffer + call sign_jump(10, '', '') +< + + *sign_place()* +sign_place({id}, {group}, {name}, {expr} [, {dict}]) + Place the sign defined as {name} at line {lnum} in file or + buffer {expr} and assign {id} and {group} to sign. This is + similar to the |:sign-place| command. + + If the sign identifier {id} is zero, then a new identifier is + allocated. Otherwise the specified number is used. {group} is + the sign group name. To use the global sign group, use an + empty string. {group} functions as a namespace for {id}, thus + two groups can use the same IDs. Refer to |sign-identifier| + and |sign-group| for more information. + + {name} refers to a defined sign. + {expr} refers to a buffer name or number. For the accepted + values, see |bufname()|. + + The optional {dict} argument supports the following entries: + lnum line number in the file or buffer + {expr} where the sign is to be placed. + For the accepted values, see |line()|. + priority priority of the sign. See + |sign-priority| for more information. + + If the optional {dict} is not specified, then it modifies the + placed sign {id} in group {group} to use the defined sign + {name}. + + Returns the sign identifier on success and -1 on failure. + + Examples: > + " Place a sign named sign1 with id 5 at line 20 in + " buffer json.c + call sign_place(5, '', 'sign1', 'json.c', + \ {'lnum' : 20}) + + " Updates sign 5 in buffer json.c to use sign2 + call sign_place(5, '', 'sign2', 'json.c') + + " Place a sign named sign3 at line 30 in + " buffer json.c with a new identifier + let id = sign_place(0, '', 'sign3', 'json.c', + \ {'lnum' : 30}) + + " Place a sign named sign4 with id 10 in group 'g3' + " at line 40 in buffer json.c with priority 90 + call sign_place(10, 'g3', 'sign4', 'json.c', + \ {'lnum' : 40, 'priority' : 90}) +< + + *sign_placelist()* +sign_placelist({list}) + Place one or more signs. This is similar to the + |sign_place()| function. The {list} argument specifies the + List of signs to place. Each list item is a dict with the + following sign attributes: + buffer buffer name or number. For the accepted + values, see |bufname()|. + group sign group. {group} functions as a namespace + for {id}, thus two groups can use the same + IDs. If not specified or set to an empty + string, then the global group is used. See + |sign-group| for more information. + id sign identifier. If not specified or zero, + then a new unique identifier is allocated. + Otherwise the specified number is used. See + |sign-identifier| for more information. + lnum line number in the buffer {expr} where the + sign is to be placed. For the accepted values, + see |line()|. + name name of the sign to place. See |sign_define()| + for more information. + priority priority of the sign. When multiple signs are + placed on a line, the sign with the highest + priority is used. If not specified, the + default value of 10 is used. See + |sign-priority| for more information. + + If {id} refers to an existing sign, then the existing sign is + modified to use the specified {name} and/or {priority}. + + Returns a List of sign identifiers. If failed to place a + sign, the corresponding list item is set to -1. + + Examples: > + " Place sign s1 with id 5 at line 20 and id 10 at line + " 30 in buffer a.c + let [n1, n2] = sign_placelist([ + \ {'id' : 5, + \ 'name' : 's1', + \ 'buffer' : 'a.c', + \ 'lnum' : 20}, + \ {'id' : 10, + \ 'name' : 's1', + \ 'buffer' : 'a.c', + \ 'lnum' : 30} + \ ]) + + " Place sign s1 in buffer a.c at line 40 and 50 + " with auto-generated identifiers + let [n1, n2] = sign_placelist([ + \ {'name' : 's1', + \ 'buffer' : 'a.c', + \ 'lnum' : 40}, + \ {'name' : 's1', + \ 'buffer' : 'a.c', + \ 'lnum' : 50} + \ ]) +< + +sign_undefine([{name}]) *sign_undefine()* +sign_undefine({list}) + Deletes a previously defined sign {name}. This is similar to + the |:sign-undefine| command. If {name} is not supplied, then + deletes all the defined signs. + + The one argument {list} can be used to undefine a list of + signs. Each list item is the name of a sign. + + Returns 0 on success and -1 on failure. For the one argument + {list} call, returns a list of values one for each undefined + sign. + + Examples: > + " Delete a sign named mySign + call sign_undefine("mySign") + + " Delete signs 'sign1' and 'sign2' + call sign_undefine(["sign1", "sign2"]) + + " Delete all the signs + call sign_undefine() +< + +sign_unplace({group} [, {dict}]) *sign_unplace()* + Remove a previously placed sign in one or more buffers. This + is similar to the |:sign-unplace| command. + + {group} is the sign group name. To use the global sign group, + use an empty string. If {group} is set to '*', then all the + groups including the global group are used. + The signs in {group} are selected based on the entries in + {dict}. The following optional entries in {dict} are + supported: + buffer buffer name or number. See |bufname()|. + id sign identifier + If {dict} is not supplied, then all the signs in {group} are + removed. + + Returns 0 on success and -1 on failure. + + Examples: > + " Remove sign 10 from buffer a.vim + call sign_unplace('', {'buffer' : "a.vim", 'id' : 10}) + + " Remove sign 20 in group 'g1' from buffer 3 + call sign_unplace('g1', {'buffer' : 3, 'id' : 20}) + + " Remove all the signs in group 'g2' from buffer 10 + call sign_unplace('g2', {'buffer' : 10}) + + " Remove sign 30 in group 'g3' from all the buffers + call sign_unplace('g3', {'id' : 30}) + + " Remove all the signs placed in buffer 5 + call sign_unplace('*', {'buffer' : 5}) + + " Remove the signs in group 'g4' from all the buffers + call sign_unplace('g4') + + " Remove sign 40 from all the buffers + call sign_unplace('*', {'id' : 40}) + + " Remove all the placed signs from all the buffers + call sign_unplace('*') +< +sign_unplacelist({list}) *sign_unplacelist()* + Remove previously placed signs from one or more buffers. This + is similar to the |sign_unplace()| function. + + The {list} argument specifies the List of signs to remove. + Each list item is a dict with the following sign attributes: + buffer buffer name or number. For the accepted + values, see |bufname()|. If not specified, + then the specified sign is removed from all + the buffers. + group sign group name. If not specified or set to an + empty string, then the global sign group is + used. If set to '*', then all the groups + including the global group are used. + id sign identifier. If not specified, then all + the signs in the specified group are removed. + + Returns a List where an entry is set to 0 if the corresponding + sign was successfully removed or -1 on failure. + + Example: > + " Remove sign with id 10 from buffer a.vim and sign + " with id 20 from buffer b.vim + call sign_unplacelist([ + \ {'id' : 10, 'buffer' : "a.vim"}, + \ {'id' : 20, 'buffer' : 'b.vim'}, + \ ]) +< + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/spell.txt b/runtime/doc/spell.txt index 0eef976819..f722747ce9 100644 --- a/runtime/doc/spell.txt +++ b/runtime/doc/spell.txt @@ -854,7 +854,7 @@ time ":mkspell" is used. Vim will then convert everything to 'encoding' and generate a spell file for 'encoding'. If some of the used characters to not fit in 'encoding' you will get an error message. *spell-affix-mbyte* -When using a multi-byte encoding it's possible to use more different affix +When using a multibyte encoding it's possible to use more different affix flags. But Myspell doesn't support that, thus you may not want to use it anyway. For compatibility use an 8-bit encoding. @@ -1411,7 +1411,7 @@ are spelling mistakes this may not be quite right. Common words can be specified with the COMMON item. This will give better suggestions when editing a short file. Example: - COMMON the of to and a in is it you that he was for on are ~ + COMMON the of to and a in is it you that he she was for on are ~ The words must be separated by white space, up to 25 per line. When multiple regions are specified in a ":mkspell" command the common words diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index d3647246fa..ae9022c56c 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -42,9 +42,12 @@ filename One or more file names. The first one will be the current In most cases (except -s, -es, |--embed|, --headless) if stdin is not a TTY then it is read as text, so "-" is implied: > echo text | nvim file -< The buffer will be marked modified, because it contains text - that needs to be saved (except for readonly |-R| mode). - +< The buffer will be marked as modified, because it contains + text that needs to be saved (except for readonly |-R| mode). + If you don't like that, put these lines in your init.vim: > + " Don't set 'modified' when reading from stdin + au StdinReadPost * set nomodified +< To read stdin as Normal commands use |-s| with "-": > echo "ifoo" | nvim -s - < To read stdin as Ex commands use |-es| or |-e|: > @@ -390,7 +393,7 @@ accordingly. Vim proceeds in this order: 1. Set the 'shell' option *SHELL* *COMSPEC* The environment variable SHELL, if it exists, is used to set the - 'shell' option. On Windows, the COMSPEC variable is used + 'shell' option. On Win32, the COMSPEC variable is used if SHELL is not set. 2. Process the arguments @@ -518,7 +521,8 @@ accordingly. Vim proceeds in this order: displayed yet). When switching screens, it happens now. Redrawing starts. If the "-q" flag was given to Vim, the first error is jumped to. - Buffers for all windows will be loaded. + Buffers for all windows will be loaded, without triggering |BufAdd| + autocommands. 14. Execute startup commands If a "-t" flag was given to Vim, the tag is jumped to. @@ -621,7 +625,7 @@ Nvim will try to get the value for $VIMRUNTIME in this order: 1. Environment variable $VIMRUNTIME, if it is set. 2. Directory path "$VIM/vim{version}", if it exists, where {version} is the - Vim version number without '-' or '.'. For example: "$VIM/vim54". + Vim version number without '-' or '.'. For example: "$VIM/vim82". 3. Directory path "$VIM/runtime", if it exists. 4. Value of $VIM environment variable. This is for backwards compatibility with older Vim versions. @@ -766,7 +770,11 @@ resulting file, when executed with a ":source" command: "options". Script-local mappings will not be written. 2. Restores global variables that start with an uppercase letter and contain at least one lowercase letter, if 'sessionoptions' contains "globals". -3. Unloads all currently loaded buffers. +3. Closes all windows in the current tab page, except the current one; closes + all tab pages except the current one (this results in currently loaded + buffers to be unloaded, some may become hidden if 'hidden' is set or + otherwise specified); wipes out the current buffer, if it is empty + and unnamed. 4. Restores the current directory if 'sessionoptions' contains "curdir", or sets the current directory to where the Session file is if 'sessionoptions' contains "sesdir". @@ -938,8 +946,8 @@ about to abandon with ":bdel", use ":wsh". The '[' and ']' marks are not stored, but the '"' mark is. The '"' mark is very useful for jumping to the cursor position when the file was last exited. No marks are saved for files that start with any string given with the "r" flag in 'shada'. This can be -used to avoid saving marks for files on removable media (for Windows you would -use "ra:,rb:". +used to avoid saving marks for files on removable media (for MS-Windows you +would use "ra:,rb:"). The |v:oldfiles| variable is filled with the file names that the ShaDa file has marks for. diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt index aeee02a1e0..95e00720b1 100644 --- a/runtime/doc/syntax.txt +++ b/runtime/doc/syntax.txt @@ -37,14 +37,14 @@ If the VIM environment variable is not set, Vim will try to find the path in another way (see |$VIMRUNTIME|). Usually this works just fine. If it doesn't, try setting the VIM environment variable to the directory where the Vim stuff is located. For example, if your syntax files -are in the "/usr/vim/vim50/syntax" directory, set $VIMRUNTIME to -"/usr/vim/vim50". You must do this in the shell, before starting Vim. +are in the "/usr/vim/vim82/syntax" directory, set $VIMRUNTIME to +"/usr/vim/vim82". You must do this in the shell, before starting Vim. This command also sources the |menu.vim| script when the GUI is running or will start soon. See |'go-M'| about avoiding that. *:syn-on* *:syntax-on* -The `:syntax enable` command will keep your current color settings. This -allows using `:highlight` commands to set your preferred colors before or +The `:syntax enable` command will keep most of your current color settings. +This allows using `:highlight` commands to set your preferred colors before or after using this command. If you want Vim to overrule your settings with the defaults, use: > :syntax on @@ -56,10 +56,10 @@ with: > For a color terminal see |:hi-normal-cterm|. For setting up your own colors syntax highlighting see |syncolor|. -NOTE: The syntax files on Windows have lines that end in <CR><NL>. The files -for Unix end in <NL>. This means you should use the right type of file for -your system. Although on Windows the right format is automatically selected -if the 'fileformats' option is not empty. +NOTE: The syntax files on MS-Windows have lines that end in <CR><NL>. +The files for Unix end in <NL>. This means you should use the right type of +file for your system. Although on MS-Windows the right format is +automatically selected if the 'fileformats' option is not empty. NOTE: When using reverse video ("gvim -fg white -bg black"), the default value of 'background' will not be set until the GUI window is opened, which is after @@ -194,7 +194,7 @@ The name for a highlight or syntax group must consist of ASCII letters, digits and the underscore. As a regexp: "[a-zA-Z0-9_]*". However, Vim does not give an error when using other characters. -To be able to allow each user to pick his favorite set of colors, there must +To be able to allow each user to pick their favorite set of colors, there must be preferred names for highlight groups that are common for many languages. These are the suggested group names (if syntax highlighting works properly you can see the actual color, except for "Ignore"): @@ -453,6 +453,16 @@ conversion. See |-E| and |-s-ex| for details. It is probably best to create a script to replace all the -c commands and use it with the -u flag instead of specifying each command separately. + *hl-TOhtmlProgress* *TOhtml-progress-color* +When displayed, the progress bar will show colored boxes along the statusline +as the HTML conversion proceeds. By default, the background color as the +current "DiffDelete" highlight group is used. If "DiffDelete" and "StatusLine" +have the same background color, TOhtml will automatically adjust the color to +differ. If you do not like the automatically selected colors, you can define +your own highlight colors for the progress bar. Example: > + + hi TOhtmlProgress guifg=#c0ffee ctermbg=7 +< *g:html_number_lines* Default: current 'number' setting. When 0, buffer text is displayed in the generated HTML without line numbering. @@ -484,8 +494,8 @@ For example: > < *g:html_use_css* Default: 1. -When 1, generate valid HTML 4.01 markup with CSS1 styling, supported in all -modern browsers and most old browsers. +When 1, generate valid HTML 5 markup with CSS styling, supported in all modern +browsers and many old browsers. When 0, generate <font> tags and similar outdated markup. This is not recommended but it may work better in really old browsers, email clients, forum posts, and similar situations where basic CSS support is unavailable. @@ -557,23 +567,43 @@ affected in this way as follows: Example, to make the fold column and line numbers uncopyable: > :let g:html_prevent_copy = "fn" < -This feature is currently implemented by inserting read-only <input> elements -into the markup to contain the uncopyable areas. This does not work well in -all cases. When pasting to some applications which understand HTML, the -<input> elements also get pasted. But plain-text paste destinations should -always work. +The method used to prevent copying in the generated page depends on the value +of |g:html_use_input_for_pc|. + + *g:html_use_input_for_pc* +Default: "fallback" +If |g:html_prevent_copy| is non-empty, then: + +When "all", read-only <input> elements are used in place of normal text for +uncopyable regions. In some browsers, especially older browsers, after +selecting an entire page and copying the selection, the <input> tags are not +pasted with the page text. If |g:html_no_invalid| is 0, the <input> tags have +invalid type; this works in more browsers, but the page will not validate. +Note: this method does NOT work in recent versions of Chrome and equivalent +browsers; the <input> tags get pasted with the text. + +When "fallback" (default value), the same <input> elements are generated for +older browsers, but newer browsers (detected by CSS feature query) hide the +<input> elements and instead use generated content in an ::before pseudoelement +to display the uncopyable text. This method should work with the largest +number of browsers, both old and new. + +When "none", the <input> elements are not generated at all. Only the +generated-content method is used. This means that old browsers, notably +Internet Explorer, will either copy the text intended not to be copyable, or +the non-copyable text may not appear at all. However, this is the most +standards-based method, and there will be much less markup. *g:html_no_invalid* Default: 0. -When 0, if |g:html_prevent_copy| is non-empty, an invalid attribute is -intentionally inserted into the <input> element for the uncopyable areas. This -increases the number of applications you can paste to without also pasting the -<input> elements. Specifically, Microsoft Word will not paste the <input> -elements if they contain this invalid attribute. -When 1, no invalid markup is ever intentionally inserted, and the generated -page should validate. However, be careful pasting into Microsoft Word when -|g:html_prevent_copy| is non-empty; it can be hard to get rid of the <input> -elements which get pasted. +When 0, if |g:html_prevent_copy| is non-empty and |g:html_use_input_for_pc| is +not "none", an invalid attribute is intentionally inserted into the <input> +element for the uncopyable areas. This prevents pasting the <input> elements +in some applications. Specifically, some versions of Microsoft Word will not +paste the <input> elements if they contain this invalid attribute. When 1, no +invalid markup is inserted, and the generated page should validate. However, +<input> elements may be pasted into some applications and can be difficult to +remove afterward. *g:html_hover_unfold* Default: 0. @@ -895,7 +925,7 @@ SELECTEMPTY, ... The indentation preceding the begin/end keywords has to match (spaces are not considered equal to a tab). > let baan_fold_sql=1 Note: Block folding can result in many small folds. It is suggested to |:set| -the options 'foldminlines' and 'foldnestmax' in |init.vim| or use |:setlocal| +the options 'foldminlines' and 'foldnestmax' in |init.vim| or use |:setlocal| in .../after/syntax/baan.vim (see |after-directory|). Eg: > set foldminlines=5 set foldnestmax=6 @@ -913,10 +943,12 @@ Basic. C *c.vim* *ft-c-syntax* A few things in C highlighting are optional. To enable them assign any value -to the respective variable. Example: > +(including zero) to the respective variable. Example: > :let c_comment_strings = 1 -To disable them use ":unlet". Example: > + :let c_no_bracket_error = 0 +To disable them use `:unlet`. Example: > :unlet c_comment_strings +Setting the value to zero doesn't work! An alternative is to switch to the C++ highlighting: > :set filetype=cpp @@ -932,8 +964,8 @@ Variable Highlight ~ except { and } in first column 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_curly_error* highlight a missing } by finding all pairs; 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 @@ -1135,15 +1167,37 @@ startup vimrc: > :let filetype_w = "cweb" +DART *dart.vim* *ft-dart-syntax* + +Dart is an object-oriented, typed, class defined, garbage collected language +used for developing mobile, desktop, web, and back-end applications. Dart uses +a C-like syntax derived from C, Java, and JavaScript, with features adopted +from Smalltalk, Python, Ruby, and others. + +More information about the language and its development environment at the +official Dart language website at https://dart.dev + +dart.vim syntax detects and highlights Dart statements, reserved words, +type declarations, storage classes, conditionals, loops, interpolated values, +and comments. There is no support idioms from Flutter or any other Dart +framework. + +Changes, fixes? Submit an issue or pull request via: + +https://github.com/pr3d4t0r/dart-vim-syntax/ + + DESKTOP *desktop.vim* *ft-desktop-syntax* Primary goal of this syntax file is to highlight .desktop and .directory files according to freedesktop.org standard: -http://standards.freedesktop.org/desktop-entry-spec/latest/ -But actually almost none implements this standard fully. Thus it will -highlight all Unix ini files. But you can force strict highlighting according -to standard by placing this in your vimrc file: > - :let enforce_freedesktop_standard = 1 +https://specifications.freedesktop.org/desktop-entry-spec/latest/ +To highlight nonstandard extensions that does not begin with X-, set > + let g:desktop_enable_nonstd = 1 +Note that this may cause wrong highlight. +To highlight KDE-reserved features, set > + let g:desktop_enable_kde = 1 +g:desktop_enable_kde follows g:desktop_enable_nonstd if not supplied DIFF *diff.vim* @@ -1326,26 +1380,26 @@ to your startup file. EUPHORIA *euphoria3.vim* *euphoria4.vim* *ft-euphoria-syntax* -Two syntax highlighting files exists for Euphoria. One for Euphoria -version 3.1.1, which is the default syntax highlighting file, and one for +Two syntax highlighting files exist for Euphoria. One for Euphoria +version 3.1.1, which is the default syntax highlighting file, and one for Euphoria version 4.0.5 or later. -Euphoria version 3.1.1 (http://www.rapideuphoria.com/) is still necessary -for developing applications for the DOS platform, which Euphoria version 4 +Euphoria version 3.1.1 (http://www.rapideuphoria.com/) is still necessary +for developing applications for the DOS platform, which Euphoria version 4 (http://www.openeuphoria.org/) does not support. -The following file extensions are auto-detected as Euphoria file type: - +The following file extensions are auto-detected as Euphoria file type: + *.e, *.eu, *.ew, *.ex, *.exu, *.exw *.E, *.EU, *.EW, *.EX, *.EXU, *.EXW -To select syntax highlighting file for Euphoria, as well as for +To select syntax highlighting file for Euphoria, as well as for auto-detecting the *.e and *.E file extensions as Euphoria file type, add the following line to your startup file: > :let filetype_euphoria="euphoria3" - or + or :let filetype_euphoria="euphoria4" @@ -1656,8 +1710,8 @@ The coloring scheme for tags in the HTML file works as follows. The <> of opening tags are colored differently than the </> of a closing tag. This is on purpose! For opening tags the 'Function' color is used, while for -closing tags the 'Type' color is used (See syntax.vim to check how those are -defined for you) +closing tags the 'Identifier' color is used (See syntax.vim to check how those +are defined for you) Known tag names are colored the same way as statements in C. Unknown tag names are colored with the same color as the <> or </> respectively which @@ -1852,7 +1906,7 @@ new highlightings for the following groups.: Debug, DebugSpecial, DebugString, DebugBoolean, DebugType which are used for the statement itself, special characters used in debug strings, strings, boolean constants and types (this, super) respectively. I -have opted to chose another background for those statements. +have opted to choose another background for those statements. Javadoc is a program that takes special comments out of Java program files and creates HTML pages. The standard configuration will highlight this HTML code @@ -1892,6 +1946,16 @@ displayed line. The default value is 10. The disadvantage of using a larger number is that redrawing can become slow. +JSON *json.vim* *ft-json-syntax* + +The json syntax file provides syntax highlighting with conceal support by +default. To disable concealment: > + let g:vim_json_conceal = 0 + +To disable syntax highlighting of errors: > + let g:vim_json_warnings = 0 + + LACE *lace.vim* *ft-lace-syntax* Lace (Language for Assembly of Classes in Eiffel) is case insensitive, but the @@ -2141,9 +2205,10 @@ can use them. For example, Linux and BSD distributions use groff as their default text processing package. In order to activate the extra syntax highlighting -features for groff, add the following option to your start-up files: > +features for groff, arrange for files to be recognized as groff (see +|ft-groff-syntax|) or add the following option to your start-up files: > - :let b:nroff_is_groff = 1 + :let nroff_is_groff = 1 Groff is different from the old AT&T n/troff that you may still find in Solaris. Groff macro and request names can be longer than 2 characters and @@ -2221,7 +2286,7 @@ contain very long structures that Vim does not synchronize anymore. PAPP *papp.vim* *ft-papp-syntax* -The PApp syntax file handles .papp files and, to a lesser extend, .pxml +The PApp syntax file handles .papp files and, to a lesser extent, .pxml and .pxsl files which are all a mixture of perl/xml/html/other using xml as the top-level file format. By default everything inside phtml or pxml sections is treated as a string with embedded preprocessor commands. If @@ -2239,11 +2304,12 @@ http://papp.plan9.de. PASCAL *pascal.vim* *ft-pascal-syntax* -Files matching "*.p" could be Progress or Pascal. If the automatic detection -doesn't work for you, or you don't edit Progress at all, use this in your -startup vimrc: > +Files matching "*.p" could be Progress or Pascal and those matching "*.pp" +could be Puppet or Pascal. If the automatic detection doesn't work for you, +or you only edit Pascal files, use this in your startup vimrc: > - :let filetype_p = "pascal" + :let filetype_p = "pascal" + :let filetype_pp = "pascal" The Pascal syntax file has been extended to take into account some extensions provided by Turbo Pascal, Free Pascal Compiler and GNU Pascal Compiler. @@ -2593,12 +2659,12 @@ Note: only existence of these options matter, not their value. You can replace QUAKE *quake.vim* *ft-quake-syntax* -The Quake syntax definition should work for most any FPS (First Person -Shooter) based on one of the Quake engines. However, the command names vary -a bit between the three games (Quake, Quake 2, and Quake 3 Arena) so the -syntax definition checks for the existence of three global variables to allow -users to specify what commands are legal in their files. The three variables -can be set for the following effects: +The Quake syntax definition should work for most FPS (First Person Shooter) +based on one of the Quake engines. However, the command names vary a bit +between the three games (Quake, Quake 2, and Quake 3 Arena) so the syntax +definition checks for the existence of three global variables to allow users +to specify what commands are legal in their files. The three variables can +be set for the following effects: set to highlight commands only available in Quake: > :let quake_is_quake1 = 1 @@ -2667,6 +2733,13 @@ This will add highlighting for the commands that BASH (version 2.05a and later, and part earlier) adds. +REGO *rego.vim* *ft-rego-syntax* + +Rego is a query language developed by Styra. It is mostly used as a policy +language for kubernetes, but can be applied to almost anything. Files with +the following extensions are recognized as rego files: .rego. + + RESTRUCTURED TEXT *rst.vim* *ft-rst-syntax* Syntax highlighting is enabled for code blocks within the document for a @@ -2679,10 +2752,10 @@ To set a user-defined list of code block syntax highlighting: > To assign multiple code block types to a single syntax, define `rst_syntax_code_list` as a mapping: > let rst_syntax_code_list = { - \ 'cpp' = ['cpp', 'c++'], - \ 'bash' = ['bash', 'sh'], + \ 'cpp': ['cpp', 'c++'], + \ 'bash': ['bash', 'sh'], ... - } + \ } To use color highlighting for emphasis text: > let rst_use_emphasis_colors = 1 @@ -2903,7 +2976,7 @@ vimrc file: > (Adapted from the html.vim help text by Claudio Fleiner <claudio@fleiner.com>) - *ft-posix-synax* *ft-dash-syntax* + *ft-posix-syntax* *ft-dash-syntax* SH *sh.vim* *ft-sh-syntax* *ft-bash-syntax* *ft-ksh-syntax* This covers syntax highlighting for the older Unix (Bourne) sh, and newer @@ -2927,7 +3000,7 @@ variables in your vimrc: ksh: > let g:is_kornshell = 1 -< posix: (using this is the nearly the same as setting g:is_kornshell to 1) > +< posix: (using this is nearly the same as setting g:is_kornshell to 1) > let g:is_posix = 1 < bash: > let g:is_bash = 1 @@ -3080,6 +3153,7 @@ redrawing can become slow. TEX *tex.vim* *ft-tex-syntax* *latex-syntax* + *syntax-tex* *syntax-latex* Tex Contents~ Tex: Want Syntax Folding? |tex-folding| @@ -3096,6 +3170,7 @@ TEX *tex.vim* *ft-tex-syntax* *latex-syntax* Tex: Selective Conceal Mode |g:tex_conceal| Tex: Controlling iskeyword |g:tex_isk| Tex: Fine Subscript and Superscript Control |tex-supersub| + Tex: Match Check Control |tex-matchcheck| *tex-folding* *g:tex_fold_enabled* Tex: Want Syntax Folding? ~ @@ -3316,9 +3391,25 @@ syntax highlighting script handles this with the following logic: For example, I use Luxi Mono Bold; it doesn't support subscript characters for "hklmnpst", so I put > let g:tex_subscripts= "[0-9aeijoruvx,+-/().]" -< in ~/.config/nvim/ftplugin/tex/tex.vim in order to avoid having +< in ~/.config/nvim/ftplugin/tex/tex.vim in order to avoid having inscrutable utf-8 glyphs appear. + *tex-matchcheck* *g:tex_matchcheck* + Tex: Match Check Control~ + + Sometimes one actually wants mismatched parentheses, square braces, + and or curly braces; for example, \text{(1,10] is a range from but + not including 1 to and including 10}. This wish, of course, conflicts + with the desire to provide delimiter mismatch detection. To + accommodate these conflicting goals, syntax/tex.vim provides > + g:tex_matchcheck = '[({[]' +< which is shown along with its default setting. So, if one doesn't + want [] and () to be checked for mismatches, try using > + let g:tex_matchcheck= '[{}]' +< If you don't want matching to occur inside bold and italicized + regions, > + let g:tex_excludematcher= 1 +< will prevent the texMatcher group from being included in those regions. TF *tf.vim* *ft-tf-syntax* @@ -3430,26 +3521,26 @@ It will look much better with a font in a quadratic cell size, e.g. for X: > YAML *yaml.vim* *ft-yaml-syntax* *g:yaml_schema* *b:yaml_schema* -A YAML schema is a combination of a set of tags and a mechanism for resolving -non-specific tags. For user this means that YAML parser may, depending on -plain scalar contents, treat plain scalar (which can actually be only string -and nothing else) as a value of the other type: null, boolean, floating-point, -integer. `g:yaml_schema` option determines according to which schema values +A YAML schema is a combination of a set of tags and a mechanism for resolving +non-specific tags. For user this means that YAML parser may, depending on +plain scalar contents, treat plain scalar (which can actually be only string +and nothing else) as a value of the other type: null, boolean, floating-point, +integer. `g:yaml_schema` option determines according to which schema values will be highlighted specially. Supported schemas are Schema Description ~ failsafe No additional highlighting. json Supports JSON-style numbers, booleans and null. core Supports more number, boolean and null styles. -pyyaml In addition to core schema supports highlighting timestamps, - but there are some differences in what is recognized as - numbers and many additional boolean values not present in core +pyyaml In addition to core schema supports highlighting timestamps, + but there are some differences in what is recognized as + numbers and many additional boolean values not present in core schema. Default schema is `core`. -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 +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. @@ -3532,7 +3623,7 @@ DEFINING FOLDLEVEL *:syn-foldlevel* start: Use level of item containing start of line. minimum: Use lowest local-minimum level of items on line. - The default is 'start'. Use 'minimum' to search a line horizontally + The default is "start". Use "minimum" to search a line horizontally for the lowest level contained on the line that is followed by a higher level. This produces more natural folds when syntax items may close and open horizontally within a line. @@ -3569,7 +3660,7 @@ SYNTAX ISKEYWORD SETTING *:syn-iskeyword* 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. + {option} Set the syntax 'iskeyword' option to a new value. Example: > :syntax iskeyword @,48-57,192-255,$,_ @@ -3677,9 +3768,9 @@ DEFINING REGIONS *:syn-region* *:syn-start* *:syn-skip* *:syn-end* [keepend] [extend] [excludenl] - start={start_pattern} .. - [skip={skip_pattern}] - end={end_pattern} .. + start={start-pattern} .. + [skip={skip-pattern}] + end={end-pattern} .. [{options}] This defines one region. It may span several lines. @@ -3701,12 +3792,12 @@ DEFINING REGIONS *:syn-region* *:syn-start* *:syn-skip* *:syn-end* extend a containing match or item. Only useful for end patterns. Must be given before the patterns it applies to. |:syn-excludenl| - start={start_pattern} The search pattern that defines the start of + start={start-pattern} The search pattern that defines the start of the region. See |:syn-pattern| below. - skip={skip_pattern} The search pattern that defines text inside + skip={skip-pattern} The search pattern that defines text inside the region where not to look for the end pattern. See |:syn-pattern| below. - end={end_pattern} The search pattern that defines the end of + end={end-pattern} The search pattern that defines the end of the region. See |:syn-pattern| below. Example: > @@ -4229,7 +4320,7 @@ Notes: - A negative offset for an end pattern may not always work, because the end pattern may be detected when the highlighting should already have stopped. - Before Vim 7.2 the offsets were counted in bytes instead of characters. - This didn't work well for multi-byte characters, so it was changed with the + This didn't work well for multibyte characters, so it was changed with the Vim 7.2 release. - The start of a match cannot be in a line other than where the pattern matched. This doesn't work: "a\nb"ms=e. You can make the highlighting @@ -4417,8 +4508,8 @@ two different ways: (e.g., "syntax/pod.vim") the file is searched for in 'runtimepath'. All matching files are loaded. Using a relative path is recommended, because it allows a user to replace the included file - with his own version, without replacing the file that does the ":syn - include". + with their own version, without replacing the file that does the + ":syn include". *E847* The maximum number of includes is 999. @@ -4538,7 +4629,7 @@ matches, nextgroup, etc. But there are a few differences: - A line continuation pattern can be given. It is used to decide which group of lines need to be searched like they were one line. This means that the search for a match with the specified items starts in the first of the - consecutive that contain the continuation pattern. + consecutive lines that contain the continuation pattern. - When using "nextgroup" or "contains", this only works within one line (or group of continued lines). - When using a region, it must start and end in the same line (or group of @@ -4850,8 +4941,8 @@ ctermbg={color-nr} *highlight-ctermbg* *E419* *E420* When Vim knows the normal foreground and background colors, "fg" and "bg" can be used as color names. This only works after setting the - colors for the Normal group and for the Windows console. Example, for - reverse video: > + colors for the Normal group and for the MS-Windows console. Example, + for reverse video: > :highlight Visual ctermfg=bg ctermbg=fg < Note that the colors are used that are valid at the moment this command are given. If the Normal group colors are changed later, the @@ -5002,9 +5093,9 @@ MsgSeparator Separator for scrolled messages, `msgsep` flag of 'display' *hl-MoreMsg* MoreMsg |more-prompt| *hl-NonText* -NonText '@' at the end of the window, characters from 'showbreak' - and other characters that do not really exist in the text - (e.g., ">" displayed when a double-wide character doesn't +NonText '@' at the end of the window, characters from 'showbreak' + and other characters that do not really exist in the text + (e.g., ">" displayed when a double-wide character doesn't fit at the end of the line). See also |hl-EndOfBuffer|. *hl-Normal* Normal normal text @@ -5131,6 +5222,12 @@ If you like Question highlighting for C comments, put this in your vimrc file: > Without the "default" in the C syntax file, the highlighting would be overruled when the syntax file is loaded. +To have a link survive `:highlight clear`, which is useful if you have +highlighting for a specific filetype and you want to keep it when selecting +another color scheme, put a command like this in the +"after/syntax/{filetype}.vim" file: > + highlight! default link cComment Question + ============================================================================== 15. Cleaning up *:syn-clear* *E391* @@ -5191,7 +5288,7 @@ script file to set these colors. Put this file in a directory in the default colors. This way these colors will be used after the ":syntax reset" command. -For Unix you can use the file ~/.config/nvim/after/syntax/syncolor.vim. +For Unix you can use the file ~/.config/nvim/after/syntax/syncolor.vim. Example: > if &background == "light" diff --git a/runtime/doc/tabpage.txt b/runtime/doc/tabpage.txt index 1407fdd968..7f91fda9f4 100644 --- a/runtime/doc/tabpage.txt +++ b/runtime/doc/tabpage.txt @@ -129,7 +129,7 @@ something else. :+tabclose " close the next tab page :1tabclose " close the first tab page :$tabclose " close the last tab page - :tabclose -2 " close the two previous tab page + :tabclose -2 " close the 2nd previous tab page :tabclose + " close the next tab page :tabclose 3 " close the third tab page :tabclose $ " close the last tab page diff --git a/runtime/doc/tagsrch.txt b/runtime/doc/tagsrch.txt index 7d09ca86ac..2c1b927e5a 100644 --- a/runtime/doc/tagsrch.txt +++ b/runtime/doc/tagsrch.txt @@ -179,6 +179,29 @@ commands explained above the tag stack will look like this: The |gettagstack()| function returns the tag stack of a specified window. The |settagstack()| function modifies the tag stack of a window. + *tagstack-examples* +Write to the tag stack just like `:tag` but with a user-defined +jumper#jump_to_tag function: > + " Store where we're jumping from before we jump. + let tag = expand('<cword>') + let pos = [bufnr()] + getcurpos()[1:] + let item = {'bufnr': pos[0], 'from': pos, 'tagname': tag} + if jumper#jump_to_tag(tag) + " Jump was successful, write previous location to tag stack. + let winid = win_getid() + let stack = gettagstack(winid) + let stack['items'] = [item] + call settagstack(winid, stack, 't') + endif +< +Set current index of the tag stack to 4: > + call settagstack(1005, {'curidx' : 4}) +< +Push a new item onto the tag stack: > + let pos = [bufnr('myfile.txt'), 10, 1, 0] + let newtag = [{'tagname' : 'mytag', 'from' : pos}] + call settagstack(2, {'items' : newtag}, 'a') +< *E73* When you try to use the tag stack while it doesn't contain anything you will get an error message. @@ -204,14 +227,14 @@ the same entry. Example output: > - nr pri kind tag file + # pri kind tag file 1 F f mch_delay os_amiga.c mch_delay(msec, ignoreinput) > 2 F f mch_delay os_msdos.c mch_delay(msec, ignoreinput) 3 F f mch_delay os_unix.c mch_delay(msec, ignoreinput) - Enter nr of choice (<CR> to abort): + Type number and <Enter> (empty cancels): < See |tag-priority| for the "pri" column. Note that this depends on the current file, thus using @@ -488,10 +511,13 @@ a tag for each "#defined" macro, typedefs, enums, etc. Some programs that generate tags files: ctags As found on most Unix systems. Only supports C. Only does the basic work. +universal ctags A maintained version of ctags based on exuberant + ctags. See https://ctags.io. *Exuberant_ctags* exuberant ctags This is a very good one. It works for C, C++, Java, Fortran, Eiffel and others. It can generate tags for many items. See http://ctags.sourceforge.net. + No new version since 2009. JTags For Java, in Java. It can be found at http://www.fleiner.com/jtags/. ptags.py For Python, in Python. Found in your Python source @@ -513,7 +539,7 @@ The first format is a normal tag, which is completely compatible with Vi. It is the only format produced by traditional ctags implementations. This is often used for functions that are global, also referenced in other files. -The lines in the tags file can end in <LF> or <CR><LF>. On the Macintosh <CR> +The lines in the tags file can end in <NL> or <CR><NL>. On the Macintosh <CR> also works. The <CR> and <NL> characters can never appear inside a line. The second format is new. It includes additional information in optional @@ -893,8 +919,8 @@ The following is a hypothetical example of a function used for 'tagfunc'. It uses the output of |taglist()| to generate the result: a list of tags in the inverse order of file names. > - function! TagFunc(pattern, flags, info) - function! CompareFilenames(item1, item2) + function TagFunc(pattern, flags, info) + function CompareFilenames(item1, item2) let f1 = a:item1['filename'] let f2 = a:item2['filename'] return f1 >=# f2 ? diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt index 6a271c08d3..935d958729 100644 --- a/runtime/doc/term.txt +++ b/runtime/doc/term.txt @@ -289,7 +289,7 @@ border, the text is scrolled. A selection can be started by pressing the left mouse button on the first character, moving the mouse to the last character, then releasing the mouse button. You will not always see the selection until you release the button, -only in some versions (GUI, Windows) will the dragging be shown immediately. +only in some versions (GUI, Win32) will the dragging be shown immediately. Note that you can make the text scroll by moving the mouse at least one character in the first/last line in the window when 'scrolloff' is non-zero. @@ -306,7 +306,7 @@ alt key is pressed (it may move the window). *double-click* Double, triple and quadruple clicks are supported when the GUI is active, for -Windows and for an xterm. For selecting text, extra clicks extend the +Win32 and for an xterm. For selecting text, extra clicks extend the selection: click select ~ double word or % match *<2-LeftMouse>* @@ -318,9 +318,8 @@ A double click on a word selects that word. 'iskeyword' is used to specify which characters are included in a word. A double click on a character that has a match selects until that match (like using "v%"). If the match is an #if/#else/#endif block, the selection becomes linewise. -For MS-DOS and xterm the time for double clicking can be set with the -'mousetime' option. For the other systems this time is defined outside of -Vim. +For MS-Windows and xterm the time for double clicking can be set with the +'mousetime' option. For the other systems this time is defined outside of Vim. An example, for using a double click to jump to the tag under the cursor: > :map <2-LeftMouse> :exe "tag ". expand("<cword>")<CR> diff --git a/runtime/doc/testing.txt b/runtime/doc/testing.txt new file mode 100644 index 0000000000..b2ce6d670d --- /dev/null +++ b/runtime/doc/testing.txt @@ -0,0 +1,169 @@ +*testing.txt* Nvim + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Testing Vim and Vim script *testing-support* + +Expression evaluation is explained in |eval.txt|. This file goes into details +about writing tests in Vim script. This can be used for testing Vim itself +and for testing plugins. + +1. Testing Vim |testing| +2. Test functions |test-functions-details| +3. Assert funtions |assert-functions-details| + +============================================================================== +1. Testing Vim *testing* + +Vim can be tested after building it, usually with "make test". +The tests are located in the directory "src/testdir". + +There are several types of tests added over time: + test33.in oldest, don't add any of these + test_something.in old style tests + test_something.vim new style tests + + *new-style-testing* +New tests should be added as new style tests. These use functions such as +|assert_equal()| to keep the test commands and the expected result in one +place. + *old-style-testing* +In some cases an old style test needs to be used. E.g. when testing Vim +without the |+eval| feature. + +Find more information in the file src/testdir/README.txt. + +============================================================================== +2. Test functions *test-functions-details* + +test_garbagecollect_now() *test_garbagecollect_now()* + Like garbagecollect(), but executed right away. This must + only be called directly to avoid any structure to exist + internally, and |v:testing| must have been set before calling + any function. + +============================================================================== +3. Assert functions *assert-functions-details* + + +assert_beeps({cmd}) *assert_beeps()* + Run {cmd} and add an error message to |v:errors| if it does + NOT produce a beep or visual bell. + Also see |assert_fails()|, |assert_nobeep()| and + |assert-return|. + + *assert_equal()* +assert_equal({expected}, {actual} [, {msg}]) + When {expected} and {actual} are not equal an error message is + added to |v:errors| and 1 is returned. Otherwise zero is + returned |assert-return|. + There is no automatic conversion, the String "4" is different + from the Number 4. And the number 4 is different from the + Float 4.0. The value of 'ignorecase' is not used here, case + always matters. + When {msg} is omitted an error in the form "Expected + {expected} but got {actual}" is produced. + Example: > + assert_equal('foo', 'bar') +< Will result in a string to be added to |v:errors|: + test.vim line 12: Expected 'foo' but got 'bar' ~ + + *assert_equalfile()* +assert_equalfile({fname-one}, {fname-two}) + When the files {fname-one} and {fname-two} do not contain + exactly the same text an error message is added to |v:errors|. + Also see |assert-return|. + When {fname-one} or {fname-two} does not exist the error will + mention that. + +assert_exception({error} [, {msg}]) *assert_exception()* + When v:exception does not contain the string {error} an error + message is added to |v:errors|. Also see |assert-return|. + This can be used to assert that a command throws an exception. + Using the error number, followed by a colon, avoids problems + with translations: > + try + commandthatfails + call assert_false(1, 'command should have failed') + catch + call assert_exception('E492:') + endtry + +assert_fails({cmd} [, {error} [, {msg}]]) *assert_fails()* + Run {cmd} and add an error message to |v:errors| if it does + NOT produce an error. Also see |assert-return|. + When {error} is given it must match in |v:errmsg|. + Note that beeping is not considered an error, and some failing + commands only beep. Use |assert_beeps()| for those. + +assert_false({actual} [, {msg}]) *assert_false()* + When {actual} is not false an error message is added to + |v:errors|, like with |assert_equal()|. + Also see |assert-return|. + A value is false when it is zero. When {actual} is not a + number the assert fails. + When {msg} is omitted an error in the form + "Expected False but got {actual}" is produced. + +assert_inrange({lower}, {upper}, {actual} [, {msg}]) *assert_inrange()* + This asserts number and |Float| values. When {actual} is lower + than {lower} or higher than {upper} an error message is added + to |v:errors|. Also see |assert-return|. + When {msg} is omitted an error in the form + "Expected range {lower} - {upper}, 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|. Also see |assert-return|. + + {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_nobeep({cmd}) *assert_nobeep()* + Run {cmd} and add an error message to |v:errors| if it + produces a beep or visual bell. + Also see |assert_beeps()|. + + *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. + Also see |assert-return|. + + *assert_notmatch()* +assert_notmatch({pattern}, {actual} [, {msg}]) + The opposite of `assert_match()`: add an error message to + |v:errors| when {pattern} matches {actual}. + Also see |assert-return|. + +assert_report({msg}) *assert_report()* + Report a test failure directly, using {msg}. + Always returns one. + +assert_true({actual} [, {msg}]) *assert_true()* + When {actual} is not true an error message is added to + |v:errors|, like with |assert_equal()|. + Also see |assert-return|. + A value is |TRUE| when it is a non-zero number or |v:true|. + When {actual} is not a number or |v:true| the assert fails. + When {msg} is omitted an error in the form "Expected True but + got {actual}" is produced. + + + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/tips.txt b/runtime/doc/tips.txt index 1362b730b7..bcb2e48cbf 100644 --- a/runtime/doc/tips.txt +++ b/runtime/doc/tips.txt @@ -446,4 +446,28 @@ A slightly more advanced version is used in the |matchparen| plugin. autocmd InsertEnter * match none < +============================================================================== +Opening help in the current window *help-curwin* + +By default, help is displayed in a split window. If you prefer it opens in +the current window, try this custom `:HelpCurwin` command: +> + command -bar -nargs=? -complete=help HelpCurwin execute s:HelpCurwin(<q-args>) + let s:did_open_help = v:false + + function s:HelpCurwin(subject) abort + let mods = 'silent noautocmd keepalt' + if !s:did_open_help + execute mods .. ' help' + execute mods .. ' helpclose' + let s:did_open_help = v:true + endif + if !getcompletion(a:subject, 'help')->empty() + execute mods .. ' edit ' .. &helpfile + endif + return 'help ' .. a:subject + endfunction +< + + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/uganda.txt b/runtime/doc/uganda.txt index 97a67befb9..79519da51e 100644 --- a/runtime/doc/uganda.txt +++ b/runtime/doc/uganda.txt @@ -212,7 +212,7 @@ Check the ICCF web site for the latest information! See |iccf| for the URL. USA: The methods mentioned below can be used. Sending a check to the Nehemiah Group Outreach Society (NGOS) is no longer possible, unfortunately. We are looking for - another way to get you an IRS tax receipt. + another way to get you an IRS tax receipt. For sponsoring a child contact KCF in Canada (see below). US checks can be sent to them to lower banking costs. diff --git a/runtime/doc/undo.txt b/runtime/doc/undo.txt index a500e87e35..b11d7581ed 100644 --- a/runtime/doc/undo.txt +++ b/runtime/doc/undo.txt @@ -60,9 +60,9 @@ with the redo command. If you make a new change after the undo command, the redo will not be possible anymore. 'u' included, the Vi-compatible way: -The undo command undoes the previous change, and also the previous undo command. -The redo command repeats the previous undo command. It does NOT repeat a -change command, use "." for that. +The undo command undoes the previous change, and also the previous undo +command. The redo command repeats the previous undo command. It does NOT +repeat a change command, use "." for that. Examples Vim way Vi-compatible way ~ "uu" two times undo no-op @@ -98,7 +98,7 @@ change again. But you can do something like this: > :undojoin | delete -After this an "u" command will undo the delete command and the previous +After this a "u" command will undo the delete command and the previous change. To do the opposite, break a change into two undo blocks, in Insert mode use @@ -257,7 +257,7 @@ respectively: (the magic number at the start of the file is wrong), then this fails, unless the ! was added. If it exists and does look like an undo file it is - overwritten. If there is no undo-history, nothing will be + overwritten. If there is no undo-history, nothing will be written. Implementation detail: Overwriting happens by first deleting the existing file and then creating a new file with the same @@ -371,7 +371,7 @@ back the text of three deletes ago with '"3P'. *redo-register* If you want to get back more than one part of deleted text, you can use a special feature of the repeat command ".". It will increase the number of the -register used. So if you first do ""1P", the following "." will result in a +register used. So if you first do '"1P', the following "." will result in a '"2P'. Repeating this will result in all numbered registers being inserted. Example: If you deleted text with 'dd....' it can be restored with diff --git a/runtime/doc/usr_01.txt b/runtime/doc/usr_01.txt index 3deaf181e5..52fbf06ec4 100644 --- a/runtime/doc/usr_01.txt +++ b/runtime/doc/usr_01.txt @@ -41,11 +41,11 @@ the commands and options used for it. Use these two commands: Press CTRL-O to jump back (repeat to go further back). Many links are in vertical bars, like this: |bars|. The bars themselves may -be hidden or invisible, see below. An option name, like 'number', a command +be hidden or invisible; see below. An option name, like 'number', a command in double quotes like ":write" and any other word can also be used as a link. Try it out: Move the cursor to CTRL-] and press CTRL-] on it. -Other subjects can be found with the ":help" command, see |help.txt|. +Other subjects can be found with the ":help" command; see |help.txt|. The bars and stars are usually hidden with the |conceal| feature. They also use |hl-Ignore|, using the same color for the text as the background. You can @@ -69,7 +69,7 @@ For more info see |vimrc|. *01.3* Using the Vim tutor *tutor* *vimtutor* Instead of reading the text (boring!) you can use :Tutor to learn your first -Vim commands. This is a 30 minute tutorial that teaches the most basic Vim +Vim commands. This is a 30-minute tutorial that teaches the most basic Vim functionality hands-on. To start the tutorial, execute > diff --git a/runtime/doc/usr_02.txt b/runtime/doc/usr_02.txt index c8fd7c3e35..f822e7d4b8 100644 --- a/runtime/doc/usr_02.txt +++ b/runtime/doc/usr_02.txt @@ -29,8 +29,8 @@ To start Vim, enter this command: > gvim file.txt -On Unix you can type this at any command prompt. If you are running Windows, -open a command prompt window and enter the command. In either case, Vim +On Unix you can type this at any command prompt. If you are running Microsoft +Windows, open a Command Prompt and enter the command. In either case, Vim starts editing a file called file.txt. Because this is a new file, you get a blank window. This is what your screen will look like: @@ -42,7 +42,7 @@ blank window. This is what your screen will look like: |~ | |"file.txt" [New file] | +---------------------------------------+ - ('#" is the cursor position.) + ('#' is the cursor position.) The tilde (~) lines indicate lines not in the file. In other words, when Vim runs out of file to display, it displays tilde lines. At the bottom of the @@ -253,11 +253,11 @@ restores the character. g intelligent turtle ~ -The next u command restores the next-to-last character deleted: +The next "u" command restores the next-to-last character deleted: ng intelligent turtle ~ -The next u command gives you the u, and so on: +The next "u" command gives you the u, and so on: ung intelligent turtle ~ oung intelligent turtle ~ @@ -364,7 +364,7 @@ To exit, use the "ZZ" command. This command writes the file and exits. Unlike many other editors, Vim does not automatically make a backup file. If you type "ZZ", your changes are committed and there's no turning back. You can configure the Vim editor to produce backup - files, see |07.4|. + files; see |07.4|. DISCARDING CHANGES @@ -387,7 +387,7 @@ message and refuse to exit: E37: No write since last change (use ! to override) ~ By specifying the override, you are in effect telling Vim, "I know that what -I'm doing looks stupid, but I'm a big boy and really want to do this." +I'm doing looks stupid, but I really want to do this." If you want to continue editing with Vim: The ":e!" command reloads the original version of the file. @@ -499,14 +499,14 @@ Summary: *help-summary* > 1) Use Ctrl-D after typing a topic and let Vim show all available topics. Or press Tab to complete: > - :help some<Tab> + :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 + :help pattern.txt < You can see the user guide topics |03.9| and |usr_27.txt| in the introduction. @@ -518,29 +518,29 @@ Summary: *help-summary* > < 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> + :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> + :help cpo-; +< And for the 'guioptions' 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 + :help gt 5) Insert mode commands start with i_. Help for deleting a word: > - :help i_CTRL-W + :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 + :help v_o 7) Command line editing and arguments start with c_. Help for using the command argument %: > - :help c_% + :help c_% -8) Ex-commands always start with ":", so to go to the :s command help: > +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 the help @@ -549,55 +549,56 @@ Summary: *help-summary* > 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 + :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 + :help CTRL-W < In contrast > :help c_CTRL-R -< will describe what the Ctrl-R does when entering commands in the Command +< will describe what the CTRL-R does when entering commands in the Command line and > - :help v_Ctrl-A + :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" +< talks about the "g<C-A>" command (e.g. you have to press "g" then + <CTRL-A>). Here the "g" stands 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 /\+ + :help /\+ < If you need to know everything about regular expressions, start reading at: > - :help pattern.txt + :help pattern.txt 12) Registers always start with "quote". To find out about the special ":" register: > - :help quote: + :help quote: 13) Vim Script 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. + :help expr-! +< will take you to the topic describing the "!" (Not) operator for Vim + Script. Also important is > - :help function-list + :help function-list < to find a short description of all functions available. Help topics for Vim script functions always include the "()", so: > - :help append() + :help append() < talks about the append Vim script 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 + :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 + :help :map-local < for buffer-local mappings or > :help map-bar < for how the '|' is handled in mappings. @@ -608,7 +609,7 @@ Summary: *help-summary* > 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 + :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 @@ -617,57 +618,58 @@ Summary: *help-summary* > 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 + :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 + :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 + :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 + :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. + :help 10.1 +< which 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 + :help hl-WarningMsg < talks about the WarningMsg highlighting group. -20) Syntax highlighting is namespaced to :syn-topic e.g. > +20) Syntax highlighting is namespaced to :syn-topic. E.g. > :help :syn-conceal -< talks about the conceal argument for the :syn command. +< 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 + :help BufWinLeave < To see all possible events: > :help events 23) Command-line switches always start with "-". So for the help of the -f command switch of Vim use: > - :help -f + :help -f 24) Optional features always start with "+". To find out about the conceal feature use: > - :help +conceal + :help +conceal 25) Documentation for included filetype specific functionality is usually available in the form ft-<filetype>-<functionality>. So > - :help ft-c-syntax + :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 + :help ft-php-omni < or filetype plugins > :help ft-tex-plugin < are available. @@ -677,9 +679,9 @@ Summary: *help-summary* > < 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 + Sometimes, however, those error codes are not described, but rather are listed at the Vim command that usually causes this. So: > - :help E128 + :help E128 < takes you to the |:function| command diff --git a/runtime/doc/usr_03.txt b/runtime/doc/usr_03.txt index 2649534900..74674fdb42 100644 --- a/runtime/doc/usr_03.txt +++ b/runtime/doc/usr_03.txt @@ -30,10 +30,11 @@ Table of contents: |usr_toc.txt| To move the cursor forward one word, use the "w" command. Like most Vim commands, you can use a numeric prefix to move past multiple words. For -example, "3w" moves three words. This figure shows how it works: +example, "3w" moves three words. This figure shows how it works (starting at +the position marked with "x"): This is a line with example text ~ - --->-->->-----------------> + x-->-->->-----------------> w w w 3w Notice that "w" moves to the start of the next word if it already is at the @@ -41,15 +42,15 @@ start of a word. The "b" command moves backward to the start of the previous word: This is a line with example text ~ - <----<--<-<---------<--- + <----<--<-<---------<--x b b b 2b b There is also the "e" command that moves to the next end of a word and "ge", which moves to the previous end of a word: This is a line with example text ~ - <- <--- -----> ----> - ge ge e e + <----<----x---->------------> + 2ge ge e 2e If you are at the last word of a line, the "w" command will take you to the first word in the next line. Thus you can use this to move through a @@ -81,13 +82,13 @@ The "$" command moves the cursor to the end of a line. If your keyboard has an <End> key it will do the same thing. The "^" command moves to the first non-blank character of the line. The "0" -command (zero) moves to the very first character of the line. The <Home> key -does the same thing. In a picture: +command (zero) moves to the very first character of the line, and the <Home> +key does the same thing. In a picture ("." indicates a space): ^ - <------------ + <-----------x .....This is a line with example text ~ - <----------------- ---------------> + <----------------x x--------------> 0 $ (the "....." indicates blanks here) @@ -222,7 +223,8 @@ you can see? This figure shows the three commands you can use: L --> | text sample text | +---------------------------+ -Hints: "H" stands for Home, "M" for Middle and "L" for Last. +Hints: "H" stands for Home, "M" for Middle and "L" for Last. Alternatively, +"H" for high, "M" for Middle and "L" for low. ============================================================================== *03.6* Telling where you are @@ -299,22 +301,22 @@ To scroll one line at a time use CTRL-E (scroll up) and CTRL-Y (scroll down). Think of CTRL-E to give you one line Extra. (If you use MS-Windows compatible key mappings CTRL-Y will redo a change instead of scroll.) -To scroll forward by a whole screen (except for two lines) use CTRL-F. The -other way is backward, CTRL-B is the command to use. Fortunately CTRL-F is -Forward and CTRL-B is Backward, that's easy to remember. +To scroll forward by a whole screen (except for two lines) use CTRL-F. To +scroll backwards, use CTRL-B. These should be easy to remember: F for +Forwards and B for Backwards. A common issue is that after moving down many lines with "j" your cursor is at the bottom of the screen. You would like to see the context of the line with the cursor. That's done with the "zz" command. +------------------+ +------------------+ - | some text | | some text | - | some text | | some text | - | some text | | some text | - | some text | zz --> | line with cursor | - | some text | | some text | - | some text | | some text | - | line with cursor | | some text | + | earlier text | | earlier text | + | earlier text | | earlier text | + | earlier text | | earlier text | + | earlier text | zz --> | line with cursor | + | earlier text | | later text | + | earlier text | | later text | + | line with cursor | | later text | +------------------+ +------------------+ The "zt" command puts the cursor line at the top, "zb" at the bottom. There @@ -346,7 +348,8 @@ to find the first #include after the cursor: > And then type "n" several times. You will move to each #include in the text. You can also use a count if you know which match you want. Thus "3n" finds -the third match. Using a count with "/" doesn't work. +the third match. You can also use a count with "/": "4/the" goes to the +fourth match of "the". The "?" command works like "/" but searches backwards: > @@ -354,7 +357,7 @@ The "?" command works like "/" but searches backwards: > The "N" command repeats the last search the opposite direction. Thus using "N" after a "/" command searches backwards, using "N" after "?" searches -forward. +forwards. IGNORING CASE @@ -458,8 +461,8 @@ essential ones: :set nowrapscan This stops the search at the end of the file. Or, when you are searching -backwards, at the start of the file. The 'wrapscan' option is on by default, -thus searching wraps around the end of the file. +backwards, it stops the search at the start of the file. The 'wrapscan' +option is on by default, thus searching wraps around the end of the file. > :set noincsearch @@ -481,7 +484,8 @@ Vim. Example: > Go:set hlsearch<Esc> "G" moves to the end of the file. "o" starts a new line, where you type the -":set" command. You end insert mode with <Esc>. Then write the file: > +":set" command. You end insert mode with <Esc>. Then write and close the +file: > ZZ @@ -495,8 +499,8 @@ Regular expressions are an extremely powerful and compact way to specify a search pattern. Unfortunately, this power comes at a price, because regular expressions are a bit tricky to specify. In this section we mention only a few essential ones. More about search -patterns and commands in chapter 27 |usr_27.txt|. You can find the full -explanation here: |pattern|. +patterns and commands can be found in chapter 27 |usr_27.txt|. You can find +the full explanation here: |pattern|. BEGINNING AND END OF A LINE @@ -522,9 +526,9 @@ And with "/^the" we find this one: the solder holding one of the chips melted and the ~ xxx -You can try searching with "/^the$", it will only match a single line -consisting of "the". White space does matter here, thus if a line contains a -space after the word, like "the ", the pattern will not match. +You can try searching with "/^the$"; it will only match a single line +consisting entirely of "the". White space does matter here, thus if a line +contains a space after the word, like "the ", the pattern will not match. MATCHING ANY SINGLE CHARACTER @@ -559,20 +563,20 @@ where you came from, use this command: > This ` is a backtick or open single-quote character. If you use the same command a second time you will jump back again. That's -because the ` command is a jump itself, and the position from before this jump -is remembered. +because the "`" command is a jump itself, and the position from before this +jump is remembered. Generally, every time you do a command that can move the cursor further than within the same line, this is called a jump. This includes the search commands "/" and "n" (it doesn't matter how far away the match is). But not the character searches with "fx" and "tx" or the word movements "w" and "e". - Also, "j" and "k" are not considered to be a jump. Even when you use a + Also, "j" and "k" are not considered to be a jump, even when you use a count to make them move the cursor quite a long way away. -The `` command jumps back and forth, between two points. The CTRL-O command +The "``" command jumps back and forth, between two points. The CTRL-O command jumps to older positions (Hint: O for older). CTRL-I then jumps back to newer -positions (Hint: I is just next to O on the keyboard). Consider this sequence -of commands: > +positions (Hint: for many common keyboard layouts, I is just next to O). +Consider this sequence of commands: > 33G /^The @@ -610,9 +614,9 @@ Thus to move to the a mark: > `a -The command 'mark (single quotation mark, or apostrophe) moves you to the -beginning of the line containing the mark. This differs from the `mark -command, which moves you to marked column. +The command "'mark" (single quotation mark, or apostrophe) moves you to the +beginning of the line containing the mark. This differs from the "`mark" +command, which also moves you to the marked column. The marks can be very useful when working on two related parts in a file. Suppose you have some text near the start of the file you need to look at, diff --git a/runtime/doc/usr_04.txt b/runtime/doc/usr_04.txt index a327a09a71..b2dd617542 100644 --- a/runtime/doc/usr_04.txt +++ b/runtime/doc/usr_04.txt @@ -33,7 +33,7 @@ using a count: "4x" deletes four characters. move word command. In fact, the "d" command may be followed by any motion command, and it deletes from the current location to the place where the cursor winds up. - The "4w" command, for example, moves the cursor over four words. The d4w + The "4w" command, for example, moves the cursor over four words. The "d4w" command deletes four words. To err is human. To really foul up you need a computer. ~ @@ -91,14 +91,14 @@ This "c2wbe<Esc>" contains these bits: be insert this text <Esc> back to Normal mode -If you have paid attention, you will have noticed something strange: The space -before "human" isn't deleted. There is a saying that for every problem there -is an answer that is simple, clear, and wrong. That is the case with the -example used here for the "cw" command. The c operator works just like the -d operator, with one exception: "cw". It actually works like "ce", change to -end of word. Thus the space after the word isn't included. This is an -exception that dates back to the old Vi. Since many people are used to it -now, the inconsistency has remained in Vim. +You will have noticed something strange: The space before "human" isn't +deleted. There is a saying that for every problem there is an answer that is +simple, clear, and wrong. That is the case with the example used here for the +"cw" command. The c operator works just like the d operator, with one +exception: "cw". It actually works like "ce", change to end of word. Thus +the space after the word isn't included. This is an exception that dates back +to the old Vi. Since many people are used to it now, the inconsistency has +remained in Vim. MORE CHANGES @@ -114,7 +114,7 @@ Insert mode and append new text. SHORTCUTS Some operator-motion commands are used so often that they have been given a -single letter command: +single-letter command: x stands for dl (delete character under the cursor) X stands for dh (delete character left of the cursor) @@ -138,6 +138,7 @@ REPLACING WITH ONE CHARACTER The "r" command is not an operator. It waits for you to type a character, and will replace the character under the cursor with it. You could do the same with "cl" or with the "s" command, but with "r" you don't have to press <Esc> +to get back out of insert mode. there is somerhing grong here ~ rT rt rw @@ -160,11 +161,11 @@ line break. ============================================================================== *04.3* Repeating a change -The "." command is one of the most simple yet powerful commands in Vim. It +The "." command is one of the simplest yet powerful commands in Vim. It repeats the last change. For instance, suppose you are editing an HTML file and want to delete all the <B> tags. You position the cursor on the first < and delete the <B> with the command "df>". You then go to the < of the next -</B> and kill it using the "." command. The "." command executes the last +</B> and delete it using the "." command. The "." command executes the last change command (in this case, "df>"). To delete another tag, position the cursor on the < and use the "." command. @@ -176,8 +177,8 @@ cursor on the < and use the "." command. f< find next < -------------> . repeat df> --> -The "." command works for all changes you make, except for the "u" (undo), -CTRL-R (redo) and commands that start with a colon (:). +The "." command works for all changes you make, except for "u" (undo), CTRL-R +(redo) and commands that start with a colon (:). Another example: You want to change the word "four" to "five". It appears several times in your text. You can do this quickly with this sequence of @@ -269,8 +270,8 @@ where they open a new line below or above the cursor. ============================================================================== *04.5* Moving text -When you delete something with the "d", "x", or another command, the text is -saved. You can paste it back by using the p command. (The Vim name for +When you delete something with "d", "x", or another command, the text is +saved. You can paste it back by using the "p" command. (The Vim name for this is put). Take a look at how this works. First you will delete an entire line, by putting the cursor on the line you want to delete and typing "dd". Now you @@ -362,11 +363,11 @@ Use "y$" to yank to the end of the line. If you are using the GUI version of Vim (gvim), you can find the "Copy" item in the "Edit" menu. First select some text with Visual mode, then use the -Edit/Copy menu. The selected text is now copied to the clipboard. You can -paste the text in other programs. In Vim itself too. +Edit/Copy menu item. The selected text is now copied to the clipboard. You +can paste the text in other programs. In Vim itself too. If you have copied text to the clipboard in another application, you can paste -it in Vim with the Edit/Paste menu. This works in Normal mode and Insert +it in Vim with the Edit/Paste menu item. This works in Normal mode and Insert mode. In Visual mode the selected text is replaced with the pasted text. The "Cut" menu item deletes the text before it's put on the clipboard. The @@ -385,7 +386,7 @@ To put text from the clipboard back into the text: > "*p This only works on versions of Vim that include clipboard support. More about -the clipboard in section |09.3| and here: |clipboard|. +the clipboard can be found in section |09.3| and here: |clipboard|. ============================================================================== *04.8* Text objects @@ -401,8 +402,8 @@ to do this: "daw". The "d" of "daw" is the delete operator. "aw" is a text object. Hint: "aw" stands for "A Word". Thus "daw" is "Delete A Word". To be precise, the white -space after the word is also deleted (the white space before the word at the -end of the line). +space after the word is also deleted (or the white space before the word if at +the end of the line). Using text objects is the third way to make changes in Vim. We already had operator-motion and Visual mode. Now we add operator-text object. @@ -429,11 +430,11 @@ sentence "Another line.": some text. ~ "cis" consists of the "c" (change) operator and the "is" text object. This -stands for "Inner Sentence". There is also the "as" (a sentence) object. The -difference is that "as" includes the white space after the sentence and "is" -doesn't. If you would delete a sentence, you want to delete the white space -at the same time, thus use "das". If you want to type new text the white -space can remain, thus you use "cis". +stands for "Inner Sentence". There is also the "as" ("A Sentence") object. +The difference is that "as" includes the white space after the sentence and +"is" doesn't. If you would delete a sentence, you want to delete the white +space at the same time, thus use "das". If you want to type new text the +white space can remain, thus you use "cis". You can also use text objects in Visual mode. It will include the text object in the Visual selection. Visual mode continues, thus you can do this several @@ -462,21 +463,21 @@ of characters to replace. It will not continue on the next line. You can switch between Insert mode and Replace mode with the <Insert> key. -When you use <BS> (backspace) to make correction, you will notice that the -old text is put back. Thus it works like an undo command for the last typed -character. +When you use <BS> (backspace) to make a correction, you will notice that the +old text is put back. Thus it works like an undo command for the previously +typed character. ============================================================================== *04.10* Conclusion The operators, movement commands and text objects give you the possibility to -make lots of combinations. Now that you know how it works, you can use N +make lots of combinations. Now that you know how they work, you can use N operators with M movement commands to make N * M commands! -You can find a list of operators here: |operator| +You can find a list of operators here: |operator|. For example, there are many other ways to delete pieces of text. Here are a -few often used ones: +few common ones: x delete character under the cursor (short for "dl") X delete character before the cursor (short for "dh") @@ -492,14 +493,14 @@ If you use "c" instead of "d" they become change commands. And with "y" you yank the text. And so forth. -There are a few often used commands to make changes that didn't fit somewhere +There are a few common commands to make changes that didn't fit somewhere else: - ~ change case of the character under the cursor, and move the + ~ Change case of the character under the cursor, and move the cursor to the next character. This is not an operator (unless 'tildeop' is set), thus you can't use it with a motion - command. It does work in Visual mode and changes case for - all the selected text then. + command. It does work in Visual mode, where it changes case + for all the selected text. I Start Insert mode after moving the cursor to the first non-blank in the line. diff --git a/runtime/doc/usr_05.txt b/runtime/doc/usr_05.txt index 70a0ad97c1..d8634ac6ed 100644 --- a/runtime/doc/usr_05.txt +++ b/runtime/doc/usr_05.txt @@ -45,8 +45,8 @@ This file is always used and is recommended: ~/AppData/Local/nvim/init.vim (Windows) ~ The vimrc file can contain all the commands that you type after a colon. The -most simple ones are for setting options. For example, if you want Vim to -always start with the 'ignorecase' option on, add this line your vimrc file: > +simplest ones are for setting options. For example, if you want Vim to always +start with the 'incsearch' option on, add this line your vimrc file: > set ignorecase diff --git a/runtime/doc/usr_07.txt b/runtime/doc/usr_07.txt index c44a54d76c..649be8d7ce 100644 --- a/runtime/doc/usr_07.txt +++ b/runtime/doc/usr_07.txt @@ -227,8 +227,8 @@ the file. FILE MARKS -In chapter 4 was explained how you can place a mark in a file with "mx" and -jump to that position with "`x". That works within one file. If you edit +In section |03.10| was explained how you can place a mark in a file with "mx" +and jump to that position with "`x". That works within one file. If you edit another file and place marks there, these are specific for that file. Thus each file has its own set of marks, they are local to the file. So far we were using marks with a lowercase letter. There are also marks diff --git a/runtime/doc/usr_08.txt b/runtime/doc/usr_08.txt index 559ca6f1ef..8e69307a94 100644 --- a/runtime/doc/usr_08.txt +++ b/runtime/doc/usr_08.txt @@ -401,7 +401,7 @@ Another way to start in diff mode can be done from inside Vim. Edit the "main.c" file, then make a split and show the differences: > :edit main.c - :vertical diffsplit main.c~ + :vertical diffsplit main.c~ The ":vertical" command is used to make the window split vertically. If you omit this, you will get a horizontal split. diff --git a/runtime/doc/usr_10.txt b/runtime/doc/usr_10.txt index 3646786052..5365f90314 100644 --- a/runtime/doc/usr_10.txt +++ b/runtime/doc/usr_10.txt @@ -370,7 +370,8 @@ into "barfoo". was specified in this example. This is different from ":substitute", which works on one line without a range. The command isn't perfect, since it also matches lines where "//" appears -halfway in a line, and the substitution will also take place before the "//". +halfway through a line, and the substitution will also take place before the +"//". Just like with ":substitute", any pattern can be used. When you learn more complicated patterns later, you can use them here. @@ -634,9 +635,9 @@ using it. To check the current value of 'textwidth': > :set textwidth Now lines will be broken to take only up to 78 characters. However, when you -insert text halfway through a line or delete a few words, the line will get -too long or too short as Vim won't automatically reformat the text. To tell -Vim to format the current paragraph: +insert text halfway through a line, or when you delete a few words, the lines +will get too long or too short. Vim doesn't automatically reformat the text. +To tell Vim to format the current paragraph: > gqap @@ -686,7 +687,7 @@ with any motion command, with text objects and in Visual mode. lowercase. This can be shortened to "guu". "gUgU" is shortened to "gUU" and "g~g~" to "g~~". Example: > - g~~ + g~~ < Some GIRLS have Fun ----> sOME girls HAVE fUN ~ ============================================================================== diff --git a/runtime/doc/usr_11.txt b/runtime/doc/usr_11.txt index c26f1e8f09..361fe51caa 100644 --- a/runtime/doc/usr_11.txt +++ b/runtime/doc/usr_11.txt @@ -211,8 +211,11 @@ will automatically delete it: - The flag that the file was modified is not set. - The process is not running. +You can programmatically deal with this situation with the |FileChangedShell| +autocommand event. -UNREADABLE SWAP FILE + +UNREADABLE SWAP FILE ~ Sometimes the line @@ -253,7 +256,7 @@ O Open the file readonly. Use this when you just want to view the file and E Edit the file anyway. Use this with caution! If the file is being edited in another Vim, you might end up with two versions of the file. Vim will - try to warn you when this happens, but better be safe then sorry. + try to warn you when this happens, but better be safe than sorry. R Recover the file from the swap file. Use this if you know that the swap file contains changes that you want to recover. @@ -290,7 +293,7 @@ machines. Therefore, don't rely on Vim always warning you. If you really don't want to see this message, you can add the 'A' flag to the 'shortmess' option. But it's very unusual that you need this. -For programatic access to the swap file, see |swapinfo()|. +For programmatic access to the swap file, see |swapinfo()|. ============================================================================== *11.4* Further reading diff --git a/runtime/doc/usr_12.txt b/runtime/doc/usr_12.txt index 21efa36a25..51a25b1593 100644 --- a/runtime/doc/usr_12.txt +++ b/runtime/doc/usr_12.txt @@ -180,14 +180,14 @@ after it. That way you don't have this problem again. The |:global| command can be combined with the |:move| command to move all the lines before the first line, resulting in a reversed file. The command is: > - :global/^/m 0 + :global/^/move 0 Abbreviated: > :g/^/m 0 The "^" regular expression matches the beginning of the line (even if the line -is blank). The |:move| command moves the matching line to after the mythical +is blank). The |:move| command moves the matching line to after the imaginary zeroth line, so the current matching line becomes the first line of the file. As the |:global| command is not confused by the changing line numbering, |:global| proceeds to match all remaining lines of the file and puts each as diff --git a/runtime/doc/usr_20.txt b/runtime/doc/usr_20.txt index 8eee7aedb7..29252705d6 100644 --- a/runtime/doc/usr_20.txt +++ b/runtime/doc/usr_20.txt @@ -327,10 +327,10 @@ for next. ============================================================================== *20.5* Command line window -Typing the text in the command line works different from typing text in Insert -mode. It doesn't allow many commands to change the text. For most commands -that's OK, but sometimes you have to type a complicated command. That's where -the command line window is useful. +Typing the text in the command line works differently from typing text in +Insert mode. It doesn't allow many commands to change the text. For most +commands that's OK, but sometimes you have to type a complicated command. +That's where the command line window is useful. Open the command line window with this command: > diff --git a/runtime/doc/usr_22.txt b/runtime/doc/usr_22.txt index 96fc02aaa5..56fe5ada2b 100644 --- a/runtime/doc/usr_22.txt +++ b/runtime/doc/usr_22.txt @@ -74,9 +74,9 @@ higher. Pressing "-" does the same thing, without the need to move to the You can press <F1> to get help on the things you can do in the netrw file browser. This is what you get: > - 9. Directory Browsing netrw-browse netrw-dir netrw-list netrw-help + 9. Directory Browsing netrw-browse netrw-dir netrw-list netrw-help - MAPS netrw-maps + MAPS netrw-maps <F1>.............Help.......................................|netrw-help| <cr>.............Browsing...................................|netrw-cr| <del>............Deleting Files or Directories..............|netrw-delete| @@ -84,7 +84,7 @@ browser. This is what you get: > a................Hiding Files or Directories................|netrw-a| mb...............Bookmarking a Directory....................|netrw-mb| gb...............Changing to a Bookmarked Directory.........|netrw-gb| - c................Make Browsing Directory The Current Dir....|netrw-c| + cd...............Make Browsing Directory The Current Dir....|netrw-c| d................Make A New Directory.......................|netrw-d| D................Deleting Files or Directories..............|netrw-D| <c-h>............Edit File/Directory Hiding List............|netrw-ctrl-h| @@ -121,7 +121,7 @@ The following normal-mode commands may be used to control the browser display: As a sampling of extra normal-mode commands: - c Change Vim's notion of the current directory to be + cd Change Vim's notion of the current directory to be the same as the browser directory. (see |g:netrw_keepdir| to control this, too) R Rename the file or directory under the cursor; a diff --git a/runtime/doc/usr_23.txt b/runtime/doc/usr_23.txt index 810da05ff8..2f88793db2 100644 --- a/runtime/doc/usr_23.txt +++ b/runtime/doc/usr_23.txt @@ -26,9 +26,9 @@ start a new line. One to move the carriage back to the first position (carriage return, <CR>), another to move the paper up (line feed, <LF>). When computers came out, storage was expensive. Some people decided that they did not need two characters for end-of-line. The Unix people decided -they could use <Line Feed> only for end-of-line. The Apple people -standardized on <CR>. The MS-DOS (and Microsoft Windows) folks decided to -keep the old <CR><LF>. +they could use <New Line> or <NL> only for end-of-line. The Apple people +standardized on <CR>. The Microsoft Windows folks decided to keep the old +<CR><NL> (we use <NL> for line feed in the help text). This means that if you try to move a file from one system to another, you have line-break problems. The Vim editor automatically recognizes the different file formats and handles things properly behind your back. @@ -53,20 +53,20 @@ which format you have, execute the following command: > The three names that Vim uses are: - unix <LF> - dos <CR><LF> + unix <NL> + dos <CR><NL> mac <CR> USING THE MAC FORMAT -On Unix, <LF> is used to break a line. It's not unusual to have a <CR> +On Unix, <NL> is used to break a line. It's not unusual to have a <CR> character halfway in a line. Incidentally, this happens quite often in Vi (and Vim) scripts. On the Macintosh, where <CR> is the line break character, it's possible to -have a <LF> character halfway in a line. +have a <NL> character halfway in a line. The result is that it's not possible to be 100% sure whether a file -containing both <CR> and <LF> characters is a Mac or a Unix file. Therefore, +containing both <CR> and <NL> characters is a Mac or a Unix file. Therefore, Vim assumes that on Unix you probably won't edit a Mac file, and doesn't check for this type of file. To check for this format anyway, add "mac" to 'fileformats': > diff --git a/runtime/doc/usr_24.txt b/runtime/doc/usr_24.txt index 3c4ff6f55e..efda2bc33d 100644 --- a/runtime/doc/usr_24.txt +++ b/runtime/doc/usr_24.txt @@ -563,9 +563,9 @@ that combination. Thus CTRL-K dP also works. Since there is no digraph for "dP" Vim will also search for a "Pd" digraph. Note: - The digraphs depend on the character set that Vim assumes you - are using. Always use ":digraphs" to find out which digraphs are - currently available. + The digraphs depend on the character set that Vim assumes you are + using. Always use ":digraphs" to find out which digraphs are currently + available. You can define your own digraphs. Example: > diff --git a/runtime/doc/usr_27.txt b/runtime/doc/usr_27.txt index 637523b9ee..230603de70 100644 --- a/runtime/doc/usr_27.txt +++ b/runtime/doc/usr_27.txt @@ -83,7 +83,7 @@ matter if 'ignorecase' or 'smartcase' was changed. Note: If your search takes much longer than you expected, you can interrupt - it with CTRL-C on Unix and CTRL-Break on Windows. + it with CTRL-C on Unix and CTRL-Break on MS-Windows. ============================================================================== *27.2* Wrapping around the file end @@ -434,7 +434,7 @@ redefined without changing the search pattern. /\f\+ -The "\f" items stands for file name characters. Thus this matches a sequence +The "\f" item stands for file name characters. Thus this matches a sequence of characters that can be a file name. Which characters can be part of a file name depends on the system you are using. On MS-Windows, the backslash is included, on Unix it is not. This is diff --git a/runtime/doc/usr_30.txt b/runtime/doc/usr_30.txt index b729c7a263..98d1780cc4 100644 --- a/runtime/doc/usr_30.txt +++ b/runtime/doc/usr_30.txt @@ -336,7 +336,7 @@ How to do that is explained here: |indent-expression|. ============================================================================== *30.4* Other indenting -The most simple form of automatic indenting is with the 'autoindent' option. +The simplest form of automatic indenting is with the 'autoindent' option. It uses the indent from the previous line. A bit smarter is the 'smartindent' option. This is useful for languages where no indent file is available. 'smartindent' is not as smart as 'cindent', but smarter than 'autoindent'. diff --git a/runtime/doc/usr_31.txt b/runtime/doc/usr_31.txt index 74de3f1042..a35f392324 100644 --- a/runtime/doc/usr_31.txt +++ b/runtime/doc/usr_31.txt @@ -198,9 +198,9 @@ is not possible in most terminals. You can start the X-Windows version of gvim with an argument to specify the size and position of the window: > - gvim -geometry {width}x{height}+{x_offset}+{y_offset} + gvim -geometry {width}x{height}+{x-offset}+{y-offset} -{width} and {height} are in characters, {x_offset} and {y_offset} are in +{width} and {height} are in characters, {x-offset} and {y-offset} are in pixels. Example: > gvim -geometry 80x25+100+300 diff --git a/runtime/doc/usr_40.txt b/runtime/doc/usr_40.txt index 9a1fe50f31..5b1254e2ae 100644 --- a/runtime/doc/usr_40.txt +++ b/runtime/doc/usr_40.txt @@ -453,12 +453,12 @@ matching BufWritePre autocommands and executes them, and then it performs the ":write". The general form of the :autocmd command is as follows: > - :autocmd [group] {events} {file_pattern} [++nested] {command} + :autocmd [group] {events} {file-pattern} [++nested] {command} The [group] name is optional. It is used in managing and calling the commands (more on this later). The {events} parameter is a list of events (comma separated) that trigger the command. - {file_pattern} is a filename, usually with wildcards. For example, using + {file-pattern} is a filename, usually with wildcards. For example, using "*.txt" makes the autocommand be used for all files whose name end in ".txt". The optional [++nested] flag allows for nesting of autocommands (see below), and finally, {command} is the command to be executed. @@ -489,7 +489,7 @@ See |autocmd-events| for a complete list of events. PATTERNS -The {file_pattern} argument can actually be a comma-separated list of file +The {file-pattern} argument can actually be a comma-separated list of file patterns. For example: "*.c,*.h" matches files ending in ".c" and ".h". The usual file wildcards can be used. Here is a summary of the most often used ones: diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt index 41948f577e..4cba5a33d0 100644 --- a/runtime/doc/usr_41.txt +++ b/runtime/doc/usr_41.txt @@ -41,6 +41,12 @@ prefer. And you can use any colon command in it (commands that start with a specific file type. A complicated macro can be defined by a separate Vim script file. You can think of other uses yourself. + If you are familiar with Python, you can find a comparison between + Python and Vim script here, with pointers to other documents: + https://gist.github.com/yegappan/16d964a37ead0979b05e655aa036cad0 + And if you are familiar with JavaScript: + https://w0rp.com/blog/post/vim-script-for-the-javascripter/ + Let's start with a simple example: > :let i = 1 @@ -93,6 +99,8 @@ and the value of the variable i. Since i is one, this will print: Then there is the ":let i += 1" command. This does the same thing as ":let i = i + 1". This adds one to the variable i and assigns the new value to the same variable. +Note: this is how it works in legacy Vim script, which is what we discuss in +this file. The example was given to explain the commands, but would you really want to make such a loop, it can be written much more compact: > @@ -107,21 +115,29 @@ if you are impatient. FOUR KINDS OF NUMBERS -Numbers can be decimal, hexadecimal, octal or binary. A hexadecimal number -starts with "0x" or "0X". For example "0x1f" is decimal 31. An octal number -starts with a zero. "017" is decimal 15. A binary number starts with "0b" or -"0B". For example "0b101" is decimal 5. Careful: don't put a zero before a -decimal number, it will be interpreted as an octal number! - The ":echo" command always prints decimal numbers. Example: > +Numbers can be decimal, hexadecimal, octal or binary. + +A hexadecimal number starts with "0x" or "0X". For example "0x1f" is decimal +31. + +An octal number starts with "0o", "0O" or a zero and another digit. "0o17" is +decimal 15. Using just a zero prefix is not supported in Vim9 script. + +A binary number starts with "0b" or "0B". For example "0b101" is decimal 5. + +A decimal number is just digits. Careful: don't put a zero before a decimal +number, it will be interpreted as an octal number in legacy script! + +The ":echo" command always prints decimal numbers. Example: > - :echo 0x7f 036 + :echo 0x7f 0o36 < 127 30 ~ A number is made negative with a minus sign. This also works for hexadecimal, octal and binary numbers. A minus sign is also used for subtraction. Compare this with the previous example: > - :echo 0x7f -036 + :echo 0x7f -0o36 < 97 ~ White space in an expression is ignored. However, it's recommended to use it @@ -129,7 +145,7 @@ for separating items, to make the expression easier to read. For example, to avoid the confusion with a negative number above, put a space between the minus sign and the following number: > - :echo 0x7f - 036 + :echo 0x7f - 0o36 ============================================================================== *41.2* Variables @@ -319,9 +335,9 @@ Grouping is done with parentheses. No surprises here. Example: > :echo (10 + 5) * 2 < 30 ~ -Strings can be concatenated with ".". Example: > +Strings can be concatenated with ".." (see |expr6|). Example: > - :echo "foo" . "bar" + :echo "foo" .. "bar" < foobar ~ When the ":echo" command gets multiple arguments, it separates them with a @@ -488,9 +504,9 @@ So far the commands in the script were executed by Vim directly. The very powerful way to build commands and execute them. An example is to jump to a tag, which is contained in a variable: > - :execute "tag " . tag_name + :execute "tag " .. tag_name -The "." is used to concatenate the string "tag " with the value of variable +The ".." is used to concatenate the string "tag " with the value of variable "tag_name". Suppose "tag_name" has the value "get_cmd", then the command that will be executed is: > @@ -506,7 +522,7 @@ This jumps to the first line and formats all lines with the "=" operator. To make ":normal" work with an expression, combine ":execute" with it. Example: > - :execute "normal " . normal_commands + :execute "normal " .. normal_commands The variable "normal_commands" must contain the Normal mode commands. Make sure that the argument for ":normal" is a complete command. Otherwise @@ -523,12 +539,12 @@ If you don't want to execute a string but evaluate it to get its expression value, you can use the eval() function: > :let optname = "path" - :let optval = eval('&' . optname) + :let optval = eval('&' .. optname) A "&" character is prepended to "path", thus the argument to eval() is "&path". The result will then be the value of the 'path' option. The same thing can be done with: > - :exe 'let optval = &' . optname + :exe 'let optval = &' .. optname ============================================================================== *41.6* Using functions @@ -848,6 +864,7 @@ Insert mode completion: *completion-functions* complete_check() check if completion should be aborted complete_info() get current completion information pumvisible() check if the popup menu is displayed + pum_getpos() position and size of popup menu if visible Folding: *folding-functions* foldclosed() check for a closed fold at a specific line @@ -1127,7 +1144,7 @@ Example: > : let n = n + len(split(getline(lnum))) : let lnum = lnum + 1 : endwhile - : echo "found " . n . " words" + : echo "found " .. n .. " words" :endfunction You can call this function with: > @@ -1140,7 +1157,7 @@ It will be executed once and echo the number of words. range, with the cursor in that line. Example: > :function Number() - : echo "line " . line(".") . " contains: " . getline(".") + : echo "line " .. line(".") .. " contains: " .. getline(".") :endfunction If you call this function with: > @@ -1164,11 +1181,11 @@ so on. The variable "a:0" contains the number of extra arguments. :function Show(start, ...) : echohl Title - : echo "start is " . a:start + : echo "start is " .. a:start : echohl None : let index = 1 : while index <= a:0 - : echo " Arg " . index . " is " . a:{index} + : echo " Arg " .. index .. " is " .. a:{index} : let index = index + 1 : endwhile : echo "" @@ -1576,10 +1593,10 @@ Another useful mechanism is the ":finally" command: > :let tmp = tempname() :try - : exe ".,$write " . tmp - : exe "!filter " . tmp + : exe ".,$write " .. tmp + : exe "!filter " .. tmp : .,$delete - : exe "$read " . tmp + : exe "$read " .. tmp :finally : call delete(tmp) :endtry @@ -1600,7 +1617,7 @@ Here is a summary of items that apply to Vim scripts. They are also mentioned elsewhere, but form a nice checklist. The end-of-line character depends on the system. For Unix a single <NL> -character is used. For Windows <CR><LF> is used. This is important when +character is used. For Windows <CR><NL> is used. This is important when using mappings that end in a <CR>. See |:source_crnl|. @@ -1887,9 +1904,9 @@ for this mapping, but the user might already use it for something else. To allow the user to define which keys a mapping in a plugin uses, the <Leader> item can be used: > - 22 map <unique> <Leader>a <Plug>TypecorrAdd + 22 map <unique> <Leader>a <Plug>TypecorrAdd; -The "<Plug>TypecorrAdd" thing will do the work, more about that further on. +The "<Plug>TypecorrAdd;" thing will do the work, more about that further on. The user can set the "mapleader" variable to the key sequence that he wants this mapping to start with. Thus if the user has done: > @@ -1905,15 +1922,15 @@ already happened to exist. |:map-<unique>| But what if the user wants to define his own key sequence? We can allow that with this mechanism: > - 21 if !hasmapto('<Plug>TypecorrAdd') - 22 map <unique> <Leader>a <Plug>TypecorrAdd + 21 if !hasmapto('<Plug>TypecorrAdd;') + 22 map <unique> <Leader>a <Plug>TypecorrAdd; 23 endif -This checks if a mapping to "<Plug>TypecorrAdd" already exists, and only +This checks if a mapping to "<Plug>TypecorrAdd;" already exists, and only defines the mapping from "<Leader>a" if it doesn't. The user then has a chance of putting this in his vimrc file: > - map ,c <Plug>TypecorrAdd + map ,c <Plug>TypecorrAdd; Then the mapped key sequence will be ",c" instead of "_a" or "\a". @@ -1930,8 +1947,8 @@ prepending it with "s:". We will define a function that adds a new typing correction: > 30 function s:Add(from, correct) - 31 let to = input("type the correction for " . a:from . ": ") - 32 exe ":iabbrev " . a:from . " " . to + 31 let to = input("type the correction for " .. a:from .. ": ") + 32 exe ":iabbrev " .. a:from .. " " .. to .. 36 endfunction @@ -1943,15 +1960,15 @@ function (without the "s:"), which is again another function. <SID> can be used with mappings. It generates a script ID, which identifies the current script. In our typing correction plugin we use it like this: > - 24 noremap <unique> <script> <Plug>TypecorrAdd <SID>Add + 24 noremap <unique> <script> <Plug>TypecorrAdd; <SID>Add .. 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR> Thus when a user types "\a", this sequence is invoked: > - \a -> <Plug>TypecorrAdd -> <SID>Add -> :call <SID>Add() + \a -> <Plug>TypecorrAdd; -> <SID>Add -> :call <SID>Add() -If another script would also map <SID>Add, it would get another script ID and +If another script also maps <SID>Add, it will get another script ID and thus define another mapping. Note that instead of s:Add() we use <SID>Add() here. That is because the @@ -1992,9 +2009,9 @@ difference between using <SID> and <Plug>: To make it very unlikely that other plugins use the same sequence of characters, use this structure: <Plug> scriptname mapname In our example the scriptname is "Typecorr" and the mapname is "Add". - This results in "<Plug>TypecorrAdd". Only the first character of - scriptname and mapname is uppercase, so that we can see where mapname - starts. + We add a semicolon as the terminator. This results in + "<Plug>TypecorrAdd;". Only the first character of scriptname and + mapname is uppercase, so that we can see where mapname starts. <SID> is the script ID, a unique identifier for a script. Internally Vim translates <SID> to "<SNR>123_", where "123" can be any @@ -2036,7 +2053,7 @@ a few lines to count the number of corrections: > 30 function s:Add(from, correct) .. 34 let s:count = s:count + 1 - 35 echo s:count . " corrections now" + 35 echo s:count .. " corrections now" 36 endfunction First s:count is initialized to 4 in the script itself. When later the @@ -2069,21 +2086,21 @@ Here is the resulting complete example: > 18 \ synchronization 19 let s:count = 4 20 - 21 if !hasmapto('<Plug>TypecorrAdd') - 22 map <unique> <Leader>a <Plug>TypecorrAdd + 21 if !hasmapto('<Plug>TypecorrAdd;') + 22 map <unique> <Leader>a <Plug>TypecorrAdd; 23 endif - 24 noremap <unique> <script> <Plug>TypecorrAdd <SID>Add + 24 noremap <unique> <script> <Plug>TypecorrAdd; <SID>Add 25 26 noremenu <script> Plugin.Add\ Correction <SID>Add 27 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR> 29 30 function s:Add(from, correct) - 31 let to = input("type the correction for " . a:from . ": ") - 32 exe ":iabbrev " . a:from . " " . to + 31 let to = input("type the correction for " .. a:from .. ": ") + 32 exe ":iabbrev " .. a:from .. " " .. to 33 if a:correct | exe "normal viws\<C-R>\" \b\e" | endif 34 let s:count = s:count + 1 - 35 echo s:count . " corrections now" + 35 echo s:count .. " corrections now" 36 endfunction 37 38 if !exists(":Correct") @@ -2122,7 +2139,7 @@ Here is a simple example for a plugin help file, called "typecorr.txt": > 6 There are currently only a few corrections. Add your own if you like. 7 8 Mappings: - 9 <Leader>a or <Plug>TypecorrAdd + 9 <Leader>a or <Plug>TypecorrAdd; 10 Add a correction for the word under the cursor. 11 12 Commands: @@ -2260,13 +2277,13 @@ To make sure mappings will only work in the current buffer use the > command. This needs to be combined with the two-step mapping explained above. An example of how to define functionality in a filetype plugin: > - if !hasmapto('<Plug>JavaImport') - map <buffer> <unique> <LocalLeader>i <Plug>JavaImport + if !hasmapto('<Plug>JavaImport;') + map <buffer> <unique> <LocalLeader>i <Plug>JavaImport; endif - noremap <buffer> <unique> <Plug>JavaImport oimport ""<Left><Esc> + noremap <buffer> <unique> <Plug>JavaImport; oimport ""<Left><Esc> |hasmapto()| is used to check if the user has already defined a map to -<Plug>JavaImport. If not, then the filetype plugin defines the default +<Plug>JavaImport;. If not, then the filetype plugin defines the default mapping. This starts with |<LocalLeader>|, which allows the user to select the key(s) he wants filetype plugin mappings to start with. The default is a backslash. @@ -2283,12 +2300,12 @@ plugin for the mail filetype: > " Add mappings, unless the user didn't want this. if !exists("no_plugin_maps") && !exists("no_mail_maps") " Quote text by inserting "> " - if !hasmapto('<Plug>MailQuote') - vmap <buffer> <LocalLeader>q <Plug>MailQuote - nmap <buffer> <LocalLeader>q <Plug>MailQuote + if !hasmapto('<Plug>MailQuote;') + vmap <buffer> <LocalLeader>q <Plug>MailQuote; + nmap <buffer> <LocalLeader>q <Plug>MailQuote; endif - vnoremap <buffer> <Plug>MailQuote :s/^/> /<CR> - nnoremap <buffer> <Plug>MailQuote :.,$s/^/> /<CR> + vnoremap <buffer> <Plug>MailQuote; :s/^/> /<CR> + nnoremap <buffer> <Plug>MailQuote; :.,$s/^/> /<CR> endif Two global variables are used: @@ -2331,7 +2348,7 @@ should be undone. Set the b:undo_ftplugin variable to the commands that will undo the settings in your filetype plugin. Example: > let b:undo_ftplugin = "setlocal fo< com< tw< commentstring<" - \ . "| unlet b:match_ignorecase b:match_words b:match_skip" + \ .. "| unlet b:match_ignorecase b:match_words b:match_skip" Using ":setlocal" with "<" after the option name resets the option to its global value. That is mostly the best way to reset the option value. @@ -2452,17 +2469,17 @@ The following example shows how it's done: > map <F19> :call BufNetWrite('something')<CR> let s:did_load = 1 - exe 'au FuncUndefined BufNet* source ' . expand('<sfile>') + exe 'au FuncUndefined BufNet* source ' .. expand('<sfile>') finish endif function BufNetRead(...) - echo 'BufNetRead(' . string(a:000) . ')' + echo 'BufNetRead(' .. string(a:000) .. ')' " read functionality here endfunction function BufNetWrite(...) - echo 'BufNetWrite(' . string(a:000) . ')' + echo 'BufNetWrite(' .. string(a:000) .. ')' " write functionality here endfunction diff --git a/runtime/doc/usr_42.txt b/runtime/doc/usr_42.txt index 501f02e745..99da1359c2 100644 --- a/runtime/doc/usr_42.txt +++ b/runtime/doc/usr_42.txt @@ -209,8 +209,8 @@ argument: > :amenu <silent> Mine.Next\ File :call <SID>NextFile()<CR> Don't use "<silent>" too often. It is not needed for short commands. If you -make a menu for someone else, being able the see the executed command will -give him a hint about what he could have typed, instead of using the mouse. +make a menu for someone else, being able to see the executed command will give +him a hint about what he could have typed, instead of using the mouse. LISTING MENUS diff --git a/runtime/doc/usr_44.txt b/runtime/doc/usr_44.txt index 722c3de26c..5c04c26434 100644 --- a/runtime/doc/usr_44.txt +++ b/runtime/doc/usr_44.txt @@ -673,21 +673,10 @@ syntax file, earlier in 'runtimepath' was already loaded: > finish endif -To be compatible with Vim 5.8 use: > - - if version < 600 - syntax clear - elseif exists("b:current_syntax") - finish - endif - Set "b:current_syntax" to the name of the syntax at the end. Don't forget that included files do this too, you might have to reset "b:current_syntax" if you include two files. -If you want your syntax file to work with Vim 5.x, add a check for v:version. -Find an syntax file in the Vim 7.2 distribution for an example. - Do not include anything that is a user preference. Don't set 'tabstop', 'expandtab', etc. These belong in a filetype plugin. diff --git a/runtime/doc/usr_45.txt b/runtime/doc/usr_45.txt index 1ce6969d37..bc95f3405e 100644 --- a/runtime/doc/usr_45.txt +++ b/runtime/doc/usr_45.txt @@ -2,7 +2,7 @@ VIM USER MANUAL - by Bram Moolenaar - Select your language + Select your language (locale) The messages in Vim can be given in several languages. This chapter explains diff --git a/runtime/doc/usr_toc.txt b/runtime/doc/usr_toc.txt index 69846f1bcf..f466a8ece9 100644 --- a/runtime/doc/usr_toc.txt +++ b/runtime/doc/usr_toc.txt @@ -42,7 +42,7 @@ Tuning Vim |usr_42.txt| Add new menus |usr_43.txt| Using filetypes |usr_44.txt| Your own syntax highlighted -|usr_45.txt| Select your language +|usr_45.txt| Select your language (locale) Reference manual @@ -327,7 +327,7 @@ Make Vim work as you like it. |44.11| Installing a syntax file |44.12| Portable syntax file layout -|usr_45.txt| Select your language +|usr_45.txt| Select your language (locale) |45.1| Language for Messages |45.2| Language for Menus |45.3| Using another encoding diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt index 5fb7c4ce50..d5c07d9622 100644 --- a/runtime/doc/various.txt +++ b/runtime/doc/various.txt @@ -92,7 +92,7 @@ g8 Print the hex values of the bytes used in the encoding because it contains illegal bytes. Does not wrap around the end of the file. Note that when the cursor is on an illegal byte or the - cursor is halfway through a multi-byte character the + cursor is halfway through a multibyte character the command won't move the cursor. *:p* *:pr* *:print* *E749* @@ -134,19 +134,21 @@ g8 Print the hex values of the bytes used in the quit < *:z* *E144* -:{range}z[+-^.=]{count} Display several lines of text surrounding the line - specified with {range}, or around the current line - if there is no {range}. If there is a {count}, that's - how many lines you'll see; if there is only one window - then twice the value of the 'scroll' option is used, +:[range]z[+-^.=][count] Display several lines of text surrounding the line + specified with [range], or around the current line + if there is no [range]. + + If there is a [count], that's how many lines you'll + see; if there is no [count] and only one window then + twice the value of the 'scroll' option is used, otherwise the current window height minus 3 is used. + This is the value of "scr" in the table below. - If there is a {count} the 'window' option is set to + If there is a [count] the 'window' option is set to its value. :z can be used either alone or followed by any of - several punctuation marks. These have the following - effect: + several marks. These have the following effect: mark first line last line new cursor line ~ ---- ---------- --------- ------------ @@ -160,7 +162,7 @@ g8 Print the hex values of the bytes used in the If the mark is "=", a line of dashes is printed around the current line. -:{range}z#[+-^.=]{count} *:z#* +:[range]z#[+-^.=][count] *:z#* Like ":z", but number the lines. {not in all versions of Vi, not with these arguments} @@ -260,6 +262,7 @@ g8 Print the hex values of the bytes used in the use it to append a Vim command. See |:bar|. Any "%" in {cmd} is expanded to the current file name. + Any "#" in {cmd} is expanded to the alternate file name. Special characters are not escaped, use quotes or |shellescape()|: > :!ls "%" @@ -338,7 +341,7 @@ g8 Print the hex values of the bytes used in the 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. + function can be used instead of redirection. :redi[r] =>> {var} Append messages to an existing variable. Only string variables can be used. @@ -358,7 +361,7 @@ g8 Print the hex values of the bytes used in the it in / any non-ID character (see |'isident'|) can be used, so long as it does not appear in {pat}. Without the enclosing character the pattern cannot include the - bar character. + bar character. 'ignorecase' is not used. The pattern is matched against the relevant part of the output, not necessarily the whole line. Only some @@ -502,6 +505,9 @@ gO Show a filetype-specific, navigable "outline" of the if at a visible position. Queued messages are processed during the sleep. + *:sl!* *:sleep!* +:[N]sl[eep]! [N] [m] Same as above, but hide the cursor. + ============================================================================== 2. Using Vim like less or more *less* @@ -514,7 +520,7 @@ up mappings to simulate the commands that less supports. Otherwise, you can still use the Vim commands. This isn't perfect. For example, when viewing a short file Vim will still use -the whole screen. But it works good enough for most uses, and you get syntax +the whole screen. But it works well enough for most uses, and you get syntax highlighting. The "h" key will give you a short overview of the available commands. diff --git a/runtime/doc/vi_diff.txt b/runtime/doc/vi_diff.txt index beecca2480..cef2859eb5 100644 --- a/runtime/doc/vi_diff.txt +++ b/runtime/doc/vi_diff.txt @@ -11,9 +11,10 @@ Differences between Vim and Vi *vi-differences* ============================================================================== 1. Limits *limits* -Vim has only a few limits for the files that can be edited. +Vim has only a few limits for the files that can be edited {Vi: can not handle +<Nul> characters and characters above 128, has limited line length, many other +limits}. - *E340* Maximum line length 2147483647 characters Maximum number of lines 2147483647 lines Maximum file size 2147483647 bytes (2 Gbyte) when a long integer is @@ -358,7 +359,7 @@ Editing binary files. |edit-binary| last line in the file. Multi-language support. |multi-lang| - Files in double-byte or multi-byte encodings can be edited. There is + Files in double-byte or multibyte encodings can be edited. There is UTF-8 support to be able to edit various languages at the same time, without switching fonts. |UTF-8| Messages and menus are available in different languages. diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index eadc1c04a0..2c39fdb53c 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -498,13 +498,23 @@ Test functions: test_alloc_fail() test_autochdir() test_disable_char_avail() + test_feedinput() + test_garbagecollect_soon + test_getvalue() + test_ignore_error() + test_null_blob() test_null_channel() test_null_dict() + test_null_function() test_null_job() test_null_list() test_null_partial() test_null_string() + test_option_not_set() test_override() + test_refcount() + test_scrollbar() + test_setmouse() test_settime() TUI: diff --git a/runtime/doc/visual.txt b/runtime/doc/visual.txt index fd3d93ed98..f7828f0289 100644 --- a/runtime/doc/visual.txt +++ b/runtime/doc/visual.txt @@ -103,6 +103,7 @@ gn Search forward for the last used search pattern, like E.g., "dgn" deletes the text of the next match. If Visual mode is active, extends the selection until the end of the next match. + 'wrapscan' applies Note: Unlike `n` the search direction does not depend on the previous search command. @@ -111,7 +112,7 @@ gN Like |gn| but searches backward, like with `N`. *<LeftMouse>* <LeftMouse> Set the current cursor position. If Visual mode is - active it is stopped. Only when 'mouse' option is + active it is stopped. Only when 'mouse' option contains 'n' or 'a'. If the position is within 'so' lines from the last line on the screen the text is scrolled up. If the position is within 'so' lines from @@ -122,7 +123,7 @@ gN Like |gn| but searches backward, like with `N`. <RightMouse> Start Visual mode if it is not active. The text from the cursor position to the position of the click is highlighted. If Visual mode was already active move - the start or end of the highlighted text, which ever + the start or end of the highlighted text, whichever is closest, to the position of the click. Only when 'mouse' option contains 'n' or 'a'. @@ -225,7 +226,7 @@ The objects that can be used are: is inner sentence |v_is| ap a paragraph (with white space) |v_ap| ip inner paragraph |v_ip| - ab a () block (with parenthesis) |v_ab| + ab a () block (with parentheses) |v_ab| ib inner () block |v_ib| aB a {} block (with braces) |v_aB| iB inner {} block |v_iB| @@ -336,7 +337,7 @@ Visual-block Shift *v_b_>* The block is shifted by 'shiftwidth'. The RHS of the block is irrelevant. The LHS of the block determines the point from which to apply a right shift, and padding includes TABs optimally according to 'ts' and 'et'. The LHS of the -block determines the point upto which to shift left. +block determines the point up to which to shift left. See |v_b_>_example|. See |v_b_<_example|. diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt index 35efb1bbce..3a58cc08d9 100644 --- a/runtime/doc/windows.txt +++ b/runtime/doc/windows.txt @@ -115,6 +115,12 @@ status line, the '^' character is used for the current window, and '=' for other windows. If 'mouse' is enabled, a status line can be dragged to resize windows. + *filler-lines* +The lines after the last buffer line in a window are called filler lines. +These lines start with a tilde (~) character. By default, these are +highlighted as NonText (|hl-NonText|). The EndOfBuffer highlight group +(|hl-EndOfBuffer|) can be used to change the highlighting of filler lines. + ============================================================================== 3. Opening and closing a window *opening-window* *E36* @@ -177,15 +183,12 @@ CTRL-W CTRL_N *CTRL-W_CTRL-N* This behaves like a ":split" first, and then an ":enew" command. -:[N]vne[w] [++opt] [+cmd] [file] *:vne* *:vnew* - Like |:new|, but split vertically. If 'equalalways' is set - and 'eadirection' isn't "ver" the windows will be spread out - horizontally, unless a width was specified. - :[N]new [++opt] [+cmd] {file} :[N]sp[lit] [++opt] [+cmd] {file} *:split_f* Create a new window and start editing file {file} in it. This - behaves like a ":split" first, and then an ":e" command. + behaves almost like a ":split" first, and then an ":edit" + command, but the alternate file name in the original window is + set to {file}. If [+cmd] is given, execute the command when the file has been loaded |+cmd|. Also see |++opt|. @@ -193,7 +196,12 @@ CTRL-W CTRL_N *CTRL-W_CTRL-N* height). Reduces the current window height to create room (and others, if the 'equalalways' option is set). -:[N]sv[iew] [++opt] [+cmd] {file} *:sv* *:sview* *splitview* +:[N]vne[w] [++opt] [+cmd] [file] *:vne* *:vnew* + Like |:new|, but split vertically. If 'equalalways' is set + and 'eadirection' isn't "ver" the windows will be spread out + horizontally, unless a width was specified. + +:[N]sv[iew] [++opt] [+cmd] [file] *:sv* *:sview* *splitview* Same as ":split", but set 'readonly' option for this buffer. :[N]sf[ind] [++opt] [+cmd] {file} *:sf* *:sfi* *:sfind* *splitfind* @@ -269,8 +277,9 @@ CTRL-W CTRL-Q *CTRL-W_CTRL-Q* Without {count}: Quit the current window. If {count} is given quit the {count} window - When quitting the last window (not counting a help window), - exit Vim. + *edit-window* + When quitting the last edit window (not counting help or + preview windows), exit Vim. When 'hidden' is set, and there is only one window for the current buffer, it becomes hidden. When 'hidden' is not set, @@ -287,6 +296,10 @@ CTRL-W CTRL-Q *CTRL-W_CTRL-Q* :+quit " quit the next window :+2quit " quit the second next window < + When closing a help window, and this is not the only window, + Vim will try to restore the previous window layout, see + |:helpclose|. + :q[uit]! :{count}q[uit]! Without {count}: Quit the current window. If {count} is @@ -306,9 +319,9 @@ CTRL-W c *CTRL-W_c* *:clo* *:close* [!] is used, the buffer becomes hidden (unless there is another window editing it). - When there is only one window in the current tab page and - there is another tab page, this closes the current tab page. - |tab-page|. + When there is only one |edit-window| in the current tab page + and there is another tab page, this closes the current tab + page. |tab-page|. This command fails when: *E444* - There is only one window on the screen. @@ -480,14 +493,14 @@ CTRL-W J Move the current window to be at the very bottom, using the CTRL-W H Move the current window to be at the far left, using the full height of the screen. This works like closing the current window and then creating another one with - ":vert topleft split", except that the current window contents + `:vert topleft split`, except that the current window contents is used for the new window. *CTRL-W_L* CTRL-W L Move the current window to be at the far right, using the full height of the screen. This works like closing the current window and then creating another one with - ":vert botright split", except that the current window + `:vert botright split`, except that the current window contents is used for the new window. *CTRL-W_T* @@ -518,6 +531,10 @@ CTRL-W + Increase current window height by N (default 1). CTRL-W CTRL-_ *CTRL-W_CTRL-_* *CTRL-W__* CTRL-W _ Set current window height to N (default: highest possible). +:{winnr}res[ize] [+-]N + Like `:resize` above, but apply the size to window {winnr} + instead of the current window. + z{nr}<CR> Set current window height to {nr}. *CTRL-W_<* @@ -526,7 +543,7 @@ CTRL-W < Decrease current window width by N (default 1). *CTRL-W_>* CTRL-W > Increase current window width by N (default 1). -:vertical res[ize] [N] *:vertical-resize* *CTRL-W_bar* +:vert[ical] res[ize] [N] *:vertical-resize* *CTRL-W_bar* CTRL-W | Set current window width to N (default: widest possible). You can also resize a window by dragging a status line up or down with the @@ -743,7 +760,7 @@ can also get to them with the buffer list commands, like ":bnext". Examples: > - :windo set nolist nofoldcolumn | normal zn + :windo set nolist foldcolumn=0 | normal! zn This resets the 'list' option and disables folding in all windows. > @@ -751,7 +768,7 @@ This resets the 'list' option and disables folding in all windows. > This resets the 'fileencoding' in each buffer and writes it if this changed the buffer. The result is that all buffers will use the 'encoding' encoding -(if conversion works properly). +(if conversion succeeds). ============================================================================== 9. Tag or file name under the cursor *window-tag* @@ -1034,7 +1051,9 @@ list of buffers. |unlisted-buffer| < *:bad* *:badd* :bad[d] [+lnum] {fname} - Add file name {fname} to the buffer list, without loading it. + Add file name {fname} to the buffer list, without loading it, + if it wasn't listed yet. If the buffer was previously + deleted, not wiped, it will be made listed again. If "lnum" is specified, the cursor will be positioned at that line when the buffer is first entered. Note that other commands after the + will be ignored. |