aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-10-15 11:10:38 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2007-10-15 11:10:38 +0000
commit503481c165de28bc0a5db25b7848708df7cb2668 (patch)
tree41eac48b7d7915ca0e7e88bb5dc9ea65225d3b99
parent8f51d97de6b38b8bc8a9b129baecf4bebd183c7b (diff)
downloadpaludis-503481c165de28bc0a5db25b7848708df7cb2668.tar.gz
paludis-503481c165de28bc0a5db25b7848708df7cb2668.tar.xz
Start reworking docs
-rw-r--r--Makefile.am2
-rw-r--r--configure.ac12
-rw-r--r--doc/Makefile.am335
-rw-r--r--doc/api/Makefile.am16
-rw-r--r--doc/api/cplusplus/Makefile.am51
-rw-r--r--doc/api/cplusplus/doxygen.conf.in (renamed from doc/doxygen.conf.in)234
-rw-r--r--doc/api/cplusplus/examples/Makefile.am (renamed from doc/examples/Makefile.am)8
-rw-r--r--doc/api/cplusplus/examples/example_about.cc (renamed from doc/examples/example_about.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_action.cc (renamed from doc/examples/example_action.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_command_line.cc (renamed from doc/examples/example_command_line.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_command_line.hh (renamed from doc/examples/example_command_line.hh)0
-rw-r--r--doc/api/cplusplus/examples/example_contents.cc (renamed from doc/examples/example_contents.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_dep_label.cc (renamed from doc/examples/example_dep_label.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_dep_spec.cc (renamed from doc/examples/example_dep_spec.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_dep_spec_flattener.cc (renamed from doc/examples/example_dep_spec_flattener.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_dep_tag.cc (renamed from doc/examples/example_dep_tag.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_dep_tree.cc (renamed from doc/examples/example_dep_tree.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_environment.cc (renamed from doc/examples/example_environment.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_formatter.cc (renamed from doc/examples/example_formatter.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_mask.cc (renamed from doc/examples/example_mask.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_match_package.cc (renamed from doc/examples/example_match_package.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_metadata_key.cc (renamed from doc/examples/example_metadata_key.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_name.cc (renamed from doc/examples/example_name.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_package_database.cc (renamed from doc/examples/example_package_database.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_package_id.cc (renamed from doc/examples/example_package_id.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_query.cc (renamed from doc/examples/example_query.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_query_delegate.cc (renamed from doc/examples/example_query_delegate.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_repository.cc (renamed from doc/examples/example_repository.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_stringify_formatter.cc (renamed from doc/examples/example_stringify_formatter.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_version_operator.cc (renamed from doc/examples/example_version_operator.cc)0
-rw-r--r--doc/api/cplusplus/examples/example_version_spec.cc (renamed from doc/examples/example_version_spec.cc)0
-rw-r--r--doc/api/cplusplus/groups.doxygen (renamed from doc/doc_main.doxygen)38
-rw-r--r--doc/api/cplusplus/main_page.doxygen (renamed from doc/doc_mainpage.doxygen)8
-rw-r--r--doc/api/cplusplus/namespaces.doxygen14
-rw-r--r--doc/api/cplusplus/references.doxygen (renamed from doc/doc_references.doxygen)0
-rw-r--r--doc/api/python/Makefile.am13
-rw-r--r--doc/api/ruby/Makefile.am13
-rw-r--r--doc/authors.html.skel24
-rw-r--r--doc/cachefiles.html.skel96
-rw-r--r--doc/changelog.html.skel26
-rw-r--r--doc/clients/Makefile.am13
-rw-r--r--doc/configuration.html.skel406
-rw-r--r--doc/configuration/Makefile.am13
-rw-r--r--doc/doc_coding_standards.doxygen180
-rw-r--r--doc/doc_namespaces.doxygen29
-rw-r--r--doc/faq.html.skel549
-rw-r--r--doc/faq/Makefile.am13
-rw-r--r--doc/faq/different.html.part89
-rw-r--r--doc/faq/general.html.part63
-rw-r--r--doc/faq/howdoi.html.part199
-rw-r--r--doc/faq/index.html.part79
-rw-r--r--doc/faq/misfunctionality.html.part81
-rw-r--r--doc/faq/operation.html.part30
-rw-r--r--doc/faq/repositories.html.part40
-rw-r--r--doc/faq/stricter.html.part88
-rw-r--r--doc/footer.html8
-rw-r--r--doc/header.html69
-rw-r--r--doc/hooks.html.skel482
-rw-r--r--doc/htaccess10
-rw-r--r--doc/htmlfooter.html7
-rw-r--r--doc/htmlheader.html48
-rw-r--r--doc/index.html.skel99
-rw-r--r--doc/licence.html.skel26
-rw-r--r--doc/man.html.skel17
-rw-r--r--doc/migration.html.skel204
-rw-r--r--doc/news.html.skel23
-rw-r--r--doc/overview/Makefile.am13
-rw-r--r--doc/overview/contact.html.part25
-rw-r--r--doc/overview/features.html.part93
-rw-r--r--doc/paludis.css391
-rw-r--r--doc/portagedifferences.html.skel147
-rw-r--r--doc/sets.html.skel90
72 files changed, 1140 insertions, 3374 deletions
diff --git a/Makefile.am b/Makefile.am
index abfd049..5873e44 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -24,7 +24,7 @@ automake-deps-dist-hack.tmp : distcheck-deps-subdirs
dist-hook :
rm $(distdir)/automake-deps-dist-hack.tmp
-doxygen rdoc epydoc homepage htmlpages upload-homepage :
+doxygen : built-sources
$(MAKE) -C doc $@
check-local :
diff --git a/configure.ac b/configure.ac
index ebd0eb5..0823c0b 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1274,8 +1274,16 @@ AC_OUTPUT(
Makefile
bash-completion/Makefile
doc/Makefile
- doc/doxygen.conf
- doc/examples/Makefile
+ doc/api/Makefile
+ doc/api/cplusplus/doxygen.conf
+ doc/api/cplusplus/Makefile
+ doc/api/cplusplus/examples/Makefile
+ doc/api/python/Makefile
+ doc/api/ruby/Makefile
+ doc/clients/Makefile
+ doc/configuration/Makefile
+ doc/faq/Makefile
+ doc/overview/Makefile
eselect/Makefile
hooks/Makefile
hooks/demos/Makefile
diff --git a/doc/Makefile.am b/doc/Makefile.am
index f5ee32d..ceb5a11 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,333 +1,7 @@
-SUBDIRS = examples .
+SUBDIRS = . api clients configuration faq overview
-if HAVE_DOXYGEN_TAGS
-
-tagfiles = \
- libstdc++.tag \
- libwrapiter.tag
-
-libstdc++.tag :
- wget -O $@ http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/libstdc++.tag
-
-libwrapiter.tag :
- wget -O $@ http://libwrapiter.pioto.org/libwrapiter.tag
-
-endif
-
-docfiles = \
- doc_main.doxygen \
- doc_mainpage.doxygen \
- doc_coding_standards.doxygen \
- doc_namespaces.doxygen \
- doc_references.doxygen
-
-images = \
- paludis.svg \
- paludis_270.png
-
-htmlfiles = \
- index.html \
- news.html \
- changelog.html \
- licence.html \
- authors.html \
- faq.html \
- migration.html \
- cachefiles.html \
- configuration.html \
- portagedifferences.html \
- sets.html \
- hooks.html \
- man-paludis.html \
- man-qualudis.html \
- man-contrarius.html \
- man-adjutrix.html \
- man-accerso.html \
- man-instruo.html \
- man-inquisitio.html
-
-EXTRA_DIST = doxygen.conf.in header.html footer.html paludis.css epydoc.css \
- $(docfiles) $(images) 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 \
- sets.html.skel hooks.html.skel man.html.skel
-
-CLEANFILES = *~ news.html index.html changelog.html licence.html authors.html faq.html \
- migration.html cachefiles.html configuration.html portagedifferences.html \
- sets.html hooks.html man-paludis.html man-qualudis.html man-contrarius.html man-adjutrix.html man-inquisitio.html \
- man-accerso.html man-instruo.html \
- cleannews cleanrecentnews cleanchangelog cleanauthors cleanfaqtoc cleanbasiccppapp cleanbasicrubyapp
-
-MAINTAINERCLEANFILES = Makefile.in $(tagfiles)
-
-www :
- mkdir -p www
-
-all-built-sources :
- $(MAKE) -C .. built-sources
-
-if HAVE_DOXYGEN
-
-doxygen : doxygen.conf $(top_srcdir)/paludis/*.cc $(top_srcdir)/paludis/*.hh \
- $(docfiles) $(tagfiles) www all-built-sources
- mkdir -p www/doxygen/html
- cp paludis_270.png www/doxygen/html
- doxygen doxygen.conf
-
-else
-
-doxygen :
- @echo "You don't have doxygen installed!"
- exit 1
-
-endif
-
-if ENABLE_RUBY
-
-rdoc : create_ruby_doc.rb www all-built-sources
- $(RUBY) $(srcdir)/create_ruby_doc.rb -t "Paludis Ruby API" -m Paludis --op www/ruby/ $(top_srcdir)/ruby/*.cc
-
-else
-
-rdoc :
- @echo "You don't have ruby turned on!"
- exit 1
-
-endif
-
-if ENABLE_PYTHON
-
-epydoc : epydoc.css www all-built-sources
- mkdir -p www/python/doc
- epydoc -n Paludis -o www/python/doc -u http://paludis.pioto.org --no-frames -c epydoc.css \
- $(top_builddir)/python/paludis.so
-
-else
-
-epydoc :
- @echo "You don't have python turned on!"
- exit 1
-
-endif
-
-
-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>,' \
- < $(top_srcdir)/AUTHORS > cleanauthors
-
-authors.html : authors.html.skel cleanauthors htmlheader.html htmlfooter.html
- sed -e '/@AUTHORS@/r cleanauthors' -e '/@AUTHORS@/d' \
- -e '/@HEADER@/r htmlheader.html' \
- -e '/@HEADER@/d' \
- -e '/@FOOTER@/r htmlfooter.html' \
- -e '/@FOOTER@/d' < $(srcdir)/authors.html.skel > authors.html
-
-cleannews : $(top_srcdir)/NEWS
- sed -e '1,6d' -e '$$d' < $(top_srcdir)/NEWS > cleannews
-
-news.html : news.html.skel cleannews htmlheader.html htmlfooter.html
- sed -e '/@RELEASE_NOTES@/r cleannews' -e '/@RELEASE_NOTES@/d' \
- -e '/@HEADER@/r htmlheader.html' \
- -e '/@HEADER@/d' \
- -e '/@FOOTER@/r htmlfooter.html' \
- -e '/@FOOTER@/d' < $(srcdir)/news.html.skel | \
- sed \
- -e 's~^\([0-9].*\):~</li></ul><h3>&</h3><ul>~' \
- -e 's~^ \*~</li><li>~' \
- | tr '\012' '\007' \
- | sed \
- -e 's~</li></ul><h3>~<h3>~' \
- -e 's~<ul>\a*</li>~<ul>~g' \
- | tr '\007' '\012' > news.html
-
-cleanchangelog : $(top_srcdir)/ChangeLog
- sed -e '1,7d' -e '$$d' -e 's,&,\&amp;,g' -e 's,<,\&lt;,g' -e 's,>,\&gt;,g' -e 's,@, at ,g' \
- < $(top_srcdir)/ChangeLog \
- | sed \
- -e 's~^\(200[0-9]-[0-9][0-9].*\)~<dt>&</dt>~' \
- | tr '\012' '\007' \
- | sed -e 's~\a\t[\*\+] ~\a<dd>~g' \
- | sed -e 's~\([^>]\)\a\a~\1</dd>\a~g' \
- | sed \
- -e 's,<dd>\([^:<]\+\):,<dd><code>\1</code>:<br />,g' \
- | tr '\007' '\012' > cleanchangelog
-
-changelog.html : changelog.html.skel cleanchangelog htmlheader.html htmlfooter.html
- sed -e '/@CHANGELOG@/r cleanchangelog' -e '/@CHANGELOG@/d' \
- -e '/@HEADER@/r htmlheader.html' \
- -e '/@HEADER@/d' \
- -e '/@FOOTER@/r htmlfooter.html' \
- -e '/@FOOTER@/d' < $(srcdir)/changelog.html.skel > changelog.html
-
-cleanrecentnews : news.html
- sed -n -e '/^<h3>[0-9]\+\.[^:]\+:/,/<.li><.ul><h3>/p' < news.html \
- | sed -e '1s/.*<.h3>//' -e '$$s,.*,</ul>,' > cleanrecentnews
-
-index.html : index.html.skel htmlheader.html htmlfooter.html cleanrecentnews
- sed -e '/[@]HEADER@/r htmlheader.html' \
- -e '/[@]HEADER@/d' \
- -e '/[@]FOOTER@/r htmlfooter.html' \
- -e '/[@]FOOTER@/d' \
- -e 's/[@]VERSION@/$(VERSION_FULL)/g' \
- -e '/[@]RECENTNEWS@/r cleanrecentnews' \
- -e '/[@]RECENTNEWS@/d' \
- < $(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
-
-sets.html : sets.html.skel htmlheader.html htmlfooter.html
- sed -e '/@HEADER@/r htmlheader.html' \
- -e '/@HEADER@/d' \
- -e '/@FOOTER@/r htmlfooter.html' \
- -e '/@FOOTER@/d' \
- < $(srcdir)/sets.html.skel > sets.html
-
-hooks.html : hooks.html.skel htmlheader.html htmlfooter.html
- sed -e '/@HEADER@/r htmlheader.html' \
- -e '/@HEADER@/d' \
- -e '/@FOOTER@/r htmlfooter.html' \
- -e '/@FOOTER@/d' \
- < $(srcdir)/hooks.html.skel > hooks.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' \
- < $(srcdir)/migration.html.skel > migration.html
-
-portagedifferences.html : portagedifferences.html.skel htmlheader.html htmlfooter.html
- sed -e '/@HEADER@/r htmlheader.html' \
- -e '/@HEADER@/d' \
- -e '/@FOOTER@/r htmlfooter.html' \
- -e '/@FOOTER@/d' \
- < $(srcdir)/portagedifferences.html.skel > portagedifferences.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' \
- -e '/@HEADER@/d' \
- -e '/@FOOTER@/r htmlfooter.html' \
- -e '/@FOOTER@/d' \
- -e '/@TOC@/r cleanfaqtoc' \
- -e '/@TOC@/d' \
- < $(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' \
- < $(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>!' \
- -e '$$s!$$!</ul></li></ul>!' \
- > cleanfaqtoc
-
-licence.html : licence.html.skel htmlheader.html htmlfooter.html ../COPYING
- sed -e '/@HEADER@/r htmlheader.html' \
- -e '/@HEADER@/d' \
- -e '/@FOOTER@/r htmlfooter.html' \
- -e '/@FOOTER@/d' \
- -e '/@COPYING@/r ../COPYING' \
- -e '/@COPYING@/d' \
- < $(srcdir)/licence.html.skel > licence.html
-
-man-adjutrix.html : $(top_builddir)/src/clients/adjutrix/adjutrix.html man.html.skel
- sed -e '/@HEADER@/r htmlheader.html' \
- -e '/@HEADER@/d' \
- -e '/@FOOTER@/r htmlfooter.html' \
- -e '/@FOOTER@/d' \
- -e '/@MAN@/r $(top_builddir)/src/clients/adjutrix/adjutrix.html' \
- -e '/@MAN@/d' \
- < $(srcdir)/man.html.skel > man-adjutrix.html
-
-man-accerso.html : $(top_builddir)/src/clients/accerso/accerso.html man.html.skel
- sed -e '/@HEADER@/r htmlheader.html' \
- -e '/@HEADER@/d' \
- -e '/@FOOTER@/r htmlfooter.html' \
- -e '/@FOOTER@/d' \
- -e '/@MAN@/r $(top_builddir)/src/clients/accerso/accerso.html' \
- -e '/@MAN@/d' \
- < $(srcdir)/man.html.skel > man-accerso.html
-
-man-instruo.html : $(top_builddir)/src/clients/instruo/instruo.html man.html.skel
- sed -e '/@HEADER@/r htmlheader.html' \
- -e '/@HEADER@/d' \
- -e '/@FOOTER@/r htmlfooter.html' \
- -e '/@FOOTER@/d' \
- -e '/@MAN@/r $(top_builddir)/src/clients/instruo/instruo.html' \
- -e '/@MAN@/d' \
- < $(srcdir)/man.html.skel > man-instruo.html
-
-man-inquisitio.html : $(top_builddir)/src/clients/inquisitio/inquisitio.html man.html.skel
- sed -e '/@HEADER@/r htmlheader.html' \
- -e '/@HEADER@/d' \
- -e '/@FOOTER@/r htmlfooter.html' \
- -e '/@FOOTER@/d' \
- -e '/@MAN@/r $(top_builddir)/src/clients/inquisitio/inquisitio.html' \
- -e '/@MAN@/d' \
- < $(srcdir)/man.html.skel > man-inquisitio.html
-
-man-qualudis.html : $(top_builddir)/src/clients/qualudis/qualudis.html man.html.skel
- sed -e '/@HEADER@/r htmlheader.html' \
- -e '/@HEADER@/d' \
- -e '/@FOOTER@/r htmlfooter.html' \
- -e '/@FOOTER@/d' \
- -e '/@MAN@/r $(top_builddir)/src/clients/qualudis/qualudis.html' \
- -e '/@MAN@/d' \
- < $(srcdir)/man.html.skel > man-qualudis.html
-
-man-paludis.html : $(top_builddir)/src/clients/paludis/paludis.html man.html.skel
- sed -e '/@HEADER@/r htmlheader.html' \
- -e '/@HEADER@/d' \
- -e '/@FOOTER@/r htmlfooter.html' \
- -e '/@FOOTER@/d' \
- -e '/@MAN@/r $(top_builddir)/src/clients/paludis/paludis.html' \
- -e '/@MAN@/d' \
- < $(srcdir)/man.html.skel > man-paludis.html
-
-man-contrarius.html : $(top_builddir)/src/clients/contrarius/contrarius.html man.html.skel
- sed -e '/@HEADER@/r htmlheader.html' \
- -e '/@HEADER@/d' \
- -e '/@FOOTER@/r htmlfooter.html' \
- -e '/@FOOTER@/d' \
- -e '/@MAN@/r $(top_builddir)/src/clients/contrarius/contrarius.html' \
- -e '/@MAN@/d' \
- < $(srcdir)/man.html.skel > man-contrarius.html
-
-clean-local :
- rm -fr www
-
-htmlpages : $(htmlfiles) paludis.css www
- for s in $(htmlfiles) paludis.css ; do cp $(srcdir)/$$s www/ ; done
-
-dothtaccess : htaccess
- cp $(srcdir)/htaccess www/.htaccess
-
-homepage : doxygen rdoc epydoc htmlpages dothtaccess images
-
-images : $(images)
- for s in $(images) ; do cp $(srcdir)/$$s www/ ; done
-
-upload-homepage : homepage upload-homepage-real
-
-upload-homepage-real :
- cd `readlink -f $(top_srcdir)/doc/www` && tar jc ./ --exclude ./ | \
- ssh svn.pioto.org tar vjx -C /srv/paludis.pioto.org/www/htdocs/
+MAINTAINERCLEANFILES = Makefile.in
+CLEANFILES = *~
built-sources : $(BUILT_SOURCES)
for s in `echo $(SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s built-sources || exit 1 ; done
@@ -340,3 +14,6 @@ distcheck-deps-subdirs :
for s in $(SUBDIRS) . ; do if test x$$s = x. ; then make distcheck-deps-local || exit 1 ; \
else $(MAKE) -C $$s distcheck-deps || exit 1 ; fi ; done
+doxygen :
+ make -C api doxygen
+
diff --git a/doc/api/Makefile.am b/doc/api/Makefile.am
new file mode 100644
index 0000000..98cccf6
--- /dev/null
+++ b/doc/api/Makefile.am
@@ -0,0 +1,16 @@
+SUBDIRS = cplusplus python ruby .
+
+CLEANFILES = *~ gmon.out *.gcov *.gcno *.gcda
+MAINTAINERCLEANFILES = Makefile.in
+
+built-sources : $(BUILT_SOURCES)
+ for s in `echo $(SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s built-sources || exit 1 ; done
+
+distcheck-deps : $(DISTCHECK_DEPS) distcheck-deps-subdirs
+
+distcheck-deps-subdirs :
+ for s in `echo $(DIST_SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s distcheck-deps || exit 1 ; done
+
+doxygen :
+ make -C cplusplus doxygen
+
diff --git a/doc/api/cplusplus/Makefile.am b/doc/api/cplusplus/Makefile.am
new file mode 100644
index 0000000..f3f44a7
--- /dev/null
+++ b/doc/api/cplusplus/Makefile.am
@@ -0,0 +1,51 @@
+SUBDIRS = examples .
+
+if HAVE_DOXYGEN_TAGS
+
+tagfiles = \
+ libstdc++.tag \
+ libwrapiter.tag
+
+libstdc++.tag :
+ wget -O $@ http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/libstdc++.tag
+
+libwrapiter.tag :
+ wget -O $@ http://libwrapiter.pioto.org/libwrapiter.tag
+
+endif
+
+doxygen_files = \
+ groups.doxygen \
+ main_page.doxygen \
+ namespaces.doxygen \
+ references.doxygen
+
+EXTRA_DIST = doxygen.conf.in $(doxygen_files)
+CLEANFILES = *~ doxygen/ paludis.tag
+
+MAINTAINERCLEANFILES = Makefile.in doxygen.conf $(tagfiles)
+
+if HAVE_DOXYGEN
+
+doxygen : doxygen.conf $(doxygen_files) $(tagfiles)
+ doxygen doxygen.conf
+
+else
+
+doxygen :
+ @echo "You don't have doxygen installed!"
+ exit 1
+
+endif
+
+built-sources : $(BUILT_SOURCES)
+ for s in `echo $(SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s built-sources || exit 1 ; done
+
+distcheck-deps : $(DISTCHECK_DEPS) distcheck-deps-subdirs
+
+distcheck-deps-subdirs :
+ for s in `echo $(SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s distcheck-deps || exit 1 ; done
+
+clean-local :
+ rm -fr doxygen/
+
diff --git a/doc/doxygen.conf.in b/doc/api/cplusplus/doxygen.conf.in
index b96f4fe..d5cfe2b 100644
--- a/doc/doxygen.conf.in
+++ b/doc/api/cplusplus/doxygen.conf.in
@@ -1,6 +1,4 @@
-# Doxyfile 1.4.2
-
-@GENERATED_FILE@
+# Doxyfile 1.5.3
# This file describes the settings to be used by the documentation system
# doxygen (www.doxygen.org) for a project
@@ -16,6 +14,14 @@
# Project related configuration options
#---------------------------------------------------------------------------
+# This tag specifies the encoding used for all characters in the config file that
+# follow. The default is UTF-8 which is also the encoding used for all text before
+# the first occurrence of this tag. Doxygen uses libiconv (or the iconv built into
+# libc) for the transcoding. See http://www.gnu.org/software/libiconv for the list of
+# possible encodings.
+
+DOXYFILE_ENCODING = UTF-8
+
# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
# by quotes) that should identify the project.
@@ -32,7 +38,7 @@ PROJECT_NUMBER = "Version @VERSION@"
# If a relative path is entered, it will be relative to the location
# where doxygen was started. If left blank the current directory will be used.
-OUTPUT_DIRECTORY = ./www/doxygen/
+OUTPUT_DIRECTORY =
# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create
# 4096 sub-directories (in 2 levels) under the output directory of each output
@@ -47,24 +53,14 @@ CREATE_SUBDIRS = NO
# documentation generated by doxygen is written. Doxygen will use this
# information to generate all constant output in the proper language.
# The default language is English, other supported languages are:
-# Brazilian, Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish,
-# Dutch, Finnish, French, German, Greek, Hungarian, Italian, Japanese,
-# Japanese-en (Japanese with English messages), Korean, Korean-en, Norwegian,
-# Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovene, Spanish,
-# Swedish, and Ukrainian.
+# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional,
+# Croatian, Czech, Danish, Dutch, Finnish, French, German, Greek, Hungarian,
+# Italian, Japanese, Japanese-en (Japanese with English messages), Korean,
+# Korean-en, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Russian,
+# Serbian, Slovak, Slovene, Spanish, Swedish, and Ukrainian.
OUTPUT_LANGUAGE = English
-# This tag can be used to specify the encoding used in the generated output.
-# The encoding is not always determined by the language that is chosen,
-# but also whether or not the output is meant for Windows or non-Windows users.
-# In case there is a difference, setting the USE_WINDOWS_ENCODING tag to YES
-# forces the Windows encoding (this is the default for the Windows binary),
-# whereas setting the tag to NO uses a Unix-style encoding (the default for
-# all platforms other than Windows).
-
-USE_WINDOWS_ENCODING = NO
-
# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will
# include brief member descriptions after the members that are listed in
# the file and class documentation (similar to JavaDoc).
@@ -102,13 +98,13 @@ ALWAYS_DETAILED_SEC = NO
# members were ordinary class members. Constructors, destructors and assignment
# operators of the base classes will not be shown.
-INLINE_INHERITED_MEMB = YES
+INLINE_INHERITED_MEMB = NO
# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full
# path before files name in the file list and in the header files. If set
# to NO the shortest path that makes the file name unique will be used.
-FULL_PATH_NAMES = NO
+FULL_PATH_NAMES = YES
# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag
# can be used to strip a user-defined part of the path. Stripping is
@@ -137,10 +133,18 @@ SHORT_NAMES = NO
# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen
# will interpret the first line (until the first dot) of a JavaDoc-style
# comment as the brief description. If set to NO, the JavaDoc
-# comments will behave just like the Qt-style comments (thus requiring an
-# explicit @brief command for a brief description.
+# comments will behave just like regular Qt-style comments
+# (thus requiring an explicit @brief command for a brief description.)
+
+JAVADOC_AUTOBRIEF = NO
-JAVADOC_AUTOBRIEF = YES
+# If the QT_AUTOBRIEF tag is set to YES then Doxygen will
+# interpret the first line (until the first dot) of a Qt-style
+# comment as the brief description. If set to NO, the comments
+# will behave just like regular Qt-style comments (thus requiring
+# an explicit \brief command for a brief description.)
+
+QT_AUTOBRIEF = NO
# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen
# treat a multi-line C++ special comment block (i.e. a block of //! or ///
@@ -155,7 +159,7 @@ MULTILINE_CPP_IS_BRIEF = NO
# If set to NO, the detailed description appears after the member
# documentation.
-DETAILS_AT_TOP = YES
+DETAILS_AT_TOP = NO
# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented
# member inherits the documentation from any documented member that it
@@ -163,13 +167,6 @@ DETAILS_AT_TOP = YES
INHERIT_DOCS = YES
-# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
-# tag is set to YES, then doxygen will reuse the documentation of the first
-# member in the group (if any) for the other members of the group. By default
-# all members of a group must be documented explicitly.
-
-DISTRIBUTE_GROUP_DOC = NO
-
# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce
# a new page for each member. If set to NO, the documentation of a member will
# be part of the file/class/namespace that contains it.
@@ -197,8 +194,8 @@ ALIASES =
OPTIMIZE_OUTPUT_FOR_C = NO
-# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java sources
-# only. Doxygen will then generate output that is more tailored for Java.
+# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java
+# sources only. Doxygen will then generate output that is more tailored for Java.
# For instance, namespaces will be presented as packages, qualified scopes
# will look different, etc.
@@ -213,13 +210,25 @@ OPTIMIZE_OUTPUT_JAVA = NO
BUILTIN_STL_SUPPORT = YES
+# If you use Microsoft's C++/CLI language, you should set this option to YES to
+# enable parsing support.
+
+CPP_CLI_SUPPORT = NO
+
+# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
+# tag is set to YES, then doxygen will reuse the documentation of the first
+# member in the group (if any) for the other members of the group. By default
+# all members of a group must be documented explicitly.
+
+DISTRIBUTE_GROUP_DOC = NO
+
# Set the SUBGROUPING tag to YES (the default) to allow class member groups of
# the same type (for instance a group of public functions) to be put as a
# subgroup of that type (e.g. under the Public Functions section). Set it to
# NO to prevent subgrouping. Alternatively, this can be done per class using
# the \nosubgrouping command.
-SUBGROUPING = YES
+SUBGROUPING = NO
#---------------------------------------------------------------------------
# Build related configuration options
@@ -255,6 +264,13 @@ EXTRACT_LOCAL_CLASSES = YES
EXTRACT_LOCAL_METHODS = NO
+# If this flag is set to YES, the members of anonymous namespaces will be extracted
+# and appear in the documentation as a namespace called 'anonymous_namespace{file}',
+# where file will be replaced with the base name of the file that contains the anonymous
+# namespace. By default anonymous namespace are hidden.
+
+EXTRACT_ANON_NSPACES = NO
+
# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all
# undocumented members of documented classes, files or namespaces.
# If set to NO (the default) these members will be included in the
@@ -338,7 +354,7 @@ SORT_BRIEF_DOCS = NO
# Note: This option applies only to the class list, not to the
# alphabetical list.
-SORT_BY_SCOPE_NAME = YES
+SORT_BY_SCOPE_NAME = NO
# The GENERATE_TODOLIST tag can be used to enable (YES) or
# disable (NO) the todo list. This list is created by putting \todo
@@ -387,7 +403,7 @@ SHOW_USED_FILES = YES
# If the sources in your project are distributed over multiple directories
# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy
-# in the documentation.
+# in the documentation. The default is NO.
SHOW_DIRECTORIES = YES
@@ -396,10 +412,10 @@ SHOW_DIRECTORIES = YES
# version control system). Doxygen will invoke the program by executing (via
# popen()) the command <command> <input-file>, where <command> is the value of
# the FILE_VERSION_FILTER tag, and <input-file> is the name of an input file
-# provided by doxygen. Whatever the progam writes to standard output
+# provided by doxygen. Whatever the program writes to standard output
# is used as the file version. See the manual for examples.
-FILE_VERSION_FILTER =
+FILE_VERSION_FILTER =
#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
@@ -461,14 +477,21 @@ WARN_LOGFILE =
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
-INPUT = ../paludis ../paludis/args ../paludis/environments ../paludis/environments/no_config ../paludis/environments/adapted ../paludis/environments/test ../paludis/fetchers ../paludis/repositories/fake ../paludis/selinux ../paludis/syncers ../paludis/util ../doc ../doc/examples
+INPUT = ../../../paludis ../../../paludis/args ../../../paludis/environments ../../../paludis/environments/no_config ../../../paludis/environments/adapted ../../../paludis/environments/test ../../../paludis/fetchers ../../../paludis/repositories/fake ../../../paludis/selinux ../../../paludis/syncers ../../../paludis/util ./ ./examples/
+
+# This tag can be used to specify the character encoding of the source files that
+# doxygen parses. Internally doxygen uses the UTF-8 encoding, which is also the default
+# input encoding. Doxygen uses libiconv (or the iconv built into libc) for the transcoding.
+# See http://www.gnu.org/software/libiconv for the list of possible encodings.
+
+INPUT_ENCODING = UTF-8
# If the value of the INPUT tag contains directories, you can use the
# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
# and *.h) to filter out the source-files in the directories. If left
# blank the following patterns are tested:
# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx
-# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm
+# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py
FILE_PATTERNS = *.hh *.doxygen example_*.cc
@@ -482,7 +505,7 @@ RECURSIVE = NO
# excluded from the INPUT source files. This way you can easily exclude a
# subdirectory from a directory tree whose root is specified with the INPUT tag.
-EXCLUDE =
+EXCLUDE =
# The EXCLUDE_SYMLINKS tag can be used select whether or not files or
# directories that are symbolic links (a Unix filesystem feature) are excluded
@@ -492,15 +515,24 @@ EXCLUDE_SYMLINKS = YES
# If the value of the INPUT tag contains directories, you can use the
# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude
-# certain files from those directories.
+# certain files from those directories. Note that the wildcards are matched
+# against the file with absolute path, so to exclude all test directories
+# for example use the pattern */test/*
EXCLUDE_PATTERNS = *-sr.* *-se.*
+# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
+# (namespaces, classes, functions, etc.) that should be excluded from the output.
+# The symbol name can be a fully qualified name, a word, or if the wildcard * is used,
+# a substring. Examples: ANamespace, AClass, AClass::ANamespace, ANamespace::*Test
+
+EXCLUDE_SYMBOLS = *_GUARD_*
+
# The EXAMPLE_PATH tag can be used to specify one or more files or
# directories that contain example code fragments that are included (see
# the \include command).
-EXAMPLE_PATH = ../ ./examples/
+EXAMPLE_PATH = ./examples
# If the value of the EXAMPLE_PATH tag contains directories, you can use the
# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
@@ -539,7 +571,7 @@ INPUT_FILTER =
# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER
# is applied to all files.
-FILTER_PATTERNS =
+FILTER_PATTERNS =
# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
# INPUT_FILTER) will be used to filter the input files when producing source
@@ -554,7 +586,9 @@ FILTER_SOURCE_FILES = NO
# If the SOURCE_BROWSER tag is set to YES then a list of source files will
# be generated. Documented entities will be cross-referenced with these sources.
# Note: To get rid of all source code in the generated output, make sure also
-# VERBATIM_HEADERS is set to NO.
+# VERBATIM_HEADERS is set to NO. If you have enabled CALL_GRAPH or CALLER_GRAPH
+# then you must also enable this option. If you don't then doxygen will produce
+# a warning and turn it on anyway
SOURCE_BROWSER = NO
@@ -581,6 +615,21 @@ REFERENCED_BY_RELATION = YES
REFERENCES_RELATION = YES
+# If the REFERENCES_LINK_SOURCE tag is set to YES (the default)
+# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from
+# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will
+# link to the source code. Otherwise they will link to the documentstion.
+
+REFERENCES_LINK_SOURCE = YES
+
+# If the USE_HTAGS tag is set to YES then the references to source code
+# will point to the HTML generated by the htags(1) tool instead of doxygen
+# built-in source browser. The htags tool is part of GNU's global source
+# tagging system (see http://www.gnu.org/software/global/global.html). You
+# will need version 4.8.6 or higher.
+
+USE_HTAGS = NO
+
# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen
# will generate a verbatim copy of the header file for each class for
# which an include is specified. Set to NO to disable this.
@@ -608,7 +657,7 @@ COLS_IN_ALPHA_INDEX = 5
# The IGNORE_PREFIX tag can be used to specify one or more prefixes that
# should be ignored while generating the index headers.
-IGNORE_PREFIX =
+IGNORE_PREFIX =
#---------------------------------------------------------------------------
# configuration options related to the HTML output
@@ -623,7 +672,7 @@ GENERATE_HTML = YES
# If a relative path is entered the value of OUTPUT_DIRECTORY will be
# put in front of it. If left blank `html' will be used as the default path.
-HTML_OUTPUT = html
+HTML_OUTPUT = doxygen
# The HTML_FILE_EXTENSION tag can be used to specify the file extension for
# each generated HTML page (for example: .htm,.php,.asp). If it is left blank
@@ -635,13 +684,13 @@ HTML_FILE_EXTENSION = .html
# each generated HTML page. If it is left blank doxygen will generate a
# standard header.
-HTML_HEADER = header.html
+HTML_HEADER =
# The HTML_FOOTER tag can be used to specify a personal HTML footer for
# each generated HTML page. If it is left blank doxygen will generate a
# standard footer.
-HTML_FOOTER = footer.html
+HTML_FOOTER =
# The HTML_STYLESHEET tag can be used to specify a user-defined cascading
# style sheet that is used by each HTML page. It can be used to
@@ -650,7 +699,7 @@ HTML_FOOTER = footer.html
# the style sheet file to the HTML output directory, so don't put your own
# stylesheet in the HTML output directory as well, or it will be erased!
-HTML_STYLESHEET = paludis.css
+HTML_STYLESHEET =
# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes,
# files or namespaces will be aligned in HTML using tables. If set to
@@ -665,6 +714,14 @@ HTML_ALIGN_MEMBERS = YES
GENERATE_HTMLHELP = NO
+# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML
+# documentation will contain sections that can be hidden and shown after the
+# page has loaded. For this to work a browser that supports
+# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox
+# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari).
+
+HTML_DYNAMIC_SECTIONS = YES
+
# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can
# be used to specify the file name of the resulting .chm file. You
# can add a path in front of the file if the result should not be
@@ -700,7 +757,7 @@ TOC_EXPAND = NO
# top of each HTML page. The value NO (the default) enables the index and
# the value YES disables it.
-DISABLE_INDEX = YES
+DISABLE_INDEX = NO
# This tag can be used to set the number of enum values (range [1..20])
# that doxygen will group on one line in the generated HTML documentation.
@@ -963,13 +1020,13 @@ ENABLE_PREPROCESSING = YES
# compilation will be performed. Macro expansion can be done in a controlled
# way by setting EXPAND_ONLY_PREDEF to YES.
-MACRO_EXPANSION = NO
+MACRO_EXPANSION = YES
# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
# then the macro expansion is limited to the macros specified with the
-# PREDEFINED and EXPAND_AS_PREDEFINED tags.
+# PREDEFINED and EXPAND_AS_DEFINED tags.
-EXPAND_ONLY_PREDEF = NO
+EXPAND_ONLY_PREDEF = YES
# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
# in the INCLUDE_PATH (see below) will be search if a #include is found.
@@ -980,15 +1037,14 @@ SEARCH_INCLUDES = YES
# contain include files that are not input files but should be processed by
# the preprocessor.
-INCLUDE_PATH = ../
+INCLUDE_PATH = ../../../
# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
# patterns (like *.h and *.hpp) to filter out the header-files in the
# directories. If left blank, the patterns specified with FILE_PATTERNS will
# be used.
-# This doesn't seem to change anything..
-INCLUDE_FILE_PATTERNS = *-sr.* *-se.*
+INCLUDE_FILE_PATTERNS =
# The PREDEFINED tag can be used to specify one or more macro names that
# are defined before the preprocessor is started (similar to the -D option of
@@ -1034,12 +1090,12 @@ SKIP_FUNCTION_MACROS = YES
# If a tag file is not located in the directory in which doxygen
# is run, you must also specify the path to the tagfile here.
-TAGFILES = @DOXYGEN_TAG_FILES@
+TAGFILES = @DOXYGEN_TAG_FILES@
# When a file name is specified after GENERATE_TAGFILE, doxygen will create
# a tag file that is based on the input files it reads.
-GENERATE_TAGFILE =
+GENERATE_TAGFILE = paludis.tag
# If the ALLEXTERNALS tag is set to YES all external classes will be listed
# in the class index. If set to NO only the inherited external classes
@@ -1051,7 +1107,7 @@ ALLEXTERNALS = NO
# in the modules index. If set to NO, only the current project's groups will
# be listed.
-EXTERNAL_GROUPS = NO
+EXTERNAL_GROUPS = YES
# The PERL_PATH should be the absolute path and name of the perl script
# interpreter (i.e. the result of `which perl').
@@ -1071,6 +1127,14 @@ PERL_PATH = /usr/bin/perl
CLASS_DIAGRAMS = YES
+# You can define message sequence charts within doxygen comments using the \msc
+# command. Doxygen will then run the mscgen tool (see http://www.mcternan.me.uk/mscgen/) to
+# produce the chart and insert it in the documentation. The MSCGEN_PATH tag allows you to
+# specify the directory where the mscgen tool resides. If left empty the tool is assumed to
+# be found in the default search path.
+
+MSCGEN_PATH =
+
# If set to YES, the inheritance and collaboration graphs will hide
# inheritance and usage relations if the target is undocumented
# or is not a class.
@@ -1096,12 +1160,12 @@ CLASS_GRAPH = YES
# indirect implementation dependencies (inheritance, containment, and
# class references variables) of the class with other documented classes.
-COLLABORATION_GRAPH = NO
+COLLABORATION_GRAPH = YES
# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen
# will generate a graph for groups, showing the direct groups dependencies
-GROUP_GRAPHS = NO
+GROUP_GRAPHS = YES
# If the UML_LOOK tag is set to YES doxygen will generate inheritance and
# collaboration diagrams in a style similar to the OMG's Unified Modeling
@@ -1112,7 +1176,7 @@ UML_LOOK = NO
# If set to YES, the inheritance and collaboration graphs will show the
# relations between templates and their instances.
-TEMPLATE_RELATIONS = NO
+TEMPLATE_RELATIONS = YES
# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT
# tags are set to YES then doxygen will generate a graph for each documented
@@ -1128,7 +1192,7 @@ INCLUDE_GRAPH = YES
INCLUDED_BY_GRAPH = YES
-# If the CALL_GRAPH and HAVE_DOT tags are set to YES then doxygen will
+# If the CALL_GRAPH, SOURCE_BROWSER and HAVE_DOT tags are set to YES then doxygen will
# generate a call dependency graph for every global function or class method.
# Note that enabling this option will significantly increase the time of a run.
# So in most cases it will be better to enable call graphs for selected
@@ -1136,6 +1200,14 @@ INCLUDED_BY_GRAPH = YES
CALL_GRAPH = NO
+# If the CALLER_GRAPH, SOURCE_BROWSER and HAVE_DOT tags are set to YES then doxygen will
+# generate a caller dependency graph for every global function or class method.
+# Note that enabling this option will significantly increase the time of a run.
+# So in most cases it will be better to enable caller graphs for selected
+# functions only using the \callergraph command.
+
+CALLER_GRAPH = NO
+
# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen
# will graphical hierarchy of all classes instead of a textual one.
@@ -1165,31 +1237,23 @@ DOT_PATH =
DOTFILE_DIRS =
-# The MAX_DOT_GRAPH_WIDTH tag can be used to set the maximum allowed width
-# (in pixels) of the graphs generated by dot. If a graph becomes larger than
-# this value, doxygen will try to truncate the graph, so that it fits within
-# the specified constraint. Beware that most browsers cannot cope with very
-# large images.
-
-MAX_DOT_GRAPH_WIDTH = 1024
-
-# The MAX_DOT_GRAPH_HEIGHT tag can be used to set the maximum allows height
-# (in pixels) of the graphs generated by dot. If a graph becomes larger than
-# this value, doxygen will try to truncate the graph, so that it fits within
-# the specified constraint. Beware that most browsers cannot cope with very
-# large images.
+# The MAX_DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of
+# nodes that will be shown in the graph. If the number of nodes in a graph
+# becomes larger than this value, doxygen will truncate the graph, which is
+# visualized by representing a node as a red box. Note that doxygen if the number
+# of direct children of the root node in a graph is already larger than
+# MAX_DOT_GRAPH_NOTES then the graph will not be shown at all. Also note
+# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH.
-MAX_DOT_GRAPH_HEIGHT = 1024
+DOT_GRAPH_MAX_NODES = 50
# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the
# graphs generated by dot. A depth value of 3 means that only nodes reachable
# from the root by following a path via at most 3 edges will be shown. Nodes
# that lay further from the root node will be omitted. Note that setting this
# option to 1 or 2 may greatly reduce the computation time needed for large
-# code bases. Also note that a graph may be further truncated if the graph's
-# image dimensions are not sufficient to fit the graph (see MAX_DOT_GRAPH_WIDTH
-# and MAX_DOT_GRAPH_HEIGHT). If 0 is used for the depth value (the default),
-# the graph is not depth-constrained.
+# code bases. Also note that the size of a graph can be further restricted by
+# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction.
MAX_DOT_GRAPH_DEPTH = 0
@@ -1199,7 +1263,7 @@ MAX_DOT_GRAPH_DEPTH = 0
# badly anti-aliased labels on the edges of a graph (i.e. they become hard to
# read).
-DOT_TRANSPARENT = YES
+DOT_TRANSPARENT = NO
# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output
# files in one run (i.e. multiple -o and -T options on the command line). This
@@ -1229,5 +1293,3 @@ DOT_CLEANUP = YES
SEARCHENGINE = NO
-
-
diff --git a/doc/examples/Makefile.am b/doc/api/cplusplus/examples/Makefile.am
index 238fc6c..6773fdc 100644
--- a/doc/examples/Makefile.am
+++ b/doc/api/cplusplus/examples/Makefile.am
@@ -177,10 +177,8 @@ example_name_LDFLAGS = \
built-sources : $(BUILT_SOURCES)
for s in `echo $(SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s built-sources || exit 1 ; done
-distcheck-deps-local : $(DISTCHECK_DEPS)
-
-distcheck-deps : distcheck-deps-subdirs
+distcheck-deps : $(DISTCHECK_DEPS) distcheck-deps-subdirs
distcheck-deps-subdirs :
- for s in $(SUBDIRS) . ; do if test x$$s = x. ; then make distcheck-deps-local || exit 1 ; \
- else $(MAKE) -C $$s distcheck-deps || exit 1 ; fi ; done
+ for s in `echo $(SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s distcheck-deps || exit 1 ; done
+
diff --git a/doc/examples/example_about.cc b/doc/api/cplusplus/examples/example_about.cc
index 2ef9156..2ef9156 100644
--- a/doc/examples/example_about.cc
+++ b/doc/api/cplusplus/examples/example_about.cc
diff --git a/doc/examples/example_action.cc b/doc/api/cplusplus/examples/example_action.cc
index e00f42f..e00f42f 100644
--- a/doc/examples/example_action.cc
+++ b/doc/api/cplusplus/examples/example_action.cc
diff --git a/doc/examples/example_command_line.cc b/doc/api/cplusplus/examples/example_command_line.cc
index 08ef3d5..08ef3d5 100644
--- a/doc/examples/example_command_line.cc
+++ b/doc/api/cplusplus/examples/example_command_line.cc
diff --git a/doc/examples/example_command_line.hh b/doc/api/cplusplus/examples/example_command_line.hh
index 62a4d73..62a4d73 100644
--- a/doc/examples/example_command_line.hh
+++ b/doc/api/cplusplus/examples/example_command_line.hh
diff --git a/doc/examples/example_contents.cc b/doc/api/cplusplus/examples/example_contents.cc
index f728c24..f728c24 100644
--- a/doc/examples/example_contents.cc
+++ b/doc/api/cplusplus/examples/example_contents.cc
diff --git a/doc/examples/example_dep_label.cc b/doc/api/cplusplus/examples/example_dep_label.cc
index 7429e77..7429e77 100644
--- a/doc/examples/example_dep_label.cc
+++ b/doc/api/cplusplus/examples/example_dep_label.cc
diff --git a/doc/examples/example_dep_spec.cc b/doc/api/cplusplus/examples/example_dep_spec.cc
index 129c2b3..129c2b3 100644
--- a/doc/examples/example_dep_spec.cc
+++ b/doc/api/cplusplus/examples/example_dep_spec.cc
diff --git a/doc/examples/example_dep_spec_flattener.cc b/doc/api/cplusplus/examples/example_dep_spec_flattener.cc
index 1974bce..1974bce 100644
--- a/doc/examples/example_dep_spec_flattener.cc
+++ b/doc/api/cplusplus/examples/example_dep_spec_flattener.cc
diff --git a/doc/examples/example_dep_tag.cc b/doc/api/cplusplus/examples/example_dep_tag.cc
index 17e1a3d..17e1a3d 100644
--- a/doc/examples/example_dep_tag.cc
+++ b/doc/api/cplusplus/examples/example_dep_tag.cc
diff --git a/doc/examples/example_dep_tree.cc b/doc/api/cplusplus/examples/example_dep_tree.cc
index defa451..defa451 100644
--- a/doc/examples/example_dep_tree.cc
+++ b/doc/api/cplusplus/examples/example_dep_tree.cc
diff --git a/doc/examples/example_environment.cc b/doc/api/cplusplus/examples/example_environment.cc
index 5b09235..5b09235 100644
--- a/doc/examples/example_environment.cc
+++ b/doc/api/cplusplus/examples/example_environment.cc
diff --git a/doc/examples/example_formatter.cc b/doc/api/cplusplus/examples/example_formatter.cc
index 51582a8..51582a8 100644
--- a/doc/examples/example_formatter.cc
+++ b/doc/api/cplusplus/examples/example_formatter.cc
diff --git a/doc/examples/example_mask.cc b/doc/api/cplusplus/examples/example_mask.cc
index 1b60e77..1b60e77 100644
--- a/doc/examples/example_mask.cc
+++ b/doc/api/cplusplus/examples/example_mask.cc
diff --git a/doc/examples/example_match_package.cc b/doc/api/cplusplus/examples/example_match_package.cc
index dbe5404..dbe5404 100644
--- a/doc/examples/example_match_package.cc
+++ b/doc/api/cplusplus/examples/example_match_package.cc
diff --git a/doc/examples/example_metadata_key.cc b/doc/api/cplusplus/examples/example_metadata_key.cc
index ea3a355..ea3a355 100644
--- a/doc/examples/example_metadata_key.cc
+++ b/doc/api/cplusplus/examples/example_metadata_key.cc
diff --git a/doc/examples/example_name.cc b/doc/api/cplusplus/examples/example_name.cc
index a56a177..a56a177 100644
--- a/doc/examples/example_name.cc
+++ b/doc/api/cplusplus/examples/example_name.cc
diff --git a/doc/examples/example_package_database.cc b/doc/api/cplusplus/examples/example_package_database.cc
index 6adb7a6..6adb7a6 100644
--- a/doc/examples/example_package_database.cc
+++ b/doc/api/cplusplus/examples/example_package_database.cc
diff --git a/doc/examples/example_package_id.cc b/doc/api/cplusplus/examples/example_package_id.cc
index b684e3a..b684e3a 100644
--- a/doc/examples/example_package_id.cc
+++ b/doc/api/cplusplus/examples/example_package_id.cc
diff --git a/doc/examples/example_query.cc b/doc/api/cplusplus/examples/example_query.cc
index 161e8cc..161e8cc 100644
--- a/doc/examples/example_query.cc
+++ b/doc/api/cplusplus/examples/example_query.cc
diff --git a/doc/examples/example_query_delegate.cc b/doc/api/cplusplus/examples/example_query_delegate.cc
index b006eef..b006eef 100644
--- a/doc/examples/example_query_delegate.cc
+++ b/doc/api/cplusplus/examples/example_query_delegate.cc
diff --git a/doc/examples/example_repository.cc b/doc/api/cplusplus/examples/example_repository.cc
index 07608a4..07608a4 100644
--- a/doc/examples/example_repository.cc
+++ b/doc/api/cplusplus/examples/example_repository.cc
diff --git a/doc/examples/example_stringify_formatter.cc b/doc/api/cplusplus/examples/example_stringify_formatter.cc
index 6f5d3b6..6f5d3b6 100644
--- a/doc/examples/example_stringify_formatter.cc
+++ b/doc/api/cplusplus/examples/example_stringify_formatter.cc
diff --git a/doc/examples/example_version_operator.cc b/doc/api/cplusplus/examples/example_version_operator.cc
index 1bea6e2..1bea6e2 100644
--- a/doc/examples/example_version_operator.cc
+++ b/doc/api/cplusplus/examples/example_version_operator.cc
diff --git a/doc/examples/example_version_spec.cc b/doc/api/cplusplus/examples/example_version_spec.cc
index 186fd79..186fd79 100644
--- a/doc/examples/example_version_spec.cc
+++ b/doc/api/cplusplus/examples/example_version_spec.cc
diff --git a/doc/doc_main.doxygen b/doc/api/cplusplus/groups.doxygen
index 0b4c2ae..c81a096 100644
--- a/doc/doc_main.doxygen
+++ b/doc/api/cplusplus/groups.doxygen
@@ -135,7 +135,7 @@ using namespace paludis;
* - \ref example_metadata_key.cc "example_metadata_key.cc"
*/
-/** \defgroup g_repository "Repository"
+/** \defgroup g_repository Repository
*
* \ingroup g_paludis
*
@@ -147,7 +147,7 @@ using namespace paludis;
* - \ref example_repository.cc "example_repository.cc"
*/
-/** \defgroup g_query "Query"
+/** \defgroup g_query Query
*
* \ingroup g_package_database
*
@@ -161,7 +161,7 @@ using namespace paludis;
* - \ref example_match_package.cc "example_match_package.cc"
*/
-/** \defgroup g_package_database "Package Database"
+/** \defgroup g_package_database Package Database
*
* \ingroup g_paludis
*
@@ -175,7 +175,7 @@ using namespace paludis;
* - \ref example_query_delegate.cc "example_query_delegate.cc"
*/
-/** \defgroup g_names "Names and Versions"
+/** \defgroup g_names Names and Versions
*
* \ingroup g_paludis
*
@@ -190,7 +190,7 @@ using namespace paludis;
* - \ref example_version_operator.cc "example_version_operator.cc"
*/
-/** \defgroup g_dep_list "Dependency Resolution"
+/** \defgroup g_dep_list Dependency Resolution
*
* \ingroup g_paludis
*
@@ -203,7 +203,7 @@ using namespace paludis;
* - None at this time.
*/
-/** \defgroup g_tasks "Tasks"
+/** \defgroup g_tasks Tasks
*
* \ingroup g_paludis
*
@@ -218,7 +218,7 @@ using namespace paludis;
* - None at this time.
*/
-/** \defgroup g_hooks "Hooks"
+/** \defgroup g_hooks Hooks
*
* \ingroup g_paludis
*
@@ -230,7 +230,7 @@ using namespace paludis;
* - None at this time.
*/
-/** \defgroup g_digests "Digests"
+/** \defgroup g_digests Digests
*
* \ingroup g_paludis
*
@@ -241,7 +241,7 @@ using namespace paludis;
* - None at this time.
*/
-/** \defgroup g_utils "Utilities"
+/** \defgroup g_utils Utilities
*
* \ingroup g_paludis
*
@@ -253,7 +253,7 @@ using namespace paludis;
* - None at this time.
*/
-/** \defgroup g_config_file "Configuration Files"
+/** \defgroup g_config_file Configuration Files
*
* \ingroup g_utils
*
@@ -265,7 +265,7 @@ using namespace paludis;
* - None at this time.
*/
-/** \defgroup g_strings "Strings"
+/** \defgroup g_strings Strings
*
* \ingroup g_utils
*
@@ -277,7 +277,7 @@ using namespace paludis;
* - None at this time.
*/
-/** \defgroup g_fs "Filesystem"
+/** \defgroup g_fs Filesystem
*
* \ingroup g_utils
*
@@ -289,7 +289,7 @@ using namespace paludis;
* - None at this time.
*/
-/** \defgroup g_data_structures "Data Structures"
+/** \defgroup g_data_structures Data Structures
*
* \ingroup g_utils
*
@@ -300,7 +300,7 @@ using namespace paludis;
* - None at this time.
*/
-/** \defgroup g_iterator "Iterators"
+/** \defgroup g_iterator Iterators
*
* \ingroup g_utils
*
@@ -311,7 +311,7 @@ using namespace paludis;
* - None at this time.
*/
-/** \defgroup g_oo "OO Design Helpers"
+/** \defgroup g_oo OO Design Helpers
*
* \ingroup g_utils
*
@@ -322,7 +322,7 @@ using namespace paludis;
* - None at this time.
*/
-/** \defgroup g_log "Logging"
+/** \defgroup g_log Logging
*
* \ingroup g_utils
*
@@ -333,7 +333,7 @@ using namespace paludis;
* - None at this time.
*/
-/** \defgroup g_system "System"
+/** \defgroup g_system System
*
* \ingroup g_utils
*
@@ -344,7 +344,7 @@ using namespace paludis;
* - None at this time.
*/
-/** \defgroup g_visitors "Visitors"
+/** \defgroup g_visitors Visitors
*
* \ingroup g_utils
*
@@ -356,7 +356,7 @@ using namespace paludis;
* - None at this time.
*/
-/** \defgroup g_threads "Threads"
+/** \defgroup g_threads Threads
*
* \ingroup g_utils
*
diff --git a/doc/doc_mainpage.doxygen b/doc/api/cplusplus/main_page.doxygen
index a938998..a54c417 100644
--- a/doc/doc_mainpage.doxygen
+++ b/doc/api/cplusplus/main_page.doxygen
@@ -4,11 +4,17 @@
This is the Paludis core API documentation.
+To find your way around:
+
+- Use the <a href="modules.html">Modules</a> link, rather than trying to browse through
+ raw class lists.
+- See the <a href="examples.html">Examples</a>.
+
Some classes you may find useful:
- paludis::Environment, which is usually created using paludis::EnvironmentMaker
- paludis::PackageDatabase
- paludis::Repository and the associated interface classes
-- paludis::VersionMetadata
+- paludis::PackageID
*/
diff --git a/doc/api/cplusplus/namespaces.doxygen b/doc/api/cplusplus/namespaces.doxygen
new file mode 100644
index 0000000..1888fbf
--- /dev/null
+++ b/doc/api/cplusplus/namespaces.doxygen
@@ -0,0 +1,14 @@
+/* vim: set ft=cpp tw=80 sw=4 et : */
+
+/** \namespace paludis
+ * Paludis library code.
+ *
+ * \ingroup g_paludis
+ */
+
+/** \namespace paludis::args
+ * Commandline argument handling.
+ *
+ * \ingroup g_args
+ */
+
diff --git a/doc/doc_references.doxygen b/doc/api/cplusplus/references.doxygen
index 3bc3e59..3bc3e59 100644
--- a/doc/doc_references.doxygen
+++ b/doc/api/cplusplus/references.doxygen
diff --git a/doc/api/python/Makefile.am b/doc/api/python/Makefile.am
new file mode 100644
index 0000000..e412f64
--- /dev/null
+++ b/doc/api/python/Makefile.am
@@ -0,0 +1,13 @@
+SUBDIRS = .
+
+CLEANFILES = *~ gmon.out *.gcov *.gcno *.gcda
+MAINTAINERCLEANFILES = Makefile.in
+
+built-sources : $(BUILT_SOURCES)
+ for s in `echo $(SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s built-sources || exit 1 ; done
+
+distcheck-deps : $(DISTCHECK_DEPS) distcheck-deps-subdirs
+
+distcheck-deps-subdirs :
+ for s in `echo $(DIST_SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s distcheck-deps || exit 1 ; done
+
diff --git a/doc/api/ruby/Makefile.am b/doc/api/ruby/Makefile.am
new file mode 100644
index 0000000..e412f64
--- /dev/null
+++ b/doc/api/ruby/Makefile.am
@@ -0,0 +1,13 @@
+SUBDIRS = .
+
+CLEANFILES = *~ gmon.out *.gcov *.gcno *.gcda
+MAINTAINERCLEANFILES = Makefile.in
+
+built-sources : $(BUILT_SOURCES)
+ for s in `echo $(SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s built-sources || exit 1 ; done
+
+distcheck-deps : $(DISTCHECK_DEPS) distcheck-deps-subdirs
+
+distcheck-deps-subdirs :
+ for s in `echo $(DIST_SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s distcheck-deps || exit 1 ; done
+
diff --git a/doc/authors.html.skel b/doc/authors.html.skel
deleted file mode 100644
index 7a868ce..0000000
--- a/doc/authors.html.skel
+++ /dev/null
@@ -1,24 +0,0 @@
-<!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: Release Notes</title>
-<link rel="stylesheet" href="paludis.css" type="text/css" />
-</head>
-<body>
-@HEADER@
-
- <h1>Paludis, the Other Package Mangler</h1>
-
- <h2>Authors</h2>
-
-@AUTHORS@
-
- </li></ul>
-
-@FOOTER@
-</body>
-</html>
-
-
-
diff --git a/doc/cachefiles.html.skel b/doc/cachefiles.html.skel
deleted file mode 100644
index fb3875a..0000000
--- a/doc/cachefiles.html.skel
+++ /dev/null
@@ -1,96 +0,0 @@
-<!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>Cache Files</h2>
-
-<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.</p>
-
-<h3>The Provides Cache</h3>
-
-<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.</p>
-
-<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.</p>
-
-<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.</p>
-
-<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 if it has started to modify the live filesystem.</p>
-
-<h3>The Names Cache</h3>
-
-<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>ebuild</code> and
-<code>vdb</code> repository formats. This makes certain common tasks much
-faster.</p>
-
-<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.</p>
-
-<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 ebuild 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 if
- has started to modify the live filesystem.</p>
-
-<h3>The Metadata Cache</h3>
-
-<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.</p>
-
-<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 an ebuild 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.</p>
-
-@FOOTER@
-</body>
-</html>
-
diff --git a/doc/changelog.html.skel b/doc/changelog.html.skel
deleted file mode 100644
index f648a68..0000000
--- a/doc/changelog.html.skel
+++ /dev/null
@@ -1,26 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<!-- vim: set ft=html : -->
-<html lang="en" xml:lang="en">
-<head>
-<title>Paludis, the Other Package Mangler: Release Notes</title>
-<link rel="stylesheet" href="paludis.css" type="text/css" />
-</head>
-<body>
-@HEADER@
-
- <h1>Paludis, the Other Package Mangler</h1>
-
- <h2>ChangeLog</h2>
-
-<dl>
-@CHANGELOG@
-</dd></dl>
-
-
-@FOOTER@
-</body>
-</html>
-
-
-
diff --git a/doc/clients/Makefile.am b/doc/clients/Makefile.am
new file mode 100644
index 0000000..e412f64
--- /dev/null
+++ b/doc/clients/Makefile.am
@@ -0,0 +1,13 @@
+SUBDIRS = .
+
+CLEANFILES = *~ gmon.out *.gcov *.gcno *.gcda
+MAINTAINERCLEANFILES = Makefile.in
+
+built-sources : $(BUILT_SOURCES)
+ for s in `echo $(SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s built-sources || exit 1 ; done
+
+distcheck-deps : $(DISTCHECK_DEPS) distcheck-deps-subdirs
+
+distcheck-deps-subdirs :
+ for s in `echo $(DIST_SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s distcheck-deps || exit 1 ; done
+
diff --git a/doc/configuration.html.skel b/doc/configuration.html.skel
deleted file mode 100644
index 3a32ea0..0000000
--- a/doc/configuration.html.skel
+++ /dev/null
@@ -1,406 +0,0 @@
-<!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.conf</code> exists in this directory, Paludis uses
-this file to determine the real configuration directory. The <code>specpath.conf</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.conf</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.conf</code> file is present, the original directory is
-used.</p>
-
-<h3>The environment.conf File</h3>
-
-<p>The <code>environment.conf</code> file controls various options related to
-general operation. Recognised keys are:</p>
-
-<dl>
- <dt><code>reduced_username</code></dt>
- <dd>The username to use when dropping priviledges. Defaults to
- <code>paludisbuild</code>. This user's default group (which is also called
- <code>paludisbuild</code> if you installed using ebuilds) must have read,
- write and execute access to distfiles and build directories.</dd>
-
- <dt><code>portage_compatible</code></dt>
- <dd>If set to a non-empty string, Paludis will mask any ebuild that is known
- to break Portage. Currently this means any version containing <code>-scm</code>
- or <code>-try</code> and any <code>EAPI</code> containing the string <code>paludis</code>.</dd>
-</dl>
-
-<p>If <code>environment.conf</code> does not exist and <code>environment.bash</code>
-does, Paludis executes the latter and pretends that its stdout is the content of the former.</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>spec use use use ...</code>, where
-<code>spec</code> is a package dependency specification or <a href="sets.html">package set</a>
-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>spec 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>
-
-<p>If <code>use.bash</code> exists, it is executed and its stdout is used as if
-it were appended to the main file. If a <code>use.conf.d</code> directory
-exists, any file named <code>*.conf</code> in this directory is treated as if it
-were appended to the main file, and any file named <code>*.bash</code> is
-executed and has its stdout used as if it were appended to the main file.</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>spec keyword1 keywords2 ...</code>, where <code>spec</code> is a package
-dependency specification or <a href="sets.html">set name</a> 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
-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>
-
-<p>The <code>-*</code> special keyword can be used to remove previously accepted
-keywords from a less specific match. The <code>*</code> special keyword can be
-used to accept anything.</p>
-
-<p>If <code>keywords.bash</code> exists, it is executed and its stdout is used as if
-it were appended to the main file. If a <code>keywords.conf.d</code> directory
-exists, any file named <code>*.conf</code> in this directory is treated as if it
-were appended to the main file, and any file named <code>*.bash</code> is
-executed and has its stdout used as if it were appended to the main file.</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>spec</code> or <a href="sets.html">set name</a>
-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>
-
-<p>If <code>package_mask.bash</code> exists, it is executed and its stdout is used as if
-it were appended to the main file. If a <code>package_mask.conf.d</code> directory
-exists, any file named <code>*.conf</code> in this directory is treated as if it
-were appended to the main file, and any file named <code>*.bash</code> is
-executed and has its stdout used as if it were appended to the main file.</p>
-
-<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>spec</code> or <a href="sets.html">set name</a> per line. For example:</p>
-
-<pre>
-# I need banshee 0.11.0
-=media-sound/banshee-0.11.0
-</pre>
-
-<p>If <code>package_unmask.bash</code> exists, it is executed and its stdout is used as if
-it were appended to the main file. If a <code>package_unmask.conf.d</code> directory
-exists, any file named <code>*.conf</code> in this directory is treated as if it
-were appended to the main file, and any file named <code>*.bash</code> is
-executed and has its stdout used as if it were appended to the main file.</p>
-
-<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>
-
-<p>If <code>licenses.bash</code> exists, it is executed and its stdout is used as if
-it were appended to the main file. If a <code>licenses.conf.d</code> directory
-exists, any file named <code>*.conf</code> in this directory is treated as if it
-were appended to the main file, and any file named <code>*.bash</code> is
-executed and has its stdout used as if it were appended to the main file.</p>
-
-<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>
-
-<p>Note that, for Gentoo mirrors, the last component of the URL must
-be <code>/distfiles</code>. Portage adds this automatically, so if
-you are obtaining your list of mirrors from <code>make.conf</code> or
-the <code>mirrorselect</code> tool, you will need to add it
-yourself.</p>
-
-<p>If <code>mirrors.bash</code> exists, it is executed and its stdout is used as if
-it were appended to the main file. If a <code>mirrors.conf.d</code> directory
-exists, any file named <code>*.conf</code> in this directory is treated as if it
-were appended to the main file, and any file named <code>*.bash</code> is
-executed and has its stdout used as if it were appended to the main file.</p>
-
-<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.conf</code>. All
-files must define a <code>format =</code> key; depending upon the value used, other
-optional and mandatory keys are available.</p>
-
-<p>Files named <code>*.bash</code> in the <code>repositories/</code> subdirectory
-are executed by Paludis and their stdout is used as if it were a normal repository
-<code>.conf</code> file.</p>
-
-<p>Each repository can have a key named <code>importance</code>. This is used when
-two different repositories contain an identically named and versioned package (e.g. foo/bar-1.0).
-The repository with the higher importance will always be chosen first. The normal default value for
-importance is 0, repositories which specify <code>master_repository</code> have a default
-importance of 10.</p>
-
-<p>To avoid duplication across configuration files, a file named
-<code>repository_defaults.conf</code> can be used to specify defaults (this file
-does <strong>not</strong> live in the <code>repositories/</code> subdirectory).
-Keys in this file are overridden by identically named keys in individual
-configuration files.</p>
-
-<p>If <code>repository_defaults.conf</code> does not exist and <code>repository_defaults.bash</code>
-does, Paludis executes the latter and pretends that its stdout is the content of the former.</p>
-
-<h4>ebuild Format Repositories</h4>
-
-<p>The following keys are available for <code>format = ebuild</code>:</p>
-
-<ul>
- <li><code>location</code> (mandatory), which points to the location of the
- tree.</li>
-
- <li><code>master_repository</code> (default: not used), which specifies the
- name of another ebuild format repository that is used as a 'master' for
- this repository. The master repository's location is used for the <code>PORTDIR</code>
- variable, its <code>profiles/</code> directory (not to be confused with its
- profiles) is used in addition to the repository's own and the default values
- for some of the keys below are affected.</li>
-
- <li><code>profiles</code> (mandatory), which should be a space separated list of
- directories used for profile data. Later directories have priority. Inherited from
- <code>master_repository</code> if unset.</li>
- <li><code>builddir</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. Inherited from
- <code>master_repository</code> if unset.</li>
- <li><code>eclassdirs</code> (default: any <code>master_repository</code> values,
- plus <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. This
- can be a space-separated list, in which case each will be tried in order
- until one succeeds.</li>
- <li><code>sync_options</code> (default: empty), which specifies
- additional options to pass to the syncing script. The valid options
- for each protocol are listed by <code>paludis
- --list-sync-protocols</code>. Note that options are not
- automatically passed through to the underlying sync program
- (<code>rsync</code>, <code>svn</code> etc.), you must use
- <code>--<em>program</em>-option=OPTION</code> or
- <code>--<em>program</em>-<em>action</em>-option=OPTION</code> for
- each option. If a pass-through option takes an argument, you must
- specify <code>--<em>program</em>-option=</code> for both the option
- itself and the argument. For example:
-<pre>
-# For an rsync repository, to exclude files matching patterns listed in
-# /etc/sync.exclude, and to log the transfer to the file /var/log/sync.log
-sync_options = --exclude-from=/etc/sync.exclude --rsync-option=--log-file --rsync-option=/var/log/sync.log
-# For a CVS repository, to use maximum compression for the network
-# traffic, and to disable keyword expansion
-sync_options = --cvs-option=-z9 --cvs-checkout-option=-ko
-</pre></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>. This key is deprecated, use
- <code>sync_options = --exclude-from=FILE</code> instead.</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>ebuild</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>builddir</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>builddir</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 =
- ebuild</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/configuration/Makefile.am b/doc/configuration/Makefile.am
new file mode 100644
index 0000000..e412f64
--- /dev/null
+++ b/doc/configuration/Makefile.am
@@ -0,0 +1,13 @@
+SUBDIRS = .
+
+CLEANFILES = *~ gmon.out *.gcov *.gcno *.gcda
+MAINTAINERCLEANFILES = Makefile.in
+
+built-sources : $(BUILT_SOURCES)
+ for s in `echo $(SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s built-sources || exit 1 ; done
+
+distcheck-deps : $(DISTCHECK_DEPS) distcheck-deps-subdirs
+
+distcheck-deps-subdirs :
+ for s in `echo $(DIST_SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s distcheck-deps || exit 1 ; done
+
diff --git a/doc/doc_coding_standards.doxygen b/doc/doc_coding_standards.doxygen
deleted file mode 100644
index 440d1df..0000000
--- a/doc/doc_coding_standards.doxygen
+++ /dev/null
@@ -1,180 +0,0 @@
-/* vim: set ft=cpp tw=80 sw=4 et : */
-
-/**
-\page CodingStandards Coding Standards
-
-These are rough guidelines. You should stick to these unless there's a good
-reason to do otherwise. There are lots more standards that aren't documented
-here yet -- ask for clarification as necessary.
-
-\section CodingStandardsCopyrights Copyrights and Licence
-
-Paludis is licenced under the GPLv2. Any contributions must use this licence.
-You should copy the standard licence header from another source file when
-creating new source files.
-
-Copyright is handled on a per-file basis. If you are the primary author of
-a file, you should list yourself as the copyright holder. If you make a
-substantial contribution to a source file (for example, one or more
-non-trivial classes, functions or methods), you should add yourself as a
-copyright holder on that file. You should <em>not</em> add to the copyright for
-small changes or bug fixes.
-
-Copyright years are per contributor. See, for example, paludis/fs_entry.hh for
-a file that has multiple copyright holders with different years.
-
-Substantial contributors should also list themselves in the AUTHORS file.
-
-\section CodingStandardsIndentingAndSpacing Indenting and Spacing
-
-Indents are four spaces. There are no tabs anywhere. Braces go on a line of
-their own, and may be omitted if the clarity of the code isn't affected. Make
-sure you don't include trailing whitespace.
-
-Function calls have no space before or after the parentheses. Most operators
-and built-in functions have spaces before the opening parenthesis but not
-inside. The ! operator has a space after it.
-
-For example::
-\code
-if (some_function("moo", 2))
- do_stuff("moo");
-else
-{
- // this needs some explanation
- while (end != do_other_stuff(foo) || ! foo)
- ++foo;
-}
-\endcode
-
-\section CodingStandardsSwitches Switches
-
-You'll sometimes see code like this:
-
-\code
-do
-{
- switch (my_enum)
- {
- case e_one:
- // ...
- continue;
-
- case e_two:
- // ...
- continue;
- }
-
- throw InternalError(PALUDIS_HERE, "Unexpected value for my_enum");
-} while (false);
-\endcode
-
-The reason for using this rather than a <code>default:</code> label is that the
-compiler will (or at least the compiler we use will) generate a warning if
-someone later goes and adds <code>e_three</code>, and we haven't updated our
-switch to recognise it.
-
-\section CodingStandardsComments Comments
-
-All public and protected interfaces and classes should be documented in the
-header files via Doxygen. Implementations should be documented appropriately --
-explain complicated or unobvious parts and anything that can easily be broken
-by other people. Don't bother with comments on obvious things.
-
-\section CodingStandardsNaming Naming
-
-Types are named in <code>MixedCaseNoUnderscores</code>.
-
-Variables and functions are named in <code>lower_case_with_underscores</code>.
-
-Private member variables that aren't going to end up being used anywhere
-external are <code>_prefixed_with_underscore</code>.
-
-Template values are <code>suffixed_with_underscore_</code>, and template
-typenames are <code>SuffixedAsWell_</code> (and use <code>typename</code> rather
-than <code>class</code>, \ref EffCpp item 42).
-
-The files for <code>SomeClass</code> (and any small related utilities) would be
-<code>some_class.hh</code> and <code>some_class.cc</code>. We are somewhat
-inconsistent when it comes to what warrants its own file -- originally it was
-pretty much one class per file, but then compiles started taking too long so
-it's now more like one class plus related utilities and exceptions per file.
-
-Macros are <code>PALUDIS_UPPER_CASE</code>, but they're evil (\ref TCppPL
-section 7.8, \ref EffCpp item 2) so don't use them.
-
-Very short names for loop indices and the like are fine, but prefer longer,
-self-documenting names for proper variables. For loop iterator pairs, the
-usual style is:
-
-\code
-for (MyType::Iterator i(my_container.begin()), i_end(my_container.end()) ;
- i != i_end ; ++i)
-{
- // ...
-}
-\endcode
-
-If there's a convenient standard library algorithm available, use that
-instead of a manual loop (\ref EffSTL item 43).
-
-\section CodingStandardsPointers Pointers and References
-
-Try to avoid returning raw pointer types from raw interfaces, especially if the
-programmer is expected to deallocate them manually. Make liberal use of
-<code>std::tr1::shared_ptr</code> instead -- it's low overhead and a lot less
-prone to subtle screwups. See \ref EffCpp item 18.
-
-Pass object parameters by const reference rather than pointer to const unless
-you're prepared to accept a zero pointer. Avoid pass by value except for small
-integral types. See \ref EffCpp item 20.
-
-\section CodingStandardsNamespaces Namespaces
-
-Everything under <code>paludis/</code> should be inside namespace
-<code>paludis</code>. Sometimes sub-namespaces are used where they look useful.
-
-\section CodingStandardsIncludeGuards Include Guards
-
-Include guards are <code>\#define PALUDIS_GUARD_FILE_NAME_HH 1</code>.
-
-\section CodingStandardsStandardLibrary Standard Library
-
-Never use <code>using namespace std</code>. It can bring arbitrary weirdness
-into the current namespace. It's ok to selectively introduce things from std
-where they're used a lot. See \ref TCppPL section 8.2.9.1.
-
-Make use of the standard library where suitable. It has fewer bugs than
-code you write yourself, and it may be doing clever optimisations behind
-the scenes.
-
-Remember the container member functions. Many containers have template
-constructors that take iterator pairs. Many containers have assign and
-swap methods. Use these over <code>std::copy</code>. See \ref EffSTL item
-25.
-
-Don't use <code>vector&lt;bool&gt;</code>. It's just not worth it. See
-\ref EffSTL item 18.
-
-\section CodingStandardsCasts Casts
-
-<code>dynamic_cast</code> is banned. It's slow (\ref EffCpp item 27) and a sign
-that you should be using one of visitors (\ref GoF Visitor), multiple dispatch
-(\ref MCppD chapter 11) or capability queries via a <code>get_interface</code>
-type method (for example, as described in \ref GoF Composite -- Implementation
-item 4) instead.
-
-<code>reinterpret_cast</code> is probably banned as well, unless we end up
-having to talk to some weirdly broken C libraries.
-
-There are very few legitimate uses for <code>const_cast</code>. It
-<em>might</em> be ok to use it as described in \ref EffCpp item 3. It
-<em>might</em> be ok to use it to talk to C libraries.
-
-There's nothing wrong with making appropriate use of <code>static_cast</code>.
-
-Old C style <code>(Type) variable</code> casts are banned. Function style casts
-(that is, <code>Type(value)</code>) should only be used when calling an explicit
-constructor to pass an object to a function. See \ref EffCpp item 27.
-
-*/
diff --git a/doc/doc_namespaces.doxygen b/doc/doc_namespaces.doxygen
deleted file mode 100644
index 8b8164f..0000000
--- a/doc/doc_namespaces.doxygen
+++ /dev/null
@@ -1,29 +0,0 @@
-/* vim: set ft=cpp tw=80 sw=4 et : */
-
-/** \namespace test_cases
- * Test cases.
- *
- * \ingroup Test
- */
-
-/** \namespace test
- * Test framework.
- *
- * \ingroup Test
- */
-
-/** \namespace paludis
- * Paludis library code.
- */
-
-/** \namespace paludis::args
- * Commandline argument handling.
- *
- * \ingroup Args
- */
-
-/** \namespace paludis::qa
- * QA checks.
- *
- * \ingroup Args
- */
diff --git a/doc/faq.html.skel b/doc/faq.html.skel
deleted file mode 100644
index ee46576..0000000
--- a/doc/faq.html.skel
+++ /dev/null
@@ -1,549 +0,0 @@
-<!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>FAQ</h2>
-
-<p>This document describes some of the more commonly encountered problems, issues
-and things that aren't bugs but might look like they are. Pestering anyone about
-these is liable to get you hurt.</p>
-
-<p>This document also describes some things that are not bugs or missing
-functionality. Pestering anyone about these is liable to get you hurt a lot.</p>
-
-@TOC@
-
-<h2 id="general">General Paludis Questions</h2>
-
-<h3 id="ihaveaquestion">I have an Unanswered Question</h3>
-
-<p>If you've checked the documentation, and your question really isn't answered,
-you should ask it in one of these places:</p>
-
-<ul>
- <li>The <code>#paludis</code> channel on <code>irc.freenode.net</code></li>
- <li>The <a href="https://developer.berlios.de/mail/?group_id=6360">paludis-user
- mailing list</a></li>
- <li>The <a href="http://paludis.pioto.org/trac/">bug tracker</a> will probably also be useful</li>
-</ul>
-
-<p>You are encouraged to submit an entry for this document once your question
-has been answered.</p>
-
-<h3 id="why">Why not fix Portage?</h3>
-
-<p>The Portage codebase is too broken to be fixed. It is a huge mess of
-spaghetti procedural code with no underlying design. It relies upon weird
-quirks in its own behaviour all over the place, so any change is liable to
-cause huge breakage in seemingly unrelated areas. It is almost entirely
-undocumented, and the internal names are perverse and often do not reflect what
-the code now does.</p>
-
-<h3 id="cplusplus">Why C++?</h3>
-
-<p>Because we don't have the time or the manpower to write it in C.</p>
-
-<h3 id="contribute">Contributing</h3>
-
-<p>Contributions to Paludis are welcome:</p>
-
-<ul>
- <li>Patches can be submitted via <a
- href="http://paludis.pioto.org/trac/">trac</a>. It's best to
- discuss ideas before spending too much time on the code, because we don't
- have any qualms about rejecting things we think are a bad idea.</li>
-
- <li>We could probably use some more documentation. Again, ask first.</li>
-
- <li>Translations aren't currently possible. We don't have anything against
- internationalisation in principle, but as we're not gettextised it'll be a
- fair bit of effort.</li>
-
- <li>If you're thinking about donating cash, hardware, etc., it's probably
- easiest to talk to us on IRC first. Alternatively, you can donate stuff
- using the following Amazon wishlists:
- <ul>
- <li>Ciaran McCreesh's <a href="http://www.amazon.co.uk/gp/registry/registry.html/026-3388518-6349216?ie=UTF8&amp;type=wishlist&amp;id=16LVEYP610005">Amazon.co.uk wishlist</a>.</li>
- <li>Danny van Dyk's <a href="http://www.amazon.de/gp/registry/registry.html/302-9394188-4603250?ie=UTF8&amp;type=wishlist&amp;id=1VYVUQ9CAEBM8">Amazon.de wishlist</a>.</li>
- <li>Stephen P. Bennett's <a href="https://www.amazon.co.uk/gp/registry/wishlist/3QAXX2WBNBW9W/ref=cm_reg_rd-upd/026-1190159-2009266?ie=UTF8&amp;msgid=updated">Amazon.co.uk wishlist</a>.</li>
- <li>Mike Kelly's <a href="http://www.amazon.com/gp/registry/wishlist/3LUY7EGNEJR7N/">Amazon.com wishlist</a>.</li>
- </ul></li>
-
- <li>We're pretty much ok for hosting currently.</li>
-</ul>
-
-<h2 id="howdoi">How do I...</h2>
-
-<h3 id="ccache">Use <code>ccache</code></h3>
-
-<p>To enable <code>ccache</code>, simply set the relevant variables in your
-configuration <code>bashrc</code>:</p>
-
-<pre>
-PATH="/usr/lib/ccache/bin/:${PATH}"
-CCACHE_DIR="/var/tmp/ccache"
-</pre>
-
-<h3 id="distcc">Use <code>distcc</code></h3>
-
-<p>To enable <code>distcc</code>, simply set the relevant variables in your
-configuration <code>bashrc</code>:</p>
-
-<pre>
-DISTCC_DIR="/var/tmp/paludis/.distcc"
-DISTCC_HOSTS="localhost another_host"
-PATH="/usr/lib/distcc/bin:${PATH}"
-</pre>
-
-<h3 id="defaultoptions">Specify default options</h3>
-
-<p>Often users want to specify certain options by default. Common choices include:</p>
-
-<ul>
- <li><code>--debug-build split</code>, to make debugging easier (at the cost of disk
- space)</li>
-
- <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>
-
- <li><code>--safe-resume</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>
-
-<h3 id="removeunneeded">Remove unneeded packages</h3>
-
-<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>
-
-<h3 id="unmask">Unmask a Package</h3>
-
-<p>First, you need to determine how a package is masked. The easiest way to do
-this is to use <code>paludis --query</code>. Then, if you're sure you really
-want to unmask a package, and bearing in mind that doing so might break your
-system, you need to override the mask. How to do this depends upon the mask
-reasons:</p>
-
-<dl>
- <dt>keyword</dt>
-
- <dd>You need to add an entry to your <code>keywords.conf</code> accepting
- one of the ebuild's keywords. The special <code>-*</code> keyword cannot be
- accepted this way; if an ebuild only has this in its keywords, report it
- to <a href="https://bugs.gentoo.org/show_bug.cgi?id=160519">Gentoo bug
- 160519</a> and work around it by using <code>*</code>.</dd>
-
- <dt>user mask</dt>
-
- <dd>Either remove your <code>package_mask.conf</code> entry or override it
- with <code>package_unmask.conf</code>.</dd>
-
- <dt>profile mask</dt>
-
- <dd>Override with <code>package_unmask.conf</code>.</dd>
-
- <dt>repository mask</dt>
-
- <dd>Override with <code>package_unmask.conf</code>.</dd>
-
- <dt>eapi</dt>
-
- <dd>You cannot override this mask. It indicates either a broken ebuild (if
- <code>EAPI=unknown</code> or an ebuild not supported by your current version
- of Paludis.</dd>
-
- <dt>license</dt>
-
- <dd>Accept the appropriate licences in <code>licenses.conf</code>.</dd>
-
- <dt>by association</dt>
-
- <dd>Unmask the associated package. This mask reason is currently only used
- for old style virtuals.</dd>
-</dl>
-
-<h3 id="syncfromcvs">Sync from CVS</h3>
-
-<p>Syncing from CVS requires use of either the <code>cvs+pserver</code> or the <code>cvs+ssh</code> protocol.
-The syntax for the configuration file line is
-<code>sync = cvs+ssh://username@host:/path/to/cvsroot:modulename</code>. As an example,
-for syncing with the <code>gentoo</code> repository via CVS, you would use
-<code>sync = cvs+ssh://username@cvs.gentoo.org:/var/cvsroot:gentoo-x86</code>.</p>
-
-<h3 id="syncfromsnapshot">Sync from a Gentoo tree snapshot</h3>
-
-<p>Syncing from a tarball requires the <code>tar+http</code>
-or <code>tar+ftp</code> protocol. You must also
-specify <code>sync_options = --strip-components=1</code>, as the
-Gentoo snapshots place everything under a subdirectory
-named <code>portage</code>. For example:</p>
-<pre>
-# Replace this with your favourite Gentoo mirror
-sync = tar+ftp://my.favourite.mirror/gentoo/snapshots/portage-latest.tar.bz2
-sync_options = --strip-components=1
-</pre>
-
-<h2 id="generaloperation">General Operation</h2>
-
-<h3 id="updatingdepends">Paludis does not update DEPENDs of already installed packages</h3>
-
-<p>Paludis ignores DEPENDs of already installed packages by default. If you
-need a different behaviour, use the <code>--dl-installed-deps-pre</code>
-option.</p>
-
-<h2 id="stricter">Paludis is Stricter than Portage</h2>
-
-<h3 id="mergingweirdstuff">Merging Weird Stuff</h3>
-
-<p>Paludis will refuse to merge various things:</p>
-
-<ul>
- <li>Device nodes, fifos and similar weird files. Portage will merge these
- incorrectly and then leave stray garbage lying around; Paludis refuses to do
- anything with them. Ebuilds that need to install fancy file types should do
- so in <code>pkg_postinst</code>.</li>
-
- <li>Things containing spaces. The VDB format, which cannot be changed
- without breaking Portage compatibility, uses spaces as a delimiter. Portage
- behaves incorrectly on items with spaces in the name; Paludis simply refuses
- to touch them.</li>
-
- <li>Non-directories on top of directories. Paludis will not let a package
- overwrite a directory with a non-directory. This is for your own safety.
- Portage doesn't bail out on this, but instead ends up partially merging
- content and generally making a mess of your system.</li>
-</ul>
-
-<h3 id="testfailures">Packages Failing <code>src_test</code></h3>
-
-<p>Various packages will fail <code>src_test</code>.</p>
-
-<p>You can set <code>SKIP_FUNCTIONS="test"</code> to skip tests. This
-is best done on a per-package basis via <code>bashrc</code>:</p>
-
-<pre>
-case "${PN}" in
-
- # Don't use src_test for these broken packages
- foo|bar|baz)
- SKIP_FUNCTIONS=test
- ;;
-
-esac
-</pre>
-
-<p>Unfortunately not all package maintainers care about making their package's test
-suite work. This is a nuisance, a) because it makes things much harder for arch
-teams and b) because it makes it harder for users to catch bugs.</p>
-
-<p>At this stage, you should not consider filing a bug about packages whose test
-phases fail. This is something that is being handled by the Gentoo QA team and
-various arch teams.</p>
-
-<h3 id="sandboxwithroot">Sandbox Violations when <code>ROOT</code> is Set</h3>
-
-<p>Various packages will give sandbox violations when installing to somewhere
-other than <code>/</code>.</p>
-
-<p>Paludis enforces <code>ROOT</code> via Sandbox. However, some packages don't
-honour <code>ROOT</code>. To temporarily disable sandbox for these packages,
-set <code>SANDBOX_PREDICT=/</code> or <code>SANDBOX_WRITE=/</code> as
-appropriate.</p>
-
-<h3 id="blacklist">Repository Blacklists</h3>
-
-<p>Paludis will sometimes blacklist certain repositories. When using a
-blacklisted repository, you will receive a warning when Paludis starts up. This
-is not a fatal error, but you should realise that use of the repository in
-question will likely lead to breakages.</p>
-
-<p>Repositories are only blacklisted under extreme circumstances, such as:</p>
-
-<ul>
- <li>When they are known to be very broken.</li>
- <li>When they are known to rely heavily upon quirks in Portage's behaviour
- that Paludis will not emulate.</li>
- <li>When they are known to be a security threat.</li>
-</ul>
-
-<h3 id="downgrades">Paludis wants to downgrade Qt or KDE</h3>
-
-<p>Unlike Portage, Paludis enforces the dependencies of installed
-packages, rather than those of the corresponding package in the tree.
-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>
-
-<h2 id="misfunctionality">Undesirable Misfunctionality</h2>
-
-<h3 id="wgetresume">wget Resume Support</h3>
-
-<p>Non-Problem: With Portage, <code>wget -c</code> is used to attempt to resume
-downloads of partial files. With Paludis, this is not done by default.</p>
-
-<p>Rationale: This leads to corruption and wasted bandwidth far too frequently.
-In particular, if an error page that isn't recognised as a 404 is fetched from
-one server (this is common for <code>mirror://sourceforge/</code>), resume
-support means <code>wget</code> would then download all but the first few
-hundred bytes of the file from somewhere else, leading to a corrupt distfile
-notice only after lots of bandwidth has been wasted.</p>
-
-<p>Paludis provides a <code>--safe-resume</code> option. When enabled, the download
-logic is as follows:</p>
-
-<ul>
- <li>If <code>output_file.-PARTIAL-</code> exists and is below a certain
- arbitrary threshold (currently somewhere in the 100KBytes region), delete it.</li>
-
- <li>Rather than downloading straight to <code>output_file</code>, download to
- <code>output_file.-PARTIAL-</code>. If this file already exists, resume rather than
- starting from scratch.</li>
-
- <li>If <code>wget</code> exits with success, move <code>output_file.-PARTIAL-</code>
- to <code>output_file</code>.</li>
-</ul>
-
-<p>Note that you must <strong>always</strong> specify this option,
-not just after a download has already been interrupted. See <a href="#defaultoptions">the
- discussion on default options</a> for how to do this easily.</p>
-
-<p>This logic is handled by the default fetcher for <code>http://</code>, <code>https://</code>
-and <code>ftp://</code>. This can be overridden by a custom fetcher if finer grained control
-is required.</p>
-
-<h3 id="skipfirst">Build Resume / Skip First Support</h3>
-
-<p>Non-Problem: Paludis doesn't have an equivalent to --resume --skipfirst in
-Portage.</p>
-
-<p>Rationale: Too unreliable, too flaky and far too widely abused; however, if
-an ebuild exits with an error, Paludis will echo a resume command (<code>paludis
- -i10 =sys-apps/foo-1.23-r1 =app-misc/fnord-2 ...</code>) that can be used to
-resume the build.</p>
-
-<h3 id="nice">No Automatic Niceness Support</h3>
-
-<p>Non-Problem: There's no <code>PORTAGE_NICENESS</code> equivalent.</p>
-
-<p>Rationale: Learn how to use <code>nice</code>. There's no
-<code>GCC_NICENESS</code> or <code>VIM_NICENESS</code> either.</p>
-
-<h3 id="ask">No Ask Support</h3>
-
-<p>Non-Problem: There's nothing like <code>emerge --ask</code>.</p>
-
-<p>Rationale: the <code>paludis</code> client is non-interactive. If someone is
-making an interactive client, there are much better ways of doing it than
-the limited functionality that <code>emerge --ask</code> provides.</p>
-
-<h3 id="digests">No Digest Generation</h3>
-
-<p>Non-Problem: Paludis doesn't do digest or Manifest creation.</p>
-
-<p>Rationale: In its current form, digest / Manifest is worthless. We will be
-implementing Manifest2 when it gets properly worked out.</p>
-
-<h3 id="xtermtitles">Restoring XTerm Titles</h3>
-
-<p>Non-Problem: Paludis doesn't restore the xterm title on exit.</p>
-
-<p>Rationale: Neither does anything else. Some programs do set it to a guessed
-value based upon a default prompt for certain distributions, but they don't
-restore it. You should be using <code>PROMPT_COMMAND</code> to do that yourself
--- see the <code>bash</code> documentation.</p>
-
-<h2 id="differences">Paludis Does Things Differently</h2>
-
-<h3 id="tree">No <code>--tree</code> Equivalent</h3>
-
-<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>
-
-<h3 id="features">No <code>FEATURES</code> Equivalent</h3>
-
-<p>Paludis doesn't use the <code>FEATURES</code> variable. We find this to be
-a rather ugly way of handling things. We do have equivalents to most values:</p>
-
-<dl>
- <dt>ccache</dt>
- <dd>See <a href="#ccache">Use <code>ccache</code></a>.</dd>
-
- <dt>collision-protect</dt>
- <dd>There are various third party hooks that implement this. We might start
- shipping one as a demo hook at some point.</dd>
-
- <dt>distcc</dt>
- <dd>See <a href="#distcc">Use <code>distcc</code></a>.</dd>
-
- <dt>keepwork, keeptemp, noclean</dt>
- <dd>The <code>builtin_tidyup</code> phase does cleaning up. You can turn
- this phase off using <code>SKIP_FUNCTIONS="tidyup"</code>.</dd>
-
- <dt>nodoc, noinfo, noman</dt>
- <dd>You could write a hook that removes the relevant directories from
- <code>$D</code>.</dd>
-
- <dt>nostrip</dt>
- <dd>Again, it's a function, so use <code>SKIP_FUNCTIONS="strip"</code>.</dd>
-
- <dt>sandbox</dt>
- <dd>Always on.</dd>
-
- <dt>splitdebug</dt>
- <dd>Use <code>--debug-build split</code>.</dd>
-
- <dt>test</dt>
- <dd>Always on. See <a href="#testfailures">Packages failing
- <code>src_test</code></a>.</dd>
-</dl>
-
-<h3 id="emptytree_usechanged">No <code>--emptytree</code> Equivalent or No <code>--newuse</code> Equivalent</h3>
-
-<p>The option <code>--dl-reinstall</code> handles both these cases.</p>
-
-<h3 id="elog">ELOG Equivalent</h3>
-
-<p>Paludis ships with a demo hook showing how to get a summary of messages after
-all packages have been installed. It can be found in
-<code>SHAREDIR/paludis/hooks/demos/elog.bash</code>. See <a
- href="hooks.html">the hooks documentation</a> for more information about
-hooks.</p>
-
-<h3 id="mkdir">No Automatic Directory Creation</h3>
-
-<p>Portage usually automatically creates directories for things. Paludis will
-usually refuse to create directories, except as a subdirectory of an existing
-Paludis-owned directory. This is for security reasons -- Paludis does not know
-what permissions are correct for you for the directory, and unlike Portage it
-does not grant back-door root access to all users in a particular group.</p>
-
-<p>Incidentally, if you want to let multiple users do Paludis cache writes and
-the like, you should look into what <code>chmod +s</code> does to directories.</p>
-
-<h3 id="revdep_rebuild">Revdep-rebuild Equivalent</h3>
-
-<p>Gentoolkit provides a script for rebuilding broken binaries and shared libraries
-using portage, Paludis provides a ruby script, check_linkage.rb. Install Paludis
-with the ruby USE flag enabled, and run ruby <code>/usr/share/paludis/ruby/demos/check_linkage.rb</code>.</p>
-
-<h2 id="repos">Repository Questions</h2>
-
-<h3 id="profiles">Profiles vs Profiles</h3>
-
-<p>Don't confuse the <code>profiles/</code> directory with the <code>profiles
- =</code> setting for ebuild format repositories. The special files
-immediately under <code>profiles/</code>, such as
-<code>profiles/thirdpartymirrors</code>, <code>profiles/use.desc</code>
-and <code>profiles/package.mask</code>, are specific to that particular profile
-and no other; the <code>profiles =</code> key has no effect upon them.</p>
-
-<h3 id="repo_name">Repository names</h3>
-
-<p>Because of a requirement forced into <a
- href="http://www.gentoo.org/proj/en/glep/glep-0042.html">GLEP 42</a> by the
-peanut gallery, repositories are required to be uniquely identifiable. The
-identifier must remain consistent even if a repository is moved, either locally
-or remotely, and thus must be independent of user configuration.</p>
-
-<p>For ebuild format repositories, this is controlled by the <code>profiles/repo_name</code>
-file. It should contain a single string with no whitespace or funny characters.
-For many repositories, this has already been created for you; for some overlays,
-probably including your local overlay if you have one, the file is not yet
-there so you will have to create it.</p>
-
-
-@FOOTER@
-</body>
-</html>
-
-
diff --git a/doc/faq/Makefile.am b/doc/faq/Makefile.am
new file mode 100644
index 0000000..e412f64
--- /dev/null
+++ b/doc/faq/Makefile.am
@@ -0,0 +1,13 @@
+SUBDIRS = .
+
+CLEANFILES = *~ gmon.out *.gcov *.gcno *.gcda
+MAINTAINERCLEANFILES = Makefile.in
+
+built-sources : $(BUILT_SOURCES)
+ for s in `echo $(SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s built-sources || exit 1 ; done
+
+distcheck-deps : $(DISTCHECK_DEPS) distcheck-deps-subdirs
+
+distcheck-deps-subdirs :
+ for s in `echo $(DIST_SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s distcheck-deps || exit 1 ; done
+
diff --git a/doc/faq/different.html.part b/doc/faq/different.html.part
new file mode 100644
index 0000000..8bacae3
--- /dev/null
+++ b/doc/faq/different.html.part
@@ -0,0 +1,89 @@
+<!-- vim: set tw=120 ft=html sw=4 sts=4 et : -->
+
+<h1>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#elog">ELOG 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>
+</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
+a rather ugly way of handling things. We do have equivalents to most values:</p>
+
+<dl>
+ <dt>ccache</dt>
+ <dd>See <a href="howdoi.html#ccache">Use <code>ccache</code></a>.</dd>
+
+ <dt>collision-protect</dt>
+ <dd>There are various third party hooks that implement this. We might start
+ shipping one as a demo hook at some point. Note that collision-protect is
+ conceptually broken and you shouldn't be using it.</dd>
+
+ <dt>distcc</dt>
+ <dd>See <a href="howdoi.html#distcc">Use <code>distcc</code></a>.</dd>
+
+ <dt>keepwork, keeptemp, noclean</dt>
+ <dd>The <code>builtin_tidyup</code> phase does cleaning up. You can turn
+ this phase off using <code>SKIP_FUNCTIONS="tidyup"</code>.</dd>
+
+ <dt>nodoc, noinfo, noman</dt>
+ <dd>You could write a hook that removes the relevant directories from
+ <code>$D</code>.</dd>
+
+ <dt>nostrip</dt>
+ <dd>Again, it's a function, so use <code>SKIP_FUNCTIONS="strip"</code>.</dd>
+
+ <dt>sandbox</dt>
+ <dd>Always on.</dd>
+
+ <dt>splitdebug</dt>
+ <dd>Use <code>--debug-build split</code>.</dd>
+
+ <dt>test</dt>
+ <dd>Controlled by <code>--checks</code>.</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="elog">ELOG Equivalent</h2>
+
+<p>Paludis ships with a demo hook showing how to get a summary of messages after
+all packages have been installed. It can be found in
+<code>SHAREDIR/paludis/hooks/demos/elog.bash</code>. See <a
+ href="hooks.html">the hooks documentation</a> for more information about
+hooks.</p>
+
+<p>This hook is not enabled by default because it is highly annoying. If you use
+repositories that don't use elog to spam pointless messages about revdep-rebuild,
+the demo hook may be of use.</p>
+
+<h2 id="mkdir">No Automatic Directory Creation</h2>
+
+<p>Portage usually automatically creates directories for things. Paludis will
+usually refuse to create directories, except as a subdirectory of an existing
+Paludis-owned directory. This is for security reasons -- Paludis does not know
+what permissions are correct for you for the directory, and unlike Portage it
+does not grant back-door root access to all users in a particular group.</p>
+
+<p>Incidentally, if you want to let multiple users do Paludis cache writes and
+the like, you should look into what <code>chmod +s</code> does to directories.</p>
+
+<h2 id="revdep_rebuild">Revdep-rebuild Equivalent</h2>
+
+<p>Use the <code>reconcilio</code> client.</p>
+
diff --git a/doc/faq/general.html.part b/doc/faq/general.html.part
new file mode 100644
index 0000000..48224b5
--- /dev/null
+++ b/doc/faq/general.html.part
@@ -0,0 +1,63 @@
+<!-- vim: set tw=120 ft=html sw=4 sts=4 et : -->
+
+<h1>FAQ: General Questions</h1>
+
+<ul>
+ <li><a href="general.html#ihaveaquestion">I have an Unanswered Question</a></li>
+ <li><a href="general.html#why">Why not fix Portage?</a></li>
+ <li><a href="general.html#cplusplus">Why C++?</a></li>
+ <li><a href="general.html#butcplusplusis">But C++ is ...</a></li>
+ <li><a href="general.html#contribute">Contributing</a></li>
+</ul>
+
+<h2 id="ihaveaquestion">I have an Unanswered Question</h2>
+
+<p>If you've checked the documentation, and your question really isn't answered,
+you should ask it in one of these places:</p>
+
+<ul>
+ <li>The <code>#paludis</code> channel on <code>irc.freenode.net</code></li>
+ <li>The <a href="../overview/contact.html">paludis-user mailing list</a></li>
+ <li>The <a href="http://paludis.pioto.org/trac/">bug tracker</a> will probably
+ also be useful</li>
+</ul>
+
+<p>You are encouraged to submit an entry for this document once your question
+has been answered.</p>
+
+<h2 id="why">Why not fix Portage?</h2>
+
+<p>The Portage codebase is too broken to be fixed. It is a huge mess of
+spaghetti procedural code with no underlying design. It relies upon weird
+quirks in its own behaviour all over the place, so any change is liable to
+cause huge breakage in seemingly unrelated areas. It is almost entirely
+undocumented, and the internal names are perverse and often do not reflect what
+the code now does.</p>
+
+<h2 id="cplusplus">Why C++?</h2>
+
+<p>Because we don't have the time or the manpower to write it in C.</p>
+
+<h2 id="butcplusplusis">But C++ is ...</h2>
+
+<p>No it isn't. Whoever told you that was either trolling or ignorant.</p>
+
+<h2 id="contribute">Contributing</h2>
+
+<p>Contributions to Paludis are welcome:</p>
+
+<ul>
+ <li>Patches can be submitted via <a
+ href="http://paludis.pioto.org/trac/">trac</a>. It's best to
+ discuss ideas before spending too much time on the code, because we don't
+ have any qualms about rejecting things we think are a bad idea.</li>
+
+ <li>We could probably use some more documentation. Again, ask first.</li>
+
+ <li>Translations aren't currently possible. We don't have anything against
+ internationalisation in principle, but as we're not gettextised it'll be a
+ fair bit of effort.</li>
+
+ <li>We don't need or desire assistance with hosting etc. at present.</li>
+</ul>
+
diff --git a/doc/faq/howdoi.html.part b/doc/faq/howdoi.html.part
new file mode 100644
index 0000000..d9d69a9
--- /dev/null
+++ b/doc/faq/howdoi.html.part
@@ -0,0 +1,199 @@
+<!-- vim: set tw=120 ft=html sw=4 sts=4 et : -->
+
+<h1>FAQ: How do I ...?</h1>
+
+<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>
+</ul>
+
+<h2 id="ccache">Use <code>ccache</code></h2>
+
+<p>To enable <code>ccache</code>, simply set the relevant variables in your
+configuration <code>bashrc</code>:</p>
+
+<pre>
+PATH="/usr/lib/ccache/bin/:${PATH}"
+CCACHE_DIR="/var/tmp/ccache"
+SANDBOX_WRITE="${SANDBOX_WRITE}:${CCACHE_DIR}"
+</pre>
+
+<p>You'll need to make sure that your ccache directory has appropriate permissions. Paludis
+will sometimes use the <code>paludisbuild</code> user when compiling.</p>
+
+<h2 id="distcc">Use <code>distcc</code></h2>
+
+<p>To enable <code>distcc</code>, simply set the relevant variables in your
+configuration <code>bashrc</code>:</p>
+
+<pre>
+DISTCC_DIR="/var/tmp/paludis/.distcc"
+DISTCC_HOSTS="localhost another_host"
+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>--debug-build split</code>, to make debugging easier (at the cost of disk
+ space)</li>
+
+ <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
+this is to use <code>paludis --query</code>. Then, if you're sure you really
+want to unmask a package, and bearing in mind that doing so might break your
+system, you need to override the mask. How to do this depends upon the mask
+reasons:</p>
+
+<dl>
+ <dt>keyword</dt>
+
+ <dd>You need to add an entry to your <code>keywords.conf</code> accepting
+ one of the ebuild's keywords. The special <code>-*</code> keyword cannot be
+ accepted this way; if an ebuild only has this in its keywords, report it
+ to <a href="https://bugs.gentoo.org/show_bug.cgi?id=160519">Gentoo bug
+ 160519</a> and work around it by using <code>*</code>. An asterisk will
+ also accept an ebuild with empty keywords.</dd>
+
+ <dt>user mask</dt>
+
+ <dd>Either remove your <code>package_mask.conf</code> entry or override it
+ with <code>package_unmask.conf</code>.</dd>
+
+ <dt>profile mask</dt>
+
+ <dd>Override with <code>package_unmask.conf</code>.</dd>
+
+ <dt>repository mask</dt>
+
+ <dd>Override with <code>package_unmask.conf</code>.</dd>
+
+ <dt>eapi</dt>
+
+ <dd>You cannot override this mask. It indicates either a broken ebuild (if
+ <code>EAPI=unknown</code> or an ebuild not supported by your current version
+ of Paludis.</dd>
+
+ <dt>license</dt>
+
+ <dd>Accept the appropriate licences in <code>licenses.conf</code>.</dd>
+
+ <dt>by association</dt>
+
+ <dd>Unmask the associated package. This mask reason is currently only used
+ for old style virtuals.</dd>
+</dl>
+
+<h2 id="syncfromcvs">Sync from CVS</h2>
+
+<p>Syncing from CVS requires use of either the <code>cvs+pserver</code> or the <code>cvs+ssh</code> protocol.
+The syntax for the configuration file line is
+<code>sync = cvs+ssh://username@host:/path/to/cvsroot:modulename</code>. As an example,
+for syncing with the <code>gentoo</code> repository via CVS, you would use
+<code>sync = cvs+ssh://username@cvs.gentoo.org:/var/cvsroot:gentoo-x86</code>.</p>
+
+<h2 id="syncfromsnapshot">Sync from a Gentoo tree snapshot</h2>
+
+<p>Syncing from a tarball requires the <code>tar+http</code>
+or <code>tar+ftp</code> protocol. You must also
+specify <code>sync_options = --strip-components=1</code>, as the
+Gentoo snapshots place everything under a subdirectory
+named <code>portage</code>. For example:</p>
+<pre>
+# Replace this with your favourite Gentoo mirror
+sync = tar+ftp://my.favourite.mirror/gentoo/snapshots/portage-latest.tar.bz2
+sync_options = --strip-components=1
+</pre>
+
diff --git a/doc/faq/index.html.part b/doc/faq/index.html.part
new file mode 100644
index 0000000..6a55198
--- /dev/null
+++ b/doc/faq/index.html.part
@@ -0,0 +1,79 @@
+<!-- vim: set tw=120 ft=html sw=4 sts=4 et : -->
+
+<h1>Frequently Asked Questions</h1>
+
+<p>This document describes some of the more commonly encountered problems, issues
+and things that aren't bugs but might look like they are. Pestering anyone about
+these is liable to get you hurt.</p>
+
+<p>This document also describes some things that are not bugs or missing
+functionality. Pestering anyone about these is liable to get you hurt a lot.</p>
+
+<h2>General Questions</h2>
+
+<ul>
+ <li><a href="general.html#ihaveaquestion">I have an Unanswered Question</a></li>
+ <li><a href="general.html#why">Why not fix Portage?</a></li>
+ <li><a href="general.html#cplusplus">Why C++?</a></li>
+ <li><a href="general.html#butcplusplusis">But C++ is ...</a></li>
+ <li><a href="general.html#contribute">Contributing</a></li>
+</ul>
+
+<h2>How do I ...?</h2>
+
+<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>
+</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>
+</ul>
+
+<h2>Stricter than Portage</h2>
+
+<ul>
+ <li><a href="stricter.html#mergingweirdstuff">Merging Weird Stuff</a></li>
+ <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>
+
+<ul>
+ <li><a href="misfunctionality.html#wgetresume">wget Resume Support</a></li>
+ <li><a href="misfunctionality.html#skipfirst">Build Resume / Skip First Support</a></li>
+ <li><a href="misfunctionality.html#nice">No Automatic Niceness Support</a></li>
+ <li><a href="misfunctionality.html#ask">No Ask Support</a></li>
+ <li><a href="misfunctionality.html#xtermtitles">Restoring XTerm Titles</a></li>
+</ul>
+
+<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#elog">ELOG 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>
+</ul>
+
+<h2>Repository Questions</h2>
+
+<ul>
+ <li><a href="repositories.html#profiles">Profiles vs Profiles</a></li>
+ <li><a href="repositories.html#repo_name">Repository names</a></li>
+</ul>
+
diff --git a/doc/faq/misfunctionality.html.part b/doc/faq/misfunctionality.html.part
new file mode 100644
index 0000000..91b54f1
--- /dev/null
+++ b/doc/faq/misfunctionality.html.part
@@ -0,0 +1,81 @@
+<!-- vim: set tw=120 ft=html sw=4 sts=4 et : -->
+
+<h1>FAQ: Undesirable Misfunctionality</h1>
+
+<ul>
+ <li><a href="misfunctionality.html#wgetresume">wget Resume Support</a></li>
+ <li><a href="misfunctionality.html#skipfirst">Build Resume / Skip First Support</a></li>
+ <li><a href="misfunctionality.html#nice">No Automatic Niceness Support</a></li>
+ <li><a href="misfunctionality.html#ask">No Ask Support</a></li>
+ <li><a href="misfunctionality.html#xtermtitles">Restoring XTerm Titles</a></li>
+</ul>
+
+<h2 id="wgetresume">wget Resume Support</h2>
+
+<p>Non-Problem: With Portage, <code>wget -c</code> is used to attempt to resume
+downloads of partial files. With Paludis, this is not done by default.</p>
+
+<p>Rationale: This leads to corruption and wasted bandwidth far too frequently.
+In particular, if an error page that isn't recognised as a 404 is fetched from
+one server (this is common for <code>mirror://sourceforge/</code>), resume
+support means <code>wget</code> would then download all but the first few
+hundred bytes of the file from somewhere else, leading to a corrupt distfile
+notice only after lots of bandwidth has been wasted.</p>
+
+<p>Paludis uses a much safer mechanism known as 'safe resume'. When downloading, the
+following steps are taken:</p>
+
+<ul>
+ <li>If <code>output_file.-PARTIAL-</code> exists and is below a certain
+ arbitrary threshold (currently somewhere in the 100KBytes region), it is
+ deleted.</li>
+
+ <li>Rather than downloading straight to <code>output_file</code>, Paludis downloads to
+ <code>output_file.-PARTIAL-</code>. If this file already exists, Paludis resumes rather than
+ starting from scratch.</li>
+
+ <li>If <code>wget</code> exits with success, <code>output_file.-PARTIAL-</code> is moved
+ to <code>output_file</code>.</li>
+</ul>
+
+<p>This logic is handled by the default fetcher for <code>http://</code>, <code>https://</code>
+and <code>ftp://</code>. This can be overridden by a custom fetcher if finer grained control
+is required.</p>
+
+<h2 id="skipfirst">Build Resume / Skip First Support</h2>
+
+<p>Non-Problem: Paludis doesn't have an equivalent to --resume --skipfirst in
+Portage.</p>
+
+<p>Rationale: Too unreliable, too flaky, a security hole and far too widely abused;
+however, if an ebuild exits with an error, Paludis will echo a resume command
+(<code>paludis -i10 =sys-apps/foo-1.23-r1 =app-misc/fnord-2 ...</code>) that can be used to
+resume the build.</p>
+
+<p>Paludis also includes <code>--continue-on-failure</code> support. This is much more
+elegant.</p>
+
+<h2 id="nice">No Automatic Niceness Support</h2>
+
+<p>Non-Problem: There's no <code>PORTAGE_NICENESS</code> equivalent.</p>
+
+<p>Rationale: Learn how to use <code>nice</code>. There's no
+<code>GCC_NICENESS</code> or <code>VIM_NICENESS</code> either.</p>
+
+<h2 id="ask">No Ask Support</h2>
+
+<p>Non-Problem: There's nothing like <code>emerge --ask</code>.</p>
+
+<p>Rationale: the <code>paludis</code> client is non-interactive. If someone is
+making an interactive client, there are much better ways of doing it than
+the limited functionality that <code>emerge --ask</code> provides.</p>
+
+<h2 id="xtermtitles">Restoring XTerm Titles</h2>
+
+<p>Non-Problem: Paludis doesn't restore the xterm title on exit.</p>
+
+<p>Rationale: Neither does anything else. Some programs do set it to a guessed
+value based upon a default prompt for certain distributions, but they don't
+restore it. You should be using <code>PROMPT_COMMAND</code> to do that yourself
+-- see the <code>bash</code> documentation.</p>
+
diff --git a/doc/faq/operation.html.part b/doc/faq/operation.html.part
new file mode 100644
index 0000000..1629d97
--- /dev/null
+++ b/doc/faq/operation.html.part
@@ -0,0 +1,30 @@
+<!-- vim: set tw=120 ft=html sw=4 sts=4 et : -->
+
+<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>
+</ul>
+
+<h2 id="updatingdepends">Paludis does not update DEPENDs of already installed packages</h2>
+
+<p>Paludis ignores 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>everything</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>
+
diff --git a/doc/faq/repositories.html.part b/doc/faq/repositories.html.part
new file mode 100644
index 0000000..7f992f4
--- /dev/null
+++ b/doc/faq/repositories.html.part
@@ -0,0 +1,40 @@
+<!-- vim: set tw=120 ft=html sw=4 sts=4 et : -->
+
+<h1>Repository Questions</h1>
+
+<ul>
+ <li><a href="repositories.html#profiles">Profiles vs Profiles</a></li>
+ <li><a href="repositories.html#repo_name">Repository names</a></li>
+</ul>
+
+<h2 id="profiles">Profiles vs Profiles</h2>
+
+<p>Don't confuse the <code>profiles/</code> directory with the <code>profiles
+ =</code> setting for ebuild format repositories. The special files
+immediately under <code>profiles/</code>, such as
+<code>profiles/thirdpartymirrors</code>, <code>profiles/use.desc</code>
+and <code>profiles/package.mask</code>, are specific to that particular profile
+and no other; the <code>profiles =</code> key has no effect upon them.</p>
+
+<h2 id="repo_name">Repository names</h2>
+
+<p>Because of a requirement forced into <a
+ href="http://www.gentoo.org/proj/en/glep/glep-0042.html">GLEP 42</a> by the
+peanut gallery, repositories are required to be uniquely identifiable. The
+identifier must remain consistent even if a repository is moved, either locally
+or remotely, and thus must be independent of user configuration.</p>
+
+<p>For ebuild format repositories, this is controlled by the <code>profiles/repo_name</code>
+file. It should contain a single string with no whitespace or funny characters.
+For many repositories, this has already been created for you; for some overlays,
+probably including your local overlay if you have one, the file is not yet
+there so you will have to create it.</p>
+
+<p>If a repository has not yet been synced, or if it does not contain a <code>repo_name</code>,
+Paludis will try to auto-generate a repository name for it. The generated name will start
+with <code>x-</code>. Paludis will <em>not</em> attempt to generate a name without the <code>x-</code>
+prefix to avoid strange collisions.</p>
+
+<p>The name of a repository has nothing to do with the filename of the configuration
+file in <code>confdir/paludis/repositories/</code>.</p>
+
diff --git a/doc/faq/stricter.html.part b/doc/faq/stricter.html.part
new file mode 100644
index 0000000..5d2dd79
--- /dev/null
+++ b/doc/faq/stricter.html.part
@@ -0,0 +1,88 @@
+<!-- vim: set tw=120 ft=html sw=4 sts=4 et : -->
+
+<h1>FAQ: Paludis is Stricter than Portage</h1>
+
+<ul>
+ <li><a href="stricter.html#mergingweirdstuff">Merging Weird Stuff</a></li>
+ <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>
+
+<p>Paludis will refuse to merge various things:</p>
+
+<ul>
+ <li>Device nodes, fifos and similar weird files. Portage will merge these
+ incorrectly and then leave stray garbage lying around; Paludis refuses to do
+ anything with them. Ebuilds that need to install fancy file types should do
+ so in <code>pkg_postinst</code>.</li>
+
+ <li>Things containing spaces. The VDB format, which cannot be changed
+ without breaking Portage compatibility, uses spaces as a delimiter. Portage
+ behaves incorrectly on items with spaces in the name; Paludis simply refuses
+ to touch them.</li>
+
+ <li>Non-directories on top of directories. Paludis will not let a package
+ overwrite a directory with a non-directory. This is for your own safety.
+ Portage doesn't bail out on this, but instead ends up partially merging
+ content and generally making a mess of your system.</li>
+</ul>
+
+<p>If you encounter an ebuild that does any of these, fix the ebuild.</p>
+
+<h2 id="testfailures">Packages Failing <code>src_test</code></h2>
+
+<p>Prior to version 0.26, Paludis would always run <code>src_test</code>. Earlier
+versions of this FAQ suggested using <code>SKIP_FUNCTIONS</code> to override this.</p>
+
+<p>Unfortunately, because the QA standards in many parts of the Gentoo tree are so low,
+and because some Gentoo developers have such terrible attitudes towards QA, this is
+no longer the default behaviour. Whether or not tests are run is now controlled by
+the <code>--checks</code> command line argument.</p>
+
+<h2 id="sandboxwithroot">Sandbox Violations when <code>ROOT</code> is Set</h2>
+
+<p>Various packages will give sandbox violations when installing to somewhere
+other than <code>/</code>.</p>
+
+<p>Paludis enforces <code>ROOT</code> via Sandbox. However, some packages don't
+honour <code>ROOT</code>. To temporarily disable sandbox for these packages,
+set <code>SANDBOX_PREDICT=/</code> or <code>SANDBOX_WRITE=/</code> as
+appropriate.</p>
+
+<h2 id="blacklist">Repository Blacklists</h2>
+
+<p>Paludis will sometimes blacklist certain repositories. When using a
+blacklisted repository, you will receive a warning when Paludis starts up. This
+is not a fatal error, but you should realise that use of the repository in
+question will likely lead to breakages.</p>
+
+<p>Repositories are only blacklisted under extreme circumstances, such as:</p>
+
+<ul>
+ <li>When they are known to be very broken.</li>
+ <li>When they are known to rely heavily upon quirks in Portage's behaviour
+ that Paludis will not emulate.</li>
+ <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 the tree.
+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/footer.html b/doc/footer.html
deleted file mode 100644
index 32832e3..0000000
--- a/doc/footer.html
+++ /dev/null
@@ -1,8 +0,0 @@
-<div class="qindex" style="text-align: center; margin-top: 1em;">
- <p>Copyright &copy; 2005, 2006, 2007 <a href="http://ciaranm.org/">Ciaran
- McCreesh</a> and various others. See the <a href="../../authors.html">Authors
- list</a> and <a href="../../licence.html">Licence</a> for details and redistribution conditions.</p>
-</div>
-</body>
-</html>
-
diff --git a/doc/header.html b/doc/header.html
deleted file mode 100644
index 7eb915a..0000000
--- a/doc/header.html
+++ /dev/null
@@ -1,69 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<!-- vim: set sw=4 sts=4 et : -->
-<html>
- <head>
- <title>$title</title>
- <link href="$relpath$paludis.css" rel="stylesheet" type="text/css">
- </head>
- <body>
-
-<div class="qindex">
- <table border="0">
- <tr>
- <td><a href="index.html"><img src="paludis_270.png" alt="Paludis logo"
- style="border: 0px;" /></a></td>
- <td style="text-align: left;">
- <ul>
- <li><a class="qindex" href="/faq.html">FAQ&nbsp;(Important!)</a></li>
- <li><a class="qindex" href="http://paludis.pioto.org/trac/">Bugs&nbsp;and&nbsp;Requests</a></li>
- <li><a class="qindex"
- href="/portagedifferences.html">Portage&nbsp;Differences</a></li>
- <li><a class="qindex"
- href="/migration.html">Migration&nbsp;Guide</a></li>
- </ul>
- </td>
- <td style="text-align: left;">
- <ul>
- <li><a class="qindex"
- href="/configuration.html">Configuration&nbsp;Guide</a></li>
- <li><a class="qindex"
- href="/cachefiles.html">Cache&nbsp;Options</a></li>
- <li><a class="qindex"
- href="/sets.html">Sets&nbsp;Guide</a></li>
- <li><a class="qindex"
- href="/hooks.html">Hooks&nbsp;Guide</a></li>
- </ul>
- </td>
- <td style="text-align: left;">
- <ul>
- <li><a class="qindex" href="/news.html">Release&nbsp;Notes</a></li>
- <li><a class="qindex" href="/changelog.html">ChangeLog</a></li>
- <li><a class="qindex" href="/licence.html">Licence</a></li>
- <li><a class="qindex" href="/authors.html">Authors</a></li>
- </ul>
- </td>
- <td style="text-align: left;">
- <ul>
- <li><a class="qindex" href="https://developer.berlios.de/project/showfiles.php?group_id=6360">Download</a></li>
- <li><a class="qindex" href="http://paludis.pioto.org/trac/browser">SVN</a></li>
- <li><a class="qindex" href="https://developer.berlios.de/projects/paludis/">Berlios&nbsp;Project</a></li>
- <li><a class="qindex"
- href="http://lists.pioto.org/">Mailing&nbsp;Lists</a></li>
- </ul>
- </td>
- </tr>
- </table>
-</div>
-
- <div class="qindex">Code Documentation: [
- <a class="qindex" href="modules.html">Modules</a> |
- <a class="qindex" href="examples.html">Examples</a> |
- <a class="qindex" href="namespaces.html">Namespaces</a> |
- <a class="qindex" href="annotated.html">Classes</a> |
- <a class="qindex" href="files.html">Files</a> |
- <a class="qindex" href="namespacemembers.html">Namespace&nbsp;Members</a> |
- <a class="qindex" href="functions.html">Class&nbsp;Members</a> |
- <a class="qindex" href="globals.html">File&nbsp;Members</a> |
- <a class="qindex" href="pages.html">Other&nbsp;Topics</a> ]
- </div>
-
diff --git a/doc/hooks.html.skel b/doc/hooks.html.skel
deleted file mode 100644
index 36b432f..0000000
--- a/doc/hooks.html.skel
+++ /dev/null
@@ -1,482 +0,0 @@
-<!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>Hooks</h2>
-
-<h3>Overview</h3>
-
-<p>This document describes the Paludis hooks interface. A hook is a piece of code
-that is executed when a particular well defined action occurs.</p>
-
-<p>There are currently four categories of hook:</p>
-
-<ul>
- <li>General hooks. These have access to a limited environment. If
- a hook returns a non-zero exit code, the action will be aborted.
- See <a href="#general-hooks">General Hooks</a>.</li>
-
- <li>Ebuild phase hooks. These have <code>ebuild</code> in the hook name, and
- have full access to the ebuild environment (including the ability to call
- <code>die</code>), but are only used for ebuild-based activities.
- See <a href="#ebuild-hooks">Ebuild Hooks</a>.</li>
-
- <li>Ebuild message hooks. These are special hooks that are called for
- <code>einfo</code>, <code>ewarn</code> etc.
- See <a href="#ebuild-message-hooks">Ebuild Message Hooks</a>.</li>
-
- <li>Merger / Unmerger hooks. These are used when installing and uninstalling
- content to the live filesystem. If a check hook returns a non-zero exit
- code, the action will be aborted.
- See <a href="#merger-hooks">Merger / Unmerger Hooks</a>.</li>
-</ul>
-
-<p>There are currently five categories of hook execution code:</p>
-
-<ul>
- <li><code>.bash</code> hooks. These are simple <code>.bash</code> files that
- are executed with a particular environment. See <a href="#bash-hooks">Bash Hooks</a>
- for details.</li>
-
- <li><code>.hook</code> hooks. These are also <code>bash</code> files, but rather
- than containing the relevant code in global scope, they make use of functions
- to perform hook actions. They also support specifying execution order dependencies
- upon other hooks. See <a href="#hook-hooks">Hook Hooks</a> for details.</li>
-
- <li><code>.py</code> hooks. These are much like .hook hooks, but written in Python and
- with additional power given by Python bindings and access to the current Environment.
- See <a href="#py-hooks">Python Hooks</a> for details.</li>
-
- <li><code>.so</code> hooks. These are written in C++ and compiled into shared
- libraries, and run inside the Paludis process. See <a href="#so-hooks">So Hooks</a>
- for details.</li>
-
- <li>Repository hooks. These are implemented internally by <code>Repository</code>
- classes.</li>
-</ul>
-
-<p>Not all hook execution code methods are available for all hook categories. The
-following table indicates availability:</p>
-
-<table border="1">
- <tr>
- <td></td>
- <th><code>.bash</code></th>
- <th><code>.hook</code></th>
- <th><code>.py</code></th>
- <th><code>.so</code></th>
- <th>Repository</th>
- </tr>
- <tr>
- <th>General</th>
- <td>yes</td>
- <td>yes</td>
- <td>yes</td>
- <td>yes</td>
- <td>yes</td>
- </tr>
- <tr>
- <th>Ebuild Phase</th>
- <td>yes</td>
- <td></td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <th>Ebuild Message</th>
- <td>yes</td>
- <td></td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <th>Merger</th>
- <td>yes</td>
- <td>yes</td>
- <td>yes</td>
- <td>yes</td>
- <td>yes</td>
- </tr>
-</table>
-
-<p>Where there is a choice, <code>.hook</code> hooks should be favoured over <code>.bash</code>
-hooks.</p>
-
-<h3>Available Hooks</h3>
-
-<h4 id="general-hooks">General Hooks</h4>
-
-<p>The following general normal hooks are available:</p>
-
-<ul>
- <li><code>install_pre</code></li>
- <li><code>install_fail</code></li>
- <li><code>install_post</code></li>
- <li><code>install_all_pre</code></li>
- <li><code>install_all_post</code></li>
- <li><code>install_pretend_pre</code></li>
- <li><code>install_pretend_post</code></li>
- <li><code>install_pretend_display_item_pre</code></li>
- <li><code>install_pretend_display_item_post</code></li>
- <li><code>uninstall_pre</code></li>
- <li><code>uninstall_fail</code></li>
- <li><code>uninstall_post</code></li>
- <li><code>uninstall_all_pre</code></li>
- <li><code>uninstall_all_post</code></li>
- <li><code>clean_pre</code></li>
- <li><code>clean_post</code></li>
- <li><code>clean_fail</code></li>
- <li><code>clean_all_pre</code></li>
- <li><code>clean_all_post</code></li>
- <li><code>sync_pre</code></li>
- <li><code>sync_fail</code></li>
- <li><code>sync_post</code></li>
- <li><code>sync_all_pre</code></li>
- <li><code>sync_all_post</code></li>
- <li><code>fetch_pre</code></li>
- <li><code>fetch_post</code></li>
- <li><code>fetch_all_pre</code></li>
- <li><code>fetch_all_post</code></li>
-</ul>
-
-<p>In general, certain special environment variables will be set. <code>HOOK</code> will contain
-the name of the hook. For <code>all</code> hooks, <code>TARGETS</code> will contain the targets
-for the operation. For non-<code>all</code> hooks, <code>TARGET</code> will contain the current
-target. The <code>PALUDIS_CMDLINE</code> variables described below are also available. For the
-<code>install_pretend_display_item</code> hooks, the <code>KIND</code> variable will also be of
-interest.</p>
-
-<h4 id="ebuild-hooks">Ebuild Hooks</h4>
-
-<p>The following ebuild hooks are available:</p>
-
-<ul>
- <li><code>ebuild_metadata_pre</code></li>
- <li><code>ebuild_metadata_fail</code></li>
- <li><code>ebuild_metadata_post</code></li>
- <li><code>ebuild_init_pre</code></li>
- <li><code>ebuild_init_fail</code></li>
- <li><code>ebuild_init_post</code></li>
- <li><code>ebuild_fetch_pre</code></li>
- <li><code>ebuild_fetch_fail</code></li>
- <li><code>ebuild_fetch_post</code></li>
- <li><code>ebuild_tidyup_pre</code></li>
- <li><code>ebuild_tidyup_fail</code></li>
- <li><code>ebuild_tidyup_post</code></li>
- <li><code>ebuild_strip_pre</code></li>
- <li><code>ebuild_strip_fail</code></li>
- <li><code>ebuild_strip_post</code></li>
- <li><code>ebuild_unpack_pre</code></li>
- <li><code>ebuild_unpack_fail</code></li>
- <li><code>ebuild_unpack_post</code></li>
- <li><code>ebuild_compile_pre</code></li>
- <li><code>ebuild_compile_fail</code></li>
- <li><code>ebuild_compile_post</code></li>
- <li><code>ebuild_install_pre</code></li>
- <li><code>ebuild_install_fail</code></li>
- <li><code>ebuild_install_post</code></li>
- <li><code>ebuild_test_pre</code></li>
- <li><code>ebuild_test_fail</code></li>
- <li><code>ebuild_test_post</code></li>
- <li><code>ebuild_setup_pre</code></li>
- <li><code>ebuild_setup_fail</code></li>
- <li><code>ebuild_setup_post</code></li>
- <li><code>ebuild_config_pre</code></li>
- <li><code>ebuild_config_fail</code></li>
- <li><code>ebuild_config_post</code></li>
- <li><code>ebuild_nofetch_pre</code></li>
- <li><code>ebuild_nofetch_fail</code></li>
- <li><code>ebuild_nofetch_post</code></li>
- <li><code>ebuild_preinst_pre</code></li>
- <li><code>ebuild_preinst_fail</code></li>
- <li><code>ebuild_preinst_post</code></li>
- <li><code>ebuild_postinst_pre</code></li>
- <li><code>ebuild_postinst_fail</code></li>
- <li><code>ebuild_postinst_post</code></li>
- <li><code>ebuild_prerm_pre</code></li>
- <li><code>ebuild_prerm_fail</code></li>
- <li><code>ebuild_prerm_post</code></li>
- <li><code>ebuild_postrm_pre</code></li>
- <li><code>ebuild_postrm_fail</code></li>
- <li><code>ebuild_postrm_post</code></li>
-</ul>
-
-<p>As well as the full ebuild environment, the <code>HOOK</code> environment
-variable will contain the name of the hook being called. The
-<code>PALUDIS_CMDLINE</code> variables described below are also available.</p>
-
-<h4 id="ebuild-message-hooks">Ebuild Message Hooks</h4>
-
-<p>The following ebuild message hooks are available:</p>
-
-<ul>
- <li><code>einfo</code></li>
- <li><code>ewarn</code></li>
- <li><code>eerror</code></li>
- <li><code>elog</code></li>
-</ul>
-
-<p>The <code>HOOK</code> environment variable will contain the name of the hook
-being called, and the <code>MESSAGE</code> environment variable will contain
-the message being passed to the function. The <code>PALUDIS_CMDLINE</code>
-variables described below are also available.</p>
-
-<h4 id="merger-hooks">Merger / Unmerger Hooks</h4>
-
-<p>The merger runs in two stages, for safety. First it checks that it can
-probably install safely, then it does the actual install. Note that calculating
-the md5, timestamp etc for VDB CONTENTS is done <em>after</em> the install_post
-hooks are called.</p>
-
-<p>In each of the following subcategories, the hooks that do not name
-a specific type of object are called before or after the entire
-process; those that do are called once for each relevant item.</p>
-
-<p>The following merger check hooks are available:</p>
-
-<ul>
- <li><code>merger_check_pre</code></li>
- <li><code>merger_check_post</code></li>
- <li><code>merger_check_file_pre</code></li>
- <li><code>merger_check_file_post</code></li>
- <li><code>merger_check_sym_pre</code></li>
- <li><code>merger_check_sym_post</code></li>
- <li><code>merger_check_dir_pre</code></li>
- <li><code>merger_check_dir_post</code></li>
-</ul>
-
-<p>The <code>INSTALL_SOURCE</code> and <code>INSTALL_DESTINATION</code>
-environment variables contain the target source and destination. The
-<code>ROOT</code> variable contains the filesystem root. The <code>IMAGE</code>
-variable contains the image root.</p>
-
-<p>The following merger hooks are available:</p>
-
-<ul>
- <li><code>merger_install_pre</code></li>
- <li><code>merger_install_post</code></li>
- <li><code>merger_install_file_pre</code></li>
- <li><code>merger_install_file_post</code></li>
- <li><code>merger_install_sym_pre</code></li>
- <li><code>merger_install_sym_post</code></li>
- <li><code>merger_install_dir_pre</code></li>
- <li><code>merger_install_dir_post</code></li>
- <li><code>merger_unlink_file_pre</code></li>
- <li><code>merger_unlink_file_post</code></li>
- <li><code>merger_unlink_dir_pre</code></li>
- <li><code>merger_unlink_dir_post</code></li>
- <li><code>merger_unlink_sym_pre</code></li>
- <li><code>merger_unlink_sym_post</code></li>
- <li><code>merger_unlink_misc_pre</code></li>
- <li><code>merger_unlink_misc_post</code></li>
-</ul>
-
-<p>Again, <code>ROOT</code> and <code>IMAGE</code> are available. For
-install hooks, <code>INSTALL_SOURCE</code>, <code>INSTALL_DESTINATION</code> are
-set, and for uninstall hooks, <code>UNLINK_TARGET</code>.</p>
-
-<p>The unmerger hooks are used for uninstalling a package, but not when existing
-things have to be removed for an install (the merger does that). The following
-unmerger hooks are available:</p>
-
-<ul>
- <li><code>unmerger_unlink_pre</code></li>
- <li><code>unmerger_unlink_post</code></li>
- <li><code>unmerger_unlink_file_pre</code></li>
- <li><code>unmerger_unlink_file_post</code></li>
- <li><code>unmerger_unlink_dir_pre</code></li>
- <li><code>unmerger_unlink_dir_post</code></li>
- <li><code>unmerger_unlink_sym_pre</code></li>
- <li><code>unmerger_unlink_sym_post</code></li>
- <li><code>unmerger_unlink_misc_pre</code></li>
- <li><code>unmerger_unlink_misc_post</code></li>
-</ul>
-
-<p>The <code>UNLINK_TARGET</code> environment variable specifies the file about
-to be unlinked, and <code>ROOT</code> is the filesystem root.</p>
-
-<h3>User Defined Hooks</h3>
-
-<p>User defined hooks should be executable (<code>chmod a+x</code>) scripts named
-<code>*.bash</code> or <code>*.hook</code>. They can live in two locations (or
-be symlinked there, to allow a single script to be shared between hooks):</p>
-
-<ul>
- <li><code><em>confdir</em>/hooks/<em>hookname</em>/</code>, where
- <code><em>confdir</em></code> is the directory in which <code>use.conf</code>
- et al. reside.</li>
-
- <li><code><em>DATADIR</em>/paludis/hooks/<em>hookname</em>/</code>. On most
- systems, <code><em>DATADIR</em></code> is <code>/usr/share</code>.</li>
-
- <li><code><em>LIBDIR</em>/paludis/hooks/<em>hookname</em>/</code>. On most
- systems, <code><em>LIBDIR</em></code> is <code>/usr/lib</code> or <code>/usr/lib64</code>.</li>
-</ul>
-
-<h4 id="bash-hooks">Bash Hooks</h4>
-
-<p>A <code>.bash</code> hook is merely executed when the associated action is
-triggered. There is no guarantee as to execution order.</p>
-
-<h4 id="hook-hooks">Hook Hooks</h4>
-
-<p>A <code>.hook</code> hook is more powerful. It must not run anything in
-global scope, but instead defines all its actions in functions. It must, at
-minimum, define a function called <code>hook_run_$HOOK</code> for each hook
-that it can handle. It may also define functions called <code>hook_depend_$HOOK</code>,
-which should output names of any other hooks upon which it depends, and
-<code>hook_after_$HOOK</code>, which is similar but indicates an ordering
-rather than hard dependency (the named hooks not existing is not an error).
-For example:</p>
-
-<pre>
-#!/bin/bash
-
-hook_run_install_all_post()
-{
- # ensure that einfo etc are available
- export PATH="$(${PALUDIS_EBUILD_DIR}/utils/canonicalise ${PALUDIS_EBUILD_DIR}/utils/ ):${PATH}"
- source ${PALUDIS_EBUILD_DIR}/echo_functions.bash
-
- echo
- einfo "Checking for monkeys..."
-
- if [[ -d "${ROOT}/var/lib/monkeys" ]] ; then
- for m in "${ROOT}"/var/lib/monkeys/* ; do
- ewarn "Found monkey $(basename ${m} )"
- done
- else
- einfo "No monkeys found"
- fi
-}
-
-hook_depend_install_all_post()
-{
- # we need to run after the Paludis standard eselect_env_update hook
- echo eselect_env_update
-}
-
-hook_after_install_all_post()
-{
- # if checking for rabbits or squirrels, do those first
- echo check_for_rabbits check_for_squirrels
-}
-</pre>
-
-<p>Note that the <code>hook_depend_</code> and <code>hook_after_</code> functions
-are cached, and are generally only called once per session, so the output should
-not vary based upon outside parameters.</p>
-
-<h4 id="py-hooks">Python Hooks</h4>
-
-<p>A <code>.py</code> hook is much like <code>.hook</code> hook, but written
-in Python and with full access to the current Paludis environment through
-Python bindings. For each hook it can handle it must, at minimum, define
-a function named <code>hook_run_$HOOK</code> which accepts exactly two positional
-arguments: the current Environment used by Paludis, and the additional Hook environment variables
-represented by a Python dictionary. It may also define the <code>hook_depend_$HOOK</code>
-and <code>hook_after_$HOOK</code> functions which must take exactly one argument,
-the Hook environment, and return a list of strings.
-For example:</p>
-
-<pre>
-def hook_run_install_all_post(env, hook_env):
- from paludis import *
-
- print "* Checking for monkeys..."
-
- if list(env.package_database().query(Query.Package("nice/monkey"))):
- print "Found a monkey!"
- else:
- print "No monkeys found"
-
-def hook_depend_install_all_post(hook_env):
- # we need to run after the Paludis standard eselect_env_update hook
- return ["eselect_env_update"]
-
-def hook_after_install_all_post(hook_env):
- # if checking for rabbits or squirrels, do those first
- return ["check_for_rabbits", "check_for_squirrels"]
-</pre>
-
-<h4 id="so-hooks">So Hooks</h4>
-
-<p>A <code>.so</code> hook is written in C++ and has full access to the Paludis public API.
-The hook takes the form of a shared library with a filename ending in <code>.so.<i>N</i></code>,
-where <i>N</i> is the first component of the Paludis version number multiplied by 100,
-plus the second component of the version number (for example, 26 for Paludis 0.26.x,
-or 102 for Paludis 1.2.y). The library must export a function with prototype
-<code>paludis::HookResult paludis_hook_run(const paludis::Environment *, const paludis::Hook &amp;)</code>
-that performs the action, and optionally one with prototype
-<code>void paludis_hook_add_dependencies(const paludis::Environment *, const paludis::Hook &amp;, paludis::DirectedGraph&lt;std::string, int&gt; &amp;)</code>
-if it needs to define ordering dependencies with other hooks. Both functions are
-declared in the header <code>&lt;paludis/hook.hh&gt;</code>, including any necessary
-<code>extern</code> or visibility declarations.</p>
-
-<p>The parameters and return values have the following meanings:</p>
-<dl>
-<dt><code>const paludis::Environment *</code></dt>
-<dd>The usual <code>Environment</code>, as used by all Paludis clients.</dd>
-<dt><code>const paludis::Hook &amp;</code></dt>
-<dd>Contains information about the hook being called. In <code>paludis_hook_add_dependencies</code>,
-the only useful member is <code>name()</code>.
-<dt><code>paludis::DirectedGraph&lt;std::string, int&gt; &amp;</code></dt>
-<dd>A graph containing, as nodes, all named hooks that will be executed along with
-this one. The <code>paludis_hook_add_dependencies</code> function should add any
-edges required to indicate its desired execution order relative to the other hooks,
-as follows: <code>g.add_edge("after", "before", 0);</code> (the 0 is not significant,
-but required by the <code>DirectedGraph</code> API).</dd>
-<dt><code>paludis::HookResult</code></dt>
-<dd>The <code>HookResult</code> constructor takes two arguments: an <code>int</code>,
-which should be zero if the hook is successful, or positive if not, and a <code>std::string</code>
-containing any information that should be passed back to the hook's caller (only
-used if the <code>Hook</code>'s <code>output_dest</code> member is <code>hod_grab</code>).</dd>
-</dl>
-
-<h3>Package Manager Defined Hooks</h3>
-
-<p>Paludis places some of its own hooks in
-<code><em>LIBEXECDIR</em>/hooks/<em>hookname</em></code>. These directories are
-not for end user use.</p>
-
-<h3>Example Hooks</h3>
-
-<p>Paludis ships certain example hooks that many users would find useful, but that
-are not suitably general to be enabled by default -- these live in
-<code>DATADIR/paludis/hooks/demos/</code>. You may also find the default
-hooks useful -- these live in various places in <code>LIBEXECDIR/paludis/hooks/</code>.</p>
-
-<h3>The <code>PALUDIS_CMDLINE</code> Variables</h3>
-
-<p>Sometimes hooks need access to the commandline used to invoke
-<code>paludis</code>. However, manual parsing of the commandline by hooks will
-lead to bugs when people forget to emulate certain behaviour (say, short
-options, aliases or <code>--</code> support). To work around this issue,
-Paludis provides environment variables prefixed <code>PALUDIS_CMDLINE_</code>
-that specify the parsed command line:</p>
-
-<ul>
- <li>The <code>PALUDIS_CMDLINE_PARAMS</code> variable contains the parameters (that is,
- the parts that aren't <code>-x</code> or <code>--blah</code> or values for these).</li>
-
- <li>For each <code>--param-name</code>, <code>PALUDIS_CMDLINE_param_name</code> (note
- the case and the underscores) is set. If <code>--param-name</code> takes an argument,
- this argument is used for the environment variable's value.</li>
-
- <li>For short options (<code>-x</code>) and aliases, the appropriate long option's
- variable is set instead.</li>
-</ul>
-
-@FOOTER@
-</body>
-</html>
-
-
diff --git a/doc/htaccess b/doc/htaccess
deleted file mode 100644
index f0280c6..0000000
--- a/doc/htaccess
+++ /dev/null
@@ -1,10 +0,0 @@
-# vim: set ft=apache :
-
-AddCharset UTF-8 .html
-
-Redirect Permanent /News.html http://paludis.pioto.org/news.html
-Redirect Permanent /PaludisNews.html http://paludis.pioto.org/news.html
-Redirect Permanent /KnownIssues.html http://paludis.pioto.org/faq.html
-Redirect Permanent /Authors.html http://paludis.pioto.org/authors.html
-Redirect Permanent /Licence.html http://paludis.pioto.org/licence.html
-
diff --git a/doc/htmlfooter.html b/doc/htmlfooter.html
deleted file mode 100644
index bc79603..0000000
--- a/doc/htmlfooter.html
+++ /dev/null
@@ -1,7 +0,0 @@
-<div class="qindex" style="text-align: center; margin-top: 1em;">
- <p>Copyright &copy; 2005, 2006, 2007 <a href="http://ciaranm.org/">Ciaran
- McCreesh</a> and various others. See the <a href="authors.html">Authors
- list</a> and <a href="licence.html">Licence</a> for details and redistribution conditions.</p>
-</div>
-
-
diff --git a/doc/htmlheader.html b/doc/htmlheader.html
deleted file mode 100644
index 5ad20e8..0000000
--- a/doc/htmlheader.html
+++ /dev/null
@@ -1,48 +0,0 @@
-<div class="qindex">
- <table border="0">
- <tr>
- <td><a href="index.html"><img src="paludis_270.png" alt="Paludis logo"
- style="border: 0px;" /></a></td>
- <td style="text-align: left;">
- <ul>
- <li><a class="qindex" href="/faq.html">FAQ&nbsp;(Important!)</a></li>
- <li><a class="qindex" href="http://paludis.pioto.org/trac/">Bugs&nbsp;and&nbsp;Requests</a></li>
- <li><a class="qindex"
- href="/portagedifferences.html">Portage&nbsp;Differences</a></li>
- <li><a class="qindex"
- href="/migration.html">Migration&nbsp;Guide</a></li>
- </ul>
- </td>
- <td style="text-align: left;">
- <ul>
- <li><a class="qindex"
- href="/configuration.html">Configuration&nbsp;Guide</a></li>
- <li><a class="qindex"
- href="/cachefiles.html">Cache&nbsp;Options</a></li>
- <li><a class="qindex"
- href="/sets.html">Sets&nbsp;Guide</a></li>
- <li><a class="qindex"
- href="/hooks.html">Hooks&nbsp;Guide</a></li>
- </ul>
- </td>
- <td style="text-align: left;">
- <ul>
- <li><a class="qindex" href="/news.html">Release&nbsp;Notes</a></li>
- <li><a class="qindex" href="/changelog.html">ChangeLog</a></li>
- <li><a class="qindex" href="/licence.html">Licence</a></li>
- <li><a class="qindex" href="/authors.html">Authors</a></li>
- </ul>
- </td>
- <td style="text-align: left;">
- <ul>
- <li><a class="qindex" href="https://developer.berlios.de/project/showfiles.php?group_id=6360">Download</a></li>
- <li><a class="qindex" href="http://paludis.pioto.org/trac/browser">SVN</a></li>
- <li><a class="qindex" href="https://developer.berlios.de/projects/paludis/">Berlios&nbsp;Project</a></li>
- <li><a class="qindex"
- href="http://lists.pioto.org/">Mailing&nbsp;Lists</a></li>
- </ul>
- </td>
- </tr>
- </table>
-</div>
-
diff --git a/doc/index.html.skel b/doc/index.html.skel
deleted file mode 100644
index 2bd316a..0000000
--- a/doc/index.html.skel
+++ /dev/null
@@ -1,99 +0,0 @@
-<!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>
-
- <p>Paludis is a package manager for use with <a
- href="http://www.gentoo.org/">Gentoo</a> and related distributions. It
- is entirely independent of Portage. The current version is <strong>@VERSION@</strong>,
- with the following changes:</p>
-
-@RECENTNEWS@
-
- <p>See the <a href="news.html">Release Notes</a> for previous releases.</p>
-
- <h2>For prospective users:</h2>
-
- <ul>
- <li>An overview of <a href="portagedifferences.html">the differences between
- Paludis and its predecessor, Portage</a>.</li>
-
- <li>A <a href="migration.html">guide to migrating to
- Paludis</a>.</li>
- </ul>
-
- <h2>For current users:</h2>
-
- <ul>
- <li>An <a href="faq.html">FAQ</a> is available. You should familiarise
- yourself with this list before asking questions.</li>
-
- <li>The <a href="news.html">release notes</a> document major
- changes between releases. More detailed information is available
- in the <a href="changelog.html">changelog</a>.</li>
-
- <li>There is <a href="configuration.html">documentation on the
- configuration files</a> and <a href="cachefiles.html">the
- various optional caches</a> used by Paludis. There is also documentation on
- <a href="sets.html">sets (including how user defined sets work)</a> and
- <a href="hooks.html">hooks (and how user defined hooks work)</a>.</li>
-
- <li><strong>Support</strong> is available via <code>#paludis</code> on
- <code>irc.freenode.net</code> or the <a
- href="http://lists.pioto.org/">mailing
- lists</a>. There is a <a
- href="http://paludis.pioto.org/trac/">bug tracker</a> that can
- be used for bug reports and feature requests.</li>
-
- <li>Manual pages:
- <ul>
- <li><a href="man-accerso.html">accerso</a>, the mirror client</li>
- <li><a href="man-adjutrix.html">adjutrix</a>, the developer tools
- client</li>
- <li><a href="man-contrarius.html">contrarius</a>, the
- cross-toolchain generation client</li>
- <li><a href="man-inquisitio.html">inquisitio</a>, the search client</li>
- <li><a href="man-instruo.html">instruo</a>, the metadata generation
- client</li>
- <li><a href="man-paludis.html">paludis</a>, the console package
- management client</li>
- <li><a href="man-qualudis.html">qualudis</a>, the QA client</li>
- </ul>
- </li>
-
- </ul>
-
- <h2>For developers:</h2>
-
- <ul>
- <li><strong>Subversion access</strong> is available via
- <code>svn co svn://svn.pioto.org/paludis/trunk paludis</code>. There
- is also <a href="http://paludis.pioto.org/trac/browser">Trac's
- code browser</a> for viewing via the web.</li>
-
- <li>There is <a href="doxygen/html"/>extensive C++ core API and implementation
- documentation</a>. This is also available via <code>make
- doxygen</code>.</li>
-
- <li>Similarly, the <a href="ruby/">Ruby API documentation</a> is available
- via <code>make rdoc</code> and the <a href="python/doc/">Python API documentation</a>
- via <code>make epydoc</code>.</li>
-
- <li><strong>Development questions</strong> should be asked in <code>#paludis</code> on
- <code>irc.freenode.net</code> or on the <a
- href="http://lists.pioto.org/">mailing lists</a>.
- Patches go to the <a href="http://paludis.pioto.org/trac/">bug tracker</a>.</li>
-
- </ul>
-
-@FOOTER@
-</body>
-</html>
-
diff --git a/doc/licence.html.skel b/doc/licence.html.skel
deleted file mode 100644
index 1c0cbc9..0000000
--- a/doc/licence.html.skel
+++ /dev/null
@@ -1,26 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<!-- vim: set ft=html : -->
-<html lang="en" xml:lang="en">
-<head>
-<title>Paludis, the Other Package Mangler: Release Notes</title>
-<link rel="stylesheet" href="paludis.css" type="text/css" />
-</head>
-<body>
-@HEADER@
-
- <h1>Paludis, the Other Package Mangler</h1>
-
- <h2>Licence</h2>
-
-<pre>
-@COPYING@
-</pre>
-
-@FOOTER@
-</body>
-</html>
-
-
-
-
diff --git a/doc/man.html.skel b/doc/man.html.skel
deleted file mode 100644
index 7bb27e7..0000000
--- a/doc/man.html.skel
+++ /dev/null
@@ -1,17 +0,0 @@
-<!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@
-
-@MAN@
-
-@FOOTER@
-</body>
-</html>
-
-
diff --git a/doc/migration.html.skel b/doc/migration.html.skel
deleted file mode 100644
index 379538a..0000000
--- a/doc/migration.html.skel
+++ /dev/null
@@ -1,204 +0,0 @@
-<!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>Migrating to Paludis</h2>
-
-<p>There are two methods you can follow to migrate from Portage to Paludis: the
-<a href="#manual">manual method</a> or the <a href="#automated">automated
- method</a>. Also, it is now usually possible to migrate <a
- href="#coward">from Paludis back to Portage</a>.</p>
-
-<p><strong>Warning:</strong> Migration is not always entirely reliable. If
-you've had an install for a long time, chances are your system contains a fair
-amount of cruft generated by buggy Portage versions. You may need to fix this
-manually.</p>
-
-<p>No matter which method you plan to use, start by installing Paludis. There
-are ebuilds in the tree, or you can get SVN ebuilds (which Portage can't use)
-from <a href="http://paludis.pioto.org/trac/browser/overlay/">the Paludis
- overlay</a>. If you don't like the <code>libxml2</code> and
-<code>pcre++</code> dependencies, turn off the <code>qa</code> USE flag.
-<strong>Make sure you are using at least version 0.14</strong> when following
-this guide.</p>
-
-<h3 id="automated">How to Migrate from Portage to Paludis (the automated
- method)</h3>
-
-The easiest way to migrate your configuration from Portage to Paludis is by
-using the <a href="http://paludis.pioto.org/trac/browser/scratch/scripts/portage2paludis.bash?format=raw">portage2paludis.bash</a> script, available via subversion. It is invoked as follows:
-
-<pre>
-$ sudo ./portage2paludis.bash
-</pre>
-
-<p>A few notes on the migration script. The target configuration directory <b>must not exist</b>,
-or the script will bail out. This is to prevent it from clobbering an existing
-paludis config. Also, the script will not migrate your customized portage
-bashrc -- this is something you will have to do on your own.</p>
-
-<p>The script will migrate your <code>PORTDIR_OVERLAYS</code> to Paludis as best as
-possible. Finally, the script
-will first try to name your repositories what their profiles/repo_name file
-says they should be called and, if that fails, they will be called what their
-top level directory is called (so, /usr/local/portage is called "portage"). If
-any name collisions occur, the script will terminate, and you will have to
-finish configuring your overlays on your own.</p>
-
-<p>Now, try:</p>
-
-<pre>
-sudo paludis --sync
-paludis -pi world
-</pre>
-
-<p>You will likely find that it picks up a few packages that Portage wouldn't. This
-is to be expected -- the Paludis dependency resolver is considerably more complete
-than the Portage one, and it will try to enforce runtime dependencies of already
-installed packages. In particular, this means that if you have any packages
-installed that have a <code>virtual/x11</code> runtime dependency, the virtual will
-be pulled in.</p>
-
-<p>You may encounter some nasty error messages, especially if you're running an old
-install and have some packages that were installed a very long time ago with a
-broken Portage release. In most cases, removing the VDB entry by hand and then
-immediately reinstalling the same version of the package using Paludis (or even
-a recent Portage) will suffice.</p>
-
-<h3 id="#manual">How to Migrate from Portage to Paludis (the manual method)</h3>
-
-<p>First, make some configuration files. For full details, see <a
- href="configuration.html">the configuration files documentation</a>.
-For a quick template:</p>
-
-<pre>
-mkdir -p /etc/paludis/repositories
-
-cat &lt;&lt;"END" &gt; /etc/paludis/keywords.conf
-*/* x86
-dev-cpp/libebt x86 ~x86
-sys-apps/paludis x86 ~x86
-dev-util/subversion x86 ~x86
-app-admin/eselect x86 ~x86
-sys-fs/udev x86 ~x86
-END
-
-cat &lt;&lt;"END" &gt; /etc/paludis/use.conf
-*/* -doc nls -apache2
-*/* LINGUAS: en
-*/* INPUT_DEVICES: keyboard mouse
-*/* VIDEO_CARDS: -* ati
-app-editors/vim -nls
-END
-
-cat &lt;&lt;"END" &gt; /etc/paludis/licenses.conf
-*/* *
-END
-
-cat &lt;&lt;"END" &gt; /etc/paludis/mirrors.conf
-gentoo http://gentoo.blueyonder.co.uk/distfiles/
-gnu http://gnu.blueyonder.co.uk/
-debian http://debian.blueyonder.co.uk/
-END
-</pre>
-
-<p>Set up your <code>bashrc</code>. This must <b>NOT</b> be used to change any
-values that affect dependency resolution (e.g. <code>USE</code>,
-<code>LINGUAS</code>). It can be used to set <code>CFLAGS</code>,
-<code>CHOST</code> and the like (on some archs you'll have to do this to
-avoid getting junk from your profile).</p>
-
-<pre>
-cat &lt;&lt;"END" &gt; /etc/paludis/bashrc
-CFLAGS="-O2 -march=pentium4 -fomit-frame-pointer"
-CXXFLAGS="${CFLAGS}"
-CHOST="i686-pc-linux-gnu"
-MAKEOPTS="-j2"
-END
-</pre>
-
-<p>Set up your repository files. Do not tinker with the VDB location, it
-<b>must</b> go in <code>${ROOT}/var/db/pkg</code>. Here we'll avoid using
-<code>/usr/portage</code> for the main tree because sticking data that gets
-changed on <code>/usr</code> is silly.</p>
-
-<p>You will also need to specify <code>names_cache</code> for the ebuild format
-repositories and <code>provides_cache</code> for the VDB repositories.
-See <a href="cachefiles.html">the cache documentation</a>.</p>
-
-<pre>
-cat &lt;&lt;"END" &gt; /etc/paludis/repositories/gentoo.conf
-location = /var/paludis/repositories/gentoo/
-sync = rsync://rsync.europe.gentoo.org/gentoo-portage/
-profiles = /var/paludis/repositories/gentoo/profiles/default-linux/x86/2006.0
-format = ebuild
-END
-
-cat &lt;&lt;"END" &gt; /etc/paludis/repositories/installed.conf
-location = /var/db/pkg/
-format = vdb
-END
-
-cat &lt;&lt;"END" &gt; /etc/paludis/repositories/paludis-overlay.conf
-location = /var/paludis/repositories/paludis-overlay/
-sync = svn://svn.pioto.org/paludis/overlay
-cache = /var/empty
-format = ebuild
-master_repository = gentoo
-END
-</pre>
-
-<p>The world file for Paludis lives in the VDB directory. For Portage compatibility,
-a symlink can be used (but be careful when uninstalling Portage if you use this
-route).</p>
-
-<pre>
-sudo ln -s /var/lib/portage/world /var/db/pkg/world
-</pre>
-
-<p>Now, try:</p>
-
-<pre>
-sudo paludis --sync
-paludis -pi world
-</pre>
-
-<p>You will likely find that it picks up a few packages that Portage wouldn't. This
-is to be expected -- the Paludis dependency resolver is considerably more complete
-than the Portage one, and it will try to enforce runtime dependencies of already
-installed packages. In particular, this means that if you have any packages
-installed that have a <code>virtual/x11</code> runtime dependency, the virtual will
-be pulled in.</p>
-
-<p>You may encounter some nasty error messages, especially if you're running an old
-install and have some packages that were installed a very long time ago with a
-broken Portage release. In most cases, removing the VDB entry by hand and then
-immediately reinstalling the same version of the package using Paludis (or even
-a recent Portage) will suffice.</p>
-
-<h3 id="#coward">How to Migrate from Paludis to Portage</h3>
-
-<p>Start by uninstalling any packages that use <code>-scm</code> or
-<code>-try</code>. Also <code>rm -fr</code> any <code>.cache</code> directories
-created inside repository directories.</p>
-
-<p>Finally <code>emerge --sync</code> (this is important) and you might be back to normal.
-If you encounter weird failures when upgrading or uninstalling packages that were
-installed by Paludis, removing the VDB entry by hand and then immediately
-reinstalling the same version of the package using Portage will usually fix
-things.</p>
-
-@FOOTER@
-</body>
-</html>
-
-
-
diff --git a/doc/news.html.skel b/doc/news.html.skel
deleted file mode 100644
index d8c327e..0000000
--- a/doc/news.html.skel
+++ /dev/null
@@ -1,23 +0,0 @@
-<!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: Release Notes</title>
-<link rel="stylesheet" href="paludis.css" type="text/css" />
-</head>
-<body>
-@HEADER@
-
- <h1>Paludis, the Other Package Mangler</h1>
-
- <h2>Release Notes</h2>
-
-@RELEASE_NOTES@
-
- </li></ul>
-
-@FOOTER@
-</body>
-</html>
-
-
diff --git a/doc/overview/Makefile.am b/doc/overview/Makefile.am
new file mode 100644
index 0000000..e412f64
--- /dev/null
+++ b/doc/overview/Makefile.am
@@ -0,0 +1,13 @@
+SUBDIRS = .
+
+CLEANFILES = *~ gmon.out *.gcov *.gcno *.gcda
+MAINTAINERCLEANFILES = Makefile.in
+
+built-sources : $(BUILT_SOURCES)
+ for s in `echo $(SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s built-sources || exit 1 ; done
+
+distcheck-deps : $(DISTCHECK_DEPS) distcheck-deps-subdirs
+
+distcheck-deps-subdirs :
+ for s in `echo $(DIST_SUBDIRS) | tr -d .` ; do $(MAKE) -C $$s distcheck-deps || exit 1 ; done
+
diff --git a/doc/overview/contact.html.part b/doc/overview/contact.html.part
new file mode 100644
index 0000000..3e212ff
--- /dev/null
+++ b/doc/overview/contact.html.part
@@ -0,0 +1,25 @@
+<!-- vim: set tw=120 ft=html sw=4 sts=4 et : -->
+
+<h1>Contact Options</h1>
+
+<h2>IRC</h2>
+
+<p>You can find us on IRC in <code>#paludis</code> on <code>irc.freenode.net</code>.</p>
+
+<h2>Mailing Lists</h2>
+
+<p>We have two mailing lists:</p>
+
+<ul>
+ <li><a href="http://lists.pioto.org/mailman/listinfo/paludis-user">paludis-user</a>, for general
+ user questions.</li>
+ <li><a href="http://lists.pioto.org/mailman/listinfo/paludis-sekrit">paludis-sekrit</a>, for
+ development. Rather high noise, since it gets an auto-CC: on trac tickets and nightly build reports.
+ Approval is required to subscribe.</li>
+</ul>
+
+<h2>Bug Reports</h2>
+
+<p>We use <a href="http://paludis.pioto.org/trac/">Trac</a> for bug reports, feature requests and
+so on.</p>
+
diff --git a/doc/overview/features.html.part b/doc/overview/features.html.part
new file mode 100644
index 0000000..febe79c
--- /dev/null
+++ b/doc/overview/features.html.part
@@ -0,0 +1,93 @@
+<!-- vim: set tw=120 ft=html sw=4 sts=4 et : -->
+
+<h1>Features</h1>
+
+<h2>For the End User</h2>
+
+<ul>
+ <li>An optional new configuration system, making it much easier to operate upon
+ groups of related packages, much easier to maintain multiple systems (or chroots)
+ and much easier to set options on a per-package or per-repository basis.</li>
+
+ <li>Performance. Paludis can be an order of magnitude faster than other package
+ managers.</li>
+
+ <li>Low dependency bloat. No Python, no big external crypto libraries.</li>
+
+ <li>Native security (GLSA) integration.</li>
+
+ <li>Proper multiple repository support, not constrained by a limited 'overlay'
+ model.</li>
+
+ <li>Support for repositories containing things other than ebuilds.</li>
+
+ <li>License filtering.</li>
+
+ <li>Hook scripts, for running code after a certain action occurs.</li>
+
+ <li>User definable package sets.</li>
+
+ <li>Ability to sync multiple repositories, natively, using SVN, CVS, Git etc.</li>
+
+ <li>Ability to uninstall packages with dependencies, and safely remove unneeded
+ packages.</li>
+
+ <li>Ability to continue with a collection of installs after a failure, and to resume
+ failed compiles far more flexibly than offered by Portage.</li>
+
+ <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
+ relevant information (e.g. USE flag descriptions and an explanation of why a package
+ is being pulled in).</li>
+
+ <li>Secure (un)installation of set*id files, preventing your system from being left
+ vulnerable after having replaced a vulnerable application.</li>
+
+ <li>Ability to use slot, use, repository and ranged version dependencies when selecting
+ a version.</li>
+
+ <li>Ability to see all packages that need unmasking in one go, rather than one package
+ at a time.</li>
+
+ <li>Ability to automatically reinstall scm (svn, cvs etc.) packages after a given period
+ (daily, weekly, ...).</li>
+
+ <li>Ability to manage packages even where no ebuild is available.</li>
+</ul>
+
+<h2>For the Ebuild Developer</h2>
+
+<ul>
+ <li>Full and correct circular dependency resolution.</li>
+
+ <li>Default deep dependency resolution.</li>
+
+ <li>Support for 'experimental' (read: 'still not implemented in Portage') EAPI proposals
+ (use dependencies, ranged version specs, -scm and -try version specs, src_uri arrows etc).</li>
+
+ <li>Ability to deliver news items to the end user.</li>
+
+ <li>Much more useful diagnostics.</li>
+</ul>
+
+<h2>For the Programmer</h2>
+
+<ul>
+ <li>Proper client / library separation.</li>
+
+ <li>API documentation and code examples.</li>
+
+ <li>A sane OO API.</li>
+
+ <li>Consistent interfaces for different repository types.</li>
+
+ <li>Test suites and extensive static checking, to check the impact of changes.</li>
+
+ <li>Type safe interfaces, for catching programming errors at compile time.</li>
+
+ <li>A choice of programming language for external tools.</li>
+</ul>
+
diff --git a/doc/paludis.css b/doc/paludis.css
deleted file mode 100644
index f5c184f..0000000
--- a/doc/paludis.css
+++ /dev/null
@@ -1,391 +0,0 @@
-body {
- background-color: #eedd99;
- color: #333333;
- font-family: "Verdana", "Helvetica", sans-serif;
-}
-
-h1 {
- text-align: center;
- font-size: x-large;
- border-bottom: 1px dashed #aa9933;
-}
-
-h2 {
- text-align: left;
- border-bottom: 1px dashed #aa9933;
- font-size: x-large;
-}
-
-h3 {
- font-size: large;
- text-align: left;
- border-bottom: 1px dashed #ddcc99;
-}
-
-caption {
- font-weight: bold;
-}
-
-div.qindex {
- width: 100%;
- background-color: #ddcc99;
- border: 1px solid #aa9933;
- text-align: center;
- margin: 2px;
- padding: 2px;
- font-size: small;
- line-height: 140%;
-}
-
-div.nav {
- width: 100%;
- background-color: #ddcc99;
- border: 1px solid #aa9933;
- text-align: center;
- margin: 2px;
- padding: 2px;
- font-size: small;
- line-height: 140%;
-}
-
-a:link {
- text-decoration: none;
- font-weight: bold;
- color: #996600;
-}
-
-a:visited {
- text-decoration: none;
- font-weight: bold;
- color: #996600;
-}
-
-a:hover {
- text-decoration: none;
- background-color: #996600;
- font-weight: bold;
- color: #ffffff;
-}
-
-a:hover img {
- background-color: #996600;
-}
-
-a.el {
- font-weight: bold;
-}
-
-a.elRef {
- font-weight: bold;
-}
-
-.fragment {
- font-family: monospace;
-}
-
-pre {
- border: 1px solid #ddcc99;
- background-color: #eee4bb;
- margin-top: 4px;
- margin-bottom: 4px;
- margin-left: 2px;
- margin-right: 8px;
- padding-left: 6px;
- padding-right: 6px;
- padding-top: 4px;
- padding-bottom: 4px;
-}
-
-div.ah {
- background-color: black;
- font-weight: bold;
- color: #ffffff;
- margin-bottom: 3px;
- margin-top: 3px;
-}
-
-td.md {
- background-color: #eee4bb;
- font-weight: bold;
-}
-
-td.mdPrefix {
- background-color: #eee4bb;
- color: #606060;
-}
-
-td.mdname1 {
- background-color: #eee4bb;
- font-weight: bold;
- color: #602020;
-}
-
-td.mdname {
- background-color: #eee4bb;
- font-weight: bold;
- color: #602020;
-}
-
-div.groupHeader {
- margin-left: 16px;
- margin-top: 12px;
- margin-bottom: 6px;
- font-weight: bold;
-}
-
-div.groupText {
- margin-left: 16px;
- font-style: italic;
- font-size: small;
-}
-
-td.indexkey {
- background-color: #eee4bb;
- font-weight: bold;
- padding-right : 10px;
- padding-top : 2px;
- padding-left : 10px;
- padding-bottom : 2px;
- margin-left : 0px;
- margin-right : 0px;
- margin-top : 2px;
- margin-bottom : 2px;
- border: 1px solid #ddcc99;
-}
-
-td.indexvalue {
- background-color: #eee4bb;
- font-style: italic;
- padding-right : 10px;
- padding-top : 2px;
- padding-left : 10px;
- padding-bottom : 2px;
- margin-left : 0px;
- margin-right : 0px;
- margin-top : 2px;
- margin-bottom : 2px;
- border: 1px solid #ddcc99;
-}
-
-tr.memlist {
- background-color: #f0f0f0;
-}
-
-p.formulaDsp { text-align: center; }
-IMG.formulaDsp { }
-IMG.formulaInl { vertical-align: middle; }
-SPAN.keyword { color: #008000 }
-SPAN.keywordtype { color: #604020 }
-SPAN.keywordflow { color: #e08000 }
-SPAN.comment { color: #800000 }
-SPAN.preprocessor { color: #806020 }
-SPAN.stringliteral { color: #002080 }
-SPAN.charliteral { color: #008080 }
-.mdTable {
- border: 1px solid #868686;
- background-color: #eee4bb;
-}
-.mdRow {
- padding: 8px 10px;
-}
-.mdescLeft {
- padding: 0px 8px 4px 8px;
- font-size: small;
- font-style: italic;
- background-color: #FAFAFA;
- border-top: 1px none #E0E0E0;
- border-right: 1px none #E0E0E0;
- border-bottom: 1px none #E0E0E0;
- border-left: 1px none #E0E0E0;
- margin: 0px;
-}
-.mdescRight {
- padding: 0px 8px 4px 8px;
- font-size: small;
- font-style: italic;
- background-color: #FAFAFA;
- border-top: 1px none #E0E0E0;
- border-right: 1px none #E0E0E0;
- border-bottom: 1px none #E0E0E0;
- border-left: 1px none #E0E0E0;
- margin: 0px;
-}
-.memItemLeft {
- padding: 1px 0px 0px 8px;
- margin: 4px;
- border-top-width: 1px;
- border-right-width: 1px;
- border-bottom-width: 1px;
- border-left-width: 1px;
- border-top-color: #E0E0E0;
- border-right-color: #E0E0E0;
- border-bottom-color: #E0E0E0;
- border-left-color: #E0E0E0;
- border-top-style: solid;
- border-right-style: none;
- border-bottom-style: none;
- border-left-style: none;
- background-color: #FAFAFA;
- font-size: small;
-}
-.memItemRight {
- padding: 1px 8px 0px 8px;
- margin: 4px;
- border-top-width: 1px;
- border-right-width: 1px;
- border-bottom-width: 1px;
- border-left-width: 1px;
- border-top-color: #E0E0E0;
- border-right-color: #E0E0E0;
- border-bottom-color: #E0E0E0;
- border-left-color: #E0E0E0;
- border-top-style: solid;
- border-right-style: none;
- border-bottom-style: none;
- border-left-style: none;
- background-color: #FAFAFA;
- font-size: small;
-}
-.memTemplItemLeft {
- padding: 1px 0px 0px 8px;
- margin: 4px;
- border-top-width: 1px;
- border-right-width: 1px;
- border-bottom-width: 1px;
- border-left-width: 1px;
- border-top-color: #E0E0E0;
- border-right-color: #E0E0E0;
- border-bottom-color: #E0E0E0;
- border-left-color: #E0E0E0;
- border-top-style: none;
- border-right-style: none;
- border-bottom-style: none;
- border-left-style: none;
- background-color: #FAFAFA;
- font-size: small;
-}
-.memTemplItemRight {
- padding: 1px 8px 0px 8px;
- margin: 4px;
- border-top-width: 1px;
- border-right-width: 1px;
- border-bottom-width: 1px;
- border-left-width: 1px;
- border-top-color: #E0E0E0;
- border-right-color: #E0E0E0;
- border-bottom-color: #E0E0E0;
- border-left-color: #E0E0E0;
- border-top-style: none;
- border-right-style: none;
- border-bottom-style: none;
- border-left-style: none;
- background-color: #FAFAFA;
- font-size: small;
-}
-.memTemplParams {
- padding: 1px 0px 0px 8px;
- margin: 4px;
- border-top-width: 1px;
- border-right-width: 1px;
- border-bottom-width: 1px;
- border-left-width: 1px;
- border-top-color: #E0E0E0;
- border-right-color: #E0E0E0;
- border-bottom-color: #E0E0E0;
- border-left-color: #E0E0E0;
- border-top-style: solid;
- border-right-style: none;
- border-bottom-style: none;
- border-left-style: none;
- color: #606060;
- background-color: #FAFAFA;
- font-size: small;
-}
-.memtemplate {
- font-size: small;
- color: #606060;
- font-weight: normal;
-}
-.memnav {
- background-color: #e8e8e8;
- border: 1px solid #333333;
- text-align: center;
- margin: 2px;
- margin-right: 15px;
- padding: 2px;
-}
-.memitem {
- background-color: #eedd99;
- border-width: 1px;
- border-style: solid;
- border-color: #aa9933;
-}
-.memname {
- white-space: nowrap;
- font-weight: bold;
-}
-.memdoc{
- padding-left: 10px;
-}
-.memproto {
- background-color: #f8f8f8;
- width: 100%;
- border-bottom-width: 1px;
- border-bottom-style: solid;
- border-bottom-color: #aa9933;
- font-weight: bold;
-}
-.memproto * {
- font-size: small;
-}
-.paramkey {
- text-align: right;
-}
-.paramtype {
- white-space: nowrap;
-}
-.paramname {
- color: #666666;
- font-style: italic;
- white-space: nowrap;
-}
-
-.search { color: #003399;
- font-weight: bold;
-}
-FORM.search {
- margin-bottom: 0px;
- margin-top: 0px;
-}
-INPUT.search { font-size: small;
- color: #000080;
- font-weight: normal;
- background-color: #eee4bb;
-}
-TD.tiny { font-size: 75%;
-}
-.dirtab { padding: 4px;
- border-collapse: collapse;
- border: 1px solid #b0b0b0;
-}
-TH.dirtab { background: #eee4bb;
- font-weight: bold;
-}
-HR { height: 1px;
- border: none;
- border-top: 1px solid black;
-}
-
-code {
- background-color: #ddcc99;
-}
-
-dd {
- margin-left: 3em;
- margin-bottom: 0.3em;
-}
-
-dt {
- font-weight: bold;
-}
-
diff --git a/doc/portagedifferences.html.skel b/doc/portagedifferences.html.skel
deleted file mode 100644
index 8ac27c3..0000000
--- a/doc/portagedifferences.html.skel
+++ /dev/null
@@ -1,147 +0,0 @@
-<!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>How Paludis and Portage Differ</h2>
-
- <p>This is not a complete list. It's not even vaguely near complete. Rather, it's
- a collection of lists of things of interest that are intentionally different
- between Paludis and its predecessor, Portage.</p>
-
- <h3>For the End User</h3>
-
- <ul>
-
- <li>A whole different <a
- href="configuration.html">configuration system</a>, making it far easier to maintain
- multiple systems, some in chroots, with entirely separate configuration
- files.</li>
-
- <li>Performance. Paludis is <a
- href="http://ciaranm.org/show_post.pl?post_id=61">fast</a>.</li>
-
- <li>Low dependency bloat. No Python, no big external crypto libraries.</li>
-
- <li>Security integration (<code>paludis --pretend --install
- security</code>).</li>
-
- <li>Multiple repository support, replacing Portage's highly limited
- overlays.</li>
-
- <li>Support for repositories of different types (e.g. CRAN).</li>
-
- <li>Simple per-(category, package, version, anything else) environment variable
- setting (e.g. CFLAGS) without having to add on nasty external hacks.</li>
-
- <li>Licence filtering.</li>
-
- <li>Hook scripts, for running code after a certain action occurs.</li>
-
- <li>Wrappers for econf, emake, wget etc to allow user defined command bindings
- (nice, ionice, taskset etc).</li>
-
- <li>User definable package sets.</li>
-
- <li>Repositories can deliver news items, warning the user of important changes
- before they take place.</li>
-
- <li>Ability to sync from Subversion, Git, CVS etc.</li>
-
- <li>Ability to <a href="faq.html#removeunneeded">uninstall packages with dependencies</a>, and safely remove
- unused packages.</li>
-
- <li>Ability to see a report of insecure, unused etc packages affecting the
- system, either manually or automatically after a sync (<code>paludis
- --report</code>).</li>
-
- <li>Ability to <a href="faq.html#tree">see why a package is
- really being pulled in</a>, replacing Portage's
- misleading and incomplete tree support.</li>
-
- <li>Much more fine grained control over dropping dependencies.</li>
-
- <li>Ability to automatically reinstall scm (cvs, svn etc) packages after a
- given interval (<code>paludis --dl-reinstall-scm weekly</code>).</li>
-
- <li>Ability to <a href="faq.html#skipfirst">resume failed
- compiles</a> with far more control than is offered
- by Portage's limited <code>--resume</code> and
- <code>--skipfirst</code>.</li>
-
- <li>Ability to display additional information, such as USE flag
- descriptions, when installing a package.</li>
-
- <li>Secure installation and uninstallation of set*id files,
- preventing your system from being left vulnerable after having
- uninstalled or replaced an insecure application.</li>
- </ul>
-
- <h3>For the Ebuild Developer</h3>
-
- <p>As well as the end user advantages, ebuild authors will benefit from:</p>
-
- <ul>
- <li><code>:slot</code> dependencies</li>
-
- <li><code>::repository</code> dependencies</li>
-
- <li><code>[use]</code> dependencies</li>
-
- <li>Full and correct circular dependency detection</li>
-
- <li>Per package use masking, and from this per package use combination
- restrictions.</li>
-
- <li>Profile-level use forcing, globally and per-package, and from this the
- ability to specify a default in cases where one of n USE flags must be
- enabled.</li>
-
- <li>Default deep dependency resolution.</li>
-
- <li>Support for -scm, -try versions.</li>
-
- <li>Multiple inheritance for profiles.</li>
-
- <li>Ability to install hook scripts.</li>
-
- <li>Repository definable package sets.</li>
-
- <li>Ability to deliver news items to the end user.</li>
-
- <li>Ranged dep specification support.</li>
-
- <li>Extensive and easily extendable QA checks.</li>
-
- <li>Much more meaningful error messages, with proper context.</li>
- </ul>
-
- <h3>For the Programmer</h3>
-
- <ul>
- <li>Proper library / interface separation.</li>
-
- <li>Reasonable internals documentation, via Doxygen.</li>
-
- <li>Consistent interfaces for different repository types.</li>
-
- <li>Modularity where it matters.</li>
-
- <li>Test suites, to detect the impact of changes.</li>
-
- <li>Type safe interfaces, for detecting errors at compile time.</li>
-
- <li>A choice of programming language for external tools.</li>
- </ul>
-
-@FOOTER@
- </body>
-</html>
-
diff --git a/doc/sets.html.skel b/doc/sets.html.skel
deleted file mode 100644
index c4020b3..0000000
--- a/doc/sets.html.skel
+++ /dev/null
@@ -1,90 +0,0 @@
-<!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>Sets</h2>
-
-<h3>Overview</h3>
-
-<p>This document explains the concept known to Paludis as a 'set', and describes the standard
-internal sets and how to create new sets.</p>
-
-<h3>Formal Set Description</h3>
-
-<p>Internally, a set is a name with an associated dependency-style specification. In most cases
-the dependency specification will be an 'all-of' collection of package dependencies, although
-this is not a hard restriction.</p>
-
-<p>There are multiple origins for sets:</p>
-
-<ul>
- <li>Some environment classes define their own package sets (possibly via user configuration
- files). A set defined by the environment <em>overrides</em> any later set of the same name.</li>
-
- <li>Most repositories define their own package sets. Some of these are defined internally --
- examples include <code>everything</code>, <code>system</code>, <code>world</code> and
- <code>security</code>. Repository classes may also provide a way for additional sets to be
- defined by the repository maintainer. If multiple repositories define a named set, the
- resulting set is all of these repository sets merged using an 'all-of' composite. The
- <code>everything</code> and <code>world</code> sets automatically contain <code>system</code>.</li>
-
- <li>Finally, the <code>everything</code>, <code>system</code>, <code>world</code> and
- <code>security</code> sets always exist, even if no repositories nor the environment defines
- them.</li>
-</ul>
-
-<p><strong>Important:</strong> a set is a named collecion of <em>dependency specifications</em>, not
-a collection of packages.</p>
-
-<h3>User Defined Sets</h3>
-
-<p>The <code>PaludisEnvironment</code> environment class allows user defined package sets via
-text files. These should be named <code><em>setname</em>.conf</code> and placed in
-<code><em>confdir</em>/sets/</code>, where <code><em>confdir</em></code> is the configuration directory
-in which <code>use.conf</code> et al. reside. The format is as follows:</p>
-
-<ul>
- <li>Comments lines start with a <code>#</code>. These, and blank lines, are ignored.</li>
- <li>Lines consist of a symbol, followed by whitespace, followed by a package dependency
- specification.</li>
- <li>The symbol <code>*</code> should be used to mean "include this package dependency specification in
- the set".</li>
- <li>The symbol <code>?</code> should be used to mean "include this package dependency specification in
- the set if and only if the package part of the specification is matched by an installed package". For
- example, the line <code>? &gt;=app-editors/vim-7</code> means requires <code>vim-7</code> if
- and only if <code>app-editors/vim</code> (any version) is already installed.</li>
-</ul>
-
-<p>Most users will only have use for <code>*</code> lines.</p>
-
-<p>In addition, dynamic sets are possible. These should use a <code>.bash</code> extension instead
-of <code>.conf</code>, and when executed should output what would be valid content for a
-<code>.conf</code> set.</p>
-
-<h3>Ebuild Repositories Defined Sets</h3>
-
-<p>Ebuild format repositories can supply their own sets. The <code>system</code> and
-<code>security</code> sets are defined programmatically; other sets are defined by a file
-named <code>sets/<em>setname</em>.conf</code>, which should be in the format described for
-user defined sets above.</p>
-
-<h3>Using Sets</h3>
-
-<p>Sets can currently be used as targets for <code>paludis --query</code>,
-<code>paludis --install</code> and <code>paludis --uninstall</code>.
-They can also be used as the specification column in the
-<code>use.conf</code>, <code>keywords.conf</code>, <code>licenses.conf</code>,
-<code>package_mask.conf</code> and <code>package_unmask.conf</code>.</p>
-
-@FOOTER@
-</body>
-</html>
-