From 3556c15f358b818f00cafb58f9db64d4e1e4d406 Mon Sep 17 00:00:00 2001
From: Wez Furlong <wez@wezfurlong.org>
Date: Sat, 25 Jun 2022 06:10:41 -0700
Subject: [PATCH] docs: wezterm.action ergnomics

I forgot about this! This is in the most recent release.

refs: https://github.com/wez/wezterm/issues/1150
---
 docs/changelog.md                 |  1 +
 docs/config/lua/wezterm/action.md | 79 +++++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+)

diff --git a/docs/changelog.md b/docs/changelog.md
index b33fca97b..97692834c 100644
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -70,6 +70,7 @@ As features stabilize some brief notes about them will accumulate here.
 * Windows: [allow_win32_input_mode](config/lua/config/allow_win32_input_mode.md) now defaults to `true` and enables using [win32-input-mode](https://github.com/microsoft/terminal/blob/main/doc/specs/%234999%20-%20Improved%20keyboard%20handling%20in%20Conpty.md) to send high-fidelity keyboard input to ConPTY. This means that win32 console applications, such as [FAR Manager](https://github.com/FarGroup/FarManager) that use the low level `INPUT_RECORD` API will now receive key-up events as well as events for modifier-only key presses. [#1509](https://github.com/wez/wezterm/issues/1509) [#2009](https://github.com/wez/wezterm/issues/2009) [#2098](https://github.com/wez/wezterm/issues/2098) [#1904](https://github.com/wez/wezterm/issues/1904)
 * Wayland: [enable_wayland](config/lua/config/enable_wayland.md) now defaults to `true`. [#2104](https://github.com/wez/wezterm/issues/2104)
 * [exit_behavior](config/lua/config/exit_behavior.md) now defaults to `"Close"`. [#2105](https://github.com/wez/wezterm/issues/2105)
+* Improved [wezterm.action](config/lua/wezterm/action.md) syntax for slightly more ergnomic and understandable key assignments. [#1150](https://github.com/wez/wezterm/issues/1150)
 
 #### Fixed
 * Flush after replying to `XTGETTCAP`, `DECRQM`, `XTVERSION`, `DA2`, `DA3` [#2060](https://github.com/wez/wezterm/issues/2060) [#1850](https://github.com/wez/wezterm/issues/1850) [#1950](https://github.com/wez/wezterm/issues/1950)
diff --git a/docs/config/lua/wezterm/action.md b/docs/config/lua/wezterm/action.md
index c72415797..ace5d408c 100644
--- a/docs/config/lua/wezterm/action.md
+++ b/docs/config/lua/wezterm/action.md
@@ -5,6 +5,85 @@ This is really just sugar for the underlying Lua -> Rust deserialation
 mapping that makes it a bit easier to identify where syntax errors may
 exist in your configuration file.
 
+## Constructor Syntax
+
+*Since: 20220624-141144-bd1b7c5d*
+
+`wezterm.action` is a special enum constructor type that makes it bit
+more ergonomic to express the various actions than in earlier releases.
+The older syntax is still supported, so you needn't scramble to update
+your configuration files.
+
+Indexing `wezterm.action` with a valid
+[KeyAssignment](../keyassignment/index.md) name will act as a constructor for
+that key assignment type.  For example, the lua expression:
+
+```lua
+wezterm.action.QuickSelectArgs
+```
+
+is a constructor for [QuickSelectArgs](../keyassignment/QuickSelectArgs.md).
+
+If the key assignment type is a *unit variant* (has no parameters) such as
+[Copy](../keyassignment/Copy.md), or can be constructed with default values
+such as [QuickSelectArgs](../keyassignment/QuickSelectArgs.md) then you can
+reference the constructor directly to have it evaluate as that value without
+having to add any extra punctuation:
+
+```lua
+local wezterm = require 'wezterm'
+return {
+   keys = {
+     {key=" ", mods="CTRL|SHIFT", action=wezterm.action.QuickSelectArgs},
+   }
+}
+```
+
+You may pass the optional parameters to `QuickSelectArgs` as you need
+them, like this:
+
+```lua
+local wezterm = require 'wezterm'
+return {
+   keys = {
+     {key=" ", mods="CTRL|SHIFT", action=wezterm.action.QuickSelectArgs{
+      alphabet="abc"
+     }},
+   }
+}
+```
+
+If the key assignment type is a *tuple variant* (has positional parameters)
+such as [ActivatePaneByIndex](../keyassignment/ActivatePaneByIndex.md), then
+you can pass those by calling the constructor:
+
+```lua
+local wezterm = require 'wezterm'
+-- shortcut to save typing below
+local act = wezterm.action
+
+return {
+   keys = {
+     {key="F1", mods="ALT", action=act.ActivatePaneByIndex(0)},
+     {key="F2", mods="ALT", action=act.ActivatePaneByIndex(1)},
+     {key="F3", mods="ALT", action=act.ActivatePaneByIndex(2)},
+     {key="F4", mods="ALT", action=act.ActivatePaneByIndex(3)},
+     {key="F5", mods="ALT", action=act.ActivatePaneByIndex(4)},
+     {key="F6", mods="ALT", action=act.ActivatePaneByIndex(5)},
+     {key="F7", mods="ALT", action=act.ActivatePaneByIndex(6)},
+     {key="F8", mods="ALT", action=act.ActivatePaneByIndex(7)},
+     {key="F9", mods="ALT", action=act.ActivatePaneByIndex(8)},
+     {key="F10", mods="ALT", action=act.ActivatePaneByIndex(9)},
+
+     -- Compare this with the older syntax shown in the section below
+     {key="{", mods="CTRL", action=act.ActivateTabRelative(-1)},
+     {key="}", mods="CTRL", action=act.ActivateTabRelative(1)},
+   }
+}
+```
+
+## Older versions
+
 Usage looks like this:
 
 ```lua