Man pages (#104)
* Initial man pages * Added meson option and script * Updated Dockerfiles
This commit is contained in:
Erik Reider
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
40
README.md
40
README.md
@@ -1,7 +1,7 @@
|
||||
[](https://github.com/ErikReider/SwayNotificationCenter/actions/workflows/building.yml)
|
||||
|
||||
# SwayNotificationCenter
|
||||
|
||||
[](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).
|
||||
|
||||
|
||||
53
man/swaync-client.1.scd
Normal file
53
man/swaync-client.1.scd
Normal file
@@ -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
|
||||
145
man/swaync.1.scd
Normal file
145
man/swaync.1.scd
Normal file
@@ -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* <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";
|
||||
}
|
||||
```
|
||||
145
man/swaync.5.scd
Normal file
145
man/swaync.5.scd
Normal file
@@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
31
meson.build
31
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
|
||||
|
||||
@@ -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.')
|
||||
|
||||
Reference in New Issue
Block a user