Rewrote the integrated help to show the complete pathname, not only the

RCS Id, of the file containing the documentation.

When the documentation contains lines starting with "Keywords:", these
lines are not shown by "make help", but all following words are checked
for the topic.

2 files changed, 51 insertions, 37 deletions

diff --git a/mk/help/help.awk b/mk/help/help.awk
index 181bc20ef23..528229fa88b 100644
--- a/mk/help/help.awk
+++ b/mk/help/help.awk
@@ -1,35 +1,53 @@
-# $NetBSD: help.awk,v 1.2 2006/11/04 22:05:43 rillig Exp $
+# $NetBSD: help.awk,v 1.3 2007/01/02 17:22:30 rillig Exp $
+#
+
+# This program extracts the inline documentation from *.mk files.
+#
+# usage: env TOPIC="topic" awk help.awk file...
 #
 
 BEGIN {
-	no = 0; yes = 1;
-	hline = "===============";
-	hline = hline hline hline hline hline;
-	found = no; var = no; comment = no; n = 0;
-	rcsid = "";
-	last_line_was_rcsid = no;
-	last_line_was_empty = yes;
+	no = 0; yes = 1; always = 1;
+
 	topic = ENVIRON["TOPIC"];
 	uctopic = toupper(topic);
+	lctopic = tolower(topic);
+
+	found_anything = no;	# has some help text been found at all?
+	last_fname = "";
+	last_line_was_empty = yes;
+	last_line_was_rcsid = no;
+	ignore_next_empty_line = no;
+
+	delete lines;		# the collected lines
+	relevant = no;		# are the current lines relevant?
+	nlines = 0;		# the number of lines collected so far
+	comment_lines = 0;	# the number of comment lines so far
 }
 
-/.*/ {
+NF >= 1 {
 	if ($0 ~ /^#.*\$.*\$$/) {
-		rcsid = $0;
 		last_line_was_rcsid = yes;
+		ignore_next_empty_line = yes;
 	} else {
-		if (last_line_was_rcsid && $0 == "#") {
-			# Skip this line
-		} else if ($0 == "") {
-			# Skip completely empty lines, too.
+		if ($1 == "#" && $2 == "Keywords:") {
+			for (i = 3; i <= NF; i++) {
+				w = ($i == toupper($1)) ? tolower($i) : $i;
+				if (w == lctopic) {
+					relevant = yes;
+				}
+			}
+			ignore_next_empty_line = yes;
+		} else if (ignore_next_empty_line && $0 == "#") {
+			ignore_next_empty_line = no;
 		} else {
-			lines[n++] = $0;
+			lines[nlines++] = $0;
 		}
 		last_line_was_rcsid = no;
 	}
 }
 
-/./ {
+NF >= 2 {
 	# When looking for "configure", catch lines that contain
 	# "configure" and "CONFIGURE", but not "Configure".
 	w1 = ($1 == tolower($1)) ? toupper($1) : $1;
@@ -40,35 +58,33 @@ BEGIN {
 	    (index(w1, "#"uctopic"?=") == 1) ||
 	    (w1 == "#" && last_line_was_empty &&
 	     (w2 == uctopic || w2 == uctopic":"))) {
-		var = 1;
+		relevant = 1;
 	}
 }
 
 /^#/ {
-	comment = 1;
+	comment_lines++;
 }
 
-/^$/ {
-	if (var && comment) {
+/^$/ || last_fname != FILENAME {
+	if (relevant && comment_lines > 2) {
 		found = yes;
-		print hline;
-		if (rcsid != "") { print rcsid; print "#"; }
-		for (i = 0; i < n; i++) { print lines[i]; }
+		print "===> "last_fname":";
+		for (i = 0; i < nlines; i++) {
+			#print gensub(/^# ?/, "", "", lines[i]);
+			print lines[i];
+		}
 	}
-	var = no; comment = no; n = 0;
+	relevant = no; comment_lines = 0; nlines = 0;
 }
 
-/./ {
-	last_line_was_empty = no;
-}
-/^#$/ || /^$/ {
-	last_line_was_empty = yes;
+always {
+	last_line_was_empty = (/^#$/ || /^$/);
+	last_fname = FILENAME;
 }
 
 END {
-	if (found) {
-		print hline;
-	} else {
+	if (!found) {
 		print "No help found for "topic".";
 	}
 }
diff --git a/mk/help/help.mk b/mk/help/help.mk
index 1d53e2f5412..af6635c4de4 100644
--- a/mk/help/help.mk
+++ b/mk/help/help.mk
@@ -1,4 +1,4 @@
-# $NetBSD: help.mk,v 1.3 2006/12/21 19:50:20 rillig Exp $
+# $NetBSD: help.mk,v 1.4 2007/01/02 17:22:30 rillig Exp $
 #
 
 # This is the integrated pkgsrc online help system. To query for the
@@ -31,10 +31,8 @@ help:
 	@${PRINTF} "\\tvariable names.\\n"
 	@${PRINTF} "\\n"
 .else
-	${_PKG_SILENT}${_PKG_DEBUG} set -e;				\
-	cd ${PKGSRCDIR};						\
-	{ for i in ${_HELP_FILES}; do ${CAT} "$$i"; ${ECHO} ""; done; }	\
-	| env TOPIC=${TOPIC:Q} ${AWK} -f ${PKGSRCDIR}/mk/help/help.awk
+	${RUN} cd ${PKGSRCDIR};						\
+	env TOPIC=${TOPIC:Q} ${AWK} -f ${PKGSRCDIR}/mk/help/help.awk ${_HELP_FILES}
 .endif
 
 .endif