From d0dfaf04882a9c60761957338e8bad9f207e1c82 Mon Sep 17 00:00:00 2001 From: fwsmit Date: Tue, 8 Dec 2020 23:51:57 +0100 Subject: [PATCH 1/2] Improve docs --- .gitignore | 1 + Makefile | 8 +- docs/dunst.1.pod | 159 ++++++++++++++++++++++++++++++++ docs/{dunst.pod => dunst.5.pod} | 69 ++++---------- test/test-install.sh | 1 + 5 files changed, 185 insertions(+), 53 deletions(-) create mode 100644 docs/dunst.1.pod rename docs/{dunst.pod => dunst.5.pod} (96%) diff --git a/.gitignore b/.gitignore index f6fb626..8232854 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,7 @@ core vgcore.* /docs/*.1 +/docs/*.5 /docs/internal/coverage /docs/internal/html /dunst diff --git a/Makefile b/Makefile index e3f36d0..01a2528 100644 --- a/Makefile +++ b/Makefile @@ -123,12 +123,14 @@ test/test: ${OBJ} ${TEST_OBJ} ${CC} -o ${@} ${TEST_OBJ} $(filter-out ${TEST_OBJ:test/%=src/%},${OBJ}) ${CFLAGS} ${LDFLAGS} .PHONY: doc doc-doxygen -doc: docs/dunst.1 docs/dunstctl.1 +doc: docs/dunst.1 docs/dunst.5 docs/dunstctl.1 # Can't dedup this as we need to explicitly provide the name and title text to # pod2man :( -docs/dunst.1: docs/dunst.pod +docs/dunst.1: docs/dunst.1.pod ${POD2MAN} --name=dunst -c "Dunst Reference" --section=1 --release=${VERSION} $< > $@ +docs/dunst.5: docs/dunst.5.pod + ${POD2MAN} --name=dunst -c "Dunst Reference" --section=5 --release=${VERSION} $< > $@ docs/dunstctl.1: docs/dunstctl.pod ${POD2MAN} --name=dunstctl -c "dunstctl reference" --section=1 --release=${VERSION} $< > $@ @@ -200,6 +202,7 @@ install: install-dunst install-dunstctl install-doc install-service install-duns install-dunst: dunst doc install -Dm755 dunst ${DESTDIR}${BINDIR}/dunst install -Dm644 docs/dunst.1 ${DESTDIR}${MANPREFIX}/man1/dunst.1 + install -Dm644 docs/dunst.5 ${DESTDIR}${MANPREFIX}/man5/dunst.5 install -Dm644 docs/dunstctl.1 ${DESTDIR}${MANPREFIX}/man1/dunstctl.1 install-dunstctl: dunstctl @@ -224,6 +227,7 @@ uninstall: uninstall-service uninstall-dunstctl rm -f ${DESTDIR}${BINDIR}/dunst rm -f ${DESTDIR}${BINDIR}/dunstify rm -f ${DESTDIR}${MANPREFIX}/man1/dunst.1 + rm -f ${DESTDIR}${MANPREFIX}/man5/dunst.5 rm -f ${DESTDIR}${MANPREFIX}/man1/dunstctl.1 rm -rf ${DESTDIR}${SYSCONFDIR}/dunst diff --git a/docs/dunst.1.pod b/docs/dunst.1.pod new file mode 100644 index 0000000..1641d51 --- /dev/null +++ b/docs/dunst.1.pod @@ -0,0 +1,159 @@ +=head1 NAME + +dunst - A customizable and lightweight notification-daemon + +=head1 SYNOPSIS + +dunst [-conf file] [-font font] [-geometry geom] [-format fmt] [-follow mode] [-monitor n] [-history_length n] ... + +=head1 DESCRIPTION + +Dunst is a highly configurable and lightweight notification daemon. + +=head1 COMMAND LINE OPTIONS + +=over 4 + +=item B<-h/--help> + +List all command line flags + +=item B<-conf/-config file> + +Use alternative config file. + +=item B<-v/--version> + +Print version information. + +=item B<-print> + +Print notifications to stdout. This might be useful for logging, setting up +rules or using the output in other scripts. + +=item B<-*setting* [value]> + +Where *setting* can be any setting that's available in the global section of +the configuration file. See B for possible settings. + +Each configuration option in the global section can be overridden from the +command line by adding a single dash in front of it's name. +For example the font option can be overridden by running + + $ dunst -font "LiberationSans Mono 4" + +Configuration options that take boolean values can only currently be set to +"true" through the command line via the same method. e.g. + + $ dunst -shrink + +This is a known limitation of the way command line parameters are parsed and +will be changed in the future. + +=back + +=head1 CONFIGURATION + +An example configuration file is included (usually /etc/dunst/dunstrc). Note: +this was previously /usr/share/dunst/dunstrc. +Before using dunst, copy this file to ~/.config/dunst/dunstrc and edit +it accordingly. + +=head2 NOTIFY-SEND + +dunst is able to get different colors for a message via notify-send. +In order to do that you have to add a hint via the -h option. +The progress value can be set with a hint, too. + +=over 4 + +=item notify-send -h string:fgcolor:#ff4444 + +=item notify-send -h string:bgcolor:#4444ff -h string:fgcolor:#ff4444 -h string:frcolor:#44ff44 + +=item notify-send -h int:value:42 "Working ..." + +=back + +=head1 ACTIONS + +Dunst allows notifiers (i.e.: programs that send the notifications) to specify +actions. Dunst has support for both displaying indicators for these, and +interacting with these actions. + +If "show_indicators" is true and a notification has an action, an "(A)" will be +prepended to the notification format. Likewise, an "(U)" is prepended to +notifications with URLs. It is possible to interact with notifications that +have actions regardless of this setting, though it may not be obvious which +notifications HAVE actions. + +The "context" keybinding is used to interact with these actions, by showing a +menu of possible actions. This feature requires "dmenu" or a dmenu drop-in +replacement present. + +Alternatively, you can invoke an action with a middle click on the notification. +If there is exactly one associated action, or one is marked as default, that one +is invoked. If there are multiple, the context menu is shown. The same applies +to URLs when there are no actions. + +=head1 MISCELLANEOUS + +Dunst can be paused via the `dunstctl set-paused true` command. To unpause dunst use +`dunstctl set-paused false`. +Alternatively you can send SIGUSR1 and SIGUSR2 to pause and unpause +respectively. For Example: + +=over 4 + +=item killall -SIGUSR1 dunst # pause + +=item killall -SIGUSR2 dunst # resume + +=back + +When paused dunst will not display any notifications but keep all notifications +in a queue. This can for example be wrapped around a screen locker (i3lock, +slock) to prevent flickering of notifications through the lock and to read all +missed notifications after returning to the computer. + +=head1 FILES + +These are the places where dunst will look for a configuration file. They are +listed here in order and if dunst finds one of them, it will stop looking for +more. + +$XDG_CONFIG_HOME/dunst/dunstrc + +$HOME/.config/dunst/dunstrc + +-or- + +$XDG_CONFIG_HOME/dunst/dunstrc + +/etc/xdg/dunst/dunstrc + +=over 4 + +=item /etc/dunst/dunstrc + +This is where the default config file is located + +=back + +=head1 AUTHORS + +Written by Sascha Kruse + +=head1 REPORTING BUGS + +Bugs and suggestions should be reported on GitHub at https://github.com/dunst-project/dunst/issues + +=head1 COPYRIGHT + +Copyright 2013 Sascha Kruse and contributors (see LICENSE for licensing information) + +If you feel that copyrights are violated, please send me an email. + +=head1 SEE ALSO + +dunst(5), dunstctl(1), dwm(1), dmenu(1), twmn(1), notify-send(1) diff --git a/docs/dunst.pod b/docs/dunst.5.pod similarity index 96% rename from docs/dunst.pod rename to docs/dunst.5.pod index c886349..4fabfcb 100644 --- a/docs/dunst.pod +++ b/docs/dunst.5.pod @@ -1,40 +1,9 @@ =head1 NAME -dunst - A customizable and lightweight notification-daemon - -=head1 SYNOPSIS - -dunst [-conf file] [-font font] [-geometry geom] [-format fmt] [-follow mode] [-monitor n] [-history_length n] ... +dunst - configuration file =head1 DESCRIPTION -Dunst is a highly configurable and lightweight notification daemon. - -=head1 COMMAND LINE OPTIONS - -=over 4 - -=item B<-h/--help> - -List all command line flags - -=item B<-conf/-config file> - -Use alternative config file. - -=item B<-v/--version> - -Print version information. - -=item B<-print> - -Print notifications to stdout. This might be useful for logging, setting up -rules or using the output in other scripts. - -=back - -=head1 CONFIGURATION - An example configuration file is included (usually /etc/dunst/dunstrc). Note: this was previously /usr/share/dunst/dunstrc. To change the configuration, copy this file to ~/.config/dunst/dunstrc and edit @@ -51,24 +20,6 @@ more details. For backwards compatibility reasons the section name 'frame' is considered bound and can't be used as a rule. -=head2 Command line - -Each configuration option in the global section can be overridden from the -command line by adding a single dash in front of it's name. -For example the font option can be overridden by running - - $ dunst -font "LiberationSans Mono 4" - -Configuration options that take boolean values can only currently be set to -"true" through the command line via the same method. e.g. - - $ dunst -shrink - -This is a known limitation of the way command line parameters are parsed and -will be changed in the future. - -Available settings per section: - =head2 Global section =over 4 @@ -1009,11 +960,27 @@ missed notifications after returning to the computer. =head1 FILES +These are the places where dunst will look for a configuration file. They are +listed here in order and if dunst finds one of them, it will stop looking for +more. + $XDG_CONFIG_HOME/dunst/dunstrc +$HOME/.config/dunst/dunstrc + -or- -$HOME/.config/dunst/dunstrc +$XDG_CONFIG_HOME/dunst/dunstrc + +/etc/xdg/dunst/dunstrc + +=over 4 + +=item /etc/dunst/dunstrc + +This is where the default config file is located + +=back =head1 AUTHORS diff --git a/test/test-install.sh b/test/test-install.sh index e21ddff..1a5a61a 100755 --- a/test/test-install.sh +++ b/test/test-install.sh @@ -19,6 +19,7 @@ testprefix/bin/dunstctl testprefix/bin/dunstify testprefix/share/man/man1/dunst.1 testprefix/share/man/man1/dunstctl.1 +testprefix/share/man/man5/dunst.5 EOF # make sure to manually sort the above values From 63103f991d5b67b8d2c42d9da522c57751810334 Mon Sep 17 00:00:00 2001 From: fwsmit Date: Fri, 25 Dec 2020 20:04:35 +0100 Subject: [PATCH 2/2] Update a few man page descriptions --- docs/dunst.1.pod | 16 ++++++++++------ docs/dunst.5.pod | 19 ++++++++++--------- 2 files changed, 20 insertions(+), 15 deletions(-) diff --git a/docs/dunst.1.pod b/docs/dunst.1.pod index 1641d51..c667257 100644 --- a/docs/dunst.1.pod +++ b/docs/dunst.1.pod @@ -31,10 +31,10 @@ Print version information. Print notifications to stdout. This might be useful for logging, setting up rules or using the output in other scripts. -=item B<-*setting* [value]> +=item B<->F B<[value]> -Where *setting* can be any setting that's available in the global section of -the configuration file. See B for possible settings. +Where F can be any setting that's available in the global section of +the configuration file. See dunst(5) for possible settings. Each configuration option in the global section can be overridden from the command line by adding a single dash in front of it's name. @@ -57,7 +57,7 @@ will be changed in the future. An example configuration file is included (usually /etc/dunst/dunstrc). Note: this was previously /usr/share/dunst/dunstrc. Before using dunst, copy this file to ~/.config/dunst/dunstrc and edit -it accordingly. +it accordingly. See dunst(5) for all possible settings. =head2 NOTIFY-SEND @@ -89,12 +89,16 @@ notifications HAVE actions. The "context" keybinding is used to interact with these actions, by showing a menu of possible actions. This feature requires "dmenu" or a dmenu drop-in -replacement present. +replacement present. It is preferred to set this keybinding with your window +manager or desktop envirorment and let it execute C. Another +option is to set this keybinding in your dunstrc, but this is soon to be deprecated +(and doesn't work on Wayland). Alternatively, you can invoke an action with a middle click on the notification. If there is exactly one associated action, or one is marked as default, that one is invoked. If there are multiple, the context menu is shown. The same applies -to URLs when there are no actions. +to URLs when there are no actions. You can change the mouse button to right click +by setting C in your dunstrc. =head1 MISCELLANEOUS diff --git a/docs/dunst.5.pod b/docs/dunst.5.pod index 4fabfcb..09a7bf3 100644 --- a/docs/dunst.5.pod +++ b/docs/dunst.5.pod @@ -10,9 +10,11 @@ To change the configuration, copy this file to ~/.config/dunst/dunstrc and edit it accordingly. The configuration is divided into sections in an ini-like format. The 'global' -section contains most general settings while the 'shortcuts' sections contains -all keyboard configuration and the 'experimental' section all the features that -have not yet been tested thoroughly. +section contains most general settings while the setions 'urgency_low', +'urgency_normal' and 'urgency_critical' are for low, normal and critical urgency +notifications respectively. The 'shortcuts' section (deprecated) contains all +keyboard configuration and the 'experimental' section all the features that have +not yet been tested thoroughly. Any section that is not one of the above is assumed to be a rule, see RULES for more details. @@ -640,16 +642,15 @@ See TIME FORMAT for valid times. Dunst now contains a command line control command that can be used to interact with it. It supports all functions previously done only via keyboard shortcuts -but also has a lot of extra functionality. So see more see the dunstctl man -page. +but also has a lot of extra functionality. So see more see dunstctl(1). =head1 HISTORY Dunst saves a number of notifications (specified by B) in memory. -These notifications can be recalled (i.e. redisplayed) by pressing the -B (see the shortcuts section), whether these notifications will -time out like if they have been just send depends on the value of the -B setting. +These notifications can be recalled (i.e. redisplayed) by calling +B (see dunstctl(1)). Whether these notifications will time out +like if they have been just send depends on the value of the B +setting. Past notifications are redisplayed in a first-in-last-out order, meaning that pressing the history key once will bring up the most recent notification that