Clarify the role of the egg URL fragment

1 files changed, 15 insertions, 9 deletions

diff --git a/docs/html/topics/vcs-support.md b/docs/html/topics/vcs-support.md
index 4c69c4e02..faa0633cc 100644
--- a/docs/html/topics/vcs-support.md
+++ b/docs/html/topics/vcs-support.md
@@ -132,17 +132,17 @@ take on the VCS requirement (not the commit itself).
 
 ## URL fragments
 
-pip looks at 2 fragments for VCS URLs:
+pip looks at the `subdirectory` fragments of VCS URLs for specifying the path to the
+Python package, when it is not in the root of the VCS directory. eg: `pkg_dir`.
 
-- `egg`: For specifying the "project name" for use in pip's dependency
-  resolution logic. e.g.: `egg=project_name`
+pip also looks at the `egg` fragment specifying the "project name". In practice the
+`egg` fragment is only required to help pip determine the VCS clone location in editable
+mode. In all other circumstances, the `egg` fragment is not necessary and its use is
+discouraged.
 
-  The `egg` fragment **should** be a bare
-  [PEP 508](https://peps.python.org/pep-0508/) project name. Anything else
-  is not guaranteed to work.
-
-- `subdirectory`: For specifying the path to the Python package, when it is not
-  in the root of the VCS directory. e.g.: `pkg_dir`
+The `egg` fragment **should** be a bare
+[PEP 508](https://peps.python.org/pep-0508/) project name. Anything else
+is not guaranteed to work.
 
 ````{admonition} Example
 If your repository layout is:
@@ -159,6 +159,12 @@ some_other_file
 Then, to install from this repository, the syntax would be:
 
 ```{pip-cli}
+$ pip install "pkg @ vcs+protocol://repo_url/#subdirectory=pkg_dir"
+```
+
+or:
+
+```{pip-cli}
 $ pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir"
 ```
 ````