Re #11498 Better document Cabal's --semaphore=SEMAPHORE option

This is follows GHC's dependency on `semaphore-compat-2.0.0` (first reflected in GHC 9.12.5-rc2).

The terminology of the dependency package now:
* introduces the concept of protocol versions for semaphores (there remains only one protocol version on Windows);
* distinguishes server semaphores and corresponding client semaphores; and
* distinguishes unversioned client semaphore names and client semaphore identifiers.

This conforms the language in Cabal's User Guide to that of the package.

Author: mpilgrem

Cabal/src/Distribution/Simple/Setup/Build.hs

@@ -151,7 +151,7 @@ buildOptions progDb showOrParseArgs =
     , option
         []
         ["semaphore"]
-        "Use the specified semaphore so GHC can compile components in parallel"
+        "Use the specified semaphore identifier so GHC can compile components in parallel"
         buildUseSemaphore
         (\v flags -> flags{buildUseSemaphore = v})
         (reqArg' "SEMAPHORE" Flag flagToList)

changelog.d/pr-12022.md

@@ -0,0 +1,10 @@
+synopsis: Better document Cabal's `--semaphore=SEMAPHORE` option in light of `semaphore-compat-2.0.0`
+packages: Cabal
+prs: #12022
+significance:
+
+description: {
+
+- Cabal's `--semaphore=SEMAPHORE` option is better documented in the user's guide and in `--help`.
+
+}

doc/setup-commands.rst

@@ -1091,8 +1091,17 @@ This command takes the following options:
 
     GHC 9.8.1 and later can act as a jobserver client, which enables two or more
     GHC processes running at once to share system resources with each other,
-    communicating via a specified system semaphore. The system semaphore is
-    identified by a name (a string).
+    communicating via a semaphore, as implemented by the
+    `semaphore-compat <https://hackage.haskell.org/package/semaphore-compat>`_
+    library.
+    
+    The expected usage is that a jobserver (the build system controlling the build,
+    e.g. ``cabal-install``, ``stack``, ``nix``, ``buck2``...) creates or obtains a semaphore using ``semaphore-compat``,
+    passing down the semaphore to jobclients in order to control the total
+    amount of parallelism. This is done by passing the corresponding semaphore identifier to ``Cabal`` via the ``--semaphore`` flag.
+    
+    Refer to `semaphore-compat <https://hackage.haskell.org/package/semaphore-compat>`_
+    for more details.
 
     This option causes Cabal to control parallelism by using the specified
     system semaphore.