Documented PKGNAME and PKGREVISION.

2 files changed, 51 insertions, 11 deletions

diff --git a/mk/help/distname.help b/mk/help/distname.help
new file mode 100644
index 00000000000..ca937e71a3a
--- /dev/null
+++ b/mk/help/distname.help
@@ -0,0 +1,51 @@
+# $NetBSD: distname.help,v 1.1 2007/02/06 20:03:30 rillig Exp $
+#
+# DISTNAME
+#	Every package definition should start with the definition of this
+#	variable. It is used in three places:
+#
+#	1. It is the first part of the default value for DISTFILES.
+#	2. It is the default value for PKGNAME, except for the trailing
+#	   "nb" part.
+#	3. The default value of WRKSRC is ${WRKDIR}/${DISTNAME}.
+#
+
+# PKGNAME
+#	This variable is somewhat special in pkgsrc. On the one hand, it
+#	is intended to be defined by the package, but on the other hand,
+#	it is overridden by bsd.pkg.mk with a value that is similar, but
+#	not identical to the one provided by the package. This makes it
+#	somewhat tricky to use this variable correctly, because its
+#	value changes over time.
+#
+#	When the variable is defined by the package, it should consist
+#	of the package name and version, as released upstream. The "nb"
+#	part is specified by another variable, PKGREVISION.
+#
+#	Later, in bsd.pkg.mk, the "nb" part is added to PKGNAME, so when
+#	it is used in the package, its value may differ. The package
+#	name without the "nb" suffix is provided in the PKGNAME_NOREV
+#	variable.
+#
+#	See also: DISTNAME, PKGREVISION, PKGNAME_NOREV.
+#
+
+# PKGREVISION
+#	When a pkgsrc package changes but there has not been an update
+#	of the upstream package, there must be a way to mark a package
+#	as "newer" than a previous one. That's the purpose of
+#	PKGREVISION.
+#
+#	Whenever a package is modified in a user-visible way, this
+#	variable is increased.
+#
+#	The value of PKGREVISION (if defined, non-empty and non-zero)
+#	is the last part of the PKGNAME, separated from the rest by the
+#	letters "nb" (which stand for NetBSD).
+#
+#	Since this variable is specific to a single package, the only
+#	place where it may be defined is the package Makefile itself.
+#	No other file may define it.
+#
+#	Keywords: nb
+#
diff --git a/mk/help/distname.mk b/mk/help/distname.mk
deleted file mode 100644
index b5385dc9309..00000000000
--- a/mk/help/distname.mk
+++ /dev/null
@@ -1,11 +0,0 @@
-# $NetBSD: distname.mk,v 1.1 2006/10/23 13:52:32 rillig Exp $
-#
-# DISTNAME
-#	Every package definition should start with the definition of this
-#	variable. It is used in three places:
-#
-#	1. It is the first part of the default value for DISTFILES.
-#	2. It is the default value for PKGNAME, except for the trailing
-#	   "nb" part.
-#	3. The default value of WRKSRC is ${WRKDIR}/${DISTNAME}.
-#