io/StateDirectories: implement (artificial) symlinks

doc/index.rst

@@ -40,3 +40,28 @@ these subdirectories is specific to that particular application.
 Each setting is one file.  The following data types are available:
 
 - *boolean*: ``1`` means true, ``0`` means false.
+
+Symlinks
+--------
+
+Symlinks have a special meaning, and they are resolved in userspace,
+not by the kernel, to implement this special meaning: they may point
+to files in any of the base directories.  Example::
+
+  /lib/cm4all/state/workshop/cron/foo/enabled -> ../../../pillar/foo/enabled
+  /lib/cm4all/state/workshop/cron/foo/enabled -> /pillar/foo/enabled
+
+Both symlinks targets are equal; an absolute target points to the root
+of each base directory, not to the root filesystem.  They may point to
+one of the following:
+
+- :file:`/run/cm4all/state/pillar/foo/enabled`
+- :file:`/etc/cm4all/state/pillar/foo/enabled`
+- :file:`/var/lib/cm4all/state/pillar/foo/enabled`
+- :file:`/lib/cm4all/state/pillar/foo/enabled`
+
+This way, only a single file may need to be modified to change the
+state of several daemons.  As usual, there may be overrides in the
+other base directories.
+
+Symlinks to directories are possible just as well.