aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2010-12-07 15:41:44 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2010-12-07 15:41:44 +0000
commita6813eacb72123966641834799954e4b023d7f75 (patch)
tree86ebaef95704efe14ea79c212c1e5a326f005f49
parent738e455a3beaedf5252cb2354381f6facef8d62d (diff)
downloadpaludis-a6813eacb72123966641834799954e4b023d7f75.tar.gz
paludis-a6813eacb72123966641834799954e4b023d7f75.tar.xz
caveify docs
-rw-r--r--doc/clients/index.html.part4
-rw-r--r--doc/configuration/syncers.html.part.in3
-rw-r--r--doc/faq/different.html.part19
-rw-r--r--doc/faq/howdoi.html.part90
-rw-r--r--doc/faq/index.html.part9
-rw-r--r--doc/faq/operation.html.part33
-rw-r--r--doc/faq/stricter.html.part18
-rw-r--r--doc/overview/features.html.part4
-rw-r--r--doc/overview/gettingstarted.html.part4
9 files changed, 17 insertions, 167 deletions
diff --git a/doc/clients/index.html.part b/doc/clients/index.html.part
index 69eab82..32c0252 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 fcdcd3c..b302a35 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 be6664c..ef674fd 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 323ca9c..a239510 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 117988f..1b48a7e 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 ee9a909..c0845b6 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 8785312..39c5821 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 7d5514c..6ca08d9 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 b43ec08..7bd8d13 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