Fix a Sphinx warning. [ci skip]

Plus port the Cabal spec changelog from master.

(cherry picked from commit 21ba817e)

Cabal/doc/file-format-changelog.rst

@@ -23,3 +23,122 @@ Changes in 2.4
 
 * License fields use identifiers from SPDX License List version
   ``3.2 2018-07-10``
+
+
+``cabal-version: 2.2``
+----------------------
+
+* New :pkg-section:`common` stanzas and :pkg-field:`import`
+  pseudo-field added.
+
+* New :pkg-field:`library:virtual-modules` field added.
+
+* New :pkg-field:`cxx-sources` and :pkg-field:`cxx-options` fields
+  added for suppporting bundled foreign routines implemented in C++.
+
+* New :pkg-field:`asm-sources` and :pkg-field:`asm-options` fields
+  added for suppporting bundled foreign routines implemented in
+  assembler.
+
+* New :pkg-field:`extra-bundled-libraries` field for specifying
+  additional custom library objects to be installed.
+
+* Extended ``if`` control structure with support for ``elif`` keyword.
+
+* Changed default rules of :pkg-field:`build-type` field to infer
+  "build-type:" for "Simple"/"Custom" automatically.
+
+* :pkg-field:`license` field syntax changed to require SPDX
+  expression syntax (using SPDX license list version ``3.0 2017-12-28``).
+
+* Allow redundant leading or trailing commas in package fields (which
+  require commas) such as :pkg-field:`build-depends`.
+
+
+``cabal-version: 2.0``
+----------------------
+
+* New :pkg-field:`library:signatures` and :pkg-field:`mixins` fields
+  added for supporting Backpack_.
+
+* New :pkg-field:`build-tool-depends` field added for adding
+  build-time dependencies of executable components.
+
+* New :pkg-field:`custom-setup:autogen-modules` field added for declaring modules
+  which are generated at build time.
+
+* Support for new PVP_ caret-style version operator (``^>=``) added to
+  :pkg-field:`build-depends`.
+
+* Add support for new :pkg-section:`foreign-library` stanza.
+
+* Add support for :ref:`internal library stanzas <sublibs>`.
+
+* New CPP Macro ``CURRENT_PACKAGE_VERSION``.
+
+``cabal-version: 1.24``
+----------------------
+
+* New :pkg-section:`custom-setup` stanza and
+  :pkg-field:`custom-setup:setup-depends` field added for specifying dependencies
+  of custom ``Setup.hs`` scripts.
+
+* CPP Macros ``VERSION_$pkgname`` and ``MIN_VERSION_$pkgname`` are now
+  also generated for the current package.
+
+* New CPP Macros ``CURRENT_COMPONENT_ID`` and ``CURRENT_PACKAGE_KEY``.
+
+* New :pkg-field:`extra-framework-dirs` field added for specifying
+  extra locations to find OS X frameworks.
+
+``cabal-version: 1.22``
+----------------------
+
+* New :pkg-field:`library:reexported-modules` field.
+
+* Support for ``-none`` version constraint added to
+  :pkg-field:`build-depends`.
+
+* New :pkg-field:`license` type ``ISC`` added.
+
+``cabal-version: 1.20``
+----------------------
+
+* Add support for new :pkg-field:`license-files` field for declaring
+  multiple license documents.
+
+* New CPP Macro ``MIN_TOOL_VERSION_$buildtool``.
+
+* New :pkg-field:`license` types ``BSD2`` and ``MPL-2.0`` added.
+
+``cabal-version: 1.18``
+----------------------
+
+* Add support for new :pkg-field:`extra-doc-files` field for
+  specifying extra file assets referenced by the Haddock
+  documentation.
+
+* New :pkg-field:`license` type ``AGPL`` and ``AGPL-3`` added.
+
+* Add support for specifying a C/C++/obj-C source file in
+  :pkg-field:`executable:main-is` field.
+
+* Add ``getSysconfDir`` operation to ``Paths_`` API.
+
+``cabal-version: 1.16``
+----------------------
+
+.. todo::
+
+   this needs to be researched; there were only few changes between
+   1.12 and 1.18;
+
+``cabal-version: 1.12``
+----------------------
+
+* Change syntax of :pkg-field:`cabal-version` to support the new recommended
+  ``cabal-version: x.y`` style
+
+
+
+.. include:: references.inc