+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
* 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
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
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
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
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:
[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
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.
+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 '>'.
deb-shlibs.5 \
deb-substvars.5 \
deb-symbols.5 \
+ deb-triggers.5 \
deb-old.5 \
deb-override.5 \
deb.5 \
dpkg-source.1 \
dpkg-split.1 \
dpkg-statoverride.8 \
+ dpkg-trigger.1 \
dpkg.1 \
dpkg.cfg.5 \
dselect.1 \
--- /dev/null
+.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).
--- /dev/null
+.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).
+
-.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
.
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
\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
.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
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
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
projects / dpkg / commitdiff