Add instance Ord for Field, FieldLine, SectionArg and Name

Restructure user guide into top-level guides, reference and explanation parts

The goal is for users to easier find pages for typical problems through search engines and page navigation.
- The top-level layout is based on the popular documentation structure by https://documentation.divio.com/ to give a
   clear structure to users and future documentation contributors:
  * Guides: Present a solution to a single, atomic, typical user problem.
  * Reference: Describe user API (CLI fields, syntax etc) with technical rigour and completeness.
  * Explanation: Discuss background information, scope, design decisions etc.
- Move existing documentation roughly into these categories with minimal editing as the basis for further editing.
- Rename guide titles to mention how-to for improving SEO.
- Rename some files to improve SEO since that name becomes part of the URL (often called slug).
  Important page keywords should appear in the slug as well to make pages rank higher in search engines.

Use the newer haskell-actions organisation

* Revert #3639 (Don't pass -package-db and -package flags to --abi-hash)

With ghc>=9.6 `ghc --abi-hash` initialises the plugins so it will fail
if a cabal file specifies `ghc-options: -fplugin=Foo`.

Closes: #9375

* Also revert in GHC.hs

---------

Co-authored-by: Hamish Mackenzie <Hamish.K.Mackenzie@gmail.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

update GH validate workflow to 9.2.8, 9.4.7, 9.6.3

Bump dependencies for GHC 9.8

[cabal-7825] Implement external command system

Fix #2349 and #7825

Have hlint ignore CmmSourcesExe Demo

Avoid double space in "Executing install plan ..."

* doc: render math with HTML to make it selectable (fix #8453)

* Update doc/conf.py

Co-authored-by: Bryan Richter <bryan@haskell.foundation>

---------

Co-authored-by: Bryan Richter <bryan@haskell.foundation>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

Fix markdown syntax in changelog

Create Cabal-3.10.2.1 release notes

Ignore because it warns about missing MachDeps.h

Update format.yml

Bump haskell-actions/run-fourmolu to v9 and fix fourmolu version to 0.12.0.0. This makes explicit which version is used and avoids unexpected changes later on.

The current version v8 of run-fourmolu uses fourmolu-0.12.0.0 so this should not produce any change in formatting now.

Simplify to avoid a typo

Bump urllib3 from 2.0.6 to 2.0.7 in /doc

Not a mistake in fixing the old

Bumps [urllib3](https://github.com/urllib3/urllib3) from 2.0.6 to 2.0.7.
- [Release notes](https://github.com/urllib3/urllib3/releases)
- [Changelog](https://github.com/urllib3/urllib3/blob/main/CHANGES.rst)
- [Commits](https://github.com/urllib3/urllib3/compare/2.0.6...2.0.7

)

---
updated-dependencies:
- dependency-name: urllib3
  dependency-type: direct:production
...

Signed-off-by: dependabot[bot] <support@github.com>

Make “sublibrary” standard terminology in docs

Substitute “internal library” occourrences with “sublibrary”.

* Use ProjectFlags to define CleanCmd

The nearly identical PR for #7439 was used as a guide for this PR.
The point of this PR is to reduce the duplication of project flag
handling.

Co-authored-by: Jean-Paul Calderone <exarkun@twistedmatrix.com>

* remove duplicate support for project-dir

* switch use of NamedFieldPuns to RecordWildCards

---------

Co-authored-by: Jean-Paul Calderone <exarkun@twistedmatrix.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

* Rewrite installation section of getting-started.rst

* Rephrase creating a package documentation section

* Length align titles in getting-started.rst

* Fix length alignment in getting-started.rst

* Update doc/getting-started.rst

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

* Update getting-started.rst

* Update doc/getting-started.rst

Co-authored-by: brandon s allbery kf8nh <allbery.b@gmail.com>

* Align package and script example in getting-started.rst

* Align example package versions in getting-started.rst

* Update doc/getting-started.rst

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

* Update doc/getting-started.rst

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

* Update doc/getting-started.rst

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

* Update doc/getting-started.rst

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

* Update doc/getting-started.rst

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

* Update doc/getting-started.rst

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

* Update doc/getting-started.rst

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

* Update doc/getting-started.rst

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

* Added review suggestions

* Update doc/getting-started.rst

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

* Update doc/getting-started.rst

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

* Update doc/getting-started.rst

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

* Update doc/getting-started.rst

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

* Update doc/getting-started.rst

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

* Update doc/getting-started.rst

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

* Update doc/getting-started.rst

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

* Update doc/getting-started.rst

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

* Update doc/getting-started.rst

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>

* Update getting-started.rst

Reflow sentence to trigger CI

* Update getting-started.rst

* Update doc/getting-started.rst

---------

Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>
Co-authored-by: brandon s allbery kf8nh <allbery.b@gmail.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

Add 9 and revise 6 comments.

As part of improving DX for new contributors, I have added
or revised comments to the Cabal/Distribution.Simple.Flag file,
giving it 100% comment coverage, as well as pointing out
its isomorphism to Maybe, and adding markdown for internal links.

Cabal/Distribution.Utils.IOData received a comment on withIOData,
and had the comment on IODataMode expanded. It is still
missing a comment on KnownIODataMode.

Cabal/Distribution.Lex received a comment on its sole function,
so its writer won't get annoyed by newbies unfamiliar with
its lexing pattern in the future.

Recent comments on Cabal/Distribution.Simple.defaultMainHelper
and cabal-install/Distribution.Client.Main.main were amended
for clarity, and to note the "--" behavior on
Distribution.Client.Main.main's expandResponse.