wez/wezterm
1
1
Fork 0
mirror of https://github.com/wez/wezterm.git synced 2024-11-22 22:42:48 +03:00
Code Issues Projects Releases Wiki Activity

docs: Make it easier to split out docs into multiple pages

Browse Source
This commit is contained in:
Wez Furlong 2020-10-09 22:03:59 -07:00
parent 5a8fc09336
commit 6e0836d11a
20 changed files with 415 additions and 329 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@ -8,8 +8,10 @@
/pkg
/target/
/gh_pages/
/docs/SUMMARY.md
/docs/installation.md
/docs/install/*.md
/docs/config/lua/wezterm/index.md
**/*.rs.bk
.*.sw*
/esctest.log

1
ci/build-docs.sh
View File

@ -2,6 +2,7 @@
[[ -f /tmp/wezterm.releases.json ]] || curl https://api.github.com/repos/wez/wezterm/releases > /tmp/wezterm.releases.json
python3 ci/subst-release-info.py
python3 ci/generate-docs.py
mdbook build docs
# mdBook can append js includes but it is too late to register syntax

98
ci/generate-docs.py Normal file
View File

@ -0,0 +1,98 @@
#!/usr/bin/env python3
import sys
import os
import glob
import re
class Page(object):
def __init__(self, title, filename, children=None):
self.title = title
self.filename = filename
self.children = children or []
def render(self, output, depth=0):
indent = " " * depth
bullet = "- " if depth > 0 else ""
output.write(f"{indent}{bullet}[{self.title}]({self.filename})\n")
for kid in self.children:
kid.render(output, depth + 1)
# autogenerate an index page from the contents of a directory
class Gen(object):
def __init__(self, title, dirname):
self.title = title
self.dirname = dirname
def render(self, output, depth=0):
print(self.dirname)
names = sorted(glob.glob(f"{self.dirname}/*.md"))
children = []
for filename in names:
title = os.path.basename(filename).rsplit(".", 1)[0]
if title == "index":
continue
children.append(Page(title, filename))
index_filename = f"{self.dirname}/index.md"
index_page = Page(self.title, index_filename, children=children)
index_page.render(output, depth)
with open(f"{self.dirname}/index.md", "w") as idx:
for page in children:
page.render(idx, 1)
TOC = [
Page(
"wezterm",
"index.markdown",
children=[
Page(
"Install",
"installation.md",
children=[
Page("Windows", "install/windows.md"),
Page("macOS", "install/macos.md"),
Page("Linux", "install/linux.md"),
Page("Build from source", "install/source.md"),
],
),
Page("Features", "features.markdown"),
Page("Change Log", "changelog.markdown"),
Page(
"Configuration",
"config/files.markdown",
children=[
Page("Launching Programs", "config/launch.markdown"),
Page("Fonts", "config/fonts.markdown"),
Page("Font Shaping", "config/font-shaping.markdown"),
Page("Misc", "config/misc.markdown"),
Page("Key & Mouse Binding", "config/keys.markdown"),
Page("Colors & Appearance", "config/appearance.markdown"),
],
),
Page(
"Lua Reference",
"config/lua/general.md",
children=[Gen("module: wezterm", "config/lua/wezterm"),],
),
Page("Scrollback", "scrollback.markdown"),
Page("Copy Mode", "copymode.markdown"),
Page("Hyperlinks", "hyperlinks.markdown"),
Page("Shell Integration", "shell-integration.markdown"),
Page("iTerm Image Protocol", "imgcat.markdown"),
Page("SSH", "ssh.markdown"),
Page("Serial Ports & Arduino", "serial.markdown"),
Page("Mulitplexing", "multiplexing.markdown"),
Page("F.A.Q.", "faq.markdown"),
Page("Getting Help", "help.markdown"),
Page("Contributing", "contributing.markdown"),
],
)
]
os.chdir("docs")
with open("SUMMARY.md", "w") as f:
for page in TOC:
page.render(f)

27
docs/SUMMARY.md
View File

