Move top-level VCS fields reference page content back to description pages

[malteneuss]

A small improvement of a step of the user guide improvement initiative #9214:

I removed the top-level VCS fields reference page and moved its content into the .cabal and cabal.project reference pages with a bit of duplication. With more content coming to the Cabal documentation, the top-level space is precious and a short description of a technical detail doesn't feel to pull its weight.

• 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).

[geekosaur]

I am not sure I agree with removing the VCS fields section entirely, but I do agree it is a poor fit. This may mean we want to split the user manual from a technical reference, with links thereto as needed.

[malteneuss]

The content of that section isn't gone. It just now lives in the two reference pages with a bit of duplication, which i think is fine, because the use cases are quite separate. A nice guide how to fill those attribute is also still present.

[philderbeast]

Would it be possible to avoid the duplication and remove the version-control-fields from the table of contents?

One way to do this would be:

$ git diff
diff --git a/doc/index.rst b/doc/index.rst
index 0b5407e85..0791253d8 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -27,7 +27,6 @@ Welcome to the Cabal User Guide
 
    cabal-package-description-file
    cabal-project-description-file
-   version-control-fields
    cabal-config-and-commands
    external-commands
    setup-commands
diff --git a/doc/version-control-fields.rst b/doc/version-control-fields.rst
index 739905d4b..33ba9046f 100644
--- a/doc/version-control-fields.rst
+++ b/doc/version-control-fields.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Version Control System Fields
 =============================

[malteneuss]

I would like to avoid having a page that is basically only reachable via a an anchor link deep in the reference pages, and which creates a layer of indirection to read the full reference content. This small amount of duplication in the field descriptions shouldn't be a problem as it's quite stable; before your improvements those sections only ever where touched 2x for tiny changes in 4 years.

[philderbeast]

Would it be possible to avoid the duplication

What about using other means to avoid duplication such as the include directive?

[ulysses4ever]

Thanks for the contribution! I definitely feel that it's the right direction. I only will be able to properly review this in the matter of days (due to the ongoing release procedures and last minute issues related to this like #10548).