Merge #7171 from justinmk/doc

8 files changed, 123 insertions, 93 deletions

diff --git a/README.md b/README.md
index 0442ee61de..4016c9b3c2 100644
--- a/README.md
+++ b/README.md
@@ -48,17 +48,24 @@ and [more](https://github.com/neovim/neovim/wiki/Installing-Neovim)!
 Project layout
 --------------
 
-    ├─ ci/            Build server scripts
-    ├─ cmake/         Build scripts
-    ├─ runtime/       User plugins/docs
-    ├─ src/           Source code
-    ├─ third-party/   CMake subproject to build dependencies 
-    └─ test/          Test code
-
-- `third-party/` is activated if `USE_BUNDLED_DEPS` is undefined or the
-  `USE_BUNDLED` CMake option is true.
-- [Source README](src/nvim/README.md)
-- [Test README](test/README.md)
+    ├─ ci/              build automation
+    ├─ cmake/           build scripts
+    ├─ runtime/         user plugins/docs
+    ├─ src/             application source code (see src/nvim/README.md)
+    │  ├─ api/          API subsystem
+    │  ├─ eval/         VimL subsystem
+    │  ├─ event/        event-loop subsystem
+    │  ├─ generators/   code generation (pre-compilation)
+    │  ├─ lib/          generic data structures
+    │  ├─ lua/          lua subsystem
+    │  ├─ msgpack_rpc/  RPC subsystem
+    │  ├─ os/           low-level platform code
+    │  └─ tui/          built-in UI
+    ├─ third-party/     cmake subproject to build dependencies
+    └─ test/            tests (see test/README.md)
+
+- To disable `third-party/` specify `USE_BUNDLED_DEPS=NO` or `USE_BUNDLED=NO`
+  (CMake option).
 
 Features
 --------
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 7c6b8a3c1a..e12cd1cfa9 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -171,8 +171,8 @@ nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special})
                 Parameters:~
                     {str}        String to be converted.
                     {from_part}  Legacy Vim parameter. Usually true.
-                    {do_lt}      Also translate <lt>. Does nothing if
-                                 `special` is false.
+                    {do_lt}      Also translate <lt>. Ignored if `special` is
+                                 false.
                     {special}    Replace |keycodes|, e.g. <CR> becomes a "\n"
                                  char.
 
@@ -309,20 +309,24 @@ nvim_set_option({name}, {value})                           *nvim_set_option()*
                     {value}  New option value
 
 nvim_out_write({str})                                       *nvim_out_write()*
