Content-Transfer-Encoding: 7bit
Content-Type: multipart/mixed; boundary="_----------=_1585549313267780"
MIME-Version: 1.0
Date: Mon, 30 Mar 2020 06:21:53 +0000
From: "Roland Illig" <rillig@netbsd.org>
Subject: CVS commit: pkgsrc/mk/help
To: pkgsrc-changes@NetBSD.org
Reply-To: rillig@netbsd.org
Message-Id: <20200330062153.12976FB27@cvs.NetBSD.org>
Sender: pkgsrc-changes-owner@NetBSD.org
Precedence: bulk

This is a multi-part message in MIME format.

--_----------=_1585549313267780
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
Content-Type: text/plain; charset="US-ASCII"

Module Name:	pkgsrc
Committed By:	rillig
Date:		Mon Mar 30 06:21:53 UTC 2020

Modified Files:
	pkgsrc/mk/help: help.awk

Log Message:
mk/help/help.awk: find library functions in undefined-references.help

Before, searching for topic=socket did not find the documentation.

The detection of useful help topics is still not perfect since it now
finds sections that consist of a single word, such as the word
"undo-replace" in mk/install/replace.mk, but that will be fixed later,
after adding a few unit tests.


To generate a diff of this commit:
cvs rdiff -u -r1.34 -r1.35 pkgsrc/mk/help/help.awk

Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.


--_----------=_1585549313267780
Content-Disposition: inline
Content-Length: 3152
Content-Transfer-Encoding: binary
Content-Type: text/x-diff; charset=us-ascii

Modified files:

Index: pkgsrc/mk/help/help.awk
diff -u pkgsrc/mk/help/help.awk:1.34 pkgsrc/mk/help/help.awk:1.35
--- pkgsrc/mk/help/help.awk:1.34	Sun Aug 25 20:30:11 2019
+++ pkgsrc/mk/help/help.awk	Mon Mar 30 06:21:52 2020
@@ -1,4 +1,4 @@
-# $NetBSD: help.awk,v 1.34 2019/08/25 20:30:11 rillig Exp $
+# $NetBSD: help.awk,v 1.35 2020/03/30 06:21:52 rillig Exp $
 #
 
 # This program extracts the inline documentation from *.mk files.
@@ -38,7 +38,9 @@ BEGIN {
 function end_of_topic() {
 
 	if (comment_lines <= 2 || ignore_this_section) {
-		if (comment_lines <= 2) {
+		if (array_is_empty(keywords)) {
+			dprint("Ignoring section because of missing keywords.");
+		} else if (comment_lines <= 2) {
 			dprint("Ignoring section because of too small comment.");
 		} else {
 			dprint("Ignoring section because of a previous decision.");
@@ -101,9 +103,22 @@ function cleanup() {
 }
 
 function dprint(msg) {
-	if (debug) {
-		print(FILENAME ":" FNR ": " msg);
+	if (!debug) return;
+	print(FILENAME ":" FNR ": " msg);
+}
+
+function dprint_skip(word, reason) {
+	if (!debug) return;
+	print(FILENAME ":" FNR ": \"" word "\" is no keyword because " reason);
+}
+
+function array_is_empty(arr,   i, empty) {
+	empty = yes;
+	for (i in arr) {
+		empty = no;
+		break;
 	}
+	return empty;
 }
 
 {
@@ -127,7 +142,7 @@ function dprint(msg) {
 		w = ($i == toupper($i)) ? tolower($i) : $i;
 		sub(/,$/, "", w);
 		keywords[w] = yes;
-		dprint("Adding keyword " w);
+		dprint("Adding keyword \"" w "\"");
 	}
 	ignore_this_line = yes;
 	ignore_next_empty_line = yes;
@@ -167,29 +182,41 @@ NF >= 1 && !/^[\t.]/ && !/^#*$/ && !/^#\
 
 	if (w ~ /\+=$/) {
 		# Appending to a variable is usually not a definition.
+		dprint_skip(w, "it is appended to a variable");
 
 	} else if (w != toupper(w) && w != tolower(w)) {
 		# Words in mixed case are not taken as keywords. If you
 		# want them anyway, list them in a "Keywords:" line.
+		dprint_skip(w, "it is mixed case");
 
 	} else if (w !~ /^[A-Za-z][-0-9A-Z_a-z]*[0-9A-Za-z](:|\?=|=)?$/) {
 		# Keywords must consist only of letters, digits, hyphens
 		# and underscores; except for some trailing type specifier.
+		dprint_skip(w, "it contains special characters");
+
+	} else if (NF > 2 && w == tolower(w)) {
+		dprint_skip(w, "it is lowercase and followed by other words");
+
+	} else if (/^#[ \t][ \t]/ && w == tolower(w)) {
+		dprint_skip(w, "it is indented by several spaces");
 
-	} else if (w == tolower(w) && !(w ~ /:$/)) {
+	} else if (w == tolower(w) && w !~ /:$/ && $0 != "# " w) {
 		# Lower-case words (often make targets) must be followed
 		# by a colon to be recognized as keywords.
+		dprint_skip(w, "it is lowercase and not followed by a colon");
 
 	} else if (w == toupper(w) && w ~ /:$/) {
 		# Upper-case words ending with a colon are probably not
 		# make targets, so ignore them. Common cases are tags
 		# like FIXME and TODO.
+		dprint_skip(w, "it is uppercase and followed by a hyphen");
 
 	} else {
 		sub(/^#[ \t]*/, "", w);
 		sub(/(:|\?=|=)$/, "", w);
 		sub(/:$/, "", w);
 		if (w != "") {
+			if (debug) dprint("Adding keyword \"" w "\"");
 			keywords[w] = yes;
 		}
 	}


--_----------=_1585549313267780--