doc

closes neovim#7622

Author: justinmk

Diff for: CONTRIBUTING.md

@@ -14,7 +14,7 @@ low-risk/isolated tasks:
 Developer guidelines
 --------------------
 
-- Nvim developers should read `:help dev-help`.
+- Nvim developers should read `:help dev`.
 - External UI developers should read `:help dev-ui`.
 
 Reporting problems
@@ -24,7 +24,7 @@ Reporting problems
 - Search [existing issues][github-issues] (including closed!)
 - Update Neovim to the latest version to see if your problem persists.
 - Disable plugins incrementally, to narrow down the cause of the issue.
-- When reporting a crash, include a stacktrace.
+- When reporting a crash, [include a stacktrace](https://github.com/neovim/neovim/wiki/Development-tips#backtrace-linux).
 - [Bisect][git-bisect] to the cause of a regression, if you are able. This is _extremely_ helpful.
 - Check `$NVIM_LOG_FILE`, if it exists.
 - Include `cmake --system-information` for **build** issues.
@@ -92,7 +92,7 @@ and [AppVeyor].
 - CI builds are compiled with [`-Werror`][gcc-warnings], so compiler warnings
   will fail the build.
 - If any tests fail, the build will fail.
-  See [Building Neovim#running-tests][wiki-run-tests] to run tests locally.
+  See [test/README.md#running-tests][run-tests] to run tests locally.
   Passing locally doesn't guarantee passing the CI build, because of the
   different compilers and platforms tested against.
 - CI runs [ASan] and other analyzers.
@@ -168,7 +168,7 @@ as context, use the `-W` argument as well.
 [hygiene]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
 [style-guide]: http://neovim.io/develop/style-guide.xml
 [ASan]: http://clang.llvm.org/docs/AddressSanitizer.html
-[wiki-run-tests]: https://github.com/neovim/neovim/wiki/Building-Neovim#running-tests
+[run-tests]: https://github.com/neovim/neovim/blob/master/test/README.md#running-tests
 [wiki-faq]: https://github.com/neovim/neovim/wiki/FAQ
 [review-checklist]: https://github.com/neovim/neovim/wiki/Code-review-checklist
 [3174]: https://github.com/neovim/neovim/issues/3174

Diff for: README.md

@@ -14,7 +14,7 @@
 [![PVS-studio Check](https://neovim.io/doc/reports/pvs/badge.svg)](https://neovim.io/doc/reports/pvs)
 
 [![Debian CI](https://badges.debian.net/badges/debian/testing/neovim/version.svg)](https://buildd.debian.org/neovim)
-[![Downloads](https://img.shields.io/github/downloads/neovim/neovim/total.svg?maxAge=2592000)](https://github.com/neovim/neovim/releases/)
+[![Downloads](https://img.shields.io/github/downloads/neovim/neovim/total.svg?maxAge=2592001)](https://github.com/neovim/neovim/releases/)
 
 Neovim is a project that seeks to aggressively refactor Vim in order to:
 

Diff for: runtime/doc/api.txt

@@ -60,8 +60,7 @@ External programs ("clients") can use the metadata to discover the |rpc-api|.
 API contract                                                     *api-contract*
 
 The API is made of functions and events. Clients call functions like those
-described at |api-global|, and may "attach" in order to receive rich events,
-described at |rpc-remote-ui|.
+described at |api-global|, and may "attach" to receive rich |ui-events|.
 
 As Nvim develops, its API may change only according the following "contract":
 
@@ -481,6 +480,84 @@ nvim_call_atomic({calls})                                 *nvim_call_atomic()*
                     error ocurred, the values from all preceding calls will
                     still be returned.
 
+                                                     *nvim_parse_expression()*
+nvim_parse_expression({expr}, {flags}, {highlight})
+                Parse a VimL expression
+
+                Attributes:~
+                    {async}
+
+                Parameters:~
+                    {expr}       Expression to parse. Is always treated as a
+                                 single line.
+                    {flags}      Flags:  - "m" if multiple expressions in a
+                                 row are allowed (only the first one will be
+                                 parsed), - "E" if EOC tokens are not allowed
+                                 (determines whether they will stop parsing
+                                 process or be recognized as an
+                                 operator/space, though also yielding an
+                                 error). - "l" when needing to start parsing
+                                 with lvalues for ":let" or ":for". Common
+                                 flag sets: - "m" to parse like for ":echo". -
+                                 "E" to parse like for "<C-r>=". - empty
+                                 string for ":call". - "lm" to parse for
+                                 ":let".
+                    {highlight}  If true, return value will also include
+                                 "highlight" key containing array of 4-tuples
+                                 (arrays) (Integer, Integer, Integer, String),
+                                 where first three numbers define the
+                                 highlighted region and represent line,
+                                 starting column and ending column (latter
+                                 exclusive: one should highlight region
+                                 [start_col, end_col)).
+
+                Return:~
+                    AST: top-level dictionary holds keys "error": Dictionary
+                    with error, present only if parser saw some error.
+                    Contains the following keys: "message": String, error
+                    message in printf format, translated. Must contain exactly
+                    one "%.*s". "arg": String, error message argument. "len":
+                    Amount of bytes successfully parsed. With flags equal to
+                    "" that should be equal to the length of expr string.
+                    @note: “Sucessfully parsed” here means “participated in
+                    AST creation”, not “till the first error”. "ast": AST,
+                    either nil or a dictionary with these keys: "type": node
+                    type, one of the value names from ExprASTNodeType
+                    stringified without "kExprNode" prefix. "start": a pair
+                    [line, column] describing where node is “started” where
+                    "line" is always 0 (will not be 0 if you will be using
+                    nvim_parse_viml() on e.g. ":let", but that is not present
+                    yet). Both elements are Integers. "len": “length” of the
+                    node. This and "start" are there for debugging purposes
+                    primary (debugging parser and providing debug
+                    information). "children": a list of nodes described in
+                    top/"ast". There always is zero, one or two children, key
+                    will not be present if node has no children. Maximum
+                    number of children may be found in node_maxchildren array.
+                    Local values (present only for certain nodes): "scope": a
+                    single Integer, specifies scope for "Option" and
+                    "PlainIdentifier" nodes. For "Option" it is one of
+                    ExprOptScope values, for "PlainIdentifier" it is one of
+                    ExprVarScope values. "ident": identifier (without scope,
+                    if any), present for "Option", "PlainIdentifier",
+                    "PlainKey" and "Environment" nodes. "name": Integer,
+                    register name (one character) or -1. Only present for
+                    "Register" nodes. "cmp_type": String, comparison type, one
+                    of the value names from ExprComparisonType, stringified
+                    without "kExprCmp" prefix. Only present for "Comparison"
+                    nodes. "ccs_strategy": String, case comparison strategy,
+                    one of the value names from ExprCaseCompareStrategy,
+                    stringified without "kCCStrategy" prefix. Only present for
+                    "Comparison" nodes. "augmentation": String, augmentation
+                    type for "Assignment" nodes. Is either an empty string,
+                    "Add", "Subtract" or "Concat" for "=", "+=", "-=" or ".="
+                    respectively. "invert": Boolean, true if result of
+                    comparison needs to be inverted. Only present for
+                    "Comparison" nodes. "ivalue": Integer, integer value for
+                    "Integer" nodes. "fvalue": Float, floating-point value for
+                    "Float" nodes. "svalue": String, value for
+                    "SingleQuotedString" and "DoubleQuotedString" nodes.
+
 nvim__id({obj})                                                   *nvim__id()*
                 Returns object given as argument
 
@@ -721,9 +798,10 @@ nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line},
                                  or -1 for ungrouped highlight
                     {hl_group}   Name of the highlight group to use
                     {line}       Line to highlight (zero-indexed)
-                    {col_start}  Start of range of columns to highlight
-                    {col_end}    End of range of columns to highlight, or -1
-                                 to highlight to end of line
+                    {col_start}  Start of (byte-indexed) column range to
+                                 highlight
+                    {col_end}    End of (byte-indexed) column range to
+                                 highlight, or -1 to highlight to end of line
 
                 Return:~
                     The src_id that was used
@@ -957,9 +1035,6 @@ nvim_tabpage_is_valid({tabpage})                     *nvim_tabpage_is_valid()*
 ==============================================================================
 UI Functions                                                          *api-ui*
 
-remote_ui_disconnect()                                *remote_ui_disconnect()*
-                TODO: Documentation
-
 nvim_ui_attach({width}, {height}, {options})                *nvim_ui_attach()*
                 TODO: Documentation
 

Diff for: runtime/doc/autocmd.txt

@@ -259,13 +259,12 @@ Name			triggered by ~
 |BufNew|		just after creating a new buffer
 
 |SwapExists|		detected an existing swap file
-|TermOpen|		when a terminal buffer is starting
-|TermClose|		when a terminal buffer ends
+|TermOpen|		when a terminal job starts
+|TermClose|		when a terminal job ends
 
 	Options
 |FileType|		when the 'filetype' option has been set
 |Syntax|		when the 'syntax' option has been set
-|TermChanged|		after the value of 'term' has changed
 |OptionSet|		after setting any option
 
 	Startup and exit
@@ -933,26 +932,20 @@ TabEnter			Just after entering a tab page. |tab-page|
 TabLeave			Just before leaving a tab page. |tab-page|
 				A WinLeave event will have been triggered
 				first.
-						 {Nvim} *TabNew*
+							*TabNew*
 TabNew				When creating a new tab page. |tab-page|
 				After WinEnter and before TabEnter.
-						 {Nvim} *TabNewEntered*
+							*TabNewEntered*
 TabNewEntered			After entering a new tab page. |tab-page|
 				After BufEnter.
-						 {Nvim} *TabClosed*
+							*TabClosed*
 TabClosed			After closing a tab page. <afile> can be used
 				for the tab page number.
-							*TermChanged*
-TermChanged			After the value of 'term' has changed.  Useful
-				for re-loading the syntax file to update the
-				colors, fonts and other terminal-dependent
-				settings.  Executed for all loaded buffers.
-						 {Nvim} *TermClose*
-TermClose			When a terminal buffer ends.
-						 {Nvim} *TermOpen*
-TermOpen			When a terminal buffer is starting.  This can
-				be used to configure the terminal emulator by
-				setting buffer variables. |terminal|
+							*TermClose*
+TermClose			When a |terminal| job ends.
+							*TermOpen*
+TermOpen			When a |terminal| job is starting.  Can be
+				used to configure the terminal buffer.
 							*TermResponse*
 TermResponse			After the response to |t_RV| is received from
 				the terminal.  The value of |v:termresponse|

Diff for: runtime/doc/syntax.txt

@@ -4709,17 +4709,7 @@ ctermbg={color-nr}				*highlight-ctermbg*
 	"cterm".  For example, on some systems "cterm=bold ctermfg=3" gives
 	another color, on others you just get color 3.
 
-	For an xterm this depends on your resources, and is a bit
-	unpredictable.	See your xterm documentation for the defaults.	The
-	colors for a color-xterm can be changed from the .Xdefaults file.
-	Unfortunately this means that it's not possible to get the same colors
-	for each user.
-
-	The MSDOS standard colors are fixed (in a console window), so these
-	have been used for the names.  But the meaning of color names in X11
-	are fixed, so these color settings have been used, to make the
-	highlighting settings portable (complicated, isn't it?).  The
-	following names are recognized, with the color number used:
+	The following names are recognized, with the color number used:
 
 							*cterm-colors*
 	    NR-16   NR-8    COLOR NAME ~

Diff for: runtime/doc/ui.txt

@@ -9,7 +9,7 @@ Nvim UI protocol							  *ui*
                                       Type |gO| to see the table of contents.
 
 ==============================================================================
-Introduction							     *ui-intro*
+UI Events							    *ui-events*
 
 GUIs can be implemented as external processes communicating with Nvim over the
 RPC API. The UI model consists of a terminal-like grid with a single,

Diff for: runtime/doc/various.txt

@@ -207,21 +207,18 @@ g8			Print the hex values of the bytes used in the
 :sh[ell]		Removed. |vim-differences| {Nvim}
 
 						  *:terminal* *:te*
-:te[rminal][!] [{cmd}]	Execute {cmd} with 'shell' in a new |terminal| buffer.
-			Equivalent to: >
-			      :enew
-			      :call termopen('{cmd}')
-<
-			See |termopen()|.
+:te[rminal][!] [{cmd}]	Execute {cmd} with 'shell' in a new |terminal-emulator|
+			buffer. Without {cmd}, start an interactive 'shell'.
 
-			Without {cmd}, start an interactive shell.
+			Type |i| to enter |Terminal-mode|, then keys are sent to
+			the job running in the terminal. Type <C-\><C-N> to
+			leave Terminal-mode. |CTRL-\_CTRL-N|
 
-			Creating the terminal buffer fails when changes have been
-			made to the current buffer, unless 'hidden' is set.
+			Fails if changes have been made to the current buffer,
+			unless 'hidden' is set.
 
 			To enter |Terminal-mode| automatically: >
-			      autocmd BufEnter term://* startinsert
-			      autocmd BufLeave term://* stopinsert
+			      autocmd TermOpen * startinsert
 <
 							*:!cmd* *:!* *E34*
 :!{cmd}			Execute {cmd} with 'shell'. See also |:terminal|.

Diff for: runtime/doc/vim_diff.txt

@@ -302,7 +302,8 @@ Highlight groups:
   |hl-ColorColumn|, |hl-CursorColumn| are lower priority than most other
   groups
 
-The variable name "count" is no fallback for |v:count| anymore.
+VimL (Vim script) compatibility:
+  `count` does not alias to |v:count|
 
 ==============================================================================
 5. Missing legacy features				 *nvim-features-missing*

Diff for: src/nvim/api/buffer.c

@@ -763,8 +763,8 @@ ArrayOf(Integer, 2) nvim_buf_get_mark(Buffer buffer, String name, Error *err)
 ///                   or -1 for ungrouped highlight
 /// @param hl_group   Name of the highlight group to use
 /// @param line       Line to highlight (zero-indexed)
-/// @param col_start  Start of range of columns to highlight
-/// @param col_end    End of range of columns to highlight,
+/// @param col_start  Start of (byte-indexed) column range to highlight
+/// @param col_end    End of (byte-indexed) column range to highlight,
 ///                   or -1 to highlight to end of line
 /// @param[out] err   Error details, if any
 /// @return The src_id that was used

Diff for: src/nvim/tui/tui.c

@@ -1529,7 +1529,7 @@ static void patch_terminfo_bugs(TUIData *data, const char *term,
         || iterm || iterm_pretending_xterm
         || teraterm    // per TeraTerm "Supported Control Functions" doco
         // Some linux-type terminals (such as console-terminal-emulator
-        // from the nosh toolset) implement implement the xterm extension.
+        // from the nosh toolset) implement the xterm extension.
         || (linuxvt && (xterm_version || (vte_version > 0) || colorterm)))) {
       data->unibi_ext.set_cursor_style =
         (int)unibi_add_ext_str(ut, "Ss", "\x1b[%p1%d q");

Diff for: test/README.md

@@ -168,16 +168,13 @@ minutes](http://learnxinyminutes.com/docs/lua/).
   Do not silently skip the test with `if-else`. If a functional test depends on
   some external factor (e.g. the existence of `md5sum` on `$PATH`), *and* you
   can't mock or fake the dependency, then skip the test via `pending()` if the
-  external factor is missing. This ensures that the *total* test-count (success
-  + fail + error + pending) is the same in all environments.
+  external factor is missing. This ensures that the *total* test-count
+  (success + fail + error + pending) is the same in all environments.
     - *Note:* `pending()` is ignored if it is missing an argument _unless_ it is
-      [contained in an `it()`
-      block](https://github.com/neovim/neovim/blob/d21690a66e7eb5ebef18046c7a79ef898966d786/test/functional/ex_cmds/grep_spec.lua#L11).
-      Provide empty function argument if the `pending()` call is outside of
-      `it()`
+      [contained in an `it()` block](https://github.com/neovim/neovim/blob/d21690a66e7eb5ebef18046c7a79ef898966d786/test/functional/ex_cmds/grep_spec.lua#L11).
+      Provide empty function argument if the `pending()` call is outside of `it()`
       ([example](https://github.com/neovim/neovim/commit/5c1dc0fbe7388528875aff9d7b5055ad718014de#diff-bf80b24c724b0004e8418102f68b0679R18)).
-- Use `make testlint` for using the shipped luacheck program ([supported by
-  syntastic](https://github.com/scrooloose/syntastic/blob/d6b96c079be137c83009827b543a83aa113cc011/doc/syntastic-checkers.txt#L3546))
+- Use `make testlint` for using the shipped luacheck program ([supported by syntastic](https://github.com/scrooloose/syntastic/blob/d6b96c079be137c83009827b543a83aa113cc011/doc/syntastic-checkers.txt#L3546))
   to lint all tests.
 
 ### Where tests go