Deduplicate documentation of cabal commands

[BinderDavid]

Fixes #9216

Documentation of various cabal-install commands is split between section 5.2 and section 6.2.
This PR was written under the assumption that the documentation of these subcommands is in the wrong place in 6.2, which otherwise only contains documentation about the .cabal file format.

(Andreas: rendering of this PR at:)

• 5.2 commands: https://cabal--9217.org.readthedocs.build/en/9217/cabal-commands.html
• 6.2 package descriptions: https://cabal--9217.org.readthedocs.build/en/9217/cabal-package.html#package-descriptions

[ffaf1]

I understand that this is more general, but we do not support every VCS.

[BinderDavid]

The cabal get command, and especially the -s option was documented twice. The formulation in section 5.2 used the explicit list of VCS's and the formulation in 6.2 used the one that I have used here with "using the appropriate version control system". When I combined them I picked the latter version, but I can also use the alternative. I will add a commit.

Edit: a282425

[ffaf1]

Are you sure that all this block contains no useful information? I am checking current manual for repl

[BinderDavid]

I do agree that this is useful information, but I think it is not in the correct place to write it down. It looks to me that section 6.2 wants to be the reference section for all the things that can be written in the package description/.cabal file. For some sections (such as executable, testsuite and benchmark) of the cabal file it makes sense to refer to the documentation of cabal run cabal test and cabal bench, because these commands are directly related to the subsections. But commands such as cabal repl and cabal get which were also documented in section 6.2 do not correspond to a specific section of the cabal file, but to general workflows with cabal-install instead. A command such as cabal repl should be documented in the command reference section, and maybe also in the sections 1+2+3 which describe general cabal workflows.

[ffaf1]

I agree with the spirit of the patch, but I would like to have references from 6.2.x to the appropriate command doc. By skimming the patch it seems some got lost in rewrite (e.g. repl). If I am wrong, please correct me!

[andreasabel]

Thanks! LGTM.

[ffaf1]

good

[BinderDavid]

The failing test seemed to be flaky. I did 2 force pushes to restart the pipeline.

[BinderDavid]

@Mergifyio refresh

[mergify]

refresh

✅ Pull request refreshed