doc

13 files changed, 121 insertions, 63 deletions

diff --git a/README.md b/README.md
index 87d2db8cae..454137219f 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,11 @@ Install from source
     make CMAKE_BUILD_TYPE=RelWithDebInfo
     sudo make install
 
+To install to a non-default location, specify `CMAKE_INSTALL_PREFIX`:
+
+    make CMAKE_EXTRA_FLAGS="-DCMAKE_INSTALL_PREFIX=/full/path/"
+    make install
+
 See [the wiki](https://github.com/neovim/neovim/wiki/Building-Neovim) for details.
 
 Install from package
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 159dd93c5e..876adf0d72 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -7,7 +7,7 @@
 Nvim API							   *API* *api*
 
 Nvim exposes a powerful API that can be used by plugins and external processes
-via |msgpack-rpc|, Lua and VimL (|eval-api|).
+via |RPC|, |Lua| and VimL (|eval-api|).
 
 Applications can also embed libnvim to work with the C API directly.
 
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 298f64bbee..36826e2479 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -142,6 +142,8 @@ shell		The Vim application.  This can cover the whole screen (e.g.,
 window		View on a buffer.  There can be several windows in Vim,
 		together with the command line, menubar, toolbar, etc. they
 		fit in the shell.
+frame		Windows are kept in a tree of frames.  Each frame contains
+		a column, row, or window ("leaf" frame).
 
 PROVIDERS 						*dev-provider*
 
@@ -230,23 +232,47 @@ _not_ a Buffer). The common {action} "list" indicates that it lists all
 bufs (plural) in the global context.
 
 
+API-CLIENT						*dev-api-client*
+
+Package Naming ~
+API client packages should NOT be named something ambiguous like "neovim" or
+"python-client".  Use "nvim" as a prefix/suffix to some other identifier
+following ecosystem conventions.
+
+For example, Python packages tend to have "py" in the name, so "pynvim" is
+a good name: it's idiomatic and unambiguous. If the package is named "neovim",
+it confuses users, and complicates documentation and discussions.
+
+Examples of API-client package names:
+        GOOD: nvim-racket
+        GOOD: pynvim
+        BAD:  python-client
+        BAD:  neovim
+
+Implementation ~
+Consider using libmpack instead of the msgpack.org C/C++ library. libmpack is
+small, efficient, and C89-compatible. It can be easily inlined in your
+C project source, too.  https://github.com/libmpack/libmpack/
+
+
 EXTERNAL UI 						*dev-ui*
 
+Compatibility ~
 External UIs should be aware of the |api-contract|. In particular, future
-versions of Nvim may add optional, new items to existing events. The API is
-strongly backwards-compatible, but clients must not break if new fields are
-added to existing events.
+versions of Nvim may add new items to existing events. The API is strongly
+backwards-compatible, but clients must not break if new fields are added to
+existing events.
 
-External UIs are expected to implement some common features.
+Common Features ~
+External UIs are expected to implement these common features:
+- Cursor style (shape, color) should respond to the 'guicursor' properties
+  delivered with the mode_info_set UI event.
+- Send the "super" key (Windows key, Apple key) as a |<D-| chord.
 
-- Users may want to configure UI-specific options. The UI should publish the
-  |GUIEnter| autocmd after attaching to Nvim: >
-    doautocmd GUIEnter
+Implementation ~
 - Options can be monitored for changes by the |OptionSet| autocmd. E.g. if the
   user sets the 'guifont' option, this autocmd notifies channel 42: >
     autocmd OptionSet guifont call rpcnotify(42, 'option-changed', 'guifont', &guifont)
-- cursor-shape change: 'guicursor' properties are sent in the mode_info_set UI
-  event.
 
 
  vim:tw=78:ts=8:ft=help:norl:
diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt
index a123041866..968d882a22 100644
--- a/runtime/doc/if_lua.txt
+++ b/runtime/doc/if_lua.txt
@@ -24,7 +24,7 @@ the existing `package.cpath` are used.  Example:
 
 1. Given that
    - 'runtimepath' contains `/foo/bar,/xxx;yyy/baz,/abc`;
-   - initial (defined at compile time or derived from 
+   - initial (defined at compile-time or derived from 
      `$LUA_CPATH`/`$LUA_INIT`) `package.cpath` contains 
      `./?.so;/def/ghi/a?d/j/g.elf;/def/?.so`.
 2. It finds `?`-containing suffixes `/?.so`, `/a?d/j/g.elf` and `/?.so`, in 
@@ -159,14 +159,17 @@ Examples:
 >
 	:lua vim.api.nvim_command('echo "Hello, Nvim!"')
 <
+To see the Lua version: >
+	:lua print(_VERSION)
+
+To see the LuaJIT version: >
+	:lua print(jit.version)
+<
 
 :[range]lua << {endmarker}
 {script}
 {endmarker}
 			Execute Lua script {script}.
-			Note: This command doesn't work when the Lua
-			feature wasn't compiled in.  To avoid errors, see
-			|script-here|.
 
 {endmarker} must NOT be preceded by any white space.  If {endmarker} is
 omitted from after the "<<", a dot '.' must be used after {script}, like
@@ -186,15 +189,8 @@ Example:
 	EOF
 	endfunction
 
-Note that the variables are prefixed with `local`: they will disappear when
-block finishes. This is not the case for globals.
-
-To see what version of Lua you have: >
-	:lua print(_VERSION)
-
-If you use LuaJIT you can also use this: >
-	:lua print(jit.version)
-<
+Note that the `local` variables will disappear when block finishes. This is
+not the case for globals.
 
 							*:luado*
 :[range]luado {body}	Execute Lua function "function (line, linenr) {body}
diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt
index 90b0ff7da3..30524fb6aa 100644
--- a/runtime/doc/intro.txt
+++ b/runtime/doc/intro.txt
@@ -373,8 +373,7 @@ CTRL-{char}	{char} typed as a control character; that is, typing {char}
 
 					*key-notation* *key-codes* *keycodes*
 These names for keys are used in the documentation.  They can also be used
-with the ":map" command (insert the key name by pressing CTRL-K and then the
-key you want the name for).
+with the ":map" command.
 
 notation	meaning		    equivalent	decimal value(s)	~
 -----------------------------------------------------------------------
diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt
index 7af6e401da..a1453a6cc6 100644
--- a/runtime/doc/msgpack_rpc.txt
+++ b/runtime/doc/msgpack_rpc.txt
@@ -175,7 +175,7 @@ contains information that makes this task easier (see also |rpc-types|):
     even more strongly-typed APIs.
   - Functions that are considered to be methods that operate on instances of
     Nvim special types (msgpack EXT) will have the `"method"` attribute set to
-    `true`. The reciever type is the type of the first argument. The method
+    `true`. The receiver type is the type of the first argument. The method
     names are prefixed with `nvim_` plus a shortened type name, e.g.
     `nvim_buf_get_lines` represents the `get_lines` method of a Buffer instance.
     - Global functions have `"method"` set to `false` and are prefixed with just
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 4df08ca5fb..c2018fc511 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -6759,7 +6759,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	
 	Highlights of vertical separators are determined by the window to the
 	left of the separator.  The highlight of a tabpage in |tabline| is
-	determine by the last-focused window of the tabpage.  Highlights of
+	determined by the last-focused window of the tabpage.  Highlights of
 	the popupmenu are determined by the current window.  Highlights in the
 	message area cannot be overridden.
 
diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt
index 02f3fcab6c..b806b08f95 100644
--- a/runtime/doc/provider.txt
+++ b/runtime/doc/provider.txt
@@ -133,8 +133,8 @@ registers. Nvim looks for these clipboard tools, in order of priority:
 
   - |g:clipboard|
   - pbcopy/pbpaste (macOS)
-  - xclip
-  - xsel (newer alternative to xclip)
+  - xsel (if $DISPLAY is set)
+  - xclip (if $DISPLAY is set)
   - lemonade (for SSH) https://github.com/pocke/lemonade
   - doitclient (for SSH) http://www.chiark.greenend.org.uk/~sgtatham/doit/
   - win32yank (Windows)
@@ -162,13 +162,11 @@ process has not died, the cached selection is applied.
 ==============================================================================
 X11 selection mechanism			      *clipboard-x11* *x11-selection*
 
-The clipboard providers for X11 store text in what is known as "selections".
-Selections are "owned" by an application, so when the application is closed,
-the selection text is lost.
-
+X11 clipboard providers store text in "selections". Selections are owned by an
+application, so when the application gets closed, the selection text is lost.
 The contents of selections are held by the originating application (e.g., upon
-a copy), and only passed on to another application when that other application
-asks for them (e.g., upon a paste).
+a copy), and only passed to another application when that other application
+requests them (e.g., upon a paste).
 
 							      *quoteplus* *quote+*
 
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index c92fcd8994..6959d64989 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -60,14 +60,17 @@ a complete and centralized reference of those differences.
 
 MAJOR COMPONENTS ~
 
-Embedded terminal emulator	|terminal|
-RPC API				|RPC|
-Shared data			|shada|
-XDG base directories		|xdg|
+API				|API|
+Lua scripting			|lua|
 Job control			|job-control|
 Remote plugins			|remote-plugin|
-Python plugins			|provider-python|
-Clipboard integration		|provider-clipboard|
+Providers
+  Clipboard			|provider-clipboard|
+  Python plugins		|provider-python|
+  Ruby plugins			|provider-ruby|
+Shared data			|shada|
+Embedded terminal		|terminal|
+XDG base directories		|xdg|
 
 USER EXPERIENCE  ~
 
@@ -87,6 +90,16 @@ Working intuitively and consistently is a major goal of Nvim.
 - Vim's internal test functions (test_autochdir(), test_settime(), etc.) are
   not exposed (nor implemented); instead Nvim has a robust API.
 
+- Behaviors, options, documentation are removed if they cost users more time
+  than they save.
+
+Usability details have been improved where the benefit outweighs any
+backwards-compatibility cost. Some examples:
+
+- |K| in help documents can be used like |CTRL-]|.
+- Directories for 'directory' and 'undodir' are auto-created.
+- Terminal features such as 'guicursor' are enabled where possible.
+
 ARCHITECTURE ~
 
 External plugins run in separate processes. |remote-plugin| This improves
