CVS commit: pkgsrc/mk/help

["Roland Illig" <rillig%netbsd.org@localhost>]

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.

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;
                }
        }