document @exec/@unexec variations in more detail.

Point users at pkg_create for packing-list details (suggested by
ajacoutot@)

2 files changed, 63 insertions, 4 deletions

diff --git a/usr.sbin/pkg_add/pkg_add.1 b/usr.sbin/pkg_add/pkg_add.1
index faf85d79c1b..91b1102a92c 100644
--- a/usr.sbin/pkg_add/pkg_add.1
+++ b/usr.sbin/pkg_add/pkg_add.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: pkg_add.1,v 1.65 2007/05/31 19:20:26 jmc Exp $
+.\"	$OpenBSD: pkg_add.1,v 1.66 2007/06/17 10:35:55 espie Exp $
 .\"
 .\" Documentation and design originally from FreeBSD. All the code has
 .\" been rewritten since. We keep the documentation's notice:
@@ -15,7 +15,7 @@
 .\" Jordan K. Hubbard
 .\"
 .\"
-.Dd $Mdocdate: May 31 2007 $
+.Dd $Mdocdate: June 17 2007 $
 .Dt PKG_ADD 1
 .Os
 .Sh NAME
@@ -68,6 +68,9 @@ option
 .Fl u
 .Pc .
 .Pp
+Details of packing-list internals are documented in
+.Xr pkg_create 1 .
+.Pp
 In normal mode,
 the package names given on the command lines are names of new packages that
 .Nm
@@ -481,9 +484,15 @@ in cases the installation fails.
 .It
 The old package is deleted as usual, except that some packages may still depend
 on it.
+Note also that
+.Cm @unexec-delete
+commands are not executed.
 .It
 The new package is installed as usual, except that the files are already present
 and only need to be renamed.
+Note also that
+.Cm @exec-add
+commands are not executed.
 .It
 Dependencies from the old package are adjusted to point to the new package.
 .El
diff --git a/usr.sbin/pkg_add/pkg_create.1 b/usr.sbin/pkg_add/pkg_create.1
index 6e5c3ae03a0..73481ef2a45 100644
--- a/usr.sbin/pkg_add/pkg_create.1
+++ b/usr.sbin/pkg_add/pkg_create.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: pkg_create.1,v 1.42 2007/06/14 10:16:37 espie Exp $
+.\"	$OpenBSD: pkg_create.1,v 1.43 2007/06/17 10:35:55 espie Exp $
 .\"
 .\" Documentation and design originally from FreeBSD. All the code has
 .\" been rewritten since. We keep the documentation's notice:
@@ -21,7 +21,7 @@
 .\" [jkh] Took John's changes back and made some additional extensions for
 .\" better integration with FreeBSD's new ports collection.
 .\"
-.Dd $Mdocdate: June 14 2007 $
+.Dd $Mdocdate: June 17 2007 $
 .Dt PKG_CREATE 1
 .Os
 .Sh NAME
@@ -339,6 +339,15 @@ Execute
 .Ar command
 during
 .Xr pkg_add 1 .
+Note that
+.Cm @exec
+commands are executed relative to their location in the packing-list,
+so they can rely on any data that have already been extracted,
+but not on anything that is listed after them.
+Some special elements, such as new users and new groups, are always
+created first, so that
+.Cm @exec
+can rely on them.
 If
 .Ar command
 contains any of the following sequences somewhere in it, they will
@@ -376,6 +385,22 @@ in the example case,
 .Pa emacs .
 .El
 .Pp
+.It Cm @exec-always Ar command
+Synonym of
+.Cm @exec .
+.Pp
+.It Cm @exec-add Ar command
+Similar to
+.Cm @exec ,
+except it only gets executed during new installations,
+and not during updates.
+.Pp
+.It Cm @exec-update Ar command
+Similar to
+.Cm @exec ,
+except it only gets executed during updates,
+and not during new installations.
+.Pp
 .It Cm @extra Ar filename
 Declare extra file
 .Pa filename
@@ -652,6 +677,31 @@ Expansion of special
 .Cm \&%
 sequences is the same as for
 .Cm @exec .
+Note that
+.Cm @unexec
+commands are executed relative to their location in the packing-list,
+so they cannot rely on any data that has already been deleted,
+thus they should occur before the files they need to function.
+Some special elements, such as new users and new groups, are always
+deleted last, so that
+.Cm @unexec
+can rely on them.
+.Pp
+.It Cm @unexec-always Ar command
+Synonym of
+.Cm @unexec .
+.Pp
+.It Cm @unexec-delete Ar command
+Similar to
+.Cm @unexec ,
+except it only gets executed during true deletions
+and not while removing an old package during updates.
+.Pp
+.It Cm @unexec-update Ar command
+Similar to
+.Cm @unexec ,
+except it only gets executed while removing an old package during updates,
+and not during true deletions.
 .Pp
 .It Cm @wantlib Ar libspec
 Package needs a shared library to work.