Document promise_to_disable_if_enabled.

diff --git a/theme.rst b/theme.rst
index 2e8b6663b0ccddd05fe1314502ff9c5d2cf040f5..dbfdebe8e684ba302f8fe74498b212bf7775ece1 100644 (file)
--- a/theme.rst
+++ b/theme.rst
@@ -399,6 +399,17 @@ crop is. If so, you can do this::
 
    resample_effect:always_disable_if_disabled(crop_effect)
 
+Also, since Nageru 1.9.1, you can disable an optional effect if a given other
+effect is *enabled*::
+
+   overlay1_effect:promise_to_disable_if_enabled(overlay2_effect)
+   overlay2_effect:promise_to_disable_if_enabled(overlay1_effect)
+
+Note that the latter is a promise from the user, not automatic disabling; since
+it is mostly useful for mutual exclusions, Nageru wouldn't know which of the
+two to disable. (If you violate the promise, you will get an error message at
+runtime.) It can still be useful for reducing the number of alternatives, though.
+
 For more advanced exclusions, you may choose to split up the scenes into several
 distinct ones that you manage yourself; indeed, before Nageru 1.9.0, that was
 the only option. At some point, however, you may choose to simply accept the