vim-patch:2190036: runtime(doc): Add environment variable expansion note to options (#36675)

Add "Environment variables are expanded |:set_env|" documentation to
options that have the P_EXPAND flag but were missing this note.

Updated options:
- 'cdpath'
- 'dictionary'
- 'mkspellmem'
- 'packpath'
- 'runtimepath'
- 'spellfile'
- 'spellsuggest'
- 'thesaurus'
- 'ttytype'
- 'undodir'
- 'verbosefile'
- 'viewdir'
- 'viminfofile'

These options support environment variable expansion in their values
(e.g., $HOME, $USER) but the documentation didn't explicitly mention
this capability. This brings their documentation in line with other
options like backupdir, directory, and makeprg that already include
this note.

closes: vim/vim#18791

2190036c8c

Co-authored-by: Alex Plate <AlexPl292@gmail.com>

runtime/doc/options.txt

@@ -1288,7 +1288,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 	a modified version of the following command in your vimrc file to
 	override it: >vim
 	  let &cdpath = ',' .. substitute(substitute($CDPATH, '[, ]', '\\\0', 'g'), ':', ',', 'g')
-<	This option cannot be set from a |modeline| or in the |sandbox|, for
+<	Environment variables are expanded |:set_env|.
+	This option cannot be set from a |modeline| or in the |sandbox|, for
 	security reasons.
 	(parts of 'cdpath' can be passed to the shell to expand file names).
 
@@ -2146,6 +2147,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	To include a comma in a file name precede it with a backslash.  Spaces
 	after a comma are ignored, otherwise spaces are included in the file
 	name.  See |option-backslash| about using backslashes.
+	Environment variables are expanded |:set_env|.
 	This has nothing to do with the |Dictionary| variable type.
 	Where to find a list of words?
 	- BSD/macOS include the "/usr/share/dict/words" file.
@@ -4452,7 +4454,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 		set mkspellmem=900000,3000,800
 <	If you have less than 512 Mbyte |:mkspell| may fail for some
 	languages, no matter what you set 'mkspellmem' to.
-
+	Environment variables are expanded |:set_env|.
 	This option cannot be set from a |modeline| or in the |sandbox|, for
 	security reasons.
 
@@ -4775,6 +4777,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 			global
 	Directories used to find packages.
 	See |packages| and |packages-runtimepath|.
+	Environment variables are expanded |:set_env|.
 	This option cannot be set from a |modeline| or in the |sandbox|, for
 	security reasons.
 
@@ -5231,6 +5234,9 @@ A jump table for the options with a short description can be found at |Q_op|.
 	to find files which add to distributed runtime files.
 
 	With |--clean| the home directory entries are not included.
+	Environment variables are expanded |:set_env|.
+	This option cannot be set from a |modeline| or in the |sandbox|, for
+	security reasons.
 
 						*'scroll'* *'scr'*
 'scroll' 'scr'		number	(default half the window height)
@@ -5532,6 +5538,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	When equal to "NONE" no shada file will be read or written.
 	This option can be set with the |-i| command line flag.  The |--clean|
 	command line flag sets it to "NONE".
+	Environment variables are expanded |:set_env|.
 	This option cannot be set from a |modeline| or in the |sandbox|, for
 	security reasons.
 
@@ -6073,6 +6080,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	name if you want to.  However, it will then only be used when
 	'spellfile' is set to it, for entries in 'spelllang' only files
 	without region name will be found.
+	Environment variables are expanded |:set_env|.
 	This option cannot be set from a |modeline| or in the |sandbox|, for
 	security reasons.
 
@@ -6194,7 +6202,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	Only one of "best", "double" or "fast" may be used.  The others may
 	appear several times in any order.  Example: >vim
 		set sps=file:~/.config/nvim/sugg,best,expr:MySuggest()
-<
+<	Environment variables are expanded |:set_env|.
 	This option cannot be set from a |modeline| or in the |sandbox|, for
 	security reasons.
 
@@ -6873,8 +6881,9 @@ A jump table for the options with a short description can be found at |Q_op|.
 	name.  See |option-backslash| about using backslashes.  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.  Backticks cannot be used in this option for security
+	another default.
-	reasons.
+	Environment variables are expanded |:set_env|.
+	Backticks cannot be used in this option for security reasons.
 
 					*'thesaurusfunc'* *'tsrfu'*
 'thesaurusfunc' 'tsrfu'	string	(default "")
@@ -7009,6 +7018,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	undo file that exists is used.  When it cannot be read an error is
 	given, no further entry is used.
 	See |undo-persistence|.
+	Environment variables are expanded |:set_env|.
 	This option cannot be set from a |modeline| or in the |sandbox|, for
 	security reasons.
 
@@ -7162,6 +7172,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	Setting 'verbosefile' to a new value is like making it empty first.
 	The difference with |:redir| is that verbose messages are not
 	displayed when 'verbosefile' is set.
+	Environment variables are expanded |:set_env|.
 	This option cannot be set from a |modeline| or in the |sandbox|, for
 	security reasons.
 
@@ -7169,6 +7180,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 'viewdir' 'vdir'	string	(default "$XDG_STATE_HOME/nvim/view//")
 			global
 	Name of the directory where to store files for |:mkview|.
+	Environment variables are expanded |:set_env|.
 	This option cannot be set from a |modeline| or in the |sandbox|, for
 	security reasons.
 

runtime/lua/vim/_meta/options.lua

@@ -753,6 +753,7 @@ vim.go.cdh = vim.go.cdhome
 --- ```vim
 ---   let &cdpath = ',' .. substitute(substitute($CDPATH, '[, ]', '\\\0', 'g'), ':', ',', 'g')
 --- ```
+--- Environment variables are expanded `:set_env`.
 --- This option cannot be set from a `modeline` or in the `sandbox`, for
 --- security reasons.
 --- (parts of 'cdpath' can be passed to the shell to expand file names).
@@ -1752,6 +1753,7 @@ vim.go.deco = vim.go.delcombine
 --- To include a comma in a file name precede it with a backslash.  Spaces
 --- after a comma are ignored, otherwise spaces are included in the file
 --- name.  See `option-backslash` about using backslashes.
+--- Environment variables are expanded `:set_env`.
 --- This has nothing to do with the `Dictionary` variable type.
 --- Where to find a list of words?
 --- - BSD/macOS include the "/usr/share/dict/words" file.
@@ -4547,7 +4549,7 @@ vim.go.mopt = vim.go.messagesopt
 --- ```
 --- If you have less than 512 Mbyte `:mkspell` may fail for some
 --- languages, no matter what you set 'mkspellmem' to.
----
+--- Environment variables are expanded `:set_env`.
 --- This option cannot be set from a `modeline` or in the `sandbox`, for
 --- security reasons.
 ---
@@ -4931,6 +4933,7 @@ vim.go.opfunc = vim.go.operatorfunc
 
 --- Directories used to find packages.
 --- See `packages` and `packages-runtimepath`.
+--- Environment variables are expanded `:set_env`.
 --- This option cannot be set from a `modeline` or in the `sandbox`, for
 --- security reasons.
 ---
@@ -5489,6 +5492,9 @@ vim.go.ruf = vim.go.rulerformat
 --- to find files which add to distributed runtime files.
 ---
 --- With `--clean` the home directory entries are not included.
+--- Environment variables are expanded `:set_env`.
+--- This option cannot be set from a `modeline` or in the `sandbox`, for
+--- security reasons.
 ---
 --- @type string
 vim.o.runtimepath = "..."
@@ -5832,6 +5838,7 @@ vim.go.sd = vim.go.shada
 --- When equal to "NONE" no shada file will be read or written.
 --- This option can be set with the `-i` command line flag.  The `--clean`
 --- command line flag sets it to "NONE".
+--- Environment variables are expanded `:set_env`.
 --- This option cannot be set from a `modeline` or in the `sandbox`, for
 --- security reasons.
 ---
@@ -6487,6 +6494,7 @@ vim.bo.spc = vim.bo.spellcapcheck
 --- name if you want to.  However, it will then only be used when
 --- 'spellfile' is set to it, for entries in 'spelllang' only files
 --- without region name will be found.
+--- Environment variables are expanded `:set_env`.
 --- This option cannot be set from a `modeline` or in the `sandbox`, for
 --- security reasons.
 ---
@@ -6623,7 +6631,7 @@ vim.bo.spo = vim.bo.spelloptions
 --- ```vim
 --- 	set sps=file:~/.config/nvim/sugg,best,expr:MySuggest()
 --- ```
----
+--- Environment variables are expanded `:set_env`.
 --- This option cannot be set from a `modeline` or in the `sandbox`, for
 --- security reasons.
 ---
@@ -7438,8 +7446,9 @@ vim.bo.tw = vim.bo.textwidth
 --- name.  See `option-backslash` about using backslashes.  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.  Backticks cannot be used in this option for security
+--- another default.
---- reasons.
+--- Environment variables are expanded `:set_env`.
+--- Backticks cannot be used in this option for security reasons.
 ---
 --- @type string
 vim.o.thesaurus = ""
@@ -7610,6 +7619,7 @@ vim.go.ttm = vim.go.ttimeoutlen
 --- undo file that exists is used.  When it cannot be read an error is
 --- given, no further entry is used.
 --- See `undo-persistence`.
+--- Environment variables are expanded `:set_env`.
 --- This option cannot be set from a `modeline` or in the `sandbox`, for
 --- security reasons.
 ---
@@ -7803,6 +7813,7 @@ vim.go.vbs = vim.go.verbose
 --- Setting 'verbosefile' to a new value is like making it empty first.
 --- The difference with `:redir` is that verbose messages are not
 --- displayed when 'verbosefile' is set.
+--- Environment variables are expanded `:set_env`.
 --- This option cannot be set from a `modeline` or in the `sandbox`, for
 --- security reasons.
 ---
@@ -7813,6 +7824,7 @@ vim.go.verbosefile = vim.o.verbosefile
 vim.go.vfile = vim.go.verbosefile
 
 --- Name of the directory where to store files for `:mkview`.
+--- Environment variables are expanded `:set_env`.
 --- This option cannot be set from a `modeline` or in the `sandbox`, for
 --- security reasons.
 ---

src/nvim/options.lua

@@ -1080,7 +1080,8 @@ local options = {
         a modified version of the following command in your vimrc file to
         override it: >vim
           let &cdpath = ',' .. substitute(substitute($CDPATH, '[, ]', '\\\0', 'g'), ':', ',', 'g')
-        <	This option cannot be set from a |modeline| or in the |sandbox|, for
+        <	Environment variables are expanded |:set_env|.
+        This option cannot be set from a |modeline| or in the |sandbox|, for
         security reasons.
         (parts of 'cdpath' can be passed to the shell to expand file names).
       ]=],
@@ -2300,6 +2301,7 @@ local options = {
         To include a comma in a file name precede it with a backslash.  Spaces
         after a comma are ignored, otherwise spaces are included in the file
         name.  See |option-backslash| about using backslashes.
+        Environment variables are expanded |:set_env|.
         This has nothing to do with the |Dictionary| variable type.
         Where to find a list of words?
         - BSD/macOS include the "/usr/share/dict/words" file.
@@ -5892,7 +5894,7 @@ local options = {
         	set mkspellmem=900000,3000,800
         <	If you have less than 512 Mbyte |:mkspell| may fail for some
         languages, no matter what you set 'mkspellmem' to.
-
+        Environment variables are expanded |:set_env|.
         This option cannot be set from a |modeline| or in the |sandbox|, for
         security reasons.
       ]=],
@@ -6480,6 +6482,7 @@ local options = {
       desc = [=[
         Directories used to find packages.
         See |packages| and |packages-runtimepath|.
+        Environment variables are expanded |:set_env|.
         This option cannot be set from a |modeline| or in the |sandbox|, for
         security reasons.
       ]=],
@@ -7209,6 +7212,9 @@ local options = {
         to find files which add to distributed runtime files.
 
         With |--clean| the home directory entries are not included.
+        Environment variables are expanded |:set_env|.
+        This option cannot be set from a |modeline| or in the |sandbox|, for
+        security reasons.
       ]=],
       expand = 'nodefault',
       full_name = 'runtimepath',
@@ -7660,6 +7666,7 @@ local options = {
         When equal to "NONE" no shada file will be read or written.
         This option can be set with the |-i| command line flag.  The |--clean|
         command line flag sets it to "NONE".
+        Environment variables are expanded |:set_env|.
         This option cannot be set from a |modeline| or in the |sandbox|, for
         security reasons.
       ]=],
@@ -8501,6 +8508,7 @@ local options = {
         name if you want to.  However, it will then only be used when
         'spellfile' is set to it, for entries in 'spelllang' only files
         without region name will be found.
+        Environment variables are expanded |:set_env|.
         This option cannot be set from a |modeline| or in the |sandbox|, for
         security reasons.
       ]=],
@@ -8661,7 +8669,7 @@ local options = {
         Only one of "best", "double" or "fast" may be used.  The others may
         appear several times in any order.  Example: >vim
         	set sps=file:~/.config/nvim/sugg,best,expr:MySuggest()
-        <
+        <	Environment variables are expanded |:set_env|.
         This option cannot be set from a |modeline| or in the |sandbox|, for
         security reasons.
       ]=],
@@ -9627,8 +9635,9 @@ local options = {
         name.  See |option-backslash| about using backslashes.  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.  Backticks cannot be used in this option for security
+        another default.
-        reasons.
+        Environment variables are expanded |:set_env|.
+        Backticks cannot be used in this option for security reasons.
       ]=],
       expand = true,
       full_name = 'thesaurus',
@@ -9860,6 +9869,7 @@ local options = {
         undo file that exists is used.  When it cannot be read an error is
         given, no further entry is used.
         See |undo-persistence|.
+        Environment variables are expanded |:set_env|.
         This option cannot be set from a |modeline| or in the |sandbox|, for
         security reasons.
 
@@ -10090,6 +10100,7 @@ local options = {
         Setting 'verbosefile' to a new value is like making it empty first.
         The difference with |:redir| is that verbose messages are not
         displayed when 'verbosefile' is set.
+        Environment variables are expanded |:set_env|.
         This option cannot be set from a |modeline| or in the |sandbox|, for
         security reasons.
       ]=],
@@ -10106,6 +10117,7 @@ local options = {
       defaults = '',
       desc = [=[
         Name of the directory where to store files for |:mkview|.
+        Environment variables are expanded |:set_env|.
         This option cannot be set from a |modeline| or in the |sandbox|, for
         security reasons.
       ]=],