Merge pull request #9217 from BinderDavid/remove-duplicate-documentation

Deduplicate documentation of cabal commands

Author: mergify[bot]

doc/cabal-commands.rst

@@ -398,31 +398,46 @@ Check ``cabal fetch --help`` for a complete list of options.
 cabal get
 ^^^^^^^^^
 
-``cabal get [PACKAGES]`` (synonym: ``cabal unpack``) downloads and unpacks
+``cabal get [FLAGS] [PACKAGES]`` (synonym: ``cabal unpack``) downloads and unpacks
 the source code of ``PACKAGES`` locally. By default the content of the
 packages is unpacked in the current working directory, in named subfolders
 (e.g.  ``./filepath-1.2.0.8/``), use ``--destdir=PATH`` to specify another
 folder. By default the latest version of the package is downloaded, you can
 ask for a spefic one by adding version numbers
 (``cabal get random-1.0.0.1``).
 
+The ``cabal get`` command supports the following options:
+
 .. option:: -s[[head|this|...]], --source-repository[=[head|this|...]]
 
-    Clone the package's source repository (Darcs, Git, etc.) instead
-    of downloading the tarball. Only works if the package specifies
-    a ``source-repository``.
+    Clone the package's source repository (Darcs, Git, etc.)
+    instead of downloading the tarball. Only works if the
+    package specifies a ``source-repository``.
 
 .. option:: --index-state=STATE
 
     Pin your request to a specific Hackage index state. Available
     ``STATE`` formats: Unix timestamps (e.g. ``@1474732068``),
     ISO8601 UTC timestamps (e.g. ``2016-09-24T17:47:48Z``), or ``HEAD``
     (default).
+    This determines which package versions are available as well as which
+    ``.cabal`` file revision is selected (unless ``--pristine`` is used).
 
 .. option:: --pristine
 
     Unpacks the pristine tarball, i.e. disregarding any Hackage revision.
 
+.. option:: -d, --destdir=PATH
+
+    Where to place the package source, defaults to (a subdirectory of)
+    the current directory.
+
+.. option:: --only-package-description, --package-description-only
+
+    Unpack the original pristine tarball, rather than updating the
+    ``.cabal`` file with the latest revision from the package archive.
+
+
 .. _command-group-config:
 
 Project configuration
@@ -478,6 +493,12 @@ flag.
 cabal freeze
 ^^^^^^^^^^^^
 
+If a package is built in several different environments, such as a
+development environment, a staging environment and a production
+environment, it may be necessary or desirable to ensure that the same
+dependency versions are selected in each environment. This can be done
+with the ``freeze`` command:
+
 ``cabal freeze`` writes out a **freeze file** which records all of
 the versions and flags that are picked by the solver under the
 current index and flags.  Default name of this file is
@@ -511,15 +532,88 @@ cabal gen-bounds
 ``cabal gen-bounds [FLAGS]`` generates bounds for all dependencies that do not
 currently have them.  Generated bounds are printed to stdout. You can then
 paste them into your .cabal file.
+The generated bounds conform to the `Package Versioning Policy`_, which is
+a recommended versioning system for publicly released Cabal packages.
+
+.. code-block:: console
+
+    $ cabal gen-bounds
+
+For example, given the following dependencies without bounds specified in
+:pkg-field:`build-depends`:
+
+::
+
+    build-depends:
+      base,
+      mtl,
+      transformers,
+
+``gen-bounds`` might suggest changing them to the following:
+
+::
+
+    build-depends:
+      base          >= 4.15.0 && < 4.16,
+      mtl           >= 2.2.2 && < 2.3,
+      transformers  >= 0.5.6 && < 0.6,
 
-See `the section on generating dependency version bounds <cabal-package.html#generating-dependency-version-bounds>`__ for more details and examples.
 
 cabal outdated
 ^^^^^^^^^^^^^^
 
 ``cabal outdated [FLAGS]`` checks for outdated dependencies in the package
 description file or freeze file.
 
+Manually updating dependency version bounds in a ``.cabal`` file or a
+freeze file can be tedious, especially when there's a lot of
+dependencies. The ``cabal outdated`` command is designed to help with
+that. It will print a list of packages for which there is a new
+version on Hackage that is outside the version bound specified in the
+``build-depends`` field. The ``outdated`` command can also be
+configured to act on the freeze file and
+ignore major (or all) version bumps on Hackage for a subset of
+dependencies.
+
+Examples:
+
+.. code-block:: console
+
+    $ cd /some/package
+    $ cabal outdated
+    Outdated dependencies:
+    haskell-src-exts <1.17 (latest: 1.19.1)
+    language-javascript <0.6 (latest: 0.6.0.9)
+    unix ==2.7.2.0 (latest: 2.7.2.1)
+
+    $ cabal outdated --simple-output
+    haskell-src-exts
+    language-javascript
+    unix
+
+    $ cabal outdated --ignore=haskell-src-exts
+    Outdated dependencies:
+    language-javascript <0.6 (latest: 0.6.0.9)
+    unix ==2.7.2.0 (latest: 2.7.2.1)
+
+    $ cabal outdated --ignore=haskell-src-exts,language-javascript,unix
+    All dependencies are up to date.
+
+    $ cabal outdated --ignore=haskell-src-exts,language-javascript,unix -q
+    $ echo $?
+    0
+
+    $ cd /some/other/package
+    $ cabal outdated --freeze-file
+    Outdated dependencies:
+    HTTP ==4000.3.3 (latest: 4000.3.4)
+    HUnit ==1.3.1.1 (latest: 1.5.0.0)
+
+    $ cabal outdated --freeze-file --ignore=HTTP --minor=HUnit
+    Outdated dependencies:
+    HUnit ==1.3.1.1 (latest: 1.3.1.2)
+
+
 ``cabal outdated`` supports the following flags:
 
 .. option:: --freeze-file
@@ -575,8 +669,6 @@ description file or freeze file.
     be used without arguments, in that case major version bumps are ignored for
     all packages.
 
-    See `the section on listing outdated dependency version bounds <cabal-package.html#listing-outdated-dependency-version-bounds>`__ for more details and examples.
-
 .. _command-group-build:
 
 Project building and installing
@@ -1157,3 +1249,5 @@ cabal report
 .. option:: -p PASSWORD or -pPASSWORD, --password=PASSWORD
 
     Your Hackage password.
+
+.. include:: references.inc