docs: misc #24163

- Also delete old perl scripts which are not used since 8+ years ago.

fix #23251
fix #27367
ref https://github.com/neovim/neovim/issues/2252#issuecomment-1902662577

Helped-by: Daniel Kongsgaard <dakongsgaard@gmail.com>
Co-authored-by: Kevin Pham <keevan.pham@gmail.com>

1 files changed, 17 insertions, 24 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index c5d656992c..071cdc8ef1 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -592,24 +592,13 @@ A subset of the `vim.*` API is available in threads. This includes:
 ==============================================================================
 VIM.HIGHLIGHT                                                  *vim.highlight*
 
-Nvim includes a function for highlighting a selection on yank.
-
-To enable it, add the following to your `init.vim`: >vim
-    au TextYankPost * silent! lua vim.highlight.on_yank()
-<
-
-You can customize the highlight group and the duration of the highlight via: >vim
-    au TextYankPost * silent! lua vim.highlight.on_yank {higroup="IncSearch", timeout=150}
-<
+vim.highlight.on_yank({opts})                        *vim.highlight.on_yank()*
+    Highlight the yanked text during a |TextYankPost| event.
 
-If you want to exclude visual selections from highlighting on yank, use: >vim
-    au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false}
+    Add the following to your `init.vim`: >vim
+        autocmd TextYankPost * silent! lua vim.highlight.on_yank {higroup='Visual', timeout=300}
 <
 
-
-vim.highlight.on_yank({opts})                        *vim.highlight.on_yank()*
-    Highlight the yanked text
-
     Parameters: ~
       • {opts}  (`table?`) Optional parameters
                 • higroup highlight group for yanked region (default
@@ -4002,18 +3991,22 @@ Iter:flatten({depth})                                         *Iter:flatten()*
         (`Iter`)
 
 Iter:fold({init}, {f})                                           *Iter:fold()*
-    Folds ("reduces") an iterator into a single value.
+    Folds ("reduces") an iterator into a single value.         *Iter:reduce()*
 
     Examples: >lua
         -- Create a new table with only even values
-        local t = { a = 1, b = 2, c = 3, d = 4 }
-        local it = vim.iter(t)
-        it:filter(function(k, v) return v % 2 == 0 end)
-        it:fold({}, function(t, k, v)
-          t[k] = v
-          return t
-        end)
-        -- { b = 2, d = 4 }
+        vim.iter({ a = 1, b = 2, c = 3, d = 4 })
+          :filter(function(k, v) return v % 2 == 0 end)
+          :fold({}, function(acc, k, v)
+            acc[k] = v
+            return acc
+          end) --> { b = 2, d = 4 }
+
+        -- Get the "maximum" item of an iterable.
+        vim.iter({ -99, -4, 3, 42, 0, 0, 7 })
+          :fold({}, function(acc, v)
+            acc.max = math.max(v, acc.max or v) return acc
+          end) --> { max = 42 }
 <
 
     Parameters: ~