From a172cd29a720424178b487f31f34a33e525e8486 Mon Sep 17 00:00:00 2001
From: Leonid Onokhov <sopvop@gmail.com>
Date: Fri, 16 Sep 2016 15:35:43 +0300
Subject: [PATCH] docs: Cleanup flags section and use more refs
[ci skip]
---
Cabal/doc/developing-packages.rst | 26 +++++++++++++-------------
Cabal/doc/installing-packages.rst | 2 +-
2 files changed, 14 insertions(+), 14 deletions(-)
diff --git a/Cabal/doc/developing-packages.rst b/Cabal/doc/developing-packages.rst
index 6f3752ca22..cee7c129e4 100644
--- a/Cabal/doc/developing-packages.rst
+++ b/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.
diff --git a/Cabal/doc/installing-packages.rst b/Cabal/doc/installing-packages.rst
index 360822a21b..b9f28b1bab 100644
--- a/Cabal/doc/installing-packages.rst
+++ b/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
--
GitLab