wez/wezterm
1
1
Fork 0
mirror of https://github.com/wez/wezterm.git synced 2024-09-21 19:58:15 +03:00
Code Issues Projects Releases Wiki Activity

docs: expand font_rules

Browse Source 
refs: #2836
This commit is contained in:
Wez Furlong 2022-12-06 09:36:35 -07:00
parent af9d0efa17
commit 92e851d648
No known key found for this signature in database
GPG Key ID: 7A7F66A31EC9B387
1 changed files with 133 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

201
docs/config/lua/config/font_rules.md
View File

@ -1,104 +1,169 @@
# `font_rules`
You may optionally specify rules that apply different font styling based on the
attributes of the text rendered in the terminal. Most users won't need to do
this; these rules are useful when you have some unusual fonts or mixtures of
fonts that you'd like to use. The default is to auto-generate reasonable
italic and bold styling based on the [font](font.md) configuration.
When textual output in the terminal is styled with bold, italic or other
attributes, wezterm uses `font_rules` to decide how to render that text.
If you do specify `font_rules`, they are applied in the order that they are
specified in the configuration file, stopping with the first matching rule:
By default, unstyled text will use the font specified by the [font](font.md)
configuration, and wezterm will use that as a base, and then automatically
generate appropriate `font_rules` that use heavier weight fonts for bold text,
lighter weight fonts for dim text and italic fonts for italic text.
```lua
local wezterm = require 'wezterm'
return {
font_rules = {
-- Define a rule that matches when italic text is shown
{
-- If specified, this rule matches when a cell's italic value exactly
-- matches this. If unspecified, the attribute value is irrelevant
-- with respect to matching.
italic = true,
Most users won't need to specify any explicit value for `font_rules`, as the
defaults should be sufficient.
-- Match based on intensity: "Bold", "Normal" and "Half" are supported
-- intensity = "Normal",
If you have some unusual fonts or mixtures of fonts that you'd like to use,
such as using your favourite monospace font for the base and a fancy italic
font from a different font family for italics, then `font_rules` will allow you
to do so.
-- Match based on underline: "None", "Single", and "Double" are supported
-- underline = "None",
`font_rules` is comprised of a list of rule entries with fields that are split
into *matcher* fields and *action* fields. Matcher fields specify which textual
attributes you want to match on, while action fields specify how you want to
render them.
-- Match based on the blink attribute: "None", "Slow", "Rapid"
-- blink = "None",
The following fields are matcher fields:
-- Match based on reverse video
-- reverse = false,
|Name |Associated Attribute|Possible Values|
|----------|--------------------|---------------|
|italic |italic |`true` (italic) or `false` (not italic)|
|intensity |bold/bright or dim/half-bright|`"Normal"` (neither bold nor dim), `"Bold"`, `"Half"`|
|underline |underline | `"None"` (not underlined), `"Single"` (single underline), `"Double"` (double underline)|
|blink |blinking | `"None"` (not blinking), `"Rapid"` (regular rapid blinking), `"Slow"` (slow blinking)|
|reverse |reverse/inverse | `true` (reversed) or `false` (not reversed)|
|strikethrough|strikethrough | `true` (struck-through) or `false` (not struck-through)|
|invisible |invisible | `true` (invisible) or `false` (not invisible)|
-- Match based on strikethrough
-- strikethrough = false,
If a matcher field is omitted, then the associated attribute has no impact
on the match: the rule *doesn't care about* that attribute and will match based
on the attributes that were listed.
-- Match based on the invisible attribute
-- invisible = false,
The following fields are action fields:
-- When the above attributes match, apply this font styling
font = wezterm.font('Operator Mono SSm Lig Medium', { italic = true }),
},
},
}
```
|Name |Action |
|--------------|---------|
|font |Specify the font that should be used|
Here's an example from my configuration file;
The way that `font_rules` are processed is:
1. Take the list of `font_rules` from your configuration
2. For each rule in the order listed in `font_rules`:
3. Consider each *matcher* field explicitly specified in the entry. If the associated attribute does not match the value specified in the entry, move on to the next rule.
4. If all of the *matcher* fields explicitly specified in the entry match the attributes of the text, then:
* The `font` *action* field, if specified, will override the base `font` configuration
* No further `font_rules` will be considered: the matching is complete
5. If none of the rules you specify matched, then a set of default rules based on your base `font` will be used in the same way as above.
Here's an example from my configuration file, which I use with a variant of
`Operator Mono` that is patched to add ligatures. This particular font has
font-weights that are either too bold or too light for the default rules to
produce great results, hence this set of rules.
```lua
local wezterm = require 'wezterm'
-- A helper function for my fallback fonts
function font_with_fallback(name, params)
local names = { name, 'Noto Color Emoji', 'JetBrains Mono' }
return wezterm.font_with_fallback(names, params)
end
return {
font = font_with_fallback 'Operator Mono SSm Lig Medium',
font = wezterm.font_with_fallback 'Operator Mono SSm Lig Medium',
font_rules = {
-- Select a fancy italic font for italic text
{
italic = true,
font = font_with_fallback 'Operator Mono SSm Lig Medium Italic',
},
-- Similarly, a fancy bold+italic font
{
italic = true,
intensity = 'Bold',
font = font_with_fallback 'Operator Mono SSm Lig Book Italic',
},
-- Make regular bold text a different color to make it stand out even more
-- For Bold-but-not-italic text, use this relatively bold font, and override
-- its color to a tomato-red color to make bold text really stand out.
{
intensity = 'Bold',
font = font_with_fallback(
'Operator Mono SSm Lig Bold',
italic = false,
font = wezterm.font_with_fallback(
'Operator Mono SSm Lig',
-- Override the color specified by the terminal output and force
-- it to be tomato-red.
-- The color value you set here can be any CSS color name or
-- RGB color string.
{ foreground = 'tomato' }
),
},
-- For half-intensity text, use a lighter weight font
-- Bold-and-italic
{
intensity = 'Bold',
italic = true,
font = wezterm.font_with_fallback {
family = 'Operator Mono SSm Lig',
italic = true,
},
},
-- normal-intensity-and-italic
{
intensity = 'Normal',
italic = true,
font = wezterm.font_with_fallback {
family = 'Operator Mono SSm Lig',
weight = 'DemiLight',
italic = true,
},
},
-- half-intensity-and-italic (half-bright or dim); use a lighter weight font
{
intensity = 'Half',
font = font_with_fallback 'Operator Mono SSm Lig Light',
italic = true,
font = wezterm.font_with_fallback {
family = 'Operator Mono SSm Lig',
weight = 'Light',
italic = true,
},
},
-- half-intensity-and-not-italic
{
intensity = 'Half',
italic = false,
font = wezterm.font_with_fallback {
family = 'Operator Mono SSm Lig',
weight = 'Light',
},
},
},
}
```
*Since: 20210502-130208-bff6815d*
Here's another example combining `FiraCode` with `Victor Mono`, using `Victor Mono` only for italics:
The default `font_rules` generated by wezterm are now always appended to the
rules that you've supplied (rather than used only if you didn't specify any),
and now also include rules for selecting lighter weight fonts when half-bright
text is rendered to the terminal.
```lua
local wezterm = require 'wezterm'
That means that you shouldn't need to specify as many rules as in previously
releases.
return {
font = wezterm.font { family = 'FiraCode' },
font_rules = {
{
intensity = 'Bold',
italic = true,
font = wezterm.font {
family = 'VictorMono',
weight = 'Bold',
style = 'Italic',
},
},
{
italic = true,
intensity = 'Half',
font = wezterm.font {
family = 'VictorMono',
weight = 'DemiBold',
style = 'Italic',
},
},
{
italic = true,
intensity = 'Normal',
font = wezterm.font {
family = 'VictorMono',
style = 'Italic',
},
},
},
}
```
## Debugging Font Rules
You can run `wezterm ls-fonts` to summarize the font rules and the fonts that
match them: