aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-01-01 22:20:47 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-01-01 22:20:47 +0000
commit5a1d7c6abb6583666c4ed272df44465b7dc56c8c (patch)
treecfceea87fd08c43a961e42a822a5099832db9548
parentf766b4edcadedf4cd177c3fb6c2336fd5dd49aaf (diff)
downloadpaludis-5a1d7c6abb6583666c4ed272df44465b7dc56c8c.tar.gz
paludis-5a1d7c6abb6583666c4ed272df44465b7dc56c8c.tar.xz
More docs work
-rw-r--r--doc/Makefile.am46
-rw-r--r--doc/cachefiles.html.skel (renamed from doc/doc_cache_files.doxygen)73
-rw-r--r--doc/configuration.html.skel296
-rw-r--r--doc/doc_configuration_files.doxygen272
4 files changed, 370 insertions, 317 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index eb5ce74..8d37adf 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -11,9 +11,7 @@ docfiles = \
doc_namespaces.doxygen \
doc_references.doxygen \
doc_portage_differences.doxygen \
- doc_configuration_files.doxygen \
- doc_programming_with_paludis.doxygen \
- doc_cache_files.doxygen
+ doc_programming_with_paludis.doxygen
htmlfiles = \
index.html \
@@ -22,15 +20,19 @@ htmlfiles = \
licence.html \
authors.html \
faq.html \
- migration.html
+ migration.html \
+ cachefiles.html \
+ configuration.html
EXTRA_DIST = doxygen.conf.in header.html footer.html paludis.css \
- $(docfiles) $(tagfiles) $(htmlfiles) htaccess \
+ $(docfiles) $(tagfiles) htaccess \
news.html.skel index.html.skel changelog.html.skel licence.html.skel authors.html.skel \
- faq.html.skel htmlheader.html htmlfooter.html migration.html.skel
+ faq.html.skel htmlheader.html htmlfooter.html migration.html.skel cachefiles.html.skel \
+ configuration.html.skel
CLEANFILES = *~ news.html index.html changelog.html licence.html authors.html faq.html \
- migration.html cleannews cleanchangelog cleanauthors cleanfaqtoc
+ migration.html cachefiles.html configuration.html \
+ cleannews cleanchangelog cleanauthors cleanfaqtoc
MAINTAINERCLEANFILES = Makefile.in $(tagfiles)
@@ -86,7 +88,7 @@ authors.html : authors.html.skel cleanauthors htmlheader.html htmlfooter.html
-e '/@HEADER@/r htmlheader.html' \
-e '/@HEADER@/d' \
-e '/@FOOTER@/r htmlfooter.html' \
- -e '/@FOOTER@/d' < authors.html.skel > authors.html
+ -e '/@FOOTER@/d' < $(srcdir)/authors.html.skel > authors.html
cleannews : $(top_srcdir)/NEWS
sed -e '1,6d' -e '$$d' < $(top_srcdir)/NEWS > cleannews
@@ -96,7 +98,7 @@ news.html : news.html.skel cleannews htmlheader.html htmlfooter.html
-e '/@HEADER@/r htmlheader.html' \
-e '/@HEADER@/d' \
-e '/@FOOTER@/r htmlfooter.html' \
- -e '/@FOOTER@/d' < news.html.skel | \
+ -e '/@FOOTER@/d' < $(srcdir)/news.html.skel | \
sed \
-e 's~^\([0-9].*\):~</li></ul><h3>&</h3><ul>~' \
-e 's~^ \*~</li><li>~' \
@@ -123,21 +125,35 @@ changelog.html : changelog.html.skel cleanchangelog htmlheader.html htmlfooter.h
-e '/@HEADER@/r htmlheader.html' \
-e '/@HEADER@/d' \
-e '/@FOOTER@/r htmlfooter.html' \
- -e '/@FOOTER@/d' < changelog.html.skel > changelog.html
+ -e '/@FOOTER@/d' < $(srcdir)/changelog.html.skel > changelog.html
index.html : index.html.skel htmlheader.html htmlfooter.html
sed -e '/@HEADER@/r htmlheader.html' \
-e '/@HEADER@/d' \
-e '/@FOOTER@/r htmlfooter.html' \
-e '/@FOOTER@/d' \
- < index.html.skel > index.html
+ < $(srcdir)/index.html.skel > index.html
+
+configuration.html : configuration.html.skel htmlheader.html htmlfooter.html
+ sed -e '/@HEADER@/r htmlheader.html' \
+ -e '/@HEADER@/d' \
+ -e '/@FOOTER@/r htmlfooter.html' \
+ -e '/@FOOTER@/d' \
+ < $(srcdir)/configuration.html.skel > configuration.html
migration.html : migration.html.skel htmlheader.html htmlfooter.html
sed -e '/@HEADER@/r htmlheader.html' \
-e '/@HEADER@/d' \
-e '/@FOOTER@/r htmlfooter.html' \
-e '/@FOOTER@/d' \
- < migration.html.skel > migration.html
+ < $(srcdir)/migration.html.skel > migration.html
+
+cachefiles.html : cachefiles.html.skel htmlheader.html htmlfooter.html
+ sed -e '/@HEADER@/r htmlheader.html' \
+ -e '/@HEADER@/d' \
+ -e '/@FOOTER@/r htmlfooter.html' \
+ -e '/@FOOTER@/d' \
+ < $(srcdir)/cachefiles.html.skel > cachefiles.html
faq.html : faq.html.skel htmlheader.html htmlfooter.html cleanfaqtoc
sed -e '/@HEADER@/r htmlheader.html' \
@@ -146,11 +162,11 @@ faq.html : faq.html.skel htmlheader.html htmlfooter.html cleanfaqtoc
-e '/@FOOTER@/d' \
-e '/@TOC@/r cleanfaqtoc' \
-e '/@TOC@/d' \
- < faq.html.skel > faq.html
+ < $(srcdir)/faq.html.skel > faq.html
cleanfaqtoc : faq.html.skel
sed -n -e 's!^<h\([23]\) id="\([^"]\+\)">\(.*\)</h\1>!\1 <li><a href="#\2">\3</a></li>!gp' \
- < faq.html.skel \
+ < $(srcdir)/faq.html.skel \
| sed -e 's!^2 <li>\(.*\)</li>!</ul></li><li><strong>\1</strong><ul>!' \
-e 's!^3 !!' \
| sed -e '1s!^</ul></li>!<ul>!' \
@@ -164,7 +180,7 @@ licence.html : licence.html.skel htmlheader.html htmlfooter.html ../COPYING
-e '/@FOOTER@/d' \
-e '/@COPYING@/r ../COPYING' \
-e '/@COPYING@/d' \
- < licence.html.skel > licence.html
+ < $(srcdir)/licence.html.skel > licence.html
clean-local :
rm -fr www
diff --git a/doc/doc_cache_files.doxygen b/doc/cachefiles.html.skel
index 9901dbc..39339cc 100644
--- a/doc/doc_cache_files.doxygen
+++ b/doc/cachefiles.html.skel
@@ -1,83 +1,96 @@
-/* vim: set ft=cpp tw=80 sw=4 et : */
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html lang="en" xml:lang="en">
+<head>
+<title>Paludis, the Other Package Mangler</title>
+<link rel="stylesheet" href="paludis.css" type="text/css" />
+</head>
+<body>
+@HEADER@
-/**
-\page CacheFiles Cache Files
+<h1>Paludis, the Other Package Mangler</h1>
-\section CacheFilesOverview Overview
+<h2>Cache Files</h2>
-This document explains the various cache options that are available for
+<h3>Overview</h3>
+
+<p>This document explains the various cache options that are available for
Paludis. Correct use of the cache can offer huge speed benefits; however,
using the different cache options impose various restrictions about
-how other package managers can be used in parallel with Paludis.
+how other package managers can be used in parallel with Paludis.</p>
-\section CacheFilesProvidesCache The Provides Cache
+<h3>The Provides Cache</h3>
-Loading the VDB (information about installed packages) is slow on
+<p>Loading the VDB (information about installed packages) is slow on
systems that have several hundred packages installed. The VDB format cannot
currently be changed because lots of ebuilds rely upon it working (solutions
involving hacking in a fake VDB with real data elsewhere are considered far too
impractical). This is a nuisance, because the VDB needs to be
-fully loaded for most tasks.
+fully loaded for most tasks.</p>
-Many common tasks only require a full VDB load to check for PROVIDE entries.
+<p>Many common tasks only require a full VDB load to check for PROVIDE entries.
If, instead of forcing a full scan to load PROVIDEs, we cache this data in
a single file, various common tasks become an order of magnitude faster.
Paludis supports this option via a key called <code>provides_cache</code>
-in the configuration files for <code>vdb</code> format repositories.
+in the configuration files for <code>vdb</code> format repositories.</p>
-To enable this cache, set <code>provides_cache = ${location}/.cache/provides</code> .
+<p>To enable this cache, set <code>provides_cache = ${location}/.cache/provides</code> .
To disable it, set <code>provides_cache = /var/empty</code> . By default, the
provides cache is disabled but generates a warning message suggesting that the
-user explicitly enable or disable it.
+user explicitly enable or disable it.</p>
-\warning If you enable the provides cache, and then go on to install or
+<p><strong>Warning:</strong>
+ If you enable the provides cache, and then go on to install or
uninstall packages using another package manager, you <b>must</b> run
<code>paludis --regenerate-installed-cache</code> before performing
<i>any</i> other operation. You should also run this command after turning
on the cache for the first time, and if Paludis is interrupted during
- an install or uninstall.
+ an install or uninstall if it has started to modify the live filesystem.</p>
-\section CacheFilesNamesCache The Names Cache
+<h3>The Names Cache</h3>
-Turning an unqualified package name, like <code>vim</code>, into a qualified
+<p>Turning an unqualified package name, like <code>vim</code>, into a qualified
name, like <code>app-editors/vim</code>, involves scanning every category
directory. This can take several seconds on a cold filesystem cache. Paludis can
cache unqualified to qualified name mappings for <code>portage</code> and
-<code>vdb</code> repository formats. This makes certain common tasks much faster.
+<code>vdb</code> repository formats. This makes certain common tasks much
+faster.</p>
-To enable this cache, set <code>names_cache = ${location}/.cache/names</code> .
+<p>To enable this cache, set <code>names_cache = ${location}/.cache/names</code> .
To disable it, set <code>names_cache = /var/empty</code> . By default, the
names cache is disabled but generates a warning message suggesting that the
-user explicitly enable or disable it.
+user explicitly enable or disable it.</p>
-\warning If you enable the names cache, and then go on to sync or otherwise
+<p><strong>Warning:</strong> If you enable the names cache, and then go on to sync or otherwise
modify the repository in question manually or with another package manager,
you <b>must</b> run <code>paludis --regenerate-installable-cache</code>
(for Portage repositories) or <code>paludis
--regenerate-installed-cache</code> (for VDB repositories). You should
also run this command after turning on the cache for the first time,
- and if Paludis is interrupted during an install, uninstall or sync.
+ and if Paludis is interrupted during an install, uninstall or sync if
+ has started to modify the live filesystem.</p>
-\section CacheFilesMetadataCache The Metadata Cache
+<h3>The Metadata Cache</h3>
-Extracting metadata (description, dependency information and so on) from an
+<p>Extracting metadata (description, dependency information and so on) from an
ebuild is slow -- it involves invoking <code>bash</code> with a considerable
amount of supporting code. To avoid this penalty, a centrally generated metadata
cache is distributed with the official tree in the <code>metadata/cache</code>
directory (Paludis can be told to look elsewhere by using the <code>cache</code>
reposiory key). For third party repositories and non-rsync users, this metadata
-cache may not be available.
+cache may not be available.</p>
-Paludis can generate metadata cache locally on demand. This will not speed up the
+<p>Paludis can generate metadata cache locally on demand. This will not speed up the
first time cache is accessed for a particular ebuild, but subsequent invocations
will be several orders of magnitude faster. To enable this cache where it is needed,
set the <code>write_cache</code> key in a Portage format repository. Recommended
values are <code>/var/cache/paludis/metadata</code> or
<code>/home/username/.paludis-cache</code>. Note that Paludis will place the
write cache for a repository into a subdirectory named for that repository, so
-specifying the same <code>write_cache</code> for every repository is acceptable.
-
-*/
-
+specifying the same <code>write_cache</code> for every repository is
+acceptable.</p>
+@FOOTER@
+</body>
+</html>
diff --git a/doc/configuration.html.skel b/doc/configuration.html.skel
new file mode 100644
index 0000000..5b76e2b
--- /dev/null
+++ b/doc/configuration.html.skel
@@ -0,0 +1,296 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html lang="en" xml:lang="en">
+<head>
+<title>Paludis, the Other Package Mangler</title>
+<link rel="stylesheet" href="paludis.css" type="text/css" />
+</head>
+<body>
+@HEADER@
+
+<h1>Paludis, the Other Package Mangler</h1>
+
+<h2>Configuration Files</h2>
+
+<h3>Overview</h3>
+
+<p>This document explains where Paludis looks for user configuration files, and
+describes the format of these files.</p>
+
+<h3>General File Format</h3>
+
+<p>Except where otherwise noted, configuration files are plain text files where
+blank lines and lines starting with optional whitespace followed by a hash
+symbol are ignored.</p>
+
+<p>Many files use a key = value format. Here, any whitespace around the outside
+of key and value is stripped. The value may be quoted using single or double
+quotes. Variable expansion on previously defined keys (and sometimes on
+predefined special values) may be done using <code>${variable}</code>. To
+include a literal dollar, use <code>\$</code>.</p>
+
+<h3>Locations</h3>
+
+<p>Paludis tries the following locations for its configuration directory:</p>
+
+<ul>
+ <li><code>${PALUDIS_HOME}/.paludis/</code>, if the <code>PALUDIS_HOME</code>
+ environment variable is set, or <code>${HOME}/.paludis/</code> otherwise.</li>
+ <li><code>SYSCONFDIR/paludis/</code>, where <code>SYSCONFDIR</code> is
+ <code>/etc</code> on most systems.</li>
+</ul>
+
+<p>If the <code>--config-suffix</code> commandline argument is supplied, Paludis
+will use <code>.paludis-thesuffix</code> or <code>paludis-thesuffix</code>
+instead.</p>
+
+<p>If a file named <code>specpath</code> exists in this directory, Paludis uses
+this file to determine the real configuration directory. The <code>specpath</code>
+file is a standard key / value configuration file (see above). The keys that
+are used are:</p>
+
+<ul>
+ <li><code>root</code>, which specifies the install root for packages and the
+ real configuration directory, which is <code>${root}/SYSCONFDIR/paludis/</code>
+ (note that the HOME values are <em>not</em> used here). This value is set in
+ <code>specpath</code> rather than the real configuration directory so
+ that chrooting into an image can work with no configuration changes.</li>
+
+ <li><code>config-suffix</code>, which specifies a new configuration suffix. By
+ default, no configuration suffix is used under root.</li>
+</ul>
+
+<p>If no <code>specpath</code> file is present, the original directory is
+used.</p>
+
+<h3>The use.conf File</h3>
+
+<p>User <code>USE</code> preferences are controlled by the <code>use.conf</code>
+file. The basic format of a line is <code>atom use use use ...</code>, where
+<code>atom</code> is a package depend atom or <code>*</code> for "all packages",
+and <code>use use use ...</code> is one or more USE flag names, prefixed by
+a minus if they are to be disabled.</p>
+
+<p>For <code>USE_EXPAND</code> variables such as <code>LINGUAS</code> and
+<code>VIDEO_CARDS</code>, <code>atom VARIABLE: value value ...</code> should be
+used. To avoid inheriting values from your profile, include <code>-*</code>.</p>
+
+<pre>
+# By default, apply these to all packages
+* -doc nls -apache2
+
+# Turn off nls for vim
+app-editors/vim -nls
+
+# For gvim 7, turn on and off various interpreters
+&gt;=app-editors/gvim-7_alpha mzscheme perl -python ruby
+
+# For gtk+ with SLOT=2, enable tiff support
+x11-libs/gtk+:2 tiff
+
+# We like English
+* LINGUAS: -* en_GB en
+</pre>
+
+<p>Note that if a package matches multiple lines, <em>all</em> of these lines will
+be considered, not just the best or last match.</p>
+
+<h3>The keywords.conf File</h3>
+
+<p>Which <code>ARCH KEYWORDS</code> to accept is controlled by the
+<code>keywords.conf</code> file. The format of a line is
+<code>atom keyword1 keywords2 ...</code>, where <code>atom</code> is a package
+depend atom or <code>*</code> for "all packages" and
+<code>keyword1 keyword2 ...</code> is one or more arch keywords. As with Portage,
+accepting <code>~arch</code> does <em>not</em>
+implicitly accept <code>arch</code>, however, if a package matches multiple lines,
+<em>all</em> of these lines will be considered, not just the best or last match.
+For example:</p>
+
+<pre>
+# We want a mostly stable system:
+* x86
+
+# But some ~arch packages:
+app-editors/vim ~x86
+app-editors/vim-core ~x86
+</pre>
+
+<p>If <code>*</code> is not used, then every package that is to be installed will require
+an entry in <code>keywords.conf</code>. It is also generally assumed within the gentoo
+portage tree that if <code>~ARCH</code> is accepted for a package, then so is
+<code>ARCH</code>; not doing so may result in all versions or the latest version of a
+package being masked, as the package is stabilised.</p>
+
+<h3>The package_mask.conf File</h3>
+
+<p>Packages can be masked through the use of the <code>package_mask.conf</code>
+file. The format of the file is one <code>atom</code> per line. For example:</p>
+
+<pre>
+# Hide vim 7
+&gt;=app-editors/vim-core-7
+&gt;=app-editors/vim-7
+
+# Hide gvim
+app-editors/gvim
+</pre>
+
+<h3>The package_unmask.conf File</h3>
+
+<p>Packages can be unmasked through the use of the
+<code>package_unmask.conf</code> file. The format of the file is one
+<code>atom</code> per line. For example:</p>
+
+<pre>
+# I need banshee 0.11.0
+=media-sound/banshee-0.11.0
+</pre>
+
+<h3>The licenses.conf File</h3>
+
+<p>Licence filtering can be controlled via <code>licenses.conf</code>. If no
+filtering is desired, use:</p>
+
+<pre>
+* *
+</pre>
+
+<p>For filtering, the format is similar to the keywords and use files:</p>
+
+<pre>
+* GPL-2 BSD
+app-editors/vim-core vim
+</pre>
+
+<h3>The mirrors.conf File</h3>
+
+<p>Mirrors and downloading can be controlled via <code>mirrors.conf</code>. Each
+line takes the form <code>mirrorname http://mirror/blah/ http://another.mirror/</code>.
+A special mirror named <code>*</code>, if present, will be consulted <em>before</em>
+any other location for all files. For example:</p>
+
+<pre>
+* file:///mnt/nfs/distfiles
+gentoo http://gentoo.blueyonder.co.uk/distfiles
+</pre>
+
+<h3>The bashrc File</h3>
+
+<p>Paludis will source <code>bashrc</code> when doing ebuild work. This file
+can be used to set environment variables (<code>CHOST</code>, <code>CFLAGS</code>
+and so on), but <em>cannot</em> be used to change metadata-affecting variables
+such as <code>USE</code> or <code>LINGUAS</code>.</p>
+
+<h3>The repositories/ Files</h3>
+
+<p>Each file named <code>*.conf</code> in the <code>repositories/</code> subdirectory
+creates a repository for Paludis. This is a key = value format file, and the special
+variable <code>${ROOT}</code> is defined based upon <code>specpath</code>. All
+files must define a <code>format =</code> key; depending upon the value used, other
+optional and mandatory keys are available.</p>
+
+<p>Each repository can have a key named <code>importance</code>. This is used when
+two different repositories contain an identical package atom (e.g. foo/bar-1.0).
+The repository with the higher importance will always be chosen first. If not
+provided, the default is 0.</p>
+
+<h4>portage Format Repositories</h4>
+
+<p>Note: The name <code>portage</code> is used here to refer to repositories in the
+format used by the <code>gentoo-portage</code> (or <code>gentoo-x86</code>) tree.
+The name is far from ideal... In future, this may be changed to <code>format =
+ ebuild</code>.</p>
+
+<p>The following keys are available for <code>format = portage</code>:</p>
+
+<ul>
+ <li><code>location</code> (mandatory), which points to the location of the
+ tree.</li>
+ <li><code>profiles</code> (mandatory), which should be a space separated list of
+ directories used for profile data. Later directories have priority.</li>
+ <li><code>buildroot</code> (default: <code>/var/tmp/paludis</code>), which controls
+ the temporary directory used by Paludis for compiling software.</li>
+ <li><code>cache</code> (default: <code>${location}/metadata/cache</code>), which
+ controls the location of the metadata cache for a repository. It should be set
+ to <code>/var/empty</code> if there is no metadata cache available.</li>
+ <li><code>write_cache</code>, which can be set to a directory that will be used
+ to write generated cache files.</li>
+ <li><code>names_cache</code>, which should be either <code>/var/empty</code> or
+ <code>${location}/.cache/names</code>. See <a href="cachefiles.html">the cache
+ documentation</a>.</li>
+ <li><code>distdir</code> (default: <code>${location}/distfiles</code>), which
+ controls where downloaded files are saved.</li>
+ <li><code>eclassdirs</code> (default: <code>${location}/eclass</code>), which
+ is a space separated list of locations of eclasses. The value of ECLASSDIR
+ is taken from the <em>first</em> entry, but eclasses from later entries are
+ favoured.</li>
+ <li><code>newsdir</code> (default: <code>${location}/metadata/news</code>), which
+ controls where GLEP 42 news items are located.</li>
+ <li><code>securitydir</code> (default: <code>${location}/metadata/security</code>),
+ which controls where security advisories are located.</li>
+ <li><code>setsdir</code> (default: <code>${location}/sets</code>), which controls
+ where package set files are located.</li>
+ <li><code>sync</code> (default: empty), which controls how the repository is
+ synced. Typically values are in the form <code>rsync://rsync.europe.gentoo.org/gentoo-portage</code>
+ or <code>svn://svn.pioto.org/paludis/overlay</code>. Use
+ <code>paludis --list-sync-protocols</code> to see supported protocols.</li>
+ <li><code>sync_exclude</code> (default: empty), which can point to a file that
+ contains a list of directories to exclude when syncing via
+ <code>rsync://</code>.</li>
+ </ul>
+
+<h4>vdb Format Repositories</h4>
+
+<p>You should have exactly one VDB format repository. It holds packages that have
+been installed from a <code>portage</code> format repository.</p>
+
+<p>The following keys are available for <code>format = vdb</code>:</p>
+
+<ul>
+ <li><code>location</code> (mandatory), which <strong>must</strong> be set to
+ <code>${ROOT}/var/db/pkg</code>.</li>
+ <li><code>buildroot</code> (default: <code>/var/tmp/paludis</code>), which is
+ used as a temporary directory when carrying out uninstall operations,</li>
+ <li><code>provides_cache</code>, which should be either <code>/var/empty</code> or
+ <code>${location}/.cache/provides</code>. See <a href="cachefiles.html">the
+ cache documentation</a>.</li>
+ <li><code>world</code> (default: <code>${location}/world</code>), which is used
+ for the world file.</li>
+</ul>
+
+<h4>CRAN Format Repositories</h4>
+
+<p>The following keys are available for <code>format = cran</code>:</p>
+
+<ul>
+ <li><code>buildroot</code> (default: <code>/var/tmp/paludis</code>), which controls
+ the temporary directory used by Paludis for compiling software.</li>
+ <li><code>distdir</code> (default: <code>${location}/distfiles</code>), which
+ controls where downloaded files are saved.</li>
+ <li><code>library</code> (mandatory), which should be set to <code>${ROOT}/usr/${libdir}/R/library</code>, unless
+ you know what you're doing.</li>
+ <li><code>location</code> (mandatory), which points to the location of the
+ CRAN tree.</li>
+ <li><code>sync</code> (default: empty), as per <code>format =
+ portage</code>.</li>
+</ul>
+
+<h4>CRAN Installed Format Repositories</h4>
+
+<p>The following keys are available for <code>format =
+ cran_installed</code>:</p>
+
+<ul>
+ <li><code>location</code> (mandatory), which should be set to <code>${ROOT}/usr/${libdir}/R/library</code>, unless
+ you know what you're doing. This must point to the same directory as
+ <code>library</code> for <code>format = cran</code>.</li>
+</ul>
+
+@FOOTER@
+</body>
+</html>
+
+
+
+
diff --git a/doc/doc_configuration_files.doxygen b/doc/doc_configuration_files.doxygen
deleted file mode 100644
index a3069ee..0000000
--- a/doc/doc_configuration_files.doxygen
+++ /dev/null
@@ -1,272 +0,0 @@
-/* vim: set ft=cpp tw=80 sw=4 et : */
-
-/**
-\page ConfigurationFiles Configuration Files
-
-\section ConfigurationFilesOverview Overview
-
-This document explains where Paludis looks for user configuration files, and
-describes the format of these files.
-
-\section ConfigurationFilesGeneralFormat General File Format
-
-Except where otherwise noted, configuration files are plain text files where
-blank lines and lines starting with optional whitespace followed by a hash
-symbol are ignored.
-
-Many files use a key = value format. Here, any whitespace around the outside
-of key and value is stripped. The value may be quoted using single or double
-quotes. Variable expansion on previously defined keys (and sometimes on
-predefined special values) may be done using <code>${variable}</code>. To
-include a literal dollar, use <code>\$</code>.
-
-\section ConfigurationFilesLocations Locations
-
-Paludis tries the following locations for its configuration directory:
-
-- <code>${PALUDIS_HOME}/.paludis/</code>, if the <code>PALUDIS_HOME</code>
- environment variable is set, or <code>${HOME}/.paludis/</code> otherwise.
-- <code>SYSCONFDIR/paludis/</code>, where <code>SYSCONFDIR</code> is
- <code>/etc</code> on most systems.
-
-If the <code>--config-suffix</code> commandline argument is supplied, Paludis
-will use <code>.paludis-thesuffix</code> or <code>paludis-thesuffix</code>
-instead.
-
-If a file named <code>specpath</code> exists in this directory, Paludis uses
-this file to determine the real configuration directory. The <code>specpath</code>
-file is a standard key / value configuration file (see above). The keys that
-are used are:
-
-- <code>root</code>, which specifies the install root for packages and the
- real configuration directory, which is <code>${root}/SYSCONFDIR/paludis/</code>
- (note that the HOME values are <em>not</em> used here). This value is set in
- <code>specpath</code> rather than the real configuration directory so
- that chrooting into an image can work with no configuration changes.
-- <code>config-suffix</code>, which specifies a new configuration suffix. By
- default, no configuration suffix is used under root.
-
-If no <code>specpath</code> file is present, the original directory is used.
-
-\section ConfigurationFilesUseConf The use.conf File
-
-User <code>USE</code> preferences are controlled by the <code>use.conf</code>
-file. The basic format of a line is <code>atom use use use ...</code>, where
-<code>atom</code> is a package depend atom or <code>*</code> for "all packages",
-and <code>use use use ...</code> is one or more USE flag names, prefixed by
-a minus if they are to be disabled.
-
-For <code>USE_EXPAND</code> variables such as <code>LINGUAS</code> and
-<code>VIDEO_CARDS</code>, <code>atom VARIABLE: value value ...</code> should be
-used. To avoid inheriting values from your profile, include <code>-*</code>.
-
-\verbatim
-# By default, apply these to all packages
-* -doc nls -apache2
-
-# Turn off nls for vim
-app-editors/vim -nls
-
-# For gvim 7, turn on and off various interpreters
->=app-editors/gvim-7_alpha mzscheme perl -python ruby
-
-# For gtk+ with SLOT=2, enable tiff support
-x11-libs/gtk+:2 tiff
-
-# We like English
-* LINGUAS: -* en_GB en
-\endverbatim
-
-Note that if a package matches multiple lines, <em>all</em> of these lines will
-be considered, not just the best or last match.
-
-\section ConfigurationFilesKeywordsConf The keywords.conf File
-
-Which <code>ARCH KEYWORDS</code> to accept is controlled by the
-<code>keywords.conf</code> file. The format of a line is
-<code>atom keyword1 keywords2 ...</code>, where <code>atom</code> is a package
-depend atom or <code>*</code> for "all packages" and
-<code>keyword1 keyword2 ...</code> is one or more arch keywords. As with Portage,
-accepting <code>~arch</code> does <em>not</em>
-implicitly accept <code>arch</code>, however, if a package matches multiple lines,
-<em>all</em> of these lines will be considered, not just the best or last match.
-For example:
-
-\verbatim
-# We want a mostly stable system:
-* x86
-
-# But some ~arch packages:
-app-editors/vim ~x86
-app-editors/vim-core ~x86
-\endverbatim
-
-If <code>*</code> is not used, then every package that is to be installed will require
-an entry in <code>keywords.conf</code>. It is also generally assumed within the gentoo
-portage tree that if <code>~ARCH</code> is accepted for a package, then so is
-<code>ARCH</code>; not doing so may result in all versions or the latest version of a
-package being masked, as the package is stabilised.
-
-
-\section ConfigurationFilesPackage_MaskConf The package_mask.conf File
-
-Packages can be masked through the use of the <code>package_mask.conf</code> file. The format of the file is one <code>atom</code> per line. For example:
-
-\verbatim
-# Hide vim 7
->=app-editors/vim-core-7
->=app-editors/vim-7
-
-# Hide gvim
-app-editors/gvim
-\endverbatim
-
-\section ConfigurationFilesPackage_UnmaskConf The package_unmask.conf File
-
-Packages can be unmasked through the use of the <code>package_unmask.conf</code> file. The format of the file is one <code>atom</code> per line. For example:
-
-\verbatim
-# I need banshee 0.11.0
-=media-sound/banshee-0.11.0
-\endverbatim
-
-\section ConfigurationFilesLicensesConf The licenses.conf File
-
-Licence filtering can be controlled via <code>licenses.conf</code>. If no
-filtering is desired, use:
-
-\verbatim
-* *
-\endverbatim
-
-For filtering, the format is similar to the keywords and use files:
-
-\verbatim
-* GPL-2 BSD
-app-editors/vim-core vim
-\endverbatim
-
-\section ConfigurationFilesMirrorsConf The mirrors.conf File
-
-Mirrors and downloading can be controlled via <code>mirrors.conf</code>. Each
-line takes the form <code>mirrorname http://mirror/blah/ http://another.mirror/</code>.
-A special mirror named <code>*</code>, if present, will be consulted <em>before</em>
-any other location for all files. For example:
-
-\verbatim
-* file:///mnt/nfs/distfiles
-gentoo http://gentoo.blueyonder.co.uk/distfiles
-\endverbatim
-
-\section ConfigurationFilesBashrc The bashrc File
-
-Paludis will source <code>bashrc</code> when doing ebuild work. This file
-can be used to set environment variables (<code>CHOST</code>, <code>CFLAGS</code>
-and so on), but <em>cannot</em> be used to change metadata-affecting variables
-such as <code>USE</code> or <code>LINGUAS</code>.
-
-\section ConfigurationFilesRepositories The repositories/ Files
-
-Each file named <code>*.conf</code> in the <code>repositories/</code> subdirectory
-creates a repository for Paludis. This is a key = value format file, and the special
-variable <code>${ROOT}</code> is defined based upon <code>specpath</code>. All
-files must define a <code>format =</code> key; depending upon the value used, other
-optional and mandatory keys are available.
-
-Each repository can have a key named <code>importance</code>. This is used when
-two different repositories contain an identical package atom (e.g. foo/bar-1.0).
-The repository with the higher importance will always be chosen first. If not
-provided, the default is 0.
-
-\subsection ConfigurationFilesRepositoriesPortage portage Format Repositories
-
-\note The name <code>portage</code> is used here to refer to repositories in the
-format used by the <code>gentoo-portage</code> (or <code>gentoo-x86</code>) tree.
-The name is far from ideal...
-
-The following keys are available for <code>format = portage</code>:
-
-- <code>location</code> (mandatory), which points to the location of the
- tree.
-- <code>profiles</code> (mandatory), which should be a space separated list of
- directories used for profile data. Later directories have priority.
-- <code>buildroot</code> (default: <code>/var/tmp/paludis</code>), which controls
- the temporary directory used by Paludis for compiling software.
-- <code>cache</code> (default: <code>${location}/metadata/cache</code>), which
- controls the location of the metadata cache for a repository. It should be set
- to <code>/var/empty</code> if there is no metadata cache available.
-- <code>write_cache</code>, which can be set to a directory that will be used
- to write generated cache files.
-- <code>names_cache</code>, which should be either <code>/var/empty</code> or
- <code>${location}/.cache/names</code>. See \link CacheFiles \endlink
-- <code>distdir</code> (default: <code>${location}/distfiles</code>), which
- controls where downloaded files are saved.
-- <code>eclassdirs</code> (default: <code>${location}/eclass</code>), which
- is a space separated list of locations of eclasses. The value of ECLASSDIR
- is taken from the <em>first</em> entry, but eclasses from later entries are
- favoured.
-- <code>newsdir</code> (default: <code>${location}/metadata/news</code>), which
- controls where GLEP 42 news items are located.
-- <code>securitydir</code> (default: <code>${location}/metadata/security</code>),
- which controls where security advisories are located.
-- <code>setsdir</code> (default: <code>${location}/sets</code>), which controls
- where package set files are located.
-- <code>sync</code> (default: empty), which controls how the repository is
- synced. Typically values are in the form <code>rsync://rsync.europe.gentoo.org/gentoo-portage</code>
- or <code>svn://svn.pioto.org/paludis/overlay</code>. Use
- <code>paludis --list-sync-protocols</code> to see supported protocols.
-- <code>sync_exclude</code> (default: empty), which can point to a file that
- contains a list of directories to exclude when syncing via
- <code>rsync://</code>.
-
-\subsection ConfigurationFilesRepositoriesVDB vdb Format Repositories
-
-You should have exactly one VDB format repository. It holds packages that have
-been installed from a <code>portage</code> format repository.
-
-The following keys are available for <code>format = vdb</code>:
-
-- <code>location</code> (mandatory), which <strong>must</strong> be set to
- <code>${ROOT}/var/db/pkg</code>.
-- <code>buildroot</code> (default: <code>/var/tmp/paludis</code>), which is
- used as a temporary directory when carrying out uninstall operations,
-- <code>provides_cache</code>, which should be either <code>/var/empty</code> or
- <code>${location}/.cache/provides</code>. See \link CacheFiles \endlink
-- <code>world</code> (default: <code>${location}/world</code>), which is used
- for the world file.
-
-\subsection ConfigurationFilesRepositoriesNothing nothing Format Repositories
-
-Usually you won't have any <code>nothing</code> repositories. They are used as
-a convenience when certain locations have to be synced at <code>--sync</code>
-time; they do not contain any packages.
-
-The following keys are available for <code>format = nothing</code>:
-
-- <code>location</code> (mandatory).
-- <code>sync</code> (default: empty), as per <code>format = portage</code>.
-- <code>sync_exclude</code> (default: empty), idem.
-
-\subsection ConfigurationFilesRepositoriesCRAN CRAN Format Repositories
-
-The following keys are available for <code>format = cran</code>:
-
-- <code>buildroot</code> (default: <code>/var/tmp/paludis</code>), which controls
- the temporary directory used by Paludis for compiling software.
-- <code>distdir</code> (default: <code>${location}/distfiles</code>), which
- controls where downloaded files are saved.
-- <code>library</code> (mandatory), which should be set to <code>${ROOT}/usr/${libdir}/R/library</code>, unless
-you know what you're doing.
-- <code>location</code> (mandatory), which points to the location of the CRAN tree.
-- <code>sync</code> (default: empty), as per <code>format = portage</code>.
-
-\subsection ConfigurationFilesRepositoriesCRANInstalled CRAN Installed Format Repositories
-
-The following keys are available for <code>format = cran_installed</code>:
-
-- <code>location</code> (mandatory), which should be set to <code>${ROOT}/usr/${libdir}/R/library</code>, unless
-you know what you're doing. This must point to the same directory as <code>library</code> for <code>format = cran</code>.
-
-*/
-
-