Merge branch 'master' into css-import-semicolon

man/waybar-styles.5.scd.in

@@ -8,13 +8,27 @@ waybar-styles - using stylesheets for waybar
 
 Waybar uses Cascading Style Sheets (CSS) to configure its appearance.
 
-It uses the first file found in this search order:
+When the system appearance is light, Waybar first looks for *style-light.css*.
+When the system appearance is dark, Waybar first looks for *style-dark.css*.
+If no appearance-specific stylesheet is found, it falls back to *style.css*.
 
-- *$XDG_CONFIG_HOME/waybar/style.css*
-- *~/.config/waybar/style.css*
-- *~/waybar/style.css*
-- */etc/xdg/waybar/style.css*
-- *@sysconfdir@/xdg/waybar/style.css*
+Waybar uses the first file found in this search order for each stylesheet name:
+
+- *$XDG_CONFIG_HOME/waybar/<stylesheet>*
+- *~/.config/waybar/<stylesheet>*
+- *~/waybar/<stylesheet>*
+- */etc/xdg/waybar/<stylesheet>*
+- *@sysconfdir@/xdg/waybar/<stylesheet>*
+
+For example, a light theme is loaded from the first available file among:
+
+- *$XDG_CONFIG_HOME/waybar/style-light.css*
+- *~/.config/waybar/style-light.css*
+- *~/waybar/style-light.css*
+- */etc/xdg/waybar/style-light.css*
+- *@sysconfdir@/xdg/waybar/style-light.css*
+
+If no file is found there, Waybar repeats the same search using *style.css*.
 
 # EXAMPLE
 
@@ -43,18 +57,17 @@ You can apply special styling to any module for when the cursor hovers it.
 
 Most, if not all, module types support setting the `cursor` option. This is
 configured in your `config.jsonc`. If set to `false`, when hovering the module a
-"pointer"(as commonly known from web CSS styling `cursor: pointer`) style cursor
+"pointer" (as commonly known from web CSS styling `cursor: pointer`) style cursor
 will not be shown. Default behavior is to indicate an interaction event is
 available.
 
-There are more cursor types to choose from by setting the `cursor` option to
-a number, see Gdk3 official docs for all possible cursor types:
-https://docs.gtk.org/gdk3/enum.CursorType.html.
-However, note that not all cursor options listed may be available on
-your system. If you attempt to use a cursor which is not available, the
-application will crash.
+If set to a string value, it must be a valid cursor name
+(e.g. `"pointer"`, `"default"`, `"grab"`, `"text"`, `"crosshair"`, etc.),
+see the cursor-shape-v1 protocol for all possible cursor types:
+https://wayland.app/protocols/cursor-shape-v1#wp_cursor_shape_device_v1:enum:shape.
+Depending on the compositor and cursor theme used, cursors not listed in the protocol may also work.
 
-Example of disabling pointer(`Gdk::Hand2`) cursor type on a custom module:
+Example of disabling the cursor on a custom module:
 
 ```
 "custom/my-custom-module": {
@@ -63,13 +76,12 @@ Example of disabling pointer(`Gdk::Hand2`) cursor type on a custom module:
 }
 ```
 
-Example of setting cursor type to `Gdk::Boat`(according to
-https://docs.gtk.org/gdk3/enum.CursorType.html#boat):
+Example of setting the cursor type to `"grab"`:
 
 ```
 "custom/my-custom-module": {
     ...
-    "cursor": 8,
+    "cursor": "grab",
 }
 ```