From 27da9d3a83545ad00ee7ce15cdf52b7b8670471c Mon Sep 17 00:00:00 2001
From: espie <espie@openbsd.org>
Date: Sat, 7 Aug 2010 08:33:35 +0000
Subject: [PATCH] explain quite a bit more what PLIST_DB does

---
 share/man/man5/bsd.port.mk.5 | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/share/man/man5/bsd.port.mk.5 b/share/man/man5/bsd.port.mk.5
index 72a0d157f5f..d1d39dcc102 100644
--- a/share/man/man5/bsd.port.mk.5
+++ b/share/man/man5/bsd.port.mk.5
@@ -1,4 +1,4 @@
-.\" $OpenBSD: bsd.port.mk.5,v 1.257 2010/07/18 21:22:36 jmc Exp $
+.\" $OpenBSD: bsd.port.mk.5,v 1.258 2010/08/07 08:33:35 espie Exp $
 .\"
 .\" Copyright (c) 2000-2008 Marc Espie
 .\"
@@ -24,7 +24,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 18 2010 $
+.Dd $Mdocdate: August 7 2010 $
 .Dt BSD.PORT.MK 5
 .Os
 .Sh NAME
@@ -378,6 +378,9 @@ for each package in the
 .Ev MULTI_PACKAGES
 list.
 If the repository already contains up-to-date packages, they are not rebuilt.
+If PLIST_DB is set, the resulting packaging information is compared
+with existing stuff, and saved if new, with loud complaints if it changed
+without a REVISION bump.
 Arch-independent packages are created in ${PACKAGE_REPOSITORY}/no-arch,
 and copied into ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/all as needed.
 If ${PERMIT_PACKAGE_FTP} is set to
@@ -1652,8 +1655,12 @@ Path to the current port's directory, relative to ${PORTSDIR}.
 Read-only.
 .It Ev PLIST_DB
 User settings.
-Directory used to save generated packing-lists, for further processing,
-such as looking for unregistered conflicts.
+Directory used to save generated packing-lists, as persistent information.
+Packing-lists are processed by a script, register-plist, which complains
+when packing-lists change without a REVISION bump.
+This directory is never cleaned during normal operation.
+.Sq make clean=plist
+should only ever be used during debugging by port maintainers.
 Defaults to empty.
 .It Ev PREFERRED_CIPHERS
 List of cryptographic ciphers to use, in order of preference.
-- 
2.20.1