diff options
| author | Daniel Eklöf <daniel@ekloef.se> | 2020-08-27 18:02:30 +0000 |
|---|---|---|
| committer | Daniel Eklöf <daniel@ekloef.se> | 2020-08-27 18:02:30 +0000 |
| commit | 5c4af880fc62ee509015c28eb0b4c395b956081d (patch) | |
| tree | 08d84bfad0301cff61ba4f9097f5e8015984ce28 /doc/foot.ini.5.scd | |
| parent | readme: update references to the configuration file (diff) | |
doc: rename footrc.5 to foot.ini.5, and update references
Diffstat (limited to 'doc/foot.ini.5.scd')
| -rw-r--r-- | doc/foot.ini.5.scd | 557 |
1 files changed, 557 insertions, 0 deletions
diff --git a/doc/foot.ini.5.scd b/doc/foot.ini.5.scd new file mode 100644 index 00000000..cede6e26 --- /dev/null +++ b/doc/foot.ini.5.scd @@ -0,0 +1,557 @@ +foot.ini(5) + +# NAME +foot.ini - configuration file + +# DESCRIPTION + +*foot* uses the standard _unix configuration format_, with section based +key/value pairs. The default section is unnamed (i.e. not prefixed +with a _[section]_). + +foot will search for a configuration file in the following locations, +in this order: + +- _XDG_CONFIG_HOME/foot/foot.ini_ +- _~/.config/foot/foot.ini_ +- _XDG_CONFIG_HOME/footrc_ +- _~/.config/footrc_ +- _XDG_CONFIG_DIRS/foot/foot.init_ + +# SECTION: default + +*font* + Comma separated list of fonts to use, in fontconfig format (see + *FONT FORMAT*). + + The first font is the primary font. The remaining fonts are + fallback fonts that will be used whenever a glyph cannot be found + in the primary font. + + The fallback fonts are searched in the order they appear. If a + glyph cannot be found in any of the fallback fonts, the dynamic + fallback list from fontconfig (for the primary font) is + searched. + + Default: _monospace_. + +*geometry* + Initial window width and height in pixels (subject to output + scaling), on the form _WIDTHxHEIGHT_. Default: _700x500_. + +*pad* + Padding between border and glyphs, in pixels (subject to output + scaling), on the form _XxY_. Default: _2x2_. + +*initial-window-mode* + Initial window mode for each newly spawned window: *windowed*, + *maximized* or *fullscreen*. Default: _windowed_. + +*shell* + Executable to launch. Typically a shell. Default: _$SHELL_ if set, + otherwise the user's default shell (as specified in + _/etc/passwd_). You can also pass arguments. For example + "/bin/bash --norc". + +*login-shell* + Boolean. If enabled, the shell will be launched as a login shell, + by prepending a '-' to argv[0]. Default: _no_. + +*term* + Value to set the environment variable *TERM* to. Default: _foot_. + +*title* + Initial window title. Default: _foot_. + +*app-id* + Value to set the *app-id* property on the Wayland window to. The + compositor can use this value to e.g. group multiple windows, or + apply window management rules. Default: _foot_. + +*workers* + Number of threads to use for rendering. Set to 0 to disable + multithreading. Default: the number of available logical CPUs + (including SMT). Note that this is not always the best value. In + some cases, the number of physical _cores_ is better. + + +# SECTION: scrollback + +*lines* + Number of scrollback lines. Default: _1000_. + +*multiplier* + Amount to multiply mouse scrolling with. It is a decimal number, + i.e. fractions are allowed. Default: _1.0_. + +*indicator-position* + Configures the style of the scrollback position indicator. One of + *none*, *fixed* or *relative*. *none* disables the indicator + completely. *fixed* always renders the indicator near the top at + the window, and *relative* renders the indicator at the position + corresponding to the current scrollback position. Default: + _relative_. + +*indicator-format* + Which format to use when displaying the scrollback position + indicator. Either _percentage_, _line_, or a custom fixed + string. This option is ignored if + *indicator-position=none*. Default: _empty string_. + + +# SECTION: cursor + +This section controls the cursor style and color. Note that +applications can change these at runtime. + +*style* + Configures the default cursor style, and is one of: _block_, _bar_ + or _underline_. Note that this can be overridden by + applications. Default: _block_. + +*blink* + Boolean. Enables blinking cursor. Note that this can be overridden + by applications. Default: _no_. + +*color* + Two RRGGBB values specifying the foreground (text) and background + (cursor) colors for the cursor. Default: inversed foreground and + background colors. Note that this value only applies to the block + cursor. The other cursor styles are always rendered with the + foreground color. + + +# SECTION: mouse + +*hide-when-typing* + Boolean. When enabled, the mouse cursor is hidden while typing. + + +# SECTION: colors + +This section controls the 16 ANSI colors and the default foreground +and background colors. Note that applications can change these at +runtime. + +The colors are in RRGGBB format. That is, they do *not* have an alpha +component. You can configure the background transparency with the +_alpha_ option. + +*foreground* + Default RRGGBB foreground color. This is the color used when no + ANSI color is being used. Default: _dcdccc_. + +*background* + Default RRGGBB background color. This is the color used when no + ANSI color is being used. Default: _111111_. + +*regular0*, *regular1* *..* *regular7* + The eight basic ANSI colors. Default: _222222_, _cc9393_, + _7f9f7f_, _d0bf8f_, _6ca0a3_, _dc8cc3_, _93e0e3_ and _dcdccc_ (a + variant of the _zenburn_ theme). + +*bright0*, *bright1* *..* *bright7* + The eight bright ANSI colors. Default: _666666_, _dca3a3_, + _bfebbf_, _f0dfaf_, _8cd0d3_, _fcace3_, _b3ffff_ and _ffffff_ (a + variant of the _zenburn_ theme). + +*alpha* + Background translucency. A value in the range 0.0-1.0, where 0.0 + means completely transparent, and 1.0 is opaque. Default: _1.0_. + +*selection-foreground*, *selection-background* + Foreground (text) and background color to use in selected + text. Note that *both* options must be set, or the default will be + used. Default: _inverse foreground/background_. + + +# SECTION: csd + +This section controls the look of the _CSDs_ (Client Side +Decorations). Note that the default is to *not* use CSDs, but instead +to use _SSDs_ (Server Side Decorations) when the compositor supports +it. + +Note that unlike the colors defined in the _colors_ section, the color +values here are in AARRGGBB format. I.e. they contain an alpha +component. + +*preferred* + Which type of window decorations to prefer: *client* (CSD) or + *server* (SSD). Note that this is only a hint to the + compositor. Depending on the compositor's configuration and + capabilities, it may not have any effect. Default: _server_. + +*size* + Height, in pixels (subject to output scaling), of the + titlebar. Default: _26_. + +*color* + Titlebar AARRGGBB color. Default: use the default _foreground_ + color. + +*button-width* + Width, in pixels (subject to output scaling), of the + minimize/maximize/close buttons. Default: _26_. + +*button-minimize-color* + Minimize button's AARRGGBB color. Default: use the default + _regular4_ color (blue). + +*button-maximize-color* + Maximize button's AARRGGBB color. Default: use the default + _regular2_ color (green). + +*button-close-color* + Close button's AARRGGBB color. Default: use the default _regular1_ + color (red). + + +# SECTION: key-bindings + +This section lets you override the default key bindings. + +The general format is _action=combo1...comboN_. That is, each action +may have one or more key combinations, space separated. Each +combination is on the form _mod1+mod2+key_. The names of the modifiers +and the key *must* be valid XKB key names. + +Note that if *Shift* is one of the modifiers, the _key_ *must* be in +upper case. For example, *Control+Shift+v* will never trigger - +*Control+Shift+V* is the correct way to write it. + +Note that *Alt* is usually called *Mod1*. + +A key combination can only be mapped to *one* action. Lets say you +want to bind *Control+Shift+R* to *fullscreen*. Since this is the +default shortcut for *search-start*, you first need to unmap the +default binding. This can be done by setting _action=none_; +e.g. *search-start=none*. + +*scrollback-up* + Scrolls up/back in history. Default: _Shift+Page\_Up_. + +*scrollback-down* + Scroll down/forward in history. Default: _Shift+Page\_Down_. + +*clipboard-copy* + Copies the current selection into the _clipboard_. Default: _Control+Shift+C_. + +*clipboard-paste* + Pastes from the _clipboard_. Default: _Control+Shift+V_. + +*primary-paste* + Pastes from the _primary selection_. Default: not bound (to a + _key_, see *mouse-bindings*). + +*search-start* + Starts a scrollback/history search. Default: _Control+Shift+R_. + +*font-increase* + Increases the font size by 0.5pt. Default: _Control+plus + Control+equal Control+KP\_Add_. + +*font-decrease* + Decreases the font size by 0.5pt. Default: _Control+minus + Control+KP\_Subtract_. + +*font-reset* + Resets the font size to the default. Default: _Control+0 Control+KP\_0_. + +*spawn-terminal* + Spawns a new terminal. If the shell has been configured to emit + the OSC 7 escape sequence, the new terminal will start in the + current working directory. Default: _Control+Shift+N_. + +*minimize* + Minimizes the window. Default: _not bound_. + +*maximize* + Toggle the maximized state. Default: _not bound_. + +*fullscreen* + Toggles the fullscreen state. Default: _not bound_. + +*pipe-visible*, *pipe-scrollback*, *pipe-selected* + Pipes the currently visible text, the entire scrollback, or the + currently selected text to an external tool. The syntax for this + option is a bit special; the first part of the value is the + command to execute enclosed in "[]", followed by the binding(s). + + You can configure multiple pipes as long as the command strings + are different and the key bindings are unique. + + Note that the command is *not* automatically run inside a shell; + use *sh -c "command line"* if you need that. + + Example: + *pipe-visible=[sh -c "xurls | uniq | tac | bemenu | xargs -r + firefox"] Control+Print* + + Default: _not bound_ + + +# SECTION: search-bindings + +This section lets you override the default key bindings used in +scrollback search mode. The syntax is exactly the same as the regular +**key-bindings**. + +*cancel* + Aborts the search. The viewport is restored and the _primary + selection_ is **not** updated. Default: _Control+g Escape_. + +*commit* + Exit search mode and copy current selection into the _primary + selection_. Viewport is **not** restored. To copy the selection to + the regular _clipboard_, use *Control+Shift+C*. Default: _Return_. + +*find-prev* + Search **backwards** in the scrollback history for the next + match. Default: _Control+r_. + +*find-next* + Searches **forwards** in the scrollback history for the next + match. Default: _Control+s_. + +*cursor-left* + Moves the cursor in the search box one **character** to the + left. Default: _Left Control+b_. + +*cursor-left-word* + Moves the cursor in the search box one **word** to the + left. Default: _Control+Left Mod1+b_. + +*cursor-right* + Moves the cursor in the search box one **character** to the + right. Default: _Right Control+f_. + +*cursor-right-word* + Moves the cursor in the search box one **word** to the + right. Default: _Control+Left Mod1+b_. + +*cursor-home* + Moves the cursor in the search box to the beginning of the + input. Default: _Home Control+a_. + +*cursor-end* + Moves the cursor in the search box to the end of the + input. Default: _End Control+e_. + +*delete-prev* + Deletes the **character before** the cursor. Default: _BackSpace_. + +*delete-prev-word* + Deletes the **word before** the cursor. Default: _Mod1+BackSpace + Control+BackSpace_. + +*delete-next* + Deletes the **character after** the cursor. Default: _Delete_. + +*delete-next-word* + Deletes the **word after** the cursor. Default: _Mod1+b + Control+Delete_. + +*extend-to-word-boundary* + Extend current selection to the next word boundary. Default: + _Control+w_. + +*extend-to-next-whitespace* + Extend the current selection to the next whitespace. Default: + _Control+Shift+W_. + + +# SECTION: mouse-bindings + +This section lets you override the default mouse bindings. + +The general format is _action=combo1...comboN_. That is, each action +may have one or more key combinations, space separated. Each +combination is on the form _mod1+mod2+BTN\_<name>[-COUNT]_. The names +of the modifiers *must* be valid XKB key names, and the button name +*must* be a valid libinput name. You can find the button names using +*libinput debug-events*. + +Note that *Shift* cannot be used as a modifier in mouse bindings since +it is used to enable selection when the client application is grabbing +the mouse. + +The trailing *COUNT* is optional and specifies the click count +required to trigger the binding. The default if *COUNT* is omitted is +_1_. + +A modifier+button combination can only be mapped to *one* action. Lets +say you want to bind *BTN\_MIDDLE* to *fullscreen*. Since +*BTN\_MIDDLE* is the default binding for *primary-paste*, you first +need to unmap the default binding. This can be done by setting +_action=none_; e.g. *primary-paste=none*. + +All actions listed under *key-bindings* can be user here as well. + +*select-begin* + Begin an interactive selection. The selection is finalized, and + copied to the _primary selection_, when the button is + released. Default: _BTN\_LEFT_. + +*select-begin-block* + Begin an interactive block selection. The selection is finalized, + and copied to the _primary selection_, when the button is + released. Default: _Control+BTN\_LEFT_. + +*select-extend* + Interactively extend an existing selection. The selection is + finalized, and copied to the _primary selection_, when the button + is released. Default: _BTN\_RIGHT_. + +*select-word* + Select the _word_ (separated by spaces, period, comma, parenthesis + etc) under the pointer. Default: _BTN\_LEFT-2_. + +*select-word-whitespace* + Select the _word_ (separated by spaces _only_) under the + pointer. Default: Control+_BTN\_LEFT-2_. + +*select-row* + Select the whole row under the pointer. Default: _BTN\_LEFT-3_. + +*primary-paste* + Pastes from the _primary selection_. Default: _BTN\_MIDDLE_. + + +# FONT FORMAT + +The font is specified in FontConfig syntax. That is, a colon-separated +list of font name and font options. + +_Examples_: +- Dina:weight=bold:slant=italic +- Courier New:size=12 + +# TWEAKS + +This section is for advanced users and describes configuration options +that can be used to tweak foot's low-level behavior. + +These options are *not* included in the example configuration. You +should not change these unless you understand what they do and note +that changing the default values *will* print a warning when launching +foot. + +When reporting bugs, please mention if, and to what, you have changed +any of these options. + +*render-timer* + Enables a frame rendering timer, that prints the time it takes to + render each frame, in microseconds, either on-screen, to stderr, + or both. Valid values are *none*, *osd*, *log* and + *both*. Default: _none_. + +*delayed-render-lower*, *delayed-render-upper* + These two values control the timeouts (in nanoseconds) that are + used to mitigate screen flicker caused by clients writing large, + non-atomic screen updates. + + If a client splits up a screen update over multiple *write*(3) + calls, we may end up rendering an intermediate frame, quickly + followed by another frame with the final screen content. For + example, the client may erase part of the screen (or scroll) in + one write, and then write new content in one or more subsequent + writes. Rendering the frame when the screen has been erased, but + not yet filled with new content will be perceived as screen + flicker. + + The *real* solution to this is _Application Synchronized Updates_ + (https://gitlab.freedesktop.org/terminal-wg/specifications/-/merge_requests/2). + + The problem with this is twofold - first, it has not yet been + standardized, and thus there are not many terminal emulators that + implement it (foot *does* implement it), and second, applications + must be patched to use it. + + Until this has happened, foot offers an interim workaround; an + attempt to mitigate the screen flicker *without* affecting neither + performance nor latency. + + It is based on the fact that the screen is updated at a fixed + interval (typically 60Hz). For us, this means it does not matter + if we render a new frame at the *beginning* of a frame interval, + or at the *end*. Thus, the goal is to introduce a delay between + receiving client data and rendering the resulting state, but + without causing a frame skip. + + While it should be possible to estimate the amount of time left + until the next frame, foot's algorithm is currently not that + advanced, but is based on statistics I guess you could say - the + delay we introduce is so small that the risk of pushing the frame + over to the next frame interval is also very small. + + Now, that was a lot of text. But what is it foot actually does? + + When receiving client data, it schedules a timer, the + *delayed-render-lower*. If we do not receive any more client data + before the timer has run out, we render the frame. If however, we + do receive more data, the timer is re-scheduled. That is, each + time we receive client data, frame rendering is delayed another + *delayed-render-lower* nanoseconds. + + Now, while this works very well with most clients, it would be + possible to construct a malicious client that keeps writing data + at a slow pace. To the user, this would look like foot has frozen + as we never get to render a new frame. To prevent this, an upper + limit is set - *delayed-render-upper*. If this timer runs out, we + render the frame regardless of what the client is doing. + + If changing these values, note that the lower timeout *must* be + set lower than the upper timeout, but that this is not verified by + foot. Furthermore, both values must be less than 16ms (that is, + 16000000 nanoseconds). + + You can disable the feature altogether by setting either value to + 0. In this case, frames are rendered "as soon as possible". + + Default: lower=_500000_ (0.5ms), upper=_8333333_ (8.3ms - half a + frame interval). + +*max-shm-pool-size-mb* + + This option controls the amount of *virtual* memory used by the + pixmap memory to which the terminal screen content is rendered. + + It does *not* change how much physical memory foot uses. + + Foot uses a memory mapping trick to implement fast rendering of + interactive scrolling (typically, but applies to "slow" scrolling + in general). Example: holding down the 'up' or 'down' arrow key to + scroll in a text editor. + + For this to work, it needs a large amount of virtual address + space. Again, note that this is *not* physical memory. + + On a normal x64 based computer, each process has 128TB of virtual + address space, and newer ones have 64PB. This is an insane amount + and most applications do not use anywhere near that amount. + + Each foot terminal window can allocate up to 2GB of virtual + address space. With 128TB of address space, that means a maximum + of 65536 windows in server/daemon mode (for 2GB). That should be + enough, yes? + + However, the Wayland compositor *also* needs to allocate the same + amount of virtual address space. Thus, it has a slightly higher + chance of running out of address space since it needs to host + *all* running Wayland clients in the same way, at the same time. + + In the off chance that this becomes a problem for you, you can + reduce the amount used with this option. + + Or, for optimal performance, you can increase it to the maximum + allowed value, 2GB (but note that you most likely will not notice + any difference compared to the default value). + + Note: this feature is always disabled in 32-bit. + + Default: _512_. Maximum allowed: _2048_ (2GB). + +# SEE ALSO + +*foot*(1), *footclient*(1) |
