Is ~/.cabal/config supposed to be used when exists, in the absence of envvars and XDG folder?

[Bodigrim]

cabal/doc/config.rst

Lines 80 to 86 in ed1e4d7

	The configuration file location is determined as follows:
	1. If option ``--config-file`` is given, use it;
	2. otherwise, if ``$CABAL_CONFIG`` is set use it;
	3. otherwise, if ``$CABAL_DIR`` is set use ``$CABAL_DIR/config``;
	4. otherwise use ``config`` in ``$XDG_CONFIG_HOME/cabal``, which
	defaults to ``~/.config/cabal`` on Unix.

The documentation means that unless --config-file / $CABAL_DIR / $CABAL_CONFIG are set explicitly, ~/.cabal/config won't ever be used even if it exists and ~/.config/cabal does not. Yet, reading https://github.com/haskell/cabal/blob/master/cabal-install/src/Distribution/Client/Config.hs, I believe this is untrue. Could it please be reconciled?

Cf. haskell-CI/haskell-ci#655

[Bodigrim]

Folks, what's needed to make progress on this issue? Could you please decide what is the expected behavior? Is it a bug in documentation or a bug in implementation?

[athas]

The existence of the ~/.cabal directory is interpreted equivalent to CABAL_DIR being set. It is documented here:

cabal/doc/config.rst

Lines 63 to 67 in ed1e4d7

	For backwards compatibility, if the directory ``~/.cabal`` on
	Unix or ``%APPDATA%\cabal`` on Windows exists, and
	``$XDG_CONFIG_HOME/cabal/config`` does not exist, and
	``CABAL_DIR`` is unset, ``cabal-install`` will behave as if
	``CABAL_DIR`` was set to point at this directory.

[athas]

This backwards compatibility logic is pretty convoluted. Maybe it is better to start removing it.

[Bodigrim]

@athas so you are saying that in the passage I quoted $CABAL_DIR refers not to a vanilla $CABAL_DIR in environment, but to a $CABAL_DIR as defined a few paragraphs above. Honestly, this expects too much from a reader. Could the documentation please be brought to a state where it gives an unambigious and self-contained instruction how Cabal finds its config file?