"Controlling flag assignments" section of users guide appears not to exist

[bgamari]

Describe the bug
In the "Resolution of Conditions and Flags" section of the users guide there is a link with the text "control these in several ways". The target of this link is a page which makes no mention of flags.

To Reproduce
Follow the indicated link.

EDIT (@andreasabel): Here is the link:

cabal/doc/cabal-package.rst

Line 2511 in 2e64e23

ways <installing-packages.html#controlling-flag-assignments>`__. The

[Mikolaj]

It seems the dangling link is there at least since a commit ""This is the result of using pandoc with default settings to convert the existing .markdown files to .rst files". Presumably markdown auto-generated such anchors from section names and pandoc does not (or did not).

@andreasabel: why does our CI script that validates the docs not error out at such dangling links?

[Mikolaj]

To clarify, the link is really dangling, not just off-topic, because no such anchor exists and readthedocs just falls back to the start of the chapter.

[andreasabel]

@andreasabel: why does our CI script that validates the docs not error out at such dangling links?

Good question, I need to investigate this. Currently we run sphinx-build with these options, which should do the right thing:

• -n
  Run in nit-picky mode. Currently, this generates warnings for all missing references. See the config value nitpick_ignore for a way to exclude some references as “known missing”.

• -W
  Turn warnings into errors. This means that the build stops at the first warning and sphinx-build exits with exit status 1.

• --keep-going

  With -W option, keep going processing when getting warnings to the end of build, and sphinx-build exits with exit status 1.

[andreasabel]

The link in question is to a html file generated by sphinx. It seems that such links are not checked by sphinx.
This is anyway not the recommended way to link, as it breaks e.g. for the PDF version. Here is the docs on how to link: https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html
We should replace all such html links by proper cross-references.

Grep found these relative html links:

./cabal-package.rst�191:`Distribution.Simple <../release/cabal-latest/doc/API/Cabal/Distribution-Simple.html>`__).
./cabal-package.rst�415:    `BuildType <../release/cabal-latest/doc/API/Cabal/Distribution-PackageDescription.html#t:BuildType>`__
./cabal-package.rst�1797:    `Extension <../release/cabal-latest/doc/API/Cabal/Language-Haskell-Extension.html#t:Extension>`__
./cabal-package.rst�2511:      ways <installing-packages.html#controlling-flag-assignments>`__. The
./cabal-package.rst�2625:ways <installing-packages.html#controlling-flag-assignments>`__. If the
./cabal-package.rst�3091:independence <setup-commands.html#prefix-independence>`__). To
./cabal-package.rst�3368:   `Distribution.Simple <../release/cabal-latest/doc/API/Cabal/Distribution-Simple.html>`__
./cabal-package.rst�3380:   `Distribution.Make <../release/cabal-latest/doc/API/Cabal/Distribution-Make.html>`__,
./cabal-package.rst�3421:   packages <installing-packages.html>`__, and you may use the Cabal
./nix-local-build.rst�8:out `developing packages <developing-packages.html>`__ for
./intro.rst�106:packages <installing-packages.html>`__.
./intro.rst�128:section on `developing packages <developing-packages.html>`__.
./developing-packages.rst�5:    If this is your first time using `cabal` you should check out the `Getting Started guide <getting-started.html>`__.
./cabal-project.rst�725:    parameters <developing-packages.html#system-dependent-parameters>`__.
./getting-started.rst�176:Cabal on the `introduction <intro.html>`__ page.

Links like ../release/cabal-latest/doc/API/Cabal/Distribution-Simple.html are broken as well on readthedocs, e.g. https://cabal.readthedocs.io/en/release/cabal-latest/doc/API/Cabal/Distribution-Simple.html.
I do not know how these links are supposed to work and when they worked last time. They were added in 99d48fa#diff-76f65d84a3d81655bc7cc21bb9affd50715ebe7f10458f760fe5af9d70f9d956R630 by @hvr 5 years ago.
What should we do about these?
(Link to hackage instead? But the links will then be broken by uploading a new version to hackage, or we have to version them in the .rst sources.)