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

[mpilgrem]

EDIT: To be clear, this is only about documenting Cabal (the library) under runhaskell Setup.hs build and not about the executable provided by the cabal-install package.

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.

This PR does not modify behaviour or interface

• Patches conform to the coding conventions.
• Is this a PR that fixes CI? If so, it will need to be backported to older cabal release branches (ask maintainers for directions). N/A

[mpilgrem]

I've revised the suggested documentation to refer Cabal's users to GHC's boot package semaphore-compat and follow closely the language that package (> 1.0.0) uses to describe the relevant string.

[sheaf]

Thanks, this is looking much better. I made some more suggestions; please apply as you see fit, although I would like to avoid the "system semaphore" terminology as semaphore-compat-2.0 now implements its own notion of semaphore which technically aren't system sepahores on POSIX platforms.

I will open an MR against semaphore-compat to flesh out the documentation, I hope that you will be able to take a look at it.

[sheaf]

I will open an MR against semaphore-compat to flesh out the documentation, I hope that you will be able to take a look at it.

Wow, I realise there were a lot of bugs with the Haddocks in v2 of semaphore-compat. In particular, some named chunks of documentation were not rendering properly. I apologise for that; when reviewing v2 I did try to make sure the documentation was of high quality but clearly I missed the mark. I will let you know once the MR improving documentation is up.

[sheaf]

I have put up semaphore-compat MR !11 with an overhaul of the documentation. I would appreciate if you could take a look and let me know whether it is sufficiently clear for your needs.

[sheaf]

I have put up semaphore-compat MR !11 with an overhaul of the documentation. I would appreciate if you could take a look and let me know whether it is sufficiently clear for your needs.

This has been merged and the documentation is available online on Hackage. Please let me know if there is anything else you would like to see documented.