From 3d15b96429fa0299e17869b9ac690169b4900228 Mon Sep 17 00:00:00 2001
From: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
Date: Tue, 9 Apr 2024 10:02:33 -0400
Subject: [PATCH] Add waybar-styles(5) manual page

waybar(5) describes the configuration syntax but doesn't mention how
the stylesheets are handled.

This documentation would have been helpful to me as i figured out how
to configure waybar.
---
 man/waybar-styles.5.scd.in | 34 ++++++++++++++++++++++++++++++++++
 man/waybar.5.scd.in        |  3 +++
 meson.build                |  8 ++++++++
 3 files changed, 45 insertions(+)
 create mode 100644 man/waybar-styles.5.scd.in

diff --git a/man/waybar-styles.5.scd.in b/man/waybar-styles.5.scd.in
new file mode 100644
index 00000000..ddc4c3c9
--- /dev/null
+++ b/man/waybar-styles.5.scd.in
@@ -0,0 +1,34 @@
+waybar-styles(5)
+
+# NAME
+
+waybar-styles - using stylesheets for waybar
+
+# DESCRIPTION
+
+Waybar uses Cascading Style Sheets (CSS) to configure its appearance.
+
+It uses the first file found in this search order:
+
+- *$XDG_CONFIG_HOME/waybar/style.css*
+- *~/.config/waybar/style.css*
+- *~/waybar/style.css*
+- */etc/xdg/waybar/style.css*
+- *@sysconfdir@/xdg/waybar/style.css*
+
+# EXAMPLE
+
+An example user-controlled stylesheet that just changes the color of the clock to be green on black, while keeping the rest of the system config the same would be:
+
+```
+@import url("file:///etc/xdg/waybar/style.css")
+
+#clock {
+  background: #000000;
+  color: #00ff00;
+}
+```
+
+# SEE ALSO
+
+- *waybar(5)*
diff --git a/man/waybar.5.scd.in b/man/waybar.5.scd.in
index 5fe30ca8..53613e4a 100644
--- a/man/waybar.5.scd.in
+++ b/man/waybar.5.scd.in
@@ -19,6 +19,8 @@ Valid locations for this file are:
 A good starting point is the default configuration found at https://github.com/Alexays/Waybar/blob/master/resources/config.jsonc
 Also, a minimal example configuration can be found at the bottom of this man page.
 
+The visual display elements for waybar use a CSS stylesheet, see *waybar-styles(5)* for details.
+
 # BAR CONFIGURATION
 
 *layer* ++
@@ -347,3 +349,4 @@ A group may hide all but one element, showing them only on mouse hover. In order
 # SEE ALSO
 
 *sway-output(5)*
+*waybar-styles(5)"
diff --git a/meson.build b/meson.build
index dfdf08a8..92d1ead4 100644
--- a/meson.build
+++ b/meson.build
@@ -539,6 +539,14 @@ if scdoc.found()
         }
     )
 
+    man_files += configure_file(
+        input: 'man/waybar-styles.5.scd.in',
+        output: 'waybar-styles.5.scd',
+        configuration: {
+            'sysconfdir': prefix / sysconfdir
+        }
+    )
+
     fs = import('fs')
     mandir = get_option('mandir')
     foreach file : man_files