Merge remote-tracking branch 'upstream/master' into usermarksusermarks

1 files changed, 82 insertions, 60 deletions

diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index d57a85423c..179bacdb24 100644
--- a/runtime/doc/starting.txt
+++ b/runtime/doc/starting.txt
@@ -9,7 +9,7 @@ Starting Vim						*starting*
                                       Type |gO| to see the table of contents.
 
 ==============================================================================
-Nvim arguments						*vim-arguments*
+Nvim arguments						*cli-arguments*
 
 Most often, Nvim is started to edit a single file with the command: >
 
@@ -31,11 +31,11 @@ filename	One or more file names.  The first one will be the current
 		To avoid a file name starting with a '-' being interpreted as
 		an option, precede the arglist with "--", e.g.: >
 			nvim -- -filename
-<		All arguments after the "--" will be interpreted as file names,
-		no other options or "+command" argument can follow.
+<		All arguments after "--" are interpreted as file names, no
+		other options or "+command" arguments can follow.
 
 							*--*
--		Alias for stdin (standard input).
+`-`		Alias for stdin (standard input).
 		Example: >
 			echo text | nvim - file
 <		"text" is read into buffer 1, "file" is opened as buffer 2.
@@ -82,12 +82,10 @@ argument.
 --help							*-h* *--help* *-?*
 -?
 -h		Give usage (help) message and exit.
-		See |info-message| about capturing the text.
 
 --version						*-v* *--version*
 -v		Print version information and exit.  Same output as for
 		|:version| command.
-		See |info-message| about capturing the text.
 
 							*--clean*
 --clean		Mimics a fresh install of Nvim:
@@ -145,15 +143,12 @@ argument.
 		these commands, independently from "-c" commands.
 
 							*-S*
--S {file}	The {file} will be sourced after the first file has been read.
-		This is an easy way to do the equivalent of: >
+-S [file]	Executes Vimscript or Lua (".lua") [file] after the first file
+		has been read. See also |:source|. If [file] is not given,
+		defaults to "Session.vim". Equivalent to: >
 			-c "source {file}"
-<		It can be mixed with "-c" arguments and repeated like "-c".
-		The limit of 10 "-c" arguments applies here as well.
-		{file} cannot start with a "-".
-
--S		Works like "-S Session.vim".  Only when used as the last
-		argument or when another "-" option follows.
+<		Can be repeated like "-c", subject to the same limit of 10
+		"-c" arguments. {file} cannot start with a "-".
 
 -L							*-L* *-r*
 -r		Recovery mode.  Without a file name argument, a list of
@@ -195,8 +190,9 @@ argument.
 		  -E reads stdin as text (into buffer 1).
 
 -es						*-es* *-Es* *-s-ex* *silent-mode*
--Es		Silent mode (no UI), for scripting.  Unrelated to |-s|.
-		Disables most prompts, messages, warnings and errors.
+-Es		Script mode, aka "silent mode", aka "batch mode". No UI,
+		disables most prompts and messages. Unrelated to |-s|.
+		See also |-S| to run script files.
 
 		-es reads/executes stdin as Ex commands. >
 			printf "put ='foo'\n%%print\n" | nvim -es
@@ -205,18 +201,44 @@ argument.
 		send commands. >
 			printf "foo\n" | nvim -Es +"%print"
 
-<		Output of these commands is displayed (to stdout):
-			:print
+<		These commands display on stdout:
 			:list
 			:number
-			:set      (to display option values)
-		When 'verbose' is set messages are printed to stderr. >
-			echo foo | nvim -V1 -es
+			:print
+			:set
+		With |:verbose| or 'verbose', other commands display on stderr: >
+			nvim -es +":verbose echo 'foo'"
+			nvim -V1 -es +foo
 
-<		User |config| is skipped (unless given with |-u|).
+<		User |config| is skipped unless |-u| was given.
 		Swap file is skipped (like |-n|).
 		User |shada| is loaded (unless "-i NONE" is given).
 
+							*-l*
+-l {script} [args]
+		Executes Lua {script} non-interactively (no UI) with optional
+		[args] after processing any preceding Nvim |cli-arguments|,
+		then exits. Exits 1 on Lua error. See |-S| to run multiple Lua
+		scripts without args, with a UI.
+								    *lua-args*
+		All [args] are treated as {script} arguments and stored in the
+		Lua `_G.arg` global table, thus "-l" ends processing of Nvim
+		arguments. The {script} name is stored at `_G.arg[0]`.
+		
+		Sets 'verbose' to 1 (like "-V1"), so Lua `print()` writes to
+		output.
+
+		Arguments before "-l" are processed before executing {script}.
+		This example quits before executing "foo.lua": >
+			nvim +q -l foo.lua
+<		This loads Lua module "bar" before executing "foo.lua": >
+			nvim +"lua require('bar')" -l foo.lua
+<
+		Skips user |config| unless |-u| was given.
+		Disables plugins unless 'loadplugins' was set.
+		Disables |shada| unless |-i| was given.
+		Disables swapfile (like |-n|).
+
 							*-b*
 -b		Binary mode.  File I/O will only recognize <NL> to separate
 		lines.  The 'expandtab' option will be reset.  The 'textwidth'
