docs: misc #41063

runtime/doc/autocmd.txt

@@ -1401,10 +1401,13 @@ VimLeavePre			Before exiting Vim, just before writing the
 				Not triggered if |v:dying| is 2 or more.
 
 							*VimResized*
-VimResized			After the Vim window was resized, thus 'lines'
+VimResized			After Nvim itself was resized: 'lines' and/or
-				and/or 'columns' changed.  Not when starting
+				'columns' changed.  But not during |startup|.
-				up though.
 
+				To ensure the window layout is always
+				"equalized" on resize: >
+				    :autocmd VimResized * wincmd =
+<
 							*VimResume*
 VimResume			After Nvim resumes from |suspend| state.
 

runtime/doc/lua.txt

@@ -2647,10 +2647,8 @@ vim.fs.dir({path}, {opts})                                      *vim.fs.dir()*
                   skipping.
                 • {follow}? (`boolean`, default: `false`) Follow symbolic
                   links.
-                • {normalize}? (`boolean`, default: `true`) Normalize {path}
+                • {normalize}? (`boolean`, default: `true`) Expand "~" and "$"
-                  via |vim.fs.normalize()|. Set `false` to use {path}
+                  in {path} before scanning the directory.
-                  literally, e.g. to list a directory whose name contains `~`
-                  or `$`.
                 • {skip}? (`fun(dir_name: string): boolean`) Predicate to
                   control traversal. Return false to stop searching the
                   current directory. Only useful when depth > 1 Return an
@@ -2797,11 +2795,10 @@ vim.fs.mkdir({path}, {opts})                                  *vim.fs.mkdir()*
                   directories as necessary.
 
 vim.fs.normalize({path}, {opts})                          *vim.fs.normalize()*
-    Normalize a path to a standard format. A tilde (~) character at the
+    Normalize a path to a standard format. Expands environment variables, and
-    beginning of the path is expanded to the user's home directory and
+    tilde "~" at the beginning of the path. Resolves "." and ".." components,
-    environment variables are also expanded. "." and ".." components are also
+    except when the path is relative and resolving it would produce an
-    resolved, except when the path is relative and trying to resolve it would
+    absolute path.
-    result in an absolute path.
     • "." as the only part in a relative path:
       • "." => "."
       • "././" => "."
@@ -2811,19 +2808,19 @@ vim.fs.normalize({path}, {opts})                          *vim.fs.normalize()*
     • ".." in the root directory returns the root directory.
       • "/../../" => "/"
 
