From e6f884a9e1313b530130593e1743cb763b91f6fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Merlin=20B=C3=BCge?= Date: Thu, 21 Apr 2022 10:04:11 +0200 Subject: [PATCH] doc + meson.build: update information about foot.ini, small cleanup - foot.ini.5: mention location of example config file - foot.1: replace outdated (or incomplete) information about the location of the config file with references to foot.ini.5 - foot.1 and foot.ini.5: conform to scdoc specification, thus surround each header with (at least) one blank line. additionally consistently use exactly one line before/after each header (was sometimes two before) - foot.1: some parts of the keybindings had their own section, move into KEYBOARD SHORTCUTS section - foot.1: move EXIT STATUS section to the end where it is commonly found - foot.1: copy information about config file handling from the beginning of foot.ini.5 into the CONFIGURATION section of foot.1 - INSTALL.md: foot.ini is no longer included in the documentation - meson.build: do not bundle foot.ini with documentation anymore, see also https://codeberg.org/dnkl/foot/pulls/1015 Closes #1002 --- INSTALL.md | 4 ++-- doc/foot.1.scd | 45 +++++++++++++++++++++++++++------------------ doc/foot.ini.5.scd | 19 ++++--------------- meson.build | 2 +- 4 files changed, 34 insertions(+), 36 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 40935072..2452fafc 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -149,8 +149,8 @@ Available compile-time options: | `-Ddefault-terminfo` | string | `foot` | Default value of `TERM` | none | | `-Dcustom-terminfo-install-location` | string | `${datadir}/terminfo` | Value to set `TERMINFO` to | None | -Documentation includes the man pages, the example `foot.ini`, readme, -changelog and license files. +Documentation includes the man pages, readme, changelog and license +files. `-Ddefault-terminfo`: I strongly recommend leaving the default value. Use this option if you plan on installing the terminfo files diff --git a/doc/foot.1.scd b/doc/foot.1.scd index 940fe5fd..dfbc6651 100644 --- a/doc/foot.1.scd +++ b/doc/foot.1.scd @@ -1,9 +1,11 @@ foot(1) # NAME + foot - Wayland terminal emulator # SYNOPSIS + *foot* [_OPTIONS_]++ *foot* [_OPTIONS_] <_command_> [_COMMAND OPTIONS_] @@ -23,8 +25,7 @@ the foot command line # OPTIONS *-c*,*--config*=_PATH_ - Path to configuration file. Default: - *$XDG_CONFIG_HOME/foot/foot.ini*. + Path to configuration file, see *foot.ini*(5) for details. *-C*,*--check-config* Verify configuration and then exit with 0 if ok, otherwise exit @@ -164,13 +165,6 @@ the foot command line with the same results as with xterm, instead of producing an "invalid option" error. -# EXIT STATUS - -Foot will exit with code 230 if there is a failure in foot itself. - -In all other cases, the exit code is that of the client application -(i.e. the shell). - # KEYBOARD SHORTCUTS The following keyboard shortcuts are available by default. They can be @@ -211,7 +205,6 @@ default) available; see *foot.ini*(5). *ctrl*+*shift*+*u* Activate URL mode, allowing you to "launch" URLs. - ## SCROLLBACK SEARCH *ctrl*+*r* @@ -245,7 +238,7 @@ default) available; see *foot.ini*(5). selection. The terminal selection is kept, allowing you to press *ctrl*+*shift*+*c* to copy it to the clipboard. -# URL MODE +## URL MODE *t* Toggle URL visibility in jump label. @@ -253,8 +246,7 @@ default) available; see *foot.ini*(5). *escape*, *ctrl*+*g*, *ctrl*+*c*, *ctrl*+*d* Exit URL mode without launching a URL. - -# MOUSE SHORTCUTS +## MOUSE SHORTCUTS *left*, single-click Drag to select; when released, the selected text is copied to the @@ -365,7 +357,18 @@ numbers, when in _application_ mode. # CONFIGURATION -See *foot.ini*(5) +foot will search for a configuration file in the following locations, +in this order: + + - *XDG_CONFIG_HOME/foot/foot.ini* (defaulting to + *~/.config/foot/foot.ini* if unset) + - *XDG_CONFIG_DIRS/foot/foot.ini* (defaulting to + */etc/xdg/foot/foot.ini* if unset) + +An example configuration file containing all options with their default value +commented out will usually be installed to */etc/xdg/foot/foot.ini*. + +For more information, see *foot.ini*(5). # TERMINFO @@ -446,6 +449,12 @@ capability in the multi query. This allows us to send a proper success/fail flag for each queried capability. Responses for all queried capabilities are always sent. No queries are ever dropped. +# EXIT STATUS + +Foot will exit with code 230 if there is a failure in foot itself. + +In all other cases, the exit code is that of the client application +(i.e. the shell). # ENVIRONMENT @@ -456,11 +465,12 @@ The following environment variables are used by foot: specified and the *shell* option in *foot.ini*(5) is not set. *XDG\_CONFIG\_HOME* - Used to determine the default location of *foot.ini*(5). + Used to determine the location of the configuration file, see + *foot.ini*(5) for details. *XDG\_CONFIG\_DIRS* - Used to determine the default fallback location of *foot.ini*(5), - when not found in *${XDG\_CONFIG\_HOME:-~/.config}*. + Used to determine the location of the configuration file, see + *foot.ini*(5) for details. *XDG\_RUNTIME\_DIR* Used to construct the default _PATH_ for the *--server* @@ -507,7 +517,6 @@ The report should contain the following: with symbols. - Steps to reproduce. The more details the better. - # IRC \#foot on irc.libera.chat diff --git a/doc/foot.ini.5.scd b/doc/foot.ini.5.scd index e7dcf3f3..d4226e67 100644 --- a/doc/foot.ini.5.scd +++ b/doc/foot.ini.5.scd @@ -1,6 +1,7 @@ foot.ini(5) # NAME + foot.ini - configuration file for *foot*(1) # DESCRIPTION @@ -18,6 +19,9 @@ in this order: - *XDG_CONFIG_DIRS/foot/foot.ini* (defaulting to */etc/xdg/foot/foot.ini* if unset) +An example configuration file containing all options with their default value +commented out will usually be installed to */etc/xdg/foot/foot.ini*. + # SECTION: main *shell* @@ -301,7 +305,6 @@ in this order: (including SMT). Note that this is not always the best value. In some cases, the number of physical _cores_ is better. - # SECTION: bell *urgent* @@ -333,7 +336,6 @@ in this order: Whether to run the command on *BEL* even while focused. Default: _no_ - # SECTION: scrollback *lines* @@ -359,7 +361,6 @@ in this order: string. This option is ignored if *indicator-position=none*. Default: _empty string_. - # SECTION: url *launch* @@ -403,7 +404,6 @@ in this order: Default: _abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-\_.,~:;/?#@!$&%\*+="'()[]_ - # SECTION: cursor This section controls the cursor style and color. Note that @@ -446,7 +446,6 @@ applications can change these at runtime. Default: _font underline thickness_. - # SECTION: mouse *hide-when-typing* @@ -471,7 +470,6 @@ applications can change these at runtime. Default: _yes_. - # SECTION: colors This section controls the 16 ANSI colors, the default foreground and @@ -559,7 +557,6 @@ can configure the background transparency with the _alpha_ option. Color to use for the underline used to highlight URLs in URL mode. Default: _regular3_. - # SECTION: csd This section controls the look of the _CSDs_ (Client Side @@ -640,7 +637,6 @@ Examples: Close button's background color. Default: use the default _regular1_ color (red). - # SECTION: key-bindings This section lets you override the default key bindings. @@ -765,7 +761,6 @@ e.g. *search-start=none*. jump label with a key sequence that will place the URL in the clipboard. Default: _none_. - # SECTION: search-bindings This section lets you override the default key bindings used in @@ -844,7 +839,6 @@ scrollback search mode. The syntax is exactly the same as the regular Paste from the _primary selection_ into the search buffer. Default: _Shift+Insert_. - # SECTION: url-bindings This section lets you override the default key bindings used in URL @@ -871,7 +865,6 @@ Be careful; do not use single-letter keys that are also used in Default: _t_. - # SECTION: text-bindings This section lets you remap key combinations to custom escape @@ -902,7 +895,6 @@ Another example: to remap _Super+c_ to _Control+c_: *\\x03 = Mod4+c* - # SECTION: mouse-bindings This section lets you override the default mouse bindings. @@ -979,11 +971,9 @@ actions listed under *key-bindings* can be used here as well. *select-extend* operations to be character wise. This action is ignored for block selections. Default: _Control+BTN\_RIGHT_. - *primary-paste* Pastes from the _primary selection_. Default: _BTN\_MIDDLE_. - # TWEAK This section is for advanced users and describes configuration options @@ -1223,7 +1213,6 @@ any of these options. *sixel* Boolean. When enabled, foot will process sixel images. Default: _yes_ - # SEE ALSO *foot*(1), *footclient*(1) diff --git a/meson.build b/meson.build index c552d2a2..7ebdb672 100644 --- a/meson.build +++ b/meson.build @@ -266,11 +266,11 @@ if systemd.found() endif scdoc = dependency('scdoc', native: true, required: get_option('docs')) +install_data('foot.ini', install_dir: join_paths(get_option('sysconfdir'), 'xdg', 'foot')) if scdoc.found() install_data( 'LICENSE', 'README.md', 'CHANGELOG.md', install_dir: join_paths(get_option('datadir'), 'doc', 'foot')) - install_data('foot.ini', install_dir: join_paths(get_option('sysconfdir'), 'xdg', 'foot')) subdir('doc') endif