Outdated cabal documentation

[tomjaguarpaw]

Several of the links on this page https://www.haskell.org/cabal/ are dead
https://www.haskell.org/cabal/release/cabal-latest/doc/API/Cabal/
or refer to old versions:
https://wiki.haskell.org/Upgrading_packages

https://mail.haskell.org/pipermail/haskell-cafe/2020-December/133139.html

[tomjaguarpaw]

Outdated or dead links on The Haskell Cabal outdated links

• "ghcup" links to https://github.com/haskell/ghcup but should be https://gitlab.haskell.org/haskell/ghcup-hs
  • Use evergreen link for GHC download haskell/cabal-website#16 [EDIT: merged]
• "The GHC download docs" refers to https://www.haskell.org/ghc/download_ghc_8_4_4.html. Should probably be an evergreen link.
  • Update ghcup link haskell/cabal-website#17 [EDIT: merged]
• "How to install a cabal package" links to https://wiki.haskell.org/Cabal/How_to_install_a_Cabal_package which is outdated. This link should probably be omitted.
  • Remove link to severely outdated Haskell Wiki page haskell/cabal-website#20 [EDIT: merged]
• "FAQ and trouble shooting" links to https://www.haskell.org/cabal/FAQ.html which is severely outdated
• "Cabal-the-library API documentation" 404s https://www.haskell.org/cabal/release/cabal-latest/doc/API/Cabal/
  • Remove dead link haskell/cabal-website#18 [EDIT: merged]
• "Updating packages to work with recent Cabal and GHC versions" links to https://wiki.haskell.org/Upgrading_packages and is pretty outdated
• "Old stuff" links to https://www.haskell.org/cabal/old.html. Why? Just remove it.
  • Remove unhelpful link haskell/cabal-website#19 [EDIT: merged]
• "Applications and libraries" links to https://wiki.haskell.org/Applications_and_libraries which is verging on unmaintained

Also

• The section about --force-reinstalls is only relevant for very old cabals
  • Make it clear that --force-reinstalls is a historical artefact haskell/cabal-website#21 [EDIT: probably not a valid issue]

(I have a feeling I typed this list somewhere else, but perhaps forgot to click the button to post it)

[tomjaguarpaw]

#47 addresses the FAQ specifically

[tomjaguarpaw]

Waiting for: knowledge of who the owner of the cabal/ subsite is.

Next action: Make a PR to https://github.com/haskell/cabal-website

Waiting for: Responses to PRs (see above)

Next action: Make more PRs from https://github.com/tomjaguarpaw/cabal-website (may require rebasing)

[lspitzner]

I'd like to add regarding https://cabal.readthedocs.io:

• that the default version of is 3.4, which is not released. Sphinx etc. should have a concept of pre-release versions (right?)
• It calls itself the "Cabal User Guide", but we do have a) Cabal the library b) cabal-install c) cabal-the-specification. What is the user guide about? It seems at least b) and c). I think this should be mentioned at the front, and then the rest should be structured accordingly: So that the information about any cabal-install usage is in a separate chapter. (Note that yes, there is a cabal-install chapter, but there also is a cabal.project chapter which arguably is a feature of cabal-install. Also note that the very first chapter is only/at most interesting to users of cabal-install.)
• And a changelog included in the documentation would be neat.

I will refer to the 3.4 chapter structure here

• The introduction is the second chapter (?) It seems like you are supposed to run your first cabal init before you know what cabal is.
• chapter 4.1 is another quickstart (?)
• chapter 12.2 (interface stability) seems like a complete mess. And does not discuss the bit most important to end-users: The stability of the cabal-install commandline. Which was broken horribly in the 3.0 transition, just saying.

Or in general: The default experience you get when navigating to https://cabal.readthedocs.io is kind of a mess, even if it is not as outdated as the Haskell.org versions..

[tomjaguarpaw]

Thanks Lennart, those observations are really useful. I've created a new issue for them: #61

[tomjaguarpaw]

Most of these have been fixed. The one that hasn't been fixed has been given its own issue: #106