Fix broken links in user's guide + few haddock fixes

Cabal/Distribution/Compat/DList.hs

@@ -28,7 +28,7 @@ newtype DList a = DList ([a] -> [a])
 runDList :: DList a -> [a]
 runDList (DList run) = run []
 
--- | Make 'DList' with containing single element.
+-- | Make 'DList' containing single element.
 singleton :: a -> DList a
 singleton a = DList (a:)
 

Cabal/Distribution/Compat/Newtype.hs

@@ -26,7 +26,7 @@ import Unsafe.Coerce (unsafeCoerce)
 --
 -- Since Cabal-3.0 class arguments are in a different order than in @newtype@ package.
 -- This change is to allow usage with @DeriveAnyClass@ (and @DerivingStrategies@, in GHC-8.2).
--- Unfortunately one have to repeat inner type.
+-- Unfortunately one has to repeat inner type.
 --
 -- @
 -- newtype New = New Old
@@ -86,6 +86,6 @@ alaf _ hof f = unpack . hof (pack . f)
 pack' :: Newtype o n => (o -> n) -> o -> n
 pack' _ = pack
 
--- | Variant of 'pack', which takes a phantom type.
+-- | Variant of 'unpack', which takes a phantom type.
 unpack' :: Newtype o n => (o -> n) -> n -> o
 unpack' _ = unpack

Cabal/Distribution/FieldGrammar/Class.hs

@@ -119,7 +119,7 @@ class
         -> ALens' s [(String, String)]  -- ^ lens into the field
         -> g s [(String, String)]
 
-    -- | Known field, which we don't parse, neither pretty print.
+    -- | Known field, which we don't parse, nor pretty print.
     knownField :: FieldName -> g s ()
 
     -- | Field which is parsed but not pretty printed.
@@ -132,7 +132,7 @@ class
         -> g s a
         -> g s a
 
-    -- | Removed in. If we occur removed field, parsing fails.
+    -- | Removed in. If we encounter removed field, parsing fails.
     removedIn
         :: CabalSpecVersion   -- ^ version
         -> String             -- ^ removal message

Cabal/Distribution/FieldGrammar/FieldDescrs.hs

@@ -31,7 +31,7 @@ data SP s = SP
     , pParse  :: !(forall m. P.CabalParsing m => s -> m s)
     }
 
--- | A collection field parsers and pretty-printers.
+-- | A collection of field parsers and pretty-printers.
 newtype FieldDescrs s a = F { runF :: Map P.FieldName (SP s) }
   deriving (Functor)
 

Cabal/Distribution/FieldGrammar/Newtypes.hs

@@ -99,7 +99,7 @@ instance Sep NoCommaFSep where
 newtype List sep b a = List { _getList :: [a] }
 
 -- | 'alaList' and 'alaList'' are simply 'List', with additional phantom
--- arguments to constraint the resulting type
+-- arguments to constrain the resulting type
 --
 -- >>> :t alaList VCat
 -- alaList VCat :: [a] -> List VCat (Identity a) a
@@ -129,7 +129,7 @@ instance (Newtype a b, Sep sep, Pretty b) => Pretty (List sep b a) where
 newtype Set' sep b a = Set' { _getSet :: Set a }
 
 -- | 'alaSet' and 'alaSet'' are simply 'Set'' constructor, with additional phantom
--- arguments to constraint the resulting type
+-- arguments to constrain the resulting type
 --
 -- >>> :t alaSet VCat
 -- alaSet VCat :: Set a -> Set' VCat (Identity a) a

Cabal/Distribution/PackageDescription/Check.hs

@@ -12,9 +12,9 @@
 -- another set of checks that also looks at files in the package. Some of the
 -- checks are basic sanity checks, others are portability standards that we'd
 -- like to encourage. There is a 'PackageCheck' type that distinguishes the
--- different kinds of check so we can see which ones are appropriate to report
--- in different situations. This code gets uses when configuring a package when
--- we consider only basic problems. The higher standard is uses when
+-- different kinds of checks so we can see which ones are appropriate to report
+-- in different situations. This code gets used when configuring a package when
+-- we consider only basic problems. The higher standard is used when
 -- preparing a source tarball and by Hackage when uploading new packages. The
 -- reason for this is that we want to hold packages that are expected to be
 -- distributed to a higher standard than packages that are only ever expected

