bin/47178: Errors in, and enhancements for, wtf(6) and its man page [patch included]

[Bug Hunting <bughunting%xs4all.nl@localhost>]

>Number:         47178
>Category:       bin
>Synopsis:       Subject: Errors in, and enhancements for, wtf(6) and its man 
>page [patch included]
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    bin-bug-people
>State:          open
>Class:          sw-bug
>Submitter-Id:   net
>Arrival-Date:   Sat Nov 10 16:35:00 +0000 2012
>Originator:     Bug Hunting
>Release:        NetBSD 6.99.15
>Description:

The wtf(6) program relies on a non-zero exit status of pkgsrc's
"make help" target, while in fact this target always returns exit
status zero, whether or not the help topic was actually found.
This makes wtf(6) display non-intended output, and exit with an
incorrect exit status.  (Note: perhaps this should _actually_ be
fixed in pkgsrc?)

Also, the wtf(6) man page contains minor errors, and can use other
enhancements.

One ``error'' is that the man page still mentions to (solely) look
up acronyms; while in fact it still does, it nowadays looks up
terms in a more general sense, i.e., not just as acronyms in acronym
databases.

Also, the man page doesn't mention that pkgsrc's help facility is
only queried when wtf(6) is called from within a pkgsrc package
directory (or a second-level pkgsrc child directory in general);
even when this is only a side effect requirement because of wtf(6)
looking for the required mk/bsd.pkg.mk pkgsrc file to be able to
use pkgsrc's `help' make(1) target, it still is a valid requirement
on itself, with the rationale that people would only be interested
in wtf(6) displaying pkgsrc help when calling it from within pkgsrc
directories, and not in other cases.



>How-To-Repeat:

"man -s 6 wtf"

and

$ cd /usr/pkgsrc/mail/mutt    # or any other second-level pkgsrc child directory
$ wtf foo                     # choose a term wtf(6) can't find, not even by 
pkgsrc's help facility
foo: No help found for foo.
$ echo $?                     # see the incorrect exit status from wtf(6) itself
0



>Fix:

Apply the patch attached.  Its top lines provide a list of changes,
which may be included as-is in the commit message(s).

--nhYGnrYv1PEJ5gA2
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="wtf_1.18_wtf.6_1.15.patch"

src/games/wtf/wtf:
- Correct `usage' (to match new `SYNOPSIS' from man page);
- augment comment on quering pkgsrc's help facility;
- correct interpretation of pkgsrc' help facility query result.

src/games/wtf/wtf.6:
- enhance `SYNOPSIS', document description (`.Dd'), and overal
  program description;
- augment description about quering pkgsrc's help facility;
- improve wording;
- augment `HISTORY' section;
- bump date.

---

Index: src/games/wtf/wtf
===================================================================
RCS file: /cvsroot/src/games/wtf/wtf,v
retrieving revision 1.18
diff -u -r1.18 wtf
--- src/games/wtf/wtf   3 Oct 2012 19:50:06 -0000       1.18
+++ src/games/wtf/wtf   10 Nov 2012 15:38:02 -0000
@@ -8,7 +8,7 @@
 PROGNAME="$(basename "$0")"
 
 usage() {
-       echo "usage: $PROGNAME [-f dbfile] [is] <acronym> ..."
+       echo "usage: $PROGNAME [-f dbfile] [is] term ..."
        exit 1
 }
 
@@ -76,10 +76,10 @@
                continue
        fi
 
-       # Try querying pkgsrc's help facility next
+       # If called from pkgsrc package directory, try querying pkgsrc's help 
facility next
        if [ -f ../../mk/bsd.pkg.mk ]; then
                ans="$(make help topic="$i")"
-               if [ $? -eq 0 ]; then
+               if [ "$ans" != "No help found for $i." ]; then
                        echo "$i: $ans"
                        continue
                fi
Index: src/games/wtf/wtf.6
===================================================================
RCS file: /cvsroot/src/games/wtf/wtf.6,v
retrieving revision 1.15
diff -u -r1.15 wtf.6
--- src/games/wtf/wtf.6 3 Oct 2012 19:50:43 -0000       1.15
+++ src/games/wtf/wtf.6 10 Nov 2012 15:38:02 -0000
@@ -2,40 +2,45 @@
 .\"
 .\" Public Domain
 .\"
-.Dd October 3, 2012
+.Dd November 10, 2012
 .Dt WTF 6
 .Os
 .Sh NAME
 .Nm wtf
-.Nd translate acronyms
+.Nd look up terms
 .Sh SYNOPSIS
 .Nm
 .Op Fl f Ar dbfile
 .Op Ar is
-.Ar acronym ...
+.Ar term ...
 .Sh DESCRIPTION
 The
 .Nm
-utility displays the expansion of one or more acronyms
-specified on the command line.
-If an acronym is not in any of the acronym databases,
+utility looks up the meaning of one or more
+.Ar term
+operands specified on the command line.
+.Pp
+.Ar term
+will first be searched for as an acronym in the acronym databases,
 which are expected to be in the format
-.Dq acronym[tab]meaning ,
+.Dq acronym[tab]meaning .
+If no match has been found,
 .Nm
-will check to see if it is known by
+will check to see if the term is known by
 .Xr whatis 1 ,
 .Xr pkg_info 1 ,
-or via pkgsrc's internal help mechanism,
+or, when called from within a pkgsrc package directory,
+pkgsrc's internal help facility,
 .Dq make help topic=XXX .
 .Pp
-If
-.Dq is
-is specified on the command line, it will be ignored, allowing the
+The optional
+.Ar is
+operand will be ignored, allowing the
 fairly natural
 .Dq wtf is WTF
 usage.
 .Pp
-The following options are available:
+The following option is available:
 .Bl -tag -width flag
 .It Fl f Ar dbfile
 Overrides the default list of acronym databases, bypassing the value of the
@@ -70,3 +75,5 @@
 .Nm
 first appeared in
 .Nx 1.5 .
+Initially it only translated acronyms;
+functionality to look up the meaning of terms in other sources was added later.

--nhYGnrYv1PEJ5gA2--

>Unformatted:
 --nhYGnrYv1PEJ5gA2
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline