Update documentation explaining the source package

README.md

@@ -1,41 +1,32 @@
 # kali-themes
 
-This package joins together files that were split across gnome-theme-kali,
-kali-defaults and desktop-base.
-
-The file structure has been revamped to make it easier to see everything
-that needs to be provided.
+This package joins together all files that are related to theming
+and configuration of the visual appearance. They were formerly split
+across gnome-theme-kali, kali-defaults and desktop-base.
 
 ## desktop-base integration
 
-To create a new theme that integrates well into desktop-base, you need to
-provide appropriate files in the following directories:
+desktop-base integration is provided by kali-desktop-base through
+registration of various files in alternatives defined by the desktop-base
+package. The files are not installed in /usr/share/desktop-base/
+except for a symlink tree mimicking a "destkop-base theme". That symlink
+tree is pre-built in the "desktop-base" directory in the source package.
 
-* Wallpapers: background images in different resolutions with GNOME and
-  KDE meta-information.
-* Gnome-Backgrounds: an XML file defining available wallpapers.
-* Grub-Background: grub background image and other associated settings
-  used by the default grub menu.
-* LockScreen: wallpapers used by the screenlocker
-* LoginScreen: wallpaper used on the login screen (GDM at least)
-* Plymouth-Theme: theme used by plymouth (boot splash screen)
+The kali-themes-common package is also installing various symlinks
+trees to mimick directories that are traditionnally handled by
+desktop-base. Most notably the directories in /usr/share/wallpapers/ that
+are used by KDE.
 
-The following directories are also used by desktop-base but they don't
-need any change for a new theme as the Kali logo and emblems are unlikely
-to need any modification:
-* emblems
-* kali-logos
+## configuration files
 
-## Other integrations
+The configuration files stored in the "etc" sub-directory are installed
+as is in the "kali-themes" package. However the files listed in
+"files-to-divert" are first diverted by dpkg-divert and the actual
+files are stored in /usr/share/kali-themes/etc/ and copied in their
+target location by the postinst script (see debian/kali-themes.postinst).
 
-* Color-Schemes: color schemes for various applications and widgets
-* Window-Theme: Desktop/GTK themes
-* Icon-Theme: various icon sets
-* Grub-Theme: theme for Grub
-
-## TODO
-
-* The "Backgrounds" directory needs to be replaced with proper
-  "Wallpapers".
-* We should see whether the "Grub-Theme" directory can be folded
-  into "Grub-Background" in some way.
+When you add a new file that needs to be diverted, you can update
+the list in "files-to-divert" and run "debian/update-maintainer-scripts"
+to update the list of files in the 3 maintainer scripts. But you also
+need to add a snippet in debian/kali-themes.preinst to setup the new
+diversion on upgrade.

debian/kali-themes.preinst

@@ -15,11 +15,20 @@ FILES_TO_DIVERT="
 /etc/xdg/xfce4/xfconf/xfce-perchannel-xml/xsettings.xml
 " # END FILES_TO_DIVERT
 
+setup_diversion_on_upgrade() {
+    local prev_version="$1"
+    local ref_version="$2"
+    local file="$3"
+    if dpkg --compare-versions "$prev_version" lt "$ref_version"; then
+	setup_diversion "$file"
+    fi
+}
+
 setup_diversion() {
-    local file=$1
+    local file="$1"
     dpkg-divert --rename --package kali-themes \
-		--divert $file.original \
-		--add $file
+		--divert "$file.original" \
+		--add "$file"
 }
 
 case "$1" in
@@ -39,6 +48,9 @@ case "$1" in
     ;;
     upgrade)
 	# Dynamically add new diversions when required on upgrade
+	# Example to divert /etc/xdg/xfce4/panel/default.xml when you
+	# upgrade from a version older than 2019.4.6:
+	# setup_diversion_on_upgrade $2 2019.4.6 /etc/xdg/xfce4/panel/default.xml
     ;;
 esac