doc/cabal-package.rst

@@ -2521,6 +2521,8 @@ The following tests are currently supported.
 ``false``
     Constant value false.
 
+.. _resolution-of-conditions-and-flags:
+
 Resolution of Conditions and Flags
 """"""""""""""""""""""""""""""""""
 
@@ -2984,6 +2986,7 @@ TBW
    TBW
 
 
+.. _accessing-data-files:
 
 Accessing data files from package code
 --------------------------------------
@@ -3049,6 +3052,8 @@ exports the constant ``version ::``
 which is defined as the version of your package as specified in the
 ``version`` field.
 
+.. _system-dependent-parameters:
+
 System-dependent parameters
 ---------------------------
 
@@ -3244,6 +3249,8 @@ instead of a normal Haskell compiler. The value of the
 bugs in Haddock or generating prettier documentation in some special
 cases.
 
+.. _more-complex-packages:
+
 More complex packages
 ---------------------
 

doc/cabal-project.rst

@@ -311,8 +311,8 @@ The following settings control the behavior of the dependency solver:
 
     :default: ``none``
 
-    Allow the solver to pick an newer version of some packages than
-    would normally be permitted by than the :pkg-field:`build-depends` bounds
+    Allow the solver to pick more recent version of some packages than
+    would normally be permitted by the :pkg-field:`build-depends` bounds
     of packages in the install plan. This option may be useful if the
     dependency solver cannot otherwise find a valid install plan.
 
@@ -392,7 +392,7 @@ The following settings control the behavior of the dependency solver:
 
 
     :cfg-field:`allow-newer` is often used in conjunction with a constraint
-    (in the cfg-field:`constraints` field) forcing the usage of a specific,
+    (in the :cfg-field:`constraints` field) forcing the usage of a specific,
     newer version of a package.
 
     The command line variant of this field is e.g. ``--allow-newer=bar``. A
@@ -656,7 +656,7 @@ feature was added.
 
     :default: ``ghc``
 
-    Specify which compiler toolchain to be used. This is independent of
+    Specify the compiler toolchain to be used. This is independent of
     ``with-compiler``, because the choice of toolchain affects Cabal's
     build logic.
 
@@ -944,7 +944,7 @@ Static linking options
     :default: False
 
     Build fully static executables.
-    This link all dependent libraries into executables statically,
+    This links all dependent libraries into executables statically,
     including libc.
     This passes ``-static`` and ``-optl=-static`` to GHC.
 

doc/nix-local-build-overview.rst

@@ -1,8 +1,8 @@
+.. _nix-style-builds:
+
 Nix-style Local Builds
 ======================
 
-.. _nix-style-builds:
-
 Nix-style local builds are a new build system implementation inspired by Nix.
 The Nix-style local build system is commonly called "v2-build" for short
 after the ``cabal v2-*`` family of commands that control it. However, those

doc/setup-commands.rst

@@ -34,7 +34,7 @@ results to some permanent place and registers the package with GHC.
 .. note ::
 
     Global installing of packages is not recommended.
-    The :ref:`Nix-style builds<nix-style-builds>` is the preferred way of building and installing
+    The :ref:`nix-style-builds` is the preferred way of building and installing
     packages.
 
 Creating a binary package
@@ -108,10 +108,8 @@ the values supplied via these options are recorded in a private file
 read by later stages.
 
 If a user-supplied ``configure`` script is run (see the section on
-`system-dependent
-parameters <developing-packages.html#system-dependent-parameters>`__ or
-on `complex
-packages <developing-packages.html#more-complex-packages>`__), it is
+:ref:`system-dependent-parameters` or
+on :ref:`more-complex-packages`), it is
 passed the :option:`--with-hc-pkg`, :option:`--prefix`, :option:`--bindir`,
 :option:`--libdir`, :option:`--dynlibdir`, :option:`--datadir`, :option:`--libexecdir` and
 :option:`--sysconfdir` options. In addition the value of the
@@ -211,7 +209,7 @@ files of a package:
 .. option:: --prog-option=option
 
     Specify a single additional option to the program *prog*. For
-    passing an option that contain embedded spaces, such as a file name
+    passing an option that contains embedded spaces, such as a file name
     with embedded spaces, using this rather than :option:`--prog-options`
     means you do not need an additional level of quoting. Of course if you
     are using a command shell you may still need to quote, for example
@@ -499,9 +497,9 @@ with ``$prefix``. If this is not the case then the compiled executable
 will have baked-in all absolute paths.
 
 The application need do nothing special to achieve prefix-independence.
-If it finds any files using ``getDataFileName`` and the `other functions
+If it finds any files using ``getDataFileName`` and the :ref:`other functions
 provided for the
-purpose <developing-packages.html#accessing-data-files-from-package-code>`__,
+purpose <accessing-data-files>`,
 the files will be accessed relative to the location of the current
 executable.
 
@@ -512,8 +510,7 @@ to the library package.
 Controlling Flag Assignments
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Flag assignments (see the `resolution of conditions and
-flags <developing-packages.html#resolution-of-conditions-and-flags>`__)
+Flag assignments (see :ref:`resolution-of-conditions-and-flags`)
 can be controlled with the following command line options.
 
 .. option:: -f flagname or -f -flagname
@@ -604,7 +601,7 @@ Miscellaneous options
     built; this identifier is passed on to GHC and serves as the basis
     for linker symbols and the ``id`` field in a ``ghc-pkg``
     registration. When a package has multiple components, the actual
-    component identifiers are derived off of this identifier (e.g., an
+    component identifiers are derived off of this identifier. E.g., an
     internal library ``foo`` from package ``p-0.1-abcd`` will get the
     identifier ``p-0.1-abcd-foo``.
 
@@ -819,7 +816,7 @@ Miscellaneous options
 .. option:: --enable-executable-static
 
     Build fully static executables.
-    This link all dependent libraries into executables statically,
+    This links all dependent libraries into executables statically,
     including libc.
 
 .. option:: --disable-executable-static
@@ -829,8 +826,7 @@ Miscellaneous options
 .. option:: --configure-option=str
 
     An extra option to an external ``configure`` script, if one is used
-    (see the section on `system-dependent
-    parameters <developing-packages.html#system-dependent-parameters>`__).
+    (see the section on :ref:`system-dependent-parameters`).
     There can be several of these options.
 
 .. option:: --extra-include-dirs[=dir]
@@ -840,7 +836,7 @@ Miscellaneous options
 
     You might need to use this flag if you have standard system header
     files in a non-standard location that is not mentioned in the
-    package's ``.cabal`` file. Using this option has the same affect as
+    package's ``.cabal`` file. Using this option has the same effect as
     appending the directory *dir* to the ``include-dirs`` field in each
     library and executable in the package's ``.cabal`` file. The
     advantage of course is that you do not have to modify the package at
@@ -1064,7 +1060,7 @@ This command takes the following options:
     These are mostly the same as the `options configure
     step <#setup-configure>`__. Unlike the options specified at the
     configure step, any program options specified at the build step are
-    not persistent but are used for that invocation only. They options
+    not persistent but are used for that invocation only. The options
     specified at the build step are in addition not in replacement of
     any options specified at the configure step.
 
@@ -1097,7 +1093,9 @@ This command takes the following options:
     by hyperlinks in the generated documentation. For example, the
     following command generates links pointing at Hackage_ pages:
 
-        runhaskell Setup.hs haddock
+    ::
+
+        $ runhaskell Setup.hs haddock \
         --html-location='http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html'
 
     Here the argument is quoted to prevent substitution by the shell. If
@@ -1134,8 +1132,10 @@ This command takes the following options:
 .. option:: --hscolour-css=path
 
     The argument *path* denotes a CSS file, which is passed to HsColour_ as in
+
+    ::
 
-        runhaskell Setup.hs hscolour --css=*path*
+        $ runhaskell Setup.hs hscolour --css=*path*
 
 .. _setup-hscolour:
 
@@ -1358,6 +1358,7 @@ the package.
     results in real time).
 
 .. option:: --test-options=options
+
     Give extra options to the test executables.
 
 .. option:: --test-option=option
@@ -1385,6 +1386,7 @@ only the named benchmarks, otherwise, Cabal will run all benchmarks in
 the package.
 
 .. option:: --benchmark-options=options
+
     Give extra options to the benchmark executables.
 
 .. option:: --benchmark-option=option