docs: Improve clarity of wezterm.on wrt. callback params and example

Co-authored-by: Wez Furlong <wez@wezfurlong.org>

docs/config/lua/wezterm/on.md

@@ -13,6 +13,10 @@ an ordered list of callbacks is maintained for each event.  When the event
 is emitted, each of the registered callbacks is called in the order that
 they were registered.
 
+The callback will receive the following parameters:
+- a [`window` object](../window/index.md) that represents the active gui window.
+- a [`pane` object](../pane/index.md) that represents the active pane.
+
 If a callback returns `false` it will prevent any callbacks that were registered
 after it from being triggered for the current event.  Some events have
 a defined default action; returning `false` will prevent that default action
@@ -36,55 +40,53 @@ has no special knowledge.  It is recommended that you avoid event names
 that are likely to be used future versions of wezterm in order to avoid
 unexpected behavior if/when those names might be used in future.
 
-The `wezterm.emit` function and the `EmitEvent` key assignment can be used
+The [wezterm.emit](emit.md) function and the [EmitEvent](../keyassignment/EmitEvent.md) key assignment can be used to
 emit events.
 
-In this example, a key is assigned to capture the content of the active
+---
+
+In the following example, a key is assigned to capture the visible content of the active
 pane, write it to a file and then open that file in the `vim` editor:
 
 ```lua
-local wezterm = require 'wezterm';
+local wezterm = require "wezterm"
-local io = require 'io';
+local io = require "io"
-local os = require 'os';
+local os = require "os"
+local act = wezterm.action
 
-wezterm.on("trigger-vim-with-scrollback", function(window, pane)
+wezterm.on("trigger-vim-with-visible-text", function(window, pane)
   -- Retrieve the current viewport's text.
-  -- Pass an optional number of lines (eg: 2000) to retrieve
+  --
-  -- that number of lines starting from the bottom of the viewport.
+  -- Note: You could also pass an optional number of lines (eg: 2000) to
-  local scrollback = pane:get_lines_as_text();
+  -- retrieve that number of lines starting from the bottom of the viewport.
+  local viewport_text = pane:get_lines_as_text()
 
   -- Create a temporary file to pass to vim
-  local name = os.tmpname();
+  local name = os.tmpname()
-  local f = io.open(name, "w+");
+  local f = io.open(name, "w+")
-  f:write(scrollback);
+  f:write(viewport_text)
-  f:flush();
+  f:flush()
-  f:close();
+  f:close()
 
   -- Open a new window running vim and tell it to open the file
-  window:perform_action(wezterm.action{SpawnCommandInNewWindow={
+  window:perform_action(act.SpawnCommandInNewWindow{
-    args={"vim", name}}
+    args={"vim", name}
   }, pane)
 
-  -- wait "enough" time for vim to read the file before we remove it.
+  -- Wait "enough" time for vim to read the file before we remove it.
-  -- The window creation and process spawn are asynchronous
+  -- The window creation and process spawn are asynchronous wrt. running
-  -- wrt. running this script and are not awaitable, so we just pick
+  -- this script and are not awaitable, so we just pick a number.
-  -- a number.  We don't strictly need to remove this file, but it
+  --
-  -- is nice to avoid cluttering up the temporary file directory
+  -- Note: We don't strictly need to remove this file, but it is nice
-  -- location.
+  -- to avoid cluttering up the temporary directory.
-  wezterm.sleep_ms(1000);
+  wezterm.sleep_ms(1000)
-  os.remove(name);
+  os.remove(name)
 end)
 
 return {
   keys = {
     {key="E", mods="CTRL",
-      action=wezterm.action{EmitEvent="trigger-vim-with-scrollback"}},
+      action=act.EmitEvent("trigger-vim-with-visible-text")},
   }
 }
 ```
-
-The first event parameter is a [`window` object](../window/index.md) that
-represents the gui window.
-
-The second event parameter is a [`pane` object](../pane/index.md) that
-represents the pane.