From 24e43809270ea0675d90e54ccec2ad72d1b78593 Mon Sep 17 00:00:00 2001 From: WhitePeter Date: Sat, 16 Oct 2021 01:37:30 +0200 Subject: [PATCH] dunst.1: Document drop-in support. Also some refinements to the FILES section. --- docs/dunst.1.pod | 51 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 35 insertions(+), 16 deletions(-) diff --git a/docs/dunst.1.pod b/docs/dunst.1.pod index 1f85ceb7e..b6a0c48ba 100644 --- a/docs/dunst.1.pod +++ b/docs/dunst.1.pod @@ -107,38 +107,57 @@ missed notifications after returning to the computer. =head1 FILES These are the base directories dunst searches for configuration files in -descending order of imortance: +I: -=over 4 +=over 8 + +=item C<$XDG_CONFIG_HOME> + +This is the most important directory. (C<$HOME/.config> if unset or empty) -$XDG_CONFIG_HOME ($HOME/.config if unset or empty) +=item C<$XDG_CONFIG_DIRS> -$XDG_CONFIG_DIRS (:-separated list of base directories in descending order -of importance; ##SYSCONFDIR## if unset or empty) +This, like C<$PATH> for instance, is a :-separated list of base directories +in I. +(F<##SYSCONFDIR##> if unset or empty) =back -Dunst will search these directories for the following relative path: +Dunst will search these directories for the following relative file paths: -=over 4 +=over 8 -dunst/dunstrc +=item F -=back +This is the base config and as such the least important in a particular base +directory. -All settings from all files get applied. Settings in more important files -override those in less important ones. Settings not present in more imortant -files are taken from a less important one or from the internal defaults if they -are not found in any file. +=item F -=over 4 +These are "drop-ins" (mind the ".d" suffix of the directory). +They are more important than the base dunstrc in the parent directory, as they +are considered to be small snippets to override settings. +The last in lexical order is the most important one, so you can easily change +the order by renaming them. +A common approach to naming drop-ins is to prefix them with numbers, i.e.: -=item This is where the default (least important) config file is located: + 00-least-important.conf + 01-foo.conf + 20-bar.conf + 99-most-important.conf -##SYSCONFDIR##/dunst/dunstrc +The only requirements are that the name of the file must have the correct +suffix and the first non-blank line that is not a comment must be a section or +rule identifier. =back +All settings from all files get applied. Settings in more important files +override those in less important ones. +Settings not present in more imortant files get their value from a less +important one or from the internal defaults if respective key is not found in +any file. + =head1 AUTHORS Written by Sascha Kruse