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..c667257 --- /dev/null +++ b/docs/dunst.1.pod @@ -0,0 +1,163 @@ +=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<->F B<[value]> + +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. +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. See dunst(5) for all possible settings. + +=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. 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. You can change the mouse button to right click +by setting C in your dunstrc. + +=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 94% rename from docs/dunst.pod rename to docs/dunst.5.pod index c886349..09a7bf3 100644 --- a/docs/dunst.pod +++ b/docs/dunst.5.pod @@ -1,49 +1,20 @@ =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 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. @@ -51,24 +22,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 @@ -689,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 @@ -1009,11 +961,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