@@ -130,6 +143,7 @@ Commands:
   |:checkhealth|
   |:drop| is available on all platforms
   |:Man| is available by default, with many improvements such as completion
+  |:tchdir| tab-local |current-directory|
 
 Functions:
   |dictwatcheradd()| notifies a callback whenever a |Dict| is modified
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 98f4410347..86f4a9d008 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -166,7 +166,10 @@ void nvim_feedkeys(String keys, String mode, Boolean escape_csi)
 /// On VimL error: Does not fail, but updates v:errmsg.
 ///
 /// Unlike `nvim_feedkeys`, this uses a lower-level input buffer and the call
-/// is not deferred. This is the most reliable way to emulate real user input.
+/// is not deferred. This is the most reliable way to send real user input.
+///
+/// @note |keycodes| like <CR> are translated, so `<` is special.
+///       To input a literal `<`, send `<LT>`.
 ///
 /// @param keys to be typed
 /// @return Number of bytes actually written (can be fewer than
diff --git a/src/nvim/lua/executor.c b/src/nvim/lua/executor.c
index 16bb4169c4..8e7b8a1824 100644
--- a/src/nvim/lua/executor.c
+++ b/src/nvim/lua/executor.c
@@ -336,8 +336,8 @@ static lua_State *nlua_init(void)
 /// Calls nlua_init() if needed. Is responsible for pre-lua call initalization
 /// like updating `package.[c]path` with directories derived from &runtimepath.
 ///
