-This script sets the background image randomly based on images $imgDir. Note
-if this script is run again it senses that it was previously run and sends the
-previous script a SIGUSR2 which the script intrprets as "Change the background
-now", then exits.
+This script sets the background image randomly based on images found in bgdirs.
+Note if this script is run again it senses that it was previously run and sends
+the previous script a SIGUSR2 which the script intrprets as "Change the
+background now", then exits.
+
+Data is written to the following files:
+
+ ~/.setbg: Contains the filename of the current background image
+ ~/.setbg.hist Contains a history of all images displayed for this run
+ ~/.setbg.stats Contains statistical information for the current run
+
+Also note that this script will process a SIGUSR1 to mean "re-evaluate the
+contents of the bgdirs incase it has changed and display a new image". This is
+useful for script to be able to alert setbg that something has changed. For
+example, a script named rmbg might look at ~/.setbg to get the name of the
+current background image file and remove it then signal setbg with SIGUSR1 to
+have it re-evaluate the state of bgdirs.
+
+Finally setbg will perform the this re-evaluation at midnight everyday. This is
+useful because we point setbg to look at -bgdirs from Dropbox where Camera
+Uploads is included and new pictures can arrive everyday.