-    On Windows, backslash (\) characters are converted to forward slashes (/).
+    On Windows, backslashes (`\`) are converted to forward slashes (`/`).
 
-    Examples: >
+    Examples: >lua
-        [[C:\Users\jdoe]]                         => "C:/Users/jdoe"
+        [[C:\Users\jdoe]]                         --> "C:/Users/jdoe"
-        "~/src/neovim"                            => "/home/jdoe/src/neovim"
+        "~/src/neovim"                            --> "/home/jdoe/src/neovim"
-        "$XDG_CONFIG_HOME/nvim/init.vim"          => "/Users/jdoe/.config/nvim/init.vim"
+        "$XDG_CONFIG_HOME/nvim/init.vim"          --> "/Users/jdoe/.config/nvim/init.vim"
-        "~/src/nvim/api/../tui/./tui.c"           => "/home/jdoe/src/nvim/tui/tui.c"
+        "~/src/nvim/api/../tui/./tui.c"           --> "/home/jdoe/src/nvim/tui/tui.c"
-        "./foo/bar"                               => "foo/bar"
+        "./foo/bar"                               --> "foo/bar"
-        "foo/../../../bar"                        => "../../bar"
+        "foo/../../../bar"                        --> "../../bar"
-        "/home/jdoe/../../../bar"                 => "/bar"
+        "/home/jdoe/../../../bar"                 --> "/bar"
-        "C:foo/../../baz"                         => "C:../baz"
+        "C:foo/../../baz"                         --> "C:../baz"
-        "C:/foo/../../baz"                        => "C:/baz"
+        "C:/foo/../../baz"                        --> "C:/baz"
-        [[\\?\UNC\server\share\foo\..\..\..\bar]] => "//?/UNC/server/share/bar"
+        [[\\?\UNC\server\share\foo\..\..\..\bar]] --> "//?/UNC/server/share/bar"
 <
 
     Attributes: ~

runtime/doc/news.txt

@@ -315,6 +315,7 @@ LUA
   write binary data.
 • |vim.fs.dir()| with `opts.err=true`, reports errors. An inaccessible root
   dir yields a single (name, nil, err) item.
+• |vim.fs.dir()| gained a `normalize` parameter.
 • |vim.fs.find()| returns a list of errors as its second return value.
 • |vim.fs.mkdir()| creates directories, including parent directories with
   `opts.parents=true`.

runtime/doc/windows.txt

@@ -562,13 +562,18 @@ CTRL-W T	Move the current window to a new tabpage.  This fails if
 
 						*CTRL-W_=*
 CTRL-W =	Make all windows (almost) equally high and wide, but use
-		'winheight' and 'winwidth' for the current window.
+		'winheight' and 'winwidth' for the current window. Windows
-		Windows with 'winfixheight' set keep their height and windows
+		with 'winfixheight' set keep their height, and windows with
-		with 'winfixwidth' set keep their width.
+		'winfixwidth' set keep their width.
-		To equalize only vertically (make window equally high) use
+
-		`vertical wincmd =` .
+		To equalize only vertically (each window equally high) use: >
-		To equalize only horizontally (make window equally wide) use
+		    :vertical wincmd =
-		`horizontal wincmd =` .
+<
+		To equalize only horizontally (each window equally wide) use: >
+		    :horizontal wincmd =
+<
+		To equalize windows when Nvim itself is resized, see
+		|VimResized|.
 
 :res[ize] -N					*:res* *:resize* *CTRL-W_-*
 CTRL-W -	Decrease current window height by N (default 1).

runtime/lua/vim/fs.lua

@@ -191,8 +191,7 @@ end
 --- (default: `false`)
 --- @field follow? boolean
 ---
---- Normalize {path} via |vim.fs.normalize()|. Set `false` to use {path} literally, e.g. to list a
+--- Expand "~" and "$" in {path} before scanning the directory.
---- directory whose name contains `~` or `$`.
 --- (default: `true`)
 --- @field normalize? boolean
 
@@ -678,10 +677,10 @@ end
 --- (default: `true` in Windows, `false` otherwise)
 --- @field win? boolean
 
---- Normalize a path to a standard format. A tilde (~) character at the beginning of the path is
+--- Normalize a path to a standard format. Expands environment variables, and tilde "~" at the
---- expanded to the user's home directory and environment variables are also expanded. "." and ".."
+--- beginning of the path. Resolves "." and ".." components, except when the path is relative and
---- components are also resolved, except when the path is relative and trying to resolve it would
+--- resolving it would produce an absolute path.
---- result in an absolute path.
+---
 --- - "." as the only part in a relative path:
 ---   - "." => "."
 ---   - "././" => "."
@@ -691,20 +690,20 @@ end
 --- - ".." in the root directory returns the root directory.
 ---   - "/../../" => "/"
 ---
---- On Windows, backslash (\) characters are converted to forward slashes (/).
+--- On Windows, backslashes (`\`) are converted to forward slashes (`/`).
 ---
 --- Examples:
---- ```
+--- ```lua
---- [[C:\Users\jdoe]]                         => "C:/Users/jdoe"
+--- [[C:\Users\jdoe]]                         --> "C:/Users/jdoe"
---- "~/src/neovim"                            => "/home/jdoe/src/neovim"
+--- "~/src/neovim"                            --> "/home/jdoe/src/neovim"
---- "$XDG_CONFIG_HOME/nvim/init.vim"          => "/Users/jdoe/.config/nvim/init.vim"
+--- "$XDG_CONFIG_HOME/nvim/init.vim"          --> "/Users/jdoe/.config/nvim/init.vim"
---- "~/src/nvim/api/../tui/./tui.c"           => "/home/jdoe/src/nvim/tui/tui.c"
+--- "~/src/nvim/api/../tui/./tui.c"           --> "/home/jdoe/src/nvim/tui/tui.c"
---- "./foo/bar"                               => "foo/bar"
+--- "./foo/bar"                               --> "foo/bar"
---- "foo/../../../bar"                        => "../../bar"
+--- "foo/../../../bar"                        --> "../../bar"
---- "/home/jdoe/../../../bar"                 => "/bar"
+--- "/home/jdoe/../../../bar"                 --> "/bar"
---- "C:foo/../../baz"                         => "C:../baz"
+--- "C:foo/../../baz"                         --> "C:../baz"
---- "C:/foo/../../baz"                        => "C:/baz"
+--- "C:/foo/../../baz"                        --> "C:/baz"
---- [[\\?\UNC\server\share\foo\..\..\..\bar]] => "//?/UNC/server/share/bar"
+--- [[\\?\UNC\server\share\foo\..\..\..\bar]] --> "//?/UNC/server/share/bar"
 --- ```
 ---
 ---@since 10