Document '--allow-newer'.

The user guide really could really use an overhaul...

Cabal/doc/installing-packages.markdown

@@ -678,6 +678,46 @@ followingcommand line options.
     for libraries it is also saved in the package registration
     information and used when compiling modules that use the library.
 
+`--allow-newer`[=_pkgs_]
+:   Selectively relax upper bounds in dependencies without editing the
+    package description.
+
+    If you want to install a package A that depends on B >= 1.0 && < 2.0, but
+    you have the version 2.0 of B installed, you can compile A against B 2.0 by
+    using `cabal install --allow-newer=B A`. This works for the whole package
+    index: if A also depends on C that in turn depends on B < 2.0, C's
+    dependency on B will be also relaxed.
+
+    Example:
+
+    ~~~~~~~~~~~~~~~~
+    $ cd foo
+    $ cabal configure
+    Resolving dependencies...
+    cabal: Could not resolve dependencies:
+    [...]
+    $ cabal configure --allow-newer
+    Resolving dependencies...
+    Configuring foo...
+    ~~~~~~~~~~~~~~~~
+
+    Additional examples:
+
+    ~~~~~~~~~~~~~~~~
+    # Relax upper bounds in all dependencies.
+    $ cabal install --allow-newer foo
+
+    # Relax upper bounds only in dependencies on bar, baz and quux.
+    $ cabal install --allow-newer=bar,baz,quux foo
+
+    # Relax the upper bound on bar and force bar==2.1.
+    $ cabal install --allow-newer=bar --constraint="bar==2.1" foo
+    ~~~~~~~~~~~~~~~~
+
+    It's also possible to enable `--allow-newer` permanently by setting
+    `allow-newer: True` in the `~/.cabal/config` file.
+
+
 In the simple build infrastructure, an additional option is recognized:
 
 `--scratchdir=`_dir_