[pkgsrc/trunk]: pkgsrc/mk mk/subst.mk: use simpler words in the documentation...

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

details:   https://anonhg.NetBSD.org/pkgsrc/rev/5f6a91d0a842
branches:  trunk
changeset: 332998:5f6a91d0a842
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Sun Apr 28 12:31:15 2019 +0000

description:
mk/subst.mk: use simpler words in the documentation, add an example

diffstat:

 mk/subst.mk |  26 ++++++++++++++++++--------
 1 files changed, 18 insertions(+), 8 deletions(-)

diffs (44 lines):

diff -r 950f94f24cd8 -r 5f6a91d0a842 mk/subst.mk
--- a/mk/subst.mk       Sun Apr 28 12:10:24 2019 +0000
+++ b/mk/subst.mk       Sun Apr 28 12:31:15 2019 +0000
@@ -1,9 +1,19 @@
-# $NetBSD: subst.mk,v 1.59 2019/03/17 12:01:14 rillig Exp $
+# $NetBSD: subst.mk,v 1.60 2019/04/28 12:31:15 rillig Exp $
+#
+# The subst framework replaces text in one or more files in the WRKSRC
+# directory. Packages can define several ``classes'' of replacements.
+# Each such class defines:
 #
-# This Makefile fragment implements a general text replacement facility.
-# Package makefiles define a ``class'', for each of which a particular
-# substitution description can be defined.  For each class of files, a
-# target subst-<class> is created to perform the text replacement.
+#      - in which stage of the build process the replacement happens
+#      - which files are affected by the replacement
+#      - which text or pattern is replaced by which replacement text
+#
+# A typical example is:
+#
+#      SUBST_CLASSES+=         prefix
+#      SUBST_STAGE.prefix=     pre-configure
+#      SUBST_FILES.prefix=     ./configure doc/*.html
+#      SUBST_SED.prefix=       -e 's,/usr/local,${PREFIX},g'
 #
 # Package-settable variables:
 #
@@ -29,12 +39,12 @@
 #
 # SUBST_VARS.<class>
 #      List of variables that are substituted whenever they appear in
-#      the form @VARNAME@. This is basically a short-cut for
+#      the form @VARNAME@. This is basically a shortcut for
 #
 #              -e 's,@VARNAME@,${VARNAME},g'
 #
-#      also taking care of (most) quoting issues. You can use both
-#      SUBST_SED and SUBST_VARS in a single class.
+#      that even works when ${VARNAME} contains arbitrary characters.
+#      Both SUBST_SED and SUBST_VARS can be used in a single class.
 #
 # SUBST_FILTER_CMD.<class>
 #      Filter used to perform the actual substitution on the specified