manual: Document that the path part should be removed from hosts

docs/forge.org

@@ -313,11 +313,14 @@ the final closing parenthesis and typing ~C-x C-e~ (~eval-last-sexp~).
 Next add a line like the following to the chosen file:
 
 #+begin_src example
-  machine gitlab.com/api/v4 login USERNAME^forge password TOKEN
+  machine gitlab.com login USERNAME^forge password TOKEN
 #+end_src
 
-- The value of ~machine~ must be ~gitlab.com/api/v4~.  Variations of this
-  won't work.
+- The value of ~machine~ should be ~gitlab.com~.  For historic reasons
+  ~gitlab.com~ is also supported.
+
+- Note that if you instead use the ~auth-source-pass~ backend, then you
+  *must* use ~gitlab.com~ as ~host~.
 
 - USERNAME must be the same as the value used for the ~gitlab.user~ Git
   variable above.  You *must* append ~^forge~ to that, without any space
@@ -433,10 +436,20 @@ Next add a line like the following to the chosen file:
   machine APIHOST login USERNAME^forge password TOKEN
 #+end_src
 
-- APIHOST must be the same as the second element of the entry we added
-  to ~forge-alist~.  In the above example that would be
-  ~example.com/api/v4~.  Do *not* instead use GITHOST or INSTANCE-ID (aka
-  WEBHOST).
+- APIHOST must be either the same as the second element of the entry
+  we added to ~forge-alist~, or that element with the path suffix
+  removed.  For example, if the APIHOST, specified in an ~forge-alist~
+  entry, is ~example.com/api/v4~, then you can use ~example.com/api/v4~ or
+  ~example.com~.
+
+  Historically only the former was supported, but that was a design
+  mistake, which we are now stuck with, and using just ~example.com~ as
+  APIHOST in ~~/.authsource~ is now recommended.  For the time being, in
+  ~forge-alist~ you must still always use ~example.com/api/v4~ as APIHOST.
+
+  If you instead use the ~auth-source-pass~ backend, then you *must* use
+  ~example.com~ as the value of ~host~.  Using ~example.com/api/v4~ does not
+  work with that backend.
 
 - USERNAME must be the same username you used above as the value of
   the Git variable.  You *must* append ~^forge~ to that, without any space

docs/forge.texi

@@ -399,13 +399,17 @@ the final closing parenthesis and typing @code{C-x C-e} (@code{eval-last-sexp}).
 Next add a line like the following to the chosen file:
 
 @example
-machine gitlab.com/api/v4 login USERNAME^forge password TOKEN
+machine gitlab.com login USERNAME^forge password TOKEN
 @end example
 
 @itemize
 @item
-The value of @code{machine} must be @code{gitlab.com/api/v4}.  Variations of this
-won't work.
+The value of @code{machine} should be @code{gitlab.com}.  For historic reasons
+@code{gitlab.com} is also supported.
+
+@item
+Note that if you instead use the @code{auth-source-pass} backend, then you
+@strong{must} use @code{gitlab.com} as @code{host}.
 
 @item
 USERNAME must be the same as the value used for the @code{gitlab.user} Git
@@ -521,10 +525,20 @@ machine APIHOST login USERNAME^forge password TOKEN
 
 @itemize
 @item
-APIHOST must be the same as the second element of the entry we added
-to @code{forge-alist}.  In the above example that would be
-@code{example.com/api/v4}.  Do @strong{not} instead use GITHOST or INSTANCE-ID (aka
-WEBHOST).
+APIHOST must be either the same as the second element of the entry
+we added to @code{forge-alist}, or that element with the path suffix
+removed.  For example, if the APIHOST, specified in an @code{forge-alist}
+entry, is @code{example.com/api/v4}, then you can use @code{example.com/api/v4} or
+@code{example.com}.
+
+Historically only the former was supported, but that was a design
+mistake, which we are now stuck with, and using just @code{example.com} as
+APIHOST in @code{~/.authsource} is now recommended.  For the time being, in
+@code{forge-alist} you must still always use @code{example.com/api/v4} as APIHOST@.
+
+If you instead use the @code{auth-source-pass} backend, then you @strong{must} use
+@code{example.com} as the value of @code{host}.  Using @code{example.com/api/v4} does not
+work with that backend.
 
 @item
 USERNAME must be the same username you used above as the value of

lisp/forge.el

@@ -14,7 +14,7 @@
 ;;     (closql "2.1.0")
 ;;     (dash "2.19.1")
 ;;     (emacsql "4.1.0")
-;;     (ghub "4.2.0")
+;;     (ghub "4.2.1")
 ;;     (let-alist "1.0.6")
 ;;     (magit "4.2.1")
 ;;     (markdown-mode "2.6")