diff --git a/README.md b/README.md index 985c7e33..d213ce24 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,6 @@ The fast, lightweight and minimalistic Wayland terminal emulator. [![Packaging status](https://repology.org/badge/vertical-allrepos/foot.svg?columns=4)](https://repology.org/project/foot/versions) - ## Index 1. [Features](#features) @@ -16,17 +15,17 @@ The fast, lightweight and minimalistic Wayland terminal emulator. 1. [Why the name 'foot'?](#why-the-name-foot) 1. [Fonts](#fonts) 1. [Shortcuts](#shortcuts) - 1. [Keyboard](#keyboard) - 1. [Normal mode](#normal-mode) - 1. [Scrollback search](#scrollback-search) - 1. [Mouse](#mouse) - 1. [Touchscreen](#touchscreen) + 1. [Keyboard](#keyboard) + 1. [Normal mode](#normal-mode) + 1. [Scrollback search](#scrollback-search) + 1. [Mouse](#mouse) + 1. [Touchscreen](#touchscreen) 1. [Server (daemon) mode](#server-daemon-mode) 1. [URLs](#urls) 1. [Shell integration](#shell-integration) - 1. [Current working directory](#current-working-directory) - 1. [Jumping between prompts](#jumping-between-prompts) - 1. [Piping last command's output](#piping-last-command-s-output) + 1. [Current working directory](#current-working-directory) + 1. [Jumping between prompts](#jumping-between-prompts) + 1. [Piping last command's output](#piping-last-command-s-output) 1. [Alt/meta](#alt-meta) 1. [Backspace](#backspace) 1. [Keypad](#keypad) @@ -38,57 +37,52 @@ The fast, lightweight and minimalistic Wayland terminal emulator. 1. [Code of Conduct](#code-of-conduct) 1. [Bugs](#bugs) 1. [Contact](#contact) - 1. [IRC](#irc) - 1. [Mastodon](#mastodon) + 1. [IRC](#irc) + 1. [Mastodon](#mastodon) 1. [Sponsoring/donations](#sponsoring-donations) 1. [License](#license) - ## Features -* Fast (see [benchmarks](doc/benchmark.md), and +- Fast (see [benchmarks](doc/benchmark.md), and [performance](https://codeberg.org/dnkl/foot/wiki/Performance)) -* Lightweight, in dependencies, on-disk and in-memory -* Wayland native -* DE agnostic -* Server/daemon mode -* User configurable font fallback -* On-the-fly font resize -* On-the-fly DPI font size adjustment -* Scrollback search -* Keyboard driven URL detection -* Color emoji support -* IME (via `text-input-v3`) -* Multi-seat -* True Color (24bpp) -* [Styled and colored underlines](https://sw.kovidgoyal.net/kitty/underlines/) -* [Synchronized Updates](https://gitlab.freedesktop.org/terminal-wg/specifications/-/merge_requests/2) support -* [Sixel image support](https://en.wikipedia.org/wiki/Sixel) - - ![tux-with-foot](doc/sixel-tux-foot.png "Sixel screenshot") +- Lightweight, in dependencies, on-disk and in-memory +- Wayland native +- DE agnostic +- Server/daemon mode +- User configurable font fallback +- On-the-fly font resize +- On-the-fly DPI font size adjustment +- Scrollback search +- Keyboard driven URL detection +- Color emoji support +- IME (via `text-input-v3`) +- Multi-seat +- True Color (24bpp) +- [Styled and colored underlines](https://sw.kovidgoyal.net/kitty/underlines/) +- [Synchronized Updates](https://gitlab.freedesktop.org/terminal-wg/specifications/-/merge_requests/2) support +- [Sixel image support](https://en.wikipedia.org/wiki/Sixel) + ![tux-with-foot](doc/sixel-tux-foot.png "Sixel screenshot") # Installing See [INSTALL.md](INSTALL.md). - ## Configuration **foot** can be configured by creating a file `$XDG_CONFIG_HOME/foot/foot.ini` (defaulting to -`~/.config/foot/foot.ini`). A template for that can usually be found +`~/.config/foot/foot.ini`). A template for that can usually be found in `/etc/xdg/foot/foot.ini` or [here](https://codeberg.org/dnkl/foot/src/branch/master/foot.ini). Further information can be found in foot's man page `foot.ini(5)`. - ## Troubleshooting See the [wiki](https://codeberg.org/dnkl/foot/wiki#user-content-troubleshooting) - ## Why the name 'foot'? I'm bad at names. Most of my projects usually start out as _foo @@ -105,7 +99,6 @@ As a side note, if you pronounce the _foo_ part of _foot_ the same way you pronounce _foobar_, then _foot_ sounds a lot like the Swedish word _fot_, which incidentally means (you guessed it) _foot_. - ## Fonts **foot** supports all fonts that can be loaded by _freetype_, @@ -119,18 +112,16 @@ fallback fonts to use. This also means you can configure _each_ fallback font individually; you want _that_ fallback font to use _this_ size, and you want that -_other_ fallback font to be _italic_? No problem! +_other_ fallback font to be _italic_? No problem! If a glyph cannot be found in _any_ of the user configured fallback fonts, _then_ fontconfig's list is used. - ## Shortcuts These are the default shortcuts. See `man foot.ini` and the example `foot.ini` to see how these can be changed. - ### Keyboard #### Normal mode @@ -161,25 +152,24 @@ These are the default shortcuts. See `man foot.ini` and the example ctrl+shift+n : Spawn a new terminal. If the shell has been [configured to emit the - OSC 7 escape - sequence](https://codeberg.org/dnkl/foot/wiki#user-content-spawning-new-terminal-instances-in-the-current-working-directory), - the new terminal will start in the current working directory. +OSC 7 escape +sequence](https://codeberg.org/dnkl/foot/wiki#user-content-spawning-new-terminal-instances-in-the-current-working-directory), +the new terminal will start in the current working directory. ctrl+shift+o : Enter URL mode, where all currently visible URLs are tagged with a - jump label with a key sequence that will open the URL. +jump label with a key sequence that will open the URL. ctrl+shift+u : Enter Unicode input mode. ctrl+shift+z : Jump to the previous, currently not visible, prompt. Requires [shell - integration](https://codeberg.org/dnkl/foot/wiki#user-content-jumping-between-prompts). +integration](https://codeberg.org/dnkl/foot/wiki#user-content-jumping-between-prompts). ctrl+shift+x : Jump to the next prompt. Requires [shell - integration](https://codeberg.org/dnkl/foot/wiki#user-content-jumping-between-prompts). - +integration](https://codeberg.org/dnkl/foot/wiki#user-content-jumping-between-prompts). #### Scrollback search @@ -191,12 +181,12 @@ These are the default shortcuts. See `man foot.ini` and the example ctrl+w : Extend current selection (and thus the search criteria) to the end - of the word, or the next word if currently at a word separating - character. +of the word, or the next word if currently at a word separating +character. ctrl+shift+w : Same as ctrl+w, except that the only word - separating characters are whitespace characters. +separating characters are whitespace characters. ctrl+v, ctrl+shift+v, ctrl+y, XF86Paste : Paste from clipboard into the search buffer. @@ -209,8 +199,7 @@ These are the default shortcuts. See `man foot.ini` and the example return : Finish the search and copy the current match to the primary - selection - +selection ### URL mode @@ -220,25 +209,24 @@ These are the default shortcuts. See `man foot.ini` and the example escape, ctrl+c, ctrl+g, ctrl+d : Exit URL mode without launching any URLs - ### Mouse left - **single-click** : Drag to select; when released, the selected text is copied to the - _primary_ selection. This feature is **disabled** when client has - enabled _mouse tracking_. +_primary_ selection. This feature is **disabled** when client has +enabled _mouse tracking_. : Holding shift enables selection in mouse tracking enabled - clients. +clients. : Holding ctrl will create a block selection. left - **double-click** : Selects the _word_ (separated by spaces, period, comma, parenthesis - etc) under the pointer. Hold ctrl to select everything - under the pointer up to, and until, the next space characters. +etc) under the pointer. Hold ctrl to select everything +under the pointer up to, and until, the next space characters. left - **triple-click** : Selects the everything between enclosing quotes, or the entire row - if not inside a quote. +if not inside a quote. left - **quad-click** : Selects the entire row. @@ -248,12 +236,12 @@ These are the default shortcuts. See `man foot.ini` and the example right : Extend current selection. Clicking immediately extends the - selection, while hold-and-drag allows you to interactively resize - the selection. +selection, while hold-and-drag allows you to interactively resize +the selection. ctrl+right : Extend the current selection, but force it to be character wise, - rather than depending on the original selection mode. +rather than depending on the original selection mode. wheel : Scroll up/down in history @@ -261,7 +249,6 @@ These are the default shortcuts. See `man foot.ini` and the example ctrl+wheel : Increase/decrease font size - ### Touchscreen tap @@ -270,8 +257,7 @@ These are the default shortcuts. See `man foot.ini` and the example drag : Scrolls up/down in history. : Holding for a while before dragging (time delay can be configured) - emulates mouse dragging with left button held. - +emulates mouse dragging with left button held. ## Server (daemon) mode @@ -333,7 +319,6 @@ the clipboard. It is unbound by default. Jump label colors, the URL underline color, and the letters used in the jump label key sequences can be configured. - ## Shell integration ### Current working directory @@ -348,7 +333,6 @@ scripted to do this, if they do not support it natively. See the [wiki](https://codeberg.org/dnkl/foot/wiki#user-content-spawning-new-terminal-instances-in-the-current-working-directory) for details. - ### Jumping between prompts Foot can move the current viewport to focus prompts of already @@ -407,7 +391,6 @@ See the [wiki](https://codeberg.org/dnkl/foot/wiki#user-content-piping-last-command-s-output) for details, and examples for other shells - ## Alt/meta By default, foot prefixes _Meta characters_ with ESC. This corresponds @@ -424,7 +407,6 @@ This can also be disabled programmatically with `rmm` (_reset meta mode_, `\E[?1034l`), and enabled again with `smm` (_set meta mode_, `\E[?1034h`). - ## Backspace Foot transmits DEL (`^?`) on backspace. This corresponds to @@ -440,7 +422,6 @@ described above **cannot** be changed. Finally, pressing alt will prefix the transmitted byte with ESC. - ## Keypad By default, Num Lock overrides the run-time configuration @@ -459,7 +440,6 @@ again with `\E[?1035h`). When disabled, the keypad sends custom escape sequences instead of numbers, when in _application_ mode. - ## DPI and font size Font sizes are apparently a complex thing. Many applications use a @@ -503,7 +483,6 @@ distance**, the font size will appear to be the same, at all times. _Note_: if you configure **pixelsize**, rather than **size**, then DPI changes will **not** change the font size. Pixels are always pixels. - ### Fractional scaling on Wayland For a long time, there was no **true** support for _fractional @@ -520,42 +499,40 @@ allows compositors to tell applications the _actual_ scaling factor. Applications can then scale the image using a _viewport_ object, instead of setting a scale factor on the raw pixel buffer. - ## Supported OSCs OSC, _Operating System Command_, are escape sequences that interacts with the terminal emulator itself. Foot implements the following OSCs: -* `OSC 0` - change window icon + title (but only title is actually +- `OSC 0` - change window icon + title (but only title is actually supported) -* `OSC 2` - change window title -* `OSC 4` - change color palette -* `OSC 7` - report CWD (see [shell integration](#shell-integration)) -* `OSC 8` - hyperlink -* `OSC 9` - desktop notification -* `OSC 10` - change (default) foreground color -* `OSC 11` - change (default) background color -* `OSC 12` - change cursor color -* `OSC 17` - change highlight (selection) background color -* `OSC 19` - change highlight (selection) foreground color -* `OSC 22` - set the xcursor (mouse) pointer -* `OSC 52` - copy/paste clipboard data -* `OSC 104` - reset color palette -* `OSC 110` - reset default foreground color -* `OSC 111` - reset default background color -* `OSC 112` - reset cursor color -* `OSC 117` - reset highlight background color -* `OSC 119` - reset highlight foreground color -* `OSC 133` - [shell integration](#shell-integration) -* `OSC 176` - set app ID -* `OSC 555` - flash screen (**foot specific**) -* `OSC 777` - desktop notification (only the `;notify` sub-command of +- `OSC 2` - change window title +- `OSC 4` - change color palette +- `OSC 7` - report CWD (see [shell integration](#shell-integration)) +- `OSC 8` - hyperlink +- `OSC 9` - desktop notification +- `OSC 10` - change (default) foreground color +- `OSC 11` - change (default) background color +- `OSC 12` - change cursor color +- `OSC 17` - change highlight (selection) background color +- `OSC 19` - change highlight (selection) foreground color +- `OSC 22` - set the xcursor (mouse) pointer +- `OSC 52` - copy/paste clipboard data +- `OSC 104` - reset color palette +- `OSC 110` - reset default foreground color +- `OSC 111` - reset default background color +- `OSC 112` - reset cursor color +- `OSC 117` - reset highlight background color +- `OSC 119` - reset highlight foreground color +- `OSC 133` - [shell integration](#shell-integration) +- `OSC 176` - set app ID +- `OSC 555` - flash screen (**foot specific**) +- `OSC 777` - desktop notification (only the `;notify` sub-command of OSC 777 is supported.) See the **foot-ctlseqs**(7) man page for a complete list of supported control sequences. - ## Programmatically checking if running in foot Foot does **not** set any environment variables that can be used to @@ -589,7 +566,6 @@ which it will reply with `\EP>|foot(version)\E\\`. Version is e.g. "1.8.2" for a regular release, or "1.8.2-36-g7db8e06f" for a git build. - # XTGETTCAP `XTGETTCAP` is an escape sequence initially introduced by XTerm, and @@ -604,9 +580,9 @@ foot's terminfo on remote hosts you SSH into. XTerm's implementation (as of XTerm-370) only supports querying key (as in keyboard keys) capabilities, and three custom capabilities: -* `TN` - terminal name -* `Co` - number of colors (alias for the `colors` capability) -* `RGB` - number of bits per color channel (different semantics from +- `TN` - terminal name +- `Co` - number of colors (alias for the `colors` capability) +- `RGB` - number of bits per color channel (different semantics from the `RGB` capability in file-based terminfo definitions!). Kitty has extended this, and also supports querying all integer and @@ -622,11 +598,11 @@ multi-capability queries slightly differently, compared to XTerm. XTerm will send a single DCS reply, with `;`-separated capability/value pairs. There are a couple of issues with this: -* The success/fail flag in the beginning of the response is always `1` +- The success/fail flag in the beginning of the response is always `1` (success), unless the very **first** queried capability is invalid. -* XTerm will not respond **at all** to an invalid capability, unless +- XTerm will not respond **at all** to an invalid capability, unless it's the first one in the `XTGETTCAP` query. -* XTerm will end the response at the first invalid capability. +- XTerm will end the response at the first invalid capability. In other words, if you send a large multi-capability query, you will only get responses up to, but not including, the first invalid @@ -645,18 +621,15 @@ In addition to queries for terminfo entries, the `query-os-name` query will be answered with a response of the form `uname=$(uname -s)`, where `$(uname -s)` is the name of the OS foot was compiled for. - # Credits -* [Ordoviz](https://codeberg.org/Ordoviz), for designing and -contributing foot's [logo](icons/hicolor/48x48/apps/foot.png). - +- [Ordoviz](https://codeberg.org/Ordoviz), for designing and + contributing foot's [logo](icons/hicolor/48x48/apps/foot.png). # Code of Conduct See [Code of Conduct](CODE_OF_CONDUCT.md) - # Bugs Please report bugs to https://codeberg.org/dnkl/foot/issues @@ -674,7 +647,6 @@ The report should contain the following: with symbols. - Steps to reproduce. The more details the better. - # Contact ## IRC @@ -684,21 +656,22 @@ channel on [irc.libera.chat](https://web.libera.chat/?channels=#foot). Logs are available at https://libera.irclog.whitequark.org/foot. - ## Mastodon Every now and then I post foot related updates on [@dnkl@social.treehouse.systems](https://social.treehouse.systems/@dnkl) - # Sponsoring/donations -* Liberapay: https://liberapay.com/dnkl -* GitHub Sponsors: https://github.com/sponsors/dnkl +- Liberapay: https://liberapay.com/dnkl +- GitHub Sponsors: https://github.com/sponsors/dnkl [![Donate using Liberapay](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/dnkl/donate) - # License Foot is released under the [MIT license](LICENSE). + +## Educational Note + +This repository is used for learning Git workflow.