-                Writes a message to vim output buffer
+                Writes a message to the Vim output buffer. Does not append
+                "\n", the message is buffered (won't display) until a linefeed
+                is written.
 
                 Parameters:~
                     {str}  Message
 
 nvim_err_write({str})                                       *nvim_err_write()*
-                Writes a message to vim error buffer
+                Writes a message to the Vim error buffer. Does not append
+                "\n", the message is buffered (won't display) until a linefeed
+                is written.
 
                 Parameters:~
                     {str}  Message
 
 nvim_err_writeln({str})                                   *nvim_err_writeln()*
-                Writes a message to vim error buffer. Appends a linefeed to
-                ensure all contents are written.
+                Writes a message to the Vim error buffer. Appends "\n", so the
+                buffer is flushed (and displayed).
 
                 Parameters:~
                     {str}  Message
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 29e254b0b3..b37b0e8836 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1522,14 +1522,16 @@ v:errors	Errors found by assert functions, such as |assert_true()|.
 
 					*v:event* *event-variable*
 v:event		Dictionary of event data for the current |autocommand|.  Valid
-		only during the autocommand lifetime: storing or passing
-		`v:event` is invalid.  Copy it instead: >
+		only during the event lifetime; storing or passing v:event is
+		invalid!  Copy it instead: >
 			au TextYankPost * let g:foo = deepcopy(v:event)
 <		Keys vary by event; see the documentation for the specific
-		event, e.g. |TextYankPost|.
+		event, e.g. |DirChanged| or |TextYankPost|.
 			KEY		DESCRIPTION ~
-			operator	The current |operator|.  Also set for
-					Ex commands (unlike |v:operator|). For
+			cwd		Current working directory
+			scope		Event-specific scope name.
+			operator	Current |operator|.  Also set for Ex
+					commands (unlike |v:operator|). For
 					example if |TextYankPost| is triggered
 					by the |:yank| Ex command then
 					`v:event['operator']` is "y".
@@ -4726,7 +4728,8 @@ input({opts})
 		"-complete=" argument.	Refer to |:command-completion| for
 		more information.  Example: >
 			let fname = input("File: ", "", "file")
-<							*E5400* *E5402*
+
+<					*input()-highlight* *E5400* *E5402*
 		The optional `highlight` key allows specifying function which
 		will be used for highlighting user input.  This function
 		receives user input as its only argument and must return
@@ -4744,6 +4747,30 @@ input({opts})
 		sections must be ordered so that next hl_start_col is greater
 		then or equal to previous hl_end_col.
 
+		Example (try some input with parentheses): >
+			highlight RBP1 guibg=Red ctermbg=red
+			highlight RBP2 guibg=Yellow ctermbg=yellow
+			highlight RBP3 guibg=Green ctermbg=green
+			highlight RBP4 guibg=Blue ctermbg=blue
+			let g:rainbow_levels = 4
+			function! RainbowParens(cmdline)
+			  let ret = []
+			  let i = 0
+			  let lvl = 0
+			  while i < len(a:cmdline)
+			    if a:cmdline[i] is# '('
+			      call add(ret, [i, i + 1, 'RBP' . ((lvl % g:rainbow_levels) + 1)])
+			      let lvl += 1
+			    elseif a:cmdline[i] is# ')'
+			      let lvl -= 1
+			      call add(ret, [i, i + 1, 'RBP' . ((lvl % g:rainbow_levels) + 1)])
+			    endif
+			    let i += 1
+			  endwhile
+			  return ret
+			endfunction
+			call input({'prompt':'>','highlight':'RainbowParens'})
+<
 		Highlight function is called at least once for each new
 		displayed input string, before command-line is redrawn.  It is
 		expected that function is pure for the duration of one input()
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 2f031c0b1f..eb3c4d50ce 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -6,9 +6,8 @@
 
 Differences between Nvim and Vim			       *vim-differences*
 
-Throughout the help files, differences between Nvim and Vim are indicated via
-the "{Nvim}" tag.  This document is a complete and centralized list of all
-these differences.
+Nvim differs from Vim in many ways, big and small.  This document is
+a complete and centralized reference of those differences.
 
 				      Type <M-]> to see the table of contents.
 
@@ -72,12 +71,18 @@ Clipboard integration		|provider-clipboard|
 
 USER EXPERIENCE  ~
 
-Working intuitively and consistently is a major goal of Nvim. Examples:
+Working intuitively and consistently is a major goal of Nvim.
 
-- Nvim does not have `-X`, a platform-specific option "sometimes" available in
-  Vim (with potential surprises: http://stackoverflow.com/q/14635295). Nvim
-  avoids features that cannot be provided on all platforms--instead that is
-  delegated to external plugins/extensions.
+							*feature-compile*
+- Nvim always includes ALL features, in contrast to Vim (which ships with
+  various combinations of 100+ optional features). Think of it as a leaner
+  version of Vim's "HUGE" build. This reduces surface area for bugs, and
+  removes a common source of confusion and friction for users.
+
+- Nvim avoids features that cannot be provided on all platforms; instead that
+  is delegated to external plugins/extensions. E.g. the `-X` platform-specific
+  option is "sometimes" available in Vim (with potential surprises:
+  http://stackoverflow.com/q/14635295).
 
 - Vim's internal test functions (test_autochdir(), test_settime(), etc.) are
   not exposed (nor implemented); instead Nvim has a robust API.
@@ -268,13 +273,12 @@ Lua interface (|if_lua.txt|):
 - Lua has direct access to Nvim |API| via `vim.api`.
 - Lua package.path and package.cpath are automatically updated according to
   'runtimepath': |lua-require|.
-- Currently, most legacy Vim features are missing.
 
-|input()| and |inputdialog()| gained support for each other’s features (return 
-on cancel and completion respectively) via dictionary argument (replaces all 
+|input()| and |inputdialog()| support for each other’s features (return on
+cancel and completion respectively) via dictionary argument (replaces all
 other arguments if used).
 
-|input()| and |inputdialog()| now support user-defined cmdline highlighting.
+|input()| and |inputdialog()| support user-defined cmdline highlighting.
 
 ==============================================================================
 5. Missing legacy features				 *nvim-features-missing*
@@ -282,7 +286,7 @@ other arguments if used).
 Some legacy Vim features are not implemented:
 
 - |if_py|: vim.bindeval() and vim.Function() are not supported
-- |if_lua|: the `vim` object currently only supports `vim.api`
+- |if_lua|: the `vim` object is missing most legacy methods
 - *if_perl*
 - *if_mzscheme*
 - *if_tcl*
@@ -290,7 +294,7 @@ Some legacy Vim features are not implemented:
 ==============================================================================
 6. Removed features					 *nvim-features-removed*
 
-These features are in Vim, but have been intentionally removed from Nvim.
+These Vim features were intentionally removed from Nvim.
 
 			*'cp'* *'nocompatible'* *'nocp'* *'compatible'*
 Nvim is always "non-compatible" with Vi.
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 2bc31b2812..cfbe34b848 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -484,7 +484,8 @@ void nvim_set_option(String name, Object value, Error *err)
   set_option_to(NULL, SREQ_GLOBAL, name, value, err);
 }
 
-/// Writes a message to vim output buffer
+/// Writes a message to the Vim output buffer. Does not append "\n", the
+/// message is buffered (won't display) until a linefeed is written.
 ///
 /// @param str Message
 void nvim_out_write(String str)
@@ -493,7 +494,8 @@ void nvim_out_write(String str)
   write_msg(str, false);
 }
 
-/// Writes a message to vim error buffer
+/// Writes a message to the Vim error buffer. Does not append "\n", the
+/// message is buffered (won't display) until a linefeed is written.
 ///
 /// @param str Message
 void nvim_err_write(String str)
@@ -502,8 +504,8 @@ void nvim_err_write(String str)
   write_msg(str, true);
 }
 