@@ -224,9 +246,6 @@ argument.
 		is set.  This is done after reading the |vimrc| but before
 		reading any file in the arglist.  See also |edit-binary|.
 
-							*-l*
--l		Lisp mode.  Sets the 'lisp' and 'showmatch' options on.
-
 							*-A*
 -A		Arabic mode.  Sets the 'arabic' option on.
 
@@ -241,10 +260,10 @@ argument.
 		Example: >
 			nvim -V8
 
--V[N]{filename}
-		Like -V and set 'verbosefile' to {filename}.  Messages are not
-		displayed; instead they are written to the file {filename}.
-		{filename} must not start with a digit.
+-V[N]{file}
+		Like -V and sets 'verbosefile' to {file} (must not start with
+		a digit).  Messages are not displayed, instead they are
+		written to {file}.
 		Example: >
 			nvim -V20vimlog
 <
@@ -403,18 +422,20 @@ accordingly, proceeding as follows:
 	The |-V| argument can be used to display or log what happens next,
 	useful for debugging the initializations.
 
-3. Wait for UI to connect.
+3. Start a server (unless |--listen| was given) and set |v:servername|.
+
+4. Wait for UI to connect.
 	Nvim started with |--embed| waits for the UI to connect before
 	proceeding to load user configuration.
 
-4. Setup |default-mappings| and |default-autocmds|.  Create |popup-menu|.
+5. Setup |default-mappings| and |default-autocmds|.  Create |popup-menu|.
 
-5. Enable filetype and indent plugins.
+6. Enable filetype and indent plugins.
 	This does the same as the command: >
 		:runtime! ftplugin.vim indent.vim
 <	Skipped if the "-u NONE" command line argument was given.
 
-6. Load user config (execute Ex commands from files, environment, …).
+7. Load user config (execute Ex commands from files, environment, …).
 	$VIMINIT environment variable is read as one Ex command line (separate
 	multiple commands with '|' or <NL>).
 					*config* *init.vim* *init.lua* *vimrc* *exrc*
@@ -445,32 +466,33 @@ accordingly, proceeding as follows:
 						*VIMINIT* *EXINIT* *$MYVIMRC*
      b. Locations searched for initializations, in order of preference:
 	-  $VIMINIT environment variable (Ex command line).
-	-  User |config|: $XDG_CONFIG_HOME/nvim/init.vim.
-	-  Other config: {dir}/nvim/init.vim where {dir} is any directory
-	   in $XDG_CONFIG_DIRS.
+	-  User |config|: $XDG_CONFIG_HOME/nvim/init.vim (or init.lua).
+	-  Other config: {dir}/nvim/init.vim (or init.lua) where {dir} is any
+	   directory in $XDG_CONFIG_DIRS.
 	-  $EXINIT environment variable (Ex command line).
 	|$MYVIMRC| is set to the first valid location unless it was already
 	set or when using $VIMINIT.
 
      c. If the 'exrc' option is on (which is NOT the default), the current
-	directory is searched for two files.  The first that exists is used,
-	the others are ignored.
-	-  The file ".nvimrc"
-	-  The file ".exrc"
+	directory is searched for the following files, in order of precedence:
+	- ".nvim.lua"
+	- ".nvimrc"
+	- ".exrc"
+	The first that exists is used, the others are ignored.
 
-7. Enable filetype detection.
+8. Enable filetype detection.
 	This does the same as the command: >
-		:runtime! filetype.lua filetype.vim
+		:runtime! filetype.lua
 <	Skipped if ":filetype off" was called or if the "-u NONE" command line
 	argument was given.
 
-8. Enable syntax highlighting.
+9. Enable syntax highlighting.
 	This does the same as the command: >
 		:runtime! syntax/syntax.vim
 <	Skipped if ":syntax off" was called or if the "-u NONE" command
 	line argument was given.
 
-9. Load the plugin scripts.					*load-plugins*
+10. Load the plugin scripts.					*load-plugins*
 	This does the same as the command: >
 		:runtime! plugin/**/*.vim
 		:runtime! plugin/**/*.lua
@@ -482,13 +504,13 @@ accordingly, proceeding as follows:
 	However, directories in 'runtimepath' ending in "after" are skipped
 	here and only loaded after packages, see below.
 	Loading plugins won't be done when:
