Why are cabal-install commands in the docs prefixed with v2- ?

[Martinsos]

In the docs, at https://cabal.readthedocs.io/en/latest/cabal-commands.html# , all the commands are prefixed with v2- .
However, in the getting started guide at https://cabal.readthedocs.io/en/latest/getting-started.html, none of them are prefixed with v2- .

I understand that there are commands prefixed with nothing (install), commands prefixed with v1- (v1-install), and then there are commands prefixed with v2- (v2-install), and that this was due to change of behaviour between cabal 1 and 2, but that these days v1 should not be used while v2 is equal as having no prefix.

If that is so, I guess all mentions of v2 should be removed from the docs, at least from prominent locations and instead there could be a piece of docs that explains no prefix vs v1 vs v2?

[Martinsos]

Another thing -> is term cabal-install also outdated?

I am looking at getting started and at introduction (https://cabal.readthedocs.io/en/latest/intro.html), and while difference between cabal CLI, cabal library and cabal spec is explained, no where is mentioned that cabal CLI is also called cabal-install. From what I am getting, cabal-install is an old name that is not used any more?

Should we replace "cabal-install` with just "cabal" or "cabal CLI" if more context is needed?

[Mikolaj]

Hi @Martinsos. Thank you for you questions. I hope many of the will be answered in the upcoming https://github.com/haskell/cabal-userguide (CC @JonathanLorimer).

However, let me try to summarize: v1- will be there until cabal has satisfactory workflows that replace the v1- commands. v2- is equal to no prefix. I think it would work to explain once that v2- (as seen on the net) is no prefix and remove all v2- prefixes from the the whole repo from each file ever.

cabal-install is the correct name of Hackage package cabal-install which is the client app. OTOH, Cabal is a library, used by and shipped, e.g., in GHC. cabal-install uses the Cabal library (and others, Cabal is being split up for some time now), The exe of the cabal-install package is called cabal for short.

[Martinsos]

I didn't know about the cabal-userguide, looking forward to it!

Explaining v2- vs no prefix vs v1- at one place and removing all v2- prefixes from docs -> makes sense!

Would you like me to take a stab at this at some point, maybe create a PR to get this going?

Regarding cabal-install -> I do understand the difference between cabal CLI (cabal-install), cabal spec and cabal library (Cabal). What I found confusing though in the current docs that in getting-started and in introduction, there is no mention of cabal-install at all. They way I learned about the term cabal-install was from other sources (SO, reddit, ...).
But then later, cabal-install is suddenly mentioned in the docs, for example it is in the title of chapter 6, "cabal-install commands".

I would suggest picking one of the approaches:

1. Introducing term cabal-install in the getting-started or introduction, so that later when it is mentioned it is clear what it is.
2. Completely removing the term cabal-install from the docs and instead referring to it differently - either as only cabal or as cabal CLI when it is not clear from the context that we are talking about the CLI.

[Mikolaj]

@Martinsos, yes, please getting the v2- mess sorted out would be very useful.

Regarding cabal-install terminology, it's quite nasty. Would you perhaps observe how @JonathanLorimer and contributors do that in cabal-userguide and/or ask them how they plan to do that?

[fgaz]

option 1 has to be done anyway since other sources will mention it, and one has to type it to upgrade cabal

but option 2 can be done too

[philderbeast]

I didn't know about the cabal-userguide, looking forward to it!

@Martinsos, the current and latest cabal user guides are online at https://cabal.readthedocs.io/ and https://cabal.readthedocs.io/en/latest/. The former is for cabal-3.6 at the time I'm writing this.

[Mikolaj]

There is also https://github.com/haskell/cabal-userguide, but it seems it stalled recently.

[jneira]

related pr: #6703

[ulysses4ever]

Fixed in #8020.