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

@@ -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,
+Documentation includes the man pages, readme, changelog and license
-changelog and license files.
+files.
 
 `-Ddefault-terminfo`: I strongly recommend leaving the default
 value. Use this option if you plan on installing the terminfo files

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:
+	Path to configuration file, see *foot.ini*(5) for details.
-	*$XDG_CONFIG_HOME/foot/foot.ini*.
 
 *-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),
+	Used to determine the location of the configuration file, see
-	when not found in *${XDG\_CONFIG\_HOME:-~/.config}*.
+	*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

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)

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