From fcba071ef09dcc41f14611804534e74f31bb9f23 Mon Sep 17 00:00:00 2001
From: espie <espie@openbsd.org>
Date: Sat, 4 Jun 2022 10:12:38 +0000
Subject: [PATCH] document internal annotations a bit more, explain about the
 always-update changes, and be more specific about @digital-signature and
 @signer, since we only use the one scheme now.

---
 usr.sbin/pkg_add/package.5    | 28 +++++++++++++++++-----------
 usr.sbin/pkg_add/pkg_create.1 | 10 ++++++----
 2 files changed, 23 insertions(+), 15 deletions(-)

diff --git a/usr.sbin/pkg_add/package.5 b/usr.sbin/pkg_add/package.5
index 3f3981431c2..37a942f3d3e 100644
--- a/usr.sbin/pkg_add/package.5
+++ b/usr.sbin/pkg_add/package.5
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: package.5,v 1.30 2022/01/13 11:23:47 espie Exp $
+.\"	$OpenBSD: package.5,v 1.31 2022/06/04 10:12:38 espie Exp $
 .\" Copyright (c) 2005-2006 Marc Espie <espie@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
@@ -12,7 +12,7 @@
 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-.Dd $Mdocdate: January 13 2022 $
+.Dd $Mdocdate: June 4 2022 $
 .Dt PACKAGE 5
 .Os
 .Sh NAME
@@ -151,12 +151,12 @@ of
 .It Xo
 .Cm @digital-signature
 .Sm off
-.Ar style :
+.Ar signify2 :
 .Ar date :
-.Ar details
+.Ar external
 .Sm on
 .Xc
-Record a digital signature of the packing-list, synthetized by
+Record the date of signature of a package, synthetized by
 .Xr pkg_add 1
 from
 .Xr signify 1
@@ -181,8 +181,12 @@ for later deinstallation.
 will derive this field from the package file name.
 .Pp
 .It Cm @option Ar name
-Some options are automatically inserted by the package tools:
+Some options are automatically inserted/modified by the package tools:
 .Bl -tag -width indent
+.It Ar always-update
+.Xr pkg_create 1
+will complete the option line with a sha256 digest of the whole packing-list
+encoded in base64.
 .It Ar firmware
 Set by
 .Xr fw_update 8
@@ -204,9 +208,11 @@ to record the files's cryptographic checksum,
 as a sha256 digest encoded in base64.
 .Pp
 .It Cm @signer
-Internal annotation necessary to identify packages signed with
+Record the signing key for a package, synthetized by
+.Xr pkg_add 1
+from
 .Xr signify 1
-keys, as those keys don't carry any identity.
+output.
 .Pp
 .It Cm @size
 Added after a file entry by
@@ -219,9 +225,9 @@ Added after a file entry by
 to record that the entry is actually a symbolic link.
 .Pp
 .It Cm @url
-Original location of the package, automatically recorded in installed packages
-by
-.Xr pkg_add 1 .
+Original location of the package, synthetized by
+.Xr pkg_add 1
+during installation.
 .Pp
 .It Cm @ts Ar timestamp
 Added after a file entry to record the actual file timestamp, instead
diff --git a/usr.sbin/pkg_add/pkg_create.1 b/usr.sbin/pkg_add/pkg_create.1
index cbf28302c47..31e982c1738 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.124 2022/01/13 12:21:22 espie Exp $
+.\"	$OpenBSD: pkg_create.1,v 1.125 2022/06/04 10:12:38 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: January 13 2022 $
+.Dd $Mdocdate: June 4 2022 $
 .Dt PKG_CREATE 1
 .Os
 .Sh NAME
@@ -713,8 +713,10 @@ By default,
 .Xr pkg_add 1
 uses some simplified information to decide whether an installed package
 needs updating.
-With this option, the package is updated whenever anything changes.
-To be used sparingly, as this is more expensive.
+With this option, the package will be updated whenever anything changes.
+.Pp
+This is meant to be used by packages containing information relating to the
+whole ports tree, like sqlports, quirks, pkglocatedb.
 .It Cm is-branch
 Annotate the few rare ports where several branches are present in the
 ports tree (such as autoconf), to help
-- 
2.20.1