-/// Writes a message to vim error buffer. Appends a linefeed to ensure all
-/// contents are written.
+/// Writes a message to the Vim error buffer. Appends "\n", so the buffer is
+/// flushed (and displayed).
 ///
 /// @param str Message
 /// @see nvim_err_write()
diff --git a/src/nvim/main.c b/src/nvim/main.c
index 3f828d7be9..a665ad1de2 100644
--- a/src/nvim/main.c
+++ b/src/nvim/main.c
@@ -1878,54 +1878,47 @@ static void usage(void)
   signal_stop();              // kill us with CTRL-C here, if you like
 
   mch_msg(_("Usage:\n"));
-  mch_msg(_("  nvim [arguments] [file ...]      Edit specified file(s)\n"));
-  mch_msg(_("  nvim [arguments] -               Read text from stdin\n"));
-  mch_msg(_("  nvim [arguments] -t <tag>        Edit file where tag is defined\n"));
-  mch_msg(_("  nvim [arguments] -q [errorfile]  Edit file with first error\n"));
-  mch_msg(_("\nArguments:\n"));
+  mch_msg(_("  nvim [options] [file ...]      Edit file(s)\n"));
+  mch_msg(_("  nvim [options] -               Read text from stdin\n"));
+  mch_msg(_("  nvim [options] -t <tag>        Edit file where tag is defined\n"));
+  mch_msg(_("  nvim [options] -q [errorfile]  Edit file with first error\n"));
+  mch_msg(_("\nOptions:\n"));
   mch_msg(_("  --                    Only file names after this\n"));
