docs: document various missing things

refs: https://github.com/wez/wezterm/issues/63
refs: https://github.com/wez/wezterm/issues/461

ci/generate-docs.py

@@ -215,7 +215,10 @@ clear and convenient.
 
 """,
                     ),
+                    Page("object: SshDomain", "config/lua/SshDomain.md"),
                     Page("object: SpawnCommand", "config/lua/SpawnCommand.md"),
+                    Page("object: TlsDomainClient", "config/lua/TlsDomainClient.md"),
+                    Page("object: TlsDomainServer", "config/lua/TlsDomainServer.md"),
                     Gen(
                         "object: Pane",
                         "config/lua/pane",

docs/config/keys.md

@@ -275,6 +275,66 @@ return {
 }
 ```
 
+### Using Raw/Scan Codes for key bindings
+
+In some cases it is desirable to assign keys based on their
+physical position rather than their mapped value--perhaps you
+regularly switch between different regional keymaps but you always
+want CTRL-SHIFT plus a number to switch to a tab by ordinal
+position, and you don't want to define the mapping in terms of `!`,
+`@` etc. in the US map and whatever those keys are in some other
+regional keymap.
+
+You can achieve this by matching the `raw_key` value for the key.
+`raw_key` values are hardware and windowing system dependent
+values, so there is no portable way to list which key does what.
+To discover these values, you can set [debug_key_events =
+true](lua/config/debug_key_events.md) and press the keys of
+interest.
+
+You can specify a raw key value of 123 by using `key="raw:123"` in your config
+rather than one of the other key values.
+
+On my linux system the number key row produces sequential raw key values so I
+use configuration like this to enable this key binding; notice how the numbers
+are different between wayland and X11 on the same system!
+
+```lua
+local wezterm = require 'wezterm';
+local keys = {};
+local enable_wayland = false;
+
+if wezterm.target_triple == "x86_64-unknown-linux-gnu" then
+  -- rebind CTRL+SHIFT+<number> to switch to a tab.
+  if os.getenv("WAYLAND_DISPLAY") and enable_wayland then
+    local tab_no = 0
+    for i = 2, 9 do
+      table.insert(keys, {
+        key="raw:"..tostring(i),
+        mods="CTRL|SHIFT",
+        action=wezterm.action{ActivateTab=tab_no},
+      })
+      tab_no = tab_no + 1
+    end
+  else
+    local tab_no = 0
+    for i = 10, 20 do
+      table.insert(keys, {
+        key="raw:"..tostring(i),
+        mods="CTRL|SHIFT",
+        action=wezterm.action{ActivateTab=tab_no},
+      })
+      tab_no = tab_no + 1
+    end
+  end
+end
+
+return {
+  keys = keys,
+  enable_wayland = enable_wayland,
+}
+```
+
 # Available Actions
 
 See the [`KeyAssignment` reference](lua/keyassignment/index.md) for information

docs/config/lua/SshDomain.md

@@ -0,0 +1,37 @@
+# SshDomain
+
+The `SshDomain` struct specifies information about an individual
+[SSH Domain](../../multiplexing.md#ssh-domains).
+
+It is a lua object with the following fields:
+
+```lua
+{
+    -- The name of this specific domain.  Must be unique amongst
+    -- all types of domain in the configuration file.
+    name = "my.server",
+
+    -- identifies the host:port pair of the remote server
+    -- Can be a DNS name or an IP address with an optional
+    -- ":port" on the end.
+    remote_address = "192.168.1.1",
+
+    -- Whether agent auth should be disabled.
+    -- Set to true to disable it.
+    -- no_agent_auth = false,
+
+    -- The username to use for authenticating with the remote host
+    username = "yourusername",
+
+    -- If true, connect to this domain automatically at startup
+    -- connect_automatically = true,
+
+    -- Specify an alternative read timeout
+    -- timeout = 60,
+
+    -- The path to the wezterm binary on the remote host.
+    -- Primarily useful if it isn't installed in the $PATH
+    -- that is configure for ssh.
+    -- remote_wezterm_path = "/home/yourusername/bin/wezterm"
+}
+```

docs/config/lua/TlsDomainClient.md

@@ -0,0 +1,67 @@
+# TlsDomainClient
+
+The `TlsDomainClient` struct specifies information about how to connect
+to a [TLS Domain](../../multiplexing.md#tls-domains).
+
+It is a lua object with the following fields:
+
+```lua
+{
+    -- The name of this specific domain.  Must be unique amongst
+    -- all types of domain in the configuration file.
+    name = "server.name",
+
+    -- If set, use ssh to connect, start the server, and obtain
+    -- a certificate.
+    -- The value is "user@host:port", just like "wezterm ssh" accepts.
+    bootstrap_via_ssh = "server.hostname",
+
+    -- identifies the host:port pair of the remote server.
+    remote_address = "server.hostname:8080",
+
+    -- the path to an x509 PEM encoded private key file.
+    -- Omit this if you are using `bootstrap_via_ssh`.
+    -- pem_private_key = "/some/path/key.pem",
+
+    -- the path to an x509 PEM encoded certificate file
+    -- Omit this if you are using `bootstrap_via_ssh`.
+    -- pem_cert = "/some/path/cert.pem",
+
+    -- the path to an x509 PEM encoded CA chain file
+    -- Omit this if you are using `bootstrap_via_ssh`.
+    -- pem_ca = "/some/path/ca.pem",
+
+    -- A set of paths to load additional CA certificates.
+    -- Each entry can be either the path to a directory or to a PEM encoded
+    -- CA file.  If an entry is a directory, then its contents will be
+    -- loaded as CA certs and added to the trust store.
+    -- Omit this if you are using `bootstrap_via_ssh`.
+    -- pem_root_certs = { "/some/path/ca1.pem", "/some/path/ca2.pem" },
+
+    -- explicitly control whether the client checks that the certificate
+    -- presented by the server matches the hostname portion of
+    -- `remote_address`.  The default is true.  This option is made
+    -- available for troubleshooting purposes and should not be used outside
+    -- of a controlled environment as it weakens the security of the TLS
+    -- channel.
+    -- accept_invalid_hostnames = false,
+
+    -- the hostname string that we expect to match against the common name
+    -- field in the certificate presented by the server.  This defaults to
+    -- the hostname portion of the `remote_address` configuration and you
+    -- should not normally need to override this value.
+    -- expected_cn = "other.name",
+
+    -- If true, connect to this domain automatically at startup
+    -- connect_automatically = false,
+
+    -- Specify an alternate read timeout
+    -- read_timeout = 60,
+
+    -- Specify an alternate write timeout
+    -- write_timeout = 60,
+
+    -- The path to the wezterm binary on the remote host
+    -- remote_wezterm_path = "/home/myname/bin/wezterm"
+}
+```

docs/config/lua/TlsDomainServer.md

@@ -0,0 +1,34 @@
+# TlsDomainServer
+
+The `TlsDomainServer` struct specifies information about how to define
+the server side of a [TLS Domain](../../multiplexing.md#tls-domains).
+
+It is a lua object with the following fields:
+
+```lua
+{
+    -- The address:port combination on which the server will listen
+    -- for client connections
+    bind_address = "server.hostname:8080",
+
+    -- the path to an x509 PEM encoded private key file.
+    -- You can omit this if your tls_client is using bootstrap_via_ssh.
+    -- pem_private_key = "/path/to/key.pem",
+
+    -- the path to an x509 PEM encoded certificate file.
+    -- You can omit this if your tls_client is using bootstrap_via_ssh.
+    -- pem_cert = "/path/to/cert.pem",
+
+    -- the path to an x509 PEM encoded CA chain file.
+    -- You can omit this if your tls_client is using bootstrap_via_ssh.
+    -- pem_ca = "/path/to/chain.pem",
+
+    -- A set of paths to load additional CA certificates.
+    -- Each entry can be either the path to a directory
+    -- or to a PEM encoded CA file.  If an entry is a directory,
+    -- then its contents will be loaded as CA certs and added
+    -- to the trust store.
+    -- You can omit this if your tls_client is using bootstrap_via_ssh.
+    -- pem_root_certs = { "/some/path/ca1.pem", "/some/path/ca2.pem" },
+}
+```

docs/config/lua/config/adjust_window_size_when_changing_font_size.md

@@ -0,0 +1,10 @@
+# `adjust_window_size_when_changing_font_size = true`
+
+*Since 20210203-095643-70a364eb*
+
+Control whether changing the font size adjusts the dimensions of the window
+(true) or adjusts the number of terminal rows/columns (false). The default is
+true.
+
+If you use a tiling window manager then you may wish to set this to `false`.
+

docs/config/lua/config/daemon_options.md

@@ -0,0 +1,22 @@
+# `daemon_options`
+
+Allows configuring the multiplexer (mux) server and how it places itself into
+the background to run as a daemon process.
+
+You should not normally need to configure this setting; the defaults should
+be sufficient in most cases.
+
+There are three fields supported:
+* `pid_file` - specify the location of the pid and lock file.  The default location is `$XDG_RUNTIME_DIR/wezterm/pid` on X11/Wayland systems, or `$HOME/.local/share/wezterm/pid`
+* `stdout` - specifies where a log of the stdout stream from the daemon will be placed.  The default is `$XDG_RUNTIME_DIR/wezterm/stdout` on X11/Wayland systems, or `$HOME/.local/share/wezterm/stdout`.
+* `stderr` - specifies where a log of the stderr stream from the daemon will be placed.  The default is `$XDG_RUNTIME_DIR/wezterm/stderr` on X11/Wayland systems, or `$HOME/.local/share/wezterm/stderr`.
+
+```lua
+return {
+  daemon_options = {
+    stdout = "/some/where/stdout",
+    stderr = "/some/where/stderr",
+    pid_file = "/some/where/pid_file",
+  }
+}
+```

docs/config/lua/config/debug_key_events.md

@@ -0,0 +1,54 @@
+# `debug_key_events = false`
+
+When set to true, each key event will be logged by the GUI layer as an INFO
+level log message on the stderr stream from wezterm.  **You will typically need
+to launch `wezterm` directly from another terminal to see this logging**.
+
+This can be helpful in figuring out how keys are being decoded on your system,
+or for discovering the system-dependent "raw" key code values.
+
+```lua
+return {
+  debug_key_events = true,
+}
+```
+
+Produces logs like the following when typing `ls`: (artificially wrapped
+to make these docs more readable):
+
+```
+ 2021-02-20T17:04:28.149Z INFO  wezterm_gui::gui::termwindow   > key_event 
+   KeyEvent { key: Char('l'), modifiers: NONE, raw_key: None,
+   raw_modifiers: NONE, raw_code: Some(46), repeat_count: 1, key_is_down: true }
+ 2021-02-20T17:04:28.605Z INFO  wezterm_gui::gui::termwindow   > key_event
+   KeyEvent { key: Char('s'), modifiers: NONE, raw_key: None, raw_modifiers: NONE,
+   raw_code: Some(39), repeat_count: 1, key_is_down: true }
+```
+
+The key event has a number of fields:
+
+* `key` is the decoded key after keymapping and composition effects.  For
+  example `Char('l')` occurs when typing the `l` key and `Char('L')` occurs
+  when doing the same but with `SHIFT` held down.  It could also be one
+  of the keycode identifiers listed in
+  [the Configuring Key Assignments](../../keys.md#configuring-key-assignments)
+  section.
+* `modifiers` indicates which modifiers are active after keymapping and composition
+  effects.  For example, typing `l` with `SHIFT` held down produces
+  `key: Char('L'), modifiers: NONE` because the `SHIFT` key composed to produce
+  the uppercase `L`.
+* `raw_key` represents the key press prior to any keymapping/composition events.
+  If `raw_key` would be the same as `key` then `raw_key` will be printed as `NONE`.
+* `raw_modifiers` represents the state of the modifier keys prior to any keymapping
+  or composition effects.  For example, typeing `l` with `SHIFT` held down produces
+  `raw_modifiers: SHIFT`.
+* `raw_code` is the hardware-and-or-windowing-system-dependent raw keycode value
+  associated with the key press.  This generally represents the physical location
+  of the key independent of keymapping.
+* `repeat_count` is usually `1` but on some systems may be larger number to
+  indicate that the key is being held down and that the system is synthesizing
+  multiple key-presses based on the system key repeat settings.
+* `key_is_down` indicates whether the key is being pressed or released. This
+  will always be true when debug logging, as logging and key press handling is
+  only triggered on key press events in wezterm.
+

docs/config/lua/config/enable_csi_u_key_encoding.md

@@ -0,0 +1,20 @@
+# `enable_csi_u_key_encoding = false`
+
+This option affects how key presses are fed to the terminal; after processing
+any key binding assignments, if the key didn't match an assignment it is passed
+down to the terminal which then encodes the key press as a byte sequence to
+send to the application running in the terminal.
+
+By default, wezterm aims to be compatible with the encoding used by `xterm`.
+
+In that encoding scheme there are some key combinations that have an ambiguous
+representation.
+
+Setting `enable_csi_u_key_encoding = true` will switch to an alternative
+encoding scheme that is [described here](http://www.leonerd.org.uk/hacks/fixterms/)
+that removes the ambiguity in a mostly-backwards-compatible way, but that
+requires that applications also know about this encoding scheme to have
+the best results.
+
+The default for this option is `false`.
+

docs/config/lua/config/native_macos_fullscreen_mode.md

@@ -0,0 +1,12 @@
+# `native_macos_fullscreen_mode = false`
+
+Specifies whether the [ToggleFullScreen](../../lua/keyassignment/ToggleFullScreen.md)
+key assignment uses the native macOS full-screen application support or not.
+
+The default is `false` which will simply (and very quickly!) toggle between a
+full screen window with no decorations and a regularly size window.
+
+When `true`, transitioning to full screen will slowly animate the window moving
+to a full screen space on the monitor.
+
+This option only has an effect when running on macOS.

docs/config/lua/config/prefer_egl.md

@@ -0,0 +1,16 @@
+# `prefer_egl = true`
+
+Depending on the OS and windowing environment, there are a number of different
+ways to access the GPU.
+
+This option controls whether wezterm should attempt to use
+[EGL](https://en.wikipedia.org/wiki/EGL_%28API%29) to configure the GPU.
+
+| Environment | prefer_egl=true | prefer_egl=false |
+|-------------|-----------------|------------------|
+| Wayland     | use wayland-egl | No effect: EGL is the only way to use the GPU |
+| X11         | Use libEGL.so   | No effect: EGL is the only way to use the GPU |
+| macOS       | Use [MetalANGLE](https://github.com/kakashidinho/metalangle) libEGL.dylib if installed alongside the `wezterm-gui` executable.  Some versions of wezterm shipped with this configuration which translated OpenGL calls to [Metal](https://en.wikipedia.org/wiki/Metal_%28API%29) | Use Core OpenGL API (CGL).  Since BigSur, CGL uses Metal APIs. |
+| Windows     | Use [ANGLE](https://chromium.googlesource.com/angle/angle) to translate OpenGL calls to Direct3D, which makes wezterm more robust if you upgrade your graphics card drivers. | Use the OpenGL implementation provided by your graphics card vendor |
+
+The default is `true`.

docs/config/lua/config/show_tab_index_in_tab_bar.md

@@ -0,0 +1,6 @@
+# `show_tab_index_in_tab_bar = true`
+
+When set to `true` (the default), tab titles show their tab number with a
+prefix such as `1:`.  When false, no numeric prefix is shown.
+
+The [tab_and_split_indices_are_zero_based](tab_and_split_indices_are_zero_based.md) setting controls whether numbering starts with `0` or `1`.

docs/config/lua/config/ssh_domains.md

@@ -0,0 +1,6 @@
+# `ssh_domains`
+
+Configures SSH multiplexing domains.  [Read more about SSH Domains](
+../../../multiplexing.md#ssh-domains).
+
+This option accepts a list of [SshDomain](../SshDomain.md) objects.

docs/config/lua/config/swap_backspace_and_delete.md

@@ -0,0 +1,5 @@
+# `swap_backspace_and_delete = false`
+
+When set to `true`, switch the interpretation of the `Backspace` and
+`Delete` keys such that `Backspace` generates `Delete` and vice versa.
+

docs/config/lua/config/tab_and_split_indices_are_zero_based.md

@@ -0,0 +1,4 @@
+# `tab_and_split_indices_are_zero_based = false`
+
+If `true`, [show_tab_index_in_tab_bar](show_tab_index_in_tab_bar.md) uses a
+zero-based index.  The default is `false` and the tab shows a one-based index.

docs/config/lua/config/tls_clients.md

@@ -0,0 +1,7 @@
+# `tls_clients`
+
+Configures TLS multiplexing domains.  [Read more about TLS Domains](
+../../../multiplexing.md#tls-domains).
+
+This option accepts a list of [TlsDomainClient](../TlsDomainClient.md) objects.
+

docs/config/lua/config/tls_servers.md

@@ -0,0 +1,6 @@
+# `tls_servers`
+
+Configures TLS multiplexing domains.  [Read more about TLS Domains](
+../../../multiplexing.md#tls-domains).
+
+This option accepts a list of [TlsDomainServer](../TlsDomainServer.md) objects.

docs/multiplexing.md

@@ -49,6 +49,9 @@ return {
 }
 ```
 
+[See SshDomain](config/lua/SshDomain.md) for more information on possible
+settings to use with SSH domains.
+
 To connect to the system, run:
 
 ```bash
@@ -200,6 +203,9 @@ return {
 }
 ```
 
+[See TlsDomainClient](config/lua/TlsDomainClient.md) for more information on possible
+settings.
+
 ### Configuring the server
 
 ```lua
@@ -214,6 +220,9 @@ return {
 }
 ```
 
+[See TlsDomainServer](config/lua/TlsDomainServer.md) for more information on possible
+settings.
+
 ### Connecting
 
 On the client, running this will connect to the server, start up