>Number:         26698
>Category:       pkg
>Synopsis:       pkg_info -R description is still inverted
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    pkg-manager
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Tue Aug 17 21:29:01 UTC 2004
>Closed-Date:
>Last-Modified:
>Originator:     Jim Bernard
>Release:        NetBSD 2.0G
>Organization:
>Environment:
System: NetBSD 2.0G Sat Jul 31 17:03:53 MDT 2004 i386
Architecture: i386
Machine: i386
>Description:
	The pkg_info(1) man page _still_ (see PR 9141) says:

	  -R      Show which packages are required by each package.

	And that is still incorrect.  The wording was changed to an
	alternative, but still incorrect, form in revision 1.20, and
	that was reverted to the original and current wording in
	revision 1.21.

	What you get when you say

	  pkg_info -R some_pkg

	is a list of all packages that require some_pkg.  That is,
	you cannot install those packages without having some_pkg
	installed, since they depend on some_pkg.  The wording in
	the man page says that the result is a list of packages
	that are required by some_pkg, i.e., that some_pkg requires,
	or that some_pkg depends on having installed prior to its
	own installation and that cannot be deleted without deleting
	some_pkg first.

	I belabor these points, because evidently there is confusion
	about the meaning of the statement as worded, and I want to
	make sure it is interpreted correctly and therefore perceived
	as an incorrect representation of what the option actually
	does.

	Some of the confusion probably arises from the text given
	in the output.  For example:

	  % pkg_info -R png
	  Information for png-1.2.6rc2:

	  Required by:
	  xfig-3.2.4nb1
	  emacs-21.3nb4
	  ...

	The meaning of this is that xfig, emacs, etc. require
	(need, or depend upon) png (i.e., png is required by them),
	not that they are required by png.  The current wording in
	the man page means that the listed packages ("show which
	packages"), in this case xfig, emacs, etc. are required by
	(needed by) the packages supplied on the command line ("each
	package"), in this case, png.  Thus, the sense, as stated
	in the man page, is inverted.

>How-To-Repeat:
	Read it carefully enough to understand it, and test it with
	a couple of examples in your own installation for which you
	already know the true direction of the dependency.

>Fix:
	In PR 9141 I suggested:

	  -R   Show which packages require each package.

	This is correct wording, but evidently there is enough
	confusion about the meaning that neither the original
	wording, nor this wording, are being correctly interpreted.
	So, does this:

	  -R   Show which packages require (i.e., need or depend
	       upon) each package supplied on the command line.

	work better?  If not, I'll be happy to work with someone
	on a choice of wording that is both correct and easier to
	understand.
>Release-Note:
>Audit-Trail:
>Unformatted: