docs: Cleanup flags section and use more refs

[ci skip]

Cabal/doc/developing-packages.rst

@@ -86,7 +86,7 @@ Editing the .cabal file
 
 Load up the ``.cabal`` file in a text editor. The first part of the
 ``.cabal`` file has the package metadata and towards the end of the file
-you will find the ``executable`` or ``library`` section.
+you will find the :pkg-section:`executable` or :pkg-section:`library` section.
 
 You will see that the fields that have yet to be filled in are commented
 out. Cabal files use "``--``" Haskell-style comment syntax. (Note that
@@ -709,10 +709,10 @@ The syntax of the value depends on the field. Field types include:
 Modules and preprocessors
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Haskell module names listed in the ``exposed-modules`` and
-``other-modules`` fields may correspond to Haskell source files, i.e.
-with names ending in "``.hs``" or "``.lhs``", or to inputs for various
-Haskell preprocessors. The simple build infrastructure understands the
+Haskell module names listed in the :pkg-field:`library:exposed-modules` and
+:pkg-field:`library:other-modules` fields may correspond to Haskell source
+files, i.e. with names ending in "``.hs``" or "``.lhs``", or to inputs for
+various Haskell preprocessors. The simple build infrastructure understands the
 extensions:
 
 -  ``.gc`` (:hackage-pkg:`greencard`)
@@ -730,7 +730,7 @@ link any C sources generated by the preprocessor (produced by
 functions).
 
 Some fields take lists of values, which are optionally separated by
-commas, except for the ``build-depends`` field, where the commas are
+commas, except for the :pkg-field:`build-depends` field, where the commas are
 mandatory.
 
 Some fields are marked as required. All others are optional, and unless
@@ -1575,7 +1575,7 @@ system-dependent values for these fields.
     A list of programs, possibly annotated with versions, needed to
     build this package, e.g. ``c2hs >= 0.15, cpphs``. If no version
     constraint is specified, any version is assumed to be acceptable.
-    ``build-tools`` can refer to locally defined executables, in which
+    :pkg-field:`build-tools` can refer to locally defined executables, in which
     case Cabal will make sure that executable is built first and add it
     to the PATH upon invocations to the compiler.
 
@@ -1924,7 +1924,7 @@ overridden through the use of parentheses. For example,
 
 The following tests are currently supported.
 
-``os(``\ *name*\ ``)``
+:samp:`os({name})`
     Tests if the current operating system is *name*. The argument is
     tested against ``System.Info.os`` on the target system. There is
     unfortunately some disagreement between Haskell implementations
@@ -1932,12 +1932,12 @@ The following tests are currently supported.
     it so that in particular ``os(windows)`` works on all
     implementations. If the canonicalised os names match, this test
     evaluates to true, otherwise false. The match is case-insensitive.
-``arch(``\ *name*\ ``)``
+:samp:`arch({name})`
     Tests if the current architecture is *name*. The argument is matched
     against ``System.Info.arch`` on the target system. If the arch names
     match, this test evaluates to true, otherwise false. The match is
     case-insensitive.
-``impl(``\ *compiler*\ ``)``
+:samp:`impl({compiler})`
     Tests for the configured Haskell implementation. An optional version
     constraint may be specified (for example ``impl(ghc >= 6.6.1)``). If
     the configured implementation is of the right type and matches the
@@ -1958,7 +1958,7 @@ The following tests are currently supported.
 
     -  The version of GHC is earlier than version x.y.z.
 
-``flag(``\ *name*\ ``)``
+:samp:`flag({name})`
     Evaluates to the current assignment of the flag of the given name.
     Flag names are case insensitive. Testing for flags that have not
     been introduced with a flag section is an error.
@@ -1989,9 +1989,9 @@ assignment in the following way.
 
 To put it another way, Cabal does a complete backtracking search to find
 a satisfiable package configuration. It is only the dependencies
-specified in the ``build-depends`` field in conditional blocks that
+specified in the :pkg-field:`build-depends` field in conditional blocks that
 determine if a particular flag assignment is satisfiable
-(``build-tools`` are not considered). The order of the declaration and
+(:pkg-field:`build-tools` are not considered). The order of the declaration and
 the default value of the flags determines the search order. Flags
 overridden on the command line fix the assignment of that flag, so no
 backtracking will be tried for that flag.

Cabal/doc/installing-packages.rst

@@ -589,7 +589,7 @@ package:
 
     In the simple build system, *dir* may contain the following path
     variables: ``$prefix``, ``$pkgid``, ``$pkg``, ``$version``,
-    ``$compiler``, ``$os``, ``$arch``, ``$abi``, \`$abitag
+    ``$compiler``, ``$os``, ``$arch``, ``$abi``, ``$abitag``
 
 .. option:: --libdir=dir