@ -1,27 +0,0 @@
[wezterm](index.markdown)
- [Install](installation.md)
- [Windows](install/windows.md)
- [macOS](install/macos.md)
- [Linux](install/linux.md)
- [Build from source](install/source.md)
- [Features](features.markdown)
- [Change Log](changelog.markdown)
- [Configuration](config/files.markdown)
- [Launching Programs](config/launch.markdown)
- [Fonts](config/fonts.markdown)
- [Font Shaping](config/font-shaping.markdown)
- [Misc](config/misc.markdown)
- [Key & Mouse Binding](config/keys.markdown)
- [Colors & Appearance](config/appearance.markdown)
- [Lua Reference](config/lua.markdown)
- [Scrollback](scrollback.markdown)
- [Copy Mode](copymode.markdown)
- [Hyperlinks](hyperlinks.markdown)
- [Shell Integration](shell-integration.markdown)
- [iTerm Image Protocol](imgcat.markdown)
- [SSH](ssh.markdown)
- [Serial Ports & Arduino](serial.markdown)
- [Multiplexing](multiplexing.markdown)
- [F.A.Q.](faq.markdown)
- [Getting Help](help.markdown)
- [Contributing](contributing.markdown)

302
docs/config/lua.markdown
View File

@ -1,302 +0,0 @@
## Lua Reference
This section documents the various lua functions that are provided to
the configuration file. These are provided by the `wezterm` module that
must be imported into your configuration file:
```lua
local wezterm = require 'wezterm';
return {
font = wezterm.font("JetBrains Mono"),
}
```
### Making your own Lua Modules
If you'd like to break apart your configuration into multiple files, you'll
be interested in this information.
The `package.path` is configured with the following paths in this order:
* On Windows: a `wezterm_modules` dir in the same directory as `wezterm.exe`
* `~/.config/wezterm`
* `~/.wezterm`
* A system specific set of paths which may (or may not!) find locally installed lua modules
That means that if you wanted to break your config up into a `helpers.lua` file
you would place it in `~/.config/wezterm/helpers.lua` with contents like this:
```lua
-- I am helpers.lua and I should live in ~/.config/wezterm/helpers.lua
local wezterm = require 'wezterm';
-- This is the module table that we will export
local module = {}
-- This function is private to this module and is not visible
-- outside.
local function private_helper()
wezterm.log_error("hello!")
end
-- define a function in the module table.
-- Only functions defined in `module` will be exported to
-- code that imports this module
function module.my_function()
private_helper()
end
-- return our module table
return module
```
and then in your `wezterm.lua`
you would use it like this:
```lua
local helpers = require 'helpers';
helpers.my_function()
```
### `wezterm.config_dir`
This constant is set to the path to the directory in which your `wezterm.lua`
configuration file was found.
```lua
local wezterm = require 'wezterm';
wezterm.log_error("Config Dir " .. wezterm.config_dir)
```
### `wezterm.target_triple`
This constant is set to the [Rust target
triple](https://forge.rust-lang.org/release/platform-support.html) for the
platform on which `wezterm` was built. This can be useful when you wish to
conditionally adjust your configuration based on the platform.
```lua
local wezterm = require 'wezterm';
if wezterm.target_triple == "x86_64-pc-windows-msvc" then
-- We are running on Windows; maybe we emit different
-- key assignments here?
end
```
The most common triples are:
* `x86_64-pc-windows-msvc` - Windows
* `x86_64-apple-darwin` - macOS
* `x86_64-unknown-linux-gnu` - Linux
### `wezterm.version`
This constant is set to the `wezterm` version string that is also reported
by running `wezterm -V`. This can potentially be used to adjust configuration
according to the installed version.
The version string looks like `20200406-151651-5b700e4`. You can compare the
strings lexicographically if you wish to test whether a given version is newer
than another; the first component is the date on which the release was made,
the second component is the time and the final component is a git hash.
```lua
local wezterm = require 'wezterm';
wezterm.log_error("Version " .. wezterm.version)
```
### `wezterm.home_dir`
This constant is set to the home directory of the user running `wezterm`.
```lua
local wezterm = require 'wezterm';
wezterm.log_error("Home " .. wezterm.home_dir)
```
### `wezterm.running_under_wsl()`
This function returns a boolean indicating whether we believe that we are
running in a Windows Services for Linux (WSL) container. In such an
environment the `wezterm.target_triple` will indicate that we are running in
Linux but there will be some slight differences in system behavior (such as
filesystem capabilities) that you may wish to probe for in the configuration.
```lua
local wezterm = require 'wezterm';
wezterm.log_error("System " .. wezterm.target_triple .. " " ..
tostring(wezterm.running_under_wsl()))
```
### `wezterm.log_error(msg)`
This function logs the provided message string through wezterm's logging layer.
If you started wezterm from a terminal that text will print to the stdout of
that terminal. If running as a daemon for the multiplexer server then it will
be logged to the daemon output path.
```lua
local wezterm = require 'wezterm';
wezterm.log_error("Hello!");
```
### `wezterm.font(family [, attributes])`
This function constructs a lua table that corresponds to the internal `FontAttributes`
struct that is used to select a single named font:
```lua
local wezterm = require 'wezterm';
return {
font = wezterm.font("JetBrains Mono"),
}
```
The second parameter is an optional table that can be used to specify some
attributes; the following keys are allowed:
* `bold` - whether to select a bold variant of the font (default: `false`)
* `italic` - whether to select an italic variant of the font (default: `false`)
```lua
local wezterm = require 'wezterm';
return {
font = wezterm.font("JetBrains Mono", {bold=true}),
}
```
### `wezterm.font_with_fallback(families [, attributes])`
This function constructs a lua table that configures a font with fallback processing.
Glyphs are looked up in the first font in the list but if missing the next font is
checked and so on.
The first parameter is a table listing the fonts in their preferred order:
```lua
local wezterm = require 'wezterm';
return {
font = wezterm.font_with_fallback({"JetBrains Mono", "Noto Color Emoji"}),
}
```
The second parameter behaves the same as that of `wezterm.font`.
### `wezterm.hostname()`
This function returns the current hostname of the system that is running wezterm.
This can be useful to adjust configuration based on the host.
Note that environments that use DHCP and have many clients and short leases may
make it harder to rely on the hostname for this purpose.
```lua
local wezterm = require 'wezterm';
local hostname = wezterm.hostname();
local font_size;
if hostname == "pixelbookgo-localdomain" then
-- Use a bigger font on the smaller screen of my PixelBook Go
font_size = 12.0;
else
font_size = 10.0;
end
return {
font_size = font_size
}
```
### `wezterm.read_dir(path)`
*Since: 20200503-171512-b13ef15f*
This function returns an array containing the absolute file names of the
directory specified. Due to limitations in the lua bindings, all of the paths
must be able to be represented as UTF-8 or this function will generate an
error.
```lua
local wezterm = require 'wezterm';
-- logs the names of all of the entries under `/etc`
for _, v in ipairs(wezterm.read_dir("/etc")) do
wezterm.log_error("entry: " .. v)
end
```
### `wezterm.glob(pattern [, relative_to])`
*Since: 20200503-171512-b13ef15f*
This function evalutes the glob `pattern` and returns an array containing the
absolute file names of the matching results. Due to limitations in the lua
bindings, all of the paths must be able to be represented as UTF-8 or this
function will generate an error.
The optional `relative_to` parameter can be used to make the results relative
to a path. If the results have the same prefix as `relative_to` then it will
be removed from the returned path.
```lua
local wezterm = require 'wezterm';
-- logs the names of all of the conf files under `/etc`
for _, v in ipairs(wezterm.glob("/etc/*.conf")) do
wezterm.log_error("entry: " .. v)
end
```
### `wezterm.run_child_process(args)`
*Since: 20200503-171512-b13ef15f*
This function accepts an argument list; it will attempt to spawn that command
and will return a tuple consisting of the boolean success of the invocation,
the stdout data and the stderr data.
```lua
local wezterm = require 'wezterm';
local success, stdout, stderr = wezterm.run_child_process({"ls", "-l"})
```
### `wezterm.split_by_newlines(str)`
*Since: 20200503-171512-b13ef15f*
This function takes the input string and splits it by newlines (both `\n` and `\r\n`
are recognized as newlines) and returns the result as an array of strings that
have the newlines removed.
```lua
local wezterm = require 'wezterm';
local example = "hello\nthere\n";
for _, line in ipairs(wezterm.split_by_newlines(example)) do
wezterm.log_error(line)
end
```
### `wezterm.utf16_to_utf8(str)`
*Since: 20200503-171512-b13ef15f*
This function is overly specific and exists primarily to workaround
[this wsl.exe issue](https://github.com/microsoft/WSL/issues/4456).
It takes as input a string and attempts to convert it from utf16 to utf8.
```lua
local wezterm = require 'wezterm';
local success, wsl_list, wsl_err = wezterm.run_child_process({"wsl.exe", "-l"})
wsl_list = wezterm.utf16_to_utf8(wsl_list)
```

60
docs/config/lua/general.md Normal file
View File

@ -0,0 +1,60 @@
## Lua Reference
This section documents the various lua functions that are provided to
the configuration file. These are provided by the `wezterm` module that
must be imported into your configuration file:
```lua
local wezterm = require 'wezterm';
return {
font = wezterm.font("JetBrains Mono"),
}
```
### Making your own Lua Modules
If you'd like to break apart your configuration into multiple files, you'll
be interested in this information.
The `package.path` is configured with the following paths in this order:
* On Windows: a `wezterm_modules` dir in the same directory as `wezterm.exe`
* `~/.config/wezterm`
* `~/.wezterm`
* A system specific set of paths which may (or may not!) find locally installed lua modules
That means that if you wanted to break your config up into a `helpers.lua` file
you would place it in `~/.config/wezterm/helpers.lua` with contents like this:
```lua
-- I am helpers.lua and I should live in ~/.config/wezterm/helpers.lua
local wezterm = require 'wezterm';
-- This is the module table that we will export
local module = {}
-- This function is private to this module and is not visible
-- outside.
local function private_helper()
wezterm.log_error("hello!")
end
-- define a function in the module table.
-- Only functions defined in `module` will be exported to
-- code that imports this module
function module.my_function()
private_helper()
end
-- return our module table
return module
```
and then in your `wezterm.lua`
you would use it like this:
```lua
local helpers = require 'helpers';
helpers.my_function()
```

11
docs/config/lua/wezterm/config_dir.md Normal file
View File

@ -0,0 +1,11 @@
# `wezterm.config_dir`
This constant is set to the path to the directory in which your `wezterm.lua`
configuration file was found.
```lua
local wezterm = require 'wezterm';
wezterm.log_error("Config Dir " .. wezterm.config_dir)
```

28
docs/config/lua/wezterm/font.md Normal file
View File

@ -0,0 +1,28 @@
# `wezterm.font(family [, attributes])`
This function constructs a lua table that corresponds to the internal `FontAttributes`
struct that is used to select a single named font:
```lua
local wezterm = require 'wezterm';
return {
font = wezterm.font("JetBrains Mono"),
}
```
The second parameter is an optional table that can be used to specify some
attributes; the following keys are allowed:
* `bold` - whether to select a bold variant of the font (default: `false`)
* `italic` - whether to select an italic variant of the font (default: `false`)
```lua
local wezterm = require 'wezterm';
return {
font = wezterm.font("JetBrains Mono", {bold=true}),
}
```

19
docs/config/lua/wezterm/font_with_fallback.md Normal file
View File

@ -0,0 +1,19 @@
# `wezterm.font_with_fallback(families [, attributes])`
This function constructs a lua table that configures a font with fallback processing.
Glyphs are looked up in the first font in the list but if missing the next font is
checked and so on.
The first parameter is a table listing the fonts in their preferred order:
```lua
local wezterm = require 'wezterm';
return {
font = wezterm.font_with_fallback({"JetBrains Mono", "Noto Color Emoji"}),
}
```
The second parameter behaves the same as that of `wezterm.font`.

23
docs/config/lua/wezterm/glob.md Normal file
View File

@ -0,0 +1,23 @@
# `wezterm.glob(pattern [, relative_to])`
*Since: 20200503-171512-b13ef15f*
This function evalutes the glob `pattern` and returns an array containing the
absolute file names of the matching results. Due to limitations in the lua
bindings, all of the paths must be able to be represented as UTF-8 or this
function will generate an error.
The optional `relative_to` parameter can be used to make the results relative
to a path. If the results have the same prefix as `relative_to` then it will
be removed from the returned path.
```lua
local wezterm = require 'wezterm';
-- logs the names of all of the conf files under `/etc`
for _, v in ipairs(wezterm.glob("/etc/*.conf")) do
wezterm.log_error("entry: " .. v)
end
```

10
docs/config/lua/wezterm/home_dir.md Normal file
View File

@ -0,0 +1,10 @@
# `wezterm.home_dir`
This constant is set to the home directory of the user running `wezterm`.
```lua
local wezterm = require 'wezterm';
wezterm.log_error("Home " .. wezterm.home_dir)
```

26
docs/config/lua/wezterm/hostname.md Normal file
View File

@ -0,0 +1,26 @@
# `wezterm.hostname()`
This function returns the current hostname of the system that is running wezterm.
This can be useful to adjust configuration based on the host.
Note that environments that use DHCP and have many clients and short leases may
make it harder to rely on the hostname for this purpose.
```lua
local wezterm = require 'wezterm';
local hostname = wezterm.hostname();
local font_size;
if hostname == "pixelbookgo-localdomain" then
-- Use a bigger font on the smaller screen of my PixelBook Go
font_size = 12.0;
else
font_size = 10.0;
end
return {
font_size = font_size
}
```

13
docs/config/lua/wezterm/log_error.md Normal file
View File

@ -0,0 +1,13 @@
# `wezterm.log_error(msg)`
This function logs the provided message string through wezterm's logging layer.
If you started wezterm from a terminal that text will print to the stdout of
that terminal. If running as a daemon for the multiplexer server then it will
be logged to the daemon output path.
```lua
local wezterm = require 'wezterm';
wezterm.log_error("Hello!");
```

19
docs/config/lua/wezterm/read_dir.md Normal file
View File

@ -0,0 +1,19 @@
# `wezterm.read_dir(path)`
*Since: 20200503-171512-b13ef15f*
This function returns an array containing the absolute file names of the
directory specified. Due to limitations in the lua bindings, all of the paths
must be able to be represented as UTF-8 or this function will generate an
error.
```lua
local wezterm = require 'wezterm';
-- logs the names of all of the entries under `/etc`
for _, v in ipairs(wezterm.read_dir("/etc")) do
wezterm.log_error("entry: " .. v)
end
```

15
docs/config/lua/wezterm/run_child_process.md Normal file
View File

@ -0,0 +1,15 @@
# `wezterm.run_child_process(args)`
*Since: 20200503-171512-b13ef15f*
This function accepts an argument list; it will attempt to spawn that command
and will return a tuple consisting of the boolean success of the invocation,
the stdout data and the stderr data.
```lua
local wezterm = require 'wezterm';
local success, stdout, stderr = wezterm.run_child_process({"ls", "-l"})
```

15
docs/config/lua/wezterm/running_under_wsl.md Normal file
View File

@ -0,0 +1,15 @@
# `wezterm.running_under_wsl()`
This function returns a boolean indicating whether we believe that we are
running in a Windows Services for Linux (WSL) container. In such an
environment the `wezterm.target_triple` will indicate that we are running in
Linux but there will be some slight differences in system behavior (such as
filesystem capabilities) that you may wish to probe for in the configuration.
```lua
local wezterm = require 'wezterm';
wezterm.log_error("System " .. wezterm.target_triple .. " " ..
tostring(wezterm.running_under_wsl()))
```

19
docs/config/lua/wezterm/split_by_newlines.md Normal file
View File

@ -0,0 +1,19 @@
# `wezterm.split_by_newlines(str)`
*Since: 20200503-171512-b13ef15f*
This function takes the input string and splits it by newlines (both `\n` and `\r\n`
are recognized as newlines) and returns the result as an array of strings that
have the newlines removed.
```lua
local wezterm = require 'wezterm';
local example = "hello\nthere\n";
for _, line in ipairs(wezterm.split_by_newlines(example)) do
wezterm.log_error(line)
end
```

23
docs/config/lua/wezterm/target_triple.md Normal file
View File

@ -0,0 +1,23 @@
# `wezterm.target_triple`
This constant is set to the [Rust target
triple](https://forge.rust-lang.org/release/platform-support.html) for the
platform on which `wezterm` was built. This can be useful when you wish to
conditionally adjust your configuration based on the platform.
```lua
local wezterm = require 'wezterm';
if wezterm.target_triple == "x86_64-pc-windows-msvc" then
-- We are running on Windows; maybe we emit different
-- key assignments here?
end
```
The most common triples are:
* `x86_64-pc-windows-msvc` - Windows
* `x86_64-apple-darwin` - macOS
* `x86_64-unknown-linux-gnu` - Linux

16
docs/config/lua/wezterm/utf16_to_utf8.md Normal file
View File

@ -0,0 +1,16 @@
# `wezterm.utf16_to_utf8(str)`
*Since: 20200503-171512-b13ef15f*
This function is overly specific and exists primarily to workaround
[this wsl.exe issue](https://github.com/microsoft/WSL/issues/4456).
It takes as input a string and attempts to convert it from utf16 to utf8.
```lua
local wezterm = require 'wezterm';
local success, wsl_list, wsl_err = wezterm.run_child_process({"wsl.exe", "-l"})
wsl_list = wezterm.utf16_to_utf8(wsl_list)
```

17
docs/config/lua/wezterm/version.md Normal file
View File

@ -0,0 +1,17 @@
# `wezterm.version`
This constant is set to the `wezterm` version string that is also reported
by running `wezterm -V`. This can potentially be used to adjust configuration
according to the installed version.
The version string looks like `20200406-151651-5b700e4`. You can compare the
strings lexicographically if you wish to test whether a given version is newer
than another; the first component is the date on which the release was made,
the second component is the time and the final component is a git hash.
```lua
local wezterm = require 'wezterm';
wezterm.log_error("Version " .. wezterm.version)
```