NetBSD Problem Report #47178

From bughunting@xs4all.nl  Sat Nov 10 16:32:13 2012
Return-Path: <bughunting@xs4all.nl>
Received: from mail.netbsd.org (mail.netbsd.org [149.20.53.66])
	by www.NetBSD.org (Postfix) with ESMTP id 61D5463DFC0
	for <gnats-bugs@gnats.NetBSD.org>; Sat, 10 Nov 2012 16:32:13 +0000 (UTC)
Message-Id: <20121110163140.GA28263@frohike.homeunix.org>
Date: Sat, 10 Nov 2012 17:31:40 +0100
From: Bug Hunting <bughunting@xs4all.nl>
To: NetBSD GNATS <gnats-bugs@gnats.NetBSD.org>
Subject: Errors in, and enhancements for, wtf(6) and its man page [patch
 included]
X-Send-Pr-Version: 3.95

>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:    abs
>State:          closed
>Class:          sw-bug
>Submitter-Id:   net
>Arrival-Date:   Sat Nov 10 16:35:00 +0000 2012
>Closed-Date:    Tue Nov 20 12:41:28 +0000 2012
>Last-Modified:  Tue Nov 20 12:45:02 +0000 2012
>Originator:     Bug Hunting
>Release:        NetBSD 6.99.15
>Organization:

>Environment:

>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--

>Release-Note:

>Audit-Trail:

Responsible-Changed-From-To: bin-bug-people->abs
Responsible-Changed-By: abs@NetBSD.org
Responsible-Changed-When: Tue, 20 Nov 2012 12:41:28 +0000
Responsible-Changed-Why:


State-Changed-From-To: open->closed
State-Changed-By: abs@NetBSD.org
State-Changed-When: Tue, 20 Nov 2012 12:41:28 +0000
State-Changed-Why:
patch applied, modulus manpage date bump and splitting a long comment line

Thanks!


From: "David Brownlee" <abs@netbsd.org>
To: gnats-bugs@gnats.NetBSD.org
Cc: 
Subject: PR/47178 CVS commit: src/games/wtf
Date: Tue, 20 Nov 2012 12:40:54 +0000

 Module Name:	src
 Committed By:	abs
 Date:		Tue Nov 20 12:40:54 UTC 2012

 Modified Files:
 	src/games/wtf: wtf wtf.6

 Log Message:
 PR/47178 from Bug Hunting

 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.


 To generate a diff of this commit:
 cvs rdiff -u -r1.18 -r1.19 src/games/wtf/wtf
 cvs rdiff -u -r1.15 -r1.16 src/games/wtf/wtf.6

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

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

Home	PR Database Search