docs: more pane related docs

ci/generate-docs.py

@@ -134,6 +134,7 @@ clear and convenient.
 
 """,
                     ),
+                    Page("object: SpawnCommand", "config/lua/SpawnCommand.md"),
                     Gen(
                         "object: Pane",
                         "config/lua/pane",

docs/config/launch.markdown

@@ -83,6 +83,9 @@ the option of connecting and spawning tabs/windows in those domains.
 the menu; one that runs the `top` program to monitor process activity and a
 second one that explicitly launches the `bash` shell.
 
+Each entry in `launch_menu` is an instance of a
+[SpawnCommand](lua/SpawnCommand.md) object.
+
 ```lua
 return {
   launch_menu = {

docs/config/lua/SpawnCommand.md

@@ -0,0 +1,62 @@
+# SpawnCommand
+
+The `SpawnCommand` struct specifies information about a new command
+to be spawned.
+
+It is a lua object with the following fields; all of the fields
+have reasonable defaults and can be omitted.
+
+```lua
+{
+  -- An optional label.
+  -- The label is only used for SpawnCommands that are listed in
+  -- the `launch_menu` configuration section.
+  -- If the label is omitted, a default will be produced based
+  -- on the `args` field.
+  label = "List all the files!",
+
+  -- The argument array specifying the command and its arguments.
+  -- If omitted, the default program for the target domain will be
+  -- spawned.
+  args = {"ls", "-al"},
+
+  -- The current working directory to set for the command.
+  -- If omitted, wezterm will infer a value based on the active pane
+  -- at the time this action is triggered.  If the active pane
+  -- matches the domain specified in this `SpawnCommand` instance
+  -- then the current working directory of the active pane will be
+  -- used.
+  -- If the current working directory cannot be inferred then it
+  -- will typically fall back to using the home directory of
+  -- the current user.
+  cwd = "/some/path",
+
+  -- Sets addditional environment variables in the environment for
+  -- this command invocation.
+  set_environment_variables = {
+    SOMETHING = "a value"
+  },
+
+  -- Specifiy that the multiplexer domain of the currently active pane
+  -- should be used to start this process.  This is usually what you
+  -- want to happen and this is the default behavior if you omit
+  -- the domain.
+  domain = "CurrentPaneDomain",
+
+  -- Specify that the default multiplexer domain be used for this
+  -- command invocation.  The default domain is typically the "local"
+  -- domain, which spawns processes locally.  However, if you started
+  -- wezterm using `wezterm connect` or `wezterm serial` then the default
+  -- domain will not be "local".
+  domain = "DefaultDomain",
+
+  -- Specify a named multiplexer domain that should be used to spawn
+  -- this new command.
+  -- This is useful if you want to assign a hotkey to always start
+  -- a process in a remote multiplexer rather than based on the
+  -- current pane.
+  -- See the Multiplexing section of the docs for more on this topic.
+  domain = {DomainName="my.server"},
+}
+```
+

docs/config/lua/keyassignment/EmitEvent.md

@@ -0,0 +1,10 @@
+# EmitEvent
+
+*Since: nightly builds only*
+
+This action causes the equivalent of `wezterm.emit(name, window, pane)` to be
+called in the context of the current pane.
+
+See [the Custom Events example](../wezterm/on.md#custom-events) for a detailed
+example of using this action.
+

docs/config/lua/keyassignment/SpawnCommandInNewTab.md

@@ -1,16 +1,8 @@
 ## SpawnCommandInNewTab
 
 Spawn a new tab into the current window.
-The argument controls which command is run in the tab; it is a lua table
-with the following fields:
-
-* `args` - the argument array specifying the command and its arguments.
-  If omitted, the default program will be run.
-* `cwd` - the current working directory to set for the command.
-* `set_environment_variables` - a table specifying key/value pairs to
-  set in the environment
-* `domain` - specifies the domain into which the tab will be spawned.
-  See `SpawnTab` for examples.
+The argument is a `SpawnCommand` struct that is discussed in more
+detail in the [SpawnCommand](../SpawnCommand.md) docs.
 
 ```lua
 local wezterm = require 'wezterm';

docs/config/lua/keyassignment/SpawnCommandInNewWindow.md

@@ -1,16 +1,8 @@
 # SpawnCommandInNewWindow
 
 Spawn a new tab into a brand new window.
-The argument controls which command is run in the tab; it is a lua table
-with the following fields:
-
-* `args` - the argument array specifying the command and its arguments.
-  If omitted, the default program will be run.
-* `cwd` - the current working directory to set for the command.
-* `set_environment_variables` - a table specifying key/value pairs to
-  set in the environment
-* `domain` - specifies the domain into which the tab will be spawned.
-  See `SpawnTab` for examples.
+The argument is a `SpawnCommand` struct that is discussed in more
+detail in the [SpawnCommand](../SpawnCommand.md) docs.
 
 ```lua
 local wezterm = require 'wezterm';

docs/config/lua/keyassignment/SpawnTab.md

@@ -6,10 +6,11 @@ Create a new tab in the current window.  The argument defines to which *domain*
 local wezterm = require 'wezterm';
 return {
   keys = {
+    -- Create a new tab in the same domain as the current pane.
+    -- This is usually what you want.
+    {key="t", mods="SHIFT|ALT", action=wezterm.action{SpawnTab="CurrentPaneDomain"}},
     -- Create a new tab in the default domain
     {key="t", mods="SHIFT|ALT", action=wezterm.action{SpawnTab="DefaultDomain"}},
-    -- Create a new tab in the same domain as the current tab
-    {key="t", mods="SHIFT|ALT", action=wezterm.action{SpawnTab="CurrentPaneDomain"}},
     -- Create a tab in a named domain
     {key="t", mods="SHIFT|ALT", action=wezterm.action{SpawnTab={DomainName="unix"}}},
   }

docs/config/lua/keyassignment/SplitHorizontal.md

@@ -0,0 +1,22 @@
+# SplitHorizontal
+
+*Since: nightly builds only*
+
+Splits the current pane in half horizontally such that the current pane becomes
+the left half and the new right half spawns a new command.
+
+`SplitHorizontal` requires a [SpawnCommand](../SpawnCommand.md) parameter to
+specify what should be spawned into the new split.
+
+```lua
+local wezterm = require 'wezterm';
+
+return {
+  keys = {
+    {key="%", mods="CLTR|SHIFT|ALT", action=wezterm.action{SplitHorizontal={
+      args={"top"}
+    }}},
+  }
+}
+```
+

docs/config/lua/keyassignment/SplitVertical.md

@@ -0,0 +1,22 @@
+# SplitVertical
+
+*Since: nightly builds only*
+
+Splits the current pane in half vertically such that the current pane becomes
+the top half and the new bottom half spawns a new command.
+
+`SplitVertical` requires a [SpawnCommand](../SpawnCommand.md) parameter to
+specify what should be spawned into the new split.
+
+```lua
+local wezterm = require 'wezterm';
+
+return {
+  keys = {
+    {key="\"", mods="CTRL|SHIFT|ALT", action=wezterm.action{SplitVertical={
+      args={"top"}
+    }}},
+  }
+}
+```
+