Add trigger man pages and update dpkg with triggers information

ChangeLog

@@ -1,3 +1,8 @@
+2008-04-08  Guillem Jover  <guillem@debian.org>
+
+	* doc/triggers.txt: Move parts of the document into proper man pages.
+	Add references to those.
+
 2008-04-05  Raphael Hertzog  <hertzog@debian.org>
 
 	* scripts/Dpkg/Source/Package/V1_0.pm: Do not use

debian/changelog

@@ -4,6 +4,8 @@ dpkg (1.14.18) UNRELEASED; urgency=low
   * Bump po4a version in Build-Depends to 0.33.1-1, as usage of UTF-8
     in original man pages was causing build failures. Closes: #473498
   * Add triggers documentation to dpkg-dev. Closes: #473449
+  * Add deb-triggers.5 and dpkg-trigger.1 man pages, and document new
+    statuses and options in dpkg.1.
 
   [ Raphael Hertzog ]
   * When dpkg-source builds a source package of Format: 2.0 or 3.0 (quilt) it

debian/dpkg-dev.install

@@ -31,6 +31,8 @@ usr/share/man/*/*/deb-shlibs.5
 usr/share/man/*/deb-shlibs.5
 usr/share/man/*/*/deb-symbols.5
 usr/share/man/*/deb-symbols.5
+usr/share/man/*/*/deb-triggers.5
+usr/share/man/*/deb-triggers.5
 usr/share/man/*/*/deb-old.5
 usr/share/man/*/deb-old.5
 usr/share/man/*/*/deb.5

debian/dpkg.install

@@ -24,6 +24,8 @@ usr/share/man/*/*/dpkg-split.1
 usr/share/man/*/dpkg-split.1
 usr/share/man/*/*/dpkg-statoverride.8
 usr/share/man/*/dpkg-statoverride.8
+usr/share/man/*/*/dpkg-trigger.1
+usr/share/man/*/dpkg-trigger.1
 usr/share/man/*/*/dpkg.cfg.5
 usr/share/man/*/dpkg.cfg.5
 usr/share/man/*/*/dpkg.1

doc/triggers.txt

@@ -299,36 +299,7 @@ i18n characters, etc.  Such a trigger should not be necessary.
 Package declarations regarding triggers
 ---------------------------------------
 
-A package declares its relationship to some trigger(s) by including a
-`triggers' file in its control archive (ie, DEBIAN/triggers during
-package creation).  This file contains directives, one per line.
-Leading and trailing whitespace and everything after the first # on
-any line will be trimmed, and empty lines will be ignored.
-
-The trigger control directives currently supported are:
-
- interest <trigger-name>
-
-    Specifies that the package is interested in the named trigger.
-    All triggers in which a package is interested must be listed using
-    this directive in the triggers control file.
-
- activate <trigger-name>
-
-    Arranges that changes to this package's state will activate the
-    specified trigger.  The trigger will be activated at the start of
-    the following operations: unpack, configure, remove (including for
-    the benefit of a conflicting package), purge and deconfigure.
-
-    If this package disappears during the unpacking of another package
-    the trigger will be activated when the disappearance is noted
-    towards the end of the unpack.  Trigger processing, and transition
-    from triggers-awaited to installed, does not cause activations.
-    In the case of unpack, triggers mentioned in both the old and new
-    versions of the package will be activated.
-
-Unknown directives are an error which will prevent installation of the
-package.
+See deb-triggers(5).
 
 Support future extension of the trigger name syntax with additional
 dpkg-generated triggers is as follows: a package which is interested
@@ -343,25 +314,7 @@ trigger names syntaxes and unrecognised trigger control directives.
 New command-line interfaces to dpkg tools
 -----------------------------------------
 
-dpkg will grow new options:
-
-  --no-triggers
-      Do not run any triggers in this run (activations will still be
-      recorded).  If used with dpkg --configure <some package> or
-      --triggers-only <some package> then the named package
-      postinst will still be run even if only a triggers run is needed.
-  --triggers
-      Cancels a previous --no-triggers.
-
-  --triggers-only
-      Processes only triggers.  All pending triggers will be
-      processed.  If package names are supplied only those packages'
-      triggers will be processed, exactly once each where necessary.
-
-Use of --no-triggers or --triggers-only may leave packages in the
-improper `triggers-awaited' and `triggers-pending' states.  This can
-be fixed later by running:
-   dpkg --configure --pending
+See dpkg(1).
 
 Here is a summary of the behaviours:
 
@@ -379,36 +332,12 @@ Here is a summary of the behaviours:
  [1] can be specified explicitly by --triggers or --no-triggers
 
 
+See dpkg-trigger(1).
+
 A trigger may be activated explicitly with:
    dpkg-trigger [--by-package <package>] <name-of-trigger>
    dpkg-trigger --no-await <name-of-trigger>
 
