1
1
mirror of https://github.com/wez/wezterm.git synced 2024-12-23 05:12:40 +03:00

docs: start adding a reference section for Config

This commit is contained in:
Wez Furlong 2021-01-18 17:31:39 -08:00
parent dc1f64ad39
commit fc6f529ee5
25 changed files with 196 additions and 3 deletions

1
.gitignore vendored
View File

@ -12,6 +12,7 @@
/docs/installation.md
/docs/install/*.md
/docs/colorschemes/**/index.md
/docs/config/lua/config/index.md
/docs/config/lua/wezterm/index.md
/docs/config/lua/pane/index.md
/docs/config/lua/window/index.md

View File

@ -170,6 +170,22 @@ local wezterm = require 'wezterm';
at the top of your configuration file to enable it.
## Available functions, constants
""",
),
Gen(
"struct: Config",
"config/lua/config",
index="""
# `Config` struct
The `return` statement at the end of your `wezterm.lua` file returns
a table that is interpreted as the internal `Config` struct type.
This section documents the various available fields in the config
struct.
At the time of writing, it is not a complete list!
""",
),
Gen(

View File

@ -0,0 +1,5 @@
# `bold_brightens_ansi_colors = true`
When true (the default), PaletteIndex 0-7 are shifted to bright when the font
intensity is bold. The brightening doesn't apply to text that is the default
color.

View File

@ -0,0 +1,5 @@
# `color_schemes`
Specifies various named color schemes in your configuration file.
Described in more detail in [Colors & Appearance](../../appearance.html#defining-a-color-scheme-in-your-weztermlua)

View File

@ -0,0 +1,5 @@
# `colors`
Specifies the color palette.
Described in more detail in [Colors & Appearance](../../appearance.md#defining-your-own-colors)

View File

@ -0,0 +1,19 @@
# `default_prog`
If no `prog` is specified on the command line, use this
instead of running the user's shell.
For example, to have `wezterm` always run `top` by default,
you'd use this:
```lua
return {
default_prog = {"top"}
}
```
`default_prog` is implemented as an array where the 0th element
is the command to run and the rest of the elements are passed
as the positional arguments to that command.
See also: [Launching Programs](../../launch.html)

View File

@ -0,0 +1,6 @@
# `font`
Configures the font to use by default. The `font` setting can specify
a set of fallbacks and other options, and is described in more detail
in the [Fonts](../../fonts.md) section.

View File

@ -0,0 +1,8 @@
# `font_antialias = "Greyscale"`
Adjusts the anti-aliasing portion of the font rasterizer.
Possible values are `None`, `Greyscale`, `Subpixel`.
The default value is `Greyscale`.

View File

@ -0,0 +1,8 @@
# `font_hinting = "Full"`
Adjust the hinting portion of the font rasterizer.
Possible values are `None`, `Vertical`, `VerticalSubpixel`, `Full`.

View File

@ -0,0 +1,8 @@
# `font_locator`
specifies the method by which system fonts are located and loaded. You may
specify `ConfigDirsOnly` to disable loading system fonts and use only the fonts
found in the directories that you specify in your `font_dirs` configuration
option.
Otherwise, it is recommended to omit this setting.

View File

@ -0,0 +1,4 @@
# `font_rasterizer`
Specifies the method by which fonts are rendered on screen. The only available
implementation is `FreeType`.

View File

@ -0,0 +1,6 @@
# `font_rules`
An optional set of style rules that can be used to specify alternative
fonts to be used for text matching various styles.
This option is described in more detail in the [Fonts](../../fonts.md) section.

View File

@ -0,0 +1,7 @@
# `font_shaper`
specifies the method by which text is mapped to glyphs in the available fonts.
The shaper is responsible for handling kerning, ligatures and emoji
composition. The default is `Harfbuzz` and we have very preliminary support
for `Allsorts`.

View File

@ -0,0 +1,9 @@
# `font_size = 10.0`
Specifies the size of the font, measured in points.
The default font size is 10 points.
You may use fractional point sizes, such as `13.3`, to fine tune the size.

View File

@ -0,0 +1,5 @@
# `freetype_interpreter_version`
Selects the freetype interpret version to use. Possible values are `35`, `38`
and `40` which have different characteristics with respective to subpixel
hinting. See <https://freetype.org/freetype2/docs/subpixel-hinting.html>

View File

@ -0,0 +1,14 @@
# `front_end = "OpenGL"`
Specifies which render front-end to use. This option used to have
more scope in earlier versions of wezterm, but today it allows two
possible values:
* `OpenGL` - use GPU accelerated rasterization (this is the default)
* `Software` - use CPU-based rasterization.
You may wish (or need!) to select `Software` if there are issues with your
GPU/OpenGL drivers.
WezTerm will automatically select `Software` if it detects that it is
being started in a Remote Desktop environment on Windows.

View File

@ -0,0 +1,8 @@
# `harfbuzz_features`
When `font_shaper = "Harfbuzz"`, this setting affects how font shaping
takes place.
See [Font Shaping](../../font-shaping.html) for more information
and examples.

View File

@ -0,0 +1,7 @@
# `hyperlink_rules`
Defines rules to match text from the terminal output and generate
clickable links.
See [Hyperlinks](../../../hyperlinks.md) for more information and
examples.

View File

@ -0,0 +1,3 @@
# `initial_cols = 80`
Specifies the width of a new window, expressed in character cells.

View File

@ -0,0 +1,3 @@
# `initial_rows = 24`
Specifies the height of a new window, expressed in character cells.

View File

@ -0,0 +1,10 @@
# `line_height = 1.0`
Scales the computed line height to adjust the spacing between successive rows
of text. The default line height is controlled by the
[font_size](font_size.md) configuration option. If you feel that your chosen
font feels too vertically cramped then you can set `line_height = 1.2` to
increase the vertical spacing by 20%. Conversely, setting `line_height = 0.9`
will decrease the vertical spacing by 10%.

View File

@ -0,0 +1,5 @@
# `scrollback_lines = 3500`
How many lines of scrollback you want to retain.
[Learn more about scrollback](../../../scrollback.md)

View File

@ -0,0 +1,7 @@
# `set_environment_variables`
Specifies a map of environment variables that should be set when spawning
commands in the local domain. This is not used when working with remote
domains.
See also: [Launching Programs](../../launch.html#passing-environment-variables-to-the-spawned-program)

View File

@ -0,0 +1,24 @@
# `term = "xterm-256color"`
What to set the `TERM` environment variable to. The default is
`xterm-256color`, which should provide a good level of feature
support without requiring the installation of additional terminfo
data.
If you want to get the most application support out of wezterm, then you may
wish to install a copy of the `wezterm` TERM definition:
```
tempfile=$(mktemp) \
&& curl -o $tempfile https://raw.githubusercontent.com/wez/wezterm/master/termwiz/data/wezterm.terminfo \
&& tic -x -o ~/.terminfo $tempfile \
&& rm $tempfile
```
You can then set `term = "wezterm"` in your `.wezterm.lua` config file.
Doing this will inform some software of newer, more advanced features such
as colored underlines, styled underlines (eg: undercurl). If the system
you are using has a relatively outdated ncurses installation, the `wezterm`
terminfo will also enable italics and true color support.

View File

@ -1,8 +1,8 @@
## 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:
This section documents the various lua functions and types 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';