Handbook suggestion: Dealing with Moved Ports

[Mike Brown]

[ This is a followup to my thread at http://lists.freebsd.org/pipermail/freebsd-ports/2013-May/083943.html ]

/usr/ports/UPDATING does not normally mention when ports are moved. Unless 
there are special considerations, that info only lives in /usr/ports/MOVED, 
which isn't really something people are expected to look at. Rather, I think 
people usually find out that a port has moved when they try to update their 
installation of it and portmaster (or whatever) aborts with a message about 
the situation:

# portmaster www/mediawiki

        ===>>> The www/mediawiki port moved to www/mediawiki119
        ===>>> Reason: Rename mediawiki to mediawiki119

===>>> Exiting

===>>> The second argument to -o can be a port in /var/db/pkg,
       or a port directory from /usr/ports

        does not seem to be installed,
       or listed as a dependency

===>>> No valid installed port, or port directory given
===>>> Try portmaster --help

===>>> Killing background jobs
Terminated
===>>> Exiting


As you can see, this is a rather cryptic message. What am I expected to do 
here, in order to get this port upgraded?

As far as I can tell, there's nothing about this in the Handbook, and the 
message from portmaster isn't giving me any real guidance as to how to deal 
with this situation.

Perhaps ch. 5.8 - "Dealing with Broken Ports" could be followed by a chapter 
on dealing with moved ports. I believe the proper course of action for people 
in this situation is to first check /usr/ports/UPDATING for specific 
instructions. If there are none, then it depends on what tool they're using.
For example, in my situation, I should do this:

  portmaster -o www/mediawiki-119 www/mediawiki

or, if I want to upgrade to the newer version, I could instead do this:

  portmaster -o www/mediawiki-120 www/mediawiki

I don't know what instructions should be for the other port/package systems; 
I'm only using portmaster these days.



(Also, unrelated: I suggest changing the first sentence of ch. 5.8 from
"If you come across a port that does not compile"
to
"If you come across a port that does not build or install properly".)


Thanks for considering my requests.

- Mike