[pkgsrc/trunk]: pkgsrc/mk/help Rewrote the integrated help to show the comple...

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

details:   https://anonhg.NetBSD.org/pkgsrc/rev/ba3512e9bba0
branches:  trunk
changeset: 523138:ba3512e9bba0
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Tue Jan 02 17:22:30 2007 +0000

description:
Rewrote the integrated help to show the complete pathname, not only the
RCS Id, of the file containing the documentation.

When the documentation contains lines starting with "Keywords:", these
lines are not shown by "make help", but all following words are checked
for the topic.

diffstat:

 mk/help/help.awk |  80 +++++++++++++++++++++++++++++++++----------------------
 mk/help/help.mk  |   8 ++---
 2 files changed, 51 insertions(+), 37 deletions(-)

diffs (145 lines):

diff -r 656ff9fab798 -r ba3512e9bba0 mk/help/help.awk
--- a/mk/help/help.awk  Tue Jan 02 17:16:34 2007 +0000
+++ b/mk/help/help.awk  Tue Jan 02 17:22:30 2007 +0000
@@ -1,35 +1,53 @@
-# $NetBSD: help.awk,v 1.2 2006/11/04 22:05:43 rillig Exp $
+# $NetBSD: help.awk,v 1.3 2007/01/02 17:22:30 rillig Exp $
+#
+
+# This program extracts the inline documentation from *.mk files.
+#
+# usage: env TOPIC="topic" awk help.awk file...
 #
 
 BEGIN {
-       no = 0; yes = 1;
-       hline = "===============";
-       hline = hline hline hline hline hline;
-       found = no; var = no; comment = no; n = 0;
-       rcsid = "";
-       last_line_was_rcsid = no;
-       last_line_was_empty = yes;
+       no = 0; yes = 1; always = 1;
+
        topic = ENVIRON["TOPIC"];
        uctopic = toupper(topic);
+       lctopic = tolower(topic);
+
+       found_anything = no;    # has some help text been found at all?
+       last_fname = "";
+       last_line_was_empty = yes;
+       last_line_was_rcsid = no;
+       ignore_next_empty_line = no;
+
+       delete lines;           # the collected lines
+       relevant = no;          # are the current lines relevant?
+       nlines = 0;             # the number of lines collected so far
+       comment_lines = 0;      # the number of comment lines so far
 }
 
-/.*/ {
+NF >= 1 {
        if ($0 ~ /^#.*\$.*\$$/) {
-               rcsid = $0;
                last_line_was_rcsid = yes;
+               ignore_next_empty_line = yes;
        } else {
-               if (last_line_was_rcsid && $0 == "#") {
-                       # Skip this line
-               } else if ($0 == "") {
-                       # Skip completely empty lines, too.
+               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[n++] = $0;
+                       lines[nlines++] = $0;
                }
                last_line_was_rcsid = no;
        }
 }
 
-/./ {
+NF >= 2 {
        # When looking for "configure", catch lines that contain
        # "configure" and "CONFIGURE", but not "Configure".
        w1 = ($1 == tolower($1)) ? toupper($1) : $1;
@@ -40,35 +58,33 @@
            (index(w1, "#"uctopic"?=") == 1) ||
            (w1 == "#" && last_line_was_empty &&
             (w2 == uctopic || w2 == uctopic":"))) {
-               var = 1;
+               relevant = 1;
        }
 }
 
 /^#/ {
-       comment = 1;
+       comment_lines++;
 }
 
-/^$/ {
-       if (var && comment) {
+/^$/ || last_fname != FILENAME {
+       if (relevant && comment_lines > 2) {
                found = yes;
-               print hline;
-               if (rcsid != "") { print rcsid; print "#"; }
-               for (i = 0; i < n; i++) { print lines[i]; }
+               print "===> "last_fname":";
+               for (i = 0; i < nlines; i++) {
+                       #print gensub(/^# ?/, "", "", lines[i]);
+                       print lines[i];
+               }
        }
-       var = no; comment = no; n = 0;
+       relevant = no; comment_lines = 0; nlines = 0;
 }
 
-/./ {
-       last_line_was_empty = no;
-}
-/^#$/ || /^$/ {
-       last_line_was_empty = yes;
+always {
+       last_line_was_empty = (/^#$/ || /^$/);
+       last_fname = FILENAME;
 }
 
 END {
-       if (found) {
-               print hline;
-       } else {
+       if (!found) {
                print "No help found for "topic".";
        }
 }
diff -r 656ff9fab798 -r ba3512e9bba0 mk/help/help.mk
--- a/mk/help/help.mk   Tue Jan 02 17:16:34 2007 +0000
+++ b/mk/help/help.mk   Tue Jan 02 17:22:30 2007 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: help.mk,v 1.3 2006/12/21 19:50:20 rillig Exp $
+# $NetBSD: help.mk,v 1.4 2007/01/02 17:22:30 rillig Exp $
 #
 
 # This is the integrated pkgsrc online help system. To query for the
@@ -31,10 +31,8 @@
        @${PRINTF} "\\tvariable names.\\n"
        @${PRINTF} "\\n"
 .else
-       ${_PKG_SILENT}${_PKG_DEBUG} set -e;                             \
-       cd ${PKGSRCDIR};                                                \
-       { for i in ${_HELP_FILES}; do ${CAT} "$$i"; ${ECHO} ""; done; } \
-       | env TOPIC=${TOPIC:Q} ${AWK} -f ${PKGSRCDIR}/mk/help/help.awk
+       ${RUN} cd ${PKGSRCDIR};                                         \
+       env TOPIC=${TOPIC:Q} ${AWK} -f ${PKGSRCDIR}/mk/help/help.awk ${_HELP_FILES}
 .endif
 
 .endif