-This can be used by maintainer scripts in complex and conditional
-situations where the file triggers, or the declarative `activate'
-triggers control file directive, are insufficiently rich.  It can also
-be used for testing and by system administrators (but note that the
-triggers won't actually be run by dpkg-trigger - see `Timing...',
-above).
-
-The --by-package option should not normally be necessary.  dpkg will
-be modified to set an environment variable DPKG_MAINTSCRIPT_PACKAGE in
-the environment of maintainer scripts, naming the package to which the
-script belongs, and this will be used by default.
-
-The --no-await option arranges that the calling package T (if any)
-need not await the processing of this trigger; the interested
-package(s) I will not be added to T's trigger processing awaited list
-and T's status is unchanged.  T may be considered installed even
-though I may not yet have processed the trigger.
-
-If a postinst would like to know whether the running dpkg supports
-triggers, it can ask
-   dpkg-trigger --check-supported
-which will exit 0 if a triggers-capable dpkg has run, or 1 with an
-error message to stderr if not.  Normally, however, it is better just
-to activate the desired trigger with `dpkg-trigger'.  See Transition
-Plan, below.
-
 The --verbose and --query options will show which packages were
 interested and what the current activation state is, on stdout in
 human- and machine-readable (untranslated) format.  Without any
@@ -416,8 +345,6 @@ options there will be no output to stdout, and none to stderr unless
 dpkg-trigger is unable to make a record of the trigger activation.
 With --query no trigger is activated.
 
-Unrecognised trigger name syntaxes are an error for dpkg-trigger.
-
 NB that in the case of a file trigger the name of the trigger is
 needed, not the name of a file which would match the trigger.
 

man/ChangeLog

@@ -1,3 +1,12 @@
+2008-04-08  Guillem Jover  <guillem@debian.org>
+
+	* dpkg.1: Document new trigger statuses, and new --triggers-only,
+	--no-triggers and --triggers options.
+	* deb-triggers.5: New file.
+	* dpkg-trigger.1: Likewise.
+	* po/po4a.cfg: Add 'deb-triggers.5' and 'dpkg-trigger.1'.
+	* Makefile.am (dist_man_MANS): Likewise.
+
 2008-04-08  Guillem Jover  <guillem@debian.org>
 
 	* po/sv.po: Add missing terminating '>'.

man/Makefile.am

@@ -72,6 +72,7 @@ dist_man_MANS = \
 	deb-shlibs.5 \
 	deb-substvars.5 \
 	deb-symbols.5 \
+	deb-triggers.5 \
 	deb-old.5 \
 	deb-override.5 \
 	deb.5 \
@@ -93,6 +94,7 @@ dist_man_MANS = \
 	dpkg-source.1 \
 	dpkg-split.1 \
 	dpkg-statoverride.8 \
+	dpkg-trigger.1 \
 	dpkg.1 \
 	dpkg.cfg.5 \
 	dselect.1 \

man/deb-triggers.5

@@ -0,0 +1,51 @@
+.TH deb\-triggers 5 "2008-04-06" "Debian Project" "dpkg utilities"
+.SH NAME
+deb\-triggers \- package triggers
+.
+.SH SYNOPSIS
+triggers
+.
+.SH DESCRIPTION
+A package declares its relationship to some trigger(s) by including
+a \fItriggers\fP file in its control archive (ie, \fIDEBIAN/triggers\fP
+during package creation).
+.PP
+This file contains directives, one per line. Leading and trailing whitspace
+and everything after the first \fB#\fP on any line will be trimmer, and
+empty lines will be ignored.
+.PP
+The trigger control directives currently supported are:
+.PP
+.in +5
+.B interest
+.I trigger-name
+.PP
+.in +5
+Specifies that the package is interested in the named trigger.
+All triggers in which a package is interested must be listed using
+this directive in the triggers control file.
+.PP
+.in +5
+.B activate
+.I trigger-name
+.PP
+.in +5
+Arranges that changes to this package's state will activate the
+specified trigger. The trigger will be activated at the start of
+the following operations: unpack, configure, remove (including for
+the benefit of a conflicting package), purge and deconfigure.
+.PP
+.in +5
+If this package disappears during the unpacking of another package
+the trigger will be activated when the disappearance is noted
+towards the end of the unpack. Trigger processing, and transition
+from triggers-awaited to installed, does not cause activations.
+In the case of unpack, triggers mentioned in both the old and new
+versions of the package will be activated.
+.PP
+Unknown directives are an error which will prevent installation of the
+package.
+.
+.SH SEE ALSO
+.BR dpkg\-trigger (1),
+.BR dpkg (1).

man/dpkg-trigger.1

@@ -0,0 +1,65 @@
+.TH dpkg\-trigger 1 "2008-04-06" "Debian Project" "dpkg suite"
+.SH NAME
+dpkg\-trigger \- a package trigger utility
+.
+.SH SYNOPSIS
+.B dpkg\-trigger
+.RI [ option "...] " trigger-name
+.br
+.B dpkg\-trigger
+.RI [ option "...] " command
+.
+.SH DESCRIPTION
+\fBdpkg\-trigger\fP is a tool to explicitely activate triggers and check
+for its support on the running \fBdpkg\fP.
+.PP
+This can be used by maintainer scripts in complex and conditional
+situations where the file triggers, or the declarative \fBactivate\fP
+triggers control file directive, are insufficiently rich. It can also
+be used for testing and by system administrators (but note that the
+triggers won't actually be run by dpkg-trigger).
+.PP
+Unrecognised trigger name syntaxes are an error for dpkg-trigger.:
+.
+.SH COMMANDS
+.TP
+.BR \-\-check\-supported
+Check if the running dpkg supports triggers (usually called from a postinst).
+Will exit 0 if a triggers-capable dpkg has run, or 1 with an error message
+to stderr if not. Normally, however, it is better just to activate the
+desired trigger with \fBdpkg\-trigger\fP.
+.TP
+.BR \-h ", " \-\-help
+Show the usage message and exit.
+.TP
+.B \-\-version
+Show the version and exit.
+.TP
+.BR \-\-license ", " \-\-licence
+Show the copyright licensing terms and exit.
+.
+.SH OPTIONS
+.TP
+.BI \-\-admindir= dir
+Change the location of the \fBdpkg\fR database. The default location is
+\fI/var/lib/dpkg\fP.
+.TP
+.BR \-\-by\-package=\fIpackage\fR
+Override trigger awaiter (normally set by dpkg through the
+DPKG_MAINTSCRIPT_PACKAGE environment variable of the maintainer scripts,
+naming the package to which the script belongs, and this will be used
+by default).
+.TP
+.BR \-\-no\-await
+This option arranges that the calling package T (if any) need not await
+the processing of this trigger; the interested package(s) I, will not be
+added to T's trigger processing awaited list and T's status is unchanged.
+T may be considered installed even though I may not yet have processed
+the trigger.
+.TP
+.BR \-\-no\-act
+Just test, do not actually change anything.
+.
+.SH SEE ALSO
+.BR dpkg "(1), " deb-triggers (5).
+

man/dpkg.1

@@ -1,4 +1,4 @@
-.TH dpkg 1 "2007-07-18" "Debian Project" "dpkg suite"
+.TH dpkg 1 "2008-04-06" "Debian Project" "dpkg suite"
 .SH NAME
 dpkg \- package manager for Debian
 .
@@ -64,6 +64,12 @@ The package is unpacked, but not configured.
 The package is unpacked and configuration has been started, but not yet
 completed for some reason.
 .TP
+.B triggers\-awaited
+The package awaits trigger processing by another package.
+.TP
+.B triggers\-pending
+The package has been triggered.
+.TP
 .B installed
 The package is unpacked and configured OK.
 .SS PACKAGE SELECTION STATES
@@ -142,6 +148,13 @@ something goes wrong.
 
 \fB2.\fP Run \fIpostinst\fP script, if provided by the package.
 .TP
+\fB\-\-triggers\-only\fP \fIpackage\fP...|\fB\-a\fP|\fB\-\-pending\fP
+Processes only triggers. All pending triggers will be processed. If package
+names are supplied only those packages' triggers will be processed, exactly
+once each where necessary. Use of this option may leave packages in the
+improper \fBtriggers\-awaited\fP and \fBtriggers\-pending\fP states. This
+can be fixed later by running: \fBdpkg \-\-configure \-\-pending\fP.
+.TP
 \fB\-r\fP, \fB\-\-remove\fP, \fB\-P\fP, \fB\-\-purge \fP\fIpackage\fP...|\fB\-a\fP|\fB\-\-pending\fP
 Remove an installed package. \fB\-r\fP or \fB\-\-remove\fP remove
 everything except configuration files. This may avoid having to
@@ -519,6 +532,18 @@ or keep.
 .TP
 \fB\-\-no\-debsig\fP
 Do not try to verify package signatures.
+.TP
+\fB\-\-no\-triggers\fP
+Do not run any triggers in this run (activations will still be recorded).
+If used with \fB\-\-configure\fP \fIpackage\fP or
+\fB\-\-triggers\-only\fP \fIpackage\fP then the named package postinst
+will still be run even if only a triggers run is needed. Use of this option
+may leave packages in the improper \fBtriggers\-awaited\fP and
+\fBtriggers\-pending\fP states. This can be fixed later by running:
+\fBdpkg \-\-configure \-\-pending\fP.
+.TP
+\fB\-\-triggers\fP
+Cancels a previous \fB\-\-no\-triggers\fP.
 .
 .SH FILES
 .TP

man/po/po4a.cfg

@@ -63,6 +63,11 @@
            add_$lang:$(srcdir)/po/$lang.add
 
 
+[type:man] $(srcdir)/deb-triggers.5             \
+           $lang:$lang/deb-triggers.5           \
+           add_$lang:$(srcdir)/po/$lang.add
+
+
 [type:man] $(srcdir)/dpkg.1                     \
            $lang:$lang/dpkg.1                   \
            add_$lang:$(srcdir)/po/$lang.add
@@ -158,6 +163,11 @@
            add_$lang:$(srcdir)/po/$lang.add
 
 
+[type:man] $(srcdir)/dpkg-trigger.1             \
+           $lang:$lang/dpkg-trigger.1           \
+           add_$lang:$(srcdir)/po/$lang.add
+
+
 [type:man] $(srcdir)/dselect.1                  \
            $lang:$lang/dselect.1    \
            add_$lang:$(srcdir)/po/$lang.add