Man pages (#104)

Dockerfiles/archlinux

@@ -3,4 +3,4 @@
 FROM archlinux:latest
 
 RUN pacman-key --init
-RUN pacman -Sy --noconfirm meson gtk3 gobject-introspection vala json-glib libhandy gtk-layer-shell
+RUN pacman -Sy --noconfirm meson gtk3 gobject-introspection vala json-glib libhandy gtk-layer-shell scdoc

Dockerfiles/ubuntu

@@ -3,4 +3,4 @@
 FROM ubuntu:21.10
 
 RUN apt-get update
-RUN DEBIAN_FRONTEND=noninteractive apt install -y meson libwayland-dev libgtk-3-dev gobject-introspection libgirepository1.0-dev valac libjson-glib-dev libhandy-1-dev libgtk-layer-shell-dev
+RUN DEBIAN_FRONTEND=noninteractive apt install -y meson libwayland-dev libgtk-3-dev gobject-introspection libgirepository1.0-dev valac libjson-glib-dev libhandy-1-dev libgtk-layer-shell-dev scdoc

README.md

-[![Building](https://github.com/ErikReider/SwayNotificationCenter/actions/workflows/building.yml/badge.svg)](https://github.com/ErikReider/SwayNotificationCenter/actions/workflows/building.yml)
-
 # SwayNotificationCenter
 
+[![Building](https://github.com/ErikReider/SwayNotificationCenter/actions/workflows/building.yml/badge.svg)](https://github.com/ErikReider/SwayNotificationCenter/actions/workflows/building.yml)
+
 A simple notification daemon with a GTK gui for notifications and the control center
 
 ## Features
@@ -35,7 +35,7 @@ The package is available on the AUR:
 Fedora:
 An **unofficial** build is available in copr:
 
-``` zsh
+```zsh
 dnf copr enable lexa/SwayNotificationCenter
 dnf install SwayNotificationCenter
 ```
@@ -43,7 +43,7 @@ dnf install SwayNotificationCenter
 Gentoo:
 An **unofficial** ebuild is available in [GURU](https://github.com/gentoo/guru)
 
-``` zsh
+```zsh
 eselect repository enable guru
 emaint sync -r guru
 emerge --ask gui-apps/swaync
@@ -109,39 +109,25 @@ To reload css after changes
 
 The main config file is located in `/etc/xdg/swaync/config.json`. Copy it over
 to your `.config/swaync/` folder to customize without needing root access.
+See `swaync(1)` man page for more information
 
 To reload the config, you'll need to run `swaync-client --reload-config`
 
-- `positionX`: `left`, `right` or `center`
-- `positionY`: `top` or `bottom`
-- `timeout`: uint (Any positive number). The notification timeout for notifications with normal priority
-- `timeout-low`: uint (any positive number without decimals). The notification timeout for notifications with low priority
-- `timeout-critical`: uint (any positive number without decimals, 0 to disable). The notification timeout for notifications with critical priority
-- `keyboard-shortcuts`: `true` or `false`. If control center should use keyboard shortcuts
-- `image-visibility`: `always`, `when-available` or `never`. Notification image visiblilty
-- `transition-time`: uint (Any positive number, 0 to disable). The notification animation duration
-- `notification-window-width`: uint (Any positive number). Width of the notification in pixels
-- `hide-on-clear`: bool. Hides the control center after pressing "Clear All"
-- `hide-on-action`: bool. Hides the control center when clicking on notification action
-- `control-center-margin-top`: uint (Any positive number, 0 to disable). The margin (in pixels) at the top of the notification center
-- `control-center-margin-bottom`: uint (Any positive number, 0 to disable). The margin (in pixels) at the bottom of the notification center
-- `control-center-margin-right`: uint (Any positive number, 0 to disable). The margin (in pixels) at the right of the notification center
-- `control-center-margin-left`: uint (Any positive number, 0 to disable). The margin (in pixels) at the left of the notification center
-- `script-fail-notify`: bool. Sends a notification with error message if a script fails
-
-The main CSS style file is located in `/etc/xdg/swaync/style.css`. Copy it over to your `.config/swaync/` folder to customize without needing root access.
+The main CSS style file is located in `/etc/xdg/swaync/style.css`. Copy it over to your `~/.config/swaync/` folder to customize without needing root access.
 
 ## Scripting
 
 Scripting rules and logic:
 
-- <b>Only one</b> script can be fired per notification
-- Each script requires `exec` and at least one of the other properties
-- All listed properties must match the notification for the script to be ran
-- If any of the propeties doesn't match, the script will be skipped
-- If a notification doesn't include one of the properties, that property will
+. <b>Only one</b> script can be fired per notification
+. Each script requires `exec` and at least one of the other properties
+. All listed properties must match the notification for the script to be ran
+. If any of the propeties doesn't match, the script will be skipped
+. If a notification doesn't include one of the properties, that property will
 be skipped
 
+More information can be found in the `swaync(5)` man page
+
 Notification information can be printed into a terminal by running
 `G_MESSAGES_DEBUG=all swaync` (when a notification appears).
 

man/swaync-client.1.scd

+swaync-client(1)
+
+# NAME
+
+swaync-client - Client executable
+
+# USAGE
+
+*swaync-client* [option]
+
+# OPTIONS
+
+*-h, --help*
+	Show help options
+
+*-v, --version*
+	Prints version
+
+*-R, --reload-config*
+	Reload the config file
+
+*-rs, --reload-css*
+	Reload the css file. Location change requires restart
+
+*-t, --toggle-panel*
+	Toggle the notificaion panel
+
+*-op, --open-panel*
+	Opens the notificaion panel
+
+*-cp, --close-panel*
+	Closes the notificaion panel
+
+*-d, --toggle-dnd*
+	Toggle and print the current dnd state
+
+*-D, --get-dnd*
+	Print the current dnd state
+
+*-c, --count*
+	Print the current notificaion count
+
+*-C, --close-all*
+	Closes all notifications
+
+*-sw, --skip-wait*
+	Doesn't wait when swaync hasn't been started
+
+*-s, --subscribe*
+	Subscribe to notificaion add and close events
+
+*-swb, --subscribe-waybar*
+	Subscribe to notificaion add and close events with waybar support. Read README for example

man/swaync.1.scd

+swaync(1)
+
+# NAME
+
+swaync - A simple notification daemon with a GTK gui for notifications and the control center
+
+# USAGE
+
+*swaync* [option]
+
+# OPTIONS
+
+*-h, --help*
+	Show help options
+
+*-v, --version*
+	Prints version
+
+*-s, --style* <CSS file>
+	Use a custom Stylesheet file
+
+*-c, --config* <Config file>
+	Use a custom config file
+
+# Control Center Keyboard Shortcuts
+
+*Up/Down*: Navigate notifications
+
+*Home*: Navigate to the latest notification
+
+*End*: Navigate to the oldest notification
+
+*Escape/Caps_Lock*: Close notification panel
+
+*Return*: Execute default action or close notification if none
+
+*Delete/BackSpace*: Close notification
+
+*Shift+C*: Close all notifications
+
+*Shift+D*: Toggle Do Not Disturb
+
+*Buttons 1-9*: Execute alternative actions
+
+# CONFIGURATION
+
+The main config file is located in */etc/xdg/swaync/config.json*. Copy it over
+to your *~/.config/swaync/* folder to customize without needing root access.
+
+To reload the config, you'll need to run *swaync-client --reload-config*
+
+For information on the config file format, see *swaync*(5)
+
+
+# Scripting
+
+Scripting rules and logic:
+
+. *Only one* script can be fired per notification
+. Each script requires `exec` and at least one of the other properties
+. All listed properties must match the notification for the script to be ran
+. If any of the propeties doesn't match, the script will be skipped
+. If a notification doesn't include one of the properties, that property will be skipped
+
+Notification information can be printed into a terminal by running
+*G_MESSAGES_DEBUG=all swaync* (when a notification appears).
+
+Config properties:
+
+```
+{
+	"scripts": {
+		"example-script": {
+			"exec": "Your shell command or script here...",
+			"app-name": "Notification app-name Regex",
+			"summary": "Notification summary Regex",
+			"body": "Notification body Regex",
+			"urgency": "Low or Normal or Critical",
+			"category": "Notification category Regex"
+		}
+	}
+	other non scripting properties...
+}
+```
+
+*config.json* example:
+
+```
+{
+	"scripts": {
+		// This script will only run when Spotify sends a notification containing
+		// that exact summary and body
+		"example-script": {
+			"exec": "~/.config/swaync/myRickRollScript.sh",
+			"app-name": "Spotify"
+			"summary": "Never Gonna Give You Up",
+			"body": "Rick Astley - Whenever You Need Somebody"
+		}
+	}
+	other non scripting properties...
+}
+```
+
+## Disable scripting
+
+To completely disable scripting, the project needs to be built like so:
+
+```
+meson build -Dscripting=false
+ninja -C build
+meson install -C build
+```
+
+# Waybar Example
+
+This example requires *NotoSansMono Nerd Font* to get the icons looking right
+
+Waybar config
+
+```
+"custom/notification": {
+	"tooltip": false,
+	"format": "{icon}",
+	"format-icons": {
+		"notification": "<span foreground='red'><sup></sup></span>",
+		"none": "",
+		"dnd-notification": "<span foreground='red'><sup></sup></span>",
+		"dnd-none": ""
+	},
+	"return-type": "json",
+	"exec-if": "which swaync-client",
+	"exec": "swaync-client -swb",
+	"on-click": "swaync-client -t -sw",
+	"on-click-right": "swaync-client -d -sw",
+	"escape": true
+},
+```
+
+Waybar css file
+
+```
+#custom-notification {
+	font-family: "NotoSansMono Nerd Font";
+}
+```

man/swaync.5.scd

+swaync(5)
+
+# NAME
+
+swaync - Configuration file
+
+# CONFIGURATION
+
+Using a text editor with a JSON language server is recommended when editing the
+config file to be able to detect config errors
+
+*positionX* ++
+	type: string ++
+	default: right ++
+	values: left, right, center ++
+	description: Horizontal position of control center and notification window
+
+*positionY* ++
+	type: string ++
+	default: top ++
+	values: top, bottom ++
+	description: Vertical position of control center and notification window
+
+*control-center-margin-top* ++
+	type: integer ++
+	default: 0 ++
+	description: The margin (in pixels) at the top of the notification center. 0 to disable
+
+*control-center-margin-bottom* ++
+	type: integer ++
+	default: 0 ++
+	description: The margin (in pixels) at the bottom of the notification center. 0 to disable
+
+*control-center-margin-right* ++
+	type: integer ++
+	default: 0 ++
+	description: The margin (in pixels) at the right of the notification center. 0 to disable
+
+*control-center-margin-left* ++
+	type: integer ++
+	default: 0 ++
+	description: The margin (in pixels) at the left of the notification center. 0 to disable
+
+*timeout* ++
+	type: integer ++
+	default: 10 ++
+	description: The notification timeout for notifications with normal priority
+
+*timeout-low* ++
+	type: integer ++
+	default: 5 ++
+	description: The notification timeout for notifications with low priority
+
+*timeout-critical* ++
+	type: integer ++
+	default: 0 ++
+	description: The notification timeout for notifications with critical priority. 0 to disable
+
+*notification-window-width* ++
+	type: integer ++
+	default: 500 ++
+	description: Width of the notification in pixels
+
+*keyboard-shortcuts* ++
+	type: bool ++
+	default: true ++
+	description: If control center should use keyboard shortcuts
+
+*image-visibility* ++
+	type: string ++
+	default: always ++
+	values: always, when-available, never ++
+	description: An explanation about the purpose of this instance.
+
+*transition-time* ++
+	type: integer ++
+	default: 200 ++
+	description: The notification animation duration. 0 to disable
+
+*hide-on-clear* ++
+	type: bool ++
+	default: false ++
+	description: Hides the control center after pressing "Clear All"
+
+*hide-on-action* ++
+	type: bool ++
+	default: true ++
+	description: Hides the control center when clicking on notification action
+
+# IF BUILT WITH SCRIPTING
+
+*script-fail-notify* ++
+	type: bool ++
+	default: true ++
+	description: Sends a notification if a script fails to run
+
+*scripts* ++
+	type: object ++
+	script object properties: ++
+		*exec*++
+			type: string ++
+			optional: false ++
+			description: The script to run. Can also run regular shell commands.++
+		*app-name*++
+			type: string ++
+			optional: true ++
+			description: The app-name. Uses Regex.++
+		*summary*++
+			type: string ++
+			optional: true ++
+			description: The summary of the notification. Uses Regex.++
+		*body*++
+			type: string ++
+			optional: true ++
+			description: The body of the notification. Uses Regex.++
+		*urgency*++
+			type: string ++
+			optional: true ++
+			default: Normal ++
+			values: Low, Normal, Critical ++
+			description: The urgency of the notification.++
+		*category*++
+			type: string ++
+			optional: true ++
+			description: Which category the notification belongs to. Uses Regex.++
+	description: Which scripts to check and potentially run for every ++
+		notification. If the notification doesn't include one of the properites, ++
+		that property will be ignored. All properties (except for exec) use regex. ++
+		If all properties match the given notification, the script will be run. ++
+		Only the first matching script will be run. ++
+	example:
+```
+{
+	"scripts": {
+		"example-script": {
+			"exec": "Your shell command or script here...",
+			"app-name": "Notification app-name Regex",
+			"summary": "Notification summary Regex",
+			"body": "Notification body Regex",
+			"urgency": "Low or Normal or Critical",
+			"category": "Notification category Regex"
+		}
+	}
+}
+```

meson.build

@@ -88,3 +88,34 @@ if get_option('fish-completions')
   install_data(fish_files, install_dir: fish_install_dir)
 endif
 
+# Man pages
+man_pages = get_option('man-pages')
+scdoc = dependency('scdoc', version: '>=1.9.2', native: true, required: man_pages)
+if scdoc.found()
+  scdoc_prog = find_program(scdoc.get_pkgconfig_variable('scdoc'), native: true)
+
+  mandir = get_option('mandir')
+  man_files = [
+    'swaync.1.scd',
+    'swaync.5.scd',
+    'swaync-client.1.scd',
+  ]
+
+  foreach filename : man_files
+    topic = filename.split('.')[-3].split('/')[-1]
+    section = filename.split('.')[-2]
+    output = '@0@.@1@'.format(topic, section)
+    message(mandir, section, '@0@/man@1@'.format(mandir, section))
+
+    custom_target(
+      output,
+      input: join_paths('man', filename),
+      output: output,
+      command: scdoc_prog,
+      install: true,
+      feed: true,
+      capture: true,
+      install_dir: '@0@/man@1@'.format(mandir, section)
+    )
+  endforeach
+endif

meson_options.txt

 option('systemd-service', type: 'boolean', value: true, description: 'Install systemd user service unit.')
 option('scripting', type: 'boolean', value: true, description: 'Enable notification scripting.')
+option('man-pages', type: 'boolean', value: true, description: 'Install all man pages.')
 option('zsh-completions', type: 'boolean', value: true, description: 'Install zsh shell completions.')
 option('bash-completions', type: 'boolean', value: true, description: 'Install bash shell completions.')
 option('fish-completions', type: 'boolean', value: true, description: 'Install fish shell completions.')