From 58fde836c36fa154ddc9a42d1d6ab09e6dae905a Mon Sep 17 00:00:00 2001 From: Wez Furlong Date: Sat, 20 Feb 2021 09:43:37 -0800 Subject: [PATCH] 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 | 3 + docs/config/keys.md | 60 +++++++++++++++++ docs/config/lua/SshDomain.md | 37 ++++++++++ docs/config/lua/TlsDomainClient.md | 67 +++++++++++++++++++ docs/config/lua/TlsDomainServer.md | 34 ++++++++++ ...ust_window_size_when_changing_font_size.md | 10 +++ docs/config/lua/config/daemon_options.md | 22 ++++++ docs/config/lua/config/debug_key_events.md | 54 +++++++++++++++ .../lua/config/enable_csi_u_key_encoding.md | 20 ++++++ .../config/native_macos_fullscreen_mode.md | 12 ++++ docs/config/lua/config/prefer_egl.md | 16 +++++ .../lua/config/show_tab_index_in_tab_bar.md | 6 ++ docs/config/lua/config/ssh_domains.md | 6 ++ .../lua/config/swap_backspace_and_delete.md | 5 ++ .../tab_and_split_indices_are_zero_based.md | 4 ++ docs/config/lua/config/tls_clients.md | 7 ++ docs/config/lua/config/tls_servers.md | 6 ++ docs/multiplexing.md | 9 +++ 18 files changed, 378 insertions(+) create mode 100644 docs/config/lua/SshDomain.md create mode 100644 docs/config/lua/TlsDomainClient.md create mode 100644 docs/config/lua/TlsDomainServer.md create mode 100644 docs/config/lua/config/adjust_window_size_when_changing_font_size.md create mode 100644 docs/config/lua/config/daemon_options.md create mode 100644 docs/config/lua/config/debug_key_events.md create mode 100644 docs/config/lua/config/enable_csi_u_key_encoding.md create mode 100644 docs/config/lua/config/native_macos_fullscreen_mode.md create mode 100644 docs/config/lua/config/prefer_egl.md create mode 100644 docs/config/lua/config/show_tab_index_in_tab_bar.md create mode 100644 docs/config/lua/config/ssh_domains.md create mode 100644 docs/config/lua/config/swap_backspace_and_delete.md create mode 100644 docs/config/lua/config/tab_and_split_indices_are_zero_based.md create mode 100644 docs/config/lua/config/tls_clients.md create mode 100644 docs/config/lua/config/tls_servers.md diff --git a/ci/generate-docs.py b/ci/generate-docs.py index 1d6fa99df..283cf95bd 100644 --- a/ci/generate-docs.py +++ b/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", diff --git a/docs/config/keys.md b/docs/config/keys.md index c5c1ca945..5f7d4350f 100644 --- a/docs/config/keys.md +++ b/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+ 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 diff --git a/docs/config/lua/SshDomain.md b/docs/config/lua/SshDomain.md new file mode 100644 index 000000000..7dbe7b209 --- /dev/null +++ b/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" +} +``` diff --git a/docs/config/lua/TlsDomainClient.md b/docs/config/lua/TlsDomainClient.md new file mode 100644 index 000000000..c4fe5be4b --- /dev/null +++ b/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" +} +``` diff --git a/docs/config/lua/TlsDomainServer.md b/docs/config/lua/TlsDomainServer.md new file mode 100644 index 000000000..1d22733f1 --- /dev/null +++ b/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" }, +} +``` diff --git a/docs/config/lua/config/adjust_window_size_when_changing_font_size.md b/docs/config/lua/config/adjust_window_size_when_changing_font_size.md new file mode 100644 index 000000000..a03a9b246 --- /dev/null +++ b/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`. + diff --git a/docs/config/lua/config/daemon_options.md b/docs/config/lua/config/daemon_options.md new file mode 100644 index 000000000..2fab129ed --- /dev/null +++ b/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", + } +} +``` diff --git a/docs/config/lua/config/debug_key_events.md b/docs/config/lua/config/debug_key_events.md new file mode 100644 index 000000000..23de53a1c --- /dev/null +++ b/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. + diff --git a/docs/config/lua/config/enable_csi_u_key_encoding.md b/docs/config/lua/config/enable_csi_u_key_encoding.md new file mode 100644 index 000000000..a02f8f54f --- /dev/null +++ b/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`. + diff --git a/docs/config/lua/config/native_macos_fullscreen_mode.md b/docs/config/lua/config/native_macos_fullscreen_mode.md new file mode 100644 index 000000000..08248cdf4 --- /dev/null +++ b/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. diff --git a/docs/config/lua/config/prefer_egl.md b/docs/config/lua/config/prefer_egl.md new file mode 100644 index 000000000..b197dd1b8 --- /dev/null +++ b/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`. diff --git a/docs/config/lua/config/show_tab_index_in_tab_bar.md b/docs/config/lua/config/show_tab_index_in_tab_bar.md new file mode 100644 index 000000000..2fabb2a44 --- /dev/null +++ b/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`. diff --git a/docs/config/lua/config/ssh_domains.md b/docs/config/lua/config/ssh_domains.md new file mode 100644 index 000000000..6e1f7ae76 --- /dev/null +++ b/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. diff --git a/docs/config/lua/config/swap_backspace_and_delete.md b/docs/config/lua/config/swap_backspace_and_delete.md new file mode 100644 index 000000000..18f129ccd --- /dev/null +++ b/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. + diff --git a/docs/config/lua/config/tab_and_split_indices_are_zero_based.md b/docs/config/lua/config/tab_and_split_indices_are_zero_based.md new file mode 100644 index 000000000..619b90d9e --- /dev/null +++ b/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. diff --git a/docs/config/lua/config/tls_clients.md b/docs/config/lua/config/tls_clients.md new file mode 100644 index 000000000..aec140e27 --- /dev/null +++ b/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. + diff --git a/docs/config/lua/config/tls_servers.md b/docs/config/lua/config/tls_servers.md new file mode 100644 index 000000000..b74191ceb --- /dev/null +++ b/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. diff --git a/docs/multiplexing.md b/docs/multiplexing.md index 38c098677..5b77021e0 100644 --- a/docs/multiplexing.md +++ b/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