[pkgsrc/trunk]: pkgsrc/mk/extract mk/extract/bsd.extract-vars.mk: make docume...

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

details:   https://anonhg.NetBSD.org/pkgsrc/rev/9c7a85a32889
branches:  trunk
changeset: 413540:9c7a85a32889
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Fri Mar 20 17:16:34 2020 +0000

description:
mk/extract/bsd.extract-vars.mk: make documentation more user-friendly

The variables are now sorted chronologically instead of alphabetically,
to express the order in which the actions happen. The sentences are a bit
shorter than before.

The visual layout has been changed to make the whole variable name stick
out more. Before, the part that was easily visible was the same "EXTRACT_"
for all of them.

diffstat:

 mk/extract/bsd.extract-vars.mk |  35 +++++++++++++++++++++--------------
 1 files changed, 21 insertions(+), 14 deletions(-)

diffs (48 lines):

diff -r accf38df66a9 -r 9c7a85a32889 mk/extract/bsd.extract-vars.mk
--- a/mk/extract/bsd.extract-vars.mk    Fri Mar 20 17:14:25 2020 +0000
+++ b/mk/extract/bsd.extract-vars.mk    Fri Mar 20 17:16:34 2020 +0000
@@ -1,23 +1,30 @@
-# $NetBSD: bsd.extract-vars.mk,v 1.19 2020/03/14 00:14:35 gdt Exp $
+# $NetBSD: bsd.extract-vars.mk,v 1.20 2020/03/20 17:16:34 rillig Exp $
+#
+# This file configures how a package extracts its distfiles after
+# downloading them.
 #
 # This Makefile fragment is included separately by bsd.pkg.mk and
 # defines some variables which must be defined earlier than where
-# bsd.extract.mk is included.
+# bsd.extract.mk is included, which defines the other variables.
+#
+# Package-settable variables:
 #
-# The following variables may be set by the package Makefile and
-# specify how extraction happens:
-#
-#    EXTRACT_ONLY is a list of distfiles relative to ${_DISTDIR} to
-#      extract and defaults to ${DISTFILES}.
+# EXTRACT_SUFX
+#      The suffix for the default distfile to be extracted.
+#      Defaults to ".tar.gz".
 #
-#    EXTRACT_SUFX is the suffix for the default distfile to be
-#       extracted.  The default suffix is ".tar.gz".
+# EXTRACT_ONLY
+#      The list of distfiles relative to ${_DISTDIR} that are
+#      extracted.  Defaults to ${DISTFILES}.
 #
-#    EXTRACT_USING specifies the tool used to extract tar/ustar-format
-#      archives when using EXTRACT_CMD_DEFAULT.  The possible values are
-#      "bsdtar", "gtar", "nbtar", and "pax".
-#      By default, we use the "nbtar", which means the value of
-#      ${TOOL_PLATFORM.tar}, which is typically an arbitrary
+#      Only few packages need this variable. To extract some of the
+#      distfiles into separate directories, see EXTRACT_DIR.
+#
+# EXTRACT_USING
+#      The tool used to extract tar/ustar-format archives when using
+#      EXTRACT_CMD_DEFAULT. The possible values are "bsdtar", "gtar",
+#      "nbtar", and "pax". Defaults to "nbtar", which means the value
+#      of ${TOOL_PLATFORM.tar}, which is typically an arbitrary
 #      implementation already found on the platform.
 #    \todo: Decide if this is package-settable or user-settable or both.