[pkgsrc/trunk]: pkgsrc/mk/help mk/help/help.awk: find library functions in un...

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

details:   https://anonhg.NetBSD.org/pkgsrc/rev/88af041acde2
branches:  trunk
changeset: 414519:88af041acde2
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Mon Mar 30 06:21:52 2020 +0000

description:
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.

diffstat:

 mk/help/help.awk |  39 +++++++++++++++++++++++++++++++++------
 1 files changed, 33 insertions(+), 6 deletions(-)

diffs (97 lines):

diff -r bb411f6c1105 -r 88af041acde2 mk/help/help.awk
--- a/mk/help/help.awk  Sun Mar 29 20:43:52 2020 +0000
+++ b/mk/help/help.awk  Mon Mar 30 06:21:52 2020 +0000
@@ -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 @@
 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 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 @@
                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 @@
 
        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 (w == tolower(w) && !(w ~ /:$/)) {
+       } 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 !~ /:$/ && $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;
                }
        }