From 29cbcdd626050b748a667cb01efc450fb248b32b Mon Sep 17 00:00:00 2001
From: Charles Plessy <plessy@debian.org>
Date: Sun, 4 Aug 2013 07:51:25 +0900
Subject: [PATCH 3/6] Document concepts, syntax and control information file
 for dpkg triggers.

---
 policy.sgml              | 83 +++++++++++++++++++++++++++++++++++++++++++++---
 upgrading-checklist.sgml |  3 ++
 2 files changed, 82 insertions(+), 4 deletions(-)

diff --git a/policy.sgml b/policy.sgml
index f82aa12..48c6a5f 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -900,9 +900,11 @@ zope.
 	the package.  Other control information files include
 	the <qref id="sharedlibs-symbols"><file>symbols</file> file</qref>
 	or <qref id="sharedlibs-shlibdeps"><file>shlibs</file> file</qref>
-	used to store shared library dependency information and
+	used to store shared library dependency information,
 	the <file>conffiles</file> file that lists the package's
-	configuration files (described in <ref id="config-files">).
+	configuration files (described in <ref id="config-files">), and the
+	<file>triggers</file> file, which defines the package's interaction with
+	<prgn>dpkg</prgn>'s <qref id="dpkg-triggers">trigger</qref> system.
       </p>
 
       <p>
@@ -4776,6 +4778,79 @@ fi
 
 	</p>
       </sect>
+
+      <sect id="dpkg-triggers">
+	<heading>Dpkg triggers</heading>
+
+	<sect1 id="dpkg-triggers-concepts">
+	<heading>Concepts</heading>
+
+	  <p>
+	    Dpkg triggers allow packages to monitor events caused by
+	    the installation, upgrade or removal of other packages. Monitoring
+	    packages are said to be <em>interested</em> in some triggers. On the
+	    other side, triggers must be <em>activated</em> to notify the
+	    interested package, which is then said to have <em>pending</em>
+	    triggers.  The activating package (if any) is said to <em>await</em>
+	    the processing of the trigger.
+	  <p>
+
+	  <p>
+	    The purpose of this feature is to to avoid duplication of processing
+	    logic among packages by implementing it in one package and making
+	    sure that all other packages rely on triggers to execute the wanted
+	    code.
+	  </p>
+
+	  <p>
+	    Each trigger is named, and at any time zero or more packages may be
+	    <em>interested</em> in it.  For a package to declare its interest in
+	    a trigger, it must include one of the <tt>interest</tt> directives
+	    in the <file>triggers</file> file in its control archive.
+	  </p>
+	</sect1>
+
+	<sect1 id="dpkg-triggers-syntax">
+	<heading>Syntax</heading>
+
+	  <p>
+	    The <file>triggers</file> control file contains one directive per
+	    line.  Leading and trailing whitespace, everything after the first
+	    hash character (<tt>#</tt>) on any line, and empty lines are ignored.
+	    The following directives are supported.
+	    <taglist>
+	      <tag><tt>interest-noawait</tt> <var>trigger-name</var></tag>
+	      <tag><tt>interest</tt> <var>trigger-name</var></tag>
+	      <item>
+		Specifies that the package is interested in the named trigger.
+		The <tt>interest</tt> variant puts the triggering packages in
+		the "Triggers-Awaited" state, and the <tt>interest-noawait</tt>
+		variant does not.
+	      </item>
+
+	      <tag><tt>activate-noawait</tt> <var>trigger-name</var></tag>
+	      <tag><tt>activate</tt> <var>trigger-name</var></tag>
+	      <item>
+		Specifies that changes to this package's state will activate the
+		named trigger.  The <tt>activate</tt> variant puts this package
+		in the "Triggers-Awaited" state, and the
+		<tt>activate-noawait</tt> variant does not.
+	      </item>
+	    </taglist>
+	  </p>
+
+	  <p>
+	    The <tt>*-noawait</tt> directives should be used unless the
+	    packages awaiting triggers can not satisfy <tt>Depends</tt>
+	    relationships until the triggers have been processed.
+	    In that case, the <tt>interest</tt> or <tt>activate</tt> directives
+	    should be used, as they will put the triggering packages in the
+	    "Triggers-Awaited" state, which does not satisfy dependencies.
+	    Note that packages unnecessarily entering this state can cause the
+	    early processing of triggers or even dependency loops.
+	  </p>
+	</sect1>
+      </sect>
     </chapt>
 
 
@@ -8180,8 +8255,8 @@ Reloading <var>description</var> configuration...done.
 	<p>
 	  The <package>mime-support</package> package provides the
 	  <prgn>update-mime</prgn> program, which integrates these
-	  registrations in the <file>/etc/mailcap</file> file, using dpkg
-	  triggers<footnote>
+	  registrations in the <file>/etc/mailcap</file> file, using
+	  <qref id="dpkg-triggers">dpkg triggers</qref><footnote>
 	    Creating, modifying or removing a file in
 	    <file>/usr/lib/mime/packages/</file> using maintainer scripts will
 	    not activate the trigger.  In that case, it can be done by calling
diff --git a/upgrading-checklist.sgml b/upgrading-checklist.sgml
index 3d41475..ac44278 100644
--- a/upgrading-checklist.sgml
+++ b/upgrading-checklist.sgml
@@ -64,6 +64,9 @@ Unreleased.
   documented.  <var>postinst</var> <tt>configure</tt> must do whatever actions
   are necessary to deal with any triggers activation.
   </item>
+<tag>6.9</tag>
+  <item>New section describing Dpkg triggers.
+  </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

