pkg/26698: pkg_info -R description is still inverted

[jbernard%mines.edu@localhost]

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