-	- The 'loadplugins' option was reset in a vimrc file.
+	- The |'loadplugins'| option was reset in a vimrc file.
 	- The |--noplugin| command line argument is used.
 	- The |--clean| command line argument is used.
 	- The "-u NONE" command line argument is used |-u|.
-	Note that using "-c 'set noloadplugins'" doesn't work, because the
+	Note that using `-c 'set noloadplugins'` doesn't work, because the
 	commands from the command line have not been executed yet.  You can
-	use "--cmd 'set noloadplugins'" or "--cmd 'set loadplugins'" |--cmd|.
+	use `--cmd 'set noloadplugins'` or `--cmd 'set loadplugins'` |--cmd|.
 
 	Packages are loaded.  These are plugins, as above, but found in the
 	"start" directory of each entry in 'packpath'.  Every plugin directory
@@ -500,21 +522,21 @@ accordingly, proceeding as follows:
 	if packages have been found, but that should not add a directory
 	ending in "after".
 
-10. Set 'shellpipe' and 'shellredir'
+11. Set 'shellpipe' and 'shellredir'
 	The 'shellpipe' and 'shellredir' options are set according to the
 	value of the 'shell' option, unless they have been set before.
 	This means that Nvim will figure out the values of 'shellpipe' and
 	'shellredir' for you, unless you have set them yourself.
 
-11. Set 'updatecount' to zero, if "-n" command argument used
+12. Set 'updatecount' to zero, if "-n" command argument used
 
-12. Set binary options if the |-b| flag was given.
+13. Set binary options if the |-b| flag was given.
 
-13. Read the |shada-file|.
+14. Read the |shada-file|.
 
-14. Read the quickfix file if the |-q| flag was given, or exit on failure.
+15. Read the quickfix file if the |-q| flag was given, or exit on failure.
 
-15. Open all windows
+16. Open all windows
 	When the |-o| flag was given, windows will be opened (but not
 	displayed yet).
 	When the |-p| flag was given, tab pages will be created (but not
@@ -524,7 +546,7 @@ accordingly, proceeding as follows:
 	Buffers for all windows will be loaded, without triggering |BufAdd|
 	autocommands.
 
-16. Execute startup commands
+17. Execute startup commands
 	If a |-t| flag was given, the tag is jumped to.
 	Commands given with |-c| and |+cmd| are executed.
 	The starting flag is reset, has("vim_starting") will now return zero.
@@ -1184,7 +1206,7 @@ exactly four MessagePack objects:
                        encoding   Binary, effective 'encoding' value.
                        max_kbyte  Integer, effective |shada-s| limit value.
                        pid        Integer, instance process ID.
-                       *          It is allowed to have any number of
+                       `*`          It is allowed to have any number of
                                   additional keys with any data.
    2 (SearchPattern)   Map containing data describing last used search or
                        substitute pattern.  Normally ShaDa file contains two
@@ -1215,7 +1237,7 @@ exactly four MessagePack objects:
                        sp   Binary   N/A      Actual pattern.  Required.
                        sb   Boolean  false    True if search direction is
                                               backward.
-                       *    any      none     Other keys are allowed for
+                       `*`    any      none     Other keys are allowed for
                                               compatibility reasons, see
                                               |shada-compatibility|.
    3 (SubString)       Array containing last |:substitute| replacement string.
@@ -1286,7 +1308,7 @@ exactly four MessagePack objects:
                                                GlobalMark and LocalMark
                                                entries.
                        f    Binary    N/A      File name.  Required.
-                       *    any       none     Other keys are allowed for
+                       `*`    any       none     Other keys are allowed for
                                                compatibility reasons, see
                                                |shada-compatibility|.
    9 (BufferList)      Array containing maps.  Each map in the array
@@ -1296,10 +1318,10 @@ exactly four MessagePack objects:
                                                greater then zero.
                        c    UInteger  0        Position column number.
                        f    Binary    N/A      File name.  Required.
-                       *    any       none     Other keys are allowed for
+                       `*`    any       none     Other keys are allowed for
                                                compatibility reasons, see
                                                |shada-compatibility|.
-   * (Unknown)         Any other entry type is allowed for compatibility
+   `*` (Unknown)         Any other entry type is allowed for compatibility
                        reasons, see |shada-compatibility|.
 
 								*E575* *E576*
@@ -1359,7 +1381,7 @@ LOG FILE					*$NVIM_LOG_FILE* *E5430*
 Besides 'debug' and 'verbose', Nvim keeps a general log file for internal
 debugging, plugins and RPC clients. >
 	:echo $NVIM_LOG_FILE
-By default, the file is located at stdpath('log')/log unless that path
+By default, the file is located at stdpath("log")/log unless that path
 is inaccessible or if $NVIM_LOG_FILE was set before |startup|.