[pkgsrc/trunk]: pkgsrc/mk/help mk/help: if no intentional documentation is fo...

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

details:   https://anonhg.NetBSD.org/pkgsrc/rev/cdd7d3a55e7e
branches:  trunk
changeset: 383106:cdd7d3a55e7e
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Sun Jul 22 06:45:31 2018 +0000

description:
mk/help: if no intentional documentation is found, list containing files

diffstat:

 mk/help/help.awk |  30 +++++++++++++++++++-----------
 1 files changed, 19 insertions(+), 11 deletions(-)

diffs (93 lines):

diff -r f17ca8d9919f -r cdd7d3a55e7e mk/help/help.awk
--- a/mk/help/help.awk  Sun Jul 22 05:15:53 2018 +0000
+++ b/mk/help/help.awk  Sun Jul 22 06:45:31 2018 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: help.awk,v 1.30 2018/03/07 00:14:57 rillig Exp $
+# $NetBSD: help.awk,v 1.31 2018/07/22 06:45:31 rillig Exp $
 #
 
 # This program extracts the inline documentation from *.mk files.
@@ -7,7 +7,7 @@
 #
 
 BEGIN {
-       no = 0; yes = 1; always = 1;
+       no = 0; yes = 1;
 
        debug = ENVIRON["HELP_DEBUG"] != "";
        topic = ENVIRON["TOPIC"];
@@ -28,6 +28,7 @@
        print_noncomment_lines = yes; # for make targets, this isn't useful
        print_index = (topic == ":index");
                                # whether to print only the list of keywords
+       delete all_appearances; # all files where the topic appears as text
 }
 
 # Help topics are separated by either completely empty lines or by the
@@ -56,7 +57,7 @@
                        print "";
                found_anything = yes;
 
-               print "===> " last_fname " (keywords:" sorted_keys(keywords) "):";
+               print "===> " last_fname " (keywords:" sorted_keys(keywords, " ") "):";
 
                for (i = 0; i < nlines; i++) {
                        if (print_noncomment_lines || (lines[i] ~ /^#/))
@@ -66,7 +67,7 @@
        cleanup();
 }
 
-function sorted_keys(array,   elem, list, listlen, i, j, tmp, joined) {
+function sorted_keys(array, separator,   elem, list, listlen, i, j, tmp, joined) {
        listlen = 0;
        for (elem in array)
                list[listlen++] = elem;
@@ -83,7 +84,7 @@
 
        joined = "";
        for (i = 0; i < listlen; i++) {
-               joined = joined " " list[i];
+               joined = joined separator list[i];
        }
        return joined;
 }
@@ -104,7 +105,7 @@
        }
 }
 
-always {
+{
        ignore_this_line = (ignore_next_empty_line && $0 == "#") || $0 == "";
        ignore_next_empty_line = no;
 }
@@ -206,7 +207,11 @@
        end_of_topic();
 }
 
-always {
+index(tolower($0), topic) != 0 {
+       all_appearances[FILENAME] = yes;
+}
+
+{
        last_fname = FILENAME;
 }
 
@@ -215,10 +220,13 @@
        if (print_index) {
                print "Available help topics:";
                print "";
-               for (k in all_keywords) {
-                       print k | "LC_ALL=C sort";
+               print sorted_keys(all_keywords, "\n");
+       } else if (!found_anything) {
+               appearances = sorted_keys(all_appearances, "\n");
+               if (appearances != "") {
+                       print "No help found for " topic ", but it appears in:\n" appearances;
+               } else {
+                       print "No help found for " topic ".";
                }
-       } else if (!found_anything) {
-               print "No help found for "topic".";
        }
 }