From e7c1f429ab818b73b20c99605769ca97c5fff2f5 Mon Sep 17 00:00:00 2001
From: Charles Plessy <plessy@debian.org>
Date: Sun, 4 Aug 2013 07:41:39 +0900
Subject: [PATCH 2/6] Document "postinst triggered".

---
 policy.sgml              | 40 ++++++++++++++++++++++++++++++++++++++--
 upgrading-checklist.sgml |  5 +++++
 2 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/policy.sgml b/policy.sgml
index e3598f1..f82aa12 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -4153,7 +4153,9 @@ Checksums-Sha256:
 	      are no circular dependencies involved, all package
 	      dependencies will be configured.  For behavior in the case
 	      of circular dependencies, see the discussion
-	      in <ref id="binarydeps">.
+	      in <ref id="binarydeps">.  Even when called with
+	      <tt>configure</tt>, this script must do whatever actions are
+	      necessary to deal with any triggers activation.
 	    </item>
 
 	    <tag><var>old-postinst</var> <tt>abort-upgrade</tt>
@@ -4188,6 +4190,39 @@ Checksums-Sha256:
 	      from the package dependencies are not available is often the
 	      best approach.
 	    </item>
+
+	    <tag><var>postinst</var> <tt>triggered</tt>
+	      "<var>trigger-name</var> <var>trigger-name</var> ..."</tag>
+	    <item>
+	      <prgn>postinst configure</prgn> was already run and the
+	      dependencies ought to be configured. However, <prgn>dpkg</prgn>
+	      currently suffers of a bug which means that <prgn>postinst
+              triggered</prgn> can be called while some dependencies are being
+	      upgraded (see bug <url id="http://bugs.debian.org/671711"
+	      name="671711">). Until this bug is absent from the stable
+	      release, you should thus only rely on the fact that the
+	      dependencies are at least unpacked and were already configured once
+	      (similar to what <tt>Pre-Depends</tt> ensures for
+	      <prgn>preinst</prgn> maintainer scripts).
+
+	      <prgn>postinst triggered</prgn> processes one or more
+	      <qref id="dpkg-triggers">triggers</qref> that
+	      this package is <em>interested</em> in.  In case of failure the
+	      package's state becomes "Half-Configured" and the task associated
+	      to the trigger processing will be completed by the
+	      <tt>postinst configure</tt> during the next package's
+	      configuration<footnote>
+		When an interested package has more than one trigger and wants
+		to process them differently, the list of triggers can be
+		examined in a shell script like this:
+		<example>
+case " $2 " in
+*" trigger-name-a "*)  process-trigger-a ;;
+esac</example>
+		Generally each trigger name should be tested for separately, as
+		the postinst will often be called for several triggers at once.
+	      </footnote>.
+	    </item>
 	  </taglist>
 	</p>
 
@@ -5025,7 +5060,8 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
 		<prgn>postinst</prgn> or <prgn>prerm</prgn> scripts
 		require the depended-on package to be unpacked or
 		configured in order to run.  In the case of <tt>postinst
-		configure</tt>, the depended-on packages will be unpacked
+		configure</tt> and <tt>postinst triggered</tt>,
+	        the depended-on packages will be unpacked
 		and configured first.  (If both packages are involved in a
 		dependency loop, this might not work as expected; see the
 		explanation a few paragraphs back.)  In the case
diff --git a/upgrading-checklist.sgml b/upgrading-checklist.sgml
index 41a1e84..3d41475 100644
--- a/upgrading-checklist.sgml
+++ b/upgrading-checklist.sgml
@@ -59,6 +59,11 @@ Unreleased.
   <item>The Dpkg states are now documented.  The Policy has been proofread
   and occurences of "Failed-Config" have been corrected to "Half-Configured".
   </item>
+<tag>6.5</tag>
+  <item>The <tt>triggered</tt> call for the <var>postinst</var> script is now
+  documented.  <var>postinst</var> <tt>configure</tt> must do whatever actions
+  are necessary to deal with any triggers activation.
+  </item>
 <tag>11.5.2</tag>
   <item>Stop recommending to serve HTML documents from
   <file>/usr/share/doc/<var>package</var></file>.
-- 
1.8.4.rc0

