From 2748a7a44f3932977787450f4e8ff0297886b1ef Mon Sep 17 00:00:00 2001
From: rillig <rillig@pkgsrc.org>
Date: Sat, 6 Jan 2007 16:49:40 +0000
Subject: Rewrote the AWK program and added many comments.

---
 mk/help/help.awk | 83 ++++++++++++++++++++++++++++++++++++--------------------
 mk/help/help.mk  |  6 ++--
 2 files changed, 57 insertions(+), 32 deletions(-)

diff --git a/mk/help/help.awk b/mk/help/help.awk
index 6c1ff6993ca..a77c1fc6690 100644
--- a/mk/help/help.awk
+++ b/mk/help/help.awk
@@ -1,4 +1,4 @@
-# $NetBSD: help.awk,v 1.4 2007/01/02 22:54:54 rillig Exp $
+# $NetBSD: help.awk,v 1.5 2007/01/06 16:49:40 rillig Exp $
 #
 
 # This program extracts the inline documentation from *.mk files.
@@ -16,7 +16,7 @@ BEGIN {
 	found_anything = no;	# has some help text been found at all?
 	last_fname = "";
 	last_line_was_empty = yes;
-	last_line_was_rcsid = no;
+	ignore_this_line = no;
 	ignore_next_empty_line = no;
 
 	delete lines;		# the collected lines
@@ -25,57 +25,80 @@ BEGIN {
 	comment_lines = 0;	# the number of comment lines so far
 }
 
-NF >= 1 {
-	if ($0 ~ /^#.*\$.*\$$/) {
-		last_line_was_rcsid = yes;
-		ignore_next_empty_line = yes;
-	} else {
-		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[nlines++] = $0;
+always {
+	ignore_this_line = (ignore_next_empty_line && $0 == "#");
+}
+
+# There is no need to print the RCS Id, since the full pathname
+# is prefixed to the file contents.
+/^#.*\$.*\$$/ {
+	ignore_this_line = yes;
+	ignore_next_empty_line = yes;
+}
+
+# The lines containing the keywords should also not appear in
+# the output for now. This decision is not final since it may
+# be helpful for the user to know by which keywords a topic
+# can be reached.
+($1 == "#" && $2 == "Keywords:") {
+	for (i = 3; i <= NF; i++) {
+		w = ($i == toupper($i)) ? tolower($i) : $i;
+		if (w == lctopic) {
+			relevant = yes;
 		}
-		last_line_was_rcsid = no;
 	}
+	ignore_next_empty_line = yes;
 }
 
+($0 == "#") {
+	ignore_next_empty_line = no;
+}
+
+(!ignore_this_line) {
+	lines[nlines++] = $0;
+}
+
+# Check whether the current line contains a keyword. Such a keyword must
+# be all-lowercase (make targets) or all-uppercase (variable names).
+# Everything else is assumed to belong to the explaining text.
+#
 NF >= 2 {
-	# When looking for "configure", catch lines that contain
-	# "configure" and "CONFIGURE", but not "Configure".
 	w1 = ($1 == tolower($1)) ? toupper($1) : $1;
 	w2 = ($2 == tolower($2)) ? toupper($2) : $2;
 
-	if ((w1 == uctopic"?=") || (w1 == uctopic"=") ||
+	if ((w1 == uctopic"?=") ||
+	    (w1 == uctopic"=") ||
 	    (index(w1, "#"uctopic"=") == 1) ||
 	    (index(w1, "#"uctopic"?=") == 1) ||
-	    (w1 == "#" && last_line_was_empty &&
-	     (w2 == uctopic || w2 == uctopic":"))) {
-		relevant = 1;
+	    (last_line_was_empty && w1 == "#" && (w2 == uctopic ||
+						  w2 == uctopic":"))) {
+		relevant = yes;
 	}
 }
 
-/^#/ {
+$1 == "#" {
 	comment_lines++;
 }
 
+# Help topics are separated by either completely empty lines or by the
+# end of a file. When here have been enough comment lines, the topic is
+# considered worth printing.
+#
 /^$/ || last_fname != FILENAME {
 	if (relevant && comment_lines > 2) {
-		found = yes;
+		found_anything = yes;
 		print "===> "last_fname":";
 		for (i = 0; i < nlines; i++) {
 			#print gensub(/^# ?/, "", "", lines[i]);
 			print lines[i];
 		}
 	}
-	relevant = no; comment_lines = 0; nlines = 0;
+
+	ignore_next_empty_line = yes;
+	delete lines;
+	relevant = no;
+	nlines = 0;
+	comment_lines = 0;
 }
 
 always {
@@ -84,7 +107,7 @@ always {
 }
 
 END {
-	if (!found) {
+	if (!found_anything) {
 		print "No help found for "topic".";
 	}
 }
diff --git a/mk/help/help.mk b/mk/help/help.mk
index af6635c4de4..79cfe7e0479 100644
--- a/mk/help/help.mk
+++ b/mk/help/help.mk
@@ -1,4 +1,4 @@
-# $NetBSD: help.mk,v 1.4 2007/01/02 17:22:30 rillig Exp $
+# $NetBSD: help.mk,v 1.5 2007/01/06 16:49:40 rillig Exp $
 #
 
 # This is the integrated pkgsrc online help system. To query for the
@@ -9,7 +9,9 @@
 .if !defined(_PKGSRC_HELP_MK)
 _PKGSRC_HELP_MK=	# defined
 
-_HELP_FILES=		mk/*.mk mk/*/*.mk mk/defaults/mk.conf
+_HELP_FILES=		Makefile
+_HELP_FILES+=		mk/*.mk mk/*/*.mk
+_HELP_FILES+=		mk/defaults/mk.conf
 _HELP_FILES+=		lang/perl5/*.mk lang/php/*.mk lang/python/*.mk
 _HELP_FILES+=		lang/ruby/*.mk
 
-- 
cgit v1.2.3