From 642fdebf8cbe747d60d95857636957151652ec88 Mon Sep 17 00:00:00 2001
From: Aleksei Bavshin <alebastr@fedoraproject.org>
Date: Sun, 11 Dec 2022 20:22:49 -0800
Subject: [PATCH] sway: add initial configuration guide

---
 doc/configuration.adoc | 159 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 159 insertions(+)
 create mode 100644 doc/configuration.adoc

diff --git a/doc/configuration.adoc b/doc/configuration.adoc
new file mode 100644
index 0000000..1eaf998
--- /dev/null
+++ b/doc/configuration.adoc
@@ -0,0 +1,159 @@
+= Configuration guide
+Fedora Sway SIG <sway@lists.fedoraproject.org>
+:source-highlighter: rouge
+:sway-package:   https://packages.fedoraproject.org/pkgs/sway/
+:config-package: https://packages.fedoraproject.org/pkgs/sway-config-fedora/
+:toc:
+
+An overview of the custom Sway configuration shipped in Fedora.
+
+== Configuration profiles
+
+The Sway package in Fedora defers most of the dependencies and the config file
+ownership to the `+sway-config-*+` subpackages.
+This allows us to ship different configuration profiles with different sets of
+runtime dependencies.
+This also allows anyone to create a package with their preferred system-wide
+configuration defaults and use it instead of the default Fedora profiles.
+
+The following profiles are currently defined in the {sway-package}[`sway`]
+source package:
+ 
+ * **sway-config-minimal** - minimal configuration with any optional
+   dependencies omitted.
+   Suitable for headless servers, containers and buildroot usage.
+   Also suitable for building a very minimal installation from scratch.
+
+ * **sway-config-upstream** - the upstream configuration.
+   The only permitted modifications to the config file are adjustments for
+   dependencies currently unavailable in Fedora.
+
+The profiles defined in the {config-package}[`sway-config-fedora`] source
+package:
+
+ * **sway-config-fedora** - customized configuration for Fedora Sway Spin.
+
+The config packages are mutually exclusive, and one of these will always be
+installed.
+The one selected by default is **sway-config-upstream** and the one that will
+be installed with Sway Spin/Sway Desktop Environment group is
+**sway-config-fedora**.
+
+At any moment, you can switch the installed configuration with one of the
+following commands:
+
+[source,shell]
+----
+dnf swap sway-config sway-config-upstream
+dnf swap sway-config sway-config-minimal
+dnf swap sway-config sway-config-fedora
+----
+
+The command will replace the default `+/etc/sway/config+` file and apply the new
+set of dependencies.
+Packages unused by the new profile will be autoremoved.
+
+NOTE: The command will be different for OSTree-based installations, such as Sericea.
+
+== Fedora configuration
+
+**sway-config-fedora** contains the default configuration for Fedora Sway Spin.
+It is built on top of the default Sway config with a few quality of life
+improvements and opinionated changes.
+
+Most of the additions are implemented as a standalone configuration snippets
+stored at `+/usr/share/sway/config.d/+` and automatically loaded from the main
+configuration file.
+
+=== Sections
+
+The configuration snippets we provide are grouped into the following sections:
+
+50-59 (`+50-rules-*.conf+`)::
+Window rules (`+for_window+`, `+assign+` and related configuration).
+
+60-69 (`+60-bindings-*.conf+`, `+65-mode-*.conf+`)::
+Key bindings and binding modes
+
+90-94 (`+90-*.conf+`)::
+System applications: bars, idle daemons and other components.
+
+95-99 (`+95-*.conf+`)::
+Autostart applications
+
+=== Overrides and load precedence
+
+Fedora configuration uses the implementation details of the Sway config loading
+(https://man7.org/linux/man-pages/man3/wordexp.3p.html[`wordexp(3p)`]) to
+implement a configuration overrides mechanism for the snippets.
+
+The priority increases from the packaged configuration to a system-wide
+configuration and an user configuration directories:
+
+ * `+/usr/share/sway/config.d/*.conf+`
+ * `+/etc/sway/config.d/*.conf+`
+ * `+${XDG_CONFIG_HOME:-$HOME/.config}/sway/config.d/*.conf+`
+    (defaults to `+~/.config/sway/config.d/*.conf+`)
+
+The includes are also sorted by a file name across all the directories.
+
+By creating a file with the same name in `+/etc/sway/config.d+` you'll force
+Sway to ignore the corresponding snippet from `+/usr+` and load the one from 
+`+/etc+`.
+Similarly, the configuration snippet from a home directory wins over the earlier
+locations.
+
+To put it even more simple: imagine the distribution configuration file
+`+/usr/share/sway/config.d/90-bar.conf+` that sets waybar as a status bar.
+If you want to prevent waybar from starting, you could create an empty file
+in your home directory:
+
+[source,shell]
+----
+mkdir -p ~/.config/sway/config.d
+touch ~/.config/sway/config.d/90-bar.conf
+----
+
+If you want to set another bar, you just need to add some contents to the file.
+For example, copy the default bar section from the upstream Sway config:
+
+[source,shell]
+----
+mkdir -p ~/.config/sway/config.d
+cat >~/.config/sway/config.d/90-bar.conf <<EOF
+# Read `man 5 sway-bar` for more information about this section.
+bar {
+    position top
+
+    # When the status_command prints a new line to stdout, swaybar updates.
+    # The default just shows the current date and time.
+    status_command while date +'%Y-%m-%d %I:%M:%S %p'; do sleep 1; done
+
+    colors {
+        statusline #ffffff
+        background #323232
+        inactive_workspace #32323200 #32323200 #5c5c5c
+    }
+}
+EOF
+----
+
+=== Debugging the configuration
+
+Sometimes it's useful to know how the configuration loaded by Sway actually looks.
+There are two ways to debug that:
+
+ * Run sway config validation:
+[source,shell]
+----
+sway --debug --validate [--config /path/to/config]
+----
+
+ * Check intermediate files generated by the layered include script
+
+[source,shell]
+----
+less $XDG_RUNTIME_DIR/sway/layered-include-*.conf
+----
+
+TIP: The command referenced may display more than one file. Use `+:n+`/`+:p+` to switch between files in `+less+`