Improve bad cabal-version error message (#9754)

See: #4899

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
(cherry picked from commit b48a6206)

Cabal-syntax/src/Distribution/PackageDescription/Parsec.hs

@@ -88,7 +88,10 @@ parseGenericPackageDescription bs = do
       Just csv -> return (Just csv)
       Nothing ->
         parseFatalFailure zeroPos $
-          "Unsupported cabal-version " ++ prettyShow v ++ ". See https://github.com/haskell/cabal/issues/4899."
+          "Unsupported cabal format version in cabal-version field: "
+            ++ prettyShow v
+            ++ ".\n"
+            ++ cabalFormatVersionsDesc
     _ -> pure Nothing
 
   case readFields' bs'' of
@@ -175,8 +178,8 @@ parseGenericPackageDescription' scannedVer lexWarnings utf8WarnPos fs = do
         -- if it were at the beginning, scanner would found it
         when (v >= CabalSpecV2_2) $
           parseFailure pos $
-            "cabal-version should be at the beginning of the file starting with spec version 2.2. "
-              ++ "See https://github.com/haskell/cabal/issues/4899"
+            "cabal-version should be at the beginning of the file starting with spec version 2.2.\n"
+              ++ cabalFormatVersionsDesc
 
         return v
 
@@ -234,6 +237,10 @@ parseGenericPackageDescription' scannedVer lexWarnings utf8WarnPos fs = do
               ++ "' must use section syntax. See the Cabal user guide for details."
     maybeWarnCabalVersion _ _ = return ()
 
+-- See #4899
+cabalFormatVersionsDesc :: String
+cabalFormatVersionsDesc = "Current cabal-version values are listed at https://cabal.readthedocs.io/en/stable/file-format-changelog.html."
+
 goSections :: CabalSpecVersion -> [Field Position] -> SectionParser ()
 goSections specVer = traverse_ process
   where

Cabal-tests/tests/ParserTests/errors/forward-compat.errors

 VERSION: Just (mkVersion [99999,9])
-forward-compat.cabal:0:0: Unsupported cabal-version 99999.9. See https://github.com/haskell/cabal/issues/4899.
+forward-compat.cabal:0:0: Unsupported cabal format version in cabal-version field: 99999.9.
+Current cabal-version values are listed at https://cabal.readthedocs.io/en/stable/file-format-changelog.html.

Cabal-tests/tests/ParserTests/errors/forward-compat2.errors

 VERSION: Just (mkVersion [2,2])
-forward-compat2.cabal:5:1: cabal-version should be at the beginning of the file starting with spec version 2.2. See https://github.com/haskell/cabal/issues/4899
+forward-compat2.cabal:5:1: cabal-version should be at the beginning of the file starting with spec version 2.2.
+Current cabal-version values are listed at https://cabal.readthedocs.io/en/stable/file-format-changelog.html.

Cabal-tests/tests/ParserTests/errors/forward-compat3.errors

 VERSION: Just (mkVersion [99999,99])
-forward-compat3.cabal:0:0: Unsupported cabal-version 99999.99. See https://github.com/haskell/cabal/issues/4899.
+forward-compat3.cabal:0:0: Unsupported cabal format version in cabal-version field: 99999.99.
+Current cabal-version values are listed at https://cabal.readthedocs.io/en/stable/file-format-changelog.html.