-/// @return Interprter instance to use. Will either be initialized now or taken
-///         from previous initalization.
+/// @return Interpreter instance to use. Will either be initialized now or
+///         taken from previous initialization.
 static lua_State *nlua_enter(void)
   FUNC_ATTR_NONNULL_RET FUNC_ATTR_WARN_UNUSED_RESULT
 {
diff --git a/src/nvim/ops.c b/src/nvim/ops.c
index c6df71ea46..432c9a8b47 100644
--- a/src/nvim/ops.c
+++ b/src/nvim/ops.c
@@ -2735,7 +2735,7 @@ void do_put(int regname, yankreg_T *reg, int dir, long count, int flags)
     // Autocommands may be executed when saving lines for undo, which may make
     // y_array invalid.  Start undo now to avoid that.
     if (u_save(curwin->w_cursor.lnum, curwin->w_cursor.lnum + 1) == FAIL) {
-      ELOG(_("Failed to save undo information"));
+      ELOG("Failed to save undo information");
       return;
     }
   }
diff --git a/test/README.md b/test/README.md
index 01db5960cd..44558f0981 100644
--- a/test/README.md
+++ b/test/README.md
@@ -1,31 +1,48 @@
-# Tests
+Tests
+=====
 
 Tests are run by `/cmake/RunTests.cmake` file, using busted.
 
 For some failures, `.nvimlog` (or `$NVIM_LOG_FILE`) may provide insight.
 
