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

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

changelog.d/pr-12021.md

@@ -0,0 +1,10 @@
+synopsis: Better document, in-app and online, Cabal's `--semaphore=SEMAPHORE` option, post `semaphore-compat-2.0.0` support
+packages: Cabal
+prs: #12021
+significance:
+
+description: {
+
+- Cabal's `--semaphore=SEMAPHORE` option is better documented online and on `--help`.
+
+}

doc/setup-commands.rst

@@ -1091,11 +1091,14 @@ 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 specified system client semaphore. A GHC version
+    supports a specific protocol version for semaphores. On non-Windows
+    operating systems, more than one protocol version exists. The system client
+    semaphore is identified by a string, being a bare name (for protocol
+    version 1) or a versioned name (for subsequent protocol versions).
 
     This option causes Cabal to control parallelism by using the specified
-    system semaphore.
+    system client semaphore.
 
 .. _setup-haddock: