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.

1 files changed, 20 insertions, 13 deletions

diff --git a/mk/extract/bsd.extract-vars.mk b/mk/extract/bsd.extract-vars.mk
index 647dcb9d9f0..99e14473f7a 100644
--- a/mk/extract/bsd.extract-vars.mk
+++ b/mk/extract/bsd.extract-vars.mk
@@ -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_SUFX
+#	The suffix for the default distfile to be extracted.
+#	Defaults to ".tar.gz".
 #
-#    EXTRACT_ONLY is a list of distfiles relative to ${_DISTDIR} to
-#	extract and defaults to ${DISTFILES}.
+# EXTRACT_ONLY
+#	The list of distfiles relative to ${_DISTDIR} that are
+#	extracted.  Defaults to ${DISTFILES}.
 #
-#    EXTRACT_SUFX is the suffix for the default distfile to be
-#       extracted.  The default suffix is ".tar.gz".
+#	Only few packages need this variable. To extract some of the
+#	distfiles into separate directories, see EXTRACT_DIR.
 #
-#    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
+# 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.