-## Directory structure
+Lint
+----
 
-Directories with tests: `/test/benchmark` for benchmarks, `/test/functional` for 
-functional tests, `/test/unit` for unit tests. `/test/config` contains `*.in` 
-files (currently a single one) which are transformed into `*.lua` files using 
-`configure_file` CMake command: this is for acessing CMake variables in lua 
-tests. `/test/includes` contains include files for use by luajit `ffi.cdef` 
-C definitions parser: normally used to make macros not accessible via this 
-mechanism accessible the other way.
+`make lint` (and `make testlint`) runs [luacheck](https://github.com/mpeterv/luacheck)
+on the test code.
 
-Files `/test/*/preload.lua` contain modules which will be preloaded by busted, 
-via `--helper` option. `/test/**/helpers.lua` contain various “library” 
-functions, (intended to be) used by a number of tests and not just a single one.
+If a luacheck warning must be ignored, specify the warning code. Example:
 
-`/test/*/**/*_spec.lua` are files containing actual tests. Files that do not end 
-with a `_spec.lua` are libraries like `/test/**/helpers.lua`, except that they 
-have some common topic.
+    -- luacheck: ignore 621
 
-Tests inside `/test/unit` and `/test/functional` are normally divided into 
-groups by the semantic component they are testing.
+http://luacheck.readthedocs.io/en/stable/warnings.html
 
-## Environment variables
+Ignore the smallest applicable scope (e.g. inside a function, not at the top of
+the file).
+
+Layout
+------
+
+- `/test/benchmark` : benchmarks
+- `/test/functional` : functional tests
+- `/test/unit` : unit tests
+- `/test/config` : contains `*.in` files which are transformed into `*.lua`
+  files using `configure_file` CMake command: this is for acessing CMake
+  variables in lua tests.
+- `/test/includes` : include-files for use by luajit `ffi.cdef` C definitions
+  parser: normally used to make macros not accessible via this mechanism
+  accessible the other way.
+- `/test/*/preload.lua` : modules preloaded by busted `--helper` option
+- `/test/**/helpers.lua` : common utility functions for test code
+- `/test/*/**/*_spec.lua` : actual tests. Files that do not end with
+  `_spec.lua` are libraries like `/test/**/helpers.lua`, except that they have
+  some common topic.
+
+Tests in `/test/unit` and `/test/functional` are normally divided into groups
+by the semantic component they are testing.
+
+Environment variables
+---------------------
 
 Test behaviour is affected by environment variables. Currently supported 
 (Functional, Unit, Benchmarks) (when Defined; when set to _1_; when defined,