aboutsummaryrefslogtreecommitdiff
path: root/doc/footrc.5.scd
diff options
context:
space:
mode:
authorDaniel Eklöf <daniel@ekloef.se>2020-08-27 18:02:30 +0000
committerDaniel Eklöf <daniel@ekloef.se>2020-08-27 18:02:30 +0000
commit5c4af880fc62ee509015c28eb0b4c395b956081d (patch)
tree08d84bfad0301cff61ba4f9097f5e8015984ce28 /doc/footrc.5.scd
parentreadme: update references to the configuration file (diff)
doc: rename footrc.5 to foot.ini.5, and update references
Diffstat (limited to 'doc/footrc.5.scd')
-rw-r--r--doc/footrc.5.scd554
1 files changed, 0 insertions, 554 deletions
diff --git a/doc/footrc.5.scd b/doc/footrc.5.scd
deleted file mode 100644
index 1c974d41..00000000
--- a/doc/footrc.5.scd
+++ /dev/null
@@ -1,554 +0,0 @@
-footrc(5)
-
-# NAME
-footrc - 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/footrc_
-- _~/.config/footrc_
-
-# 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)