Merge pull request #799 from fwSmit/doc-update

Split man pages

.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,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<SETTING> B<[value]>
+
+Where F<SETTING> 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<dunsctl context>. 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<mouse_right_click = close_all> 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 <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,49 +1,20 @@
 =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
 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
+section contains most general settings while the setions 'urgency_low',
-all keyboard configuration and the 'experimental' section all the features that
+'urgency_normal' and 'urgency_critical' are for low, normal and critical urgency
-have not yet been tested thoroughly.
+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
+but also has a lot of extra functionality. So see more see dunstctl(1).
-page.
 
 =head1 HISTORY
 
 Dunst saves a number of notifications (specified by B<history_length>) in memory.
-These notifications can be recalled (i.e. redisplayed) by pressing the
+These notifications can be recalled (i.e. redisplayed) by calling 
-B<history_key> (see the shortcuts section), whether these notifications will
+B<dunstctl history> (see dunstctl(1)). Whether these notifications will time out
-time out like if they have been just send depends on the value of the
+like if they have been just send depends on the value of the B<sticky_history>
-B<sticky_history> setting.
+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
 

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