docs(pip_freeze): clarify --all; explain Python version differences

docs/html/cli/pip_freeze.rst

@@ -30,49 +30,61 @@ Options
 .. pip-command-options:: freeze
 
 
+
+
+.. note::
+
+   By default, ``pip freeze`` omits pip's own bootstrap tools (``pip``,
+   ``setuptools``, and ``wheel``) to keep the output focused on project
+   dependencies. Use ``--all`` to include these as well, which is helpful when
+   capturing a full environment snapshot. Remember that ``pip freeze`` only
+   reports what is currently installed; it is not a lockfile or solver result.
+
+
 Examples
 ========
+         env1\bin\python -m pip freeze > requirements.txt
+         env2\bin\python -m pip install -r requirements.txt
 
-#. Generate output suitable for a requirements file.
+#. Compare default output with ``--all``.
 
    .. tab:: Unix/macOS
 
       .. code-block:: console
 
          $ python -m pip freeze
-         docutils==0.11
-         Jinja2==2.7.2
-         MarkupSafe==0.19
-         Pygments==1.6
-         Sphinx==1.2.2
+         certifi==...
+         idna==...
+         requests==...
+         urllib3==...
+
+         $ python -m pip freeze --all
+         certifi==...
+         idna==...
+         requests==...
+         urllib3==...
+         pip==...
+         setuptools==...
+         wheel==...
 
    .. tab:: Windows
 
       .. code-block:: console
 
          C:\> py -m pip freeze
-         docutils==0.11
-         Jinja2==2.7.2
-         MarkupSafe==0.19
-         Pygments==1.6
-         Sphinx==1.2.2
-
-#. Generate a requirements file and then install from it in another environment.
-
-   .. tab:: Unix/macOS
-
-      .. code-block:: shell
-
-         env1/bin/python -m pip freeze > requirements.txt
-         env2/bin/python -m pip install -r requirements.txt
-
-   .. tab:: Windows
-
-      .. code-block:: shell
-
-         env1\bin\python -m pip freeze > requirements.txt
-         env2\bin\python -m pip install -r requirements.txt
-
+         certifi==...
+         idna==...
+         requests==...
+         urllib3==...
+
+         C:\> py -m pip freeze --all
+         certifi==...
+         idna==...
+         requests==...
+         urllib3==...
+         pip==...
+         setuptools==...
+         wheel==...
 
 Fixing "Permission denied:" errors
 ==================================

docs/html/topics/dependency-resolution.md

@@ -165,6 +165,9 @@ will avoid performing dependency resolution during deployment.
 
 ## Dealing with dependency conflicts
 
+This section uses imaginary packages (`package_coffee`, `package_tea`, and
+`package_water`) to explain how pip resolves conflicts.
+
 This section provides practical suggestions to pip users who encounter
 a `ResolutionImpossible` error, where pip cannot install their specified
 packages due to conflicting dependencies.
@@ -194,6 +197,11 @@ because they each depend on different versions of the same package
 - ``package_tea`` version ``4.3.0`` depends on version ``2.3.1`` of
   ``package_water``
 
+Note: `package_coffee`, `package_tea`, and `package_water` are imaginary
+packages used only to illustrate dependency conflicts. They are not real
+projects you can install.
+
+
 Sometimes these messages are straightforward to read, because they use
 commonly understood comparison operators to specify the required version
 (e.g. `<` or `>`).
@@ -252,10 +260,10 @@ the same version of `package_water`, you might consider:
 
 In the second case, pip will automatically find a version of both
 `package_coffee` and `package_tea` that depend on the same version of
-`package_water`, installing:
+`package_water`, for example:
 
 - `package_coffee 0.44.1`, which depends on `package_water 2.6.1`
-- `package_tea 4.4.3` which _also_ depends on `package_water 2.6.1`
+- `package_tea 4.4.3`, which also depends on `package_water 2.6.1`
 
 If you want to prioritize one package over another, you can add version
 specifiers to _only_ the more important package:

news/13561.doc.rst

@@ -0,0 +1 @@
+Clarified dependency resolution docs: added note on imaginary packages, fixed version mismatch, and added introduction line.