Confusion at 'apt-get dist-upgrade' definition

Question

According to man apt-get:

upgrade "is used to install the newest versions of all packages currently installed".

dist-upgrade "in addition to performing the function of upgrade, also intelligently handles changing dependencies with new versions of packages"

I searched for several definitions of dist-upgrade on the Internet and I found that it is used when new dependencies (not already installed) have to be installed, although that is not what man apt-get definition says, as I understand.

I always find man pages to be very precise, but I don't understand what 'changing dependencies with new versions of packages' exactly means in the dist-upgrade definition. Does it mean that dependencies are changed for new versions of the same dependencies? Does 'changed' mean that one dependency is removed and another one installed, or simply that a new version of the same dependency is now installed and used instead of the version replaced? Doesn't upgrade already install new versions of dependencies and 'tell somehow' that the package must use this new dependencies?

Supposing that package A depends upon a file X inside a package B (the dependency): When upgrade installs a newer version of package B, called package B-2, is this newly dependency used by package A or is it that A still uses package B until dist-upgrade is executed ?

Answer 1

Say prior to upgrading you have a situation like this, where both php and and python packages have a dependency on libxml-dev-1.2

                            +--------------------+
                            | python_3.1         |
+--------------+            |                    |
| php7.0       |            | depends on libxml-dev_1.2
|              |            +-----+--------------+
| depends on libxml-dev_1.2       |
|              |                  v
+------------+-+
             |              +---------------------+
             |              | libxml-dev-1.2      |
             +------------> |                     |
                            |                     |
                            |                     |
                            +---------------------+

you then update apt's local index , with apt-get update,
now the apt-cache policy shows there is a new package version available for php - version 7.3.
But running apt-cache show php shows that the new php package needs a newer version of its libxml-dev dependency, the new php package needs say, libxml-dev-1.3.
Normally apt would install all dependencies necessary to satisfy the php 7.3 install or upgrade, however if apt replaced libxml-dev-1.2 with the newer libxml-dev-1.3 (remembering that having libxml-dev-1.2 and libxml-dev-1.3 running side by side is not really an option) in order to satisfy the php7.3 dependency requirements, it would "break" the python dependency requirement.
In this scenario, apt-get upgrade would just do nothing, however if you look at the man apt-get entry for dist-upgrade

dist-upgrade
dist-upgrade in addition to performing the function of upgrade, also intelligently handles changing dependencies with new versions of packages; apt-get has a "smart" conflict resolution system, and it will attempt to upgrade the most important packages at the expense of less important ones if necessary. The dist-upgrade command may therefore remove some packages. [...]

So apt-get dist-upgrade will push bend/break the rules about package specified dependencies in order to get packages upgraded.

Therefore of the two commands, apt-get dist-upgrade will upgrade more packages than would otherwise be upgraded with apt-get upgrade

Answer 2

both case can happen depending if the dependency is over a file or a package. for that matter it exist the command deborphan that can show you if there is orphaned package because of newly installed dependancy.

I generally always use dist-upgrade, and sometime issue a apt-get remove $(deborphan) to clean up things.