9 files changed, 17 insertions, 167 deletions
diff --git a/doc/clients/index.html.part b/doc/clients/index.html.part
index 69eab82ef..32c0252ae 100644
--- a/doc/clients/index.html.part
+++ b/doc/clients/index.html.part
@@ -5,11 +5,11 @@
 <p>For users:</p>
 
 <ul>
-    <li><a href="cave.html">cave</a>, the new, improved and not yet entirely feature-complete console package management
+    <li><a href="cave.html">cave</a>, the new, improved and modular console package management
     client.</li>
 </ul>
 
-<p>Or for users who prefer to continue using the original clients for now:</p>
+<p>And the old clients, which are being phased out:</p>
 
 <ul>
     <li><a href="paludis.html">paludis</a>, the original console package management client.</li>
diff --git a/doc/configuration/syncers.html.part.in b/doc/configuration/syncers.html.part.in
index fcdcd3c32..b302a3554 100644
--- a/doc/configuration/syncers.html.part.in
+++ b/doc/configuration/syncers.html.part.in
@@ -17,7 +17,8 @@ tell whether such a URI should be synced by, say, Subversion, Git or Darcs. Inst
 
 <h2>Standard Syncers</h2>
 
-<p>Paludis ships with the following sync protocols (you can use <code>paludis --list-sync-protocols</code> to get the
+<p>Paludis ships with the following sync protocols (you can use <code>cave print-sync-protocols</code> and <code>cave
+    sync-protocol-options</code> to get the
 list yourself). Note that many of these syncers depend upon external programs that are not listed as dependencies for
 Paludis.</p>
 
diff --git a/doc/faq/different.html.part b/doc/faq/different.html.part
index be6664c95..ef674fd7e 100644
--- a/doc/faq/different.html.part
+++ b/doc/faq/different.html.part
@@ -3,22 +3,13 @@
 <h1>FAQ: Things Paludis Does Differently</h1>
 
 <ul>
-    <li><a href="different.html#tree">No <code>--tree</code> Equivalent</a></li>
     <li><a href="different.html#features">No <code>FEATURES</code> Equivalent</a></li>
-    <li><a href="different.html#emptytree_usechanged">No <code>--emptytree</code> Equivalent or No <code>--newuse</code>
-        Equivalent</a></li>
     <li><a href="different.html#mkdir">No Automatic Directory Creation</a></li>
     <li><a href="different.html#revdep_rebuild">Revdep-rebuild Equivalent</a></li>
     <li><a href="different.html#layman">Alternatives to Layman</a></li>
     <li><a href="different.html#package_provided">No <code>package.provided</code> file</a></li>
 </ul>
 
-<h2 id="tree">No <code>--tree</code> Equivalent</h2>
-
-<p>Paludis does not have something identical to <code>emerge --tree</code>. It
-does, however, have <code>--show-reasons</code>, which we find to be
-considerably more informative, useful and correct.</p>
-
 <h2 id="features">No <code>FEATURES</code> Equivalent</h2>
 
 <p>Paludis doesn't use the <code>FEATURES</code> variable. We find this to be
@@ -59,10 +50,6 @@ a rather ugly way of handling things. We do have equivalents to most values:</p>
     <dd>Controlled by <code>BUILD_OPTIONS: optional_tests</code> in use.conf.</dd>
 </dl>
 
-<h2 id="emptytree_usechanged">No <code>--emptytree</code> Equivalent or No <code>--newuse</code> Equivalent</h2>
-
-<p>The option <code>--dl-reinstall</code> handles both these cases.</p>
-
 <h2 id="mkdir">No Automatic Directory Creation</h2>
 
 <p>Portage usually automatically creates directories for things. Paludis will
@@ -81,7 +68,7 @@ local root access.</p>
 
 <h2 id="revdep_rebuild">Revdep-rebuild Equivalent</h2>
 
-<p>Use the <code>reconcilio</code> client.</p>
+<p>Use <code>cave fix-linkage</code>.</p>
 
 <h2 id="layman">Alternatives to Layman</h2>
 
@@ -102,11 +89,11 @@ considered preferable.</p>
 
 <p>Portage supports pretending that a package is installed for the purposes of dependency resolution via a file called
 <code>package.provided</code>. Paludis provides a cleaner approach, in the form of <a
-    href="../clients/importare.html"><code>importare</code></a>. <code>Importare</code> allows you to more cleanly
+    href="../clients/cave-import.html"><code>cave import</code></a>. <code>cave import</code> allows you to more cleanly
 reinstall, uninstall, and upgrade unpackaged packages, using the same sort of merge/unmerge process that paludis uses
 for ebuilds.</p>
 
-<p>To use importare, you will first have to configure an
+<p>To use <code>cave import</code>, you will first have to configure an
 <a href="../configuration/repositories/installed_unpackaged.html"><code>installed_unpackaged</code></a> format repository.</p>
 
 <p>To get a more direct equivalent of package.provided, you can "install" an empty directory with importare.</p>
diff --git a/doc/faq/howdoi.html.part b/doc/faq/howdoi.html.part
index 323ca9c52..a2395109f 100644
--- a/doc/faq/howdoi.html.part
+++ b/doc/faq/howdoi.html.part
@@ -5,8 +5,6 @@
 <ul>
     <li><a href="howdoi.html#ccache">Use <code>ccache</code></a></li>
     <li><a href="howdoi.html#distcc">Use <code>distcc</code></a></li>
-    <li><a href="howdoi.html#defaultoptions">Specify default options</a></li>
-    <li><a href="howdoi.html#removeunneeded">Remove unneeded packages</a></li>
     <li><a href="howdoi.html#unmask">Unmask a Package</a></li>
     <li><a href="howdoi.html#syncfromcvs">Sync from CVS</a></li>
     <li><a href="howdoi.html#syncfromsnapshot">Sync from a Gentoo tree snapshot</a></li>
@@ -44,94 +42,6 @@ PATH="/usr/lib/distcc/bin:${PATH}"
 SANDBOX_WRITE="${SANDBOX_WRITE}:${DISTCC_DIR}"
 </pre>
 
-<h2 id="defaultoptions">Specify default options</h2>
-
-<p>Often users want to specify certain options by default. Common choices include:</p>
-
-<ul>
-    <li><code>--log-level warning</code> (you should <strong>not</strong> use
-    <code>silent</code> in this way -- warnings are warnings because you need
-    to read them)</li>
-
-    <li><code>--show-reasons summary</code></li>
-
-    <li><code>--resume-command-template $HOME/.paludis-resume-XXXXXX</code></li>
-
-    <li><code>--dl-reinstall-scm weekly</code></li>
-</ul>
-
-<p>You can either use a shell alias, or <code>export
-    PALUDIS_OPTIONS="--options"</code> (in your environment, not in the
-configuration <code>bashrc</code>).</p>
-
-<h2 id="removeunneeded">Remove unneeded packages</h2>
-
-<p>Paludis has three ways of removing unused packages. You should <strong>always</strong>
-use <code>--pretend</code> and check the output before proceeding:</p>
-
-<dl>
-    <dt><code>--uninstall-unused</code></dt>
-    <dd>
-    <p>For the purposes of <code>--uninstall-unused</code>, an installed package
-    is <em>used</em> if any of these conditions are true:</p>
-
-    <ul>
-        <li>It is matched by any dependency specification in any repository's <code>system</code> or
-        <code>world</code> set.</li>
-        <li>It is depended upon by another used package.</li>
-    </ul>
-
-    <p>This action will therefore flag any packages that are no longer in use,
-    for example because they were only pulled in by a package that is no longer
-    installed, or because they were required by an old version of a package but
-    no longer are.</p>
-    </dd>
-
-    <dt><code>--uninstall --with-unused-dependencies</code></dt>
-    <dd>
-    <p>This action will uninstall a package, along with any of its dependencies
-    that will no longer be used once the target package is removed.</p>
-
-    <p>This action is recursive, so if <code>foo</code> depends upon <code>bar</code>
-    and <code>bar</code> depends upon <code>baz</code>, and if neither <code>bar</code>
-    nor <code>baz</code> are otherwise required, uninstalling <code>foo</code> will
-    also uninstall <code>bar</code> then <code>baz</code>.</p>
-    </dd>
-
-    <dt><code>--uninstall --with-dependencies</code></dt>
-    <dd>
-    <p>This action will uninstall a package, along with any other package that
-    requires this package as a dependency. Again, this action is recursive.</p>
-    </dd>
-</dl>
-
-<p>Some important notes:</p>
-
-<ul>
-    <li>These actions rely upon a package's dependencies being correctly specified.
-    They do not attempt to figure out whether a package has unlisted dependencies
-    using devious trickery.</li>
-
-    <li>These actions rely upon a package correctly using <code>USE</code> flags. If
-    a package was built with, say, <code>-foo</code> whilst <code>libfoo</code> was
-    installed, Paludis will not consider the package to require <code>libfoo</code>.
-    Unfortunately, some people don't know how to use <code>autoconf</code> correctly,
-    so this assumption is currently not entirely safe in all cases.</li>
-
-    <li>Currently a package's build dependencies, as well as its runtime and post
-    dependencies, are used when determining needed packages. Experimentation has
-    shown that doing otherwise will lead to an awful lot of breakage -- in the future,
-    if ebuild authors start being more careful, this behaviour may become
-    controllable.</li>
-
-    <li>For the case of any-of (<code>|| ( foo bar )</code>) dependencies, Paludis
-    currently does the safe thing and assumes that all available options, if
-    installed, are needed. This cannot be changed safely until ebuild authors stop
-    abusing <code>|| ( )</code> -- this construct <em>should</em> only be used
-    where the dependency can be switched at runtime, but unfortunately it is
-    often used to mean "compile against one of these".</li>
-</ul>
-
 <h2 id="unmask">Unmask a Package</h2>
 
 <p>First, you need to determine how a package is masked. The easiest way to do
diff --git a/doc/faq/index.html.part b/doc/faq/index.html.part
index 117988f2f..1b48a7ef9 100644
--- a/doc/faq/index.html.part
+++ b/doc/faq/index.html.part
@@ -26,21 +26,18 @@ functionality. Pestering anyone about these is liable to get you hurt a lot.</p>
 <ul>
     <li><a href="howdoi.html#ccache">Use <code>ccache</code></a></li>
     <li><a href="howdoi.html#distcc">Use <code>distcc</code></a></li>
-    <li><a href="howdoi.html#defaultoptions">Specify default options</a></li>
-    <li><a href="howdoi.html#removeunneeded">Remove unneeded packages</a></li>
     <li><a href="howdoi.html#unmask">Unmask a Package</a></li>
     <li><a href="howdoi.html#syncfromcvs">Sync from CVS</a></li>
     <li><a href="howdoi.html#syncfromsnapshot">Sync from a Gentoo tree snapshot</a></li>
     <li><a href="howdoi.html#deletedvdb">Recover VDB</a></li>
     <li><a href="howdoi.html#removeportage">Remove Portage from my Gentoo installation</a></li>
     <li><a href="howdoi.html#etcupdate">Update Configuration Files (<code>etc-update</code>)</a></li>
+    <li><a href="howdoi.html#sync">Sync while doing anything else</a></li>
 </ul>
 
 <h2>Operation</h2>
 
 <ul>
-    <li><a href="operation.html#updatingdepends">Paludis does not update DEPENDs of already installed packages</a></li>
-    <li><a href="operation.html#updateworldmissesthings">Updating world misses things</a></li>
     <li><a href="operation.html#info">Get package information for a bug report</a></li>
     <li><a href="operation.html#arrows">What do those fancy arrows when merging things mean?</a></li>
     <li><a href="operation.html#updates">Profiles Updates for Package Moves and Slot Moves</a></li>
@@ -55,7 +52,6 @@ functionality. Pestering anyone about these is liable to get you hurt a lot.</p>
     <li><a href="stricter.html#testfailures">Packages Failing <code>src_test</code></a></li>
     <li><a href="stricter.html#sandboxwithroot">Sandbox Violations when <code>ROOT</code> is Set</a></li>
     <li><a href="stricter.html#blacklist">Repository Blacklists</a></li>
-    <li><a href="stricter.html#downgrades">Paludis wants to downgrade Qt or KDE</a></li>
 </ul>
 
 <h2>Undesirable Misfunctionality</h2>
@@ -72,10 +68,7 @@ functionality. Pestering anyone about these is liable to get you hurt a lot.</p>
 <h2>Things Paludis Does Differently</h2>
 
 <ul>
-    <li><a href="different.html#tree">No <code>--tree</code> Equivalent</a></li>
     <li><a href="different.html#features">No <code>FEATURES</code> Equivalent</a></li>
-    <li><a href="different.html#emptytree_usechanged">No <code>--emptytree</code> Equivalent or No <code>--newuse</code>
-        Equivalent</a></li>
     <li><a href="different.html#mkdir">No Automatic Directory Creation</a></li>
     <li><a href="different.html#revdep_rebuild">Revdep-rebuild Equivalent</a></li>
     <li><a href="different.html#playman">No Layman (and how Playman is different)</a></li>
diff --git a/doc/faq/operation.html.part b/doc/faq/operation.html.part
index ee9a90964..c0845b616 100644
--- a/doc/faq/operation.html.part
+++ b/doc/faq/operation.html.part
@@ -3,8 +3,6 @@
 <h1>FAQ: Operation</h1>
 
 <ul>
-    <li><a href="operation.html#updatingdepends">Paludis does not update DEPENDs of already installed packages</a></li>
-    <li><a href="operation.html#updateworldmissesthings">Updating world misses things</a></li>
     <li><a href="operation.html#info">Get package information for a bug report</a></li>
     <li><a href="operation.html#arrows">What do those fancy arrows when merging things mean?</a></li>
     <li><a href="operation.html#updates">Profiles Updates for Package Moves and Slot Moves</a></li>
@@ -12,37 +10,16 @@
         <code>*/*::overlay-&gt;</code></a></li>
 </ul>
 
-<h2 id="updatingdepends">Paludis does not update DEPENDs of already installed packages</h2>
-
-<p>Paludis ignores build time dependencies (DEPENDs) of already installed packages by default.
-If you need a different behaviour, use the <code>--dl-installed-deps-pre</code>
-option. You may also want to use the <code>installed-slots</code> set rather than
-<code>world</code>.</p>
-
-<h2 id="updateworldmissesthings">Updating world misses things</h2>
-
-<p>Paludis doesn't 'miss' packages. If you think it is missing something, check the
-following:</p>
-
-<ul>
-    <li>See the previous item. Is the thing in question only included as a build dependency of
-    a package?</li>
-    <li>Are you sure the package is in world? <code>paludis --query world</code> will tell
-    you.</li>
-    <li>Is the upgrade being blocked by another package that depends upon a lower version
-    of the thing being missed?</li>
-</ul>
-
 <h2 id="info">Get package information for a bug report</h2>
 
-<p>Use <code>paludis --info</code> to get general configuration information. Paludis will <em>not</em> show any
+<p>Use <code>cave info info</code> to get general configuration information. Paludis will <em>not</em> show any
 configuration that is 'per-package' in this output. (This is different to <code>emerge</code>, which misleadingly shows
 an arbitrary global configuration no matter what.)</p>
 
-<p>If you are submitting a bug report for a particular package, use <code>paludis --info <em>spec</em></code> instead.
-If it's an installed package, <em>spec</em> can usually just be the qualified package name (for example, <code>paludis
-    --info sys-apps/paludis</code>). If you're installing a package, you should instead specify an exact package ID
-(such as <code>paludis --info =sys-apps/paludis-0.26.0_alpha12::paludis-overlay</code>).</p>
+<p>If you are submitting a bug report for a particular package, use <code>cave info <em>spec</em></code> instead.
+If it's an installed package, <em>spec</em> can usually just be the qualified package name (for example, <code>cave
+    info sys-apps/paludis</code>). If you're installing a package, you should instead specify an exact package ID
+(such as <code>cave info =sys-apps/paludis-0.26.0_alpha12::paludis-overlay</code>).</p>
 
 <h2 id="arrows">What do those fancy arrows when merging things mean?</h2>
 
diff --git a/doc/faq/stricter.html.part b/doc/faq/stricter.html.part
index 87853129f..39c58215a 100644
--- a/doc/faq/stricter.html.part
+++ b/doc/faq/stricter.html.part
@@ -7,7 +7,6 @@
     <li><a href="stricter.html#testfailures">Packages Failing <code>src_test</code></a></li>
     <li><a href="stricter.html#sandboxwithroot">Sandbox Violations when <code>ROOT</code> is Set</a></li>
     <li><a href="stricter.html#blacklist">Repository Blacklists</a></li>
-    <li><a href="stricter.html#downgrades">Paludis wants to downgrade Qt or KDE</a></li>
 </ul>
 
 <h2 id="mergingweirdstuff">Merging Weird Stuff</h2>
@@ -64,20 +63,3 @@ question will likely lead to breakages.</p>
     <li>When they are known to be a security threat.</li>
 </ul>
 
-<h2 id="downgrades">Paludis wants to downgrade Qt or KDE</h2>
-
-<p>Unlike Portage, Paludis enforces the dependencies of installed
-packages, rather than those of the corresponding package in its
-original repository. Unfortunately, to work around Portage limitations,
-the Qt and KDE eclasses are set up to depend specifically on those
-versions that are in the tree at the time of installation.  The result
-is that after upgrading to a newer version, dependant packages that
-were installed before the new version became available will try to
-force a downgrade back to the old version.</p>
-
-<p>To solve this problem, run your Paludis update command with
-the <code>--dl-downgrade warning</code> option, and check the
-backtrace for the package that depends on the older library.
-Reinstalling this package will fix the dependency.  Repeat if there is
-more than one package with the problem.</p>
-
diff --git a/doc/overview/features.html.part b/doc/overview/features.html.part
index 7d5514cd7..6ca08d949 100644
--- a/doc/overview/features.html.part
+++ b/doc/overview/features.html.part
@@ -38,8 +38,8 @@
     <li>Ability to see why a package is really being pulled in, rather than relying
     upon the rather crude '--tree' offered by Portage.</li>
 
-    <li>Much improved output: <code>--query</code> makes it easy to get a useful summary
-    of information about a package, and <code>--pretend</code> can be configured to show
+    <li>Much improved output: <code>cave show</code> makes it easy to get a useful summary
+    of information about a package, and <code>cave resolve</code> can be configured to show
     relevant information (e.g. USE flag descriptions and an explanation of why a package
     is being pulled in).</li>
 
diff --git a/doc/overview/gettingstarted.html.part b/doc/overview/gettingstarted.html.part
index b43ec080e..7bd8d13b1 100644
--- a/doc/overview/gettingstarted.html.part
+++ b/doc/overview/gettingstarted.html.part
@@ -318,8 +318,8 @@ config.</p>
 <p>To see if a configuration can be used successfully, try:</p>
 
 <pre>
-sudo paludis <em>[ add '--environment portage' if appropriate ]</em> --sync
-paludis <em>[ add '--environment portage' if appropriate ]</em> --pretend --install world
+sudo cave <em>[ add '--environment portage' if appropriate ]</em> sync
+cave <em>[ add '--environment portage' if appropriate ]</em> resolve --complete world
 </pre>
 
 <p>You will probably find that Paludis picks up some updates that Portage doesn't. Paludis does complete dependency