[pkgsrc/trunk]: pkgsrc/mk mk/*: improve documentation for "make help"

[rillig <rillig%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/9d376a47fe9e
branches:  trunk
changeset: 380549:9d376a47fe9e
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Wed May 16 21:23:02 2018 +0000

description:
mk/*: improve documentation for "make help"

diffstat:

 mk/alternatives.mk           |  14 +++++++++++---
 mk/build/build.mk            |  17 ++++++++++++++++-
 mk/install/bin-install.mk    |   7 ++++---
 mk/misc/can-be-built-here.mk |   3 ++-
 4 files changed, 33 insertions(+), 8 deletions(-)

diffs (104 lines):

diff -r c1106b58ede5 -r 9d376a47fe9e mk/alternatives.mk
--- a/mk/alternatives.mk        Wed May 16 20:28:16 2018 +0000
+++ b/mk/alternatives.mk        Wed May 16 21:23:02 2018 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: alternatives.mk,v 1.12 2015/11/25 13:05:47 jperkin Exp $
+# $NetBSD: alternatives.mk,v 1.13 2018/05/16 21:23:02 rillig Exp $
 #
 # This Makefile fragment handles the alternatives system, registering a
 # package in the database.
@@ -16,15 +16,23 @@
 #      Default value: The name of the ALTERNATIVES file in the package
 #      directory, if it exists. Otherwise, nothing.
 #
-#      Each line of the alternatives file contains two filenames, first
-#      the wrapper and then the alternative provided by the package.
+#      Each line of the alternatives file contains two filenames:
+#
+#              wrapper   alternative
+#
+#      The wrapper is the command that is run by the user.
+#      The alternative is the implementation of that command that is
+#      provided by the package.
 #      Both paths are relative to PREFIX.
+#      The paths may use placeholders of the form @VARNAME@, which are
+#      replaced with the actual values as per FILES_SUBST.
 #
 # Variables defined by this file:
 #
 # PKG_ALTERNATIVES
 #      The path to the pkg_alternatives command.
 #
+# Keywords: alternatives
 
 .if !defined(ALTERNATIVES_MK)
 ALTERNATIVES_MK=       # defined
diff -r c1106b58ede5 -r 9d376a47fe9e mk/build/build.mk
--- a/mk/build/build.mk Wed May 16 20:28:16 2018 +0000
+++ b/mk/build/build.mk Wed May 16 21:23:02 2018 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: build.mk,v 1.22 2017/06/01 02:15:10 jlam Exp $
+# $NetBSD: build.mk,v 1.23 2018/05/16 21:23:02 rillig Exp $
 #
 # This file defines what happens in the build phase, excluding the
 # self-test, which is defined in test.mk.
@@ -180,6 +180,21 @@
        @${DO_NADA}
 .endif
 
+# build-env:
+#      Starts an interactive shell in WRKSRC.
+#
+#      This is only used during development and testing of a package
+#      to work in the same environment as the actual build.
+#
+# User-settable variables:
+#
+# BUILD_ENV_SHELL
+#      The shell to start.
+#
+#      Default: ${SH}
+#
+# Keywords: debug build
+
 BUILD_ENV_SHELL?=      ${SH}
 .if defined(_PKGSRC_BARRIER)
 build-env: .PHONY configure
diff -r c1106b58ede5 -r 9d376a47fe9e mk/install/bin-install.mk
--- a/mk/install/bin-install.mk Wed May 16 20:28:16 2018 +0000
+++ b/mk/install/bin-install.mk Wed May 16 21:23:02 2018 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: bin-install.mk,v 1.26 2017/08/19 00:30:19 jlam Exp $
+# $NetBSD: bin-install.mk,v 1.27 2018/05/16 21:23:02 rillig Exp $
 #
 
 # This file provides the following targets:
@@ -27,8 +27,9 @@
 # XXX: This file contains implementation details from the "pkg" format,
 # for example the All/ directory and the @cwd.
 
-# List of sites carrying binary pkgs. Variables "rel" and "arch" are
-# replaced with OS release ("1.5", ...) and architecture ("mipsel", ...)
+# List of sites carrying binary packages. Shell Variables "rel" and
+# "arch" are replaced with OS release ("1.5", ...) and architecture
+# ("mipsel", ...).
 .if ${OPSYS} == "NetBSD"
 BINPKG_SITES?= \
        http://cdn.NetBSD.org/pub/pkgsrc/packages/NetBSD/$${arch}/$${rel} \
diff -r c1106b58ede5 -r 9d376a47fe9e mk/misc/can-be-built-here.mk
--- a/mk/misc/can-be-built-here.mk      Wed May 16 20:28:16 2018 +0000
+++ b/mk/misc/can-be-built-here.mk      Wed May 16 21:23:02 2018 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: can-be-built-here.mk,v 1.8 2015/01/01 06:06:06 dholland Exp $
+# $NetBSD: can-be-built-here.mk,v 1.9 2018/05/16 21:23:02 rillig Exp $
 #
 # This file checks whether a package can be built in the current pkgsrc
 # environment. It checks the following variables:
@@ -20,6 +20,7 @@
 #      XXX: It's weird to have three negations in such a short variable
 #      name.
 #
+# Keywords: compiler broken only platform
 
 _CBBH_CHECKS=          # none, but see below.