Duplicate VCS content

- Break VCS sections into files for inclusion
- Add VCS kind content to package and project
- Add VCS location content to package and project
- Add VCS branch content to package and project
- Add VCS kind content to package and project
- Add VCS subdir content to package and project
- Put "is required" first for CVS field
- Move VCS out of the "Cabal Reference"
- Rename include files to vcs/*
- Revert "Move VCS out of the "Cabal Reference""

Author: philderbeast

doc/cabal-package-description-file.rst

@@ -2747,33 +2747,42 @@ The :ref:`VCS fields<vcs-fields>` of ``source-repository`` are:
 
     This field is required.
 
+    .. include:: vcs/kind.rst
+
 .. pkg-field:: location: VCS location
 
     This field is required.
 
-.. pkg-field:: module: token
+    .. include:: vcs/location.rst
 
-    CVS requires a named module, as each CVS server can host multiple
-    named repositories.
+.. pkg-field:: module: token
 
     This field is required for the CVS repository type and should not be
     used otherwise.
 
+    CVS requires a named module, as each CVS server can host multiple
+    named repositories.
+
 .. pkg-field:: branch: VCS branch
 
     This field is optional.
 
+    .. include:: vcs/branch.rst
+
 .. pkg-field:: tag: VCS tag
 
     This field is required for the ``this`` repository kind.
 
     This might be used to indicate what sources to get if someone needs to fix a
     bug in an older branch that is no longer an active head branch.
 
+    .. include:: vcs/tag.rst
+
 .. pkg-field:: subdir: VCS subdirectory
 
     This field is optional but, if given, specifies a single subdirectory.
 
+    .. include:: vcs/subdir.rst
 
 .. _setup-hooks:
 

doc/cabal-project-description-file.rst

@@ -269,23 +269,33 @@ The :ref:`VCS fields<vcs-fields>` of ``source-repository-package`` are:
 
     This field is required.
 
+    .. include:: vcs/kind.rst
+
 .. cfg-field:: location: VCS location
 
     This field is required.
 
+    .. include:: vcs/location.rst
+
 .. cfg-field:: branch: VCS branch
 
     This field is optional.
 
+    .. include:: vcs/branch.rst
+
 .. cfg-field:: tag: VCS tag
 
     This field is optional.
 
+    .. include:: vcs/tag.rst
+
 .. cfg-field:: subdir: VCS subdirectory list
 
     Look in one or more subdirectories of the repository for cabal files, rather
     than the root. This field is optional.
 
+    .. include:: vcs/subdir.rst
+
 .. cfg-field:: post-checkout-command: command
 
     Run command in the checked out repository, prior sdisting.

doc/vcs/branch.rst

@@ -0,0 +1,8 @@
+..
+  VCS branch
+
+Many source control systems support the notion of a branch, as a distinct
+concept from having repositories in separate locations. For example CVS, SVN and
+git use branches while darcs uses different locations for different branches. If
+you need to specify a branch to identify a your repository then specify it in
+this field.

doc/vcs/fields.rst

@@ -0,0 +1,34 @@
+..
+  VCS common fields
+
+Most of the version control system (VCS) fields types are common to both
+``source-repository`` and ``source-repository-package`` stanzas.
+
+.. list-table::
+    :header-rows: 1
+    :widths: 30 30 40
+
+    * - Field Name
+      - source-repository (head|this)
+      - source-repository-package
+    * - type
+      - [x]
+      - [x]
+    * - location
+      - [x]
+      - [x]
+    * - branch
+      - [x]
+      - [x]
+    * - tag
+      - [x]
+      - [x]
+    * - subdir
+      - [x] (0 or 1)
+      - [x] (0 or 1 for each dependency)
+    * - module (CVS only)
+      - [x]
+      - [_]
+    * - post-checkout-command
+      - [_]
+      - [x]

doc/vcs/kind.rst

@@ -0,0 +1,19 @@
+..
+  VCS kind
+
+Cabal supports specifying different information for various common source
+control systems. This is the name of the source control system used for a
+repository. The currently recognised types are:
+
+-  ``darcs``
+-  ``git``
+-  ``svn``
+-  ``cvs``
+-  ``mercurial`` (or alias ``hg``)
+-  ``bazaar`` (or alias ``bzr``)
+-  ``arch``
+-  ``monotone``
+-  ``pijul``
+
+The VCS kind will determine what other fields are appropriate to specify for a
+particular version control system.

doc/vcs/location.rst

@@ -0,0 +1,9 @@
+..
+  VCS location
+
+The location of the repository, usually a URL but the exact form of this field
+depends on the repository type. For example:
+
+-  for Darcs: ``http://code.haskell.org/foo/``
+-  for Git: ``https://github.com/foo/bar.git``
+-  for CVS: ``[email protected]:/cvs``

doc/vcs/subdir.rst

@@ -0,0 +1,11 @@
+..
+  VCS subdirectory
+
+A field of this type is always optional because it defaults to empty, which
+corresponds to the root directory of the repository and is the same as
+specifying ``.`` explicitly.
+
+Some projects put the sources for multiple packages inside a single VCS
+repository. This field lets you specify the relative path from the root of the
+repository to the top directory for the package, i.e. the directory containing
+the package's ``.cabal`` file.

doc/vcs/tag.rst

@@ -0,0 +1,5 @@
+..
+  VCS tag
+
+A tag identifies a particular state of a source repository.  The exact form of
+the tag depends on the repository type.

doc/version-control-fields.rst

@@ -3,93 +3,31 @@ Version Control System Fields
 
 .. _vcs-fields:
 
-Most of the version control system (VCS) fields types are common to both
-``source-repository`` and ``source-repository-package`` stanzas.
-
-.. list-table::
-    :header-rows: 1
-    :widths: 30 30 40
-
-    * - Field Name
-      - source-repository (head|this)
-      - source-repository-package
-    * - type
-      - [x]
-      - [x]
-    * - location
-      - [x]
-      - [x]
-    * - branch
-      - [x]
-      - [x]
-    * - tag
-      - [x]
-      - [x]
-    * - subdir
-      - [x] (0 or 1)
-      - [x] (0 or 1 for each dependency)
-    * - module (CVS only)
-      - [x]
-      - [_]
-    * - post-checkout-command
-      - [_]
-      - [x]
+.. include:: vcs/fields.rst
 
 .. _vcs-kind:
 
 VCS kind
 ^^^^^^^^
 
-Cabal supports specifying different information for various common source
-control systems. This is the name of the source control system used for a
-repository. The currently recognised types are:
-
--  ``darcs``
--  ``git``
--  ``svn``
--  ``cvs``
--  ``mercurial`` (or alias ``hg``)
--  ``bazaar`` (or alias ``bzr``)
--  ``arch``
--  ``monotone``
--  ``pijul``
-
-The VCS kind will determine what other fields are appropriate to specify for a
-particular version control system.
+.. include:: vcs/kind.rst
 
 VCS location
 ^^^^^^^^^^^^
 
-The location of the repository, usually a URL but the exact form of this field
-depends on the repository type. For example:
-
--  for Darcs: ``http://code.haskell.org/foo/``
--  for Git: ``https://github.com/foo/bar.git``
--  for CVS: ``[email protected]:/cvs``
+.. include:: vcs/location.rst
 
 VCS branch
 ^^^^^^^^^^
 
-Many source control systems support the notion of a branch, as a distinct
-concept from having repositories in separate locations. For example CVS, SVN and
-git use branches while darcs uses different locations for different branches. If
-you need to specify a branch to identify a your repository then specify it in
-this field.
+.. include:: vcs/branch.rst
 
 VCS tag
 ^^^^^^^
 
-A tag identifies a particular state of a source repository.  The exact form of
-the tag depends on the repository type.
+.. include:: vcs/tag.rst
 
 VCS subdirectory
 ^^^^^^^^^^^^^^^^
 
-A field of this type is always optional because it defaults to empty, which
-corresponds to the root directory of the repository and is the same as
-specifying ``.`` explicitly.
-
-Some projects put the sources for multiple packages inside a single VCS
-repository. This field lets you specify the relative path from the root of the
-repository to the top directory for the package, i.e. the directory containing
-the package's ``.cabal`` file.
+.. include:: vcs/subdir.rst