-#if !defined(UNIX)
-  mch_msg(_("  --literal             Don't expand wildcards\n"));
-#endif
-  mch_msg(_("  -e                    Ex mode\n"));
-  mch_msg(_("  -E                    Improved Ex mode\n"));
-  mch_msg(_("  -s                    Silent (batch) mode (only for ex mode)\n"));
+  mch_msg(_("  +                     Start at end of file\n"));
+  mch_msg(_("  --cmd <cmd>           Execute <cmd> before any config\n"));
+  mch_msg(_("  +<cmd>, -c <cmd>      Execute <cmd> after config and first file\n"));
+  mch_msg("\n");
+  mch_msg(_("  -b                    Binary mode\n"));
   mch_msg(_("  -d                    Diff mode\n"));
-  mch_msg(_("  -R                    Read-only mode\n"));
-  mch_msg(_("  -Z                    Restricted mode\n"));
+  mch_msg(_("  -e, -E                Ex mode, Improved Ex mode\n"));
+  mch_msg(_("  -es                   Silent (batch) mode\n"));
+  mch_msg(_("  -h, --help            Print this help message\n"));
+  mch_msg(_("  -i <shada>            Use this shada file\n"));
   mch_msg(_("  -m                    Modifications (writing files) not allowed\n"));
   mch_msg(_("  -M                    Modifications in text not allowed\n"));
-  mch_msg(_("  -b                    Binary mode\n"));
-  mch_msg(_("  -l                    Lisp mode\n"));
-  mch_msg(_("  -A                    Arabic mode\n"));
-  mch_msg(_("  -F                    Farsi mode\n"));
-  mch_msg(_("  -H                    Hebrew mode\n"));
-  mch_msg(_("  -V[N][file]           Be verbose [level N][log messages to file]\n"));
-  mch_msg(_("  -D                    Debugging mode\n"));
   mch_msg(_("  -n                    No swap file, use memory only\n"));
-  mch_msg(_("  -r, -L                List swap files and exit\n"));
-  mch_msg(_("  -r <file>             Recover crashed session\n"));
-  mch_msg(_("  -u <vimrc>            Use <vimrc> instead of the default\n"));
-  mch_msg(_("  -i <shada>            Use <shada> instead of the default\n"));
-  mch_msg(_("  --noplugin            Don't load plugin scripts\n"));
-  mch_msg(_("  -o[N]                 Open N windows (default: one for each file)\n"));
-  mch_msg(_("  -O[N]                 Like -o but split vertically\n"));
-  mch_msg(_("  -p[N]                 Open N tab pages (default: one for each file)\n"));
-  mch_msg(_("  +                     Start at end of file\n"));
-  mch_msg(_("  +<linenum>            Start at line <linenum>\n"));
-  mch_msg(_("  +/<pattern>           Start at first occurrence of <pattern>\n"));
-  mch_msg(_("  --cmd <command>       Execute <command> before loading any vimrc\n"));
-  mch_msg(_("  -c <command>          Execute <command> after loading the first file\n"));
+  mch_msg(_("  -o[N]                 Open N windows (default: one per file)\n"));
+  mch_msg(_("  -O[N]                 Open N vertical windows (default: one per file)\n"));
+  mch_msg(_("  -p[N]                 Open N tab pages (default: one per file)\n"));
+  mch_msg(_("  -r, -L                List swap files\n"));
+  mch_msg(_("  -r <file>             Recover edit state for this file\n"));
+  mch_msg(_("  -R                    Read-only mode\n"));
   mch_msg(_("  -S <session>          Source <session> after loading the first file\n"));
   mch_msg(_("  -s <scriptin>         Read Normal mode commands from <scriptin>\n"));
