9.5 beta pg_upgrade documentation

Hi All.

I setup two test VM's with my PG93 database to test upgrading to PG95.
I have a primary and standby using wal shipping.
The database is about 150Gig, and the two servers (the real servers) are
far apart.  The vm's are both running on my desktop.

I would love to use pg_upgrade on both primary and standby to save from
copying 150Gig a very long distance.

I'm reading:
http://www.postgresql.org/docs/9.5/static/pgupgrade.html

At step 9, the first sentence says "If you have ... Log-Shipping ...
follow these steps .. before starting any servers".

At first I thought a step was missing because it never says to run
pg_upgrade on the standby.  Then I realized you only run pg_upgrade on
the primary then rsync the standby.  Would a quick description of the
process be helpful?  Something like:

"If you have Streaming Replication (Section 25.2.5) or Log-Shipping
(Section 25.2) standby servers, follow these steps to upgrade them.
After you have performed pg_upgrade on the primary don't start it up yet
because you can rsync it to the standby for an efficient standby upgrade."



I'm confused by step 5 (verify).  There are 4 PG instances we're talking
about (primary new/old and standby new/old)  Which two do I run
pg_controldata on?  And how does running it "prevent old standby servers
from being modified"?  And if step 5 requires standby shutdown after the
primary, isn't that an important thing to say near the top?  Maybe by
step 7: Stop both servers.


On a side note, I'm confusing myself by the step numbers.  There's two
step 7's.  Can we renumber the step 9 sub steps to be 9.1, 9.2, etc?


I think I understand step 9.7, of the four PG instances, "the new
master" tells me which to start and stop.  Although I'm not sure how
long I need to keep it up.  Is as fast as I can type enough time?
Should I count a few potato's between stop and start?

Step 9.8 sounds scary.  Can we specifically say that old_pgdata refers
to the new pg on the primary and new_pgdata refers to the new pg on the
standby?  Is that even right?  Any chance we could get examples of
setting old/new_pgdata?

Thanks all on another great release!

-Andy