Clarify the role of the egg URL fragment

Author: sbidoul

docs/html/topics/vcs-support.md

@@ -136,12 +136,13 @@ option.
 
 ## URL fragments
 
-pip looks at 2 fragments for VCS URLs:
+pip looks at the `subdirectory` fragments for 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. eg: `egg=project_name`
-- `subdirectory`: For specifying the path to the Python package, when it is not
-  in the root of the VCS directory. eg: `pkg_dir`
+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 circumstance the `egg` fragment is not necessary and its use is
+discouraged.
 
 ````{admonition} Example
 If your repository layout is:
@@ -157,6 +158,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"
 ```

news/11676.doc.rst

@@ -0,0 +1,2 @@
+Clarify that the egg URL fragment is only necessary for editable VCS installs, and
+otherwise not necessary anymore.