aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-01-02 23:29:38 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-01-02 23:29:38 +0000
commit43dd3fa3b3e56493bfd15f7b3005bf77eca14680 (patch)
treee2d4d59932b174d07c63a5cc4228091649e6f19d
parent246b72ee9bc9515e9f79c317ed56bb7095157034 (diff)
downloadpaludis-43dd3fa3b3e56493bfd15f7b3005bf77eca14680.tar.gz
paludis-43dd3fa3b3e56493bfd15f7b3005bf77eca14680.tar.xz
More docs work
-rw-r--r--doc/Makefile.am39
-rw-r--r--doc/doc_programming_with_paludis.doxygen228
-rw-r--r--doc/portagedifferences.html.skel2
-rw-r--r--doc/programmingwithpaludis.html.skel280
4 files changed, 310 insertions, 239 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 90b2a48..9b03266 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -9,9 +9,7 @@ docfiles = \
doc_mainpage.doxygen \
doc_coding_standards.doxygen \
doc_namespaces.doxygen \
- doc_references.doxygen \
- doc_portage_differences.doxygen \
- doc_programming_with_paludis.doxygen
+ doc_references.doxygen
htmlfiles = \
index.html \
@@ -23,17 +21,18 @@ htmlfiles = \
migration.html \
cachefiles.html \
configuration.html \
- portagedifferences.html
+ portagedifferences.html \
+ programmingwithpaludis.html
EXTRA_DIST = doxygen.conf.in header.html footer.html paludis.css \
$(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 cachefiles.html.skel \
- configuration.html.skel portagedifferences.html.skel
+ configuration.html.skel portagedifferences.html.skel programmingwithpaludis.html.skel
CLEANFILES = *~ news.html index.html changelog.html licence.html authors.html faq.html \
- migration.html cachefiles.html configuration.html portagedifferences.html \
- cleannews cleanchangelog cleanauthors cleanfaqtoc
+ migration.html cachefiles.html configuration.html portagedifferences.html programmingwithpaludis.html.skel \
+ cleannews cleanchangelog cleanauthors cleanfaqtoc cleanbasiccppapp cleanbasicrubyapp
MAINTAINERCLEANFILES = Makefile.in $(tagfiles)
@@ -77,12 +76,12 @@ rdoc :
endif
-cleanauthors : ../AUTHORS
+cleanauthors : $(top_srcdir)/AUTHORS
sed -e '1,3d' \
-e 's,&,\&amp;,g' -e 's,<,\&lt;,g' -e 's,>,\&gt;,g' -e 's,@, at ,g' \
-e 's,^ \(.*\),<dd>\1</dd>,' \
-e 's,^\([^ <].*\),<dt>\1</dt>,' \
- < ../AUTHORS > cleanauthors
+ < $(top_srcdir)/AUTHORS > cleanauthors
authors.html : authors.html.skel cleanauthors htmlheader.html htmlfooter.html
sed -e '/@AUTHORS@/r cleanauthors' -e '/@AUTHORS@/d' \
@@ -156,6 +155,26 @@ portagedifferences.html : portagedifferences.html.skel htmlheader.html htmlfoote
-e '/@FOOTER@/d' \
< $(srcdir)/portagedifferences.html.skel > portagedifferences.html
+cleanbasiccppapp : $(srcdir)/examples/pwp_basic_cplusplus_app.cc
+ sed -e 's,&,\&amp;,g' -e 's,<,\&lt;,g' -e 's,>,\&gt;,g' \
+ < $(srcdir)/examples/pwp_basic_cplusplus_app.cc > cleanbasiccppapp
+
+cleanbasicrubyapp : $(srcdir)/examples/pwp_basic_ruby_app.cc
+ sed -e 's,&,\&amp;,g' -e 's,<,\&lt;,g' -e 's,>,\&gt;,g' \
+ < $(srcdir)/examples/pwp_basic_ruby_app.cc > cleanbasicrubyapp
+
+programmingwithpaludis.html : programmingwithpaludis.html.skel htmlheader.html htmlfooter.html \
+ cleanbasiccppapp cleanbasicrubyapp
+ sed -e '/@HEADER@/r htmlheader.html' \
+ -e '/@HEADER@/d' \
+ -e '/@FOOTER@/r htmlfooter.html' \
+ -e '/@FOOTER@/d' \
+ -e '/@BASIC_CPP_APP@/r cleanbasiccppapp' \
+ -e '/@BASIC_CPP_APP@/d' \
+ -e '/@BASIC_RUBY_APP@/r cleanbasicrubyapp' \
+ -e '/@BASIC_RUBY_APP@/d' \
+ < $(srcdir)/programmingwithpaludis.html.skel > programmingwithpaludis.html
+
cachefiles.html : cachefiles.html.skel htmlheader.html htmlfooter.html
sed -e '/@HEADER@/r htmlheader.html' \
-e '/@HEADER@/d' \
@@ -203,7 +222,7 @@ homepage : doxygen rdoc htmlpages dothtaccess
upload-homepage : homepage
cd `readlink -f $(top_srcdir)/doc/www` && tar jc ./ --exclude ./ | \
- ssh shell.berlios.de tar vjx -C /home/groups/paludis/htdocs/
+ ssh svn.pioto.org tar vjx -C /srv/paludis.pioto.org/www/htdocs/
built-sources : $(BUILT_SOURCES)
for s in `echo $(SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s built-sources || exit 1 ; done
diff --git a/doc/doc_programming_with_paludis.doxygen b/doc/doc_programming_with_paludis.doxygen
deleted file mode 100644
index 0729e53..0000000
--- a/doc/doc_programming_with_paludis.doxygen
+++ /dev/null
@@ -1,228 +0,0 @@
-/* vim: set ft=cpp tw=80 sw=4 et : */
-
-/**
-\page ProgrammingWithPaludis Programming with Paludis
-
-Start by getting a
-<a href="http://svn.pioto.org/viewvc/paludis/">Subversion
-checkout</a> of <code>trunk/</code>, and reading the \link PortageDifferences Paludis and Portage
-differences \endlink document.
-
-It's best to start by skimming over the main program to get a feel for how
-everything fits together. The interface code is kept in the src/ directory,
-and library code is in paludis/ .
-
-The <a href="modules.html">Modules</a> link in the header bar will probably
-be of more use than any of the full class lists.
-
-\section ProgrammingWithPaludisBasics Basics
-
-There are currently two APIs available:
-
-- The C++ API. This offers the full range of functionality.
-- The Ruby API. This offers a subset of the functionality and is aimed at script and utility
- authors. Not every class or method is currently available; support for more classes and
- methods can be added as needed. Some things (for example, defining new Environment subclasses)
- will likely never be available through this interface.
-
-A basic C++ application will look something like:
-
-\include pwp_basic_cplusplus_app.cc
-
-Compile this using <code>g++ -Wall -lpaludis -lpaludisdefaultenvironment</code>.
-
-The same application written in Ruby will look something like:
-
-\verbinclude pwp_basic_ruby_app.rb
-
-Notice how various Rubyisms (singleton styles, question mark methods, constants
-for enums) are used. The Ruby interface aims to be natural to Ruby programmers
-and behave like a Ruby library, rather than being an exact translation.
-
-Make sure you can run both of these examples before reading on.
-
-\section ProgrammingWithPaludisCommonPatterns Common Patterns
-
-A number of common patterns are used throughout the code.
-
-\subsection ProgrammingWithPaludisCommonPatternsIterators Iterators
-
-STL style iterator pairs crop up in various places. Where this happens, there is
-usually a member typedef named <code>Iterator</code> or <code>FooIterator</code>,
-along with members named <code>begin</code> and <code>end</code> or <code>begin_foo</code>
-and <code>end_foo</code>. See \ref TCppSL if you are unfamiliar with this style.
-
-The underlying iterator format is usually hidden from the library programmer by a
-libwrapiter::ForwardIterator. This is to speed up compile times and to avoid breaking
-lots of things when underlying data types change.
-
-Ruby works better with blocks than external iterators. Thus, instead of providing
-<code>begin_foo</code> and <code>end_foo</code> methods, Ruby classes typically have
-a single <code>foo</code> member function that returns an array made from the
-iterator range.
-
-\subsection ProgrammingWithPaludisCommonPatternsPointers Pointers
-
-We have a reference-counted smart pointer template class, paludis::CountedPtr. It's
-used to avoid expensive copying and tricky memory management. Most classes that
-are suitable for being held by a smart pointer have member typedefs named
-<code>Pointer</code> and <code>ConstPointer</code>.
-
-We don't use std::tr1::shared_ptr because most of our target compilers don't have
-it yet.
-
-This is all hidden in the Ruby interface.
-
-\subsection ProgrammingWithPaludisCommonPatternsValidated Validated Names
-
-Rather than using std::string for package, category etc names, we have a wrapper
-class template called paludis::Validated, and a bunch of typedefs (paludis::CategoryNamePart,
-paludis::PackageNamePart, paludis::SlotName, paludis::RepositoryName, paludis::KeywordName).
-This gives a couple of benefits:
-
-- It catches certain screwups (e.g. passing the wrong parameter types) at compile time.
-- It means exceptions caused by weird data (e.g. from user input) are caught at a sensible
- place, rather than sometime weird later on.
-
-Ruby doesn't do static checking, so it just uses raw String instances for all of these.
-
-\subsection ProgrammingWithPaludisCommonPatternsCollections Collections
-
-Sometimes we need to pass around a collection of items. The paludis::SortedCollection,
-paludis::SequentialCollection and paludis::AssociativeCollection wrappers handle this.
-They are passed around via smart pointers to avoid copying.
-
-The basic classes are abstract. Use paludis::SortedCollection::Concrete etc if you need
-to make one yourself.
-
-In Ruby these are converted to arrays.
-
-\subsection ProgrammingWithPaludisCommonPatternsSmartRecords Smart Records
-
-Smart records are a bit smarter than Plain Old Data structs. They might define comparison
-operators and constructors. They're used in quite a few places.
-
-Some smart records support named parameter constructors. A typical call to one of these
-looks like:
-
-\code
-PackageDatabaseEntry my_pde(PackageDatabaseEntryParams::create()
- .package(QualifiedPackageName("app-editors/vim"))
- .version(VersionSpec("7.0.147"))
- .repository(RepositoryName("gentoo")));
-\endcode
-
-Named parameters can be specified in any order.
-
-\subsection ProgrammingWithPaludisCommonPatternsStringify Stringify
-
-Many types can be converted to a std::string for display purposes. The paludis::stringify()
-template function will handle this. It also works for any internal and standard library data
-type that can be written to a std::ostream.
-
-\section ProgrammingWithPaludisEnvironment The Environment
-
-At the heart of the Paludis API is a paludis::Environment subclass instance. All
-non-trivial clients will use one of the Environment subclasses as their starting
-point for obtaining data (Environment itself contains abstract members and cannot
-be used directly).
-
-\subsection ProgrammingWithPaludisDefaultEnvironment DefaultEnvironment
-
-The paludis::DefaultEnvironment class should be used when user configuration
-files (<code>~/.paludis</code> or <code>/etc/paludis</code>) are to be parsed. This
-is a singleton class (see \ref GoF for details on singletons) whose instance can
-be obtained via the paludis::DefaultEnvironment::get_instance method.
-
-The configuration suffix can be set using the paludis::DefaultConfig::set_config_suffix
-static member function. Clients should usually provide a <code>--config-suffix</code> and
-<code>-c</code> command-line option for this.
-
-When using DefaultEnvironment, linking should include <code>-lpaludisdefaultenvironment</code>.
-
-In Ruby, the class is <code>Paludis::DefaultEnvironment</code>, the instance is
-<code>Paludis::DefaultEnvironment::instance</code> and the configuration suffix is
-set using <code>Paludis::DefaultConfig::config_suffix=</code>.
-
-\subsection ProgrammingWithPaludisNoConfigEnvironment NoConfigEnvironment
-
-The paludis::NoConfigEnvironment class should be used when user configuration should
-not be read, and instead the repository should be from a single particular directory.
-Multiple instances of this environment can be created if necessary.
-
-When using NoConfigEnvironment, linking should include <code>-lpaludisnoconfigenvironment</code>.
-
-In Ruby the class is <code>Paludis::NoConfigEnvironment</code>.
-
-\subsection ProgrammingWithPaludisOtherEnvironments Other Environments
-
-The paludis::qa::QAEnvironment class is used for QA environments. There is also a
-paludis::TestEnvironment class that is used in some test cases. These are less useful
-for most client authors.
-
-There is currently no Ruby wrapper for either of these.
-
-\section ProgrammingWithPaludisPackageDatabase The Package Database
-
-Every paludis::Environment has a paludis::PackageDatabase, which can be obtained
-via the paludis::Environment::package_database() method.
-
-The PackageDatabase contains a number of paludis::Repository subclass instances. These
-can be obtained using the paludis::PackageDatabase::begin_repositories() and
-paludis::PackageDatabase::end_repositories() pair or the
-paludis::PackageDatabase::fetch_repository() method.
-
-The PackageDatabase also provides a number of utility functions. paludis::PackageDatabase::query()
-can be used to fetch a paludis::PackageDatabaseEntryCollection containing packages
-matching a particular paludis::PackageDepAtom. paludis::PackageDatabase::fetch_unique_qualified_package_name()
-can be used to convert a paludis::PackageNamePart with no associated paludis::CategoryNamePart into
-a full paludis::QualifiedPackageName .
-
-In Ruby, the class is <code>Paludis::PackageDatabase</code> and an instance can
-only be obtained by calling <code>some_environment.package_database</code>.
-Rather than providing iterator pairs, repositories are available through the
-<code>repositories</code> method, whose return value behaves like an array of
-<code>Paludis::Repository</code> subclass instances. The
-<code>fetch_repository</code> and <code>fetch_unique_qualified_package_name</code> methods are available.
-
-\section ProgrammingWithPaludisRepositories Repositories
-
-The paludis::Repository class is an abstract base class representing a
-repository. Each paludis::Repository subclass provides various core functions,
-along with various optional others based upon the repository's capabilities.
-
-The commonly used subclasses are:
-
-- paludis::PortageRepository, which is used for Gentoo-style ebuild repositories.
-- paludis::VDBRepository, which is used for installed packages
-- paludis::VirtualsRepository, which is used for old-style virtuals
-- paludis::InstalledVirtualsRepository, which is used for old-style provided virtuals
-
-Others include:
-
-- paludis::CRANRepository, which is used for CRAN packages.
-- paludis::CRANInstalledRepository, which is used for installed CRAN packages.
-- paludis::FakeRepository, which is used for some test cases.
-
-Repository creation is usually handled by the paludis::Environment subclass and its
-associated paludis::PackageDatabase. In Ruby, this is the only way to gain access
-to a repository.
-
-All repositories provide some basic functions for querying their contents. Commonly used
-functions are paludis::Repository::version_metadata(), paludis::Repository::has_category_named(),
-paludis::Repository::has_package_named(), paludis::Repository::category_names(),
-paludis::Repository::package_names(), paludis::Repository::version_specs() and
-paludis::Repository::has_version(). These are available through Ruby; the has_ functions
-have a question mark suffix as per Ruby convention.
-
-Additional capabilities are available through optional interfaces. These can be accessed
-via members named paludis::Repository::mask_interface, paludis::Repository::sets_interface
-and so on -- these members will either be a pointer to the interface or a zero pointer.
-
-A full list of optional capabilities can be seen in the documentation for paludis::RepositoryCapabilities,
-from which paludis::Repository inherits.
-
-In Ruby, this works a bit differently. Members that return either a self reference or nil
-are available for each interface. They are named as their C++ equivalents.
-
-*/
diff --git a/doc/portagedifferences.html.skel b/doc/portagedifferences.html.skel
index 50ac8f5..d8fa2cc 100644
--- a/doc/portagedifferences.html.skel
+++ b/doc/portagedifferences.html.skel
@@ -21,7 +21,7 @@
<ul>
<li>A whole different <a
- href="configurationfiles.html">configuration system</a>, making it far easier to maintain
+ href="configuration.html">configuration system</a>, making it far easier to maintain
multiple systems, some in chroots, with entirely separate configuration
files.</li>
diff --git a/doc/programmingwithpaludis.html.skel b/doc/programmingwithpaludis.html.skel
new file mode 100644
index 0000000..fe13352
--- /dev/null
+++ b/doc/programmingwithpaludis.html.skel
@@ -0,0 +1,280 @@
+<!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>Programming with Paludis, the Other Package Mangler</h1>
+
+<p>You can get a <a href="http://svn.pioto.org/viewvc/paludis/">Subversion
+ checkout</a> of <code>trunk/</code> rather than working off a tarball. If you're
+planning to submit patches, you'll have to do this.</p>
+
+<p>It's best to start by skimming over the main program to get a feel for how
+everything fits together. The interface code is kept in the src/ directory,
+and library code is in paludis/ .</p>
+
+<h2>Basics</h2>
+
+<p>There are currently two APIs available:</p>
+
+<ul>
+ <li>The C++ API. This offers the full range of functionality. <a
+ href="doxygen/html/">Full Doxygen documentation</a> is available.</li>
+ <li>The Ruby API. This offers a subset of the functionality and is aimed at script and utility
+ authors. Not every class or method is currently available; support for more classes and
+ methods can be added as needed. Some things (for example, defining new Environment subclasses)
+ will likely never be available through this interface. <a href="ruby/">Full
+ Rdoc documentation</a> is available.</li>
+</ul>
+
+<p>A basic C++ application will look something like:</p>
+
+<pre>
+@BASIC_CPP_APP@
+</pre>
+
+<p>Compile this using <code>g++ -Wall -lpaludis
+ -lpaludisdefaultenvironment</code>.</p>
+
+<p>The same application written in Ruby will look something like:</p>
+
+<pre>
+@BASIC_RUBY_APP@
+</pre>
+
+<p>Notice how various Rubyisms (singleton styles, question mark methods, constants
+for enums) are used. The Ruby interface aims to be natural to Ruby programmers
+and behave like a Ruby library, rather than being an exact translation.</p>
+
+<p>Make sure you can run both of these examples before reading on.</p>
+
+<h2>Common Patterns</h2>
+
+<p>A number of common patterns are used throughout the code.</p>
+
+<h3>Iterators</h3>
+
+<p>STL style iterator pairs crop up in various places. Where this happens, there is
+usually a member typedef named <code>Iterator</code> or <code>FooIterator</code>,
+along with members named <code>begin</code> and <code>end</code> or <code>begin_foo</code>
+and <code>end_foo</code>. See <a href="doxygen/html/References.html">TCppSL</a>
+if you are unfamiliar with this style.</p>
+
+<p>The underlying iterator format is usually hidden from the library programmer by a
+<code>libwrapiter::ForwardIterator</code>. This is to speed up compile times and to avoid breaking
+lots of things when underlying data types change.</p>
+
+<p>Ruby works better with blocks than external iterators. Thus, instead of providing
+<code>begin_foo</code> and <code>end_foo</code> methods, Ruby classes typically have
+a single <code>foo</code> member function that returns an array made from the
+iterator range. This is slower, but much easier.</p>
+
+<h3>Pointers</h3>
+
+<p>We have a reference-counted smart pointer template class,
+<code>paludis::CountedPtr</code>. It's
+used to avoid expensive copying and tricky memory management. Most classes that
+are suitable for being held by a smart pointer have member typedefs named
+<code>Pointer</code> and <code>ConstPointer</code>.</p>
+
+<p>We don't use <code>std::tr1::shared_ptr</code> because most of our target compilers don't have
+it yet. This is mildly annoying.</p>
+
+<p>This is all hidden in the Ruby interface. You shouldn't have to care about
+memory management.</p>
+
+<h3>Validated Names</h3>
+
+<p>Rather than using <code>std::string</code> for package, category etc names, we have a wrapper
+class template called <code>paludis::Validated</code>, and a bunch of typedefs
+(<code>paludis::CategoryNamePart</code>, <code>paludis::PackageNamePart</code>,
+<code>paludis::SlotName</code> etc). This gives a couple of benefits:</p>
+
+<ul>
+ <li>It catches certain screwups (e.g. passing the wrong parameter types) at
+ compile time.</li>
+ <li>It means exceptions caused by weird data (e.g. from user input) are caught at a sensible
+ place, rather than sometime weird later on.</li>
+</ul>
+
+<p>Ruby doesn't do static checking, so it just uses raw <code>String</code>
+instances for all of these.</p>
+
+<h3>Collections</h3>
+
+<p>Sometimes we need to pass around a collection of items. The
+<code>paludis::SortedCollection</code>,
+<code>paludis::SequentialCollection</code> and
+<code>paludis::AssociativeCollection</code> wrappers handle this.
+They are passed around via smart pointers to avoid copying.</p>
+
+<p>The basic classes are abstract. Use
+<code>paludis::SortedCollection::Concrete</code> etc if you need
+to make one yourself.</p>
+
+<p>In Ruby these are converted to arrays.</p>
+
+<h3>Smart Records</h3>
+
+<p>Smart records are a bit smarter than Plain Old Data structs. They might define comparison
+operators and constructors. They're used in quite a few places. Try not to worry
+about how these work internally unless you want to get a very sore head.</p>
+
+<p>Some smart records support named parameter constructors. A typical call to one of these
+looks like:</p>
+
+<pre>
+PackageDatabaseEntry my_pde(PackageDatabaseEntryParams::create()
+ .package(QualifiedPackageName("app-editors/vim"))
+ .version(VersionSpec("7.0.147"))
+ .repository(RepositoryName("gentoo")));
+</pre>
+
+<p>Named parameters can be specified in any order.</p>
+
+<h3>Stringify</h3>
+
+<p>Many types can be converted to a <code>std::string</code> for display
+purposes. The <code>paludis::stringify()</code>
+template function will handle this. It also works for any internal and standard library data
+type that can be written to a <code>std::ostream</code>.</p>
+
+<h2>The Environment</h2>
+
+<p>At the heart of the Paludis API is a <cpde>paludis::Environment</code> subclass instance. All
+non-trivial clients will use one of the Environment subclasses as their starting
+point for obtaining data (<code>Environment</code> itself contains abstract members and cannot
+be used directly).</p>
+
+<h3>DefaultEnvironment</h3>
+
+<p>The <code>paludis::DefaultEnvironment</code> class should be used when user configuration
+files (<code>~/.paludis</code> or <code>/etc/paludis</code>) are to be parsed. This
+is a singleton class (see <a href="doxygen/html/References.html">GoF</a> for details on
+singletons) whose instance can be obtained via the
+<code>paludis::DefaultEnvironment::get_instance</code> method.</p>
+
+<p>The configuration suffix can be set using the
+<code>paludis::DefaultConfig::set_config_suffix</code>
+static member function. Clients should usually provide a <code>--config-suffix</code> and
+<code>-c</code> command-line option for this.</p>
+
+<p>When using <code>DefaultEnvironment</code>, linking should include
+<code>-lpaludisdefaultenvironment</code>.</p>
+
+<p>In Ruby, the class is <code>Paludis::DefaultEnvironment</code>, the instance is
+<code>Paludis::DefaultEnvironment::instance</code> and the configuration suffix is
+set using <code>Paludis::DefaultConfig::config_suffix=</code>.</p>
+
+<h3>NoConfigEnvironment</h3>
+
+<p>The <code>paludis::NoConfigEnvironment</code> class should be used when user configuration should
+not be read, and instead the repository should be from a single particular directory.
+Multiple instances of this environment can be created if necessary.</p>
+
+<p>When using <code>NoConfigEnvironment</code>, linking should include
+<code>-lpaludisnoconfigenvironment</code>.</p>
+
+<p>In Ruby the class is <code>Paludis::NoConfigEnvironment</code>.</p>
+
+<h3>Other Environments</h3>
+
+<p>The <code>paludis::qa::QAEnvironment</code> class is used for QA environments. There is also a
+<code>paludis::TestEnvironment</code> class that is used in some test cases. These are less useful
+for most client authors.</p>
+
+<p>There is currently no Ruby wrapper for either of these.</p>
+
+<h2>The Package Database</h2>
+
+<p>Every <code>paludis::Environment</code> has a
+<code>paludis::PackageDatabase</code>, which can be obtained
+via the <code>paludis::Environment::package_database()</code> method.</p>
+
+<p>The <code>PackageDatabase</code> contains a number of
+<code>paludis::Repository</code> subclass instances. These
+can be obtained using the
+paludis<cpde>::PackageDatabase::begin_repositories()</code> and
+<code>paludis::PackageDatabase::end_repositories()</code> pair or the
+<code>paludis::PackageDatabase::fetch_repository()</code> method.</p>
+
+<p>The <code>PackageDatabase</code> also provides a number of utility functions.
+<code>paludis::PackageDatabase::query()</code>
+can be used to fetch a <code>paludis::PackageDatabaseEntryCollection</code> containing packages
+matching a particular <cpde>paludis::PackageDepAtom</code>.
+<code>paludis::PackageDatabase::fetch_unique_qualified_package_name()</code>
+can be used to convert a <code>paludis::PackageNamePart</code> with no
+associated <code>paludis::CategoryNamePart</code> into
+a full <code>paludis::QualifiedPackageName</code>.</p>
+
+<p>In Ruby, the class is <code>Paludis::PackageDatabase</code> and an instance can
+only be obtained by calling <code>some_environment.package_database</code>.
+Rather than providing iterator pairs, repositories are available through the
+<code>repositories</code> method, whose return value behaves like an array of
+<code>Paludis::Repository</code> subclass instances. The
+<code>fetch_repository</code> and
+<code>fetch_unique_qualified_package_name</code> methods are available.</p>
+
+<h2>Repositories</h2>
+
+<p>The <code>paludis::Repository</code> class is an abstract base class representing a
+repository. Each <code>paludis::Repository</code> subclass provides various core functions,
+along with various optional others based upon the repository's capabilities.</p>
+
+<p>The commonly used subclasses are:</p>
+
+<ul>
+ <li>paludis::PortageRepository, which is used for Gentoo-style ebuild
+ repositories.</li>
+ <li>paludis::VDBRepository, which is used for installed packages.</li>
+ <li>paludis::VirtualsRepository, which is used for old-style virtuals.</li>
+ <li>paludis::InstalledVirtualsRepository, which is used for old-style
+ provided virtuals.</li>
+</ul>
+
+<p>Others include:</p>
+
+<ul>
+<li>paludis::CRANRepository, which is used for CRAN packages.</li>
+<li>paludis::CRANInstalledRepository, which is used for installed CRAN
+packages.</li>
+<li>paludis::FakeRepository, which is used for some test cases.</li>
+</ul>
+
+<p>Repository creation is usually handled by the
+<code>paludis::Environment</code> subclass and its
+<code>associated paludis::PackageDatabase</code>. In Ruby, this is the only way to gain access
+to a repository.</p>
+
+<p>All repositories provide some basic functions for querying their contents. Commonly used
+functions are <code>paludis::Repository::version_metadata()</code>,
+<code>paludis::Repository::has_category_named()</code>,
+<code>paludis::Repository::has_package_named()</code>,
+<code>paludis::Repository::category_names()</code>,
+<code>paludis::Repository::package_names()</code>,
+<code>paludis::Repository::version_specs()</code> and
+<code>paludis::Repository::has_version()</code>. These are available through Ruby; the has_ functions
+have a question mark suffix as per Ruby convention.</p>
+
+<p>Additional capabilities are available through optional interfaces. These can be accessed
+via members named <code>paludis::Repository::mask_interface</code>,
+<code>paludis::Repository::sets_interface</code>
+and so on -- these members will either be a pointer to the interface or a zero
+pointer.</p>
+
+<p>A full list of optional capabilities can be seen in the documentation for
+<code>paludis::RepositoryCapabilities</code>,
+from which paludis::Repository inherits.</p>
+
+<p>In Ruby, this works a bit differently. Members that return either a self reference or nil
+are available for each interface. They are named as their C++ equivalents.</p>
+
+@FOOTER@
+</body>
+</html>
+