I agree UPGRADE.TXT should be updated to add the "--install-new" switch.
Note however that CHANGES_AND_HINTS.TXT (which UPGRADE.TXT references) does list the changes, so a careful reader should be OK:
Code:
*** PACKAGE ADDITIONS SINCE 14.2 ***
a/aaa_glibc-solibs (replaces a/glibc-solibs)
a/aaa_libraries (replaces a/aaa_elflibs)
...
*** PACKAGE REMOVALS SINCE 14.2 ***
a/aaa_elflibs (replaced by a/aaa_libraries)
a/eject (included in a/util-linux)
a/getty-ps (moved to /extra)
a/glibc-solibs (replaced by a/aaa_glibc-solibs)
...
willysr: UPGRADE.TXT and CHANGES_AND_HINTS.TXT make no mention of slackpkg. They are written for users who directly use pkgtools.