From 193a7b55b45b3294a1a5a7d36a1052aff6b881ce Mon Sep 17 00:00:00 2001 From: Guillem Jover Date: Tue, 8 Apr 2008 06:28:01 +0300 Subject: [PATCH] Add trigger man pages and update dpkg with triggers information --- ChangeLog | 5 +++ debian/changelog | 2 + debian/dpkg-dev.install | 2 + debian/dpkg.install | 2 + doc/triggers.txt | 81 ++--------------------------------------- man/ChangeLog | 9 +++++ man/Makefile.am | 2 + man/deb-triggers.5 | 51 ++++++++++++++++++++++++++ man/dpkg-trigger.1 | 65 +++++++++++++++++++++++++++++++++ man/dpkg.1 | 27 +++++++++++++- man/po/po4a.cfg | 10 +++++ 11 files changed, 178 insertions(+), 78 deletions(-) create mode 100644 man/deb-triggers.5 create mode 100644 man/dpkg-trigger.1 diff --git a/ChangeLog b/ChangeLog index 9facac94..ade8a057 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2008-04-08 Guillem Jover + + * doc/triggers.txt: Move parts of the document into proper man pages. + Add references to those. + 2008-04-05 Raphael Hertzog * scripts/Dpkg/Source/Package/V1_0.pm: Do not use diff --git a/debian/changelog b/debian/changelog index 49ad3246..f1e542ff 100644 --- a/debian/changelog +++ b/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 diff --git a/debian/dpkg-dev.install b/debian/dpkg-dev.install index 28342289..d18feec2 100644 --- a/debian/dpkg-dev.install +++ b/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 diff --git a/debian/dpkg.install b/debian/dpkg.install index c209845a..0816069f 100644 --- a/debian/dpkg.install +++ b/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 diff --git a/doc/triggers.txt b/doc/triggers.txt index 0fc8a21a..f71c038d 100644 --- a/doc/triggers.txt +++ b/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 - - 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 - - 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 or - --triggers-only 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 ] dpkg-trigger --no-await -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. diff --git a/man/ChangeLog b/man/ChangeLog index f227bbde..e45f2025 100644 --- a/man/ChangeLog +++ b/man/ChangeLog @@ -1,3 +1,12 @@ +2008-04-08 Guillem Jover + + * 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 * po/sv.po: Add missing terminating '>'. diff --git a/man/Makefile.am b/man/Makefile.am index 42b17afc..1b5758c6 100644 --- a/man/Makefile.am +++ b/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 \ diff --git a/man/deb-triggers.5 b/man/deb-triggers.5 new file mode 100644 index 00000000..fab662ff --- /dev/null +++ b/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). diff --git a/man/dpkg-trigger.1 b/man/dpkg-trigger.1 new file mode 100644 index 00000000..a03643f9 --- /dev/null +++ b/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). + diff --git a/man/dpkg.1 b/man/dpkg.1 index 04941fda..db426853 100644 --- a/man/dpkg.1 +++ b/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 diff --git a/man/po/po4a.cfg b/man/po/po4a.cfg index 1bc352b2..ee90a712 100644 --- a/man/po/po4a.cfg +++ b/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 -- 2.39.5