This commit makes haddock-project handle sublibraries.

The commit changes how `cabal haddock` works, changing the layout
in the `dist-newstyle` folder.  With this change `haddock` subcommand
will install `package:sublib` component in a directory `package-sublib`
under `l/sublib/doc/html/`.

Haddock no longer writes compilation files by default, so we do not need to pass
tmp dirs for `-hidir`, `-stubdir`, and `-odir` via `--optghc`. Indeed, we do not
*want* to do so, since it results in recompilation for every invocation of
Haddock via Cabal. This commit stops this from happening for haddock versions >=
2.28 (when Hi Haddock was introduced).

This commit also stops the default definition of the `__HADDOCK_VERSION__` macro
when invoking GHC through haddock. Since a very limited set of users may still
depend on this macro, we introduce the `--haddock-version-cpp` flag and
`haddock-version-cpp:` cabal.project field, which enable the definition of
the `__HADDOCK_VERSION__` macro when invoking GHC through Haddock. This will
almost guarantee recompilation during documentation generation due to the macro
definition.

This commit also renames the `--haddock-lib` flag to `--haddock-resources-dir`
(and `haddock-lib:` cabal.project field to `haddock-resources-dir:`), and adds
this flag to the users guide since it was missing an entry. This also allows us
to add this field to `cabal-install:test:integration-tests2`, since it is no
longer ambiguous with the `--lib` flag.

This commit also causes `documentation: true` or `--enable-documentation` to
imply `-haddock` for GHC.

Also, since Haddock >= 2.29 is renaming `--lib` to `--resources-dir`, this
commit switches the flag provided to Haddock using a backwards compatible
condition based on the Haddock version.

Adds a changelog entry.

This commit makes the library functions in Cabal agnostic of the working
directory. In practice, this means that we distinguish `FilePath`s
from un-interpreted `SymbolicPath`s. The latter may be paths that are
relative to the working directory, and need to be interpreted with
respect to a passed-in argument specifying the working directory,
instead of using the working directory of the current process.
See Note [Symbolic paths] in Distribution.Utils.Path.

In particular, paths in the package description now use the SymbolicPath
abstraction, which allows specifying whether they are allowed to be
absolute, and, if they are relative, what they are relative to.
For example, source files are relative to a source search directory,
data files are relative to the data directory, and doc files are
relative to the package root.

Fixes #9702

1. Working directory is not contaminated with results of the testsuite.
   Tests can be written in a more liberal way (creating/writing files
   etc).
2. The tests are more hermetic.. for example it was basically impossible
   to write a test which run outside of a project context.
3. The overall path lengths will be much shorter, which has been a
   consistent issue on windows. We can remove hacks like
   `withShorterPathForNewBuildStore`.

Fixes #9711

This patch makes `haddock-project` use `--local` option by default.
Since its the default, it is removed. Also `--gen-index`,
`--gen-contents`, `--hyperlinked-source` and `--quickjump` are removed
since they are always turned on.

Added a haddock-project test.

Also adds ellipsis to lines in *.out files.

This flag gives the user full control over the directory where the documentation is placed.

- Place "Error:" inside wrappers

  At least for the sake of the testsuite, the "Error:" prefix must be
  inside the bracket BEGIN...END that is added to the Cabal output
  during testing.

- Heuristic to not put "Error:" when already present

  This is because backpack outputs errors in an aligned way (Doc) where
  "Error:" is the introducing line.  Removing this breaks the layout.

- Remove manual "Error:" prefix where `die` adds it automatically.

- Update golden values.