Improve docs

.gitignore

@@ -9,6 +9,7 @@ core
 vgcore.*
 
 /docs/*.1
+/docs/*.5
 /docs/internal/coverage
 /docs/internal/html
 /dunst

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
 

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<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.
+
+=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 <knopwob@googlemail.com>
+
+=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)

docs/dunst.5.pod

@@ -1,40 +1,9 @@
 =head1 NAME
 
-dunst - A customizable and lightweight notification-daemon
+dunst - configuration file
-
-=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.
-
-=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
 

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