From bb16112746724ccef9686d407ec94c7ccf7f928a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Hr=C4=8Dek?= Date: Sat, 18 Jul 2020 10:47:05 +0200 Subject: [PATCH] Fix broken links in user's guide + few haddock fixes --- Cabal/Distribution/Compat/DList.hs | 2 +- Cabal/Distribution/Compat/Newtype.hs | 4 +- Cabal/Distribution/FieldGrammar/Class.hs | 4 +- .../Distribution/FieldGrammar/FieldDescrs.hs | 2 +- Cabal/Distribution/FieldGrammar/Newtypes.hs | 4 +- .../Distribution/PackageDescription/Check.hs | 6 +-- doc/cabal-package.rst | 7 ++++ doc/cabal-project.rst | 10 ++--- doc/nix-local-build-overview.rst | 4 +- doc/setup-commands.rst | 38 ++++++++++--------- 10 files changed, 45 insertions(+), 36 deletions(-) diff --git a/Cabal/Distribution/Compat/DList.hs b/Cabal/Distribution/Compat/DList.hs index d32642064da..29cd1bb73c1 100644 --- a/Cabal/Distribution/Compat/DList.hs +++ b/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:) diff --git a/Cabal/Distribution/Compat/Newtype.hs b/Cabal/Distribution/Compat/Newtype.hs index 3e6d1c3aa3a..adf75366e4c 100644 --- a/Cabal/Distribution/Compat/Newtype.hs +++ b/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 diff --git a/Cabal/Distribution/FieldGrammar/Class.hs b/Cabal/Distribution/FieldGrammar/Class.hs index e6965125d33..67637c9f436 100644 --- a/Cabal/Distribution/FieldGrammar/Class.hs +++ b/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 diff --git a/Cabal/Distribution/FieldGrammar/FieldDescrs.hs b/Cabal/Distribution/FieldGrammar/FieldDescrs.hs index c540354322b..e8db4448652 100644 --- a/Cabal/Distribution/FieldGrammar/FieldDescrs.hs +++ b/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) diff --git a/Cabal/Distribution/FieldGrammar/Newtypes.hs b/Cabal/Distribution/FieldGrammar/Newtypes.hs index ff13ea58150..4c8c99fa6fd 100644 --- a/Cabal/Distribution/FieldGrammar/Newtypes.hs +++ b/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 diff --git a/Cabal/Distribution/PackageDescription/Check.hs b/Cabal/Distribution/PackageDescription/Check.hs index 003b4e3bc3e..cdf90404271 100644 --- a/Cabal/Distribution/PackageDescription/Check.hs +++ b/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 diff --git a/doc/cabal-package.rst b/doc/cabal-package.rst index 843eaff5aa3..9bc1756d67d 100644 --- a/doc/cabal-package.rst +++ b/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 --------------------- diff --git a/doc/cabal-project.rst b/doc/cabal-project.rst index 676915f6a1d..c3e1430c539 100644 --- a/doc/cabal-project.rst +++ b/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. diff --git a/doc/nix-local-build-overview.rst b/doc/nix-local-build-overview.rst index bb08fdecf77..7a0f466c88f 100644 --- a/doc/nix-local-build-overview.rst +++ b/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 diff --git a/doc/setup-commands.rst b/doc/setup-commands.rst index eb79a207f32..d2162aa6b95 100644 --- a/doc/setup-commands.rst +++ b/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` 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 `__ or -on `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 `__, +purpose `, 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 `__) +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 `__). + (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