From d0dfaf04882a9c60761957338e8bad9f207e1c82 Mon Sep 17 00:00:00 2001 From: fwsmit Date: Tue, 8 Dec 2020 23:51:57 +0100 Subject: [PATCH] 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