-  mch_msg(_("  -w <scriptout>        Append all typed characters to <scriptout>\n"));
-  mch_msg(_("  -W <scriptout>        Write all typed characters to <scriptout>\n"));
-  mch_msg(_("  --startuptime <file>  Write startup timing messages to <file>\n"));
-  mch_msg(_("  --api-info            Dump API metadata serialized to msgpack and exit\n"));
+  mch_msg(_("  -u <config>           Use this config file\n"));
+  mch_msg(_("  -v, --version         Print version information\n"));
+  mch_msg(_("  -V[N][file]           Verbose [level][file]\n"));
+  mch_msg(_("  -Z                    Restricted mode\n"));
+  mch_msg("\n");
+  mch_msg(_("  --api-info            Write msgpack-encoded API metadata to stdout\n"));
   mch_msg(_("  --embed               Use stdin/stdout as a msgpack-rpc channel\n"));
   mch_msg(_("  --headless            Don't start a user interface\n"));
-  mch_msg(_("  -v, --version         Print version information and exit\n"));
-  mch_msg(_("  -h, --help            Print this help message and exit\n"));
+#if !defined(UNIX)
+  mch_msg(_("  --literal             Don't expand wildcards\n"));
+#endif
+  mch_msg(_("  --noplugin            Don't load plugins\n"));
+  mch_msg(_("  --startuptime <file>  Write startup timing messages to <file>\n"));
+  mch_msg(_("\nSee \":help startup-options\" for all options.\n"));
 }
 
 
diff --git a/src/nvim/testdir/test_startup.vim b/src/nvim/testdir/test_startup.vim
index 64f7f31294..5a38178bd5 100644
--- a/src/nvim/testdir/test_startup.vim
+++ b/src/nvim/testdir/test_startup.vim
@@ -76,11 +76,11 @@ func Test_help_arg()
     let found = []
     for line in lines
       if line =~ '-R.*Read-only mode'
-	call add(found, 'Readonly mode')
+        call add(found, 'Readonly mode')
       endif
       " Watch out for a second --version line in the Gnome version.
-      if line =~ '--version.*Print version information and exit'
-	call add(found, "--version")
+      if line =~ '--version.*Print version information'
+        call add(found, "--version")
       endif
     endfor
     call assert_equal(['Readonly mode', '--version'], found)
diff --git a/src/nvim/version.c b/src/nvim/version.c
index f5b45caefc..2a3fdbd70d 100644
--- a/src/nvim/version.c
+++ b/src/nvim/version.c
@@ -1089,13 +1089,7 @@ static void list_features(void)
           msg_putchar('\n');
         }
       } else {
-        while (msg_col % width) {
-          int old_msg_col = msg_col;
-          msg_putchar(' ');
-          if (old_msg_col == msg_col) {
-            break;  // XXX: Avoid infinite loop.
-          }
-        }
+        msg_putchar(' ');
       }
     } else {
       if (msg_col > 0) {
@@ -1103,7 +1097,7 @@ static void list_features(void)
       }
     }
   }
-  MSG_PUTS("For differences from Vim, see :help vim-differences\n\n");
+  MSG_PUTS("See \":help feature-compile\"\n\n");
 }
 
 void list_version(void)
@@ -1144,7 +1138,7 @@ void list_version(void)
   }
 #endif  // ifdef HAVE_PATHDEF
 
-  version_msg(_("\n\nOptional features included (+) or not (-): "));
+  version_msg(_("\n\nFeatures: "));
 
   list_features();
 
@@ -1216,7 +1210,6 @@ void intro_message(int colon)
   static char *(lines[]) = {
     N_(NVIM_VERSION_LONG),
     "",
-    N_("by al."),
     N_("Nvim is open source and freely distributable"),
     N_("https://neovim.io/community"),
     "",