[Bug 198097] pkg-install -R ... description is confusing

[bugzilla-noreply at freebsd.org]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=198097

            Bug ID: 198097
           Summary: pkg-install -R  ... description is confusing
           Product: Documentation
           Version: Latest
          Hardware: Any
                OS: Any
            Status: New
          Severity: Affects Only Me
          Priority: ---
         Component: Documentation
          Assignee: freebsd-doc at FreeBSD.org
          Reporter: mike.543 at comcast.net

I just updated php5 via pkg.  I wanted to assure that pkgs dependent upon the
php5 pkg were also updated.  So I read the man page for pkg-install and saw the
option

     -R, --from-root
                When used with -f, reinstalls any packages that require the
                given package.


When I saw the mention of -f, I scratched my head, what was the man page trying
to tell me.  Not liking to force anything, I ran the command without -f. 
Here's what I saw:

# pkg install -R php5
Updating FreeBSD repository catalogue...
FreeBSD repository is up-to-date.
All repositories are up-to-date.
The following 8 packages will be affected (of 0 checked):

Installed packages to be UPGRADED:
        php5: 5.4.30 -> 5.4.37
        php5-gettext: 5.4.30 -> 5.4.37
        squirrelmail: 20140420 -> 20141107
        php5-session: 5.4.30 -> 5.4.37
        php5-xml: 5.4.30 -> 5.4.37
        php5-openssl: 5.4.30 -> 5.4.37
        php5-hash: 5.4.30 -> 5.4.37
        php5-mbstring: 5.4.30 -> 5.4.37

The process will require 14 KiB more space.
3 MiB to be downloaded.

Proceed with this action? [y/N]: y
[lots of installation output removed]


That is exactly what I wanted to happen, i.e., install php5 and install all the
pkgs that are dependent upon it.

So now I wonder, what is the purpose of the -f option, if I the dependent
packages were installed by just specifying -R.

Obviously, I'm confused and may not have read the intent of the -R
documentation correctly.  Maybe it can be clarified to better explain what
happens with and without the -f being specified?

-- 
You are receiving this mail because:
You are the assignee for the bug.