From a9edf6d360e05bee8fc630236a0a1db00e369340 Mon Sep 17 00:00:00 2001 From: Erik Reider <35975961+ErikReider@users.noreply.github.com> Date: Sat, 2 Apr 2022 17:52:35 +0200 Subject: [PATCH] Man pages (#104) * Initial man pages * Added meson option and script * Updated Dockerfiles --- Dockerfiles/archlinux | 2 +- Dockerfiles/ubuntu | 2 +- README.md | 40 ++++------- man/swaync-client.1.scd | 53 +++++++++++++++ man/swaync.1.scd | 145 ++++++++++++++++++++++++++++++++++++++++ man/swaync.5.scd | 145 ++++++++++++++++++++++++++++++++++++++++ meson.build | 31 +++++++++ meson_options.txt | 1 + 8 files changed, 390 insertions(+), 29 deletions(-) create mode 100644 man/swaync-client.1.scd create mode 100644 man/swaync.1.scd create mode 100644 man/swaync.5.scd diff --git a/Dockerfiles/archlinux b/Dockerfiles/archlinux index 5c4ec19..f04146b 100644 --- a/Dockerfiles/archlinux +++ b/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 diff --git a/Dockerfiles/ubuntu b/Dockerfiles/ubuntu index 5fee913..6efb800 100644 --- a/Dockerfiles/ubuntu +++ b/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 diff --git a/README.md b/README.md index 998fd0b..37d34c6 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -[![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: -- 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 +. 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 +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). diff --git a/man/swaync-client.1.scd b/man/swaync-client.1.scd new file mode 100644 index 0000000..d344a9c --- /dev/null +++ b/man/swaync-client.1.scd @@ -0,0 +1,53 @@ +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 diff --git a/man/swaync.1.scd b/man/swaync.1.scd new file mode 100644 index 0000000..a1c0313 --- /dev/null +++ b/man/swaync.1.scd @@ -0,0 +1,145 @@ +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* + Use a custom Stylesheet file + +*-c, --config* + 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": "", + "none": "", + "dnd-notification": "", + "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"; +} +``` diff --git a/man/swaync.5.scd b/man/swaync.5.scd new file mode 100644 index 0000000..0188db1 --- /dev/null +++ b/man/swaync.5.scd @@ -0,0 +1,145 @@ +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" + } + } +} +``` diff --git a/meson.build b/meson.build index e91499d..c1fb0a3 100644 --- a/meson.build +++ b/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 diff --git a/meson_options.txt b/meson_options.txt index efd7c9d..8b863f0 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -1,5 +1,6 @@ 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.')