Deprecate hscolour, add hyperlink-source synonyms

* warning in hscolour's description
* warning when hscolour is run
* added 'hyperlinked-source' (the name Haddock has for the option) as a
  synonym for 'hyperlink-source'

Follows up comments from #5140.

Author: harpocrates

Cabal/ChangeLog.md

@@ -37,6 +37,7 @@
   * Options listed in `ghc-options`, `cc-options`, `ld-options`,
     `cxx-options`, `cpp-options` are not deduplicated anymore
     ([#4449](https://github.com/haskell/cabal/issues/4449)).
+  * Deprecated `cabal hscolour` in favour of `cabal haddock --hyperlink-source` ([#5236](https://github.com/haskell/cabal/pull/5236/)).
 
 ----
 

Cabal/Distribution/Simple/Haddock.hs

@@ -751,6 +751,11 @@ hscolour' onNoHsColour haddockTarget pkg_descr lbi suffixes flags =
   where
     go :: ConfiguredProgram -> IO ()
     go hscolourProg = do
+      warn verbosity $
+        "the 'cabal hscolour' command is deprecated in favour of 'cabal " ++
+        "haddock --hyperlink-source' and will be removed in the next major " ++
+        "release."
+
       setupMessage verbosity "Running hscolour for" (packageId pkg_descr)
       createDirectoryIfMissingVerbose verbosity True $
         hscolourPref haddockTarget distPref pkg_descr

Cabal/Distribution/Simple/Setup.hs

@@ -1221,7 +1221,8 @@ hscolourCommand = CommandUI
   , commandSynopsis     =
       "Generate HsColour colourised code, in HTML format."
   , commandDescription  = Just (\_ -> "Requires the hscolour program.\n")
-  , commandNotes        = Nothing
+  , commandNotes        = Just $ \_ ->
+      "Deprecated in favour of 'cabal haddock --hyperlink-source'."
   , commandUsage        = \pname ->
       "Usage: " ++ pname ++ " hscolour [FLAGS]\n"
   , commandDefaultFlags = defaultHscolourFlags
@@ -1513,7 +1514,7 @@ haddockOptions showOrParseArgs =
    haddockCss (\v flags -> flags { haddockCss = v })
    (reqArgFlag "PATH")
 
-  ,option "" ["hyperlink-source","hyperlink-sources"]
+  ,option "" ["hyperlink-source","hyperlink-sources","hyperlinked-source"]
    "Hyperlink the documentation to the source code"
    haddockLinkedSource (\v flags -> flags { haddockLinkedSource = v })
    trueArg