[pkgsrc/trunk]: pkgsrc/mk/help Rewrote the AWK program and added many comments.

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

details:   https://anonhg.NetBSD.org/pkgsrc/rev/39d54eb6b2a8
branches:  trunk
changeset: 523345:39d54eb6b2a8
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Sat Jan 06 16:49:40 2007 +0000

description:
Rewrote the AWK program and added many comments.

diffstat:

 mk/help/help.awk |  101 +++++++++++++++++++++++++++++++++---------------------
 mk/help/help.mk  |    6 ++-
 2 files changed, 66 insertions(+), 41 deletions(-)

diffs (164 lines):

diff -r eb4047a87e88 -r 39d54eb6b2a8 mk/help/help.awk
--- a/mk/help/help.awk  Sat Jan 06 16:47:54 2007 +0000
+++ b/mk/help/help.awk  Sat Jan 06 16:49:40 2007 +0000
@@ -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 @@
        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 @@
        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 {
+       w1 = ($1 == tolower($1)) ? toupper($1) : $1;
+       w2 = ($2 == tolower($2)) ? toupper($2) : $2;
+
+       if ((w1 == uctopic"?=") ||
+           (w1 == uctopic"=") ||
+           (index(w1, "#"uctopic"=") == 1) ||
+           (index(w1, "#"uctopic"?=") == 1) ||
+           (last_line_was_empty && w1 == "#" && (w2 == uctopic ||
+                                                 w2 == uctopic":"))) {
+               relevant = yes;
        }
 }
 
-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"=") ||
-           (index(w1, "#"uctopic"=") == 1) ||
-           (index(w1, "#"uctopic"?=") == 1) ||
-           (w1 == "#" && last_line_was_empty &&
-            (w2 == uctopic || w2 == uctopic":"))) {
-               relevant = 1;
-       }
-}
-
-/^#/ {
+$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 @@
 }
 
 END {
-       if (!found) {
+       if (!found_anything) {
                print "No help found for "topic".";
        }
 }
diff -r eb4047a87e88 -r 39d54eb6b2a8 mk/help/help.mk
--- a/mk/help/help.mk   Sat Jan 06 16:47:54 2007 +0000
+++ b/mk/help/help.mk   Sat Jan 06 16:49:40 2007 +0000
@@ -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