aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorUlrich Müller <ulm@gentoo.org>2005-07-12 17:21:19 +0000
committerUlrich Müller <ulm@gentoo.org>2020-01-09 23:50:51 +0100
commitb5eb706b0d006535cb8e48b7a03177249a630dd0 (patch)
treebd1ad55b9d89bbe5b185210eb838759e4aa4923e
downloaddevmanual-b5eb706b0d006535cb8e48b7a03177249a630dd0.tar.gz
devmanual-b5eb706b0d006535cb8e48b7a03177249a630dd0.tar.bz2
devmanual-b5eb706b0d006535cb8e48b7a03177249a630dd0.zip
reStructuredText source of the devmanual
Taken from ~sekretarz/public_html/devmanual.tar.bz on dev.gentoo.org and removed all generated HTML, PNG, and temporary files. Timestamp of oldest file: 2005-06-04 11:50:45 +0000 Timestamp of newest file: 2005-07-12 17:21:19 +0000 Signed-off-by: Ulrich Müller <ulm@gentoo.org>
-rw-r--r--appendices/common-problems/text.rst133
-rw-r--r--appendices/common-problems/violation-1.ebuild9
-rw-r--r--appendices/contributing/text.rst192
-rw-r--r--appendices/editor-configuration/emacs/text.rst38
-rw-r--r--appendices/editor-configuration/text.rst13
-rw-r--r--appendices/editor-configuration/vim/text.rst8
-rw-r--r--appendices/editor-configuration/xemacs/text.rst28
-rw-r--r--appendices/further-reading/text.rst29
-rw-r--r--appendices/man/Makefile.in23
-rw-r--r--appendices/man/text.rst11
-rw-r--r--appendices/text.rst10
-rw-r--r--archs/alpha/text.rst69
-rw-r--r--archs/amd64/amd64-1.ebuild14
-rw-r--r--archs/amd64/amd64-2.c10
-rw-r--r--archs/amd64/amd64-3.ebuild16
-rw-r--r--archs/amd64/text.rst263
-rw-r--r--archs/mips/text.rst73
-rw-r--r--archs/sparc/text.rst70
-rw-r--r--archs/text.rst17
-rw-r--r--archs/x86/text.rst10
-rw-r--r--changelog/text.rst78
-rw-r--r--ebuild-writing/error-handling/error-handling-1.ebuild3
-rw-r--r--ebuild-writing/error-handling/error-handling-2.ebuild5
-rw-r--r--ebuild-writing/error-handling/error-handling-3.ebuild3
-rw-r--r--ebuild-writing/error-handling/error-handling-4.ebuild3
-rw-r--r--ebuild-writing/error-handling/error-handling-5.ebuild4
-rw-r--r--ebuild-writing/error-handling/text.rst72
-rw-r--r--ebuild-writing/examples/text.rst26
-rw-r--r--ebuild-writing/file-format/header-sample.ebuild5
-rw-r--r--ebuild-writing/file-format/text.rst78
-rw-r--r--ebuild-writing/functions/diagram.svg71
-rw-r--r--ebuild-writing/functions/pkg_config/pkg_config-1.ebuild6
-rw-r--r--ebuild-writing/functions/pkg_config/pkg_config-2.ebuild16
-rw-r--r--ebuild-writing/functions/pkg_config/text.rst30
-rw-r--r--ebuild-writing/functions/pkg_nofetch/pkg_nofetch-1.ebuild12
-rw-r--r--ebuild-writing/functions/pkg_nofetch/pkg_nofetch-2.ebuild8
-rw-r--r--ebuild-writing/functions/pkg_nofetch/text.rst35
-rw-r--r--ebuild-writing/functions/pkg_postinst/pkg_postinst-1.ebuild6
-rw-r--r--ebuild-writing/functions/pkg_postinst/pkg_postinst-2.ebuild13
-rw-r--r--ebuild-writing/functions/pkg_postinst/text.rst35
-rw-r--r--ebuild-writing/functions/pkg_postrm/pkg_postrm-1.ebuild6
-rw-r--r--ebuild-writing/functions/pkg_postrm/pkg_postrm-2.ebuild5
-rw-r--r--ebuild-writing/functions/pkg_postrm/text.rst33
-rw-r--r--ebuild-writing/functions/pkg_preinst/pkg_preinst-1.ebuild6
-rw-r--r--ebuild-writing/functions/pkg_preinst/pkg_preinst-2.ebuild6
-rw-r--r--ebuild-writing/functions/pkg_preinst/text.rst41
-rw-r--r--ebuild-writing/functions/pkg_prerm/pkg_prerm-1.ebuild6
-rw-r--r--ebuild-writing/functions/pkg_prerm/pkg_prerm-2.ebuild6
-rw-r--r--ebuild-writing/functions/pkg_prerm/text.rst33
-rw-r--r--ebuild-writing/functions/pkg_setup/pkg_setup-1.ebuild6
-rw-r--r--ebuild-writing/functions/pkg_setup/pkg_setup-2.ebuild17
-rw-r--r--ebuild-writing/functions/pkg_setup/text.rst26
-rw-r--r--ebuild-writing/functions/src_compile/buildenv/cpu-sample.ebuild4
-rw-r--r--ebuild-writing/functions/src_compile/buildenv/filter-sample.ebuild5
-rw-r--r--ebuild-writing/functions/src_compile/buildenv/ldflags-sample.ebuild7
-rw-r--r--ebuild-writing/functions/src_compile/buildenv/replace-sample.ebuild4
-rw-r--r--ebuild-writing/functions/src_compile/buildenv/strip-sample.ebuild4
-rw-r--r--ebuild-writing/functions/src_compile/buildenv/text.rst78
-rw-r--r--ebuild-writing/functions/src_compile/configure/text.rst30
-rw-r--r--ebuild-writing/functions/src_compile/configure/use-sample.ebuild21
-rw-r--r--ebuild-writing/functions/src_compile/configure/use2-sample.ebuild16
-rw-r--r--ebuild-writing/functions/src_compile/default-sample.ebuild10
-rw-r--r--ebuild-writing/functions/src_compile/distutils/distutils-1.ebuild5
-rw-r--r--ebuild-writing/functions/src_compile/distutils/distutils-2.ebuild17
-rw-r--r--ebuild-writing/functions/src_compile/distutils/distutils-3.ebuild5
-rw-r--r--ebuild-writing/functions/src_compile/distutils/text.rst42
-rw-r--r--ebuild-writing/functions/src_compile/make/getcc-sample.ebuild14
-rw-r--r--ebuild-writing/functions/src_compile/make/text.rst40
-rw-r--r--ebuild-writing/functions/src_compile/nobuildsystem/nobuildsystem-1.ebuild6
-rw-r--r--ebuild-writing/functions/src_compile/nobuildsystem/nobuildsystem-2.ebuild11
-rw-r--r--ebuild-writing/functions/src_compile/nobuildsystem/text.rst19
-rw-r--r--ebuild-writing/functions/src_compile/sample-sample.ebuild13
-rw-r--r--ebuild-writing/functions/src_compile/text.rst36
-rw-r--r--ebuild-writing/functions/src_install/src_install-1.ebuild7
-rw-r--r--ebuild-writing/functions/src_install/src_install-2.ebuild6
-rw-r--r--ebuild-writing/functions/src_install/src_install-3.ebuild3
-rw-r--r--ebuild-writing/functions/src_install/src_install-4.ebuild3
-rw-r--r--ebuild-writing/functions/src_install/src_install-5.ebuild4
-rw-r--r--ebuild-writing/functions/src_install/src_install-6.ebuild50
-rw-r--r--ebuild-writing/functions/src_install/text.rst72
-rw-r--r--ebuild-writing/functions/src_test/default-sample.ebuild22
-rw-r--r--ebuild-writing/functions/src_test/sample-sample.ebuild12
-rw-r--r--ebuild-writing/functions/src_test/text.rst64
-rw-r--r--ebuild-writing/functions/src_test/true-sample.ebuild6
-rw-r--r--ebuild-writing/functions/src_unpack/autopackage/text.rst27
-rw-r--r--ebuild-writing/functions/src_unpack/cvs/cvs-1.ebuild19
-rw-r--r--ebuild-writing/functions/src_unpack/cvs/cvs-2.ebuild14
-rw-r--r--ebuild-writing/functions/src_unpack/cvs/text.rst76
-rw-r--r--ebuild-writing/functions/src_unpack/deb/text.rst16
-rw-r--r--ebuild-writing/functions/src_unpack/epatch/epatch-1.ebuild8
-rw-r--r--ebuild-writing/functions/src_unpack/epatch/epatch-2.ebuild8
-rw-r--r--ebuild-writing/functions/src_unpack/epatch/epatch-3.ebuild8
-rw-r--r--ebuild-writing/functions/src_unpack/epatch/text.rst69
-rw-r--r--ebuild-writing/functions/src_unpack/other-archive-formats/text.rst28
-rw-r--r--ebuild-writing/functions/src_unpack/rpm/rpm-1.ebuild3
-rw-r--r--ebuild-writing/functions/src_unpack/rpm/rpm-2.ebuild8
-rw-r--r--ebuild-writing/functions/src_unpack/rpm/rpm-3.ebuild39
-rw-r--r--ebuild-writing/functions/src_unpack/rpm/text.rst50
-rw-r--r--ebuild-writing/functions/src_unpack/src_unpack-1.ebuild7
-rw-r--r--ebuild-writing/functions/src_unpack/src_unpack-2.ebuild11
-rw-r--r--ebuild-writing/functions/src_unpack/svn/svn-1.ebuild6
-rw-r--r--ebuild-writing/functions/src_unpack/svn/text.rst59
-rw-r--r--ebuild-writing/functions/src_unpack/text.rst47
-rw-r--r--ebuild-writing/functions/src_unpack/tla/text.rst8
-rw-r--r--ebuild-writing/functions/text.rst22
-rw-r--r--ebuild-writing/messages/messages-1.ebuild7
-rw-r--r--ebuild-writing/messages/messages-2.ebuild6
-rw-r--r--ebuild-writing/messages/messages-3.ebuild8
-rw-r--r--ebuild-writing/messages/text.rst78
-rw-r--r--ebuild-writing/misc-files/changelog/changelog10
-rw-r--r--ebuild-writing/misc-files/changelog/text.rst23
-rw-r--r--ebuild-writing/misc-files/metadata/catmetadata.xml15
-rw-r--r--ebuild-writing/misc-files/metadata/pkgmetadata.xml16
-rw-r--r--ebuild-writing/misc-files/metadata/text.rst47
-rw-r--r--ebuild-writing/misc-files/patches/sample-patch.patch17
-rw-r--r--ebuild-writing/misc-files/patches/text.rst54
-rw-r--r--ebuild-writing/misc-files/text.rst9
-rw-r--r--ebuild-writing/text.rst11
-rw-r--r--ebuild-writing/use-conditional-code/text.rst28
-rw-r--r--ebuild-writing/use-conditional-code/use-sample.ebuild21
-rw-r--r--ebuild-writing/users-and-groups/text.rst51
-rw-r--r--ebuild-writing/using-eclasses/devtodo.ebuild49
-rw-r--r--ebuild-writing/using-eclasses/text.rst33
-rw-r--r--ebuild-writing/variables/text.rst187
-rw-r--r--ebuild-writing/variables/variables-1.ebuild7
-rw-r--r--ebuild-writing/variables/variables-2.ebuild10
-rw-r--r--ebuild-writing/variables/variables-3.ebuild4
-rw-r--r--eclass-reference/bash-completion.eclass/text.rst25
-rw-r--r--eclass-reference/eutils.eclass/text.rst46
-rw-r--r--eclass-reference/fdo-mime.eclass/text.rst16
-rw-r--r--eclass-reference/flag-o-matic.eclass/text.rst40
-rw-r--r--eclass-reference/rpm.eclass/text.rst31
-rw-r--r--eclass-reference/subversion.eclass/text.rst51
-rw-r--r--eclass-reference/text.rst10
-rw-r--r--eclass-writing/eclass-writing-1.ebuild26
-rw-r--r--eclass-writing/eclass-writing-2.ebuild9
-rw-r--r--eclass-writing/eclass-writing-3.ebuild9
-rw-r--r--eclass-writing/eclass-writing-4.ebuild28
-rw-r--r--eclass-writing/text.rst125
-rw-r--r--function-reference/build-functions/text.rst18
-rw-r--r--function-reference/install-functions/text.rst70
-rw-r--r--function-reference/message-functions/text.rst34
-rw-r--r--function-reference/query-functions/text.rst31
-rw-r--r--function-reference/sandbox-functions/text.rst31
-rw-r--r--function-reference/text.rst9
-rw-r--r--general-concepts/autotools/aclocal-1.ebuild6
-rw-r--r--general-concepts/autotools/aclocal-1.txt6
-rw-r--r--general-concepts/autotools/aclocal-2.ebuild5
-rw-r--r--general-concepts/autotools/aclocal-2.txt5
-rw-r--r--general-concepts/autotools/autoconf-1.txt9
-rw-r--r--general-concepts/autotools/autoconf-2.txt7
-rw-r--r--general-concepts/autotools/autoconf-3.txt7
-rw-r--r--general-concepts/autotools/autoconf-4.txt5
-rw-r--r--general-concepts/autotools/autoconf-5.txt9
-rw-r--r--general-concepts/autotools/autoconf-6.txt4
-rw-r--r--general-concepts/autotools/autoconf-7.txt4
-rw-r--r--general-concepts/autotools/autoconf-8.txt11
-rw-r--r--general-concepts/autotools/autoconf-9.txt8
-rw-r--r--general-concepts/autotools/automake-1.txt4
-rw-r--r--general-concepts/autotools/automake-2.txt8
-rw-r--r--general-concepts/autotools/diagram.svg102
-rw-r--r--general-concepts/autotools/patching-1.ebuild19
-rw-r--r--general-concepts/autotools/quoting-1.txt7
-rw-r--r--general-concepts/autotools/text.rst355
-rw-r--r--general-concepts/config-protect/text.rst20
-rw-r--r--general-concepts/cvs-to-rsync/diagram.svg142
-rw-r--r--general-concepts/cvs-to-rsync/text.rst23
-rw-r--r--general-concepts/dependencies/basic-depend-sample.ebuild5
-rw-r--r--general-concepts/dependencies/basic-depend-versions-sample.ebuild3
-rw-r--r--general-concepts/dependencies/block-sample.ebuild3
-rw-r--r--general-concepts/dependencies/block-version-sample.ebuild3
-rw-r--r--general-concepts/dependencies/ranged-depend-sample.ebuild4
-rw-r--r--general-concepts/dependencies/text.rst197
-rw-r--r--general-concepts/dependencies/use-depend-either-sample.ebuild3
-rw-r--r--general-concepts/dependencies/use-depend-either-use-sample.ebuild3
-rw-r--r--general-concepts/dependencies/use-depend-inv-sample.ebuild3
-rw-r--r--general-concepts/dependencies/use-depend-legacy-sample.ebuild3
-rw-r--r--general-concepts/dependencies/use-depend-nest-sample.ebuild6
-rw-r--r--general-concepts/dependencies/use-depend-nonlegacy-sample.ebuild4
-rw-r--r--general-concepts/dependencies/use-depend-sample.ebuild5
-rw-r--r--general-concepts/digest-and-manifest/text.rst24
-rw-r--r--general-concepts/distributed-building/text.rst6
-rw-r--r--general-concepts/ebuild-revisions/text.rst23
-rw-r--r--general-concepts/emerge-and-ebuild/diagram.svg55
-rw-r--r--general-concepts/emerge-and-ebuild/text.rst16
-rw-r--r--general-concepts/features/text.rst40
-rw-r--r--general-concepts/filesystem/text.rst55
-rw-r--r--general-concepts/herds-and-projects/text.rst20
-rw-r--r--general-concepts/install-destinations/text.rst20
-rw-r--r--general-concepts/licenses/text.rst20
-rw-r--r--general-concepts/linguas/text.rst11
-rw-r--r--general-concepts/mirrors/diagram.svg521
-rw-r--r--general-concepts/mirrors/text.rst59
-rw-r--r--general-concepts/overlay/text.rst35
-rw-r--r--general-concepts/pic/text.rst9
-rw-r--r--general-concepts/portage-cache/bad-cache-dep-sample.ebuild8
-rw-r--r--general-concepts/portage-cache/conditional-inherit.ebuild5
-rw-r--r--general-concepts/portage-cache/good-cache-dep-sample.ebuild17
-rw-r--r--general-concepts/portage-cache/text.rst33
-rw-r--r--general-concepts/privileges/text.rst9
-rw-r--r--general-concepts/sandbox/text.rst20
-rw-r--r--general-concepts/slotting/text.rst34
-rw-r--r--general-concepts/text.rst9
-rw-r--r--general-concepts/tree/text.rst121
-rw-r--r--general-concepts/use-flags/conflicting-flags.ebuild20
-rw-r--r--general-concepts/use-flags/noblah-1.ebuild3
-rw-r--r--general-concepts/use-flags/noblah-2.ebuild3
-rw-r--r--general-concepts/use-flags/noblah-3.ebuild3
-rw-r--r--general-concepts/use-flags/noblah-4.ebuild3
-rw-r--r--general-concepts/use-flags/text.rst130
-rw-r--r--general-concepts/user-environment/filtering-1.ebuild8
-rw-r--r--general-concepts/user-environment/text.rst53
-rw-r--r--hosted-projects/text.rst86
-rw-r--r--index/text.rst7
-rw-r--r--keywording/keywording-1.ebuild3
-rw-r--r--keywording/keywording-2.ebuild3
-rw-r--r--keywording/text.rst172
-rw-r--r--profiles/categories/text.rst13
-rw-r--r--profiles/info_files/text.rst9
-rw-r--r--profiles/make.defaults/text.rst13
-rw-r--r--profiles/package.mask/text.rst11
-rw-r--r--profiles/packages/text.rst9
-rw-r--r--profiles/profiles.desc/text.rst8
-rw-r--r--profiles/text.rst10
-rw-r--r--profiles/updates/text.rst7
-rw-r--r--profiles/use.desc/text.rst18
-rw-r--r--profiles/use.mask/text.rst27
-rw-r--r--profiles/virtuals/text.rst10
-rw-r--r--quickstart/ex1.ebuild26
-rw-r--r--quickstart/ex2.ebuild29
-rw-r--r--quickstart/ex3.ebuild27
-rw-r--r--quickstart/ex4.ebuild70
-rw-r--r--quickstart/ex5.ebuild40
-rw-r--r--quickstart/text.rst159
-rw-r--r--styles/devmanual.css235
-rw-r--r--tasks-reference/completion/completion-1.ebuild3
-rw-r--r--tasks-reference/completion/completion-2.ebuild19
-rw-r--r--tasks-reference/completion/completion-3.ebuild7
-rw-r--r--tasks-reference/completion/completion-4.ebuild39
-rw-r--r--tasks-reference/completion/text.rst154
-rw-r--r--tasks-reference/environment/text.rst18
-rw-r--r--tasks-reference/init-scripts/text.rst15
-rw-r--r--tasks-reference/pam/text.rst170
-rw-r--r--tasks-reference/perl-modules/text.rst11
-rw-r--r--tasks-reference/text.rst10
-rw-r--r--text.rst69
-rw-r--r--todolist/text.rst10
-rw-r--r--tools-reference/bash/bash-1.ebuild5
-rw-r--r--tools-reference/bash/bash-10.ebuild5
-rw-r--r--tools-reference/bash/bash-11.ebuild5
-rw-r--r--tools-reference/bash/bash-12.ebuild3
-rw-r--r--tools-reference/bash/bash-2.ebuild11
-rw-r--r--tools-reference/bash/bash-3.ebuild8
-rw-r--r--tools-reference/bash/bash-4.ebuild8
-rw-r--r--tools-reference/bash/bash-5.ebuild14
-rw-r--r--tools-reference/bash/bash-6.ebuild6
-rw-r--r--tools-reference/bash/bash-7.ebuild5
-rw-r--r--tools-reference/bash/bash-8.ebuild6
-rw-r--r--tools-reference/bash/bash-9.ebuild5
-rw-r--r--tools-reference/bash/text.rst372
-rw-r--r--tools-reference/cat/code-sample-1.ebuild10
-rw-r--r--tools-reference/cat/text.rst48
-rw-r--r--tools-reference/cut/cut-1.ebuild3
-rw-r--r--tools-reference/cut/cut-2.ebuild3
-rw-r--r--tools-reference/cut/text.rst37
-rw-r--r--tools-reference/diff-and-patch/text.rst31
-rw-r--r--tools-reference/echangelog/text.rst15
-rw-r--r--tools-reference/echo/text.rst60
-rw-r--r--tools-reference/ekeyword/text.rst14
-rw-r--r--tools-reference/epkgmove/text.rst8
-rw-r--r--tools-reference/false-and-true/text.rst8
-rw-r--r--tools-reference/find/find-1.ebuild5
-rw-r--r--tools-reference/find/find-2.ebuild5
-rw-r--r--tools-reference/find/find-3.ebuild3
-rw-r--r--tools-reference/find/text.rst55
-rw-r--r--tools-reference/gentoo-syntax/text.rst13
-rw-r--r--tools-reference/glep31check/text.rst12
-rw-r--r--tools-reference/grep/text.rst36
-rw-r--r--tools-reference/head-and-tail/head-and-tail-1.ebuild25
-rw-r--r--tools-reference/head-and-tail/head-and-tail-2.ebuild4
-rw-r--r--tools-reference/head-and-tail/text.rst40
-rw-r--r--tools-reference/sed/sed-1.ebuild6
-rw-r--r--tools-reference/sed/sed-10.ebuild4
-rw-r--r--tools-reference/sed/sed-11.ebuild12
-rw-r--r--tools-reference/sed/sed-2.ebuild13
-rw-r--r--tools-reference/sed/sed-3.ebuild11
-rw-r--r--tools-reference/sed/sed-4.ebuild8
-rw-r--r--tools-reference/sed/sed-5.ebuild6
-rw-r--r--tools-reference/sed/sed-6.ebuild5
-rw-r--r--tools-reference/sed/sed-7.ebuild4
-rw-r--r--tools-reference/sed/sed-8.ebuild4
-rw-r--r--tools-reference/sed/sed-9.ebuild5
-rw-r--r--tools-reference/sed/text.rst338
-rw-r--r--tools-reference/sort/text.rst15
-rw-r--r--tools-reference/text.rst11
-rw-r--r--tools-reference/tr/text.rst30
-rw-r--r--tools-reference/uniq/text.rst12
297 files changed, 9495 insertions, 0 deletions
diff --git a/appendices/common-problems/text.rst b/appendices/common-problems/text.rst
new file mode 100644
index 0000000..0eeabf3
--- /dev/null
+++ b/appendices/common-problems/text.rst
@@ -0,0 +1,133 @@
+Common Problems
+===============
+
+This page provides suggestions on how to handle various commonly seen errors
+and QA notices.
+
+Handling QA Notices
+-------------------
+
+The ``ebuild.sh`` part of portage includes a number of checks for common
+problems. These can result in a 'QA Notice' message being displayed. You must
+not rely upon portage always generating these messages -- they are not a
+substitute for proper testing and QA by developers.
+
+.. Note:: Some eclasses output messages in the same format. These are not
+ covered here.
+
+QA Notice -- USE Flag foo not in IUSE
+'''''''''''''''''''''''''''''''''''''
+
+With the exception of 'special' flags (the arch flags and ``USE_EXPAND``
+variables), all ``USE`` flags used by a package must be included in ``IUSE``.
+See `IUSE`_ and `USE Flags`_.
+
+QA Notice -- foo in global scope
+''''''''''''''''''''''''''''''''
+
+This message occurs when various tools are inappropriately used in global scope.
+Remember that no external code should be run globally. Depending upon the tool
+in use, there are various alternatives:
+
+``sed``, ``awk``, ``grep``, ``egrep``, ``cut`` etc
+ Usually when any of the above are used in global scope, it is to manipulate
+ a version or program name string. These should be avoided in favour of
+ pure ``bash`` constructs. The ``versionator`` eclass is often of use here.
+ See `Version Formatting Issues`_, `versionator.eclass-5`_ and `Bash Variable
+ Manipulation`_.
+
+``has_version``, ``best_version``, ``portageq``
+ Calls to any of these globally indicates a serious problem. You must **not**
+ have metadata varying based upon system-dependent information -- see `The
+ Portage Cache`_. You should rewrite your ebuilds to correctly use
+ dependencies.
+
+``python``, ``perl`` etc
+ Ebuilds are ``bash`` scripts. Offloading anything you don't know how to do
+ in ``bash`` onto another language is not acceptable -- if nothing else,
+ because not all users will always have a full system when ebuilds are
+ sourced.
+
+QA Notice -- foo is setXid, dynamically linked and using lazy bindings
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Dynamically linked setXid applications should not use lazy bindings when linking
+for security reasons. If this message is shown, you have a couple of options:
+
+* Modify the package's Makefile (or equivalent) to use ``-Wl,-z,now`` when
+ linking. This solution is preferred.
+* Use ``append-ldflags`` (see `Adding Additional Flags`_) to add ``-Wl,-z,now``.
+ This will affect *all* binaries installed, not just the setXid ones.
+
+QA Notice -- ECLASS foo inherited illegally
+'''''''''''''''''''''''''''''''''''''''''''
+
+All eclass inherits must be unconditional, or based purely upon static
+machine-independent criteria (``PN`` and ``PV`` are most common here). See `The
+Portage Cache`_.
+
+You may see this warning in situations where there is not actually any illegal
+inheritance occurring. Most commonly:
+
+* When unmerging a package which was installed using an old portage version that
+ did not record inheritance.
+* When working with eclasses in an overlay with a stale cache. See `Overlay and
+ Eclasses`_.
+* When working with a stale portage cache.
+
+You should manually check against the rules described in `The Portage Cache`_ if
+you see this notice locally. If you see this notice when working with a pure
+``emerge sync`` over ``rsync`` setup, it is probably a genuine issue.
+
+.. Todo:: from vapier:
+ TEXTREL's ... binary files which contain text relocations ... see
+ 'prepstrip' for a full description unsafe files ... basically files that
+ are setid and writable by Other users i've added the following QA checks to
+ portage HEAD (no idea when they'll hit a release): Insecure RUNPATHs ...
+ binary files which have RUNPATH's encoded in them which are in +t
+ directories Executable stacks ... binary files whose stack is marked with
+ +x ... will bomb on amd64 for example
+
+Handling ``repoman`` Messages
+-----------------------------
+
+.. Todo:: write me
+
+Handling Access Violations
+--------------------------
+
+Portage uses a sandbox for certain phases of the build process. This prevents a
+package from accidentally writing outside 'safe' locations. See `Sandbox`_ for
+details.
+
+If a package violates the sandbox, an error such as the following will be given
+(assuming that the sandbox is enabled and working on the test system, which
+should always be the case for developer boxes): ::
+
+ --------------------------- ACCESS VIOLATION SUMMARY ---------------------------
+ LOG FILE = "/tmp/sandbox-app-misc_-_breakme-1-31742.log"
+
+ open_wr: /big-fat-red-error
+ --------------------------------------------------------------------------------
+
+The ``open_wr`` means the package tried to open for write a file that is not
+inside write-permitted areas. In this case, the file in question is
+``/big-fat-red-error``.
+
+Other error messages exist for read-restricted areas -- these are rarely used in
+ebuilds.
+
+Access violations most commonly occur during the install phase. See
+``src_install`` and `Install Destinations`_ for discussion.
+
+Sometimes problems can also occur with packages attempting to write to
+``${HOME}``. To get around this, it is usually sufficient to trick the build
+system into using a safer location. For example, the ``fluxbox`` menu generator
+tries to work in ``${HOME}/.fluxbox`` -- to get around this, the following is
+used:
+
+.. CODESAMPLE violation-1.ebuild
+
+In this situation, providing a fake home directory is all that is needed.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/appendices/common-problems/violation-1.ebuild b/appendices/common-problems/violation-1.ebuild
new file mode 100644
index 0000000..20f05f9
--- /dev/null
+++ b/appendices/common-problems/violation-1.ebuild
@@ -0,0 +1,9 @@
+# Header.
+
+ebegin "Creating a menu file (may take a while)"
+mkdir -p "${T}/home/.fluxbox" || die "mkdir home failed"
+MENUFILENAME="${S}/data/menu" MENUTITLE="Fluxbox ${PV}" \
+ CHECKINIT="no. go away." HOME="${T}/home" \
+ ${S}/util/fluxbox-generate_menu -is -ds \
+ || die "menu generation failed"
+eend $?
diff --git a/appendices/contributing/text.rst b/appendices/contributing/text.rst
new file mode 100644
index 0000000..677d591
--- /dev/null
+++ b/appendices/contributing/text.rst
@@ -0,0 +1,192 @@
+Contributing to This Document
+=============================
+
+Contributions for this document are highly welcomed. Whether you've found a typo
+or have written an entire new section, the best way to get in touch is to `send
+an email to plasmaroo <mailto:plasmaroo@gentoo.org>`_.
+
+The editor reserves the right to modify submissions as he sees fit. Any
+substantial changes will of course be discussed with the submitter first --
+unless explicitly requested, minor typo corrections and formatting fixes will
+not be discussed.
+
+This document is licenced under the `Creative Commons Attribution-ShareAlike
+2.0 Licence <http://creativecommons.org/licenses/by-sa/2.0/>`_. If this is a
+problem, don't submit anything.
+
+If you're looking for something to do, the automatically generated `Todo List`_
+might help.
+
+This document is produced using some scary Makefile hacks from `Restructured
+Text (RST) <http://docutils.sourceforge.net/rst.html>`_ files. To view the
+source for a page, append ``text.rst`` to the URL or check the link in the page
+footer. If you'd rather just work with plain text, that's fine too -- the
+formatting can be done by someone else.
+
+Quick Introduction to RST
+-------------------------
+
+Take a look at `the source for this page <text.rst>`_ for the basic structure of
+an RST document.
+
+RST Headings
+''''''''''''
+
+At the top of the page is a heading, which is underlined by a line of equals
+signs. Within the page, normal headings use hyphens and subheadings use single
+quotes.
+
+.. Important:: These heading conventions *must* be followed. Although standard
+ RST is more lenient regarding underline characters, the build system for this
+ document makes some assumptions.
+
+If subsubheadings are needed, use the caret character. Nothing actually uses
+these yet -- it's probably better to restructure or split up your page if you
+find yourself needing this.
+
+.. Warning:: Heading names must be unique *throughout the entire document*. Try
+ to pick long descriptive titles -- for example, 'Further Notes on Foo' rather
+ than 'Further Notes'.
+
+Currently, the colon character cannot be used in headings. If you really need to
+use a colon, prod ciaranm and ask him to fix the build scripts.
+
+Inline Markup
+'''''''''''''
+
+To make some *emphasised text*, surround it with ``*asterisks*``. To make some
+**strongly emphasised text**, use ``**double asterisks**``. When typing ``code`` or
+``filenames``, surround them with ````double backticks````. These characters can
+be escaped using backslashes, like ``\`\`this\`\```.
+
+To link to another section of the document, type the section name inside
+backticks and append an underscore, ```like this`_``. You can link to any
+section in *any* page of the document in this manner. There are also link
+targets for GLEPs defined automatically for you, so ```GLEP 23`_`` will produce
+a link to `GLEP 23`_.
+
+To do an external hyperlink, use ```this format <http://example.com/>`_``.
+
+Lists
+'''''
+
+To create a bullet list, use something like the following: ::
+
+ + First
+ + Second
+
+ * Subitem for second
+ * Another subitem for second
+
+ + Third
+
+.. Note:: You **must** leave a blank line before and after a list (and each
+ sublevel in the list). A blank line between items is not necessary.
+
+You can use ``+``, ``*``, ``.`` and ``-`` for bullet characters as you prefer,
+so long as you consistently use the same marker for the same level.
+
+To create a numbered list: ::
+
+ 1. First
+ 2. Second
+ 3. Third
+
+Again, blank lines before and after the list are required.
+
+To create a key / value list: ::
+
+ First Key
+ This text is the definition of first key.
+
+ Second Key
+ And this text is the definition of second key.
+
+Code Blocks
+'''''''''''
+
+Large code blocks are started with a double colon. Any subsequent lines which
+are indented are taken to be part of the code block. To end a code block, use an
+unindented line. For example: ::
+
+ Here is an example code block: ::
+
+ This is code.
+ This is still code.
+ There's no need to escape *dodgy markup* here.
+
+ This is still code.
+
+ This is no longer code.
+
+Tables
+''''''
+
+Tables in RST are tricky. Check `the main RST documentation
+<http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#tables>`_ if
+you're feeling up to it.
+
+.. Todo:: Do we want to include some examples here?
+
+Special Paragraphs
+''''''''''''''''''
+
+To create a note, use the ``note`` directive: ::
+
+ .. Note:: This is a note. Note the two dots, the space, the directive
+ type (in this case, Note), the lack of space and then the double
+ colons. Also see how continuations onto new lines are indented.
+
+There are also ``.. Warning::`` and ``.. Important::`` directives available.
+
+.. Note:: The RST specification includes various others, but we don't have
+ stylesheet rules defined for them. If there's anything you need from `the
+ full list
+ <http://docutils.sourceforge.net/docs/ref/rst/directives.html#specific-admonitions>`_,
+ ask to have stylesheet support added.
+
+The ``.. Todo::`` directive is a local hack that needs a patched docutils to
+work. Feel free to use it, but be warned that it may not render correctly on
+your system.
+
+Build System Hacks
+''''''''''''''''''
+
+There're a few sometimes-useful substitutions which are performed by the build
+system. For example: ::
+
+ .. CODESAMPLE filename.blah
+
+can be used to include a source file with generated syntax highlighting. It's
+best to leave these to the editor -- they need some ``Makefile`` rules to back
+them up.
+
+To include a list of 'children' for a table of contents, use: ::
+
+ .. CHILDLIST
+
+Checking RST Text
+-----------------
+
+To check RST source, use: ::
+
+ rst2html.py --report=2 --halt=2 < text.rst
+
+You should ignore any warnings about missing link targets for GLEPs or link
+references to headings in other documents -- these are handled automatically by
+the build system. Similarly, ignore the lack of handling for ``.. Todo::`` and
+the `build system hacks`_.
+
+Style Guidelines
+----------------
+
++ This document is in British English. Submissions in other kinds of English are
+ welcome, but they may have their spelling corrected.
++ Third person should be used rather than first.
++ This is not a formal document. The writing style is intended to be
+ professional but readable.
++ When using in-sentence hyphens as punctuation -- like this -- use a space,
+ followed by two hyphens, followed by a space: ``--``. The build
+ system will automatically turn this into a proper Unicode long dash.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/appendices/editor-configuration/emacs/text.rst b/appendices/editor-configuration/emacs/text.rst
new file mode 100644
index 0000000..450e957
--- /dev/null
+++ b/appendices/editor-configuration/emacs/text.rst
@@ -0,0 +1,38 @@
+Configuring ``emacs`` for UTF-8
+===============================
+
+Emacs 21 has built-in Unicode support, and (fortunately) it supports
+UTF-8 far better than UTF-16 and other variants. Some extensions to this
+functionality are available in the package ``app-emacs/mule-ucs``, although
+this is not necessary (and I would not recommend it unless absolutely
+necessary, as the potential for unexpected bugs or quirky behaviour is
+increased).
+
+In versions of Emacs below 21.3, and a non-UTF-8 locale is used when
+opening a UTF-8 file, auto-detection of the character set is effectively
+disabled and characters will be garbled. The UTF-8 character set can be
+preferred with ``M-x prefer-coding-system`` and entering ``utf-8`` when
+prompted. Otherwise, it is necessary to tell Emacs that a UTF-8 file is
+being opened by prefixing the ``C-x C-f`` or ``C-x C-v`` command with
+``C-x C-m c utf-8 RET``. As a diagnostic measure, the coding system currently
+in use can be determined with ``C-h C <RET>``.
+
+Newer Emacs versions will autodetect the coding system for given text.
+
+If it is desired to prefer UTF-8 to the regular character set,
+the following can be used inside of the Emacs startup file:
+
+::
+
+ (prefer-coding-system 'utf-8)
+
+For specifying coding system to use on a per-file basis, the
+modify-coding-system function can be used.
+
+Further reading:
+
+* http://www.gnu.org/software/emacs/manual/emacs.html#Recognize%20Coding
+* http://www.gnu.org/software/emacs/manual/emacs.html#Specify%20Coding
+* http://www.emacswiki.org/cgi-bin/wiki/UnicodeEncoding
+* http://www.emacswiki.org/cgi-bin/wiki/ChangingEncodings
+
diff --git a/appendices/editor-configuration/text.rst b/appendices/editor-configuration/text.rst
new file mode 100644
index 0000000..dd43c2d
--- /dev/null
+++ b/appendices/editor-configuration/text.rst
@@ -0,0 +1,13 @@
+Editor Configuration
+====================
+
+This section provides hints as to how to configue your text editor for working with ebuilds.
+
+.. Todo:: from vapier: add a section for nano ... users just have to copy
+ /etc/nanorc to ~/.nanorc and uncomment the sections for ebuilds
+
+.. CHILDLIST
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
+
diff --git a/appendices/editor-configuration/vim/text.rst b/appendices/editor-configuration/vim/text.rst
new file mode 100644
index 0000000..e5a2c62
--- /dev/null
+++ b/appendices/editor-configuration/vim/text.rst
@@ -0,0 +1,8 @@
+Configuring ``vim`` and ``gvim``
+================================
+
+For full whitespace, character set, syntax and indent settings for ``vim`` and ``gvim``, emerge the ``app-vim/gentoo-syntax`` package.
+
+When fixing ebuilds with broken whitespace, the ``:retab!`` command may be of interest. The ! is required to replace spaces with tabs.
+
+
diff --git a/appendices/editor-configuration/xemacs/text.rst b/appendices/editor-configuration/xemacs/text.rst
new file mode 100644
index 0000000..819a144
--- /dev/null
+++ b/appendices/editor-configuration/xemacs/text.rst
@@ -0,0 +1,28 @@
+Configuring ``xemacs`` for UTF-8
+================================
+
+First, you need to have built ``xemacs`` itself with ``USE=mule``. Then, the
+``app-xemacs/mule-ucs`` package is needed. To autoload Unicode support,
+you can add the following to your ``~/.xemacs/init.el``:
+
+::
+
+ (require 'un-define)
+
+If automatic character set detection on files is not working properly,
+here are three commands that can help.
+
+* ``set-buffer-file-coding-system (C-x RET f)`` changes the coding
+ system for the current file.
+* ``set-default-buffer-file-coding-system (C-x RET F)`` sets the default for
+ unsaved buffers and ASCII-looking files that have no obvious character
+ set markers for autodetection.
+* ``universal-coding-system-argument (C-x RET c)``
+ lets you set the coding system for the next command, so issuing
+ this from a dired window immediately before opening a problematic file
+ is a tactic that can be of use when autodetection gets things
+ pathologically wrong.
+
+The current coding system will be displayed near the left edge of the
+status line.
+
diff --git a/appendices/further-reading/text.rst b/appendices/further-reading/text.rst
new file mode 100644
index 0000000..2a3d424
--- /dev/null
+++ b/appendices/further-reading/text.rst
@@ -0,0 +1,29 @@
+Further Reading
+===============
+
+This section lists some recommended further reading. These are real
+recommendations, not padding designed to make this document look important.
+
+Books
+-----
+
+Mastering Regular Expressions
+ "Mastering Regular Expressions" by Jeffrey E. F. Friedl (O'Reilly,
+ ISBN 0-596-00289-0) is **the** book on regular expressions. Very readable and
+ devoid of the usual mathematical jargon that tends to fill up these kinds of
+ books. `Publisher's page <http://www.oreilly.com/catalog/regex2/>`__
+
+Articles
+--------
+
+Making Packager-Friendly Software
+ `Making Packager-Friendly Software
+ <http://www.onlamp.com/pub/a/onlamp/2005/03/31/packaging.html>`__ by Julio M.
+ Merino Vidal describes various things that can be done by upstream software
+ providers to make life easy for the distribution people (that means you).
+
+How to Report Bugs Effectively
+ `How to Report Bugs Effectively <http://freshmeat.net/articles/view/149>`__ by
+ Simon Tatham is a good overview of effective bug reporting.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/appendices/man/Makefile.in b/appendices/man/Makefile.in
new file mode 100644
index 0000000..3624292
--- /dev/null
+++ b/appendices/man/Makefile.in
@@ -0,0 +1,23 @@
+include make.common
+
+cache.man : cache.own-url
+ grep 'man$$' cache.own-url || ( \
+ TERM=xterm \
+ MANPAGER="tr '\267' '.' | col -b | \
+ vim -f -u /etc/vim/vimrc -U NONE -i NONE \
+ +':so ${TOPDIR}/tools/manpage.vim' +':w! /tmp/$@' \
+ +':qa!' - " \
+ man $$(sed -e 's,.*/\([^/]\+\)-\([^-]\+\)$$,\2,' < cache.own-url ) \
+ $$(sed -e 's,.*/\([^/]\+\)-\([^-]\+\)$$,\1,' < cache.own-url ) && \
+ sed -i -n -e '/^<pre>$$/,/^<\/pre>$$/p' /tmp/$@ && \
+ sed -i -e 's/^/\t/' /tmp/$@ && \
+ mv /tmp/$@ $@)
+
+cache.text : | $(TOPDIR)/skel/man.rst \
+ $(wildcard text.rst) cache.own-url
+ [[ -f text.rst ]] && cp text.rst $@ || \
+ sed -e 's,@TOPIC@,$(shell \
+ sed -e 's,.*/\([^/]\+\)-\([^-]\+\)$$,\1,' < cache.own-url),' \
+ -e 's,@SECTION@,$(shell \
+ sed -e 's,.*/\([^/]\+\)-\([^-]\+\)$$,\2,' < cache.own-url),' \
+ < $(TOPDIR)/skel/man.rst > $@
diff --git a/appendices/man/text.rst b/appendices/man/text.rst
new file mode 100644
index 0000000..fc7f6b2
--- /dev/null
+++ b/appendices/man/text.rst
@@ -0,0 +1,11 @@
+Manual Pages
+============
+
+.. Note:: Some of these manual pages are taken from
+ ``app-portage/portage-manpages``.
+
+.. CHILDLIST
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
+
diff --git a/appendices/text.rst b/appendices/text.rst
new file mode 100644
index 0000000..90edbae
--- /dev/null
+++ b/appendices/text.rst
@@ -0,0 +1,10 @@
+Appendices
+==========
+
+This section incorporates various auxiliary documents which may be useful as a
+reference.
+
+.. CHILDLIST
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/archs/alpha/text.rst b/archs/alpha/text.rst
new file mode 100644
index 0000000..824212c
--- /dev/null
+++ b/archs/alpha/text.rst
@@ -0,0 +1,69 @@
+Arch Specific Notes -- ALPHA
+============================
+
+The ALPHA port uses the ``alpha`` keyword. It focuses upon HP (formerly Compaq
+(formerly DEC)) hardware. This covers from ``ev4`` (known as 21064) through
+``ev7z`` (known as 21364a).
+
+ALPHA Kernel and Userland ABIs
+------------------------------
+
+All ALPHA systems use a pure 64 bit kernel and a pure 64 bit userland.
+
+All ALPHA systems support both little and big endian -- however, Linux only uses
+little endian.
+
+Additional ALPHA Keywording Requirements
+----------------------------------------
+
+It is generally expected that anyone who does keywording for ALPHA should be on
+the ``alpha@`` alias. However the ALPHA Team is happy if maintainers keyword
+their packages when they have access to ALPHA hardware, although the Team would
+like to know about it.
+
+ALPHA Instruction Set and Performance Notes
+-------------------------------------------
+
+There are six basic ALPHA instructions set standards:
+
+* ``ev4`` or ``ev45``. The ``ev4`` was the first ALPHA processor of the Alpha
+ family. It featured one integer pipeline and one floating-point pipeline.
+ The ``ev45`` is a modified ``ev4`` with double both Data and Instruction cache
+ (D-Cache and I-Cache respectively); it also featured a division optimization.
+* ``ev5`` is an evolution of the ``ev45``. The number of pipelines was doubled
+ and the floating-point pipelines run in 9 stages rather than in 10. The
+ ``ev5`` supports 3 cache levels.
+* ``ev56`` added the BWX extension to load/store data in 8 or 16 bit quanta.
+* ``pca56`` added a new set, MVI (Motion Video Instructions), aimed to
+ accelerate video and audio calculations.
+* ``ev6`` supports all extensions supported by the ``pca56`` and a new set, FIX,
+ meant to move data between integer and floating-point registers and for square
+ root.
+* ``ev67`` is an evolution of the ``ev6``, in addition it supports a new set.
+ CIX adds instructions for counting and finding bits.
+
+When no ``-mcpu`` option is passed to ``gcc`` it defaults to the processor on
+which the compiler was built.
+
+The ``-mieee`` flag **should** always be used unless you have a deep knowledge
+of the ALPHA architecture, so the comments on `Not Filtering Variables`_ are
+really important on ALPHA.
+
+Notes on ALPHA and PIC
+----------------------
+
+General `Position Independent Code`_ policy also applies to ALPHA. In fact,
+ALPHA systems complain loudly if you try to link PIC and non-PIC code. Usually
+this results in errors during the compilation aborting emerge.
+
+Contacting the ALPHA Team
+-------------------------
+
+The ALPHA team can be contacted:
+
+* Via Bugzilla bugs assigned to ``alpha@``
+* Via email to the ``alpha@`` email alias
+* Via email to the ``gentoo-alpha`` mailing list
+* Via the ``#gentoo-alpha`` IRC channel on Freenode
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/archs/amd64/amd64-1.ebuild b/archs/amd64/amd64-1.ebuild
new file mode 100644
index 0000000..6008264
--- /dev/null
+++ b/archs/amd64/amd64-1.ebuild
@@ -0,0 +1,14 @@
+# Header.
+
+inherit multilib
+
+src_compile() {
+ econf \
+ --libdir=/usr/$(get_libdir)
+
+ emake || die
+}
+
+src_install() {
+ make DESTDIR=${D} install || die
+}
diff --git a/archs/amd64/amd64-2.c b/archs/amd64/amd64-2.c
new file mode 100644
index 0000000..78a1847
--- /dev/null
+++ b/archs/amd64/amd64-2.c
@@ -0,0 +1,10 @@
+/* Header */
+
+/* Common header file autogenerated by create_ml_includes in multilib.eclass */
+#ifdef __i386__
+#include <asm-i386/types.h>
+#endif /* __i386__ */
+
+#ifdef __x86_64__
+#include <asm-x86_64/types.h>
+#endif /* __x86_64__ */
diff --git a/archs/amd64/amd64-3.ebuild b/archs/amd64/amd64-3.ebuild
new file mode 100644
index 0000000..8ebae9d
--- /dev/null
+++ b/archs/amd64/amd64-3.ebuild
@@ -0,0 +1,16 @@
+# Header.
+
+MULTILIB_ABIS="x86 amd64"
+DEFAULT_ABI="amd64"
+
+CFLAGS_amd64="-m64"
+LDFLAGS_amd64="-m elf_x86_64"
+CHOST_amd64="x86_64-pc-linux-gnu"
+CDEFINE_amd64="__x86_64__"
+LIBDIR_amd64="lib64"
+
+CFLAGS_x86="-m32 -L/emul/linux/x86/lib -L/emul/linux/x86/usr/lib"
+LDFLAGS_x86="-m elf_i386 -L/emul/linux/x86/lib -L/emul/linux/x86/usr/lib"
+CHOST_x86="i686-pc-linux-gnu"
+CDEFINE_x86="__i386__"
+LIBDIR_x86="lib32"
diff --git a/archs/amd64/text.rst b/archs/amd64/text.rst
new file mode 100644
index 0000000..a7768da
--- /dev/null
+++ b/archs/amd64/text.rst
@@ -0,0 +1,263 @@
+Arch Specific Notes -- AMD64/EM64T
+==================================
+
+Position Independent Code Issues
+--------------------------------
+
+Gentoo Policy demands all shared objects to be compiled with ``-fPIC``
+in ``CFLAGS``. Since this is only a rule, you *can* break it on some arches.
+You might never notice it. On AMD64, this is a necessity, if shared objects aren't
+built with support for position independent code, the build process bails out
+with an error message like this: ::
+
+ foo.o: relocation R_X86_64_32 can not be used when making a shared
+ object; recompile with -fPIC
+
+How to fix -fPIC issues
+~~~~~~~~~~~~~~~~~~~~~~~
+
+There are several ways to enforce ``-fPIC`` on shared objects, each with its
+pros and cons.
+
+``sed``'ing the Makefile
+''''''''''''''''''''''''
+
+Sometimes, a simple ``sed`` command is enough to fix it, however, the statements
+normally aren't very readable and may fail when upstream changes the file.
+Please verify that you only change the ``CFLAGS`` for *shared* objects, not for
+the whole package.
+
+Patching ``Makefile.in``/``configure``
+''''''''''''''''''''''''''''''''''''''
+
+This is more readable, and easier to send upstream.
+
+How **not** to fix -fPIC issues
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Do **not** patch the ``Makefile`` itself, since it is usually generated by the
+``configure`` script and may vary heavily, so the patch could fail. Also, this
+doesn't help upstream at all.
+
+Another bad idea is to (ab)use ``append-flags`` function from
+``flag-o-matic.eclass``. Applying ``-fPIC`` on all objects will slow down the
+binaries in a drastic way.
+
+Assembler Optimisation
+----------------------
+
+Modern x86 processors support special instruction sets like ``mmx``, ``sse``,
+``SSE2`` and ``3DNow!``. AMD64 also provides support for them, but in most
+cases, x86 assembler code is incompatible with AMD64 assembler. There are lots
+of packages that provide support through USE flags for these instruction sets.
+Originally, the USE flags were introduced to keep support for older processors
+such as the Pentium I that can't handle such code. Currently, all AMD64s support the
+same combination of extended instruction sets, so there is no reason to make
+use of the mentioned USE flags. That's why these USE flags are hard-masked in
+all AMD64-profiles. This doesn't mean we don't support the extensions
+themselves, instead, we hard-enable them.
+
+The following USE flags are masked on AMD64:
+
+* mmx
+* mmx2
+* sse
+* sse2
+* 3dnow
+* 3dnowext
+
+Multilib on AMD64
+-----------------
+
+The current AMD64 processors are able to natively run 32bit code on a 64bit
+kernel. Therefore, you can run programs compiled for x86 in an amd64 environment.
+However, 32bit applications need to be linked against 32bit libraries. Mixing
+them won't work. For this reason the libraries are sorted, 32bit libraries normally
+go to ``/lib32`` respectively ``/usr/lib32``, the 64bit ones normally to ``/lib64`` or
+``/usr/lib64``. In a perfect world, you wouldn't have to read on. Unfortunately,
+that's not the case, and so it's a bit more complicated.
+
+Multilib-Toolchain
+~~~~~~~~~~~~~~~~~~
+
+GCC
+'''
+
+To generate 32bit code, we need a multilib-capable GCC. On other architectures,
+this functionality is enabled with the USE flag ``multilib``. This is also true
+for amd64 with the *pre*-2005.0 profiles. From 2005.0 on, you have to choose
+whether you want multilib support or not by selecting the profile. Choose
+``2005.0/no-multilib`` if you don't want it, all other profiles have the
+``multilib`` USE flag masked, you're forced to it. With these profiles, GCC will
+produce x86-code whenever you add ``-m32`` to its command line. Adding ``-m64``
+or omitting any bit-width option will default to producing 64bit code.
+
+glibc
+'''''
+
+If you've chosen a multilib profile, glibc will be built twice, once 64bit and
+once 32bit. This is because nearly every application links against glibc.
+To understand how this is done in the ebuild, read `The ABI Variable`_.
+
+The ``emul-linux-x86-*`` packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As you read above, 32bit applications must be linked against 32bit libraries.
+For that, we've put together the most used libraries and stuck them into the
+so-called ``emul-linux-x86`` packages, which are located in the
+``app-emulation`` category.
+
+emul-linux-x86-baselibs
+ Contains very basic libraries like zlib, pam, ncurses.
+
+emul-linux-x86-compat
+ Contains very old libraries for compatibility with binary-only programs.
+
+emul-linux-x86-glibc
+ Only used for compatibility reasons. This package is blocked by all
+ 2005.0 profiles.
+
+emul-linux-x86-gtklibs
+ The name says it -- GTK and its engines belong herein.
+
+emul-linux-x86-nvidia
+ Obsolete, ``media-video/nvidia-glx`` includes the 32bit library.
+
+emul-linux-x86-qtlibs
+ QT goes here.
+
+emul-linux-x86-sdl
+ libsdl and friends are here.
+
+emul-linux-soundlibs
+ alsa, libogg, just everything that is needed to get sound is located here.
+
+emul-linux-x86-xlibs
+ Contains the basic X libraries.
+
+These packages only provide pre-compiled libraries. Currently, the
+archives are assembled manually, which is the main reason to keep the packages
+as tidy as possible. Do not include libraries that aren't commonly used.
+
+.. Note:: The emul-packages might conflict with their native images, but only in
+ uncritical locations like ``/usr/share`` which are arch-independent anyway.
+
+``Libdir`` Links
+~~~~~~~~~~~~~~~~
+
+Currently, we provide several profiles, each with its own combination of ``libdir``
+configurations.
+
+========================== ========== ======= ========
+Profile lib32 lib lib64
+========================== ========== ======= ========
+2004.3 *l->emul* d64 *l->lib*
+2004.3/lib64 *l->emul* *l->64* d64
+2005.0 d32 *l->64* d64
+2005.0/no-multilib d32 *l->64* d64
+2005.0/no-symlink d32 d d64
+2005.0/no-symlink/no-lib32 inexistant d32 d64
+========================== ========== ======= ========
+
+d: Directory containing mixed-bit objects
+dXX: Directory containing XXbit objects
+l->foo: Link to foo
+
+To always get the right path, you should use the function ``$(get_libdir)`` from
+``multilib.eclass``. It will always return the correct directory, on all arches.
+And of course it also takes care of the ``ABI`` variable.
+
+The ``multilib-strict`` Feature
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Many Makefiles assume that their libraries should go to ``/usr/lib``, or
+``$(prefix)/lib``. This assumption can cause a serious mess if ``/usr/lib``
+isn't a symlink to ``/usr/lib64``. To find the bad packages, we have a portage feature
+called **multilib-strict**. It will prevent emerge from putting 64bit libraries
+into anything other than ``(/usr)/lib64``.
+
+``multilib-strict`` currently doesn't check perl5, gcc, gcc-lib and eclipse-3,
+this behaviour is controlled by the ``MULTILIB_STRICT_EXEMPT`` variable in
+``make.profile``.
+
+How to fix ebuilds properly
+'''''''''''''''''''''''''''
+
+In most cases, it's sufficient to use the ``$(get_libdir)`` function from
+``multilib.eclass``:
+
+.. CODESAMPLE amd64-1.ebuild
+
+Some packages provide really bad Makefiles which hard-code ``/usr/lib``. Those
+should be ``sed`` -ed or patched. Don't forget to let upstream know about your
+modifications!
+
+Headers and Multilib
+~~~~~~~~~~~~~~~~~~~~
+
+Most C/C++ programs need standard header files like ``types.h``. Some of them
+depend on architecture specific facts, e.g. ``types.h`` on the length
+of machine words. To ensure that we can compile both 32bit and 64bit
+applications and libraries, we treat ``/usr/include/asm`` a bit special.
+
+This is what ``/usr/include/asm/types.h`` looks like on a AMD64 box:
+
+.. CODESAMPLE amd64-2.c
+
+As you can see, this is just a wrapper that decides which file you need
+depending on the the parameter ``-D`` given to gcc. You'll probably run into
+some troubles if you try to compile something by hand and forget to append
+``-D__x86_64__`` to your ``CFLAGS``. Of course, this is **not necessary** when
+using portage. For an explanation, see the `The ABI Variable`_ section.
+
+The ABI Variable
+~~~~~~~~~~~~~~~~
+
+Whenever portage builds something on amd64, it has to decide whether it should
+be 32bit or 64bit. As stated in `Headers and Multilib`_, the ``__i386__`` or
+``__x86_64__`` respectively, is needed in ``CDEFINE``. Also, gcc has to know
+what code it should produce, therefore ``-m32`` or ``-m64`` must be appended to
+CFLAGS. This is done via ``profile.bashrc``. All you need to do if you want to
+build a package 32bit is to set ``ABI=x86``.
+
+The details are shown in ``make.defaults``:
+
+.. CODESAMPLE amd64-3.ebuild
+
+Porting Notes
+-------------
+
+Machine Word sizes
+~~~~~~~~~~~~~~~~~~
+
+On AMD64, some types differ in size from x86:
+
+=============== =========== ============
+Type x86 (ILP32) amd64 (LP64)
+=============== =========== ============
+``char`` 1 byte 1 byte
+``short`` 2 bytes 2 bytes
+``int`` 4 bytes 4 bytes
+``long`` **4 bytes** **8 bytes**
+``long long`` 8 bytes 8 bytes
+``pointer`` **4 bytes** **8 bytes**
+``float`` 4 bytes 4 bytes
+``double`` 8 bytes 8 bytes
+``long double`` 16 bytes 16 bytes
+=============== =========== ============
+
+If you need an exact amount of space, don't use these types but the ``uXX`` and
+``sXX`` ones provided by ``types.h``, where XX is the number of bits you need.
+Switching to a type that is the same on both arches is not suggested since it's
+not a clean solution and might cause problems with other arches.
+
+Casts
+~~~~~
+
+Many upstream developers assume that the length of a pointer is 4 bytes, which
+can cause problems when programs do casts from ``void *`` to ``int`` and vice
+versa. With GCC 3.4, this causes warnings, the compilation won't abort. If
+you're lucky, your package works, but it's likely that you encounter
+segmentation faults or strange behaviour. GCC 4.0 refuses to compile such code.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/archs/mips/text.rst b/archs/mips/text.rst
new file mode 100644
index 0000000..bd8fce4
--- /dev/null
+++ b/archs/mips/text.rst
@@ -0,0 +1,73 @@
+Arch Specific Notes -- MIPS
+===========================
+
+The MIPS port uses the ``mips`` keyword. It focuses upon commonly available
+hardware -- mainly SGI and Cobalt systems -- although various embedded and
+special purpose boards are also supported.
+
+The ``mips`` keyword covers a huge range of architectures, CPUs and hardware,
+from tiny embedded devices up to server class kit with many tens of CPUs.
+
+.. Note:: Terminology
+ ABI stands for "Application Binary Interface". It refers to issues like
+ calling conventions (which registers are used for passing parameters when
+ calling functions) and the size of data types. ISA stands for "Instruction
+ Set Architecture", and refers to the instructions available and the number
+ and types of registers for a given CPU.
+
+MIPS ABIs
+---------
+
+The ``o32`` ABI was a wonderful invention by SGI that was good at the time, but
+later turned out to be a little bit short-sighted and inefficient. The ``n32``
+ABI corrects that problem by pretending to be 32 bit, whilst in reality being 64
+bit. ``n64`` is another 64 bit ABI, this time not pretending to be 32 bit, which
+is therefore large, fat and yet very powerful.
+
+All of these ABIs can be both big and little endian, since MIPS CPUs come in
+both flavours, although most hardware does not support both options.
+
+All of these ABIs are popular amongst various applications domains. None of them
+actually work correctly.
+
+MIPS ISAs
+---------
+
+The most commonly seen MIPS ISAs are mips2, mips3, mips4, mips32 and mips64. If
+you encounter a situation in which you need to know about the differences
+between these, talk to the MIPS team.
+
+Not Dropping ``CFLAGS`` on MIPS
+-------------------------------
+
+Because ``CFLAGS`` are sometimes used to specify ISA and ABI information, it is
+vital that packages honour this setting. See `Not Filtering Variables`_.
+
+Additional MIPS Keywording Requirements
+---------------------------------------
+
+.. Note:: This section is in addition to the guidelines in `Keywording`_. It
+ discusses *additional* requirements for the MIPS architectures.
+
+For a package to have the ``~mips`` keyword added, the following additional
+items must generally hold:
+
+* The package should work on both big and little endian systems, on both pure
+ 32 bit and pure 64 bit systems and on systems with differing kernel and
+ userland ABIs.
+
+It is generally expected that anyone who does keywording for MIPS should be on
+the ``mips@`` alias.
+
+Contacting the MIPS Team
+-------------------------
+
+The MIPS team can be contacted:
+
+* Via Bugzilla bugs assigned to ``mips@``
+* Via email to the ``mips@`` email alias
+* Via email to the ``gentoo-mips`` mailing list
+* Via the ``#gentoo-mips`` IRC channel on Freenode
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/archs/sparc/text.rst b/archs/sparc/text.rst
new file mode 100644
index 0000000..c83cfb2
--- /dev/null
+++ b/archs/sparc/text.rst
@@ -0,0 +1,70 @@
+Arch Specific Notes -- SPARC
+============================
+
+The SPARC port uses the ``sparc`` keyword. It focusses mainly upon ``sun4u``
+hardware (Sun UltraSparc systems with ``v9`` CPUs), although ``sun4m`` (Sun 32
+bit hardware with ``v8`` and clones) is also sort-of supported.
+
+SPARC Kernel and Userland ABIs
+------------------------------
+
+``v9`` systems use a pure 64 bit kernel and a pure 32 bit userland. This can
+cause portability problems when working with low level software if the kernel
+does not provide working 32 bit compatibility interfaces.
+
+``v8`` systems use a pure 32 bit kernel and a pure 32 bit userland.
+
+All supported SPARC systems are big endian.
+
+Additional SPARC Keywording Requirements
+----------------------------------------
+
+.. Important:: This section is in addition to the guidelines in `Keywording`_.
+ It discusses *additional* requirements for the SPARC architecture.
+
+For a package to have the ``~sparc`` keyword added, the following additional
+items must generally hold:
+
+* The package must have been tested by an arch team member (or someone with
+ permission from the arch team) *at least* on a ``v9`` system. Testing on
+ ``v8`` is encouraged but not required.
+
+It is generally expected that anyone who does keywording for SPARC should be on
+the ``sparc@`` alias.
+
+SPARC Instruction Set and Performance Notes
+-------------------------------------------
+
+There are three basic SPARC instruction set standards.
+
+* ``v7`` is the original instruction set used in very old hardware. Gentoo does
+ not ship ``v7`` capable stages, however a sufficiently crazy person could in
+ theory run Gentoo on a ``v7`` machine.
+* ``v8`` is an extension of ``v7`` with added support for hardware integer
+ multiplication and division. Gentoo sparc32 (``sun4m``) stages are ``v8``.
+* ``v9`` adds in 64 bit support and a large number of performance-enhancing
+ features. Gentoo sparc64 (``sun4u``) stages are ``v9``.
+
+In addition, individual CPU implementations have slight differences -- for
+example, HyperSparc CPUs have relaxed requirements when it comes to scheduling
+certain instructions. These are relatively minor differences.
+
+If ``gcc`` is invoked without any ``-mcpu`` parameter, it will generate ``v7``
+code. Depending upon the application, this can be anywhere up to five times
+slower than ``v9`` code when running on an UltraSparc -- cryptographic and
+graphics applications which make heavy use of integer multiplication and
+division are especially badly hit. For this reason, the comments in `Not
+Filtering Variables`_ are especially important on SPARC.
+
+Contacting the SPARC Team
+-------------------------
+
+The SPARC team can be contacted:
+
+* Via Bugzilla bugs assigned to ``sparc@``
+* Via email to the ``sparc@`` email alias
+* Via email to the ``gentoo-sparc`` mailing list
+* Via the ``#gentoo-sparc`` IRC channel on Freenode
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/archs/text.rst b/archs/text.rst
new file mode 100644
index 0000000..f6fc064
--- /dev/null
+++ b/archs/text.rst
@@ -0,0 +1,17 @@
+Arch Specific Notes
+===================
+
+This section provides a brief overview of various arch-specific issues. It is not
+complete, and it is not a substitute for discussing any problems with the
+relevant arch team.
+
+.. Note:: People who have worked with some other distributions may find Gentoo's
+ views on architecture support slightly unfamiliar. We do not follow Debian's
+ attempts to provide a standard set of packages at specific versions and install
+ it onto every platform -- rather, we simply attempt to provide whatever
+ happens to work best in any situation.
+
+.. CHILDLIST
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/archs/x86/text.rst b/archs/x86/text.rst
new file mode 100644
index 0000000..3dce379
--- /dev/null
+++ b/archs/x86/text.rst
@@ -0,0 +1,10 @@
+Arch Specific Notes -- x86
+==========================
+
+Originally, it was assumed that all developers would have access to x86 hardware
+and that x86 would be maintained by everyone. For this reason there is no team
+for x86 of the kind that exists for other archs -- there *is* an ``x86@``
+Bugzilla alias, but it is generally only used for security bugs where the herd
+has no members with x86 hardware.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/changelog/text.rst b/changelog/text.rst
new file mode 100644
index 0000000..4b450d8
--- /dev/null
+++ b/changelog/text.rst
@@ -0,0 +1,78 @@
+Changes
+=======
+
+20050529 ``ferdy``
+ Added `Arch Specific Notes -- Alpha`_.
+
+20050527 ``ciaranm``
+ Clarified some things in `Common Problems`_. Changed URL for `The
+ Portage Cache`_.
+
+20050526 ``ciaranm``
+ Text for `Herds and Projects`_.
+
+ Tidied up `Ebuild Revisions`_.
+
+ More on `Filtering Variables`_.
+
+ Added automatically generated `Todo List`_.
+
+20050525 ``flameeyes``
+ `aclocal and m4 Files`_ section.
+
+20050522 ``flameeyes``
+ `Working with PAM`_ section.
+
+20050522 ``ciaranm``
+ Updated `Overlay`_, `The Portage Cache`_, `Eclass Writing Guide`_ with
+ more notes about eclasses in overlay.
+
+ Moved `Init Scripts`_, `Completion Files`_, `Environment Files`_ from
+ `Miscellaneous Files`_ to the new `Tasks Reference`_ section. Moved
+ `Miscellaneous Files`_ to be under `Ebuild Writing`_.
+
+ Added `Common Problems`_ section.
+
+20050521 ``ciaranm``
+ Added `Licenses`_ section.
+
+ Started `Arch Specific Notes`_ section.
+
+20050520 ``ciaranm``
+ Added some more to 'How Autotools Work', renamed to `The Basics of
+ Autotools`_.
+
+20050519 ``ciaranm``
+ Added `Contributing to This Document`_.
+
+ Added some more to 'How Autotools Work'.
+
+20050518 ``fuzzyray``
+ `RPM Sources`_ now has content.
+
+20050511 ``ciaranm``
+ Fix naming in `Eclass Writing Guide`_.
+
+20050507 ``ciaranm``
+ Improved 'How Autotools Work'.
+
+ Added in note on ``einstall`` to the `Quickstart Ebuild Guide`_.
+
+20050507 ``hansmi``
+ Clarify tab wording in `Here Documents`_.
+
+20050506 ``ciaranm``
+ Added `tr -- Character Translation`_.
+
+ Added `noblah USE Flags`_ and updated `Profiles use.mask File`_.
+
+20050505 ``ciaranm``
+ Improved `pkg_nofetch`_ and `Restricting Automatic Mirroring`_.
+
+ Added `glep31check -- UTF-8 Validation`_.
+
+ Started a ChangeLog for keeping track of major user-facing changes.
+ Typo fixes, minor wording updates and build system alterations won't be
+ logged.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/ebuild-writing/error-handling/error-handling-1.ebuild b/ebuild-writing/error-handling/error-handling-1.ebuild
new file mode 100644
index 0000000..317029c
--- /dev/null
+++ b/ebuild-writing/error-handling/error-handling-1.ebuild
@@ -0,0 +1,3 @@
+# Header
+
+[[ -f foorc ]] && ( update_foorc || die "Couldn't update foorc!" )
diff --git a/ebuild-writing/error-handling/error-handling-2.ebuild b/ebuild-writing/error-handling/error-handling-2.ebuild
new file mode 100644
index 0000000..7ac1b45
--- /dev/null
+++ b/ebuild-writing/error-handling/error-handling-2.ebuild
@@ -0,0 +1,5 @@
+# Header
+
+if [[ -f foorc ]] ; then
+ update_foorc || die "Couldn't update foorc!"
+fi
diff --git a/ebuild-writing/error-handling/error-handling-3.ebuild b/ebuild-writing/error-handling/error-handling-3.ebuild
new file mode 100644
index 0000000..daf667f
--- /dev/null
+++ b/ebuild-writing/error-handling/error-handling-3.ebuild
@@ -0,0 +1,3 @@
+# Header
+
+cat list | while read file ; do epatch ${file} ; done
diff --git a/ebuild-writing/error-handling/error-handling-4.ebuild b/ebuild-writing/error-handling/error-handling-4.ebuild
new file mode 100644
index 0000000..ff45221
--- /dev/null
+++ b/ebuild-writing/error-handling/error-handling-4.ebuild
@@ -0,0 +1,3 @@
+# Header
+
+while read file ; do epatch ${file} ; done < list
diff --git a/ebuild-writing/error-handling/error-handling-5.ebuild b/ebuild-writing/error-handling/error-handling-5.ebuild
new file mode 100644
index 0000000..af0133f
--- /dev/null
+++ b/ebuild-writing/error-handling/error-handling-5.ebuild
@@ -0,0 +1,4 @@
+# Header
+
+bunzip2 ${DISTDIR}/${VIM_RUNTIME_SNAP} | tar xf
+assert
diff --git a/ebuild-writing/error-handling/text.rst b/ebuild-writing/error-handling/text.rst
new file mode 100644
index 0000000..5e27eab
--- /dev/null
+++ b/ebuild-writing/error-handling/text.rst
@@ -0,0 +1,72 @@
+Error Handling
+==============
+
+Importance of Error Handling
+----------------------------
+
+Decent error handling is important because:
+
+* Errors must be detected *before* portage tries to install a broken or
+ incomplete package onto the live filesystem. If build failures aren't caught,
+ a working package could be unmerged and replaced with nothing.
+
+* When receiving bug reports, it is a lot easier to figure out what went wrong
+ if you know exactly which function caused the error, rather than just knowing
+ that, say, something somewhere in ``src_compile`` broke.
+
+* Good error handling and notification can help cut down on the number of bug
+ reports received for a package.
+
+The ``die`` Function
+--------------------
+
+The ``die`` function should be used to indicate a fatal error and abort the
+build. Its parameters should be the message to display.
+
+Although ``die`` will work with no parameters, a short message should always be
+provided to ease error identification. This is especially important when a
+function can die in multiple places.
+
+Some portage-provided functions will automatically die upon failure. Others will
+not. It is safe to omit the ``|| die`` after a call to ``epatch``, but not
+``econf`` or ``emake``.
+
+Sometimes displaying additional error information beforehand can be useful. Use
+``eerror`` to do this. See `Messages`_.
+
+``die`` and Subshells
+---------------------
+
+.. Warning:: ``die`` **will not work in a subshell**.
+
+The following code will not work as expected, since the ``die`` is inside a
+subshell:
+
+.. CODESAMPLE error-handling-1.ebuild
+
+The correct way to rewrite this is to use an ``if`` block:
+
+.. CODESAMPLE error-handling-2.ebuild
+
+When using pipes, a subshell is introduced, so the following is unsafe:
+
+.. CODESAMPLE error-handling-3.ebuild
+
+Using input redirection (see `Abuse of cat`_) avoids this problem:
+
+.. CODESAMPLE error-handling-4.ebuild
+
+The ``assert`` Function and ``$PIPESTATUS``
+-------------------------------------------
+
+When using pipes, simple conditionals and tests upon ``$?`` will not correctly
+detect errors occurring in anything except the final command in the chain. To get
+around this, ``bash`` provides the ``$PIPESTATUS`` variable, and portage
+provides the ``assert`` function to check this variable.
+
+.. CODESAMPLE error-handling-5.ebuild
+
+If you need the gory details of ``$PIPESTATUS``, see `bash-1`_. Most of the
+time, ``assert`` is enough.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/ebuild-writing/examples/text.rst b/ebuild-writing/examples/text.rst
new file mode 100644
index 0000000..4975720
--- /dev/null
+++ b/ebuild-writing/examples/text.rst
@@ -0,0 +1,26 @@
+Further Ebuild Examples
+=======================
+
+We'll finish the ebuild writing guide with a few examples. These are real
+packages that the author has worked on that may or may not be in the tree --
+most of these are fairly simple apps that illustrate certain points nicely.
+
+Writing a ``detox`` Ebuild
+--------------------------
+
+.. Todo:: write this
+
+
+Writing an ``msort`` Ebuild
+---------------------------
+
+.. Todo:: write this
+
+
+Writing a ``hilite`` Ebuild
+---------------------------
+
+.. Todo:: write this
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/file-format/header-sample.ebuild b/ebuild-writing/file-format/header-sample.ebuild
new file mode 100644
index 0000000..07b119f
--- /dev/null
+++ b/ebuild-writing/file-format/header-sample.ebuild
@@ -0,0 +1,5 @@
+# Header
+
+# Copyright 1999-2005 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+# $Header: $
diff --git a/ebuild-writing/file-format/text.rst b/ebuild-writing/file-format/text.rst
new file mode 100644
index 0000000..561a70a
--- /dev/null
+++ b/ebuild-writing/file-format/text.rst
@@ -0,0 +1,78 @@
+Ebuild File Format
+==================
+
+An ebuild is a ``bash`` script which is executed within a special environment. Files
+should be simple text files with a ``.ebuild`` extension.
+
+File Naming Rules
+-----------------
+
+An ebuild should be named in the form ``name-version.ebuild``.
+
+The name section should contain only lowercase non-accented letters, the digits
+0-9, hyphens, underscores and plus characters. Uppercase characters are strongly
+discouraged, but technically valid.
+
+.. Note:: This is the same as `IEEE1003.1-2004-3.276`_, with the addition of the plus
+ character to keep gtk+ and friends happy.
+
+The version section is more complicated. It consists of one or more numbers
+separated by full stop (or period, or dot, or decimal point) characters (eg
+``1.2.3``, ``20050108``). The final number may have a single letter following it
+(eg ``1.2b``). This letter should not be used to indicate 'beta' status --
+portage treats ``1.2b`` as being a later version than ``1.2`` or ``1.2a``.
+
+There can be a suffix to version indicating the kind of release. In the following table, what portage considers to be the 'lowest' version comes first.
+
+=============== ===========================
+Suffix Meaning
+=============== ===========================
+``_alpha`` Alpha release (earliest)
+``_beta`` Beta release
+``_pre`` Pre release
+``_rc`` Release candidate
+(no suffix) Normal release
+``_p`` Patch level
+=============== ===========================
+
+Any of these suffixes may be followed by a non-zero positive integer.
+
+Finally, version may have a Gentoo revision number in the form ``-r1``. The initial
+Gentoo version should have no revision suffix, the first revision should be
+``-r1``, the second ``-r2`` and so on. See `Ebuild Revisions`_.
+
+Overall, this gives us a filename like ``libfoo-1.2.5b_pre5-r2.ebuild``.
+
+Ebuild Header
+-------------
+
+All ebuilds committed to the tree should have a three line header immediately at
+the start indicating copyright. This must be an exact copy of the contents of
+``$(portageq portdir)/header.txt``. Ensure that the ``$Header: $`` line is not
+modified manually -- CVS will handle this line specially.
+
+.. CODESAMPLE header-sample.ebuild
+
+Indenting and Whitespace
+------------------------
+
+Indenting in ebuilds must be done with tabs, one tab per indent level. Each tab
+represents four spaces. Tabs should only be used for indenting, never inside
+strings.
+
+Avoid trailing whitespace: repoman will warn you about this if your
+ebuild contains trailing or leading whitespace (whitespace instead of
+tabs for indentation) when you commit.
+
+Where possible, try to keep lines no wider than 80 positions. A 'position' is
+generally the same as a character -- tabs are four positions wide, and multibyte
+characters are just one position wide.
+
+Character Set
+-------------
+
+All ebuilds (and eclasses, metadata files and ChangeLogs) must use the UTF-8
+character set. See `GLEP 31`_ for details, and `glep31check`_ for an easy way of
+checking for validity.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/ebuild-writing/functions/diagram.svg b/ebuild-writing/functions/diagram.svg
new file mode 100644
index 0000000..5834bec
--- /dev/null
+++ b/ebuild-writing/functions/diagram.svg
@@ -0,0 +1,71 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg viewBox="0 100 830 80" xmlns="http://www.w3.org/2000/svg" version="1.1">
+ <desc>Ebuild Function Order</desc>
+ <rect x="-10" y="-10" width="1000" height="1000" fill="#eeeeee" id="background" />
+
+ <rect x="10" y="110" width="80" height="30"
+ fill="#ccccff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="50" y="130">pkg_setup</text>
+
+ <line x1="90" y1="125" x2="130" y2="125" stroke-width="2" stroke="black" />
+ <line x1="130" y1="125" x2="122" y2="120" stroke-width="2" stroke="black" />
+ <line x1="130" y1="125" x2="122" y2="130" stroke-width="2" stroke="black" />
+
+ <rect x="130" y="110" width="80" height="30"
+ fill="#ffffff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="170" y="130">src_unpack</text>
+
+ <line x1="210" y1="125" x2="250" y2="125" stroke-width="2" stroke="black" />
+ <line x1="250" y1="125" x2="242" y2="120" stroke-width="2" stroke="black" />
+ <line x1="250" y1="125" x2="242" y2="130" stroke-width="2" stroke="black" />
+
+ <rect x="250" y="110" width="80" height="30"
+ fill="#ffffff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="290" y="130">src_compile</text>
+
+ <line x1="330" y1="125" x2="370" y2="125" stroke-width="2" stroke="black" />
+ <line x1="370" y1="125" x2="362" y2="120" stroke-width="2" stroke="black" />
+ <line x1="370" y1="125" x2="362" y2="130" stroke-width="2" stroke="black" />
+
+ <path d="M 330 125 Q 350 125 350 137 Q 350 150 370 150
+ L 450 150 Q 470 150 470 137 Q 470 125 490 125"
+ stroke-width="2" stroke="black" fill="none" />
+
+ <rect x="370" y="110" width="80" height="30"
+ fill="#ccffcc" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="410" y="130">src_test</text>
+
+ <line x1="450" y1="125" x2="490" y2="125" stroke-width="2" stroke="black" />
+ <line x1="490" y1="125" x2="482" y2="120" stroke-width="2" stroke="black" />
+ <line x1="490" y1="125" x2="482" y2="130" stroke-width="2" stroke="black" />
+
+ <rect x="490" y="110" width="80" height="30"
+ fill="#ffffff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="530" y="130">src_install</text>
+
+ <line x1="570" y1="125" x2="610" y2="125" stroke-width="2" stroke="black" />
+ <line x1="610" y1="125" x2="602" y2="120" stroke-width="2" stroke="black" />
+ <line x1="610" y1="125" x2="602" y2="130" stroke-width="2" stroke="black" />
+
+ <rect x="610" y="110" width="80" height="30"
+ fill="#ccccff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="650" y="130">pkg_preinst</text>
+
+ <line x1="690" y1="125" x2="730" y2="125" stroke-width="2" stroke="black" />
+ <line x1="730" y1="125" x2="722" y2="120" stroke-width="2" stroke="black" />
+ <line x1="730" y1="125" x2="722" y2="130" stroke-width="2" stroke="black" />
+
+ <rect x="730" y="110" width="80" height="30"
+ fill="#ccccff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="770" y="130">pkg_postinst</text>
+
+ <path d="M 90 125 Q 110 125 110 142 Q 110 160 130 160
+ L 570 160 Q 590 160 590 142 Q 590 125 610 125"
+ stroke-width="2" stroke="black" fill="none" />
+
+</svg>
+
+<!-- vim: set ft=xml sw=4 sts=4 et : -->
+
diff --git a/ebuild-writing/functions/pkg_config/pkg_config-1.ebuild b/ebuild-writing/functions/pkg_config/pkg_config-1.ebuild
new file mode 100644
index 0000000..1c74945
--- /dev/null
+++ b/ebuild-writing/functions/pkg_config/pkg_config-1.ebuild
@@ -0,0 +1,6 @@
+# Headers.
+
+pkg_config()
+{
+ eerror "This ebuild does not have a config function."
+}
diff --git a/ebuild-writing/functions/pkg_config/pkg_config-2.ebuild b/ebuild-writing/functions/pkg_config/pkg_config-2.ebuild
new file mode 100644
index 0000000..458569a
--- /dev/null
+++ b/ebuild-writing/functions/pkg_config/pkg_config-2.ebuild
@@ -0,0 +1,16 @@
+# Headers.
+
+pkg_config() {
+ if [ ! -d ${ROOT}/var/lib/mysql/mysql ] ; then
+ einfo "Press ENTER to create the mysql database and set proper"
+ einfo "permissions on it, or Control-C to abort now..."
+ read
+ ${ROOT}/usr/bin/mysql_install_db
+ else
+ einfo "Hmm, it appears as though you already have the mysql"
+ einfo "database in place. If you are having problems trying"
+ einfo "to start mysqld, perhaps you need to manually run"
+ einfo "/usr/bin/mysql_install_db and/or check your config"
+ einfo "file(s) and/or database(s) and/or logfile(s)."
+ fi
+}
diff --git a/ebuild-writing/functions/pkg_config/text.rst b/ebuild-writing/functions/pkg_config/text.rst
new file mode 100644
index 0000000..9622da2
--- /dev/null
+++ b/ebuild-writing/functions/pkg_config/text.rst
@@ -0,0 +1,30 @@
+pkg_config
+==========
+
++------------------+---------------------------------------------------+
+| **Function** | ``pkg_config`` |
++------------------+---------------------------------------------------+
+| **Purpose** | Run any special post-install configuration |
++------------------+---------------------------------------------------+
+| **Sandbox** | Disabled |
++------------------+---------------------------------------------------+
+| **Privilege** | root |
++------------------+---------------------------------------------------+
+| **Called for** | manual |
++------------------+---------------------------------------------------+
+
+Default ``pkg_config``
+----------------------
+
+.. CODESAMPLE pkg_config-1.ebuild
+
+Example ``pkg_config``
+----------------------
+
+Taken from the ``mysql`` ebuilds. Note the use of ``${ROOT}``.
+
+.. CODESAMPLE pkg_config-2.ebuild
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
+
diff --git a/ebuild-writing/functions/pkg_nofetch/pkg_nofetch-1.ebuild b/ebuild-writing/functions/pkg_nofetch/pkg_nofetch-1.ebuild
new file mode 100644
index 0000000..e417c9b
--- /dev/null
+++ b/ebuild-writing/functions/pkg_nofetch/pkg_nofetch-1.ebuild
@@ -0,0 +1,12 @@
+# Headers
+
+pkg_nofetch()
+{
+ [ -z "${SRC_URI}" ] && return
+
+ echo "!!! The following are listed in SRC_URI for ${PN}:"
+ for MYFILE in `echo ${SRC_URI}`; do
+ echo "!!! $MYFILE"
+ done
+ return
+}
diff --git a/ebuild-writing/functions/pkg_nofetch/pkg_nofetch-2.ebuild b/ebuild-writing/functions/pkg_nofetch/pkg_nofetch-2.ebuild
new file mode 100644
index 0000000..179f780
--- /dev/null
+++ b/ebuild-writing/functions/pkg_nofetch/pkg_nofetch-2.ebuild
@@ -0,0 +1,8 @@
+# Headers
+
+pkg_nofetch() {
+ einfo "Please download"
+ einfo " - ${P}-main.tar.bz2"
+ einfo " - ${P}-extras.tar.bz2"
+ einfo "from ${HOMEPAGE} and place them in ${DISTDIR}"
+}
diff --git a/ebuild-writing/functions/pkg_nofetch/text.rst b/ebuild-writing/functions/pkg_nofetch/text.rst
new file mode 100644
index 0000000..41c5c99
--- /dev/null
+++ b/ebuild-writing/functions/pkg_nofetch/text.rst
@@ -0,0 +1,35 @@
+pkg_nofetch
+===========
+
++------------------+---------------------------------------------------+
+| **Function** | ``pkg_nofetch`` |
++------------------+---------------------------------------------------+
+| **Purpose** | Tell the user how to deal with fetch-restricted |
+| | packages. |
++------------------+---------------------------------------------------+
+| **Sandbox** | Enabled |
++------------------+---------------------------------------------------+
+| **Privilege** | root |
++------------------+---------------------------------------------------+
+| **Called for** | ebuild |
++------------------+---------------------------------------------------+
+
+Default ``pkg_nofetch``
+-----------------------
+
+.. CODESAMPLE pkg_nofetch-1.ebuild
+
+Example ``pkg_nofetch``
+-----------------------
+
+.. CODESAMPLE pkg_nofetch-2.ebuild
+
+Notes on ``pkg_nofetch``
+------------------------
+
+This function is only triggered for packages which have ``RESTRICT="fetch"``
+(see `Restricting Automatic Mirroring`_) set, and only if one or more components
+listed in ``SRC_URI`` are not already available in the ``distfiles`` directory.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/functions/pkg_postinst/pkg_postinst-1.ebuild b/ebuild-writing/functions/pkg_postinst/pkg_postinst-1.ebuild
new file mode 100644
index 0000000..f4c376a
--- /dev/null
+++ b/ebuild-writing/functions/pkg_postinst/pkg_postinst-1.ebuild
@@ -0,0 +1,6 @@
+# Headers.
+
+pkg_postinst()
+{
+ return
+}
diff --git a/ebuild-writing/functions/pkg_postinst/pkg_postinst-2.ebuild b/ebuild-writing/functions/pkg_postinst/pkg_postinst-2.ebuild
new file mode 100644
index 0000000..1fbc039
--- /dev/null
+++ b/ebuild-writing/functions/pkg_postinst/pkg_postinst-2.ebuild
@@ -0,0 +1,13 @@
+# Headers.
+
+pkg_postinst() {
+ if has_version '<x11-wm/fluxbox-0.9.10-r3' ; then
+ ewarn "You must restart fluxbox before using the [include] /directory/"
+ ewarn "feature if you are upgrading from an older fluxbox!"
+ ewarn " "
+ fi
+ einfo "If you experience font problems, or if fluxbox takes a very"
+ einfo "long time to start up, please try the 'disablexmb' USE flag."
+ einfo "If that fails, please report bugs upstream."
+ epause
+}
diff --git a/ebuild-writing/functions/pkg_postinst/text.rst b/ebuild-writing/functions/pkg_postinst/text.rst
new file mode 100644
index 0000000..5f87394
--- /dev/null
+++ b/ebuild-writing/functions/pkg_postinst/text.rst
@@ -0,0 +1,35 @@
+pkg_postinst
+============
+
++------------------+---------------------------------------------------+
+| **Function** | ``pkg_postinst`` |
++------------------+---------------------------------------------------+
+| **Purpose** | Called after image is installed to ``${ROOT}`` |
++------------------+---------------------------------------------------+
+| **Sandbox** | Disabled |
++------------------+---------------------------------------------------+
+| **Privilege** | root |
++------------------+---------------------------------------------------+
+| **Called for** | ebuild, binary |
++------------------+---------------------------------------------------+
+
+Default ``pkg_postinst``
+------------------------
+
+.. CODESAMPLE pkg_postinst-1.ebuild
+
+Sample ``pkg_postinst``
+-----------------------
+
+.. CODESAMPLE pkg_postinst-2.ebuild
+
+Common ``pkg_postinst`` Tasks
+-----------------------------
+
+The most common use for ``pkg_postinst`` is to display post-install
+informational messages or warnings. Note that ``has_version`` will operate on
+the version that *was* installed, which can be useful for selective upgrade
+messages.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/functions/pkg_postrm/pkg_postrm-1.ebuild b/ebuild-writing/functions/pkg_postrm/pkg_postrm-1.ebuild
new file mode 100644
index 0000000..83f20ca
--- /dev/null
+++ b/ebuild-writing/functions/pkg_postrm/pkg_postrm-1.ebuild
@@ -0,0 +1,6 @@
+# Headers.
+
+pkg_postrm()
+{
+ return
+}
diff --git a/ebuild-writing/functions/pkg_postrm/pkg_postrm-2.ebuild b/ebuild-writing/functions/pkg_postrm/pkg_postrm-2.ebuild
new file mode 100644
index 0000000..0abbd46
--- /dev/null
+++ b/ebuild-writing/functions/pkg_postrm/pkg_postrm-2.ebuild
@@ -0,0 +1,5 @@
+# Headers.
+
+pkg_postrm() {
+ fdo-mime_mime_database_update
+}
diff --git a/ebuild-writing/functions/pkg_postrm/text.rst b/ebuild-writing/functions/pkg_postrm/text.rst
new file mode 100644
index 0000000..f878cc1
--- /dev/null
+++ b/ebuild-writing/functions/pkg_postrm/text.rst
@@ -0,0 +1,33 @@
+pkg_postrm
+==========
+
++------------------+---------------------------------------------------+
+| **Function** | ``pkg_postrm`` |
++------------------+---------------------------------------------------+
+| **Purpose** | Called after a package is unmerged. |
++------------------+---------------------------------------------------+
+| **Sandbox** | Disabled |
++------------------+---------------------------------------------------+
+| **Privilege** | root |
++------------------+---------------------------------------------------+
+| **Called for** | ebuild, binary |
++------------------+---------------------------------------------------+
+
+Default ``pkg_postrm``
+----------------------
+
+.. CODESAMPLE pkg_postrm-1.ebuild
+
+Sample ``pkg_postrm``
+---------------------
+
+.. CODESAMPLE pkg_postrm-2.ebuild
+
+Common ``pkg_postrm`` Tasks
+---------------------------
+
+``pkg_postrm`` is used to update symlinks, cache files and other generated
+content after a package has been uninstalled.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/functions/pkg_preinst/pkg_preinst-1.ebuild b/ebuild-writing/functions/pkg_preinst/pkg_preinst-1.ebuild
new file mode 100644
index 0000000..107af7e
--- /dev/null
+++ b/ebuild-writing/functions/pkg_preinst/pkg_preinst-1.ebuild
@@ -0,0 +1,6 @@
+# Headers.
+
+pkg_preinst()
+{
+ return
+}
diff --git a/ebuild-writing/functions/pkg_preinst/pkg_preinst-2.ebuild b/ebuild-writing/functions/pkg_preinst/pkg_preinst-2.ebuild
new file mode 100644
index 0000000..32efaab
--- /dev/null
+++ b/ebuild-writing/functions/pkg_preinst/pkg_preinst-2.ebuild
@@ -0,0 +1,6 @@
+# Headers.
+
+pkg_preinst() {
+ enewgroup foo
+ enewuser foo -1 /bin/false /dev/null foo
+}
diff --git a/ebuild-writing/functions/pkg_preinst/text.rst b/ebuild-writing/functions/pkg_preinst/text.rst
new file mode 100644
index 0000000..b6d129e
--- /dev/null
+++ b/ebuild-writing/functions/pkg_preinst/text.rst
@@ -0,0 +1,41 @@
+pkg_preinst
+===========
+
++------------------+---------------------------------------------------+
+| **Function** | ``pkg_preinst`` |
++------------------+---------------------------------------------------+
+| **Purpose** | Called before image is installed to ``${ROOT}`` |
++------------------+---------------------------------------------------+
+| **Sandbox** | Disabled |
++------------------+---------------------------------------------------+
+| **Privilege** | root |
++------------------+---------------------------------------------------+
+| **Called for** | ebuild, binary |
++------------------+---------------------------------------------------+
+
+Default ``pkg_preinst``
+-----------------------
+
+.. CODESAMPLE pkg_preinst-1.ebuild
+
+Sample ``pkg_preinst``
+----------------------
+
+.. CODESAMPLE pkg_preinst-2.ebuild
+
+Common Tasks
+------------
+
+There are a few things that are often done in ``pkg_preinst``:
+
+* Adding users and groups -- see `Users and Groups`_
+* Modifying the install image for a particular system. This function allows
+ system-specific customisation to be done even when installing from a binary.
+ The most useful example is probably smart configuration file updating -- a
+ ``pkg_preinst`` could check a configuration file in ``${ROOT}/etc/`` and
+ create a smart updated version in ``${IMAGE}/etc/`` (see `Install
+ Destinations`_) rather than always trying to install the default configuration
+ file (remember `Configuration File Protection`_).
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/functions/pkg_prerm/pkg_prerm-1.ebuild b/ebuild-writing/functions/pkg_prerm/pkg_prerm-1.ebuild
new file mode 100644
index 0000000..0ad76df
--- /dev/null
+++ b/ebuild-writing/functions/pkg_prerm/pkg_prerm-1.ebuild
@@ -0,0 +1,6 @@
+# Headers.
+
+pkg_prerm()
+{
+ return
+}
diff --git a/ebuild-writing/functions/pkg_prerm/pkg_prerm-2.ebuild b/ebuild-writing/functions/pkg_prerm/pkg_prerm-2.ebuild
new file mode 100644
index 0000000..c6fc71a
--- /dev/null
+++ b/ebuild-writing/functions/pkg_prerm/pkg_prerm-2.ebuild
@@ -0,0 +1,6 @@
+# Headers
+
+pkg_prerm() {
+ # clean up temp files
+ [[ -d "${ROOT}/var/tmp/foo" ]] && rm -rf "${ROOT}/var/tmp/foo"
+}
diff --git a/ebuild-writing/functions/pkg_prerm/text.rst b/ebuild-writing/functions/pkg_prerm/text.rst
new file mode 100644
index 0000000..3984806
--- /dev/null
+++ b/ebuild-writing/functions/pkg_prerm/text.rst
@@ -0,0 +1,33 @@
+pkg_prerm
+=========
+
++------------------+---------------------------------------------------+
+| **Function** | ``pkg_prerm`` |
++------------------+---------------------------------------------------+
+| **Purpose** | Called before a package is unmerged. |
++------------------+---------------------------------------------------+
+| **Sandbox** | Disabled |
++------------------+---------------------------------------------------+
+| **Privilege** | root |
++------------------+---------------------------------------------------+
+| **Called for** | ebuild, binary |
++------------------+---------------------------------------------------+
+
+Default ``pkg_prerm``
+---------------------
+
+.. CODESAMPLE pkg_prerm-1.ebuild
+
+Sample ``pkg_prerm``
+--------------------
+
+.. CODESAMPLE pkg_prerm-2.ebuild
+
+Common ``pkg_prerm`` Tasks
+--------------------------
+
+``pkg_prerm`` is used to clean up any files that would otherwise prevent a clean
+unmerge.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/functions/pkg_setup/pkg_setup-1.ebuild b/ebuild-writing/functions/pkg_setup/pkg_setup-1.ebuild
new file mode 100644
index 0000000..978ac66
--- /dev/null
+++ b/ebuild-writing/functions/pkg_setup/pkg_setup-1.ebuild
@@ -0,0 +1,6 @@
+# Headers.
+
+pkg_setup()
+{
+ return
+}
diff --git a/ebuild-writing/functions/pkg_setup/pkg_setup-2.ebuild b/ebuild-writing/functions/pkg_setup/pkg_setup-2.ebuild
new file mode 100644
index 0000000..280dd90
--- /dev/null
+++ b/ebuild-writing/functions/pkg_setup/pkg_setup-2.ebuild
@@ -0,0 +1,17 @@
+# Headers.
+
+pkg_setup() {
+ # We need to know which GUI we're building in several
+ # different places, so work it out here.
+ if use gtk ; then
+ if use gtk2 ; then
+ export mypkg_gui="gtk2"
+ else
+ export mypkg_gui="gtk1"
+ fi
+ elif use motif then
+ export mypkg_gui="motif"
+ else
+ export mypkg_gui="athena"
+ fi
+}
diff --git a/ebuild-writing/functions/pkg_setup/text.rst b/ebuild-writing/functions/pkg_setup/text.rst
new file mode 100644
index 0000000..e949cf9
--- /dev/null
+++ b/ebuild-writing/functions/pkg_setup/text.rst
@@ -0,0 +1,26 @@
+pkg_setup
+=========
+
++------------------+---------------------------------------------------+
+| **Function** | ``pkg_setup`` |
++------------------+---------------------------------------------------+
+| **Purpose** | Pre-build environment configuration and checks. |
++------------------+---------------------------------------------------+
+| **Sandbox** | Disabled |
++------------------+---------------------------------------------------+
+| **Privilege** | root |
++------------------+---------------------------------------------------+
+| **Called for** | ebuild, binary |
++------------------+---------------------------------------------------+
+
+Default ``pkg_setup``
+---------------------
+
+.. CODESAMPLE pkg_setup-1.ebuild
+
+Example ``pkg_setup``
+---------------------
+
+.. CODESAMPLE pkg_setup-2.ebuild
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/ebuild-writing/functions/src_compile/buildenv/cpu-sample.ebuild b/ebuild-writing/functions/src_compile/buildenv/cpu-sample.ebuild
new file mode 100644
index 0000000..22c9261
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/buildenv/cpu-sample.ebuild
@@ -0,0 +1,4 @@
+#
+
+ # Can't use ultrasparc or ultrasparc3 code, drop to v9
+ replace-cpu-flags ultrasparc ultrasparc3 v9
diff --git a/ebuild-writing/functions/src_compile/buildenv/filter-sample.ebuild b/ebuild-writing/functions/src_compile/buildenv/filter-sample.ebuild
new file mode 100644
index 0000000..0e19943
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/buildenv/filter-sample.ebuild
@@ -0,0 +1,5 @@
+#
+
+ # -fomit-frame-pointer leads to nasty broken code on sparc thanks to a
+ # rather icky asm function
+ use sparc && filter-flags -fomit-frame-pointer
diff --git a/ebuild-writing/functions/src_compile/buildenv/ldflags-sample.ebuild b/ebuild-writing/functions/src_compile/buildenv/ldflags-sample.ebuild
new file mode 100644
index 0000000..6968a8e
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/buildenv/ldflags-sample.ebuild
@@ -0,0 +1,7 @@
+#
+
+ # If we're using selinux, we need to add a -D
+ use selinux && append-flags "-DWITH_SELINUX"
+
+ # Secure linking needed, since we're setuid root
+ append-ldflags -Wl,-z,now
diff --git a/ebuild-writing/functions/src_compile/buildenv/replace-sample.ebuild b/ebuild-writing/functions/src_compile/buildenv/replace-sample.ebuild
new file mode 100644
index 0000000..c3c62e1
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/buildenv/replace-sample.ebuild
@@ -0,0 +1,4 @@
+#
+
+ # Seems to have issues with -Os, switch to -O2
+ replace-flags -Os -O2
diff --git a/ebuild-writing/functions/src_compile/buildenv/strip-sample.ebuild b/ebuild-writing/functions/src_compile/buildenv/strip-sample.ebuild
new file mode 100644
index 0000000..13b9628
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/buildenv/strip-sample.ebuild
@@ -0,0 +1,4 @@
+#
+
+ # Our app hates screwy flags
+ strip-flags
diff --git a/ebuild-writing/functions/src_compile/buildenv/text.rst b/ebuild-writing/functions/src_compile/buildenv/text.rst
new file mode 100644
index 0000000..d0718d7
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/buildenv/text.rst
@@ -0,0 +1,78 @@
+Configuring Build Environment
+=============================
+
+Sometimes it is necessary to manipulate certain aspects of the user's build
+environment before running ``./configure``. The ``flag-o-matic`` eclass is the
+best choice for manipulating ``CFLAGS``, ``LDFLAGS`` and suchlike.
+
+.. Note:: Except where otherwise specified, any function which operates on
+ ``CFLAGS`` also operates on ``CXXFLAGS``.
+
+Ebuilds must not simply ignore use ``CFLAGS`` -- see `Not Filtering Variables`_.
+
+Guidelines for Flag Filtering
+-----------------------------
+
+If a package breaks with any reasonable ``CFLAGS``, it is best to filter the
+problematic flag if a bug report is received. Reasonable ``CFLAGS`` are
+``-march=``, ``-mcpu=``, ``-mtune=`` (depending upon arch), ``-O2``, ``-Os`` and
+``-fomit-frame-pointer``. Note that ``-Os`` should usually be replaced with
+``-O2`` rather than being stripped entirely. The ``-fstack-protector`` flag
+should probably be in this group too, although our hardened team claim that this
+flag never ever breaks anything...
+
+The ``-pipe`` flag doesn't affect the generated code, so it's not really
+relevant here, but it's a sensible flag to have set globally.
+
+If a package breaks with other ``CFLAGS``, it is perfectly ok to close the bug
+with a **WONTFIX** suggesting that the user picks more sensible global
+``CFLAGS``. Similarly, if you suspect that a bug is caused by insane CFLAGS, an
+**INVALID** resolution is suitable.
+
+All of the following assumes that the ebuild has an ``inherit flag-o-matic``
+line in the correct place.
+
+Simple Flag Stripping
+---------------------
+
+The ``filter-flags`` function can be used to remove a particular flag from
+``CFLAGS``. Multiple arguments can be supplied; each is the name of a flag to
+remove.
+
+.. CODESAMPLE filter-sample.ebuild
+
+There is a ``filter-ldflags`` function available which does the equivalent for
+``LDFLAGS``.
+
+If a package is known to be very ``CFLAGS`` sensitive, the ``strip-flags``
+function will remove most flags, leaving only a minimal conservative set of
+flags.
+
+.. CODESAMPLE strip-sample.ebuild
+
+Flag Replacement
+----------------
+
+To replace a flag with a different one, use ``replace-flags``. This is most
+commonly used to replace ``-Os`` with ``-O2`` (or ``-O3`` with ``-O2`` if you
+are feeling kind).
+
+.. CODESAMPLE replace-sample.ebuild
+
+There is also a special function named ``replace-cpu-flags`` for replacing CPU
+(``-mtune``, ``-mcpu``, ``-march``) designation flags. The last argument is the
+flag to use; previous arguments are the flags to be replaced.
+
+.. CODESAMPLE cpu-sample.ebuild
+
+Adding Additional Flags
+-----------------------
+
+Sometimes it is necessary to add in additional ``CFLAGS`` or ``LDFLAGS``. The
+``append-flags`` and ``append-ldflags`` functions can be used here.
+
+.. CODESAMPLE ldflags-sample.ebuild
+
+See `flag-o-matic.eclass Reference`_ for a full reference.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/ebuild-writing/functions/src_compile/configure/text.rst b/ebuild-writing/functions/src_compile/configure/text.rst
new file mode 100644
index 0000000..f717df3
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/configure/text.rst
@@ -0,0 +1,30 @@
+Configuring a Package
+=====================
+
+Many packages come with an autoconf-generated ``./configure`` script for
+checking the build environment and configuring optional support for libraries.
+The ``econf`` function should be used where possible -- this will provide
+correct build and path specifications for a Gentoo environment.
+
+Often the configure script will try to automatically enable support for optional
+components based upon installed packages. This must **not** be allowed to
+happen. For example, if a user has ``perl`` installed but has ``USE="-perl"``,
+packages with optional ``perl`` support must not link against ``perl``. This
+automatic detection can usually be overridden using ``--enable-`` and
+``--disable`` or ``--with-`` and ``--without-`` switches (but note that these
+don't always work -- make sure these are tested properly).
+
+The ``use_enable`` and ``use_with`` utility functions should, where appropriate,
+be used to generate these switches.
+
+.. CODESAMPLE use-sample.ebuild
+
+Sometimes the package's choice of name for the option will not exactly match the
+name or case of the ``USE`` flag. This is *very* often the case with the ``X``
+flag. For these situations, there are two argument forms:
+
+.. CODESAMPLE use2-sample.ebuild
+
+To check for an unset ``USE`` flag, the ``use_enable !flag`` form can be used.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/ebuild-writing/functions/src_compile/configure/use-sample.ebuild b/ebuild-writing/functions/src_compile/configure/use-sample.ebuild
new file mode 100644
index 0000000..1127543
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/configure/use-sample.ebuild
@@ -0,0 +1,21 @@
+#
+
+src_compile() {
+ # We have optional perl, python and ruby support
+ econf \
+ $(use_enable perl ) \
+ $(use_enable python ) \
+ $(use_enable ruby ) \
+ || die "Configure failed!"
+
+ # ...
+}
+
+src_compile() {
+ # Our package optional IPv6 support which uses --with rather than
+ # --enable / --disable
+
+ econf $(use_with ipv6 ) || die "econf failed!"
+
+ # ...
+}
diff --git a/ebuild-writing/functions/src_compile/configure/use2-sample.ebuild b/ebuild-writing/functions/src_compile/configure/use2-sample.ebuild
new file mode 100644
index 0000000..fee17c3
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/configure/use2-sample.ebuild
@@ -0,0 +1,16 @@
+#
+
+src_compile() {
+ # Our package has optional perl, python and ruby support
+ econf \
+ $(use_enable perl perlinterp ) \
+ $(use_enable python pythoninterp ) \
+ $(use_enable ruby rubyinterp ) \
+ || die "Configure failed!"
+
+ # ...
+}
+
+src_compile() {
+ econf $(use_with X x11 ) || die "econf failed!"
+}
diff --git a/ebuild-writing/functions/src_compile/default-sample.ebuild b/ebuild-writing/functions/src_compile/default-sample.ebuild
new file mode 100644
index 0000000..cec696e
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/default-sample.ebuild
@@ -0,0 +1,10 @@
+#
+
+src_compile() {
+ if [ -x ./configure ]; then
+ econf
+ fi
+ if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ]; then
+ emake || die "emake failed"
+ fi
+}
diff --git a/ebuild-writing/functions/src_compile/distutils/distutils-1.ebuild b/ebuild-writing/functions/src_compile/distutils/distutils-1.ebuild
new file mode 100644
index 0000000..d2806bf
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/distutils/distutils-1.ebuild
@@ -0,0 +1,5 @@
+# Headers.
+
+inherit distutils
+
+DOCS="CHANGES"
diff --git a/ebuild-writing/functions/src_compile/distutils/distutils-2.ebuild b/ebuild-writing/functions/src_compile/distutils/distutils-2.ebuild
new file mode 100644
index 0000000..25cbfc9
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/distutils/distutils-2.ebuild
@@ -0,0 +1,17 @@
+# Headers.
+
+src_compile() {
+ distutils_src_compile
+ # ...
+}
+
+src_install() {
+ # From the docutils ebuild
+ distutils_src_install
+ cd ${S}/tools
+ for tool in *.py; do
+ newbin ${tool} docutils-${tool}
+ done
+
+ # ...
+}
diff --git a/ebuild-writing/functions/src_compile/distutils/distutils-3.ebuild b/ebuild-writing/functions/src_compile/distutils/distutils-3.ebuild
new file mode 100644
index 0000000..3115bcd
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/distutils/distutils-3.ebuild
@@ -0,0 +1,5 @@
+# Headers
+
+pkg_setup() {
+ distutils_python_tkinter
+}
diff --git a/ebuild-writing/functions/src_compile/distutils/text.rst b/ebuild-writing/functions/src_compile/distutils/text.rst
new file mode 100644
index 0000000..54ae12f
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/distutils/text.rst
@@ -0,0 +1,42 @@
+Distutils
+=========
+
+General overview
+----------------
+
+The python packaging system is known as "distutils", and the hallmark of a
+python package using distutils is the presence of a ``setup.py`` file.
+(One can think of the ``setup.py`` file as the python equivalent of a
+Makefile.) Although distutils is straightforward to use by directly
+running the ``setup.py`` with the appropriate arguments, the distutils
+eclass makes the process much simpler (and dramatically lowers the chance of
+sandbox violations). For example, for the ``dev-python/id3-py`` package the
+body of the e-build (other than the header and URIs) could have been
+written as:
+
+.. CODESAMPLE distutils-1.ebuild
+
+Any files listed in ``${DOCS}`` will be put in the docs directory when
+installed. Note that older versions of the distutils eclass used
+``${mydoc}`` instead, but the preferred variable is ``DOCS``.
+
+In practice, some tweaking is often required in the ``src_compile()`` or,
+more commonly, in the ``src_install()`` steps, and the distutils eclass
+provides ``distutils_src_compile()`` and ``distutils_src_install()``
+convenience functions:
+
+.. CODESAMPLE distutils-2.ebuild
+
+Tkinter (Tk) support
+--------------------
+
+Until portage gains the long-requested ability to depend on USE
+flags, ebuild authors who package graphical python programs will
+probably need to check at emerge-time whether or not python was
+compiled with support for Tkinter. Since Tkinter requires Tk,
+which requires X, default python builds do *not* include Tkinter.
+It's easy enough to check:
+
+.. CODESAMPLE distutils-3.ebuild
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en :
diff --git a/ebuild-writing/functions/src_compile/make/getcc-sample.ebuild b/ebuild-writing/functions/src_compile/make/getcc-sample.ebuild
new file mode 100644
index 0000000..c8eaf8e
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/make/getcc-sample.ebuild
@@ -0,0 +1,14 @@
+#
+
+inherit flag-o-matic toolchain-funcs
+
+src_compile() {
+ # -Os not happy
+ replace-flags -Os -O2
+
+ # We have a weird build.sh to work with which ignores our
+ # compiler preferences. yay!
+ sed -i -e "s:cc -O2:$(tc-getCC) ${CFLAGS}:" build.sh \
+ || die "sed Fix failed. Uh-oh..."
+ ./build.sh || die "Build failed!"
+}
diff --git a/ebuild-writing/functions/src_compile/make/text.rst b/ebuild-writing/functions/src_compile/make/text.rst
new file mode 100644
index 0000000..2128e92
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/make/text.rst
@@ -0,0 +1,40 @@
+Building
+========
+
+The ``emake`` function should be used to call ``make``. This will ensure that
+the user's ``MAKEOPTS`` are used correctly. The ``emake`` function passes on
+any arguments provided, so it can be used to make non-default targets (``emake
+extras``), for example. Occasionally you might encounter a screwy non-autotools
+``Makefile`` that explodes with ``emake``, but this is rare.
+
+Builds should be tested with various ``-j`` settings in ``MAKEOPTS`` to ensure
+that the build parallelises properly. If a package does *not* parallelise
+cleanly, it should be patched.
+
+If patching *really* isn't an option, ``emake -j1`` should be used. However,
+when doing this please remember that you are seriously hurting build times for
+many non-x86 users in particular. Forcing a ``-j1`` can increase build times
+from a few minutes to an hour on some MIPS and SPARC systems.
+
+Fixing Compiler Usage
+---------------------
+
+Sometimes a package will try to use a bizarre compiler, or will need to be told
+which compiler to use. In these situations, the ``tc-getCC()`` function from
+``toolchain-funcs.eclass`` should be used. Other similar functions are available
+-- these are documented in `toolchain-funcs.eclass-5`_.
+
+.. Note:: It is *not* correct to use the ``${CC}`` variable for this purpose.
+
+Sometimes a package will not use the user's ``${CFLAGS}``. This must be worked
+around, as sometimes this variable is used for specifying critical ABI options.
+In these cases, the build scripts should be modified (for example, with ``sed``)
+to use ``${CFLAGS}`` correctly.
+
+.. CODESAMPLE getcc-sample.ebuild
+
+.. Note:: When using ``sed`` with ``CFLAGS``, it is not safe to use a comma or a
+ slash as a delimiter. The vapier-recommended character is a colon.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/functions/src_compile/nobuildsystem/nobuildsystem-1.ebuild b/ebuild-writing/functions/src_compile/nobuildsystem/nobuildsystem-1.ebuild
new file mode 100644
index 0000000..45d9d17
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/nobuildsystem/nobuildsystem-1.ebuild
@@ -0,0 +1,6 @@
+# Headers.
+
+src_compile() {
+ $(tc-getCC ) ${CFLAGS} -o ${PN} ${P}.c \
+ || die "Compile failed!"
+}
diff --git a/ebuild-writing/functions/src_compile/nobuildsystem/nobuildsystem-2.ebuild b/ebuild-writing/functions/src_compile/nobuildsystem/nobuildsystem-2.ebuild
new file mode 100644
index 0000000..c38adb3
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/nobuildsystem/nobuildsystem-2.ebuild
@@ -0,0 +1,11 @@
+# Headers.
+
+src_compile() {
+ CONFIG="-DLINUX -DGKRELLM2 -fPIC `pkg-config gtk+-2.0 --cflags`"
+ LIBS="`pkg-config gtk+-2.0 --libs` -shared"
+ OBJS="top_three2.o gkrelltop2.o"
+
+ gcc -c $CONFIG $CFLAGS top_three.c -o top_three2.o || die
+ gcc -c $CONFIG $CFLAGS gkrelltop.c -o gkrelltop2.o || die
+ gcc $LIBS $CONFIG $CFLAGS -o gkrelltop2.so $OBJS || die
+}
diff --git a/ebuild-writing/functions/src_compile/nobuildsystem/text.rst b/ebuild-writing/functions/src_compile/nobuildsystem/text.rst
new file mode 100644
index 0000000..7fed9c9
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/nobuildsystem/text.rst
@@ -0,0 +1,19 @@
+No Build System
+===============
+
+Occasionally some really small packages are shipped simply as a single ``.c`` file.
+In these circumstances, you can either write your own ``Makefile`` and ship it
+with the source tarball, or just manually compile the thing from within the
+ebuild. Here's an example, from ``app-misc/hilite``:
+
+.. CODESAMPLE nobuildsystem-1.ebuild
+
+Here's an example from ``x11-plugins/gkrelltop``, which ships with a
+``Makefile`` that doesn't actually work:
+
+.. CODESAMPLE nobuildsystem-2.ebuild
+
+A possibly better alternative would be to patch the ``Makefile`` and send it
+upstream.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/ebuild-writing/functions/src_compile/sample-sample.ebuild b/ebuild-writing/functions/src_compile/sample-sample.ebuild
new file mode 100644
index 0000000..12182c3
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/sample-sample.ebuild
@@ -0,0 +1,13 @@
+#
+
+src_compile() {
+ use sparc && filter-flags -fomit-frame-pointer
+ append-ldflags -Wl,-z,now
+
+ econf \
+ $(use_enable ssl ) \
+ $(use_enable perl perlinterp ) \
+ || die "Configure failed!"
+
+ emake || die "Make failed!"
+}
diff --git a/ebuild-writing/functions/src_compile/text.rst b/ebuild-writing/functions/src_compile/text.rst
new file mode 100644
index 0000000..6e70721
--- /dev/null
+++ b/ebuild-writing/functions/src_compile/text.rst
@@ -0,0 +1,36 @@
+src_compile
+===========
+
++------------------+---------------------------------------------------+
+| **Function** | ``src_compile`` |
++------------------+---------------------------------------------------+
+| **Purpose** | Configure and build the package. |
++------------------+---------------------------------------------------+
+| **Sandbox** | Enabled |
++------------------+---------------------------------------------------+
+| **Privilege** | user |
++------------------+---------------------------------------------------+
+| **Called for** | ebuild |
++------------------+---------------------------------------------------+
+
+Default ``src_compile``
+-----------------------
+
+.. CODESAMPLE default-sample.ebuild
+
+Sample ``src_compile``
+----------------------
+
+.. CODESAMPLE sample-sample.ebuild
+
+
+Build Processes
+---------------
+
+Depending upon the build process used by upstream, there are a number of
+possible things that may be done during ``src_compile``:
+
+.. CHILDLIST
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/functions/src_install/src_install-1.ebuild b/ebuild-writing/functions/src_install/src_install-1.ebuild
new file mode 100644
index 0000000..8f927a0
--- /dev/null
+++ b/ebuild-writing/functions/src_install/src_install-1.ebuild
@@ -0,0 +1,7 @@
+# Headers.
+
+src_install()
+{
+ return
+}
+
diff --git a/ebuild-writing/functions/src_install/src_install-2.ebuild b/ebuild-writing/functions/src_install/src_install-2.ebuild
new file mode 100644
index 0000000..c185882
--- /dev/null
+++ b/ebuild-writing/functions/src_install/src_install-2.ebuild
@@ -0,0 +1,6 @@
+# Headers.
+
+src_install() {
+ make DESTDIR="${D}" install || die "Install failed!"
+ dodoc README CHANGES
+}
diff --git a/ebuild-writing/functions/src_install/src_install-3.ebuild b/ebuild-writing/functions/src_install/src_install-3.ebuild
new file mode 100644
index 0000000..d0abd9b
--- /dev/null
+++ b/ebuild-writing/functions/src_install/src_install-3.ebuild
@@ -0,0 +1,3 @@
+# Headers.
+
+ make DESTDIR="${D}" install || die "Install failed"
diff --git a/ebuild-writing/functions/src_install/src_install-4.ebuild b/ebuild-writing/functions/src_install/src_install-4.ebuild
new file mode 100644
index 0000000..ae493a2
--- /dev/null
+++ b/ebuild-writing/functions/src_install/src_install-4.ebuild
@@ -0,0 +1,3 @@
+# Headers.
+
+ einstall || die "Install failed!"
diff --git a/ebuild-writing/functions/src_install/src_install-5.ebuild b/ebuild-writing/functions/src_install/src_install-5.ebuild
new file mode 100644
index 0000000..e827aff
--- /dev/null
+++ b/ebuild-writing/functions/src_install/src_install-5.ebuild
@@ -0,0 +1,4 @@
+# Headers.
+
+ dodir /usr/share/foo-styles/
+ cp -R ${S}/ ${D}/ || die "Install failed!"
diff --git a/ebuild-writing/functions/src_install/src_install-6.ebuild b/ebuild-writing/functions/src_install/src_install-6.ebuild
new file mode 100644
index 0000000..d6cb68b
--- /dev/null
+++ b/ebuild-writing/functions/src_install/src_install-6.ebuild
@@ -0,0 +1,50 @@
+# Headers.
+
+src_install() {
+ dobin udevinfo
+ dobin udevtest
+ into /
+ dosbin udev
+ dosbin udevd
+ dosbin udevsend
+ dosbin udevstart
+ dosbin extras/scsi_id/scsi_id
+ dosbin extras/volume_id/udev_volume_id
+
+ exeinto /etc/udev/scripts
+ doexe extras/ide-devfs.sh
+ doexe extras/scsi-devfs.sh
+ doexe extras/cdsymlinks.sh
+ doexe extras/dvb.sh
+
+ insinto /etc/udev
+ newins ${FILESDIR}/udev.conf.post_050 udev.conf
+ doins extras/cdsymlinks.conf
+
+ # For devfs style layout
+ insinto /etc/udev/rules.d/
+ newins etc/udev/gentoo/udev.rules 50-udev.rules
+
+ # scsi_id configuration
+ insinto /etc
+ doins extras/scsi_id/scsi_id.config
+
+ # set up symlinks in /etc/hotplug.d/default
+ dodir /etc/hotplug.d/default
+ dosym ../../../sbin/udevsend /etc/hotplug.d/default/10-udev.hotplug
+
+ # set up the /etc/dev.d directory tree
+ dodir /etc/dev.d/default
+ dodir /etc/dev.d/net
+ exeinto /etc/dev.d/net
+ doexe etc/dev.d/net/hotplug.dev
+
+ doman *.8
+ doman extras/scsi_id/scsi_id.8
+
+ dodoc COPYING ChangeLog FAQ HOWTO-udev_for_dev README TODO
+ dodoc docs/{overview,udev-OLS2003.pdf,udev_vs_devfs,RFC-dev.d,libsysfs.txt}
+ dodoc docs/persistent_naming/* docs/writing_udev_rules/*
+
+ newdoc extras/volume_id/README README_volume_id
+}
diff --git a/ebuild-writing/functions/src_install/text.rst b/ebuild-writing/functions/src_install/text.rst
new file mode 100644
index 0000000..3e61a65
--- /dev/null
+++ b/ebuild-writing/functions/src_install/text.rst
@@ -0,0 +1,72 @@
+src_install
+===========
+
++------------------+---------------------------------------------------+
+| **Function** | ``src_install`` |
++------------------+---------------------------------------------------+
+| **Purpose** | Install a package image to ``${D}`` |
++------------------+---------------------------------------------------+
+| **Sandbox** | Enabled |
++------------------+---------------------------------------------------+
+| **Privilege** | root |
++------------------+---------------------------------------------------+
+| **Called for** | ebuild |
++------------------+---------------------------------------------------+
+
+Default ``src_install``
+-----------------------
+
+.. CODESAMPLE src_install-1.ebuild
+
+Sample ``src_install``
+----------------------
+
+.. CODESAMPLE src_install-2.ebuild
+
+Easy Installs
+-------------
+
+Often, especially with autotools-powered packages, there is a ``Makefile``
+``install`` target which will honour the ``DESTDIR`` variable to tell it to
+install to a non-root location. If possible, this should be used:
+
+.. CODESAMPLE src_install-3.ebuild
+
+.. Note:: ``make`` should be used over ``emake`` here. Most installs are not
+ designed to be parallelised.
+
+Sometimes this will end up installing a few things into strange places. If and
+only if this is the case, the ``einstall`` function can be used:
+
+.. CODESAMPLE src_install-4.ebuild
+
+It is usually necessary to include additional ``dodoc`` statements for the
+``README``, ``ChangeLog`` etc in these cases.
+
+Trivial Installs
+----------------
+
+For some packages with no ``Makefile`` that only install a small number of
+files, writing a manual install using ``cp`` is the easiest option. For example,
+to do a simple install of some (no compilation required) themes:
+
+.. CODESAMPLE src_install-5.ebuild
+
+Or sometimes a combination of ``insinto`` and ``doins`` (plus related functions
+-- see `Install Functions Reference`_) -- the following is based upon the
+``sys-fs/udev`` install:
+
+.. CODESAMPLE src_install-6.ebuild
+
+This is, of course, considerably harder to handle than a simple ``Makefile``
+driven install.
+
+Other Installs
+--------------
+
+Sometimes, there will be a ``Makefile`` that does not honour ``DESTDIR`` and a
+non-trivial number of files to install. In these situations, it is best to patch
+the ``Makefile`` and contact upstream explaining the situation to them.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/functions/src_test/default-sample.ebuild b/ebuild-writing/functions/src_test/default-sample.ebuild
new file mode 100644
index 0000000..17fc795
--- /dev/null
+++ b/ebuild-writing/functions/src_test/default-sample.ebuild
@@ -0,0 +1,22 @@
+#
+
+src_test()
+{
+ addpredict /
+ if make check -n &> /dev/null; then
+ echo ">>> Test phase [check]: ${CATEGORY}/${PF}"
+ if ! make check; then
+ hasq maketest $FEATURES && die "Make check failed. See above for details."
+ hasq maketest $FEATURES || eerror "Make check failed. See above for details."
+ fi
+ elif make test -n &> /dev/null; then
+ echo ">>> Test phase [test]: ${CATEGORY}/${PF}"
+ if ! make test; then
+ hasq maketest $FEATURES && die "Make test failed. See above for details."
+ hasq maketest $FEATURES || eerror "Make test failed. See above for details."
+ fi
+ else
+ echo ">>> Test phase [none]: ${CATEGORY}/${PF}"
+ fi
+ SANDBOX_PREDICT="${SANDBOX_PREDICT%:/}"
+}
diff --git a/ebuild-writing/functions/src_test/sample-sample.ebuild b/ebuild-writing/functions/src_test/sample-sample.ebuild
new file mode 100644
index 0000000..b22bfa4
--- /dev/null
+++ b/ebuild-writing/functions/src_test/sample-sample.ebuild
@@ -0,0 +1,12 @@
+#
+
+src_compile() {
+ cd ${S}/src/testdir
+
+ # Test 49 won't work inside a portage environment
+ sed -i -e 's~test49.out~~g' Makefile
+
+ # Try to run the non-gui tests only
+ make test-nongui \
+ || die "At least one test failed"
+}
diff --git a/ebuild-writing/functions/src_test/text.rst b/ebuild-writing/functions/src_test/text.rst
new file mode 100644
index 0000000..4e37b24
--- /dev/null
+++ b/ebuild-writing/functions/src_test/text.rst
@@ -0,0 +1,64 @@
+src_test
+========
+
++------------------+---------------------------------------------------+
+| **Function** | ``src_test`` |
++------------------+---------------------------------------------------+
+| **Purpose** | Run pre-install test scripts. |
++------------------+---------------------------------------------------+
+| **Sandbox** | Enabled |
++------------------+---------------------------------------------------+
+| **Privilege** | user |
++------------------+---------------------------------------------------+
+| **Called for** | ebuild |
++------------------+---------------------------------------------------+
+
+Default ``src_test``
+--------------------
+
+.. CODESAMPLE default-sample.ebuild
+
+Sample ``src_test``
+-------------------
+
+.. CODESAMPLE sample-sample.ebuild
+
+Common ``src_test`` Tasks
+-------------------------
+
+Often the default ``src_test`` is fine. Sometimes it is necessary to remove
+certain tests from the list if they cannot be used with a portage environment.
+Reasons for such a failure could include:
+
+* Needing to use X.
+* Needing to work with files which are disallowed by the sandbox.
+* Requiring user input (``src_test`` must not be interactive).
+* Requiring root privileges.
+
+Usually, removing the relevant test from the ``Makefile`` using ``sed`` or
+skipping a particular ``make`` target is sufficient.
+
+.. Note:: ``emake`` should not be used for ``src_test`` -- trying to parallelise
+ tests unless the ``Makefile`` was specifically designed for this can cause all
+ sorts of strange problems.
+
+Try to ensure that tests work properly for your ebuild. A good test suite is
+extremely helpful for arch maintainers.
+
+Skipping Tests
+--------------
+
+Sometimes it is necessary to skip tests entirely. This can be done using a dummy
+``src_test`` function:
+
+.. CODESAMPLE true-sample.ebuild
+
+Another option would be to set ``RESTRICT="test"`` in the ebuild.
+
+.. Note:: If upstream provide a test suite which doesn't work, consider talking
+ to them about getting it fixed. A broken test suite is worse than no test
+ suite at all, since we are unable to tell whether a test failure indicates a
+ genuine fault.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/functions/src_test/true-sample.ebuild b/ebuild-writing/functions/src_test/true-sample.ebuild
new file mode 100644
index 0000000..6569c49
--- /dev/null
+++ b/ebuild-writing/functions/src_test/true-sample.ebuild
@@ -0,0 +1,6 @@
+#
+
+src_test() {
+ # Tests don't even remotely work inside portage
+ true
+}
diff --git a/ebuild-writing/functions/src_unpack/autopackage/text.rst b/ebuild-writing/functions/src_unpack/autopackage/text.rst
new file mode 100644
index 0000000..dbefa92
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/autopackage/text.rst
@@ -0,0 +1,27 @@
+Autopackage
+===========
+
+If a package is only supplied in autopackage format, you must **not** add it to
+the tree, nor go anywhere near it. If a package is supplied in autopackage
+format and some other sane standard format (for example a source tarball), use
+the other format only.
+
+Autopackage packages are utterly unsuitable for Gentoo systems for a worryingly
+large number of reasons:
+
+* To even *unpack* the package, you must run arbitrary code supplied by an
+ untrusted source.
+* They install directly to the live filesystem.
+* Their intrinsic dependency resolver is broken.
+* They do not support the filesystem layout used by Gentoo.
+* They do not support configuration protection.
+* They can clobber arbitrary files on uninstall.
+* The linking mechanism used is insufficiently flexible.
+* The entire format is completely unportable and highly tied to x86 Linux
+ systems.
+
+Upstream are aware of these issues and have no desire to fix them -- indeed,
+they pass off some of their most broken behaviour as 'features'.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/functions/src_unpack/cvs/cvs-1.ebuild b/ebuild-writing/functions/src_unpack/cvs/cvs-1.ebuild
new file mode 100644
index 0000000..ca4d64d
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/cvs/cvs-1.ebuild
@@ -0,0 +1,19 @@
+# Headers.
+
+inherit cvs
+
+SRC_URI=""
+
+src_unpack() {
+ ECVS_SERVER="cvs.sourceforge.net:/cvsroot/vim"
+ ECVS_USER="anonymous"
+ ECVS_PASS=""
+ ECVS_AUTH="pserver"
+ if [[ $(get_major_version ) -ge 7 ]] ; then
+ ECVS_MODULE="vim7"
+ else
+ ECVS_MODULE="vim"
+ fi
+ ECVS_TOP_DIR="${DISTDIR}/cvs-src/${ECVS_MODULE}
+ cvs_src_unpack
+}
diff --git a/ebuild-writing/functions/src_unpack/cvs/cvs-2.ebuild b/ebuild-writing/functions/src_unpack/cvs/cvs-2.ebuild
new file mode 100644
index 0000000..71f23c7
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/cvs/cvs-2.ebuild
@@ -0,0 +1,14 @@
+# Headers.
+
+inherit cvs
+
+ECVS_AUTH="ext"
+CVS_RSH="ssh"
+ECVS_SERVER="savannah.gnu.org:/cvsroot/emacs"
+ECVS_MODULE="emacs"
+ECVS_BRANCH="emacs-unicode-2"
+ECVS_USER="anoncvs"
+ECVS_PASS=""
+ECVS_CVS_OPTIONS="-dP"
+
+# ...and so on. No src_unpack() is specified.
diff --git a/ebuild-writing/functions/src_unpack/cvs/text.rst b/ebuild-writing/functions/src_unpack/cvs/text.rst
new file mode 100644
index 0000000..52d464f
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/cvs/text.rst
@@ -0,0 +1,76 @@
+CVS Sources
+===========
+
+Rather than working with a source tarball, it is possible to use upstream's CVS
+server directly. This can be useful when there is a need to test unreleased
+snapshots on a regular basis.
+
+Disadvantages of CVS Sources
+----------------------------
+
+Note that CVS ebuilds should **not** generally be added to the tree (except
+under ``package.mask``) for the following reasons:
+
+* Upstream CVS servers tend to be far less reliable than our mirroring system
+ (particularly if we're talking Sourceforge...).
+
+* CVS ebuilds create a very heavy server load -- not only is CVS not mirrored,
+ but allowing a CVS checkout is considerably more work for a server than simply
+ serving up a file via HTTP or FTP.
+
+* Many users who are behind firewalls cannot use CVS.
+
+It is safer to make a snapshot instead. For example, ``vim`` snapshots are made
+using: ::
+
+ $ cvs -z3 -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/vim export -r HEAD vim
+
+Disadvantages of CVS Live Sources
+---------------------------------
+
+CVS ebuilds which work against ``HEAD`` rather than a specific date or revision
+are even worse candidates for tree inclusion:
+
+* You can never be sure whether upstream's CVS will actually build at any given
+ point.
+
+* It is extremely difficult to track down bugs when you cannot install the same
+ version of a package as the reporter.
+
+* Many upstream packages tend to get upset if people aren't using a specific
+ released version.
+
+Using CVS Sources
+-----------------
+
+To use a CVS source, ``cvs.eclass`` must be inherited, and then a number of
+variables must be set. The following variables are often useful:
+
+================= ================ ========================
+Variable Purpose Example
+================= ================ ========================
+``ECVS_SERVER`` Server and path ``"cvs.sourceforge.net:/cvsroot/vim"``
+``ECVS_MODULE`` Module ``"vim"``
+``ECVS_BRANCH`` Branch ``"HEAD"``
+``ECVS_AUTH`` Auth method ``"ext"``
+``ECVS_USER`` Username ``"anoncvs"``
+``ECVS_PASS`` Password ``""``
+``ECVS_TOPDIR`` Unpack location ``ECVS_TOP_DIR="${DISTDIR}/cvs-src/${ECVS_MODULE}"``
+================= ================ ========================
+
+See the eclass itself for the full range of options.
+
+Then, to perform the actual checkout, use the ``cvs_src_unpack`` function.
+
+Here's a simple snippet, based upon the CVS options in ``vim.eclass``:
+
+.. CODESAMPLE cvs-1.ebuild
+
+Here's another approach, based upon the ``emacs-cvs`` ebuild, which relies upon
+the default ``src_unpack`` provided in the eclass:
+
+.. CODESAMPLE cvs-2.ebuild
+
+This approach is simpler but less flexible.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/ebuild-writing/functions/src_unpack/deb/text.rst b/ebuild-writing/functions/src_unpack/deb/text.rst
new file mode 100644
index 0000000..e2f8edb
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/deb/text.rst
@@ -0,0 +1,16 @@
+Deb Sources
+===========
+
+.. Todo:: write this. from vapier: we dont have to 'handle' these because all
+ debian packages have a source tarball ... the .deb format is pretty simple
+ though, it's managed by the 'ar' utility from binutils. you can unpack a
+ .deb by simply doing `ar x blah.deb` ... this will give you three files:
+ debian-binary: plain text file which just contains version number of the
+ .deb format control.tar.gz: a few files which control installing/verifying
+ of package data.tar.gz: all the compiled files ... you could just extract it
+ to /
+
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
+
diff --git a/ebuild-writing/functions/src_unpack/epatch/epatch-1.ebuild b/ebuild-writing/functions/src_unpack/epatch/epatch-1.ebuild
new file mode 100644
index 0000000..59c5e9e
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/epatch/epatch-1.ebuild
@@ -0,0 +1,8 @@
+# Headers.
+
+src_unpack() {
+ unpack ${A}
+ cd ${S}
+ epatch ${FILESDIR}/${P}-destdir.patch
+ epatch ${FILESDIR}/${P}-parallel_build.patch
+}
diff --git a/ebuild-writing/functions/src_unpack/epatch/epatch-2.ebuild b/ebuild-writing/functions/src_unpack/epatch/epatch-2.ebuild
new file mode 100644
index 0000000..5e9345d
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/epatch/epatch-2.ebuild
@@ -0,0 +1,8 @@
+# Headers.
+
+src_unpack() {
+ unpack ${P}.tar.bz2
+ cd ${S}
+ epatch ${DISTDIR}/${P}-suse-update.patch.bz2
+ epatch ${FILESDIR}/${PV}-no-TIOCGDEV.patch
+}
diff --git a/ebuild-writing/functions/src_unpack/epatch/epatch-3.ebuild b/ebuild-writing/functions/src_unpack/epatch/epatch-3.ebuild
new file mode 100644
index 0000000..42e0387
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/epatch/epatch-3.ebuild
@@ -0,0 +1,8 @@
+# Headers.
+
+src_unpack() {
+ unpack ${A}
+ cd ${S}
+ EPATCH_SOURCE="${WORKDIR}/patches" EPATCH_SUFFIX="patch" \
+ EPATCH_FORCE="yes" epatch
+}
diff --git a/ebuild-writing/functions/src_unpack/epatch/text.rst b/ebuild-writing/functions/src_unpack/epatch/text.rst
new file mode 100644
index 0000000..287c45b
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/epatch/text.rst
@@ -0,0 +1,69 @@
+Patching with ``epatch``
+========================
+
+The canonical way of applying patches in ebuilds is to use ``epatch`` (from
+``eutils.eclass``) inside ``src_unpack``. This function automatically handles
+``-p`` levels, ``gunzip`` and so on as necessary.
+
+Note that distributing modified tarballs rather than a vanilla tarball and
+patches is *highly* discouraged.
+
+Basic ``epatch`` Usage
+----------------------
+
+In its simplest form, ``epatch`` takes a single filename and applies that patch.
+It will automatically ``die`` if the apply fails. The following is taken from
+``app-misc/detox``:
+
+.. CODESAMPLE epatch-1.ebuild
+
+For larger patches, using ``mirror://gentoo/`` rather than ``files/`` is more
+appropriate. In these situations, it is usually best to ``bzip2`` the patch in
+question (as opposed to ``files/`` patches, which must **not** be compressed).
+For example, from ``app-admin/showconsole``:
+
+.. CODESAMPLE epatch-2.ebuild
+
+Remember to add the patch to ``SRC_URI``.
+
+CVS Keyword Lines and Patches
+'''''''''''''''''''''''''''''
+
+If your patch includes any changes to CVS ``$Id: $`` (or ``$Header: $``, or
+``$Date: $``) lines, it cannot be distributed under ``files/``, since CVS will
+clobber the patch when you commit. In these situations, either remove this hunk
+of the patch manually, or mirror the file.
+
+Multiple Patches with ``epatch``
+--------------------------------
+
+``epatch`` can also apply multiple patches (which can be selectively based upon
+arch) from a single directory. This can be useful if upstream have a habit of
+shipping severely broken releases that need dozens of patches.
+
+A simple example:
+
+.. CODESAMPLE epatch-3.ebuild
+
+Here, one of the ``SRC_URI`` components is a tarball containing many patches
+with file extension ``.patch``.
+
+Variables which may be defined include:
+
+======================== =====================================================
+Variable Purpose
+======================== =====================================================
+``EPATCH_SOURCE`` Specifies the directory in which ``epatch`` looks for
+ patches.
+``EPATCH_SUFFIX`` File extension for patches.
+``EPATCH_OPTS`` Default options to ``patch``.
+``EPATCH_EXCLUDE`` List of patches to exclude.
+``EPATCH_FORCE`` Force epatch to apply patches even if they do not
+ follow the canonical naming form (set to ``yes``).
+======================== =====================================================
+
+Bulk patches should be named in the form ``??_${ARCH}_foo.${EPATCH_SUFFIX}``. If
+they are not, ``EPATCH_FORCE="yes"`` must be set. To apply a patch on all archs,
+use ``all`` for the ``${ARCH}`` part.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/ebuild-writing/functions/src_unpack/other-archive-formats/text.rst b/ebuild-writing/functions/src_unpack/other-archive-formats/text.rst
new file mode 100644
index 0000000..b30d968
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/other-archive-formats/text.rst
@@ -0,0 +1,28 @@
+Other Archive Formats
+=====================
+
+There are a variety of other archive formats which you may encounter.
+
+Zip Files
+---------
+
+If a package is supplied as a ``.zip`` file, you should:
+
+* ``DEPEND`` upon ``app-arch/unzip``
+* Use ``unpack`` as normal
+
+Shar Files
+----------
+
+If a package is supplied as a ``.shar`` file, you should repackage it locally
+into a ``.tar.bz2``. It may also be useful to ask upstream to use a friendlier
+package format -- however, if they ship ``.shar``, chances are they haven't done
+a release in at least ten years.
+
+RAR Files
+---------
+
+``.rar`` files must be repackaged locally into a ``.tar.bz2`` file.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/functions/src_unpack/rpm/rpm-1.ebuild b/ebuild-writing/functions/src_unpack/rpm/rpm-1.ebuild
new file mode 100644
index 0000000..4839e23
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/rpm/rpm-1.ebuild
@@ -0,0 +1,3 @@
+# Headers.
+
+inherit rpm
diff --git a/ebuild-writing/functions/src_unpack/rpm/rpm-2.ebuild b/ebuild-writing/functions/src_unpack/rpm/rpm-2.ebuild
new file mode 100644
index 0000000..446bc6c
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/rpm/rpm-2.ebuild
@@ -0,0 +1,8 @@
+# Headers.
+
+src_unpack () {
+ rpm_src_unpack ${A}
+ cd ${S}
+
+ use ssl && epatch ${FILESDIR}/${PV}/${P}-ssl.patch
+}
diff --git a/ebuild-writing/functions/src_unpack/rpm/rpm-3.ebuild b/ebuild-writing/functions/src_unpack/rpm/rpm-3.ebuild
new file mode 100644
index 0000000..d818c75
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/rpm/rpm-3.ebuild
@@ -0,0 +1,39 @@
+# Headers.
+
+# Copyright 1999-2005 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+# $Header: $
+
+inherit eutils versionator rpm
+
+MY_PV=$(replace_version_separator 3 '-')
+MY_P=fetchmail-${MY_PV}
+
+SRC_URI="http://suse.osuosl.org/suse/i386/9.2/suse/src/${MY_P}.src.rpm"
+DESCRIPTION="SuSE 9.2 Fetchmail Source Package"
+HOMEPAGE="http://www.suse.com"
+LICENSE="GPL-2 public-domain"
+SLOT="0"
+KEYWORDS="-*"
+IUSE=""
+
+RESTRICT="nomirror"
+
+# Need to test if the file can be unpacked with rpmoffset and cpio
+# If it can't then set:
+
+#DEPEND="app-arch/rpm"
+
+# To force the use of rpmoffset and cpio instead of rpm2cpio from
+# app-arch/rpm, then set the following:
+
+#USE_RPMOFFSET_ONLY=1
+
+S=${WORKDIR}/fetchmail-$(get_version_component_range 1-3)
+
+src_unpack () {
+ rpm_src_unpack ${A}
+ cd ${S}
+ EPATCH_SOURCE="${WORKDIR}" EPATCH_SUFFIX="patch" \
+ EPATCH_FORCE="yes" epatch
+}
diff --git a/ebuild-writing/functions/src_unpack/rpm/text.rst b/ebuild-writing/functions/src_unpack/rpm/text.rst
new file mode 100644
index 0000000..bbb4a53
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/rpm/text.rst
@@ -0,0 +1,50 @@
+RPM Sources
+===========
+
+If a package is supplied as an .rpm file, you should:
+
+.. CODESAMPLE rpm-1.ebuild
+
+
+If you don't need to do anything in the unpack phase, then you are finished as
+the ``rpm.eclass`` exports a default ``src_unpack`` that will unpack the rpm
+files.
+
+If you do need to apply patches then override ``src_unpack`` in a manner such
+as:
+
+.. CODESAMPLE rpm-2.ebuild
+
+.. Note:: ``${A}`` can contain non-rpm files since the rpm eclass will call
+ the normal ``unpack`` function for files that are not in the rpm format.
+
+
+Notes on Using ``rpm.eclass``
+-----------------------------
+
+There are two ways to unpack a rpm file -- using the ``rpmoffset`` program from
+``rpm2targz`` and ``cpio``, or by using ``rpm2cpio`` from ``app-arch/rpm``.
+Normally, for unpacking an rpm file, installing the entire rpm application is
+overkill. Because of this, the eclass will only use ``rpm2cpio`` if ``rpm`` is
+already installed on the system. If you want to force the eclass to only use
+the rpm offset method, set ``USE_RPMOFFSET_ONLY=1``.
+
+Another issue that might arise is that ``rpmoffset`` and ``cpio`` are not able
+to unpack the rpm file correctly. If this occurs, then you need to add
+``app-arch/rpm`` to the ``DEPEND`` variable so that ``rpm2cpio`` will be used
+instead.
+
+Example RPM Handling
+--------------------
+
+Here is an ebuild snippet that is based upon the fetchmail source rpm from SuSE
+9.2. The ebuild snippet is complete enough to work with the ``ebuild unpack``
+command. The ebuild will download the source file from the OSU SuSE mirror,
+unpack the file and apply the included patches. The filename should be
+``suse-fetchmail-6.2.5.54.1.ebuild``.
+
+.. CODESAMPLE rpm-3.ebuild
+
+Completion of the ebuild left as exercise to the reader.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/ebuild-writing/functions/src_unpack/src_unpack-1.ebuild b/ebuild-writing/functions/src_unpack/src_unpack-1.ebuild
new file mode 100644
index 0000000..1cc9c25
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/src_unpack-1.ebuild
@@ -0,0 +1,7 @@
+# Headers.
+
+src_unpack() {
+ if [ "${A}" != "" ]; then
+ unpack ${A}
+ fi
+}
diff --git a/ebuild-writing/functions/src_unpack/src_unpack-2.ebuild b/ebuild-writing/functions/src_unpack/src_unpack-2.ebuild
new file mode 100644
index 0000000..21018ef
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/src_unpack-2.ebuild
@@ -0,0 +1,11 @@
+# Headers.
+
+src_unpack() {
+ unpack ${A}
+ cd ${S}
+
+ epatch ${FILESDIR}/${PV}/${P}-fix-bogosity.patch
+ use pam && epatch ${FILESDIR}/${PV}/${P}-pam.patch
+
+ sed -i -e 's/"ispell"/"aspell"/' src/defaults.h || die "Sed failed!"
+}
diff --git a/ebuild-writing/functions/src_unpack/svn/svn-1.ebuild b/ebuild-writing/functions/src_unpack/svn/svn-1.ebuild
new file mode 100644
index 0000000..13ab1a7
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/svn/svn-1.ebuild
@@ -0,0 +1,6 @@
+# Headers.
+
+inherit subversion
+
+ESVN_REPO_URI="http://tao.uab.es/ion/svn/libtu/trunk"
+ESVN_PROJECT="libtu-snapshot"
diff --git a/ebuild-writing/functions/src_unpack/svn/text.rst b/ebuild-writing/functions/src_unpack/svn/text.rst
new file mode 100644
index 0000000..dcb5c84
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/svn/text.rst
@@ -0,0 +1,59 @@
+Subversion Sources
+==================
+
+As with CVS, an eclass exists for working directly with upstream Subversion
+repositories. See `subversion.eclass Reference`_ for a full list of functions
+and variables.
+
+Disavantages of Subversion Sources
+----------------------------------
+
+Note that Subversion ebuilds should **not** generally be added to the tree
+(except under ``package.mask``) for much the same reasons that live CVS ebuilds
+should not (see `Disadvantages of CVS Sources`_). Indeed, there should be even
+less impetus to add a live Subversion ebuild than a live CVS ebuild, as
+Subversion checkouts are roughly a factor of five larger than an equivalent CVS
+checkout.
+
+It is far safer to make a snapshot instead. For example, ``gentoo-syntax``
+snapshots could be (but aren't, because ciaranm is so lazy he automated it)
+made using: ::
+
+ $ svn export svn://svn.berlios.de/svnroot/repos/gentoo-syntax -r HEAD gentoo-syntax
+
+Disadvantages of Subversion Live Sources
+----------------------------------------
+
+Live Subversion ebuilds that work against ``HEAD`` have the same disadvantages
+as Live CVS ebuilds.
+
+Using Subversion Sources
+------------------------
+
+To use a Subversion source, ``subversion.eclass`` must be inherited, and then at
+least ``ESVN_REPO_URI`` must be set. The following variables are also noteworthy:
+
+=================== ========================================= ================
+Variable Purpose Example
+=================== ========================================= ================
+``ESVN_REPO_URI`` Server and path (http, https, svn) ``"svn://svn.example.com/foobar/trunk"``
+``ESVN_STORE_DIR`` Unpack location ``ESVN_STORE_DIR="${DISTDIR}/svn-src"``
+``ESVN_PROJECT`` Project name of ebuild ``ESVN_PROJECT="${PN/-svn}"``
+``ESVN_BOOTSTRAP`` Bootstrap command or script ``ESVN_BOOTSTRAP="autogen.sh"``
+``ESVN_PATCHES`` Patches to apply during bootstrap ``ESVN_PATCHES="${FILESDIR}/*.patch"``
+=================== ========================================= ================
+
+See the eclass itself and `subversion.eclass Reference`_ for the full range of
+options.
+
+To perform the actual checkout, use the ``subversion_src_unpack`` function,
+which calls both ``subversion_svn_fetch`` and ``subversion_bootstrap`` itself.
+
+Here is a simple snippet, based upon the Subversion options in
+``litu-svn-20040902.ebuild``:
+
+.. CODESAMPLE svn-1.ebuild
+
+This approach is sufficient for most Subversion ebuilds.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/ebuild-writing/functions/src_unpack/text.rst b/ebuild-writing/functions/src_unpack/text.rst
new file mode 100644
index 0000000..ba6060d
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/text.rst
@@ -0,0 +1,47 @@
+src_unpack
+==========
+
++------------------+---------------------------------------------------+
+| **Function** | ``src_unpack`` |
++------------------+---------------------------------------------------+
+| **Purpose** | Extract source packages and do any necessary |
+| | patching or fixes. |
++------------------+---------------------------------------------------+
+| **Sandbox** | Enabled |
++------------------+---------------------------------------------------+
+| **Privilege** | user |
++------------------+---------------------------------------------------+
+| **Called for** | ebuild |
++------------------+---------------------------------------------------+
+
+Default ``src_unpack``
+----------------------
+
+.. CODESAMPLE src_unpack-1.ebuild
+
+Sample ``src_unpack``
+---------------------
+
+.. CODESAMPLE src_unpack-2.ebuild
+
+Unpacking Tarballs
+------------------
+
+The ``unpack`` function should be used to unpack tarballs, compressed files and
+so on. Do not use ``tar``, ``gunzip`` etc. manually.
+
+The ``${A}`` variable contains all of the ``SRC_URI`` components, except for any
+which are excluded by USE-based conditionals inside ``SRC_URI`` itself. If
+multiple archives require unpacking in a particular order it is usually simpler
+to avoid working with ``${A}``.
+
+``src_unpack`` Actions
+----------------------
+
+The following subsections cover different topics which often occur when writing
+``src_unpack`` functions.
+
+.. CHILDLIST
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/functions/src_unpack/tla/text.rst b/ebuild-writing/functions/src_unpack/tla/text.rst
new file mode 100644
index 0000000..d8ce2a6
--- /dev/null
+++ b/ebuild-writing/functions/src_unpack/tla/text.rst
@@ -0,0 +1,8 @@
+Arch Sources
+============
+
+.. Todo:: anyone want to write this? You can probably mostly copy the `CVS
+ Sources`_ and `Subversion Sources`_ chapters. -- ciaranm
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/functions/text.rst b/ebuild-writing/functions/text.rst
new file mode 100644
index 0000000..b76c975
--- /dev/null
+++ b/ebuild-writing/functions/text.rst
@@ -0,0 +1,22 @@
+Ebuild Functions
+================
+
+When installing packages from source, the function call order is ``pkg_setup``,
+``src_unpack``, ``src_compile``, ``src_test`` (optional, ``FEATURES="test"``),
+``src_install``, ``pkg_preinst``, ``pkg_postinst``. When installing packages
+from a binary, the function call order is ``pkg_setup``, ``pkg_preinst``,
+``pkg_postinst``.
+
+.. figure:: diagram.png
+ :alt: ebuild function call order
+
+The ``pkg_prerm`` and ``pkg_postrm`` functions are called when uninstalling a
+package. The ``pkg_config`` function is used for any special package
+configuration -- it is only run when explicitly requested by the user. The
+``pkg_nofetch`` function is used when a ``RESTRICT="fetch"`` package needs to
+obtain some ``SRC_URI`` components.
+
+.. CHILDLIST
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/messages/messages-1.ebuild b/ebuild-writing/messages/messages-1.ebuild
new file mode 100644
index 0000000..d567370
--- /dev/null
+++ b/ebuild-writing/messages/messages-1.ebuild
@@ -0,0 +1,7 @@
+# Headers
+
+pkg_postinst() {
+ einfo "You will need to set up your /etc/foo/foo.conf file before"
+ einfo "running foo for the first time. For details, please see the"
+ einfo "foo.conf(5) manual page."
+}
diff --git a/ebuild-writing/messages/messages-2.ebuild b/ebuild-writing/messages/messages-2.ebuild
new file mode 100644
index 0000000..b7c000f
--- /dev/null
+++ b/ebuild-writing/messages/messages-2.ebuild
@@ -0,0 +1,6 @@
+# Headers
+
+i=10
+while ((i--)) ; do
+ ewarn "PLEASE UPDATE TO YOUR PACKAGE TO USE linux-info.eclass"
+done
diff --git a/ebuild-writing/messages/messages-3.ebuild b/ebuild-writing/messages/messages-3.ebuild
new file mode 100644
index 0000000..c1ab4e4
--- /dev/null
+++ b/ebuild-writing/messages/messages-3.ebuild
@@ -0,0 +1,8 @@
+# Headers
+
+ewarn "The 'frozbinate' function provided by eutils.eclass is deprecated"
+ewarn "in favour of frozbinate.eclass, but this package has not been"
+ewarn "updated yet. If this is a package from the main tree, please check"
+ewarn "http://bugs.gentoo.org/ and file a bug if there is not one already."
+ewarn "If this is your own package, please read the comments in the"
+ewarn "frozbinate eclass for instructions on how to convert."
diff --git a/ebuild-writing/messages/text.rst b/ebuild-writing/messages/text.rst
new file mode 100644
index 0000000..53dd41d
--- /dev/null
+++ b/ebuild-writing/messages/text.rst
@@ -0,0 +1,78 @@
+Messages
+========
+
+Sometimes it is necessary to display messages for the user. This can be for
+errors, post-install help messages, pre-install warnings or simply to notify the
+user of what's going on. It is considered good form to display a message
+before any particularly long and silent task is carried out, for example (and it
+also helps cut down on bogus "compiling foo froze!" bugs).
+
+.. Note:: It is a policy violation to use any of these functions to display a line
+ of characters (a banner header). The use of colours and special leading
+ characters provided by these functions is sufficient to make a message stand
+ out.
+
+In all cases, assume that the user's terminal is no wider than 79 columns, and
+that the ``einfo``, ``ewarn`` and ``eerror`` functions will occupy 4 columns
+with their fancy leading markers.
+
+Information Messages
+--------------------
+
+There are a number of functions available to assist here. The `echo` bash
+internal is the simplest -- it simply displays its parameters as a message.
+
+The ``einfo`` function can be used to display an informational message which is
+meant to 'stand out'. On a colour terminal, the message provided will be
+prefixed with a green star.
+
+.. CODESAMPLE messages-1.ebuild
+
+Warning Messages
+----------------
+
+The ``ewarn`` function is similar, but displays a yellow star. This should be
+used for warning messages rather than information.
+
+Error Messages
+--------------
+
+The ``eerror`` function displays a red star, and is used for displaying error
+messages. It should almost always be followed by a ``die`` call. This function
+is mainly used for displaying additional error details before bailing out.
+
+Important Messages
+------------------
+
+For *really* important messages, ``eutils.eclass`` provides ``ebeep`` and
+``epause``. The former will beep a number of times, and the latter will pause
+for several seconds to allow the user to read any messages. Both can be disabled
+by the user -- you must **not** attempt to override the user's preference in
+this. ``ebeep`` takes an optional parameter specifying how many times to beep.
+``epause`` takes an optional parameter (which **must** be an exact whole number)
+specifying for how long it should sleep.
+
+Do not abuse these functions -- better to save them for when things really are
+important.
+
+See `Message Functions Reference`_ for a full list of functions.
+
+Good and Bad Messages
+---------------------
+
+Here is an example of a bad message:
+
+.. CODESAMPLE messages-2.ebuild
+
+* Displaying the same message repeatedly is excessive.
+* The uppercase is excessive.
+* The bad English looks unprofessional.
+* The message will only confuse the end user and will not help them work out
+ whether they have a problem and how to solve it if they do.
+
+It would be better written as:
+
+.. CODESAMPLE messages-3.ebuild
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/misc-files/changelog/changelog b/ebuild-writing/misc-files/changelog/changelog
new file mode 100644
index 0000000..96fa791
--- /dev/null
+++ b/ebuild-writing/misc-files/changelog/changelog
@@ -0,0 +1,10 @@
+# vim: set filetype=gentoo-changelog :
+
+ *vim-6.3.068 (25 Mar 2005)
+
+ 25 Mar 2005; Ciaran McCreesh <ciaranm@gentoo.org> +vim-6.3.068.ebuild:
+ New release. Fixes bug #79981, bug #81289, bug #83383, bug #83416, bug
+ #83565, bug #85758, upstream patches up to 6.3.068.
+
+ 22 Mar 2005; Aron Griffis <agriffis@gentoo.org> vim-6.3-r4.ebuild:
+ Stable on alpha
diff --git a/ebuild-writing/misc-files/changelog/text.rst b/ebuild-writing/misc-files/changelog/text.rst
new file mode 100644
index 0000000..c54eff8
--- /dev/null
+++ b/ebuild-writing/misc-files/changelog/text.rst
@@ -0,0 +1,23 @@
+ChangeLog
+=========
+
+.. _echangelog: ..
+
+The ``ChangeLog`` should be used to record all non-trivial changes to ebuilds,
+*including keywording changes*. The `echangelog`_ tool should be used to create
+``ChangeLog`` entries -- the format of a ``ChangeLog`` is now defined as
+"whatever ``echangelog`` creates".
+
+You should include references to any relevant bugs. The standard format for
+doing this is via the phrase ``bug #20600`` -- this format (with the hash sign
+included) is recognised via `packages.gentoo.org <http://packages.gentoo.org/>`_
+and similar tools. When including user-submitted ebuilds or patches, you should
+credit the user with their full name and email address (or whatever they use to
+identify themselves on bugzilla -- some users prefer to be known only by a
+nickname).
+
+A typical ``ChangeLog`` snippet might look like the following:
+
+.. CODESAMPLE changelog
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/ebuild-writing/misc-files/metadata/catmetadata.xml b/ebuild-writing/misc-files/metadata/catmetadata.xml
new file mode 100644
index 0000000..0edec7e
--- /dev/null
+++ b/ebuild-writing/misc-files/metadata/catmetadata.xml
@@ -0,0 +1,15 @@
+# Header
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <!DOCTYPE catmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
+ <catmetadata>
+ <longdescription lang="en">
+ The app-vim category contains plugins and syntax file
+ packages for the Vim text editor.
+ </longdescription>
+ <longdescription lang="de">
+ Die Kategorie app-vim enthält Plugins und Syntax-Pakete
+ für den Vim Texteditor.
+ </longdescription>
+ </catmetadata>
+
diff --git a/ebuild-writing/misc-files/metadata/pkgmetadata.xml b/ebuild-writing/misc-files/metadata/pkgmetadata.xml
new file mode 100644
index 0000000..deccd06
--- /dev/null
+++ b/ebuild-writing/misc-files/metadata/pkgmetadata.xml
@@ -0,0 +1,16 @@
+# Header
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
+ <pkgmetadata>
+ <herd>vim</herd>
+ <maintainer>
+ <email>ciaranm@gentoo.org</email>
+ <name>Ciaran McCreesh</name>
+ </maintainer>
+ <longdescription lang="en">
+ This package provides Vim syntax highlighting for Cfengine configuration
+ files, and automatic filetype detection for these files based upon
+ filename.
+ </longdescription>
+ </pkgmetadata>
diff --git a/ebuild-writing/misc-files/metadata/text.rst b/ebuild-writing/misc-files/metadata/text.rst
new file mode 100644
index 0000000..82c1699
--- /dev/null
+++ b/ebuild-writing/misc-files/metadata/text.rst
@@ -0,0 +1,47 @@
+Package and Category metadata.xml
+=================================
+
+The ``metadata.xml`` file is used to specify additional data about a package or
+category.
+
+Category Metadata
+-----------------
+
+For categories, ``metadata.xml`` specifies a long description (in English and
+optionally in other languages). The format is specified formally in `GLEP 34`_,
+and the character set **must** be UTF-8 as specified by `GLEP 31`_. A typical
+example:
+
+.. CODESAMPLE catmetadata.xml
+
+
+When creating a new category, creating a ``metadata.xml`` file along with a
+``<longdescription>`` in English is **mandatory**. Translations are handled by
+any interested developer who speaks a language sufficiently well.
+
+The correct way to commit a *category* ``metadata.xml`` file is currently: ::
+
+ xmllint --noout --valid metadata.xml
+ glep31check metadata.xml
+ cvs commit -m "blah" metadata.xml
+
+Package Metadata
+----------------
+
+For packages, ``metadata.xml`` can specify a long description and maintainer
+information. If a long description in any language is provided, an English long
+description must be present. A typical example might look like:
+
+.. CODESAMPLE pkgmetadata.xml
+
+
+All new packages **must** include a ``metadata.xml`` file which specifies *at
+least* a herd. If no herd is suitable, ``no-herd`` should be used, and at least
+one maintainer **must** be listed -- however, if at all possible, find a herd
+willing to be listed.
+
+Commits of package metadata files are handled by ``repoman``. You should ensure
+that you have ``dev-libs/libxml2`` installed so that the XML can be validated.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/misc-files/patches/sample-patch.patch b/ebuild-writing/misc-files/patches/sample-patch.patch
new file mode 100644
index 0000000..7408c3c
--- /dev/null
+++ b/ebuild-writing/misc-files/patches/sample-patch.patch
@@ -0,0 +1,17 @@
+# Header
+
+# Detect Gentoo apache files properly. Gentoo bug 83565.
+
+--- runtime/filetype.vim.orig 2005-03-25 01:44:12.000000000 +0000
++++ runtime/filetype.vim 2005-03-25 01:45:15.000000000 +0000
+@@ -93,6 +93,9 @@
+ " Gentoo apache config file locations (Gentoo bug #76713)
+ au BufNewFile,BufRead /etc/apache2/conf/*/* setf apache
+
++" More Gentoo apache config file locations (Gentoo bug #83565)
++au BufNewFile,BufRead /etc/apache2/{modules,vhosts}.d/*.conf setf apache
++
+ " XA65 MOS6510 cross assembler
+ au BufNewFile,BufRead *.a65 setf a65
+
+
diff --git a/ebuild-writing/misc-files/patches/text.rst b/ebuild-writing/misc-files/patches/text.rst
new file mode 100644
index 0000000..b0c754d
--- /dev/null
+++ b/ebuild-writing/misc-files/patches/text.rst
@@ -0,0 +1,54 @@
+Patches
+=======
+
+There is no fixed rule for patch naming. The following are guidelines only.
+
+Small patches (less than, say, a few KBytes) should be added to ``${FILESDIR}``.
+If you anticipate having several patches, it often helps to create version
+numbered subdirectories -- ``${FILESDIR}/${PV}/`` is conventional. Patches are
+best named ``${P}-what-it-does.patch`` (or ``.diff``), where
+``what-it-does`` is a two or three word description of what the patch is for. If
+the patch is to fix a specific bug, it is often useful to add in the bug number
+-- for example, ``vim-7.0-cron-vars-79981.patch``. If the patch is pulled from
+upstream's CVS / SVN repository, it can help to include the revision number in
+the patch name as a suffix to the version part --
+``fluxbox-0.9.12-3860-menu-backups.patch``.
+
+Patches included in ``${FILESDIR}`` should not be compressed.
+
+Larger patches should be mirrored. When mirroring patches, choosing a name that
+will not cause conflicts is important -- the ``${P}`` prefix is highly
+recommended here. Mirrored patches are often compressed with ``bzip2``. Remember
+to list these patches in ``SRC_URI``.
+
+If a package requires many patches, even if they are individually small, it is
+often best to create a patch tarball to avoid cluttering up the tree too much.
+
+Patch Descriptions
+------------------
+
+It is possible to include a description with a patch. This is often helpful when
+others come to work with your packages, or, indeed when you come back to take a
+look at your own package a few months later. Good things to include in comments
+are:
+
+* What the patch actually does. Bug numbers are good here.
+* Where the patch came from. Is it an upstream CVS/SVN pull, something from
+ Bugzilla, something you wrote?
+* Whether the patch has been sent upstream.
+
+To include the description, simply insert it at the top of the patch file. The
+``patch`` tool will ignore leading text until it finds something that looks like
+it might be a 'start patching' instruction, so as long as each description line
+starts with letters (rather than numbers, symbols or whitespace) there shouldn't
+be a problem. Alternatively, prefix each description line with a hash (that's
+``#``, or 'pound' to the USians) sign. It's also best to leave a single blank
+line after the description and before the main patch.
+
+Here's a simple example (``023_all_vim-6.3-apache-83565.patch``) from the
+``vim`` patch tarball:
+
+.. CODESAMPLE sample-patch.patch
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/misc-files/text.rst b/ebuild-writing/misc-files/text.rst
new file mode 100644
index 0000000..63e2d5c
--- /dev/null
+++ b/ebuild-writing/misc-files/text.rst
@@ -0,0 +1,9 @@
+Miscellaneous Files
+===================
+
+This section contains some notes on various miscellaneous files.
+
+.. CHILDLIST
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/text.rst b/ebuild-writing/text.rst
new file mode 100644
index 0000000..afcffde
--- /dev/null
+++ b/ebuild-writing/text.rst
@@ -0,0 +1,11 @@
+Ebuild Writing
+==============
+
+This section describes how to write an ebuild. It covers the basic format of an
+ebuild and the variables and functions available, and finishes off with some
+general notes and extended examples.
+
+.. FULLCHILDLIST
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/use-conditional-code/text.rst b/ebuild-writing/use-conditional-code/text.rst
new file mode 100644
index 0000000..adef71d
--- /dev/null
+++ b/ebuild-writing/use-conditional-code/text.rst
@@ -0,0 +1,28 @@
+USE Flag Conditional Code
+=========================
+
+Often a particular block of code must only be executed if a given USE flag is
+set (or unset). For large blocks, ``if use foo`` is best, or for inverse tests
+either ``if ! use foo`` or ``if use !foo`` can be used (the former is more
+common and is recommended for readability). For single-statement conditions, the
+``use foo && blah`` (or ``use foo || blah`` for negatives) form is often more
+readable.
+
+The ``if [ "`use foo`" ]`` and ``if [ -n "`use foo`" ]`` forms which are
+occasionally seen in older code must **not** be used.
+
+.. Note:: ``die`` will not work as expected within a subshell, so code in the
+ form ``use foo && ( blah ; blah )`` should be avoided in favour of a proper if
+ statement. See `die and Subshells`_.
+
+.. CODESAMPLE use-sample.ebuild
+
+For echoing content based upon a USE flag, there is often a better helper
+function available.
+
+You must not rely upon ``use`` producing an output -- this no longer happens.
+If you really need output displayed, use the ``usev`` function. The
+``useq`` function is available for explicitly requesting no output.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/use-conditional-code/use-sample.ebuild b/ebuild-writing/use-conditional-code/use-sample.ebuild
new file mode 100644
index 0000000..26f2fca
--- /dev/null
+++ b/ebuild-writing/use-conditional-code/use-sample.ebuild
@@ -0,0 +1,21 @@
+# header
+
+ # USE conditional blocks...
+ if use livecd ; then
+ # remove some extra files for a small livecd install
+ rm -fr ${vimfiles}/{compiler,doc,ftplugin,indent}
+ fi
+
+ # Inverse USE conditional blocks...
+ if ! use cscope ; then
+ # the --disable-cscope configure arg doesn't quite work properly,
+ # so sed it out of feature.h if we're not USEing cscope.
+ sed -i -e '/# define FEAT_CSCOPE/d' src/feature.h || die "couldn't disable cscope"
+ fi
+
+ # USE conditional statements...
+ use ssl && epatch ${FILESDIR}/${P}-ssl.patch
+ use sparc && filter-flags -fomit-frame-pointer
+
+ # Inverse USE conditional statements...
+ use ncurses || epatch ${FILESDIR}/${P}-no-ncurses.patch
diff --git a/ebuild-writing/users-and-groups/text.rst b/ebuild-writing/users-and-groups/text.rst
new file mode 100644
index 0000000..d805533
--- /dev/null
+++ b/ebuild-writing/users-and-groups/text.rst
@@ -0,0 +1,51 @@
+Users and Groups
+================
+
+If your ebuild requires a user or group to be added for a daemon, for example,
+this should be performed via the functions available in ``eutils.eclass``.
+Regardless of whether you are adding a group or a user, this should be performed
+in the ``pkg_setup`` function and **not** somewhere else: pkg_setup is sandbox-safe,
+is called before the compile process so a build that requires the user to exist will
+have it, and is also called for both binary and source packages.
+
+Adding Groups
+-------------
+
+To add a group, use the ``enewgroup`` function: ::
+
+ enewgroup <name> [uid]
+
+By default the next available group ID is selected. To set a specfic group ID,
+pass it an extra argument to ``enewgroup``.
+
+.. Note:: Group IDs should rarely be hardcoded. If this is the case, you should
+ probably check first on gentoo-dev.
+
+Adding Users
+------------
+
+To add a user, use the ``enewuser`` function: ::
+
+ enewuser <user> [uid] [shell] [homedir] [groups] [params]
+
+By default, both ``enewuser`` and ``enewgroup`` allocate the next available user
+ID or group ID to the new user or group - if not, you explicitly have to specify
+one.
+
+Arguments for ``enewuser`` must be passed in the order as shown above: if you do
+not want to specify a fixed user ID however but do want to set a specific shell,
+for example, use ``-1`` for the ``uid`` parameter. The same applies for any other
+parameter where you want to keep the default setting.
+
+Groups for the ``groups`` argument should be separated by a comma (``,``) and
+wrapped correctly, for example: ::
+
+ enewuser frozd -1 -1 -1 "backup,frozd"
+
+Finally, any data left over for the ``params`` argument is passed directly to
+useradd.
+
+.. Note:: User IDs should rarely be hardcoded. If this is the case, you should
+ probably check first on gentoo-dev.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/ebuild-writing/using-eclasses/devtodo.ebuild b/ebuild-writing/using-eclasses/devtodo.ebuild
new file mode 100644
index 0000000..28386be
--- /dev/null
+++ b/ebuild-writing/using-eclasses/devtodo.ebuild
@@ -0,0 +1,49 @@
+# Header
+
+# Copyright 1999-2005 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+# $Header: $
+
+inherit eutils bash-completion flag-o-matic
+
+DESCRIPTION="A nice command line todo list for developers"
+HOMEPAGE="http://swapoff.org/DevTodo"
+SRC_URI="http://swapoff.org/files/${PN}/${P}.tar.gz"
+
+LICENSE="GPL-2"
+SLOT="0"
+KEYWORDS="alpha amd64 arm hppa ia64 mips ppc s390 sparc x86 ppc64"
+IUSE=""
+
+RDEPEND=">=sys-libs/ncurses-5.2
+ >=sys-libs/readline-4.1"
+DEPEND="${RDEPEND}"
+
+src_unpack() {
+ unpack ${A}
+ cd ${S}
+ epatch ${FILESDIR}/${P}-gentoo.diff
+}
+
+src_compile() {
+ einfo "Running autoreconf"
+ autoreconf -f -i || die "autoreconf failed"
+ replace-flags -O? -O1
+ econf --sysconfdir=/etc/devtodo || die "econf failed"
+ emake || die "emake failed"
+}
+
+src_install() {
+ make DESTDIR=${D} install || die "make install failed"
+ dodoc AUTHORS ChangeLog QuickStart README TODO doc/scripts.sh \
+ doc/scripts.tcsh doc/todorc.example contrib/tdrec || die "dodoc failed"
+ dobashcompletion ${FILESDIR}/${PN}.bash-completion ${PN}
+}
+
+pkg_postinst() {
+ echo
+ einfo "Because of a conflict with app-misc/tdl, the tdl symbolic link"
+ einfo "and manual page have been removed."
+ bash-completion_pkg_postinst
+}
+
diff --git a/ebuild-writing/using-eclasses/text.rst b/ebuild-writing/using-eclasses/text.rst
new file mode 100644
index 0000000..b8abf7d
--- /dev/null
+++ b/ebuild-writing/using-eclasses/text.rst
@@ -0,0 +1,33 @@
+Using Eclassses
+===============
+
+An eclass is a collection (library) of functions or functionality that is shared
+between packages. See `Eclass Writing Guide`_ for the full story on what
+eclasses can do, how they work and how to write them, and `Eclass Reference`_
+for documentation on various commonly used eclasses. This section only explains
+how to use an eclass which has already been written.
+
+The ``inherit`` Function
+------------------------
+
+To use an eclass, it must be 'inherited'. This is done via the ``inherit``
+function, which is provided by ``ebuild.sh``. The ``inherit`` statement must
+come at the top of the ebuild, *before* any functions. Conditional inherits are
+illegal (except where the inheritance criteria are cache-constant -- see `The
+Portage Cache`_).
+
+After inheriting an eclass, its provided functions can be used as normal. Here's
+``devtodo-0.1.18-r2.ebuild``, which uses three eclasses:
+
+.. CODESAMPLE devtodo.ebuild
+
+Note the ``inherit`` immediately after the header.
+
+The ``eutils`` eclass (see `eutils.eclass Reference`_) is needed to get the
+``epatch`` function. The ``flag-o-matic`` eclass (see `flag-o-matic.eclass
+Reference`_) is needed for ``replace-flags``, and the ``bash-completion`` eclass
+(`bash-completion.eclass Reference`_) is used to handle the bash completion file
+via ``dobashcompletion`` and ``bash-completion_pkg_postinst``.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/ebuild-writing/variables/text.rst b/ebuild-writing/variables/text.rst
new file mode 100644
index 0000000..1d6c06c
--- /dev/null
+++ b/ebuild-writing/variables/text.rst
@@ -0,0 +1,187 @@
+Variables
+=========
+
+There are a number of special variables which must be set in ebuilds, and many
+more which can optionally be specified. There are also some predefined variables
+which are of use throughout the ebuild.
+
+Predefined Read-Only Variables
+------------------------------
+
+The following variables are defined for you. You must not attempt to set
+them.
+
+============= =======================================================
+Variable Purpose
+============= =======================================================
+``P`` Package name and version (excluding revision, if any), for example ``vim-6.3``
+``PN`` Package name, for example ``vim``
+``PV`` Package version (excluding revision, if any), for example ``6.3``
+``PR`` Package revision, or ``r0`` if no revision exists.
+``PVR`` Package version and revision, for example ``6.3-r0``, ``6.3-r1``.
+``PF`` Package name, version and revision, for example
+ ``vim-6.3-r1``
+``A`` All the source files for the package (excluding those
+ which are not available because of ``USE`` flags)
+``CATEGORY`` Package's category, for example ``app-editors``.
+``FILESDIR`` Path to the ebuild's ``files/`` directory, commonly used
+ for small patches and files. Value:
+ ``"${PORTDIR}/${CATEGORY}/${PN}/files"``.
+``WORKDIR`` Path to the ebuild's root build directory. Value:
+ ``"${PORTAGE_TMPDIR}/portage/${PF}/work"``.
+``T`` Path to a temporary directory which may be used by the
+ ebuild. Value: ``"${PORTAGE_TMPDIR}/portage/${PF}/temp"``
+``D`` Path to the temporary install directory. Value:
+ ``"${PORTAGE_TMPDIR}/portage/${PF}/image"``
+``ROOT`` Path to the root directory. When not using ``${D}``,
+ always prepend ``${ROOT}`` to the path.
+============= =======================================================
+
+Required Variables
+------------------
+
+The following variables must be defined by every ebuild.
+
+====================== =======================================================
+Variable Purpose
+====================== =======================================================
+``DESCRIPTION`` A short (less than 80 characters) description of the
+ package's purpose.
+``SRC_URI`` A list of source URIs for the package. Can contain
+ ``USE``-conditional parts, see `SRC_URI`_.
+``HOMEPAGE`` Package's homepage
+``KEYWORDS`` See `KEYWORDS`_ and `Keywording`_.
+``SLOT`` The package's ``SLOT``. See `SLOT`_.
+``LICENSE`` The package's licence, corresponding exactly (including
+ case) to a file in ``licenses/``. See `LICENSE`_.
+``IUSE`` A list of all ``USE`` flags (excluding arch and auto
+ expand flags) used within the ebuild. See `IUSE`_.
+====================== =======================================================
+
+Optional Variables
+------------------
+
+Specifying the following variables is optional:
+
+====================== =======================================================
+Variable Purpose
+====================== =======================================================
+``S`` Path to the temporary build directory, used by
+ ``src_compile`` and ``src_install``. Default:
+ ``"${WORKDIR}/${P}"``. Ebuilds should **not** provide a
+ value for this ebuild if it is the default.
+``DEPEND`` A list of the package's build dependencies. See
+ `Dependencies`_.
+``RDEPEND`` A list of the package's runtime dependencies. See
+ `Dependencies`_.
+``PDEPEND`` A list of packages to be installed after the package
+ is merged. Should only be used where ``RDEPEND`` is not
+ possible. See `Dependencies`_.
+``RESTRICT`` A space-delimited list of portage features to restrict.
+ Valid values are ``nostrip``, ``nomirror``, ``nouserpriv``
+ and ``fetch``. See `ebuild-5`_ for details.
+``PROVIDE`` Any virtuals provided by this package, for example
+ ``"virtual/editor virtual/emacs"``.
+====================== =======================================================
+
+SLOT
+----
+
+When slots are not needed, use ``SLOT="0"``. Do **not** use ``SLOT=""``, as
+this will disable slotting for this package.
+
+KEYWORDS
+--------
+
+The only valid construct involving a ``*`` inside ``KEYWORDS`` is a ``-*``. Do
+**not** use ``KEYWORDS="*"`` or ``KEYWORDS="~*"``.
+
+See `Keywording`_ for how to handle this variable.
+
+SRC_URI
+-------
+
+Conditional Sources
+'''''''''''''''''''
+
+Conditional source files based upon USE flags are allowed using the usual
+``flag? ( )`` syntax. This is often useful for arch-specific code or for binary
+packages -- downloading sparc binaries on ppc would be a waste of bandwidth.
+
+.. CODESAMPLE variables-1.ebuild
+
+When creating digests it may be necessary to have *all* SRC_URI components
+downloaded. If you have ``FEATURES="cvs"`` set, portage should get this right,
+although you may end up downloading more than necessary.
+
+If a ``USE_EXPAND`` variable is used to control whether certain optional
+components are installed, the correct thing to do if the variable is unset is
+generally to install *all* available components.
+
+.. CODESAMPLE variables-2.ebuild
+
+IUSE
+----
+
+Note that the ``IUSE`` variable is cumulative, so there is no need to specify
+USE flags used only within inherited eclasses within the ebuild's IUSE. Also
+note that it's really really broken in portage versions before 2.0.51.
+
+Arch USE flags (``sparc``, ``mips``, ``x86-fbsd`` and so on) should not be
+listed. Neither should auto-expand flags (``linguas_en`` and so on).
+
+LICENSE
+-------
+
+It is possible to specify multiple ``LICENSE`` entries, and entries which only
+apply if a particular ``USE`` flag is set. The format is the same as for
+``DEPEND``. See `GLEP 23`_ for details.
+
+Version Formatting Issues
+-------------------------
+
+Often upstream's tarball versioning format doesn't quite follow Gentoo
+conventions. Differences in how underscores and hyphens are used are
+particularly common. For example, what Gentoo calls ``foo-1.2.3b`` may be
+expecting a tarball named ``foo-1.2-3b.tar.bz2``. Rather than hard coding version
+numbers, it is preferable to make a ``MY_PV`` variable and use that. The easy
+way to do this, which should be used unless you are sure you know what you are
+doing, is to use the ``versionator`` eclass:
+
+.. CODESAMPLE variables-3.ebuild
+
+This code has the advantage that it will carry on working even if upstream
+switches to a format like ``foo-1.3-4.5.tar.bz2`` (yes, this really happens).
+
+It is also possible to use bash substitution to achieve the same effect (this is
+how versionator works internally), but this is complicated, error prone and hard
+to read.
+
+Some ebuilds use calls to ``sed``, ``awk`` and / or ``cut`` to do this. This
+must *not* be done for any new code, and should be fixed to use either
+versionator or bash substitution where possible. Global scope non-bash code is
+highly discouraged.
+
+The ``versionator`` eclass can also be used to extract particular components
+from a version string. See `versionator.eclass-5`_ and the eclass source code
+for further documentation and examples. A brief summary of the functions
+follows.
+
+==================================== ========================================
+Function Purpose
+==================================== ========================================
+``get_all_version_components`` Split up a version string into its
+ component parts.
+``get_version_components`` Get important version components,
+ excluding '.', '-' and '_'.
+``get_major_version`` Get the major version.
+``get_version_component_range`` Extract a range of subparts from a version
+ string
+``get_after_major_version`` Get everything after the major version.
+``replace_version_separator`` Replace a particular version separator.
+``replace_all_version_separators`` Replace all version separators.
+``delete_version_separator`` Delete a version separator.
+``delete_all_version_separators`` Delete all version separators.
+==================================== ========================================
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/ebuild-writing/variables/variables-1.ebuild b/ebuild-writing/variables/variables-1.ebuild
new file mode 100644
index 0000000..c396d3e
--- /dev/null
+++ b/ebuild-writing/variables/variables-1.ebuild
@@ -0,0 +1,7 @@
+# Headers
+
+SRC_URI="http://example.com/files/${P}-core.tar.bz2
+ x86? ( http://example.com/files/${P}/${P}-sse-asm.tar.bz2 )
+ ppc? ( http://example.com/files/${P}/${P}-vmx-asm.tar.bz2 )
+ sparc? ( http://example.com/files/${P}/${P}-vis-asm.tar.bz2 )
+ doc? ( http://example.com/files/${P}/${P}-docs.tar.bz2 )"
diff --git a/ebuild-writing/variables/variables-2.ebuild b/ebuild-writing/variables/variables-2.ebuild
new file mode 100644
index 0000000..b7b2560
--- /dev/null
+++ b/ebuild-writing/variables/variables-2.ebuild
@@ -0,0 +1,10 @@
+# Headers
+
+SRC_URI="http://example.com/files/${P}-core.tar.bz2
+ examplecards_foo? ( http://example.com/files/${P}-foo.tar.bz2 )
+ examplecards_bar? ( http://example.com/files/${P}-bar.tar.bz2 )
+ examplecards_baz? ( http://example.com/files/${P}-baz.tar.bz2 )
+ !examplecards_foo? ( !examplecards_bar? ( !examplecards_baz? (
+ http://example.com/files/${P}-foo.tar.bz2
+ http://example.com/files/${P}-bar.tar.bz2
+ http://example.com/files/${P}-baz.tar.bz2 ) ) )"
diff --git a/ebuild-writing/variables/variables-3.ebuild b/ebuild-writing/variables/variables-3.ebuild
new file mode 100644
index 0000000..0927589
--- /dev/null
+++ b/ebuild-writing/variables/variables-3.ebuild
@@ -0,0 +1,4 @@
+# Headers
+
+inherit versionator
+MY_PV=$(replace_version_separator 2 '-')
diff --git a/eclass-reference/bash-completion.eclass/text.rst b/eclass-reference/bash-completion.eclass/text.rst
new file mode 100644
index 0000000..1563e31
--- /dev/null
+++ b/eclass-reference/bash-completion.eclass/text.rst
@@ -0,0 +1,25 @@
+``bash-completion.eclass`` Reference
+====================================
+
+The ``bash-completion`` eclass provides functions for installing contributed
+bash-completion scripts. See `Completion Files`_ for how to write completion
+scripts.
+
+================================= ======================================================
+Function Details
+================================= ======================================================
+``dobashcompletion`` Install a bash completion file if and only if
+ the user has ``USE="bash-completion"``. If
+ ``BASH_COMPLETION_NAME`` is set, this will be used for
+ deciding the application name. Otherwise, the second
+ argument will be used (if present), or failing that,
+ ``${PN}``.
+``bash-completion_pkg_postinst`` If the user has ``USE="bash-completion"``,
+ displays a message explaining how to activate
+ the completion for this package.
+================================= ======================================================
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
+
+
diff --git a/eclass-reference/eutils.eclass/text.rst b/eclass-reference/eutils.eclass/text.rst
new file mode 100644
index 0000000..fc17c9b
--- /dev/null
+++ b/eclass-reference/eutils.eclass/text.rst
@@ -0,0 +1,46 @@
+``eutils.eclass`` Reference
+===========================
+
+The ``eutils`` eclass provides various useful functions. For full documentation,
+see `eutils.eclass-5`_.
+
+========================= ======================================================
+Function Details
+========================= ======================================================
+``epause`` See `Message Functions Reference`_ and `Messages`_
+``ebeep`` See `Message Functions Reference`_ and `Messages`_
+``gen_usr_ldscript`` Generate a linker script in ``/usr/lib`` for dynamic
+ libraries in ``/lib``
+``draw_line`` Draw a line the same length as the arguments. Do not
+ use this for messages.
+``epatch`` Apply a patch (see `eutils.eclass-5`_ and `Patching
+ with epatch`_).
+``have_NPTL`` True if we are using NPTL (threads).
+``get_number_of_jobs`` Try to get the number of jobs to use when compiling.
+``emktemp`` Replacement for ``mktemp``.
+``egetent`` Wrapper for ``getent``.
+``enewuser`` See `Users and Groups`_.
+``enewgroup`` See `Users and Groups`_.
+``edos2unix`` Fix one or more files to use Unix line endings.
+``make_desktop_entry`` Create a ``.desktop`` file. Args are the binary,
+ the name, the icon, the application type and the startup
+ path.
+``make_session_desktop`` Create a GDM session file. Arguments are the title and
+ the command.
+``domenu`` Install a menu file.
+``doicon`` Install an icon file.
+``check_license`` Display a licence for the user to accept. Argument is
+ the licence to use.
+``cdrom_get_cds`` See `eutils.eclass-5`_.
+``cdrom_load_next_cd`` See `eutils.eclass-5`_.
+``strip-linguas`` Make sure ``LINGUAS`` contains only allowed values.
+ See `Linguas`_.
+``built_with_use`` Check that a package was built with a given USE flag
+ enabled.
+``dopamd`` Install a pam auth config file.
+``newpamd`` Install a pam auth config file (two arg version).
+========================= ======================================================
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
+
diff --git a/eclass-reference/fdo-mime.eclass/text.rst b/eclass-reference/fdo-mime.eclass/text.rst
new file mode 100644
index 0000000..1d8a1a0
--- /dev/null
+++ b/eclass-reference/fdo-mime.eclass/text.rst
@@ -0,0 +1,16 @@
+``fdo-mime.eclass`` Reference
+=============================
+
+The ``fdo-mime`` eclass provides functions for working with the FreeDesktop MIME
+database.
+
+===================================== ===========================================
+Function Details
+===================================== ===========================================
+``fdo-mime_desktop_database_update`` Updates the desktop database. Should be
+ called after modifying desktop entries.
+``fdo-mime_mime_database_update`` Updates the MIME database. Should be
+ called after modifying MIME entries.
+===================================== ===========================================
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/eclass-reference/flag-o-matic.eclass/text.rst b/eclass-reference/flag-o-matic.eclass/text.rst
new file mode 100644
index 0000000..cbecc27
--- /dev/null
+++ b/eclass-reference/flag-o-matic.eclass/text.rst
@@ -0,0 +1,40 @@
+``flag-o-matic.eclass`` Reference
+=================================
+
+The ``flag-o-matic`` eclass provides functions for manipulating ``CFLAGS``,
+``CXXFLAGS``, ``LDFLAGS`` and similar. See `Configuring Build Environment`_ for
+examples.
+
+========================================== ====================================
+Function Details
+========================================== ====================================
+``filter-flags <flags>`` Removes any occurances of ``flags``
+ in ``CFLAGS``, ``CXXFLAGS``
+``append-flags <flags>`` Appends ``flags`` to ``CFLAGS`` and
+ ``CXXFLAGS``
+``replace-flags <orig.flag> <new.flag>`` Replaces ``orig.flag`` (if present)
+ with ``new.flag`` in ``CFLAGS``
+ and ``CXXFLAGS``
+``replace-cpu-flags <old.cpus> <new.cpu>`` Replaces ``-mtune=``, ``-mcpu=`` and
+ ``-march=`` flags with any of
+ ``old.cpus`` with ``new.cpu`` in
+ ``CFLAGS`` and ``CXXFLAGS``
+``is-flag <flag>`` Tests whether ``flag`` is a valid
+ flag with the current compiler
+``strip-flags`` Removes all non-safe flags from
+ ``CFLAGS`` and ``CXXFLAGS``
+``strip-unsupported-flags`` Removes any flags in ``CFLAGS`` and
+ `CXXFLAGS`` which are not supported
+ by the active compiler
+``get-flag <flag>`` Finds and echoes the value of the
+ specified flag
+``filter-mfpmath <math types>`` Removes the specified maths types
+ from the fpmath specification (if
+ present) in ``CFLAGS`` and ``CXXFLAGS``
+``append-ldflags`` Appends the specified flags to ``LDFLAGS``
+``filter-ldflags <flags>`` Remove the specified flags (if
+ present) from ``LDFLAGS``
+========================================== ====================================
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/eclass-reference/rpm.eclass/text.rst b/eclass-reference/rpm.eclass/text.rst
new file mode 100644
index 0000000..421b1c3
--- /dev/null
+++ b/eclass-reference/rpm.eclass/text.rst
@@ -0,0 +1,31 @@
+``rpm.eclass`` Reference
+========================
+
+The ``rpm`` eclass provides RPM unpacking services for packages that must
+extract a source tarball from an RPM.
+
+``rpm.eclass`` Variables
+------------------------
+
+======================== ======================================================
+Variables Details
+======================== ======================================================
+``USE_RPMOFFSET_ONLY`` ``rpm_unpack`` normally will use rpm2cpio over
+ rpmoffset if both exist. If this variable is set to
+ 1, ``rpm_unpack`` will use rpmoffset.
+======================== ======================================================
+
+``rpm.eclass`` Functions
+------------------------
+
+======================== ======================================================
+Functions Details
+======================== ======================================================
+``rpm_unpack`` *<file>* Unpacks an RPM. Behaves in the same fashion as
+ ``unpack`` (see `Unpacking Tarballs`_).
+``rpm_src_unpack`` Default ``src_unpack`` that loops through ``${A}``
+ calling ``rpm_unpack`` for RPM's and ``unpack`` for
+ everything else.
+======================== ======================================================
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/eclass-reference/subversion.eclass/text.rst b/eclass-reference/subversion.eclass/text.rst
new file mode 100644
index 0000000..b681f71
--- /dev/null
+++ b/eclass-reference/subversion.eclass/text.rst
@@ -0,0 +1,51 @@
+``subversion.eclass`` Reference
+===============================
+
+The ``subversion`` eclass provides functions that enable the ebuild author to
+create 'live' ebuilds that fetch the program's sources from a subversion
+repository.
+
+See `Subversion Sources`_ for an introduction.
+
+``subversion.eclass`` Variables
+-------------------------------
+
+==================== ====================================================
+Variables Details
+==================== ====================================================
+``ESVN_REPO_URI`` URI from which the sources will be fetched. Valid
+ protocols: http, https, and svn. At a minimum, this
+ variable *must* be set.
+``ESVN_STORE_DIR`` Location fetched sources will be kept. Defaults to
+ ``${DISTDIR}/svn-src``.
+``ESVN_FETCH_CMD`` Command used for initial checkout. Defaults to
+ ``svn checkout``.
+``ESVN_UPDATE_CMD`` Command used for updating sources. Defaults to
+ ``svn update``.
+``ESVN_PROJECT`` Name of the project. Defaults to ``${PN/-svn}``.
+``ESVN_BOOTSTRAP`` Name of bootstrap script. This variable is empty by
+ default. './' is automatically prepended.
+``ESVN_PATCHES`` List of patches to apply prior to fetching the
+ sources. In addition to literal filenames, you may
+ also use globbing such as \*.diff. This variable is
+ empty by default.
+==================== ====================================================
+
+``subversion.eclass`` Functions
+-------------------------------
+
+========================== ==============================================
+Functions Details
+========================== ==============================================
+``subversion_src_unpack`` The default ``src_unpack`` that runs
+ ``subversion_svn_fetch`` and
+ ``subversion_bootstrap``.
+``subversion_svn_fetch`` Fetches the program's sources from the URI
+ specified by ``ESVN_REPO_URI`` and copies to
+ ``${S}``.
+``subversion_bootstrap`` Applies any patches specified by
+ ``ESVN_PATCHES`` and executes the bootstrap
+ script specified by ``ESVN_BOOTSTRAP``.
+========================== ==============================================
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/eclass-reference/text.rst b/eclass-reference/text.rst
new file mode 100644
index 0000000..4ebc342
--- /dev/null
+++ b/eclass-reference/text.rst
@@ -0,0 +1,10 @@
+Eclass Reference
+================
+
+This section provides a reference for some of the more commonly used eclasses.
+Note that most eclasses have an accompanying manual page -- see `Manual Pages`_.
+
+.. CHILDLIST
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/eclass-writing/eclass-writing-1.ebuild b/eclass-writing/eclass-writing-1.ebuild
new file mode 100644
index 0000000..7954c32
--- /dev/null
+++ b/eclass-writing/eclass-writing-1.ebuild
@@ -0,0 +1,26 @@
+# Headers.
+
+# Copyright 1999-2005 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+# $Header: $
+
+#
+# Original Author: Ciaran McCreesh <ciaranm@gentoo.org>
+# Purpose: install macos .app files to the relevant location.
+#
+# Bugs to osx@gentoo.org
+#
+
+ECLASS="macos-app"
+INHERITED="$INHERITED $ECLASS"
+
+# domacosapp: install a macos .app file. Usage is 'domacosapp file' or
+# 'domacosapp file newfile'.
+
+domacosapp() {
+ [[ -z "${1}" ]] && die "usage: domacosapp <file> <new file>"
+ if useq ppc-macos ; then
+ insinto /Applications
+ newins "$1" "${2:-${1}}" || die "Failed to install ${1}"
+ fi
+}
diff --git a/eclass-writing/eclass-writing-2.ebuild b/eclass-writing/eclass-writing-2.ebuild
new file mode 100644
index 0000000..3d742ff
--- /dev/null
+++ b/eclass-writing/eclass-writing-2.ebuild
@@ -0,0 +1,9 @@
+# Headers.
+
+ECLASS="fnord"
+INHERITED="$INHERITED $ECLASS"
+EXPORT_FUNCTIONS src_compile
+
+fnord_src_compile() {
+ do_stuff || die
+}
diff --git a/eclass-writing/eclass-writing-3.ebuild b/eclass-writing/eclass-writing-3.ebuild
new file mode 100644
index 0000000..0935dfe
--- /dev/null
+++ b/eclass-writing/eclass-writing-3.ebuild
@@ -0,0 +1,9 @@
+# Headers.
+
+inherit fnord.eclass
+
+src_compile() {
+ do_pre_stuff || die
+ fnord_src_compile
+ do_post_stuff || die
+}
diff --git a/eclass-writing/eclass-writing-4.ebuild b/eclass-writing/eclass-writing-4.ebuild
new file mode 100644
index 0000000..df10d0c
--- /dev/null
+++ b/eclass-writing/eclass-writing-4.ebuild
@@ -0,0 +1,28 @@
+# Headers.
+
+# Copyright 1999-2005 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+# $Header: $
+
+# Original Author: Ciaran McCreesh <ciaranm@gentoo.org>
+# Purpose: Demonstration of EXPORT_FUNCTIONS. Defines simple wrappers for the
+# (hypothetical) 'jmake' build system and a default src_compile.
+
+ECLASS="jmake"
+INHERITED="$INHERITED $ECLASS"
+EXPORT_FUNCTIONS src_compile
+
+DEPEND=">=sys-devel/jmake-2"
+
+jmake-configure() {
+ jmake configure --prefix=/usr "$@"
+}
+
+jmake-build() {
+ jmake dep && jmake build "$@"
+}
+
+jmake_src_compile() {
+ jmake-configure || die "configure failed"
+ jmake-build || die "build failed"
+}
diff --git a/eclass-writing/text.rst b/eclass-writing/text.rst
new file mode 100644
index 0000000..8990522
--- /dev/null
+++ b/eclass-writing/text.rst
@@ -0,0 +1,125 @@
+Eclass Writing Guide
+====================
+
+This section provides a brief introduction to eclass authoring.
+
+.. Important:: You should reread the `Overlay and Eclasses`_ and `The Portage
+ Cache`_ sections before continuing.
+
+Purpose of Eclasses
+-------------------
+
+An eclass is a collection of code which can be used by more than one ebuild. At
+the time of writing, all eclasses live in the ``eclass/`` directory in the tree.
+Roughly speaking, there are three kinds of eclass:
+
+* Those which provide common functions which are used by many ebuilds (for
+ example, ``eutils``, ``versionator``, ``cvs``, ``bash-completion``)
+* Those which provide a basic build system for many similar packages (for
+ example, ``vim-plugin``, ``kde``)
+* Those which handle one or a small number of packages with complex build
+ systems (for example, ``vim``, ``toolchain``, ``kernel-2``)
+
+Adding and Updating Eclasses
+----------------------------
+
+Before committing a new eclass to the tree, it should be emailed to the
+gentoo-dev mailing list with a justification and a proposed implementation. Do
+not skip this step -- sometimes a better implementation or an alternative which
+does not require a new eclass will be suggested.
+
+Before updating ``eutils`` or a similar widely used eclass, it is best to email
+the gentoo-dev list. It may be that your proposed change is broken in a way you
+had not anticipated, or that there is an existing function which performs the
+same purpose, or that your function may be better off in its own eclass. If you
+don't email gentoo-dev first, and end up breaking something, expect to be in a
+lot of trouble.
+
+If there is an existing maintainer for an eclass (this is usually the case), you
+**must** talk to the maintainer before committing any changes.
+
+It is not usually necessary to email the gentoo-dev list before making changes
+to a non-general eclass which you maintain. Use common sense here.
+
+.. Warning:: Committing a broken eclass can kill huge numbers of packages. Since
+ ``repoman`` is not eclass-aware, be very sure you do proper testing.
+
+A simple way to verify syntax is ``bash -n foo.eclass``.
+
+Eclasses must **not** be removed from the tree, even if they are no longer used,
+as this will cause problems for users who have installed packages which used the
+eclass in question.
+
+Basic Eclass Format
+-------------------
+
+An eclass is a ``bash`` script which is sourced within the ebuild environment.
+Files should be a simple text file with a ``.eclass`` extension. Allowed
+characters in the filename are lowercase letters, the digits 0-9, hyphens,
+underscores and dots. Eclasses are not intrinsically versioned.
+
+Eclasses should start with the standard ebuild header, along with comments
+explaining the maintainer and purpose of the eclass, and any other relevant
+documentation.
+
+Eclass Variables
+----------------
+
+All eclasses must define two top level variables, ``ECLASS`` and ``INHERITED``.
+The ``ECLASS`` variable must be set to the name of the eclass (without the
+``.eclass`` suffix), and ``INHERITED`` must be set to ``"$INHERITED $ECLASS"``.
+
+Other top level variables may be defined as for ebuilds. If any USE flags are
+used, ``IUSE`` must be set. The ``KEYWORDS`` variable must **not** be set in an
+eclass.
+
+Eclass Functions
+----------------
+
+Eclasses may define functions. These functions will be visible to anything which
+inherits the eclass.
+
+Simple Common Functions Eclass Example
+--------------------------------------
+
+As an example, the following eclass was written to illustrate a better way of
+installing OSX application files during a discussion on this subject. It defines
+a single function, ``domacosapp``.
+
+.. CODESAMPLE eclass-writing-1.ebuild
+
+Export Functions
+----------------
+
+An eclass may provide default implementations for any of the standard ebuild
+functions (``src_unpack``, ``pkg_postinst`` etc). This can be done either as a
+simple function definition (which is not multiple eclass friendly) or using
+``EXPORT_FUNCTIONS``. Functions given to ``EXPORT_FUNCTIONS`` are implemented
+as normal, but have their name prefixed with ``${ECLASS}_``.
+
+Important: Only 'standard' functions should be specified in
+``EXPORT_FUNCTIONS``.
+
+.. Note:: ``EXPORT_FUNCTIONS`` is a function, *not* a variable.
+
+If multiple eclasses export the same function, the latest (inherited last)
+defined version wins. If an ebuild defines a function that is exported, this
+gets priority over any eclass version. This can be used to override
+eclass-defined defaults -- for example, say we had ``fnord.eclass``:
+
+.. CODESAMPLE eclass-writing-2.ebuild
+
+Then an ebuild could do this:
+
+.. CODESAMPLE eclass-writing-3.ebuild
+
+Simple Build System Eclass Example
+----------------------------------
+
+A simple eclass which defines a number of functions and a default
+``src_compile`` for the (hypothetical) ``jmake`` build system might look
+something like the following:
+
+.. CODESAMPLE eclass-writing-4.ebuild
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/function-reference/build-functions/text.rst b/function-reference/build-functions/text.rst
new file mode 100644
index 0000000..f6c68f9
--- /dev/null
+++ b/function-reference/build-functions/text.rst
@@ -0,0 +1,18 @@
+Build Functions Reference
+=========================
+
+The following functions, which are all provided by ``ebuild.sh``, are useful
+during the unpack and compile stages.
+
+====================== ======================================================
+Function Details
+====================== ======================================================
+``unpack archives`` Unpack the specified archives.
+``econf args`` Wrapper for ``./configure``. Passes on all ``args``.
+``emake args`` Wrapper for ``make``. Passes on all ``args``.
+``einstall args`` Wrapper for ``make install``, only to be used if ``make
+ DESTDIR="${D}"`` is unsuitable.
+====================== ======================================================
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/function-reference/install-functions/text.rst b/function-reference/install-functions/text.rst
new file mode 100644
index 0000000..fedb788
--- /dev/null
+++ b/function-reference/install-functions/text.rst
@@ -0,0 +1,70 @@
+Install Functions Reference
+===========================
+
+The following functions, which are all provided ``ebuild.sh`` and the standard
+library, handle various install-related tasks. ``${D}`` is automatically handled
+for all of these functions.
+
+============== ======================================================
+Function Details
+============== ======================================================
+``insinto`` Change install location for ``doins``, ``newins`` etc
+``exeinto`` Change install location for ``doexe``, ``newexe`` etc
+``docinto`` Change install location for ``dodoc``, ``newdoc`` etc
+``insopts`` Specify arguments passed to ``install`` (eg ``-s``, ``-m644``).
+``diropts`` Specify arguments passed to ``install`` for directories
+``exeopts`` Specify arguments passed to ``install`` for executables
+``libopts`` Specify arguments passed to ``install`` for libraries
+``dobin`` Install a binary
+``doconfd`` Install an ``/etc/conf.d`` file
+``dodir`` Install a directory
+``dodoc`` Install a documentation file
+``doenvd`` Install an ``/etc/env.d`` file
+``doexe`` Install an executable
+``dohard`` Create a hardlink to the first argument from the second argument
+``dohtml`` Install an HTML documentation file
+``doinfo`` Install a GNU Info document
+``doinitd`` Install an ``/etc/init.d`` file
+``doins`` Install a miscellaneous file
+``dojar`` Install a ``.jar`` file
+``dolib`` Install a library file
+``dolib.a`` Install a library (``.a``) file
+``dolib.so`` Install a library (shared object) file
+``doman`` Install a man page
+``domo`` Install a Gettext ``.mo`` file
+``dopython`` Install a Python file
+``dosbin`` Install an ``sbin/`` file
+``dosym`` Create a symlink from the second parameter to the first
+ parameter
+``fowners`` Call ``chown`` with the first argument as the mode on all
+ additional arguments.
+``fperms`` Call ``chown`` with the first argument as the user on all
+ additional arguments.
+``keepdir`` Create a directory with an empty ``.keep`` file in it.
+``newbin`` Install a binary using the second argument as the name.
+``newconfd`` Install an ``/etc/conf.d`` entry using the second argument as the
+ name.
+``newdoc`` Install a documentation file using the second argument as the
+ name.
+``newenvd`` Install an ``/etc/env.d`` file using the second argument as the
+ name.
+``newexe`` Install an executable file using the second argument as the name.
+``newinitd`` Install an ``/etc/init.d`` file using the second argument as the
+ name.
+``newins`` Install a miscellaneous file using the second argument as the
+ name.
+``newlib.a`` Install a ``.a`` library file using the second argument as the
+ name.
+``newlib.so`` Install a ``.so`` library file using the second argument as the
+ name.
+``newman`` Install a manual page using the second argument as the name.
+``newsbin`` Install an ``sbin`` file using the second argument as the name.
+============== ======================================================
+
+The ``do*`` functions, when given multiple arguments, will work upon multiple
+targets. The ``new*`` functions take exactly two arguments (except as noted) --
+the first is the source name, the second the name to use when installing.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
+
diff --git a/function-reference/message-functions/text.rst b/function-reference/message-functions/text.rst
new file mode 100644
index 0000000..8c56778
--- /dev/null
+++ b/function-reference/message-functions/text.rst
@@ -0,0 +1,34 @@
+Message Functions Reference
+===========================
+
+The following functions, which are provided by ``functions.sh``, can be used for
+displaying informational messages.
+
+====================== ======================================================
+Function Details
+====================== ======================================================
+``einfo`` Display an informational message.
+``einfon`` Display an informational message with no trailing
+ newline.
+``ewarn`` Display a warning message.
+``eerror`` Display an error message.
+``ebegin`` Display the message for the start of an action block.
+``eend`` Display the end of an action block.
+====================== ======================================================
+
+The following are available from ``eutils.eclass``:
+
+====================== ======================================================
+Function Details
+====================== ======================================================
+``epause`` Pause for the specified number (must be a positive
+ integer) of seconds. Defaults to a sane value.
+``ebeep`` Beep the specified number (must be a positive integer) of
+ times. Defaults to a sane value.
+====================== ======================================================
+
+See `Messages`_ for a detailed discussion.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
+
diff --git a/function-reference/query-functions/text.rst b/function-reference/query-functions/text.rst
new file mode 100644
index 0000000..d22cac5
--- /dev/null
+++ b/function-reference/query-functions/text.rst
@@ -0,0 +1,31 @@
+Query Functions Reference
+=========================
+
+The following functions, which are provided by ``ebuild.sh``, can be used to
+query variables and similar state.
+
+======================= ======================================================
+Function Details
+======================= ======================================================
+``use flagname`` Returns a true value if and only if ``flagname`` is
+ included in ``USE``
+``useq flagname`` As ``use``, guaranteed to produce no output.
+``usev flagname`` As ``use``, echoes ``flagname`` upon success.
+``use_enable flag str`` Echoes either ``--enable-str`` or ``--disable-str``
+ depending upon ``useq flag``. If ``str`` is not
+ specified, uses ``flag`` instead.
+``use_with flag str`` As ``use_enable``, but ``--with-`` or ``without-``.
+``has flag string`` Returns true if ``flag`` is included in the flag list
+ ``string`` (example: ``if has ccache $FEATURES ; then``).
+``hasq flag string`` As ``has``, guaranteed quiet.
+``hasv flag string`` As ``has``, echoes ``flag`` on success.
+``portageq`` Wrapper for ``portageq``
+``best_version pkg`` Echoes the 'best' version of ``pkg`` which is currently
+ installed.
+``has_version pkg`` True if ``pkg`` (can include version specifiers) is
+ installed.
+======================= ======================================================
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
+
diff --git a/function-reference/sandbox-functions/text.rst b/function-reference/sandbox-functions/text.rst
new file mode 100644
index 0000000..7fea370
--- /dev/null
+++ b/function-reference/sandbox-functions/text.rst
@@ -0,0 +1,31 @@
+Sandbox Functions Reference
+===========================
+
+The following functions, which are all provided by ``ebuild.sh``, handle working
+with the sandbox.
+
+====================== ======================================================
+Function Details
+====================== ======================================================
+``addread`` Add one single additional item to the sandbox allowed
+ read list.
+``addwrite`` Add one single additional item to the sandbox allowed
+ write list. **Note**: If at all possible, use
+ ``addpredict`` instead. Using ``addwrite`` is **not** an
+ appropriate alternative to making your package build
+ sandbox-friendly.
+``adddeny`` Add one single additional item to the sandbox deny write
+ list.
+``addpredict`` Add one single additional item to the sandbox predict
+ (pretend to allow write) list.
+====================== ======================================================
+
+None of these functions accept multiple arguments in one call. The sandbox is
+recursive, so to allow predicted writes to ``/foo/bar`` and ``/foo/baz``,
+``addpredict /foo`` would be sufficient.
+
+See `Sandbox`_ for details on how the sandbox works. See `Handling Access
+Violations`_ for how to handle sandbox-related build problems.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/function-reference/text.rst b/function-reference/text.rst
new file mode 100644
index 0000000..da0d663
--- /dev/null
+++ b/function-reference/text.rst
@@ -0,0 +1,9 @@
+Function Reference
+==================
+
+The following functions are available for use in ebuilds:
+
+.. CHILDLIST
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/general-concepts/autotools/aclocal-1.ebuild b/general-concepts/autotools/aclocal-1.ebuild
new file mode 100644
index 0000000..c23a5a1
--- /dev/null
+++ b/general-concepts/autotools/aclocal-1.ebuild
@@ -0,0 +1,6 @@
+# vim: set ft=ebuild
+
+einfo "Regenerating autotools files..."
+cp ${WORKDIR}/gentoo-m4 ${S}/m4 || die "m4 copy failed"
+WANT_AUTOCONF="2.5" aclocal -I ${S}/m4 || die "aclocal failed"
+WANT_AUTOCONF="2.5" autoconf || die "autoconf failed"
diff --git a/general-concepts/autotools/aclocal-1.txt b/general-concepts/autotools/aclocal-1.txt
new file mode 100644
index 0000000..c23a5a1
--- /dev/null
+++ b/general-concepts/autotools/aclocal-1.txt
@@ -0,0 +1,6 @@
+# vim: set ft=ebuild
+
+einfo "Regenerating autotools files..."
+cp ${WORKDIR}/gentoo-m4 ${S}/m4 || die "m4 copy failed"
+WANT_AUTOCONF="2.5" aclocal -I ${S}/m4 || die "aclocal failed"
+WANT_AUTOCONF="2.5" autoconf || die "autoconf failed"
diff --git a/general-concepts/autotools/aclocal-2.ebuild b/general-concepts/autotools/aclocal-2.ebuild
new file mode 100644
index 0000000..4d9665e
--- /dev/null
+++ b/general-concepts/autotools/aclocal-2.ebuild
@@ -0,0 +1,5 @@
+# vim: set ft=ebuild
+
+einfo "Regenerating autotools files..."
+WANT_AUTOCONF="2.5" aclocal -I ${WORKDIR}/gentoo-m4 || die "aclocal failed"
+WANT_AUTOCONF="2.5" autoconf || die "autoconf failed"
diff --git a/general-concepts/autotools/aclocal-2.txt b/general-concepts/autotools/aclocal-2.txt
new file mode 100644
index 0000000..4d9665e
--- /dev/null
+++ b/general-concepts/autotools/aclocal-2.txt
@@ -0,0 +1,5 @@
+# vim: set ft=ebuild
+
+einfo "Regenerating autotools files..."
+WANT_AUTOCONF="2.5" aclocal -I ${WORKDIR}/gentoo-m4 || die "aclocal failed"
+WANT_AUTOCONF="2.5" autoconf || die "autoconf failed"
diff --git a/general-concepts/autotools/autoconf-1.txt b/general-concepts/autotools/autoconf-1.txt
new file mode 100644
index 0000000..9a57cca
--- /dev/null
+++ b/general-concepts/autotools/autoconf-1.txt
@@ -0,0 +1,9 @@
+# vim: set ft=config :
+
+dnl Process this file with autoconf
+AC_INIT(appname, 0.1)
+AC_PREREQ(2.5)
+AC_CONFIG_SRCDIR(src/main.c)
+AC_CONFIG_AUX_DIR(config)
+AM_INIT_AUTOMAKE(1.8)
+
diff --git a/general-concepts/autotools/autoconf-2.txt b/general-concepts/autotools/autoconf-2.txt
new file mode 100644
index 0000000..5353c35
--- /dev/null
+++ b/general-concepts/autotools/autoconf-2.txt
@@ -0,0 +1,7 @@
+# vim: set ft=config :
+
+dnl Check for toolchain and install components
+AC_PROG_CC
+AC_PROG_INSTALL
+AC_PROG_LN_S
+AC_PROG_RANLIB
diff --git a/general-concepts/autotools/autoconf-3.txt b/general-concepts/autotools/autoconf-3.txt
new file mode 100644
index 0000000..3ccffd1
--- /dev/null
+++ b/general-concepts/autotools/autoconf-3.txt
@@ -0,0 +1,7 @@
+# vim: set ft=config :
+
+dnl Check for sed
+AC_CHECK_PROGS(regex_cmd, sed)
+if test x$regex_cmd = "x" ; then
+ AC_MSG_ERROR([sed is required to build the data files.])
+fi
diff --git a/general-concepts/autotools/autoconf-4.txt b/general-concepts/autotools/autoconf-4.txt
new file mode 100644
index 0000000..6eb94dd
--- /dev/null
+++ b/general-concepts/autotools/autoconf-4.txt
@@ -0,0 +1,5 @@
+# vim: set ft=config :
+
+dnl Check that our compiler can do const and inline
+AC_C_CONST
+AC_C_INLINE
diff --git a/general-concepts/autotools/autoconf-5.txt b/general-concepts/autotools/autoconf-5.txt
new file mode 100644
index 0000000..351ee3b
--- /dev/null
+++ b/general-concepts/autotools/autoconf-5.txt
@@ -0,0 +1,9 @@
+# vim: set ft=config :
+
+dnl Check for standard headers:
+AC_HEADER_STDC
+AC_HEADER_DIRENT
+AC_CHECK_HEADERS([stdlib.h stdio.h libintl.h locale.h])
+
+dnl Check for libraries:
+AC_CHECK_LIB(ssl, SSL_free)
diff --git a/general-concepts/autotools/autoconf-6.txt b/general-concepts/autotools/autoconf-6.txt
new file mode 100644
index 0000000..e76a60a
--- /dev/null
+++ b/general-concepts/autotools/autoconf-6.txt
@@ -0,0 +1,4 @@
+# vim: set ft=config :
+
+dnl Check for functions:
+AC_CHECK_FUNCS([setlocale strtol])
diff --git a/general-concepts/autotools/autoconf-7.txt b/general-concepts/autotools/autoconf-7.txt
new file mode 100644
index 0000000..7340248
--- /dev/null
+++ b/general-concepts/autotools/autoconf-7.txt
@@ -0,0 +1,4 @@
+# vim: set ft=config :
+
+AM_CONFIG_HEADER(config.h)
+AC_OUTPUT(Makefile src/Makefile nls/Makefile man/Makefile tests/Makefile)
diff --git a/general-concepts/autotools/autoconf-8.txt b/general-concepts/autotools/autoconf-8.txt
new file mode 100644
index 0000000..1fa471c
--- /dev/null
+++ b/general-concepts/autotools/autoconf-8.txt
@@ -0,0 +1,11 @@
+# vim: set ft=config :
+
+AC_MSG_CHECKING(--enable-cscope argument)
+AC_ARG_ENABLE(cscope,
+ [ --enable-cscope Include cscope interface.],
+ [enable_cscope=$enableval],
+ [enable_cscope="no"])
+AC_MSG_RESULT($enable_cscope)
+if test "$enable_cscope" = "yes"; then
+ AC_DEFINE(FEAT_CSCOPE)
+fi
diff --git a/general-concepts/autotools/autoconf-9.txt b/general-concepts/autotools/autoconf-9.txt
new file mode 100644
index 0000000..e5864e1
--- /dev/null
+++ b/general-concepts/autotools/autoconf-9.txt
@@ -0,0 +1,8 @@
+# vim: set ft=config :
+
+AC_MSG_CHECKING([whether to enable foo])
+AC_ARG_WITH(foo,
+ [ --with-foo enable foo support],
+ with_foo=$withval,
+ with_foo=yes)
+AC_MSG_RESULT($with_foo)
diff --git a/general-concepts/autotools/automake-1.txt b/general-concepts/autotools/automake-1.txt
new file mode 100644
index 0000000..da968fa
--- /dev/null
+++ b/general-concepts/autotools/automake-1.txt
@@ -0,0 +1,4 @@
+# vim: set ft=automake :
+
+bin_PROGRAMS = myapp
+myapp_SOURCES = myapp_commandline.c myapp.c
diff --git a/general-concepts/autotools/automake-2.txt b/general-concepts/autotools/automake-2.txt
new file mode 100644
index 0000000..d05bdb8
--- /dev/null
+++ b/general-concepts/autotools/automake-2.txt
@@ -0,0 +1,8 @@
+# vim: set ft=automake :
+
+CLEANFILES = glep31check.1
+man_MANS = glep31check.1
+EXTRA_DIST = glep31check.in
+
+%.1 : %.in
+ @regex_cmd@ -e "s,\@VERSION\@,$(VERSION),g" $? > $@
diff --git a/general-concepts/autotools/diagram.svg b/general-concepts/autotools/diagram.svg
new file mode 100644
index 0000000..1f3eda8
--- /dev/null
+++ b/general-concepts/autotools/diagram.svg
@@ -0,0 +1,102 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg viewBox="0 50 510 360" xmlns="http://www.w3.org/2000/svg" version="1.1">
+ <desc>Autotools Build Process</desc>
+ <rect x="-10" y="-10" width="1000" height="1000" fill="#eeeeee" id="background" />
+
+ <rect x="0" y="70" width="470" height="122"
+ stroke-width="1" stroke="black" fill="none"
+ stroke-dasharray="5,5" rx="10" ry="10" />
+ <text style="text-anchor: middle; font-style: italic;"
+ x="400" y="150">Usually handled</text>
+ <text style="text-anchor: middle; font-style: italic;"
+ x="400" y="164">by upstream</text>
+
+ <rect x="130" y="197" width="330" height="63"
+ stroke-width="1" stroke="black" fill="none"
+ stroke-dasharray="5,5" rx="10" ry="10" />
+ <text style="text-anchor: middle; font-style: italic;"
+ x="410" y="225">Shipped with</text>
+ <text style="text-anchor: middle; font-style: italic;"
+ x="410" y="239">the package</text>
+
+ <rect x="10" y="150" width="80" height="30"
+ fill="#ccccff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="50" y="170">Makefile.am</text>
+
+ <line x1="90" y1="165" x2="130" y2="165" stroke-width="2" stroke="black" />
+ <line x1="130" y1="165" x2="122" y2="160" stroke-width="2" stroke="black" />
+ <line x1="130" y1="165" x2="122" y2="170" stroke-width="2" stroke="black" />
+
+ <polygon points="130,165 180,145 230,165 180,185" fill="#ffffff"
+ stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="180" y="169">automake</text>
+
+ <line x1="180" y1="185" x2="180" y2="215" stroke-width="2" stroke="black" />
+ <line x1="185" y1="207" x2="180" y2="215" stroke-width="2" stroke="black" />
+ <line x1="175" y1="207" x2="180" y2="215" stroke-width="2" stroke="black" />
+
+ <rect x="140" y="215" width="80" height="30"
+ fill="#ccffcc" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="180" y="235">Makefile.in</text>
+
+ <line x1="220" y1="230" x2="260" y2="230" stroke-width="2" stroke="black" />
+ <line x1="260" y1="230" x2="252" y2="235" stroke-width="2" stroke="black" />
+ <line x1="260" y1="230" x2="252" y2="225" stroke-width="2" stroke="black" />
+
+ <polygon points="260,230 310,210 360,230 310,250" fill="#ccffcc"
+ stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="310" y="234">configure</text>
+
+ <line x1="310" y1="115" x2="310" y2="210" stroke-width="2" stroke="black" />
+ <line x1="315" y1="202" x2="310" y2="210" stroke-width="2" stroke="black" />
+ <line x1="305" y1="202" x2="310" y2="210" stroke-width="2" stroke="black" />
+
+ <polygon points="260,95 310,75 360,95 310,115" fill="#ffffff"
+ stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="310" y="99">autoconf</text>
+
+
+ <line x1="220" y1="95" x2="260" y2="95" stroke-width="2" stroke="black" />
+ <line x1="260" y1="95" x2="252" y2="90" stroke-width="2" stroke="black" />
+ <line x1="260" y1="95" x2="252" y2="100" stroke-width="2" stroke="black" />
+
+
+ <rect x="140" y="80" width="80" height="30"
+ fill="#ccccff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="180" y="93" >configure.in /</text>
+ <text style="text-anchor: middle;" x="180" y="105">configure.ac</text>
+
+ <line x1="90" y1="165" x2="130" y2="165" stroke-width="2" stroke="black" />
+ <line x1="130" y1="165" x2="122" y2="160" stroke-width="2" stroke="black" />
+ <line x1="130" y1="165" x2="122" y2="170" stroke-width="2" stroke="black" />
+
+ <line x1="310" y1="250" x2="310" y2="285" stroke-width="2" stroke="black" />
+ <line x1="315" y1="278" x2="310" y2="285" stroke-width="2" stroke="black" />
+ <line x1="305" y1="278" x2="310" y2="285" stroke-width="2" stroke="black" />
+
+ <rect x="270" y="285" width="80" height="30"
+ fill="#ccffcc" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="310" y="305">Makefile</text>
+
+ <line x1="350" y1="300" x2="390" y2="300" stroke-width="2" stroke="black" />
+ <line x1="390" y1="300" x2="382" y2="295" stroke-width="2" stroke="black" />
+ <line x1="390" y1="300" x2="382" y2="305" stroke-width="2" stroke="black" />
+
+ <polygon points="390,300 440,280 490,300 440,320" fill="#ffffff"
+ stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="440" y="304">make</text>
+
+ <line x1="440" y1="320" x2="440" y2="355" stroke-width="2" stroke="black" />
+ <line x1="435" y1="348" x2="440" y2="355" stroke-width="2" stroke="black" />
+ <line x1="445" y1="348" x2="440" y2="355" stroke-width="2" stroke="black" />
+
+ <ellipse cx="440" cy="375" rx="50" ry="20" stroke-width="2" stroke="black"
+ fill="#ffcccc" />
+ <text style="text-anchor: middle;" x="440" y="378">program</text>
+
+</svg>
+
+<!-- vim: set ft=xml sw=4 sts=4 et : -->
+
diff --git a/general-concepts/autotools/patching-1.ebuild b/general-concepts/autotools/patching-1.ebuild
new file mode 100644
index 0000000..5237c02
--- /dev/null
+++ b/general-concepts/autotools/patching-1.ebuild
@@ -0,0 +1,19 @@
+#
+
+src_unpack() {
+ unpack ${A}
+ cd "${S}"
+
+ # Remove problematic LDFLAGS declaration
+ sed -i -e '/^LDFLAGS/d' src/Makefile.am
+
+ # Rerun autotools
+ einfo "Regenerating autotools files..."
+ WANT_AUTOCONF=2.5 autoconf || die "autoconf failed"
+ WANT_AUTOMAKE=1.9 automake || die "automake failed"
+}
+
+src_compile() {
+ econf $(use_enable nls) || die "econf failed"
+ emake || die "emake failed"
+}
diff --git a/general-concepts/autotools/quoting-1.txt b/general-concepts/autotools/quoting-1.txt
new file mode 100644
index 0000000..db27eef
--- /dev/null
+++ b/general-concepts/autotools/quoting-1.txt
@@ -0,0 +1,7 @@
+# vim: set ft=config :
+
+AC_MSG_RESULT(the first)
+AC_MSG_RESULT([the second])
+AC_MSG_RESULT("the third")
+AC_MSG_RESULT(@<:@the fourth@:>@)
+AC_MSG_RESULT([@<:@the fifth@:>@])
diff --git a/general-concepts/autotools/text.rst b/general-concepts/autotools/text.rst
new file mode 100644
index 0000000..17bc38c
--- /dev/null
+++ b/general-concepts/autotools/text.rst
@@ -0,0 +1,355 @@
+The Basics of Autotools
+=======================
+
+.. Todo:: This is too long for `General Concepts`_. It needs to be split up and
+ moved somewhere, either to a top-level of its own or into `Appendices`_.
+
+An understanding of GNU autotools (``automake``, ``autoconf`` etc) can be useful
+when working with ebuilds:
+
+* Finding and correcting build issues is often easier if the build system is
+ not seen simply as a scary black box.
+* The autotools input files can help when determining a package's build-time
+ dependencies.
+* The risk of accidentally breaking something by patching the wrong file at the
+ wrong time is greatly reduced if the relationship between the build system
+ files is understood.
+
+Major Autotools Components
+--------------------------
+
+Autotools is a collection of related packages which, when used together, remove
+much of the difficulty involved in creating portable software. These tools,
+together with a few relatively simple upstream-supplied input files, are used to
+create the build system for a package.
+
+.. figure:: diagram.png
+ :alt: How autotools fits together
+
+ A basic overview of how the main autotools components fit together
+
+In a simple setup:
+
+* The ``autoconf`` program produces a ``configure`` script from either
+ ``configure.in`` or ``configure.ac`` (see note below).
+* The ``automake`` program produces a ``Makefile.in`` from a ``Makefile.am``.
+* The ``configure`` script is run to produce one or more ``Makefile`` files from
+ ``Makefile.in`` files.
+* The ``make`` program uses the ``Makefile`` to compile the program.
+
+
+.. Note:: The ``configure.in`` name used to be standard. However, the GNU
+ documentation now recommends ``configure.ac`` as it is more obvious which
+ program should be used when processing it. The files perform the same purpose
+ and have the same format -- the only difference is the name.
+
+You will see autotools being used variously in both ``src_unpack`` and
+``src_compile``. The QA people prefer it in ``src_unpack`` -- the rationale is
+that ``src_unpack`` handles "getting the package ready to be compiled" -- but
+there is no official policy which mandates this.
+
+The ``autoreconf`` tool supposedly runs ``autoconf`` (and ``automake``,
+``autoheader``, ``aclocal``, ``autopoint`` and ``libtoolize``) as necessary.
+Sometimes it works. Some packages ship a shell script named ``autogen.sh`` which
+does the same thing (this is *not* related to ``autogen``).
+
+.. Warning:: You must **not** attempt to modify any of the generated files in
+ between running ``configure`` and ``make``. This can lead to autotools
+ trying to be clever and recreate the files, in turn leading to your changes
+ being removed. In some situations this will also result in ``./configure``
+ arguments being silently dropped, which can give broken dependencies.
+ The best way to proceed is usually to work with the ``.ac`` / ``.in`` files
+ instead.
+
+Simple Autotools Patching Example
+---------------------------------
+
+The following snippet illustrates the correct way to proceed after patching
+either ``Makefile.am`` or ``configure.ac``:
+
+.. CODESAMPLE patching-1.ebuild
+
+The ``einfo`` message before running autotools is not mandatory. However, these
+steps can sometimes take a while and may produce no output, so it may make sense
+to let the user know that something is still happening. See `Messages`_.
+
+The ``configure.ac`` File
+-------------------------
+
+The ``configure.ac`` file is used to create the ``./configure`` script. It
+consists of a series of macros which are processed and expanded by ``autoconf``.
+These macros can check for packages and libraries, handle ``--enable`` and
+``--with`` switches, and generate various files.
+
+Basic Format of ``configure.ac``
+''''''''''''''''''''''''''''''''
+
+The ``configure.ac`` file is a basic text file. Indenting and whitespace are
+largely irrelevant. Comments are indicated by the string ``dnl`` (``dnl`` is
+actually a macro which discards the remainder of the input -- it stands for
+"discard new line").
+
+If the previous sentence made you uneasy, you should probably stop reading this
+page. It gets far worse.
+
+A typical file might start with something like the following:
+
+.. CODESAMPLE autoconf-1.txt
+
+The ``AC_PREREQ`` line, if present, tells you which ``autoconf`` version you
+need. This is useful, because ``autoconf`` is not compatible between versions.
+In the above example, we need ``=autoconf-2.5*``, and we should
+``export WANT_AUTOCONF="2.5"`` (or use the ``autoconf-2.59`` script) when calling
+``autoconf``.
+
+The ``AM_INIT_AUTOMAKE`` line tells us which ``automake`` version we need.
+Again, there is little chance that an ``automake-1.7`` script will work properly
+with ``automake-1.8``. Setting ``WANT_AUTOMAKE="1.8"`` in the environment can be
+used to make an unversioned ``automake`` call run the correct version.
+
+.. Note:: The ``WANT_`` variables are a Gentoo feature that originally came from
+ Mandrake. Other distributions may handle things differently.
+
+Usually, some standard checks will follow:
+
+.. CODESAMPLE autoconf-2.txt
+
+For non-standard applications, you may also see manual checks:
+
+.. CODESAMPLE autoconf-3.txt
+
+You may also see checks for compiler features:
+
+.. CODESAMPLE autoconf-4.txt
+
+Library and header checks:
+
+.. CODESAMPLE autoconf-5.txt
+
+And function checks:
+
+.. CODESAMPLE autoconf-6.txt
+
+Often these will be all jumbled together without any useful comments. In some
+cases, many of the checks done won't even be necessary for the application in
+question -- most autotools code is copy/pasted rather than written from scratch,
+and ``autoscan`` (a tool which helps write ``configure.ac``) is sometimes
+over-eager to add in checks.
+
+The file will finish with some output functions:
+
+.. CODESAMPLE autoconf-7.txt
+
+These are used to make the ``./configure`` script generate the relevant files.
+
+Enable and Disable Checks
+'''''''''''''''''''''''''
+
+So far we've only seen 'hard' dependencies. Many packages have *optional*
+support for various extras (graphics toolkits, libraries which add
+functionality, interpreters, features, ...). This is (if we're lucky) handled
+via ``--enable-foo`` and ``--disable-foo`` switches to ``./configure``, which
+are generated from ``autoconf`` rules.
+
+A simple ``--enable`` / ``--disable`` function might look something like the
+following:
+
+.. CODESAMPLE autoconf-8.txt
+
+Sometimes more complicated checks are included based upon whether or not an
+option is enabled. There are also some predefined macros which include
+``AC_ARG_ENABLE``, so grepping ``configure.ac`` for ``AC_ARG_ENABLE`` may not
+give a complete list. A better way is to use ``./configure --help`` and check
+the output.
+
+.. Important:: The third argument is used when a ``--enable`` or ``--disable``
+ switch to ``./configure`` is provided, and the fourth is used when such a
+ switch is *not* passed. A common misconception is that the third is enable
+ and the fourth is disable -- this is **not** the case. You may encounter
+ packages that get this wrong.
+
+A simple way to check that a package is using this macro properly is to
+install the optional dependency, and then try all of ``./configure``,
+``./configure --enable-foo`` and ``./configure --disable-foo``. If the second
+and third runs give the same results, something is wrong. If the first run gives
+a *different* result to the second and third, there is a good chance that a
+misunderstanding of the ``AC_ARG_ENABLE`` arguments is to blame.
+
+With and Without Checks
+'''''''''''''''''''''''
+
+A simple ``--with`` / ``--without`` check might look like:
+
+.. CODESAMPLE autoconf-9.txt
+
+Again, the third argument is for 'specified' and the fourth for 'not specified',
+and there are standard macros which include ``with`` options.
+
+Automatic Checks
+''''''''''''''''
+
+It's possible to write autoconf rules which bypass the manual enable / disable
+convention (or which just ignore what the user asks for). If your package does
+this, it must be fixed to avoid dependency problems.
+
+The most common form is packages which simply use ``AC_CHECK_LIB`` to decide
+whether or not to enable a feature. If you find a package which does this, you
+**must** change the behaviour.
+
+Quoting Rules for ``configure.ac``
+''''''''''''''''''''''''''''''''''
+
+Behind the scenes, ``autoconf`` makes heavy use of the ``m4`` macro processor to
+do the work. The ``m4`` quote characters are set by ``autoconf`` to be ``[`` and
+``]`` for opening and closing quotes respectively. Using ``"`` or ``'`` may
+produce unexpected results.
+
+To include a literal left square bracket, the easiest thing to do is to use the
+special string ``@<:@``. For a right bracket, use ``@:>@``.
+
+For example:
+
+.. CODESAMPLE quoting-1.txt
+
+gives: ::
+
+ the first
+ the second
+ "the third"
+ [the fourth]
+ [the fifth]
+
+When in doubt, it is generally safest to quote macro arguments using ``[ ]``
+rather than leaving things unquoted.
+
+The ``Makefile.am`` Files
+-------------------------
+
+The ``Makefile.am`` file is processed by ``automake`` to create ``Makefile.in``,
+which is in turn processed by ``configure`` to create ``Makefile``, which is in
+turn used by ``make`` to build the software.
+
+The basic format is like that of a ``Makefile``. However, you will see various
+'special' variables being set, rather than every rule being written manually.
+
+A very simple example:
+
+.. CODESAMPLE automake-1.txt
+
+All the standard GNU rules will be generated, so ``make``, ``make clean``,
+``make distclean``, ``make dist`` and so on will all work here.
+
+You may also see some standard ``Makefile`` constructs showing up whenever there
+isn't a standard ``automake`` way of handling a certain task. For example:
+
+.. CODESAMPLE automake-2.txt
+
+Here, the ``@regex_cmd@`` variable will be substituted with whatever
+``configure`` detects (``sed`` in this case) when creating the ``Makefile``.
+This is handled via the macro ``AC_SUBST(VARNAME)`` in ``configure.ac``.
+
+Makefile Variables
+''''''''''''''''''
+
+Sometimes, badly behaved ``Makefile.am`` files will override user variables such
+as ``CFLAGS``. This must not be allowed -- see `Not Filtering Variables`_. There
+are separate special variables which should be used in these situations -- for
+setting ``CFLAGS``, for example, a ``Makefile.am`` should use ``AM_CFLAGS`` so
+that user preferences are not ignored.
+
+So, if a ``Makefile.am`` contains, say: ::
+
+ CFLAGS="-Wall"
+
+You should ``sed`` or ``patch`` it to use: ::
+
+ AM_CFLAGS="-Wall"
+
+Remember to manually run ``autoconf`` then ``automake`` if you do this.
+
+The ``config.h.in`` File
+------------------------
+
+The ``config.h.in`` file is generated by ``autoheader``. You shouldn't have to
+worry about this usually, but occasionally you may need to run ``autoheader``
+manually as part of the build process if upstream do not ship a pre-generated
+version.
+
+``aclocal`` and ``m4`` Files
+----------------------------
+
+In the ``configure.ac`` or ``configure.in`` files you can call not only the
+default macros defined by ``autoconf`` and ``automake``, but also other
+functions which can be defined by specific packages like libraries and programs
+to check for their features in the correct manner.
+
+Those functions are (usually) defined in ``m4`` files placed in
+the ``/usr/share/aclocal`` directory by packages. Problems can arise when you
+need to regenerate the ``autotools`` files, because the functions used by the
+``configure.ac`` file can be defined in an ``m4`` macro file which isn't
+installed on the user's system. This is the case for example for some optional
+features which require libraries and are disabled by ``USE`` flags. If the
+``m4`` files aren't installed in the user's system, the ``autoconf`` step will
+fail.
+
+To resolve this, most packages just ship the ``m4`` macro files needed for their
+``configure.ac`` in an ``m4`` subdirectory in the source package. Unfortunately,
+not all ``m4`` directories are complete, even if they are present.
+
+In those cases you need to find out the ``m4`` file, usually installed by the
+dependency in ``/usr/share/aclocal``, and make sure that the ``src_unpack``
+stage both makes available those files to the autotools and calls ``aclocal`` to
+recreate the ``aclocal.m4`` file which is used by ``autoconf`` when creating the
+configure script.
+
+Usually it's more than one ``m4`` file which is missing, so you probably want to
+package them in a tarball, and add it to ``SRC_URI``. After making sure that the
+tarball is extracted somewhere in ``${WORKDIR}`` (say, in a ``gentoo-m4``
+directory), you usually have two general ways to handle those macro files, one
+for packages which ships with an incomplete ``m4`` directory and one for
+packages which ships without the ``m4`` directory.
+
+In the first case you usually want to do something like:
+
+.. CODESAMPLE aclocal-1.ebuild
+
+and so on. In the second case you can simplify it in this way:
+
+.. CODESAMPLE aclocal-2.ebuild
+
+without need to copy the files.
+
+It's always better inform upstream when the needed ``m4`` files are missing in
+the distribution, asking them to add all the needed files in the source tarball
+to avoid version conflicts if the macro changes.
+
+Libtool
+-------
+
+.. Todo:: Stuff about libtool, libtoolize, elibtoolize, libtool.eclass. Which I
+ know almost nothing about... Yay!
+
+Further Autotools Reading
+-------------------------
+
+For more details on autotools:
+
+* The book "GNU Autoconf, Automake and Libtool" by Gary V. Vaughan, Ben
+ Elliston, Tom Tromey and Ian Lance Taylor (often called "The Autobook")
+ provides a good but somewhat outdated description of autotools. It is
+ `freely available online <http://sources.redhat.com/autobook/>`_.
+
+* The GNU documentation for the various autotools components is of varying
+ quality and completeness:
+
+ + `GNU automake Manual
+ <http://www.gnu.org/software/automake/manual/automake.html>`_
+ + `GNU autoconf Manual <http://www.gnu.org/software/autoconf/manual/>`_
+ + `GNU libtool Manual <http://www.gnu.org/software/libtool/manual.html>`_
+ + `GNU m4 Manual <http://www.gnu.org/software/m4/manual/m4.html>`_
+
+* There are some good overview lectures available online. `These slides
+ <http://vipe.technion.ac.il/~shlomif/lecture/Autotools/slides/>`_ are one
+ example.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/general-concepts/config-protect/text.rst b/general-concepts/config-protect/text.rst
new file mode 100644
index 0000000..58736a8
--- /dev/null
+++ b/general-concepts/config-protect/text.rst
@@ -0,0 +1,20 @@
+Configuration File Protection
+=============================
+
+Portage includes a system for configuration file protection which means ebuilds
+don't have to worry about accidentally clobbering files in ``/etc``. This is
+known as 'protection', and it is controlled by the ``CONFIG_PROTECT`` and
+``CONFIG_PROTECT_MASK`` variables.
+
+Any directory which is listed in ``CONFIG_PROTECT`` (and any subdirectories
+thereof), except for any which are listed in ``CONFIG_PROTECT_MASK`` (and
+subdirectories) are automatically 'protected' by portage when copying an image
+from ``DESTDIR`` to ``ROOT``. Rather than installing protected files directly,
+portage will install them as ``._cfg0000_filename``. These can then be processed
+by the ``etc-update`` or ``dispatch-conf`` files at the user's discretion.
+
+Packages must **not** attempt to override this system via ``pkg_postinst`` or
+similar. If you need a file renamed, remove or changed in a particular way, you
+should display a message informing the user.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/general-concepts/cvs-to-rsync/diagram.svg b/general-concepts/cvs-to-rsync/diagram.svg
new file mode 100644
index 0000000..bc7e308
--- /dev/null
+++ b/general-concepts/cvs-to-rsync/diagram.svg
@@ -0,0 +1,142 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg viewBox="0 0 700 250" xmlns="http://www.w3.org/2000/svg" version="1.1">
+ <desc>CVS to RSYNC Propagation</desc>
+
+ <rect x="-10" y="-10" width="1000" height="1000" fill="#eeeeee" id="background" />
+
+ <rect x="10" y="110" width="80" height="30"
+ fill="#ffcccc" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="50" y="130">Developers</text>
+
+ <line x1="90" y1="125" x2="130" y2="125" stroke-width="2" stroke="black" />
+ <line x1="130" y1="125" x2="122" y2="120" stroke-width="2" stroke="black" />
+ <line x1="130" y1="125" x2="122" y2="130" stroke-width="2" stroke="black" />
+
+
+ <rect x="10" y="60" width="80" height="30"
+ fill="#ffcccc" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="50" y="80">Developers</text>
+
+ <path d="M 90 75 Q 110 75 110 100 Q 110 130 130 125"
+ stroke-width="2" stroke="black" fill="none" />
+
+ <rect x="10" y="160" width="80" height="30"
+ fill="#ffcccc" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="50" y="180">Developers</text>
+
+ <path d="M 90 175 Q 110 175 110 150 Q 110 120 130 125"
+ stroke-width="2" stroke="black" fill="none" />
+
+ <rect x="130" y="110" width="80" height="30"
+ fill="#ffffff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="170" y="130">CVS</text>
+
+ <line x1="210" y1="125" x2="250" y2="125" stroke-width="2" stroke="black" />
+ <line x1="250" y1="125" x2="242" y2="120" stroke-width="2" stroke="black" />
+ <line x1="250" y1="125" x2="242" y2="130" stroke-width="2" stroke="black" />
+
+
+
+ <rect x="250" y="110" width="80" height="30"
+ fill="#ffffff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="290" y="123">Staging</text>
+ <text style="text-anchor: middle;" x="290" y="135">Box</text>
+
+ <line x1="330" y1="125" x2="370" y2="125" stroke-width="2" stroke="black" />
+ <line x1="370" y1="125" x2="362" y2="120" stroke-width="2" stroke="black" />
+ <line x1="370" y1="125" x2="362" y2="130" stroke-width="2" stroke="black" />
+
+
+
+ <rect x="370" y="110" width="80" height="30"
+ fill="#ffffff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="410" y="130">rsync1</text>
+
+
+
+ <line x1="490" y1="75" x2="482" y2="70" stroke-width="2" stroke="black" />
+ <line x1="490" y1="75" x2="482" y2="80" stroke-width="2" stroke="black" />
+ <path d="M 450 125 Q 470 125 470 100 Q 470 70 490 75"
+ stroke-width="2" stroke="black" fill="none" />
+
+ <rect x="490" y="60" width="80" height="30"
+ fill="#ccffcc" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="530" y="80">Public rsync</text>
+
+
+
+ <line x1="450" y1="125" x2="490" y2="125" stroke-width="2" stroke="black" />
+ <line x1="490" y1="125" x2="482" y2="120" stroke-width="2" stroke="black" />
+ <line x1="490" y1="125" x2="482" y2="130" stroke-width="2" stroke="black" />
+
+ <rect x="490" y="110" width="80" height="30"
+ fill="#ccffcc" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="530" y="130">Public rsync</text>
+
+
+
+ <line x1="490" y1="175" x2="482" y2="170" stroke-width="2" stroke="black" />
+ <line x1="490" y1="175" x2="482" y2="180" stroke-width="2" stroke="black" />
+ <path d="M 450 125 Q 470 125 470 150 Q 470 180 490 175"
+ stroke-width="2" stroke="black" fill="none" />
+
+ <rect x="490" y="160" width="80" height="30"
+ fill="#ccffcc" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="530" y="180">Public rsync</text>
+
+
+
+ <line x1="610" y1="25" x2="602" y2="20" stroke-width="2" stroke="black" />
+ <line x1="610" y1="25" x2="602" y2="30" stroke-width="2" stroke="black" />
+ <path d="M 570 75 Q 590 75 590 50 Q 590 20 610 25"
+ stroke-width="2" stroke="black" fill="none" />
+
+ <rect x="610" y="10" width="80" height="30"
+ fill="#ccccff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="650" y="30">Users</text>
+
+
+
+ <line x1="570" y1="75" x2="610" y2="75" stroke-width="2" stroke="black" />
+ <line x1="610" y1="75" x2="602" y2="70" stroke-width="2" stroke="black" />
+ <line x1="610" y1="75" x2="602" y2="80" stroke-width="2" stroke="black" />
+
+ <rect x="610" y="60" width="80" height="30"
+ fill="#ccccff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="650" y="80">Users</text>
+
+
+
+ <line x1="570" y1="125" x2="610" y2="125" stroke-width="2" stroke="black" />
+ <line x1="610" y1="125" x2="602" y2="120" stroke-width="2" stroke="black" />
+ <line x1="610" y1="125" x2="602" y2="130" stroke-width="2" stroke="black" />
+
+ <rect x="610" y="110" width="80" height="30"
+ fill="#ccccff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="650" y="130">Users</text>
+
+
+ <line x1="570" y1="175" x2="610" y2="175" stroke-width="2" stroke="black" />
+ <line x1="610" y1="175" x2="602" y2="170" stroke-width="2" stroke="black" />
+ <line x1="610" y1="175" x2="602" y2="180" stroke-width="2" stroke="black" />
+
+ <rect x="610" y="160" width="80" height="30"
+ fill="#ccccff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="650" y="180">Users</text>
+
+
+
+ <line x1="610" y1="225" x2="602" y2="220" stroke-width="2" stroke="black" />
+ <line x1="610" y1="225" x2="602" y2="230" stroke-width="2" stroke="black" />
+ <path d="M 570 175 Q 590 175 590 200 Q 590 230 610 225"
+ stroke-width="2" stroke="black" fill="none" />
+
+ <rect x="610" y="210" width="80" height="30"
+ fill="#ccccff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="650" y="230">Users</text>
+
+</svg>
+
+<!-- vim: set ft=xml sw=4 sts=4 et : -->
diff --git a/general-concepts/cvs-to-rsync/text.rst b/general-concepts/cvs-to-rsync/text.rst
new file mode 100644
index 0000000..2af2148
--- /dev/null
+++ b/general-concepts/cvs-to-rsync/text.rst
@@ -0,0 +1,23 @@
+CVS to RSYNC
+============
+
+Changes made to the tree are propagated to the users in stages:
+
+* Developer commits to CVS.
+
+* Staging box syncs from CVS and generates the metadata cache.
+
+* ``rsync1`` syncs from the staging box.
+
+* Public rsync servers sync from ``rsync1``.
+
+* Users sync from the public rsync servers.
+
+.. figure:: diagram.png
+ :alt: CVS to RSYNC Propagation
+
+ Diagram showing CVS to RSYNC Propagation
+
+The ``emerge-websync`` snapshot is made daily from the staging box.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/general-concepts/dependencies/basic-depend-sample.ebuild b/general-concepts/dependencies/basic-depend-sample.ebuild
new file mode 100644
index 0000000..90f6d97
--- /dev/null
+++ b/general-concepts/dependencies/basic-depend-sample.ebuild
@@ -0,0 +1,5 @@
+# header
+
+DEPEND="dev-lang/ruby
+ dev-ruby/ruby-gtk2
+ dev-ruby/mysql-ruby"
diff --git a/general-concepts/dependencies/basic-depend-versions-sample.ebuild b/general-concepts/dependencies/basic-depend-versions-sample.ebuild
new file mode 100644
index 0000000..1d64ebe
--- /dev/null
+++ b/general-concepts/dependencies/basic-depend-versions-sample.ebuild
@@ -0,0 +1,3 @@
+# header
+
+DEPEND=">=dev-libs/openssl-0.9.7d"
diff --git a/general-concepts/dependencies/block-sample.ebuild b/general-concepts/dependencies/block-sample.ebuild
new file mode 100644
index 0000000..f8aaf00
--- /dev/null
+++ b/general-concepts/dependencies/block-sample.ebuild
@@ -0,0 +1,3 @@
+# header
+
+RDEPEND="!app-misc/foo"
diff --git a/general-concepts/dependencies/block-version-sample.ebuild b/general-concepts/dependencies/block-version-sample.ebuild
new file mode 100644
index 0000000..65e83d2
--- /dev/null
+++ b/general-concepts/dependencies/block-version-sample.ebuild
@@ -0,0 +1,3 @@
+# header
+
+RDEPEND="!<app-misc/foo-1.3"
diff --git a/general-concepts/dependencies/ranged-depend-sample.ebuild b/general-concepts/dependencies/ranged-depend-sample.ebuild
new file mode 100644
index 0000000..26955f7
--- /dev/null
+++ b/general-concepts/dependencies/ranged-depend-sample.ebuild
@@ -0,0 +1,4 @@
+# header
+
+DEPEND="gtk2? ( >=x11-libs/gtk+-2.4 )
+ !gtk2? ( =x11-libs/gtk+-1.2* )"
diff --git a/general-concepts/dependencies/text.rst b/general-concepts/dependencies/text.rst
new file mode 100644
index 0000000..2ba10f2
--- /dev/null
+++ b/general-concepts/dependencies/text.rst
@@ -0,0 +1,197 @@
+Dependencies
+============
+
+Automatic dependency resolution is one of the most useful features provided by
+``emerge``.
+
+Build Dependencies
+------------------
+
+The ``DEPEND`` ebuild variable should specify any dependencies which are
+required to unpack, patch, compile or install the package (but see
+`Implicit System Dependency`_ for exemptions).
+
+Runtime Dependencies
+--------------------
+
+The ``RDEPEND`` ebuild variable should specify any dependencies which are
+required at runtime. This includes libraries (when dynamically linked), any data
+packages and (for interpreted languages) the relevant interpreter. If this
+variable is not specified, it defaults to the value of ``DEPEND``.
+
+Note that when installing from a binary package, only ``RDEPEND`` will be
+checked. It is therefore necessary to include items even if they are also listed
+in ``DEPEND``.
+
+Items which are in ``RDEPEND`` but not ``DEPEND`` could *in theory* be merged
+*after* the target package. Portage does not currently do this.
+
+Post-Merge Dependencies
+-----------------------
+
+The ``PDEPEND`` variable specifies dependencies which must be merged *after* the
+package. This is sometimes used for plugins which have a dependency upon the
+package being merged. Generally ``PDEPEND`` should be avoided in favour of
+``RDEPEND`` except where this will create circular dependency chains.
+
+Implicit System Dependency
+--------------------------
+
+All packages have an implicit compile-time and runtime dependency upon the
+entire ``system`` target. It is therefore not necessary, nor advisable, to
+specify dependencies upon ``gcc``, ``libc`` and so on, except where specific
+versions or packages (for example, ``glibc`` over ``uclibc``) are required.
+
+However, packages which are included in the ``system`` target, or are
+dependencies of ``system`` target packages, should generally include a complete
+dependency list (excluding bootstrap packages). This makes ``emerge -e system``
+possible when installing from a stage 1 or stage 2 tarball.
+
+Basic Dependency Syntax
+-----------------------
+
+A basic ``*DEPEND`` specification might look like the following:
+
+.. CODESAMPLE basic-depend-sample.ebuild
+
+Each atom is the full category and name of a package. Atoms are separated by
+arbitrary whitespace -- convention is to specify one atom per line for
+readability purposes. When specifying names, the category part should be treated
+as mandatory.
+
+Version Dependencies
+--------------------
+
+Sometimes a particular version of a package is needed. Where this is known, it
+should be specified. A simple example:
+
+.. CODESAMPLE basic-depend-versions-sample.ebuild
+
+This states that at least version 0.9.7d of ``openssl`` is required.
+
+Version Specifiers
+''''''''''''''''''
+
+Available version specifiers are:
+
+========================= ====================================================
+Specifier Meaning
+========================= ====================================================
+``>=app-misc/foo-1.23`` Version 1.23 or later is required.
+``>app-misc/foo-1.23`` A version strictly later than 1.23 is required.
+``~app-misc/foo-1.23`` Version 1.23 (or any ``1.23-r*``) is required.
+``=app-misc/foo-1.23`` Exactly version 1.23 is required. If at all possible,
+ use the ``~`` form to simplify revision bumps.
+``<=app-misc/foo-1.23`` Version 1.23 or older is required.
+``<app-misc/foo-1.23`` A version strictly before 1.23 is required.
+========================= ====================================================
+
+Ranged Dependencies
+'''''''''''''''''''
+
+To specify "version 2.x (not 1.x or 3.x)" of a package, it is necessary to use
+the asterix postfix. This is most commonly seen in situations like:
+
+.. CODESAMPLE ranged-depend-sample.ebuild
+
+Note that the equals sign is mandatory, and that there is no dot before the
+asterisk.
+
+Blockers
+''''''''
+
+Sometimes two packages cannot be installed in parallel. This is handled by
+blockers. A blocker is specified as follows:
+
+.. CODESAMPLE block-sample.ebuild
+
+Note that blockers are usually *runtime* rather than buildtime.
+
+Specific versions can also be blocked:
+
+.. CODESAMPLE block-version-sample.ebuild
+
+Blockers can be optional based upon USE flags as per normal dependencies.
+
+SLOT Dependencies
+-----------------
+
+It is not currently possible to depend upon a package in a particular ``SLOT``.
+This is a shame.
+
+USE-Conditional Dependencies
+----------------------------
+
+To depend upon a certain package if and only if a given ``USE`` flag is set:
+
+.. CODESAMPLE use-depend-sample.ebuild
+
+It is also possible to depend upon a certain package if a given ``USE`` flag is
+*not* set:
+
+.. CODESAMPLE use-depend-inv-sample.ebuild
+
+This should **not** be used for disabling a certain ``USE`` flag on a given
+architecture. In order to do this, the architecture should add the ``USE``
+flag to their ``use.mask`` file in the ``profiles/default-linux/arch``
+directory of the Portage tree.
+
+This can be nested:
+
+.. CODESAMPLE use-depend-nest-sample.ebuild
+
+Virtual Dependencies
+--------------------
+
+To depend upon a virtual package, use ``virtual/whatever`` as the atom.
+
+Currently, you must not use any kind of version specification with virtuals --
+see `GLEP 37`_ for details and a proposed solution.
+
+Any of Many Dependencies
+------------------------
+
+To depend on either ``foo`` or ``bar``:
+
+.. CODESAMPLE use-depend-either-sample.ebuild
+
+To depend on either ``foo`` or ``bar`` if the ``baz`` ``USE`` flag is set:
+
+.. CODESAMPLE use-depend-either-use-sample.ebuild
+
+Any of Many Versus USE
+''''''''''''''''''''''
+
+Say ``fnord`` can be built against either ``foo`` or ``bar``. Then a USE flag is
+not necessary if and only if all of the following hold:
+
+* ``fnord`` is merged on a system which has ``foo`` and not ``bar`` installed.
+ ``foo`` is then unmerged, and ``bar`` is installed. ``fnord`` must continue to
+ work correctly.
+
+* A binary package of ``fnord`` made on a system with ``foo`` and not ``bar``
+ can be taken and installed on a system with ``bar`` and not ``foo``.
+
+Built with USE Dependencies
+---------------------------
+
+Currently it is impossible to depend upon "``foo`` built with the ``bar``
+``USE`` flag enabled". This is a nuisance.
+
+Legacy Inverse USE-Conditional Dependency Syntax
+------------------------------------------------
+
+When looking through old ebuild versions or the occasional user-submitted
+ebuild, you may see a ``*DEPEND`` atom in the form:
+
+.. CODESAMPLE use-depend-legacy-sample.ebuild
+
+**This syntax is no longer permitted**. It is exactly equivalent to the
+following, which should be used instead:
+
+.. CODESAMPLE use-depend-nonlegacy-sample.ebuild
+
+It is useful to recognise the legacy syntax and to know that it is no longer
+valid.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/general-concepts/dependencies/use-depend-either-sample.ebuild b/general-concepts/dependencies/use-depend-either-sample.ebuild
new file mode 100644
index 0000000..c575405
--- /dev/null
+++ b/general-concepts/dependencies/use-depend-either-sample.ebuild
@@ -0,0 +1,3 @@
+# header
+
+DEPEND="|| ( app-misc/foo app-misc/bar )"
diff --git a/general-concepts/dependencies/use-depend-either-use-sample.ebuild b/general-concepts/dependencies/use-depend-either-use-sample.ebuild
new file mode 100644
index 0000000..464759e
--- /dev/null
+++ b/general-concepts/dependencies/use-depend-either-use-sample.ebuild
@@ -0,0 +1,3 @@
+# HEADER
+
+DEPEND="baz? ( || ( app-misc/foo app-misc/bar ) )"
diff --git a/general-concepts/dependencies/use-depend-inv-sample.ebuild b/general-concepts/dependencies/use-depend-inv-sample.ebuild
new file mode 100644
index 0000000..6c1965b
--- /dev/null
+++ b/general-concepts/dependencies/use-depend-inv-sample.ebuild
@@ -0,0 +1,3 @@
+# header
+
+RDEPEND="!crypt? ( net-misc/netkit-rsh )"
diff --git a/general-concepts/dependencies/use-depend-legacy-sample.ebuild b/general-concepts/dependencies/use-depend-legacy-sample.ebuild
new file mode 100644
index 0000000..45d7d51
--- /dev/null
+++ b/general-concepts/dependencies/use-depend-legacy-sample.ebuild
@@ -0,0 +1,3 @@
+# header
+
+DEPEND="use-flag? ( app-misc/foo ) : ( app-misc/bar )"
diff --git a/general-concepts/dependencies/use-depend-nest-sample.ebuild b/general-concepts/dependencies/use-depend-nest-sample.ebuild
new file mode 100644
index 0000000..6826689
--- /dev/null
+++ b/general-concepts/dependencies/use-depend-nest-sample.ebuild
@@ -0,0 +1,6 @@
+# header
+
+DEPEND="gtk? (
+ gtk2? ( >=x11-libs/gtk+-2.4 )
+ !gtk2? ( =x11-libs/gtk+-1.2* ) )
+ !gtk? ( sys-libs/ncurses )"
diff --git a/general-concepts/dependencies/use-depend-nonlegacy-sample.ebuild b/general-concepts/dependencies/use-depend-nonlegacy-sample.ebuild
new file mode 100644
index 0000000..72087e7
--- /dev/null
+++ b/general-concepts/dependencies/use-depend-nonlegacy-sample.ebuild
@@ -0,0 +1,4 @@
+# header
+
+DEPEND="use-flag? ( app-misc/foo )
+ !use-flag? ( app-misc/bar )"
diff --git a/general-concepts/dependencies/use-depend-sample.ebuild b/general-concepts/dependencies/use-depend-sample.ebuild
new file mode 100644
index 0000000..a0e3d73
--- /dev/null
+++ b/general-concepts/dependencies/use-depend-sample.ebuild
@@ -0,0 +1,5 @@
+# header
+
+DEPEND="perl? ( dev-lang/perl )
+ ruby? ( >=dev-lang/ruby-1.8 )
+ python? ( dev-lang/python )"
diff --git a/general-concepts/digest-and-manifest/text.rst b/general-concepts/digest-and-manifest/text.rst
new file mode 100644
index 0000000..613a9d0
--- /dev/null
+++ b/general-concepts/digest-and-manifest/text.rst
@@ -0,0 +1,24 @@
+Digest and Manifest
+===================
+
+In the tree, every package has a ``Manifest`` file. This file lives in the same
+directory as the ebuilds for the package. The ``Manifest`` file contains digests
+(currently MD5) and file size data for every file in the directory and any
+subdirectories. This is used to verify integrity.
+
+The ``Manifest`` may be digitally signed.
+
+Inside the ``files/`` subdirectory, there is exactly one ``digest`` file per
+ebuild. Each file contains a digest (currently MD5) and a file size for every
+file listed in ``SRC_URI`` for the ebuild. This is used to verify downloads and
+to catch any changed source files.
+
+When generating digests, it is necessary to include *all* of the files which
+*could* be downloaded (``SRC_URI`` can contain conditional entries). Portage
+will do this automatically if ``cvs`` is included in ``FEATURES``.
+
+To generate digests and ``Manifest``, use ``ebuild foo.ebuild digest``. When
+committing, the ``Manifest`` file must be regenerated to handle any CVS keyword
+expansion changes -- ``repoman`` will do this automatically.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/general-concepts/distributed-building/text.rst b/general-concepts/distributed-building/text.rst
new file mode 100644
index 0000000..367ecb0
--- /dev/null
+++ b/general-concepts/distributed-building/text.rst
@@ -0,0 +1,6 @@
+Distributed and Parallel Building
+=================================
+
+.. Todo:: write this
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/general-concepts/ebuild-revisions/text.rst b/general-concepts/ebuild-revisions/text.rst
new file mode 100644
index 0000000..dc8dd9c
--- /dev/null
+++ b/general-concepts/ebuild-revisions/text.rst
@@ -0,0 +1,23 @@
+Ebuild Revisions
+================
+
+Ebuilds may have a Gentoo revision number associated with them. This is a
+``-rX`` suffix, where ``X`` is an integer -- see `File Naming Rules`_. This
+component must only be used for Gentoo changes, not upstream releases. By
+default, ``-r0`` is implied and should not be specified manually.
+
+Ebuilds should have their ``-rX`` incremented whenever a change is made which
+will make a substantial difference to what gets installed by the package -- by
+substantial, we generally mean "something for which many users would want to
+upgrade". This is usually for bugfixes.
+
+Simple compile fixes do **not** warrant a revision bump; this is because they do
+not affect the installed package for users who already managed to compile it.
+Small documentation fixes are also usually not grounds for a new revision.
+
+When doing a revision bump, the usual rules about dropping to ``~arch`` apply.
+See `Keywording on Upgrades`_.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
+
diff --git a/general-concepts/emerge-and-ebuild/diagram.svg b/general-concepts/emerge-and-ebuild/diagram.svg
new file mode 100644
index 0000000..62bc8fd
--- /dev/null
+++ b/general-concepts/emerge-and-ebuild/diagram.svg
@@ -0,0 +1,55 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg viewBox="0 100 500 220" xmlns="http://www.w3.org/2000/svg" version="1.1">
+ <desc>Emerge and Ebuild</desc>
+ <rect x="-10" y="-10" width="1000" height="1000" fill="#eeeeee" id="background" />
+
+ <rect x="50" y="150" width="100" height="30"
+ fill="#ccffcc" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="100" y="170"># emerge foo</text>
+
+ <line x1="150" y1="165" x2="200" y2="165" stroke-width="2" stroke="black" />
+ <line x1="200" y1="165" x2="193" y2="160" stroke-width="2" stroke="black" />
+ <line x1="200" y1="165" x2="193" y2="170" stroke-width="2" stroke="black" />
+
+ <rect x="200" y="150" width="100" height="30"
+ fill="#ffffff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="250" y="170">emerge</text>
+
+ <line x1="220" y1="180" x2="220" y2="250" stroke-width="2" stroke="black" />
+ <line x1="220" y1="250" x2="215" y2="243" stroke-width="2" stroke="black" />
+ <line x1="220" y1="250" x2="225" y2="243" stroke-width="2" stroke="black" />
+ <text style="text-anchor: right;" x="210" y="220">$PN, phases</text>
+
+ <line x1="280" y1="180" x2="280" y2="250" stroke-width="2" stroke="black" />
+ <line x1="280" y1="180" x2="275" y2="187" stroke-width="2" stroke="black" />
+ <line x1="280" y1="180" x2="285" y2="187" stroke-width="2" stroke="black" />
+ <text style="text-anchor: left;" x="290" y="220">Image in $D</text>
+
+ <rect x="200" y="250" width="100" height="30"
+ fill="#ffffff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="250" y="270">ebuild.sh</text>
+
+ <rect x="50" y="250" width="100" height="30"
+ fill="#ccccff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="100" y="270">foo-1.23.ebuild</text>
+
+ <line x1="150" y1="265" x2="200" y2="265" stroke-width="2" stroke="black" />
+ <line x1="200" y1="265" x2="193" y2="260" stroke-width="2" stroke="black" />
+ <line x1="200" y1="265" x2="193" y2="270" stroke-width="2" stroke="black" />
+
+ <line x1="300" y1="165" x2="350" y2="165" stroke-width="2" stroke="black" />
+ <line x1="350" y1="165" x2="343" y2="160" stroke-width="2" stroke="black" />
+ <line x1="350" y1="165" x2="343" y2="170" stroke-width="2" stroke="black" />
+
+ <ellipse cx="400" cy="165" rx="50" ry="20" stroke-width="2" stroke="black"
+ fill="#ffcccc" />
+ <text style="text-anchor: middle;" x="400" y="164">Installed image</text>
+ <text style="text-anchor: middle;" x="400" y="177">in $ROOT</text>
+
+</svg>
+
+<!-- vim: set ft=xml sw=4 sts=4 et : -->
+
+
diff --git a/general-concepts/emerge-and-ebuild/text.rst b/general-concepts/emerge-and-ebuild/text.rst
new file mode 100644
index 0000000..f8d7615
--- /dev/null
+++ b/general-concepts/emerge-and-ebuild/text.rst
@@ -0,0 +1,16 @@
+Emerge and Ebuild Relationships
+===============================
+
+.. figure:: diagram.png
+ :alt: How emerge, ebuild and foo.ebuild interact
+
+The ``emerge`` program is a high level wrapper for ``ebuild.sh`` that handles
+dependency tracking, safe installs and uninstalls and so on. ``emerge`` calls
+``ebuild.sh`` during the build process, which in turn handles the ebuild file
+and any eclasses. The ``${D}`` to ``${ROOT}`` install is handled by ``emerge``.
+
+.. Todo:: http://dev.gentoo.org/~g2boojum/portage.html
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
+
diff --git a/general-concepts/features/text.rst b/general-concepts/features/text.rst
new file mode 100644
index 0000000..7f4fd6d
--- /dev/null
+++ b/general-concepts/features/text.rst
@@ -0,0 +1,40 @@
+FEATURES
+========
+
+The ``FEATURES`` variable specifies options which affect how portage operates
+and how packages are compiled. It is **not** used for settings which have a
+substantial effect upon the resulting generated package.
+
+Relevant ``FEATURES`` for developers include:
+
+``autoaddcvs``
+ Automatically runs a ``cvs add`` for certain files.
+
+``collision-protect``
+ Raise an error if an installing package attempts to overwrite a file which
+ is provided by a different package.
+
+``cvs``
+ Generate proper digests even when ``SRC_URI`` has conditional elements.
+
+``sandbox``
+ Enable the sandbox.
+
+``sign``
+ GPG sign manifest files.
+
+``strict``
+ Do some extra checks for potentially dangerous situations (eg missing
+ ``Manifest`` files).
+
+``test``
+ Enable the ``src_test`` phase.
+
+``userpriv``
+ Drop to non-root privileges for certain phases.
+
+``usersandbox``
+ Enables the sandbox even when running non-privileged.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/general-concepts/filesystem/text.rst b/general-concepts/filesystem/text.rst
new file mode 100644
index 0000000..6abe677
--- /dev/null
+++ b/general-concepts/filesystem/text.rst
@@ -0,0 +1,55 @@
+Filesystem
+==========
+
+The basic filesystem layout and purpose is as follows:
+
+* ``/bin``: Boot-critical applications
+* ``/etc``: System administrator controlled configuration files
+* ``/lib``: Boot-critical libraries
+* ``/opt``: Binary-only applications.
+* ``/sbin``: System administrator boot-critical applications
+* ``/tmp``: Temporary data
+* ``/usr``: General applications
+
+ + ``/usr/bin``: Applications
+ + ``/usr/lib``: Libraries
+ + ``/usr/local``: Non-portage applications. **Ebuilds must not install here**.
+ + ``/usr/sbin``: Non-system-critical system administrator applications
+ + ``/usr/share``: Architecture independent application data and documentation
+
+* ``/var``: Program generated data
+
+ + ``/var/cache``: Long term data which can be regenerated
+ + ``/var/lib``: General application generated data
+ + ``/var/log``: Log files
+
+Where possible, we prefer to put non-boot-critical applications in ``/usr``
+rather than ``/``. If a program is not needed in the boot process until after
+filesystems are mounted then it generally does not belong on ``/``.
+
+Any binary which links against a library under ``/usr`` must itself go into
+``/usr`` (or possibly ``/opt``).
+
+The ``/opt`` top-level should only be used for binary-only applications.
+Binary-only applications must not be installed outside of ``/opt``.
+
+The ``/usr/local`` heirarchy is for non-portage software. Ebuilds must not
+attempt to put anything in here.
+
+The ``/usr/share`` directory is for *architecture independent* application data
+which is not modified at runtime.
+
+Try to avoid installing unnecessary things into ``/etc`` -- every file in there
+is additional work for the system administrator. In particular, non-text files
+and files that are not intended for system administrator usage should be moved
+to ``/usr/share``.
+
+FHS
+---
+
+Gentoo does not consider the `Filesystem Hierarchy Standard
+<http://www.pathname.com/fhs/>`__ to be an authoritative standard, although much
+of our policy coincides with it.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/general-concepts/herds-and-projects/text.rst b/general-concepts/herds-and-projects/text.rst
new file mode 100644
index 0000000..f05f850
--- /dev/null
+++ b/general-concepts/herds-and-projects/text.rst
@@ -0,0 +1,20 @@
+Herds and Projects
+==================
+
+A *herd* is a collection of developers who maintain a collection of related
+packages. A herd has an associated email address which can be used for bugzilla
+assignments. This email address is **not** always ``herdname@gentoo.org`` -- for
+example, because of the way Gentoo's email aliases are set up, the ``cron`` herd
+use ``cron-bugs@gentoo.org`` (aliases cannot match system usernames).
+
+A *project* is a group formed for handling a particular general area. A project
+may have herds associated with it.
+
+Sometimes herd and project names overlap -- for example, the ``sparc`` project
+has an associated ``sparc`` herd which maintains sparc-specific packages (such
+as the ``silo`` bootloader). This is *not* always the case.
+
+The ``herdstat`` tool can display useful information about herds.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/general-concepts/install-destinations/text.rst b/general-concepts/install-destinations/text.rst
new file mode 100644
index 0000000..5fd0413
--- /dev/null
+++ b/general-concepts/install-destinations/text.rst
@@ -0,0 +1,20 @@
+Install Destinations
+====================
+
+When an ebuild runs the ``src_install`` phase, it installs an image of the
+package in question from ``${S}`` into ``${D}``. Ebuilds must *not* attempt to
+perform any operation upon the live filesystem at this stage -- this will break
+binaries, and will (often) cause a sandbox violation notice.
+
+When installing, portage will install the image in ``${D}`` into ``${ROOT}``. By
+default, ``${ROOT}`` points to ``/``, although the user can alter this -- for
+example, the user may be building a minimal image for another system in a
+different location. If your package must operate on the live filesystem (for
+example, to create some cache files during ``pkg_postinst``), you must ensure
+that you prefix any paths with ``${ROOT}``.
+
+When inside ``pkg_preinst``, the image to be installed can be accessed under
+``"${IMAGE}"``.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/general-concepts/licenses/text.rst b/general-concepts/licenses/text.rst
new file mode 100644
index 0000000..243a538
--- /dev/null
+++ b/general-concepts/licenses/text.rst
@@ -0,0 +1,20 @@
+Licenses
+========
+
+All ebuilds must specify a ``LICENSE`` (note the American English spelling)
+variable. The value of this variable must be the name of a file in the portage
+tree's ``licenses/`` directory.
+
+Adding New Licenses
+-------------------
+
+If your package's license is not already in the tree, you must add the license
+before committing the package. When adding the license, use a plain text file if
+at all possible. Some licenses are PDF files rather than plain text -- this
+should only be done if we are legally required to do so.
+
+It is not normally necessary to mail the ``gentoo-dev`` list before adding a new
+license. You should only do so if the license could be considered 'questionable'
+or if you are unsure as to the meaning of any part of it.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/general-concepts/linguas/text.rst b/general-concepts/linguas/text.rst
new file mode 100644
index 0000000..13f6ca5
--- /dev/null
+++ b/general-concepts/linguas/text.rst
@@ -0,0 +1,11 @@
+Linguas
+=======
+
+.. Todo:: Write this. From vapier: "used to specify languages users wish to have
+ support for. USE=nls covers generally natural language support, but LINGUAS
+ covers specific languages (see the games-rpg/nwn for example). the variable
+ is expanded for USE access in ebuilds. LINGUAS=de would automatically add
+ 'linguas_de' to USE." We also need strip-linguas examples.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/general-concepts/mirrors/diagram.svg b/general-concepts/mirrors/diagram.svg
new file mode 100644
index 0000000..0af1f1c
--- /dev/null
+++ b/general-concepts/mirrors/diagram.svg
@@ -0,0 +1,521 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://web.resource.org/cc/"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://inkscape.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ sodipodi:docbase="/home/plasmaroo"
+ sodipodi:docname="diagram.svg"
+ inkscape:version="0.41"
+ sodipodi:version="0.32"
+ version="1.0"
+ x="0.0000000"
+ y="0.0000000"
+ width="700.00000px"
+ height="250.00000px"
+ viewBox="0 0 700 250"
+ id="svg1546">
+ <metadata
+ id="metadata71">
+ <rdf:RDF
+ id="RDF73">
+ <cc:Work
+ id="Work75"
+ rdf:about="">
+ <dc:format
+ id="format77">image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage"
+ id="type79" />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <sodipodi:namedview
+ inkscape:current-layer="svg1546"
+ inkscape:window-y="264"
+ inkscape:window-x="164"
+ inkscape:cy="81.156529"
+ inkscape:cx="343.48587"
+ inkscape:zoom="0.97294509"
+ inkscape:window-height="541"
+ inkscape:window-width="968"
+ inkscape:pageshadow="2"
+ inkscape:pageopacity="1.0000000"
+ borderopacity="1.0"
+ bordercolor="#666666"
+ pagecolor="#eeeeee"
+ id="base" />
+ <defs
+ id="defs1680" />
+ <desc
+ id="desc1548">CVS to RSYNC Propagation</desc>
+ <rect
+ y="0.24284256"
+ x="-2.0556145"
+ height="260.03522"
+ width="710.21484"
+ id="rect1360"
+ style="fill:#eeeeee;fill-opacity:1.0000000;fill-rule:evenodd;stroke:none;stroke-width:1.0000000px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="10.000000"
+ y="110.00000"
+ style="fill:#ffcccc;stroke:#000000;stroke-width:2.0000000"
+ id="rect1551" />
+ <text
+ x="50"
+ y="130"
+ style="text-anchor:middle"
+ id="text1553">Developers</text>
+ <line
+ id="line1555"
+ stroke="black"
+ stroke-width="2"
+ y2="125.00000"
+ x2="130.00000"
+ y1="125.00000"
+ x1="90.000000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1557"
+ stroke="black"
+ stroke-width="2"
+ y2="120.00000"
+ x2="122.00000"
+ y1="125.00000"
+ x1="130.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1559"
+ stroke="black"
+ stroke-width="2"
+ y2="130.00000"
+ x2="122.00000"
+ y1="125.00000"
+ x1="130.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="10.000000"
+ y="60.000000"
+ style="fill:#ffcccc;stroke:#000000;stroke-width:2.0000000"
+ id="rect1561" />
+ <text
+ x="50"
+ y="80"
+ style="text-anchor:middle"
+ id="text1563">Developers</text>
+ <path
+ d="M 90.000000,75.000000 C 103.33333,75.000000 110.00000,83.333333 110.00000,100.00000 C 110.00000,120.00000 116.66667,128.33333 130.00000,125.00000"
+ style="fill:none;stroke:#000000;stroke-width:2.0000000"
+ id="path1565" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="10.000000"
+ y="160.00000"
+ style="fill:#ffcccc;stroke:#000000;stroke-width:2.0000000"
+ id="rect1567" />
+ <text
+ x="50"
+ y="180"
+ style="text-anchor:middle"
+ id="text1569">Developers</text>
+ <path
+ d="M 90.000000,175.00000 C 103.33333,175.00000 110.00000,166.66667 110.00000,150.00000 C 110.00000,130.00000 116.66667,121.66667 130.00000,125.00000"
+ style="fill:none;stroke:#000000;stroke-width:2.0000000"
+ id="path1571" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="130.00000"
+ y="110.00000"
+ style="fill:#ffffff;stroke:#000000;stroke-width:2.0000000"
+ id="rect1573" />
+ <text
+ x="170"
+ y="130"
+ style="text-anchor:middle"
+ id="text1575">dev.gentoo</text>
+ <line
+ id="line1577"
+ stroke="black"
+ stroke-width="2"
+ y2="125.00000"
+ x2="250.00000"
+ y1="125.00000"
+ x1="210.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1579"
+ stroke="black"
+ stroke-width="2"
+ y2="120.00000"
+ x2="242.00000"
+ y1="125.00000"
+ x1="250.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1581"
+ stroke="black"
+ stroke-width="2"
+ y2="130.00000"
+ x2="242.00000"
+ y1="125.00000"
+ x1="250.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="250.00000"
+ y="110.00000"
+ style="fill:#ffffff;stroke:#000000;stroke-width:2.0000000"
+ id="rect1583" />
+ <text
+ x="290"
+ y="123"
+ style="text-anchor:middle"
+ id="text1585">Staging</text>
+ <text
+ x="290"
+ y="135"
+ style="text-anchor:middle"
+ id="text1587">Box</text>
+ <line
+ id="line1589"
+ stroke="black"
+ stroke-width="2"
+ y2="125.00000"
+ x2="370.00000"
+ y1="125.00000"
+ x1="330.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1591"
+ stroke="black"
+ stroke-width="2"
+ y2="120.00000"
+ x2="362.00000"
+ y1="125.00000"
+ x1="370.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1593"
+ stroke="black"
+ stroke-width="2"
+ y2="130.00000"
+ x2="362.00000"
+ y1="125.00000"
+ x1="370.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="370.00000"
+ y="110.00000"
+ style="fill:#ffffff;stroke:#000000;stroke-width:2.0000000"
+ id="rect1595" />
+ <text
+ x="410"
+ y="130"
+ style="text-anchor:middle"
+ id="text1597">OSU Mirrors</text>
+ <line
+ id="line1599"
+ stroke="black"
+ stroke-width="2"
+ y2="70.000000"
+ x2="482.00000"
+ y1="75.000000"
+ x1="490.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1601"
+ stroke="black"
+ stroke-width="2"
+ y2="80.000000"
+ x2="482.00000"
+ y1="75.000000"
+ x1="490.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <path
+ d="M 450.00000,125.00000 C 463.33333,125.00000 470.00000,116.66667 470.00000,100.00000 C 470.00000,80.000000 476.66667,71.666667 490.00000,75.000000"
+ style="fill:none;stroke:#000000;stroke-width:2.0000000"
+ id="path1603" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="490.00000"
+ y="60.000000"
+ style="fill:#ccffcc;stroke:#000000;stroke-width:2.0000000"
+ id="rect1605" />
+ <text
+ x="530"
+ y="80"
+ style="text-anchor:middle"
+ id="text1607">Public mirror</text>
+ <line
+ id="line1609"
+ stroke="black"
+ stroke-width="2"
+ y2="125.00000"
+ x2="490.00000"
+ y1="125.00000"
+ x1="450.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1611"
+ stroke="black"
+ stroke-width="2"
+ y2="120.00000"
+ x2="482.00000"
+ y1="125.00000"
+ x1="490.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1613"
+ stroke="black"
+ stroke-width="2"
+ y2="130.00000"
+ x2="482.00000"
+ y1="125.00000"
+ x1="490.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="490.00000"
+ y="110.00000"
+ style="fill:#ccffcc;stroke:#000000;stroke-width:2.0000000"
+ id="rect1615" />
+ <text
+ x="530"
+ y="130"
+ style="text-anchor:middle"
+ id="text1617">Public mirror</text>
+ <line
+ id="line1619"
+ stroke="black"
+ stroke-width="2"
+ y2="170.00000"
+ x2="482.00000"
+ y1="175.00000"
+ x1="490.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1621"
+ stroke="black"
+ stroke-width="2"
+ y2="180.00000"
+ x2="482.00000"
+ y1="175.00000"
+ x1="490.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <path
+ d="M 450.00000,125.00000 C 463.33333,125.00000 470.00000,133.33333 470.00000,150.00000 C 470.00000,170.00000 476.66667,178.33333 490.00000,175.00000"
+ style="fill:none;stroke:#000000;stroke-width:2.0000000"
+ id="path1623" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="490.00000"
+ y="160.00000"
+ style="fill:#ccffcc;stroke:#000000;stroke-width:2.0000000"
+ id="rect1625" />
+ <text
+ x="530"
+ y="180"
+ style="text-anchor:middle"
+ id="text1627">Public mirror</text>
+ <line
+ id="line1629"
+ stroke="black"
+ stroke-width="2"
+ y2="20.000000"
+ x2="602.00000"
+ y1="25.000000"
+ x1="610.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1631"
+ stroke="black"
+ stroke-width="2"
+ y2="30.000000"
+ x2="602.00000"
+ y1="25.000000"
+ x1="610.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <path
+ d="M 570.00000,75.000000 C 583.33333,75.000000 590.00000,66.666667 590.00000,50.000000 C 590.00000,30.000000 596.66667,21.666667 610.00000,25.000000"
+ style="fill:none;stroke:#000000;stroke-width:2.0000000"
+ id="path1633" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="610.00000"
+ y="10.000000"
+ style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000"
+ id="rect1635" />
+ <text
+ x="650"
+ y="30"
+ style="text-anchor:middle"
+ id="text1637">Users</text>
+ <line
+ id="line1639"
+ stroke="black"
+ stroke-width="2"
+ y2="75.000000"
+ x2="610.00000"
+ y1="75.000000"
+ x1="570.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1641"
+ stroke="black"
+ stroke-width="2"
+ y2="70.000000"
+ x2="602.00000"
+ y1="75.000000"
+ x1="610.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1643"
+ stroke="black"
+ stroke-width="2"
+ y2="80.000000"
+ x2="602.00000"
+ y1="75.000000"
+ x1="610.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="610.00000"
+ y="60.000000"
+ style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000"
+ id="rect1645" />
+ <text
+ x="650"
+ y="80"
+ style="text-anchor:middle"
+ id="text1647">Users</text>
+ <line
+ id="line1649"
+ stroke="black"
+ stroke-width="2"
+ y2="125.00000"
+ x2="610.00000"
+ y1="125.00000"
+ x1="570.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1651"
+ stroke="black"
+ stroke-width="2"
+ y2="120.00000"
+ x2="602.00000"
+ y1="125.00000"
+ x1="610.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1653"
+ stroke="black"
+ stroke-width="2"
+ y2="130.00000"
+ x2="602.00000"
+ y1="125.00000"
+ x1="610.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="610.00000"
+ y="110.00000"
+ style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000"
+ id="rect1655" />
+ <text
+ x="650"
+ y="130"
+ style="text-anchor:middle"
+ id="text1657">Users</text>
+ <line
+ id="line1659"
+ stroke="black"
+ stroke-width="2"
+ y2="175.00000"
+ x2="610.00000"
+ y1="175.00000"
+ x1="570.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1661"
+ stroke="black"
+ stroke-width="2"
+ y2="170.00000"
+ x2="602.00000"
+ y1="175.00000"
+ x1="610.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1663"
+ stroke="black"
+ stroke-width="2"
+ y2="180.00000"
+ x2="602.00000"
+ y1="175.00000"
+ x1="610.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="610.00000"
+ y="160.00000"
+ style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000"
+ id="rect1665" />
+ <text
+ x="650"
+ y="180"
+ style="text-anchor:middle"
+ id="text1667">Users</text>
+ <line
+ id="line1669"
+ stroke="black"
+ stroke-width="2"
+ y2="220.00000"
+ x2="602.00000"
+ y1="225.00000"
+ x1="610.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <line
+ id="line1671"
+ stroke="black"
+ stroke-width="2"
+ y2="230.00000"
+ x2="602.00000"
+ y1="225.00000"
+ x1="610.00000"
+ style="stroke:#000000;stroke-width:2.0000000" />
+ <path
+ d="M 570.00000,175.00000 C 583.33333,175.00000 590.00000,183.33333 590.00000,200.00000 C 590.00000,220.00000 596.66667,228.33333 610.00000,225.00000"
+ style="fill:none;stroke:#000000;stroke-width:2.0000000"
+ id="path1673" />
+ <rect
+ width="80.000000"
+ height="30.000000"
+ x="610.00000"
+ y="210.00000"
+ style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000"
+ id="rect1675" />
+ <text
+ x="650"
+ y="230"
+ style="text-anchor:middle"
+ id="text1677">Users</text>
+</svg>
diff --git a/general-concepts/mirrors/text.rst b/general-concepts/mirrors/text.rst
new file mode 100644
index 0000000..b42647e
--- /dev/null
+++ b/general-concepts/mirrors/text.rst
@@ -0,0 +1,59 @@
+Mirrors
+=======
+
+Automatic Mirroring
+-------------------
+
+Packages will automatically have their ``SRC_URI`` components mirrored onto
+Gentoo mirrors. When fetching, portage checks Gentoo mirrors first before
+trying the original upstream location.
+
+This is generally desired behaviour -- upstream mirrors are prone to being
+rearranged, tidied out or having files modified.
+
+Restricting Automatic Mirroring
+'''''''''''''''''''''''''''''''
+
+Three ``RESTRICT`` keywords can be used to control the mirroring process.
+
+The ``RESTRICT="nomirror"`` setting should be used if we cannot legally mirror
+certain files.
+
+The ``RESTRICT="primaryuri"`` setting causes portage to try
+original locations *first*, and then fall back to mirrors if necessary -- this
+is sometimes useful if approximate download counts are needed, or if upstream
+have a reliable mirror setup.
+
+There is also ``RESTRICT="fetch"``, which prevents portage from trying to
+fetch anything manually. The `pkg_nofetch`_ function will be called if any
+``SRC_URI`` components cannot be found. This should only be used if a licence
+requires it.
+
+Suitable Download Hosts
+'''''''''''''''''''''''
+
+Hosting files off ``dev.gentoo.org`` is **not** acceptable for main-tree items.
+Instead, these files must be moved onto ``mirror://gentoo`` before release.
+
+Gentoo Mirrors
+--------------
+
+To manually upload a file to ``mirror://gentoo``, ``scp`` it to
+``dev.gentoo.org:/space/distfiles-local``. You must ensure that the permissions
+are set to ``ug+rw`` manually. The file should appear on the mirrors within four
+hours (note that this is *less frequent* than `CVS to rsync`_).
+
+If the upstream download location for a package uses a non-standard TCP port
+(anything other than 21, 80 or 443), you *must* manually mirror the files. Not
+doing so can cause all kinds of problems with strict firewalls.
+
+Mirroring Process
+-----------------
+
+.. figure:: diagram.png
+ :alt: Mirroring Process
+
+ Diagram showing the mirroring process
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/general-concepts/overlay/text.rst b/general-concepts/overlay/text.rst
new file mode 100644
index 0000000..483a7b3
--- /dev/null
+++ b/general-concepts/overlay/text.rst
@@ -0,0 +1,35 @@
+Overlay
+=======
+
+Portage can look in multiple places for packages by using an overlay. The
+locations of overlays are controlled by the ``PORTDIR_OVERLAY`` variable, which
+should contain a space-separated list of paths.
+
+The overlay should contain the same directory structure as ``PORTDIR`` (although
+only the necessary directories need be included). For example, a simple overlay
+might have a directory structure like: ::
+
+ overlay
+ |-- dev-util
+ `-- gengetopt
+ |-- Manifest
+ |-- files
+ | `-- digest-gengetopt-2.13
+ `-- gengetopt-2.13.ebuild
+
+An overlay can be used to 'add' items to the tree (although you must ensure that
+``/etc/portage/categories`` is used if any new categories are added) or to
+override existing entries.
+
+Overlay and Eclasses
+--------------------
+
+Be very careful when using eclasses in an overlay. Portage will not do cache
+updates when an overlay eclass is changed, nor will it do cache updates when a
+main portage tree eclass which is used by an overlay ebuild changes. You may
+also encounter bogus 'illegal inherit' notices when working with eclasses in
+overlay (see `QA Notice -- ECLASS foo inherited illegally`_). To be safe,
+manually ``touch`` all relevant overlay files after updating overlay eclasses.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/general-concepts/pic/text.rst b/general-concepts/pic/text.rst
new file mode 100644
index 0000000..fdd31a4
--- /dev/null
+++ b/general-concepts/pic/text.rst
@@ -0,0 +1,9 @@
+Position Independent Code
+=========================
+
+.. Todo:: policy. http://www.gentoo.org/proj/en/hardened/pic-internals.xml has
+ some technical details.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
+
diff --git a/general-concepts/portage-cache/bad-cache-dep-sample.ebuild b/general-concepts/portage-cache/bad-cache-dep-sample.ebuild
new file mode 100644
index 0000000..bf9cd1c
--- /dev/null
+++ b/general-concepts/portage-cache/bad-cache-dep-sample.ebuild
@@ -0,0 +1,8 @@
+# HEADER
+
+# DO NOT DO THIS!
+if ! has_version "x11-libs/gtk+" ; then
+ DEPEND="${DEPEND}
+ gtk2? ( >=x11-libs/gtk+-2 )
+ !gtk2? ( =x11-libs/gtk+-1.2* )"
+fi
diff --git a/general-concepts/portage-cache/conditional-inherit.ebuild b/general-concepts/portage-cache/conditional-inherit.ebuild
new file mode 100644
index 0000000..34fa096
--- /dev/null
+++ b/general-concepts/portage-cache/conditional-inherit.ebuild
@@ -0,0 +1,5 @@
+# header
+
+if [[ "${PN##*-}" == "cvs" ]] ; then
+ inherit cvs
+fi
diff --git a/general-concepts/portage-cache/good-cache-dep-sample.ebuild b/general-concepts/portage-cache/good-cache-dep-sample.ebuild
new file mode 100644
index 0000000..d4473bc
--- /dev/null
+++ b/general-concepts/portage-cache/good-cache-dep-sample.ebuild
@@ -0,0 +1,17 @@
+# Header
+
+inherit versionator
+
+if [[ $(get_major_version ) -ge 7 ]] ; then
+ IUSE="${IUSE} tcltk mzscheme"
+ DEPEND="$DEPEND
+ tcltk? ( dev-lang/tcl )
+ mzscheme? ( dev-lisp/mzscheme )"
+ RDEPEND="$RDEPEND
+ tcltk? ( dev-lang/tcl )
+ mzscheme? ( dev-lisp/mzscheme )"
+
+ if [[ "${MY_PN}" != "vim-core" ]] ; then
+ RDEPEND="${RDEPEND} !<app-vim/align-30-r1"
+ fi
+fi
diff --git a/general-concepts/portage-cache/text.rst b/general-concepts/portage-cache/text.rst
new file mode 100644
index 0000000..abb77f8
--- /dev/null
+++ b/general-concepts/portage-cache/text.rst
@@ -0,0 +1,33 @@
+The Portage Cache
+==================
+
+Portage uses a cache for most top-level variables (``DEPEND``, ``DESCRIPTION``,
+``SRC_URI`` and so on). This cache may be generated on a different machine, so
+these variables must be either static or generated using only unchanging
+'version / name' variables (``P``, ``PN``, ``PV``, ``PR``, ``PVR`` and ``PF``).
+
+So, the following will not work:
+
+.. CODESAMPLE bad-cache-dep-sample.ebuild
+
+However, this is legal, since ``versionator.eclass`` works upon ``PV``, and
+``PV`` and ``PN`` are both static:
+
+.. CODESAMPLE good-cache-dep-sample.ebuild
+
+Conditional Inherits
+--------------------
+
+Because eclasses modify various cached variables, conditional inheritance is not
+allowed except where the same results will always be obtained on every system.
+For example, inherits based upon USE flags are illegal, but inherits based
+solely upon ``PN`` are allowed.
+
+As an example of a legal and possibly useful conditional inherit, some eclasses
+do:
+
+.. CODESAMPLE conditional-inherit.ebuild
+
+This allows the same eclass to be used for both regular and ``-cvs`` packages.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/general-concepts/privileges/text.rst b/general-concepts/privileges/text.rst
new file mode 100644
index 0000000..4c0c62d
--- /dev/null
+++ b/general-concepts/privileges/text.rst
@@ -0,0 +1,9 @@
+Privileges
+==========
+
+.. Todo:: general privs stuff, include stuff on setuid/setgid and sticky since
+ a lot of people seem to be confused about those... Also notes on the portage
+ user and group issues, and what we use for root:root to make \*bsd work.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/general-concepts/sandbox/text.rst b/general-concepts/sandbox/text.rst
new file mode 100644
index 0000000..e40ea01
--- /dev/null
+++ b/general-concepts/sandbox/text.rst
@@ -0,0 +1,20 @@
+Sandbox
+=======
+
+During the ``src_unpack``, ``src_compile``, ``src_test`` and ``src_install``
+phases, ``ebuild.sh`` operates inside a *sandbox*. This is a special environment
+which attempts to help prevent badly written ebuilds (or ebuilds working with
+badly written build systems) accidentally writing outside of permitted locations.
+
+**All packages must build correctly when sandbox is active.** Packages must not
+achieve this by using sneaky tricks to make sandbox warnings not show up -- the
+sandbox is there to ensure that binary packages will work correctly, and that
+a badly written ``Makefile`` won't cause problems. Using ``addwrite`` is
+generally **not** the correct solution.
+
+See `Sandbox Functions Reference`_ for details on sandbox-related functions. See
+`Handling Access Violations`_ for suggestions on fixing sandbox-related build
+problems.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/general-concepts/slotting/text.rst b/general-concepts/slotting/text.rst
new file mode 100644
index 0000000..f9e9735
--- /dev/null
+++ b/general-concepts/slotting/text.rst
@@ -0,0 +1,34 @@
+Slotting
+========
+
+Packages can support having multiple versions installed simultaneously. This is
+useful for libraries which may have changed interfaces between versions -- for
+example, the ``gtk+`` package can install both versions ``1.2`` and ``2.6`` in
+parallel. This feature is called slotting.
+
+Most packages have no need for slotting. These packages specify ``SLOT="0"`` in
+the ebuilds. This is **not** the same as specifying an empty slot -- an empty
+slot means "disable slotting entirely", and should not be used.
+
+Portage permits at most one instance of a package installation *per ``SLOT``
+value*. For example, say we have the following:
+
+* ``foo-1.1`` with ``SLOT="1"``
+* ``foo-1.2`` with ``SLOT="1"``
+* ``foo-2.0`` with ``SLOT="2"``
+* ``foo-2.1`` with ``SLOT="2"``
+
+Then the user could have, say, ``foo-1.2`` and ``foo-2.0`` installed in
+parallel, but *not* ``foo-1.1`` and ``foo-1.2``. Note that it is entirely
+possible that the user may have ``foo-2.0`` installed and no ``foo-1.x`` at all.
+
+It is not possible to ``DEPEND`` upon a package in a specific slot.
+
+Currently portage will accept an arbitrary string for the value of ``SLOT``. For
+future compatibility, it is recommended that slots contain only characters which
+are allowed in an ebuild name or version (alphanumerics, hypens, full stops,
+underscores, the plus character) -- other characters may cause problems with
+future portage enhancements.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/general-concepts/text.rst b/general-concepts/text.rst
new file mode 100644
index 0000000..6057889
--- /dev/null
+++ b/general-concepts/text.rst
@@ -0,0 +1,9 @@
+General Concepts
+================
+
+This section covers some general concepts with which you should be familiar when
+writing ebuilds or working with the portage tree.
+
+.. CHILDLIST
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/general-concepts/tree/text.rst b/general-concepts/tree/text.rst
new file mode 100644
index 0000000..84974d2
--- /dev/null
+++ b/general-concepts/tree/text.rst
@@ -0,0 +1,121 @@
+The Portage Tree
+================
+
+The basic layout of the portage tree is as follows:
+
+* Categories, for example ``app-editors``, ``sys-apps``
+
+ + Category metadata, for example ``app-admin/metadata.xml``
+
+ + Package directories for example ``app-editors/vim``
+
+ - Package metadata, for example ``app-editors/vim/metadata.xml``
+
+ - Package changelog, for example ``app-editors/vim/ChangeLog``
+
+ - Package Manifest, for example ``app-editors/vim/Manifest``
+
+ - Ebuilds, for example ``app-editors/vim/vim-6.3.068.ebuild``,
+ ``app-editors/vim/vim-7.0_alpha20050326.ebuild``
+
+ - Package files directory, for example ``app-editors/vim/files``
+
+ * Digest files, for example
+ ``app-editors/vim/files/digest-vim-6.3.068``,
+ ``app-editors/vim/files/digest-vim-7.0_alpha20050326``
+
+ * Small patches and other miscellaneous files, for example
+ ``app-editors/vim/files/vim-completion``
+
+* Eclasses directory, ``eclass/``
+
+* Licenses directory, ``licenses/``
+
+* Profiles directory, ``profiles/``
+
+ + Various control and documentation files, for example ``categories``,
+ ``info_pkgs``, ``info_vars``, ``package.mask``, ``use.desc``
+
+ + Updates directory, ``profiles/updates/``
+
+ - Updates files, for example ``profiles/updates/1Q-2005``
+
+ + Main profile cascade
+
+* Scripts directory, ``scripts/``
+
+* Distfiles directory, ``distfiles/``. This is not included in the main CVS
+ tree, but it will be found on most user systems.
+
+* Packages directory, ``packages``. Again, this is found on user systems but not
+ in the main CVS tree.
+
+What Belongs in the Tree?
+-------------------------
+
+Things that do **not** belong in the tree:
+
+* Large patches
+* Non-text files
+* Photos of teletubbies
+* Files whose name starts with a dot
+
+Software-wise, in general all of the following should be met in order for a
+package to be included in the tree:
+
+Active, Cooperative Upstream
+ If a package is undeveloped or unmaintained upstream, it can be extremely
+ difficult to get problems fixed. If a package does not have an active
+ upstream, the developers who add the package to the tree must ensure that
+ they are able to fix any issues which may arise.
+
+ Sometimes upstream may have a reason for not wanting their package included
+ in the tree. This should be respected.
+
+Reasonably Stable
+ Keep super-experimental things out of the tree. If you must commit them,
+ consider using ``package.mask`` until things calm down, or better yet make
+ them available as overlay ebuilds.
+
+Reasonably Useful
+ Don't feel obliged to include "Joe's '1337 XMMS Skinz Collection" or "Hans'
+ Super Cool Fast File System" in the tree just because a few users ask for
+ it. Stick to things that might actually be of use.
+
+Properly Packaged
+ If something is only available in live CVS or dodgy autopackage format,
+ don't include it until upstream can come up with a decent source package.
+ Similarly, avoid things that don't have a proper build system (where
+ relevant) -- these are very tricky to maintain.
+
+Patching and Distribution Permitted
+ If we can't patch packages as necessary ourselves, we end up relying
+ entirely upon upstream for support. This can be problematic, especially if
+ upstream are slow at fixing things. We don't want to be in the situation
+ where we can't stable a critical package because we're still waiting for a
+ closed-source vendor to get their act together.
+
+ Similarly, not being able to mirror and distribute tarballs ourselves makes
+ us rely entirely upon upstream mirrors. Experience has shown that these are
+ often extremely unreliable, with files changing, moving or vanishing at
+ random.
+
+Working Ebuilds
+ If you don't have a *working* ebuild, don't include it.
+
+Portable
+ If software is unportable, it's generally because it's badly written.
+ Remember that although x86 has a market majority *now*, it probably won't in
+ the not too distant future once x86-64 catches on.
+
+Reasonable Security Record
+ Don't include software that has a terrible security record. Each
+ vulnerability is a *lot* of work for a lot of people (security teams, arch
+ teams and package maintainers).
+
+Obviously, sometimes exceptions are necessary. We include PHP in the tree
+*despite* its security record, for example, because it's a popular package and
+we're 'expected' to have it. These are merely guidelines.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/general-concepts/use-flags/conflicting-flags.ebuild b/general-concepts/use-flags/conflicting-flags.ebuild
new file mode 100644
index 0000000..29b9905
--- /dev/null
+++ b/general-concepts/use-flags/conflicting-flags.ebuild
@@ -0,0 +1,20 @@
+# Header
+
+src_compile() {
+ local myconf
+
+ if use ssl && use gnutls ; then
+ myconf="${myconf} --enable-ssl --with-ssl=gnutls"
+ elif use ssl && ! use gnutls ; then
+ myconf="${myconf} --enable-ssl --with-ssl=openssl"
+ else
+ myconf="${myconf} --disable-ssl"
+ fi
+
+ econf \
+ # Other stuff
+ ${myconf} \
+ || die "configure failed
+
+ emake || die "make failed"
+}
diff --git a/general-concepts/use-flags/noblah-1.ebuild b/general-concepts/use-flags/noblah-1.ebuild
new file mode 100644
index 0000000..07618e4
--- /dev/null
+++ b/general-concepts/use-flags/noblah-1.ebuild
@@ -0,0 +1,3 @@
+# Header
+
+RDEPEND="x86? ( fakemedia? ( >=media-libs/fakemedia-1.1 ) )"
diff --git a/general-concepts/use-flags/noblah-2.ebuild b/general-concepts/use-flags/noblah-2.ebuild
new file mode 100644
index 0000000..b653ce5
--- /dev/null
+++ b/general-concepts/use-flags/noblah-2.ebuild
@@ -0,0 +1,3 @@
+# Header
+
+DEPEND="!sparc? ( !alpha? ( alsa? ( media-libs/alsa-lib ) ) )"
diff --git a/general-concepts/use-flags/noblah-3.ebuild b/general-concepts/use-flags/noblah-3.ebuild
new file mode 100644
index 0000000..bbcaefa
--- /dev/null
+++ b/general-concepts/use-flags/noblah-3.ebuild
@@ -0,0 +1,3 @@
+# Header
+
+RDEPEND="fakemedia? ( >=media-libs/fakemedia-1-1 )"
diff --git a/general-concepts/use-flags/noblah-4.ebuild b/general-concepts/use-flags/noblah-4.ebuild
new file mode 100644
index 0000000..5676176
--- /dev/null
+++ b/general-concepts/use-flags/noblah-4.ebuild
@@ -0,0 +1,3 @@
+# Header
+
+RDEPEND="!noalsa? ( media-libs/alsa )"
diff --git a/general-concepts/use-flags/text.rst b/general-concepts/use-flags/text.rst
new file mode 100644
index 0000000..98f205c
--- /dev/null
+++ b/general-concepts/use-flags/text.rst
@@ -0,0 +1,130 @@
+USE Flags
+=========
+
+USE flags are to control *optional* dependencies and settings which the user may
+reasonably want to select. For example, ``vim`` can optionally build with
+support for the ``ruby`` interpreter, and it needs ``ruby`` installed to do this
+-- we use the ``ruby`` USE flag to provide this option. On the other hand,
+``glark`` requires ``ruby`` no matter what, so no USE flag is used here.
+
+No combination of USE flags should cause a package to fail to build.
+
+Packages should not configure and link based upon what is available at compile
+time -- any autodetection must be overridden.
+
+``noblah`` USE Flags
+--------------------
+
+If at all possible, avoid ``noblah`` style USE flags. These break ``use.mask``
+and cause all sorts of complications for arch developers. Here's why:
+
+Consider a hypothetical package named 'vplayer', which plays videos. This
+package has optional support, via USE flags, for various sound and video output
+methods, various video codecs and so on.
+
+One of vplayer's optional features is support for the 'fakemedia' codec, which
+is unfortunately only available as a dodgy x86 binary. We *could* handle this by
+doing something like:
+
+.. CODESAMPLE noblah-1.ebuild
+
+Except this is pretty nasty -- what happens when an amd64 binary is made as
+well? Also, users on other archs will see fakemedia listed in ``emerge -pv``
+output, even though it is not actually available.
+
+Similarly, say vplayer supports output via the ALSA codec as one option.
+However, ALSA isn't (or wasn't when this example was written) available on sparc
+or alpha. So we could do:
+
+.. CODESAMPLE noblah-2.ebuild
+
+Again, it's messy, and alsa still shows up in the ``emerge -pv`` output. Also,
+once ALSA starts working on sparc, every ebuild that does this would have to be
+manually edited.
+
+The solution is ``use.mask``, which is documented in `Profiles use.mask File`_.
+Each profile can have a ``use.mask`` file which can be used to forcibly disable
+certain USE flags on a given arch (or subarch, or subprofile). So, if the
+``fakemedia`` USE flag was use.masked on every non-x86 profile, the following
+would be totally legal and wouldn't break anything:
+
+.. CODESAMPLE noblah-3.ebuild
+
+Users of non-x86 would see the following when doing ``emerge -pv vplayer``: ::
+
+ [ebuild R ] media-video/vplayer-1.2 alsa -blah (-fakemedia) xyz
+
+To get a flag added to ``use.mask``, ask the relevant arch team.
+
+So what's the problem with ``noblah`` flags?
+
+There's no way to forcibly *enable* a given USE flag on a particular profile.
+So, something like:
+
+.. CODESAMPLE noblah-4.ebuild
+
+will make your package unusable by archs without ALSA support, and there is no
+way to fix it that doesn't involve adding in nasty ``arch?`` flags.
+
+Local and Global USE Flags
+--------------------------
+
+USE flags are categorised as either local or global. A global USE flag must
+satisfy several criteria:
+
+ * It is used by many different packages.
+ * It has a general non-specific purpose.
+
+The second point is important. If the effect of the ``thing`` USE flag upon
+``pkg-one`` is substantially different from the effect it has upon ``pkg-two``,
+then ``thing`` is not a suitable candidate for being made a global flag. In
+particular, note that if ``client`` and ``server`` USE flags are ever
+introduced, they can not be global USE flags for this reason.
+
+Before introducing a new global USE flag, it must be discussed on the gentoo-dev
+mailing list.
+
+USE Flag Descriptions
+---------------------
+
+All USE flags (excluding ``USE_EXPAND`` flags) must be described in either
+``use.desc`` or ``use.local.desc`` in the ``profiles/`` directory. See
+`portage-5`_ or the comments in these files for an explanation of the format.
+Remember to keep these files sorted.
+
+Conflicting USE Flags
+---------------------
+
+Occasionally, ebuilds will have conflicting USE flags for functionality.
+Checking for them and returning an error is *not* a viable solution. Instead,
+you must pick one of the USE flags in conflict to favour.
+
+One example comes from the ``msmtp`` ebuilds. The package can use either SSL
+with GnuTLS, SSL with OpenSSL, or no SSL at all. Because GnuTLS is more
+featureful than OpenSSL, it is favoured:
+
+.. CODESAMPLE conflicting-flags.ebuild
+
+USE_EXPAND and ARCH USE Flags
+-----------------------------
+
+The ``VIDEO_CARDS``, ``INPUT_DEVICES`` and ``LINGUAS`` variables are
+automatically expanded into USE flags. These are known as ``USE_EXPAND``
+variables. If the user has ``LINGUAS="en fr"`` in ``make.conf``, for example,
+then ``USE="linguas_en linguas_fr"`` will automatically be set by portage.
+
+The ``USE_EXPAND`` list is set in ``profiles/base/make.defaults`` as of Portage
+2.0.51.20. This must not be modified without discussion on the gentoo-dev list,
+and it must not be modified in any subprofile.
+
+The current architecture (eg ``x86``, ``sparc``, ``ppc-macos``) will
+automatically be set as a USE flag as well. See ``profiles/arch.list`` for a
+full list of valid architecture keywords, and `GLEP 22`_ for an explanation of
+the format.
+
+.. Warning:: It is a common misconception that the architecture variable is somehow
+ related to ``ACCEPT_KEYWORDS``. It isn't. Accepting ``x86`` keywords on
+ ``sparc``, for example, won't set ``USE="x86"``. Similarly, there are no
+ ``~arch`` USE flags, so don't try ``if use ~x86``.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/general-concepts/user-environment/filtering-1.ebuild b/general-concepts/user-environment/filtering-1.ebuild
new file mode 100644
index 0000000..225e368
--- /dev/null
+++ b/general-concepts/user-environment/filtering-1.ebuild
@@ -0,0 +1,8 @@
+# Header
+
+pkg_setup() {
+ # Unset all locale related variables, they can make the
+ # build fail.
+
+ eval unset ${!LC_*} LANG
+}
diff --git a/general-concepts/user-environment/text.rst b/general-concepts/user-environment/text.rst
new file mode 100644
index 0000000..8a4a11e
--- /dev/null
+++ b/general-concepts/user-environment/text.rst
@@ -0,0 +1,53 @@
+User Environment
+================
+
+User environment variables and ``make.conf`` settings get passed on to ebuilds.
+This can be useful -- it's how ``CFLAGS`` and friends work, for example -- but
+it can also result in nasty build-breaking variables like ``LANG`` and
+``LC_ALL`` getting through. Currently no sanitisation is performed upon the
+environment.
+
+Filtering Variables
+-------------------
+
+Certain variables will really really upset certain build systems. A good example
+is the locale variables (``LC_ALL`` et al), which if set to certain values will
+cause ``sed`` or ``grep`` expressions involving the likes of ``[A-Z]`` to fail.
+The easiest thing to do here is to ``unset`` or sanitise the offending variables
+inside ``pkg_setup``.
+
+The simplest way to unset all locale-related variables is:
+
+.. CODESAMPLE filtering-1.ebuild
+
+Not Filtering Variables
+-----------------------
+
+On the other hand, it is extremely important that certain user preferences are
+honoured as far as possible. A good example is ``CFLAGS``, which *must* be
+respected (selective filtering is fine, but outright ignoring is not). Ignoring
+``CFLAGS`` when compiling can cause serious problems:
+
+* Ignoring ``march/mcpu`` may force kernel or software emulation for certain
+ opcodes on some architectures. This can be *very* slow -- for example,
+ ``openssl`` built for SPARC v7 but run on v9 is around five times slower for
+ RSA operations.
+
+* Stripping certain ABI-related flags will break linkage.
+
+* Stripping certain ABI-related flags will result in invalid code being produced
+ for certain setups. In extreme cases, we could end up with daft things like
+ big endian code being produced for little endian CPUs.
+
+* If a user's ``march/mcpu/mtune`` is ignored, and an auto-detected setting is
+ used instead, GRP and stages will break. For example, ``i686`` stages could no
+ longer be produced on a ``pentium-4``, and ``v8`` stages could no longer be
+ produced on an ``UltraSparc``.
+
+Some packages do this by accident. For example, one might see
+``CFLAGS=-Wall`` in ``Makefile.am``. To fix this, either ``sed`` in the user's
+``CFLAGS``, or (the better solution) change the variable to ``AM_CFLAGS``, which
+will automatically be merged with the user's settings.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/hosted-projects/text.rst b/hosted-projects/text.rst
new file mode 100644
index 0000000..e716600
--- /dev/null
+++ b/hosted-projects/text.rst
@@ -0,0 +1,86 @@
+Hosted Projects
+===============
+
+The following guidelines have been proposed for hosted projects in an attempt to
+prevent a repeat of the ``genkernel`` disaster.
+
+Documentation Requirement
+-------------------------
+
+All hosted projects should have decent, up to date user and developer
+documentation. This documentation must be available *before the first release*,
+and not left as "something we'll do later (honest)".
+
+Our documentation team are happy to help out with GuideXMLification, translation
+etc. for the user documentation, but they *need* various things to do this:
+
++ Basic documentation to start with.
++ Basic information on the project or tool, such as:
+
+ * The goals
+ * The design specification
+ * An FAQ
+
++ To be informed of any updates, in advance if at all possible -- this is to
+ avoid having out of date recommendations in the documentation.
+
+Developer documentation is generally best left in the hands of the project
+maintainers.
+
+Portability
+-----------
+
+Gentoo runs on a large number of architectures. This is one of our big
+advantages over some other distributions. It is therefore important that any
+tools are made with portability in mind, *even if you originally think that your
+tool is only relevant for one arch*. It was this kind of assumption that meant
+that ``genkernel`` had to be completely rewritten when it suddenly became
+mandatory.
+
+In practice, this means the following:
+
+* Using a portable programming language -- no Java or C# for any Gentoo tools.
+ Bash, C and Python are good, especially since everyone already has those
+ installed.
+
+* Not making assumptions about the hardware or architecture. This covers various
+ things, depending upon the tool -- simple examples include:
+
+ + Not assuming that you are running on a 32bit little endian system.
+ + Not assuming that all computers have a VGA text console, or indeed any
+ kind of graphics capability.
+ + Not assuming that all computers use DOS disclabels.
+
+* Not relying too strongly upon particular implementations of various tools,
+ except where it has been agreed that we will always use a particular
+ implementation of said tool (it is safe to use ``GNU sed`` extensions, for
+ example, but *not* ``GNU find`` extensions).
+
+Open / Free
+-----------
+
+All hosted projects should use an appropriate open / free / libre licence.
+Typically this will be the GPL v2 for software, and the Creative Commons licence
+for documentation. However, reasonable exceptions can be made -- sometimes it
+makes more sense to use the LGPL or a \*BSD licence, and for application-specific
+projects going with the application's licence may make more sense (the
+``gentoo-syntax`` package for ``vim`` uses the ``vim`` licence, for example).
+
+Accessible
+----------
+
+Projects should be accessible to users with disabilities. Simple examples of how
+to go about this include:
+
++ Not relying solely upon colour to convey information.
++ Providing textual descriptions for any images.
++ Providing clear captions for dialogs, buttons, form fields and so on.
+
+Good places to look for further hints include:
+
++ The `GNOME Accessibility Project <http://developer.gnome.org/projects/gap/>`_
++ The `W3C Web Accessibility Initiative Guidelines
+ <http://www.w3.org/WAI/Resources/#gl>`_.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/index/text.rst b/index/text.rst
new file mode 100644
index 0000000..22690c9
--- /dev/null
+++ b/index/text.rst
@@ -0,0 +1,7 @@
+Index
+=====
+
+.. INDEX
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/keywording/keywording-1.ebuild b/keywording/keywording-1.ebuild
new file mode 100644
index 0000000..e675e60
--- /dev/null
+++ b/keywording/keywording-1.ebuild
@@ -0,0 +1,3 @@
+# Headers.
+
+KEYWORDS="x86 sparc mips ~ppc ~ppc-macos -ia64"
diff --git a/keywording/keywording-2.ebuild b/keywording/keywording-2.ebuild
new file mode 100644
index 0000000..2f1f4b8
--- /dev/null
+++ b/keywording/keywording-2.ebuild
@@ -0,0 +1,3 @@
+# Headers.
+
+KEYWORDS="-* x86 ppc"
diff --git a/keywording/text.rst b/keywording/text.rst
new file mode 100644
index 0000000..307bf98
--- /dev/null
+++ b/keywording/text.rst
@@ -0,0 +1,172 @@
+Keywording
+==========
+
+.. Note:: Terminology
+ The term 'package' refers to an entire directory, for example
+ ``app-editors/vim`` -- it does *not* refer to a specific version. The terms
+ 'ebuild' or 'package version' are used when this meaning is intended. This
+ distinction is important.
+
+Every ebuild should specify a ``KEYWORDS`` variable. This variable is used to
+indicate the suitability and stability of both the package and the ebuild on
+each given arch (``sparc``, ``ppc``, ``x86-obsd``...).
+
+.. Note:: The term 'arch' is used in this sense for historical reasons. As a result
+ of `GLEP 22`_ and the various non-Linux ports, this is no longer a particularly
+ accurate term.
+
+A sample ``KEYWORDS`` entry might look like:
+
+.. CODESAMPLE keywording-1.ebuild
+
+The different levels of keyword are:
+
+``arch`` (``x86``, ``ppc-macos``)
+ Both the package version *and* the ebuild are widely tested, known to work
+ and not have any serious issues on the indicated platform.
+
+``~arch`` (``~x86``, ``~ppc-macos``)
+ The package version and the ebuild are believed to work and do not have any
+ known serious bugs, but more testing is required before the package version
+ is considered suitable for ``arch``.
+
+No keyword
+ If a package has no keyword for a given arch, it means it is not known
+ whether the package will work, or that insufficient testing has occurred for
+ ``~arch``.
+
+``-arch`` (``-x86``, ``-ppc-macos``)
+ The package version will not work on the arch. This could be caused by badly
+ written code (for example, non-64-bit or endian clean code), relying upon
+ particular hardware (for example, a BIOS querying tool would not work on
+ non-BIOS architectures) or binary only packages.
+
+The ``-*`` keyword is special. It is used to indicate package versions which are
+not worth trying to test on unlisted archs. For example, a binary-only package
+which is only supported upstream on ``x86`` and ``ppc`` might use:
+
+.. CODESAMPLE keywording-2.ebuild
+
+This is different in implication from ``"x86 ppc"`` -- the former implies that
+it will not work on other archs, whereas the latter implies that it has not been
+tested.
+
+Do **not** use the ``*`` or ``~*`` special keywords in ebuilds.
+
+Equal Visibility Requirement
+----------------------------
+
+An ebuild **must not** depend upon any package that is of a lower keyword level
+than itself. For example, if ``foo-1.2`` depends upon ``bar-1.2``, and
+``bar-1.2`` is ``~x86``, then ``foo-1.2`` must **not** be marked stable on
+``x86`` unless ``bar-1.2`` is also stabilised.
+
+You may assume that if a user accepts ``~arch`` for a given arch then they also
+accept ``arch``.
+
+For optional dependencies, all *possible* dependencies must satisfy the above.
+Note that certain ``USE`` flags can be forcibly disabled on a per-profile basis
+-- talk to the arch teams if you require this. For either-or dependencies, *at
+least one* of the options must be of equal or better visibility than the
+package in question.
+
+Hard Masks
+----------
+
+The ``package.mask`` file can be used to 'hard mask' individual or groups of
+ebuilds. This should be used for testing ebuilds or beta releases of software,
+and may also be used if a package has serious compatibility problems. Packages
+which are not hard masked must **not** have a dependency upon hard masked
+packages.
+
+The only time it is acceptable for a user to see the ``Possibly a DEPEND
+problem`` error message is if they have manually changed visibility levels for a
+package (for example, through ``/etc/portage/``) and have missed a dependency.
+**You should never commit a change which could cause this error to appear on a
+user system**.
+
+Keywording New Packages
+-----------------------
+
+.. Important:: New packages should be marked as ``~arch`` only upon
+ architectures for which the committing developer has tested.
+
+Do **not** assume that your package works on all architectures. Do **not**
+assume that user submitted ebuilds will have correct ``KEYWORDS`` -- chances are
+they just copied from somewhere else. Do **not** assume that upstream's
+'supported architectures' list is correct. Do **not** assume that because your
+code is written in Perl / Python / Java / whatever that it will run on other
+archs (there is at least one case of a ``vim`` script which only worked on
+``x86``).
+
+Note that most (non-x86) archs expect you to be on the arch team and bugzilla
+alias if you are committing packages with keywords for that arch, and may have
+additional requirements of which you should be aware (on ``mips``, for example,
+there are multiple ABIs and byte orders to consider -- a package working on your
+``o32`` box may not work on ``o64`` or ``n32``). Contact the individual arch
+teams for details.
+
+Do **not** commit straight to ``arch``.
+
+Keywording on Upgrades
+----------------------
+
+When upgrading, drop all existing keywords from ``arch`` to ``~arch``, and leave
+any existing ``~arch`` keywords intact. This must be done even if you *think*
+you're just making a trivial fix -- there have been several examples of the
+stable tree getting broken this way.
+
+Sometimes you may need to remove a keyword because of new unresolved
+dependencies. If you do this, you **must** file a bug notifying the relevant
+arch teams.
+
+This also applies to revision bumps, not just to upstream version changes.
+
+Moving from ``~arch`` to ``arch``
+---------------------------------
+
+With the exception of ``x86``, moving a package from ``~arch`` to ``arch`` is
+done only by the relevant arch teams. If you have access to non-x86 but are not
+on the arch teams, you may wish to make individual arrangements -- the arch
+teams are happy for help, so long as they know what is going on.
+
+For a package to move to stable, the following guidelines must be met:
+
+* The package has spent a reasonable amount of time in ``~arch`` first. Thirty
+ days is the usual figure, although this is clearly only a guideline. For
+ critical packages, a much longer duration is expected. For small packages
+ which have only minor changes between versions, a shorter period is sometimes
+ appropriate.
+
+* The package must not have any non-``arch`` dependencies.
+
+* The package must not have any severe outstanding bugs or issues.
+
+* The package must be widely tested.
+
+* If the package is a library, it should be known not to break any package which
+ depends upon it.
+
+* (Excluding x86) the relevant arch team must agree to it.
+
+For security fixes, the "reasonable amount of time" guideline may be relaxed.
+See the `Vulnerability Treatment Policy
+<http://www.gentoo.org/security/en/vulnerability-policy.xml>`_.
+
+Removing Package Versions
+-------------------------
+
+When removing ebuild, ensure that you do not remove the most recent version at
+any given keyword level on any profile. The aim here is:
+
+* Never to force a downgrade. (Exception: occasionally you really do want to
+ force a downgrade, for example if the newly committed ``foo-1.3`` turns out
+ to be badly broken and that making everyone downgrade to ``foo-1.2`` is the
+ better option. This is rare.)
+
+* Do not break any existing dependencies.
+
+If you would like a particular package version moved to stable on certain archs
+so that you can tidy up, file a bug.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/profiles/categories/text.rst b/profiles/categories/text.rst
new file mode 100644
index 0000000..3df4874
--- /dev/null
+++ b/profiles/categories/text.rst
@@ -0,0 +1,13 @@
+Profiles ``categories`` File
+============================
+
+The ``profiles/categories`` file contains an asciibetically sorted list of all
+the valid categories in the portage tree. When adding a new category, remember
+to update and commit this file *before* making any related commits.
+
+The ``categories`` file is a straight list. For descriptions, see `Category
+Metadata`_.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
+
diff --git a/profiles/info_files/text.rst b/profiles/info_files/text.rst
new file mode 100644
index 0000000..39db2d0
--- /dev/null
+++ b/profiles/info_files/text.rst
@@ -0,0 +1,9 @@
+Profiles ``info_`` Files
+========================
+
+The ``profiles/info_pkgs`` file controls the packages whose versions are listed
+when ``emerge info`` is run. The ``profiles/info_vars`` file controls the
+displayed environment variables. Do not add to these files without discussion on
+the ``gentoo-dev`` mailing list.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/profiles/make.defaults/text.rst b/profiles/make.defaults/text.rst
new file mode 100644
index 0000000..6e866c0
--- /dev/null
+++ b/profiles/make.defaults/text.rst
@@ -0,0 +1,13 @@
+Profiles ``make.defaults`` File
+===============================
+
+The ``make.defaults`` file in ``profiles/`` provides a minimal set of defaults
+for the kinds of values which may be set in ``make.conf`` (``CFLAGS``, ``USE``,
+``FEATURES`` etc) along with certain control variables (eg ``USE_EXPAND``).
+These values can further be refined by additional ``make.defaults`` files in
+subprofiles.
+
+In general, ``make.defaults`` should not be modified without consulting the
+relevant arch team, or ``gentoo-dev`` for high-up ``make.defaults`` files.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/profiles/package.mask/text.rst b/profiles/package.mask/text.rst
new file mode 100644
index 0000000..f176e98
--- /dev/null
+++ b/profiles/package.mask/text.rst
@@ -0,0 +1,11 @@
+Profiles ``package.mask`` File
+==============================
+
+The ``package.mask`` file can be used to hard mask packages or certain versions
+of packages. This is often used when adding certain experimental (either in
+ebuild or upstream terms) packages to the tree. The format is described in
+`portage-5`_.
+
+This file can be used in subprofiles to mask packages only for certain setups.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/profiles/packages/text.rst b/profiles/packages/text.rst
new file mode 100644
index 0000000..e5c3427
--- /dev/null
+++ b/profiles/packages/text.rst
@@ -0,0 +1,9 @@
+Profiles ``packages`` File
+==========================
+
+The ``packages`` file in ``profiles/`` controls the packages pulled in by the
+``system`` target. The ``base/packages`` file must not be modified without
+discussion on the ``gentoo-dev`` list; subprofile overrides are up to the
+relevant arch teams.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/profiles/profiles.desc/text.rst b/profiles/profiles.desc/text.rst
new file mode 100644
index 0000000..dae6ea4
--- /dev/null
+++ b/profiles/profiles.desc/text.rst
@@ -0,0 +1,8 @@
+Profiles ``profiles.desc`` File
+===============================
+
+.. Todo:: find someone who knows exactly what this file's really used for with
+ current portage versions and what is and isn't allowed.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/profiles/text.rst b/profiles/text.rst
new file mode 100644
index 0000000..72d3055
--- /dev/null
+++ b/profiles/text.rst
@@ -0,0 +1,10 @@
+Profiles
+========
+
+This section provides details on the ``profiles/`` directory. All of these files
+are also documented in `portage-5`_.
+
+.. CHILDLIST
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/profiles/updates/text.rst b/profiles/updates/text.rst
new file mode 100644
index 0000000..3f74b8a
--- /dev/null
+++ b/profiles/updates/text.rst
@@ -0,0 +1,7 @@
+Profiles ``updates/`` Directory
+===============================
+
+.. Todo:: move and slotmove
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/profiles/use.desc/text.rst b/profiles/use.desc/text.rst
new file mode 100644
index 0000000..1980578
--- /dev/null
+++ b/profiles/use.desc/text.rst
@@ -0,0 +1,18 @@
+Profiles ``use.desc`` and ``use.local.desc`` Files
+==================================================
+
+The ``use.desc`` file contains a list of all global non-expanded ``USE`` flags,
+together with a short description. This file should not be modified without
+discussion on the ``gentoo-dev`` list.
+
+The ``use.local.desc`` file contains a list of all local ``USE`` flags, together
+with the relevant packages, and a short description. This file can be added to
+without general discussion.
+
+Having a small number of packages using identically named local ``USE`` flags is
+allowed. If the number starts to grow substantially, it may be worth proposing
+that the flag becomes a global -- see `Local and Global USE Flags`_.
+
+All non-expand flags must be listed in exactly one of these files.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/profiles/use.mask/text.rst b/profiles/use.mask/text.rst
new file mode 100644
index 0000000..dc52d8d
--- /dev/null
+++ b/profiles/use.mask/text.rst
@@ -0,0 +1,27 @@
+Profiles ``use.mask`` File
+==========================
+
+The ``use.mask`` file can be used to mark ``USE`` flags as unavailable on a
+particular profile. This can be useful for various reasons:
+
+* Masking hardware-specific feature flags. For example, ``mmx`` and ``sse`` are
+ only available on x86, ``altivec`` is only available on ``ppc`` and ``vis`` is
+ only available on sparc v9.
+
+* Disabling unavailable soft dependencies. A simple hypothetical example -- say
+ ``fooapp`` works on ``mips``, but has an optional dependency (controlled by
+ the ``bar`` flag) upon ``libbar``, which doesn't work on ``mips``. Then by
+ adding the ``bar`` flag to ``profiles/default-linux/mips/use.mask``,
+ ``fooapp`` could be made available to ``mips`` users with the unresolvable
+ dependency forcibly disabled.
+
+Note that ``use.mask`` is a per-flag thing, not per package's use of a given
+flag. This is one of the reasons that USE flags must have a specific well
+defined purpose.
+
+Updates to ``use.mask`` should be handled via the relevant arch team.
+
+See `noblah USE Flags`_ for more discussion.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/profiles/virtuals/text.rst b/profiles/virtuals/text.rst
new file mode 100644
index 0000000..a065379
--- /dev/null
+++ b/profiles/virtuals/text.rst
@@ -0,0 +1,10 @@
+Profiles ``virtuals`` Files
+===========================
+
+The ``virtuals`` files in ``profiles/`` control the default provider for
+virtuals. It can be overridden in subprofiles for profile-specific defaults.
+
+Before adding a new virtual, it should be discussed on ``gentoo-dev``.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/quickstart/ex1.ebuild b/quickstart/ex1.ebuild
new file mode 100644
index 0000000..31c878d
--- /dev/null
+++ b/quickstart/ex1.ebuild
@@ -0,0 +1,26 @@
+# Example
+
+# Copyright 1999-2005 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+# $Header: $
+
+DESCRIPTION="Exuberant ctags generates tags files for quick source navigation"
+HOMEPAGE="http://ctags.sourceforge.net"
+SRC_URI="mirror://sourceforge/ctags/${P}.tar.gz"
+
+LICENSE="GPL-2"
+SLOT="0"
+KEYWORDS="~mips ~sparc ~x86"
+IUSE=""
+
+src_compile() {
+ econf --with-posix-regex || die "econf failed"
+ emake || die "emake failed"
+}
+
+src_install() {
+ make DESTDIR="${D}" install || die "install failed"
+
+ dodoc FAQ NEWS README
+ dohtml EXTENDING.html ctags.html
+}
diff --git a/quickstart/ex2.ebuild b/quickstart/ex2.ebuild
new file mode 100644
index 0000000..5f2dd94
--- /dev/null
+++ b/quickstart/ex2.ebuild
@@ -0,0 +1,29 @@
+# Example
+
+# Copyright 1999-2005 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+# $Header: $
+
+DESCRIPTION="detox safely removes spaces and strange characters from filenames"
+HOMEPAGE="http://detox.sourceforge.net/"
+SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2"
+
+LICENSE="BSD"
+SLOT="0"
+KEYWORDS="~hppa mips sparc x86"
+IUSE=""
+
+DEPEND="dev-libs/popt
+ sys-devel/flex
+ sys-devel/bison"
+RDEPEND="dev-libs/popt"
+
+src_compile() {
+ econf --with-popt || die "econf failed"
+ emake || die "emake failed"
+}
+
+src_install() {
+ make DESTDIR="${D}" install || die "install failed"
+ dodoc README CHANGES
+}
diff --git a/quickstart/ex3.ebuild b/quickstart/ex3.ebuild
new file mode 100644
index 0000000..0d514b7
--- /dev/null
+++ b/quickstart/ex3.ebuild
@@ -0,0 +1,27 @@
+# Header
+
+# Copyright 1999-2005 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+# $Header: $
+
+DESCRIPTION="GNU charset conversion library for libc which doesn't implement it"
+SRC_URI="ftp://ftp.gnu.org/pub/gnu/libiconv/${P}.tar.gz"
+HOMEPAGE="http://www.gnu.org/software/libiconv/"
+
+SLOT="0"
+LICENSE="LGPL-2.1"
+KEYWORDS="~amd64 ~ppc ~sparc ~x86"
+IUSE="nls"
+
+DEPEND="virtual/libc
+ !sys-libs/glibc"
+
+src_compile() {
+ econf $(use_enable nls) || die "econf failed"
+ emake || die
+}
+
+src_install() {
+ make DESTDIR="${D}" install || die "install failed"
+}
+
diff --git a/quickstart/ex4.ebuild b/quickstart/ex4.ebuild
new file mode 100644
index 0000000..3142640
--- /dev/null
+++ b/quickstart/ex4.ebuild
@@ -0,0 +1,70 @@
+# Example
+
+# Copyright 1999-2005 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+# $Header: $
+
+inherit eutils
+
+DESCRIPTION="A lightweight email client and newsreader"
+HOMEPAGE="http://sylpheed.good-day.net/"
+SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2"
+
+LICENSE="GPL-2"
+KEYWORDS="alpha amd64 hppa ia64 ppc ppc64 sparc x86"
+SLOT="0"
+
+IUSE="crypt gnome imlib ipv6 ldap nls pda ssl xface"
+
+DEPEND="=x11-libs/gtk+-1.2*
+ nls? ( >=sys-devel/gettext-0.12.1 )
+ crypt? ( >=app-crypt/gpgme-0.4.5 )
+ gnome? ( media-libs/gdk-pixbuf )
+ imlib? ( media-libs/imlib )
+ ldap? ( >=net-nds/openldap-2.0.11 )
+ pda? ( app-pda/jpilot )
+ ssl? ( dev-libs/openssl )
+ xface? ( >=media-libs/compface-1.4 )"
+RDEPEND="${DEPEND}
+ app-misc/mime-types
+ x11-misc/shared-mime-info"
+
+src_unpack() {
+ unpack ${A}
+ cd "${S}"
+
+ epatch "${FILESDIR}"/${PN}-namespace.diff
+ epatch "${FILESDIR}"/${PN}-procmime.diff
+}
+
+src_compile() {
+
+ econf \
+ $(use_enable nls) \
+ $(use_enable ssl) \
+ $(use_enable crypt gpgme) \
+ $(use_enable pda jpilot) \
+ $(use_enable ldap) \
+ $(use_enable ipv6) \
+ $(use_enable imlib) \
+ $(use_enable gnome gdk-pixbuf) \
+ $(use_enable xface compface) \
+ || die
+
+ emake || die
+}
+
+src_install() {
+ einstall || die "einstall failed"
+ dodir /usr/share/pixmaps
+ insinto /usr/share/pixmaps
+ doins *.png
+
+ if use gnome ; then
+ dodir /usr/share/gnome/apps/Internet
+ insinto /usr/share/gnome/apps/Internet
+ doins sylpheed.desktop
+ fi
+
+ dodoc [A-Z][A-Z]* ChangeLog*
+}
diff --git a/quickstart/ex5.ebuild b/quickstart/ex5.ebuild
new file mode 100644
index 0000000..c6e3f18
--- /dev/null
+++ b/quickstart/ex5.ebuild
@@ -0,0 +1,40 @@
+# Header
+
+# Copyright 1999-2005 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+# $Header: $
+
+inherit eutils
+
+DESCRIPTION="detox safely removes spaces and strange characters from filenames"
+HOMEPAGE="http://detox.sourceforge.net/"
+SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2"
+
+LICENSE="BSD"
+SLOT="0"
+KEYWORDS="~hppa ~mips ~sparc ~x86"
+IUSE=""
+
+DEPEND="dev-libs/popt
+ sys-devel/flex
+ sys-devel/bison"
+RDEPEND="dev-libs/popt"
+
+src_unpack() {
+ unpack ${A}
+ cd "${S}"
+
+ epatch "${FILESDIR}"/${P}-destdir.patch
+ epatch "${FILESDIR}"/${P}-parallel_build.patch
+}
+
+src_compile() {
+ econf --with-popt || die "econf failed"
+ emake || die "emake failed"
+}
+
+src_install() {
+ make DESTDIR="${D}" install || die "install failed"
+ dodoc README CHANGES
+}
+
diff --git a/quickstart/text.rst b/quickstart/text.rst
new file mode 100644
index 0000000..02d5854
--- /dev/null
+++ b/quickstart/text.rst
@@ -0,0 +1,159 @@
+Quickstart Ebuild Guide
+=======================
+
+This page provides a *very* brief introduction to ebuild writing. It does not
+attempt to cover many of the details or problems that will be encountered by
+developers -- rather, it gives some trivial examples which may be of use when
+trying to grasp the basic idea of how ebuilds work.
+
+For proper coverage of all the ins and outs, see `Ebuild Writing`_. The `General
+Concepts`_ chapter will also be of use.
+
+Note that the examples used here, whilst based upon real tree ebuilds, have had
+several parts chopped out, changed and simplified.
+
+First Ebuild
+------------
+
+We'll start with an ebuild for the *Exuberant Ctags* utility, a source code
+indexing tool. Here's a simplified ``dev-util/ctags/ctags-5.5.4.ebuild`` (you
+can see real ebuilds in the main tree).
+
+.. CODESAMPLE ex1.ebuild
+
+Basic Format
+''''''''''''
+
+As you can see, ebuilds are just ``bash`` scripts that are executed within a
+special environment.
+
+At the top of the ebuild is a header block. This is present in all ebuilds.
+
+Ebuilds are indented using tabs, with each tab representing four places. See
+`Ebuild File Format`_.
+
+Information Variables
+'''''''''''''''''''''
+
+Next, there are a series of variables. These tell portage various things about
+the ebuild and package in question.
+
+The ``DESCRIPTION`` variable is set to a *short* description of the package and
+its purpose.
+
+The ``HOMEPAGE`` is a link to the package's homepage (remember to
+include the ``http://`` part).
+
+The ``LICENSE`` is ``GPL-2`` (the GNU General
+Public Licence version 2).
+
+The ``SRC_URI`` tells portage the address to use for
+downloading the source tarball. Here, ``mirror://sourceforge/`` is a special
+notation meaning "any of the Sourceforge mirrors". The ``${P}`` is a read-only
+variable set by portage which is the package's name and version -- in this case,
+it would be ``ctags-5.5.4``.
+
+The ``SLOT`` variable tells portage which slot this package installs to. If
+you've not seen slots before, either just use ``"0"`` or read `Slotting`_.
+
+The ``KEYWORDS`` variable is set to archs upon which this ebuild has been
+tested. We use ``~`` keywords for newly written ebuilds -- packages are not
+committed straight to stable, even if they seem to work. See `Keywording`_ for
+details.
+
+Build Functions
+'''''''''''''''
+
+Next, a function named ``src_compile``. Portage will call this function when it
+wants to *compile* the package. The ``econf`` function is a wrapper for calling
+``./configure``, and ``emake`` is a wrapper for ``make``. In both cases, the
+common ``|| die "something went wrong"`` idiom is used -- this is to ensure that
+if for some reason an error occurs, portage will stop rather than trying to
+continue with the install.
+
+The ``src_install`` function is called by portage when it wants to *install* the
+package. A slight subtlety here -- rather than installing straight to the live
+filesystem, we must install to a special location which is given by the ``${D}``
+variable (portage sets this -- see `Install Destinations`_ and `Sandbox`_).
+Again, we check for errors.
+
+.. Note:: The canonical install method is ``make DESTDIR="${D}" install``. This
+ will work with any properly written standard ``Makefile``. If this gives
+ sandbox errors, try ``einstall`` instead. If this still fails, see
+ `src_install`_ for how to do manual installs.
+
+The ``dodoc`` and ``dohtml`` are helper functions for installing files into the
+relevant part of ``/usr/share/doc``.
+
+Ebuilds can define other functions (see `Ebuild Functions`_). In all cases,
+portage provides a reasonable default implementation which quite often does the
+'right thing'. There was no need to define a ``src_unpack`` function here, for
+example -- this function is used to do any unpacking of tarballs or patching of
+source files, but the default implementation does everything we need.
+
+Ebuild with Dependencies
+------------------------
+
+In the ctags example, we didn't tell portage about any dependencies. As it
+happens, that's ok, because ctags only needs a basic toolchain to compile and
+run (see `Implicit System Dependency`_ for why we don't need to depend upon
+those explicitly). However, life is rarely that simple.
+
+Here's ``app-misc/detox/detox-1.1.1.ebuild``:
+
+.. CODESAMPLE ex2.ebuild
+
+Again, you can see the ebuild header and the various informational variables. In
+``SRC_URI``, ``${PN}`` is used to get the package's name *without* the version
+suffix (there are more of these variables -- see `Predefined Read-Only
+Variables`_).
+
+Again, we define ``src_compile`` and ``src_install`` functions.
+
+The ``DEPEND`` and ``RDEPEND`` variables are how portage determines which
+packages are needed to build and run the package. The ``DEPEND`` variable lists
+compile-time dependencies, and the ``RDEPEND`` lists runtime dependencies. See
+`Dependencies`_ for some more complex examples.
+
+Ebuild with Patches
+-------------------
+
+Often we need to apply patches. This is done in the ``src_unpack`` function
+using the ``epatch`` helper function. To use ``epatch`` one must first tell
+portage that the ``eutils`` eclass (an eclass is like a library) is required --
+this is done via ``inherit eutils`` at the top of the ebuild. Here's
+``app-misc/detox/detox-1.1.0.ebuild``:
+
+.. CODESAMPLE ex5.ebuild
+
+Note the ``${FILESDIR}/${P}-destdir.patch`` -- this refers to
+``detox-1.1.0-destdir.patch``, which lives in the ``files/`` subdirectory in the
+portage tree. Larger patch files must go on the mirrors rather than in
+``files/`` -- see `Basic epatch Usage`_.
+
+Ebuild with USE Flags
+---------------------
+
+Now for some ``USE`` flags. Here's ``dev-libs/libiconv/libiconv-1.9.2.ebuild``,
+a replacement iconv for ``libc`` implementations which don't have their own.
+
+.. CODESAMPLE ex3.ebuild
+
+Note the ``IUSE`` variable. This lists all (non-special) use flags that are used
+by the ebuild. This is used for the ``emerge -pv`` output, amongst other things.
+
+The package's ``./configure`` script takes the usual ``--enable-nls`` or
+``--disable-nls`` argument. We use the ``use_enable`` utility function to
+generate this automatically (see `Query Functions Reference`_).
+
+Another more complicated example, this time based upon
+``mail-client/sylpheed/sylpheed-1.0.4.ebuild``:
+
+.. CODESAMPLE ex4.ebuild
+
+Note the optional dependencies. Some of the ``use_enable`` lines use the
+two-argument version -- this is helpful when the USE flag name does not exactly
+match the ``./configure`` argument.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/styles/devmanual.css b/styles/devmanual.css
new file mode 100644
index 0000000..841b704
--- /dev/null
+++ b/styles/devmanual.css
@@ -0,0 +1,235 @@
+div.header {
+ border-bottom: 3px solid #333333;
+ background-color: #666666;
+ color: #eeeeee;
+ margin: 0em 0em 0em 0em;
+ padding: 0.2em;
+ font-size: 70%;
+}
+
+div.navtop {
+ border-bottom: 1px dashed #333333;
+ text-align: center;
+}
+
+div.navbottom {
+ border-top: 1px dashed #333333;
+ text-align: center;
+ margin-top: 1em;
+}
+
+@media print {
+ div.header {
+ display: none;
+ }
+}
+
+div.header a:link, div.header a:visited,
+div.footer a:link, div.footer a:visited {
+ color: #eeeeee;
+ font-weight: bold;
+ text-decoration: none;
+}
+
+div.header a:hover, div.footer a:hover {
+ color: #eeeeee;
+ font-weight: bold;
+ text-decoration: underline;
+}
+
+div.footer {
+ text-align: center;
+ border-top: 3px solid #333333;
+ background-color: #666666;
+ color: #eeeeee;
+ margin: 0em 0em 0em 0em;
+ padding: 0em 0.2em;
+ font-size: 70%;
+}
+
+@media print {
+ div.footer {
+ display: none;
+ }
+}
+
+div.main {
+ padding: 1em 40px;
+ margin: 0em;
+ background-color: #eeeeee;
+ color: #333333;
+}
+
+body {
+ background-color: #666666;
+ color: #eeeeee;
+ padding: 0em;
+ margin: 0em;
+ font-family: "Verdana", "Arial" "Helvetica", sans-serif;
+}
+
+div.footer * img {
+ border-width: 0px;
+}
+
+th {
+ font-weight: bold;
+ text-align: left;
+ padding: 0.3em;
+}
+
+th, td {
+ padding-left: 0.3em;
+ padding-right: 0.3em;
+}
+
+div.main a:link, div.main a:visited {
+ color: #000099;
+ text-decoration: none;
+}
+
+div.main a[href]:hover {
+ color: #000099;
+ text-decoration: underline;
+}
+
+div.main pre a:link, div.main pre a:visited {
+ color: #fff0e0;
+ text-decoration: none;
+}
+
+div.main pre a[href]:hover {
+ color: #fff0e0;
+ text-decoration: underline;
+}
+
+code, tt {
+ color: #993333;
+}
+
+div.main p, div.main dd {
+ text-align: justify;
+}
+
+pre {
+ background-color: #1e1e27;
+ color: #cfbfad;
+ padding-top: 3px;
+ padding-bottom: 3px;
+ padding-left: 8px;
+ padding-right: 8px;
+}
+
+div.main h1 {
+ text-align: center;
+}
+
+div.main h2 {
+ text-align: left;
+ border-bottom: 1px dashed #333333;
+ margin-left: -30px;
+}
+
+div.main h3 {
+ text-align: left;
+ margin-left: -30px;
+}
+
+dt {
+ font-weight: bold;
+}
+
+dd p.first {
+ margin-top: 0.2em;
+}
+
+dd p.last {
+ margin-bottom: 0.2em;
+}
+
+div.figure, div.figure p {
+ text-align: center;
+ font-weight: bold;
+}
+
+code, pre, tt {
+ font-family: "Terminus", monospace;
+}
+
+div.warning p.admonition-title,
+div.note p.admonition-title,
+div.todo p.admonition-title,
+div.admonition p.admonition-title,
+div.important p.admonition-title {
+ font-weight: bold;
+ display: inline;
+}
+
+div.warning p,
+div.note p,
+div.todo p,
+div.admonition p,
+div.important p {
+ display: inline;
+}
+
+div.warning p.admonition-title:after,
+div.note p.admonition-title:after,
+div.todo p.admonition-title:after,
+div.admonition p.admonition-title:after,
+div.important p.admonition-title:after {
+ content: ":";
+}
+
+div.note, div.warning,
+div.important, div.todo,
+div.admonition {
+ padding: 4px;
+ text-align: justify;
+}
+
+div.note {
+ background-color: #c9c4ff;
+}
+
+div.warning {
+ background-color: #ee9999;
+}
+
+div.important {
+ background-color: #99ee99;
+}
+
+div.todo {
+ background-color: #cccccc;
+}
+
+div.admonition {
+ background-color: #ffffff;
+}
+
+blockquote.epigraph p {
+ font-size: 80%;
+ font-style: italic;
+}
+
+blockquote.epigraph p.attribution {
+ font-style: normal;
+}
+
+pre span.Normal { color: #cfbfad; background-color: #1e1e27; }
+pre span.Number { color: #506dbd; }
+pre span.Special { color: #c080d0; }
+pre span.Identifier { color: #ff8bff; }
+pre span.Type { color: #ff8bff; }
+pre span.PreProc { color: #409090; }
+pre span.String { color: #ffcd8b; background-color: #404040; }
+pre span.Constant { color: #ffcd8b; }
+pre span.lnr { color: #8b8bcd; background-color: #2e2e2e; }
+pre span.Comment { color: #cd8b00; }
+pre span.Statement { color: #808bed; }
+pre span.DiffAdd { color: #40c060; }
+pre span.Title { color: #40c060; font-weight: bold; }
+pre span.Underlined { font-weight: bold; color: #fff0c0; }
+
+/* vim: set ts=4 tw=80 et : */
diff --git a/tasks-reference/completion/completion-1.ebuild b/tasks-reference/completion/completion-1.ebuild
new file mode 100644
index 0000000..d3fccd4
--- /dev/null
+++ b/tasks-reference/completion/completion-1.ebuild
@@ -0,0 +1,3 @@
+# Headers.
+
+complete -o nospace -d cd \ No newline at end of file
diff --git a/tasks-reference/completion/completion-2.ebuild b/tasks-reference/completion/completion-2.ebuild
new file mode 100644
index 0000000..57e5cce
--- /dev/null
+++ b/tasks-reference/completion/completion-2.ebuild
@@ -0,0 +1,19 @@
+# Headers.
+
+_foo() {
+ local cur prev opts
+ COMPREPLY=()
+ cur="${COMP_WORDS[COMP_CWORD]}"
+ prev="${COMP_WORDS[COMP_CWORD-1]}"
+ opts=""
+
+ if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then
+ COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+ return 0
+ fi
+
+ case "${prev}" in
+ # ...
+ esac
+}
+complete -F _foo foo
diff --git a/tasks-reference/completion/completion-3.ebuild b/tasks-reference/completion/completion-3.ebuild
new file mode 100644
index 0000000..d06abfa
--- /dev/null
+++ b/tasks-reference/completion/completion-3.ebuild
@@ -0,0 +1,7 @@
+# Headers.
+
+case "${prev}" in
+ -f|--file)
+ COMPREPLY=( $(compgen -f ? ${cur}) )
+ ;;
+esac \ No newline at end of file
diff --git a/tasks-reference/completion/completion-4.ebuild b/tasks-reference/completion/completion-4.ebuild
new file mode 100644
index 0000000..2f4bb03
--- /dev/null
+++ b/tasks-reference/completion/completion-4.ebuild
@@ -0,0 +1,39 @@
+# Headers.
+
+_revdep_rebuild() {
+ local cur prev opts
+ COMPREPLY=()
+ cur="${COMP_WORDS[COMP_CWORD]}"
+ prev="${COMP_WORDS[COMP_CWORD-1]}"
+ opts="-X --package-names --soname --soname-regexp -q --quiet"
+
+ if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] || \
+ [[ ${prev} == @(-q|--quiet) ]] ; then
+ COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+ return 0
+ fi
+
+ case "${prev}" in
+ -X|--package-names)
+ _pkgname -I ${cur}
+ ;;
+ --soname)
+ local sonames=$(for x in /lib/*.so?(.)* /usr/lib*/*.so\?(.)* ; do \
+ echo ${x##*/} ; \
+ done)
+ COMPREPLY=( $(compgen -W "${sonames}" -- ${cur}) )
+ ;;
+ --soname-regexp)
+ COMPREPLY=()
+ ;;
+ *)
+ if [[ ${COMP_LINE} == *" "@(-X|--package-names)* ]] ; then
+ _pkgname -I ${cur}
+ COMPREPLY=(${COMPREPLY[@]} $(compgen -W "${opts}"))
+ else
+ COMPREPLY=($(compgen -W "${opts} -- ${cur}"))
+ fi
+ ;;
+ esac
+}
+complete -F _revdep_rebuild revdep-rebuild
diff --git a/tasks-reference/completion/text.rst b/tasks-reference/completion/text.rst
new file mode 100644
index 0000000..2418a06
--- /dev/null
+++ b/tasks-reference/completion/text.rst
@@ -0,0 +1,154 @@
+Completion Files
+================
+
+Since v2.05a, ``bash`` has offered intelligent programmable completion. Writing
+such completions for your own programs/things you maintain is relatively easy
+provided you know bash already. See `bash-completion.eclass Reference`_ for how
+to install completion files.
+
+Completion-Related Internal Bash Variables
+------------------------------------------
+
+Most of these variables lose their special properties when unset, even if they
+are subsequently reset.
+
+=================== ==========================================================
+Variable Purpose
+=================== ==========================================================
+``COMP_CWORD`` An index into ``${COMP_WORDS}`` of the word containing the
+ current cursor position.
+``COMP_LINE`` The current command line.
+``COMP_POINT`` The index of the current cursor position relative to the
+ beginning of the current command. If the current cursor
+ position is at the end of the current command, the value
+ of this variable is equal to ``${#COMP_LINE}``.
+``COMP_WORDBREAKS`` The set of characters that the Readline library treats as
+ word separators when performing word completion.
+``COMP_WORDS`` An array variable consisting of the individual words in
+ the current command line, ``${COMP_LINE}``.
+``COMPREPLY`` An array variable from which bash reads the possible
+ completions generated by a completion function.
+=================== ==========================================================
+
+Completion-Related Bash Builtins
+--------------------------------
+
+See `bash-1`_ for a full description of these builtins and their options.
+
+============ ================================================================
+Builtin Usage
+============ ================================================================
+``compgen`` ``compgen [-abcdefgjksuv] [-o option] [-A action] [-G globpat]
+ [-W wordlist] [-P prefix] [-S suffix] [-X filterpat]
+ [-F function] [-C command] [word]``
+ Display the possible completions depending on the options.
+ Intended to be used from within a shell function generating
+ possible completions. If the optional WORD argument is supplied,
+ matches against WORD are generated.
+``complete`` ``complete [-abcdefgjksuv] [-pr] [-o option] [-A action]
+ [-G globpat] [-W wordlist] [-P prefix] [-S suffix]
+ [-X filterpat] [-F function] [-C command] [name ...]``
+ For each NAME, specify how arguments are to be completed.
+ If the -p option is supplied, or if no options are supplied,
+ existing completion specifications are printed in a way that
+ allows them to be reused as input. The -r option removes a
+ completion specification for each NAME, or, if no NAMEs are
+ supplied, all completion specifications.
+============ ================================================================
+
+For extremely simple cases, a simple ``complete`` statement is all that is
+needed. For example, minimal ``cd`` completion (minimal as in no support for
+``${CDPATH}``) would be as simple as:
+
+.. CODESAMPLE completion-1.ebuild
+
+Anatomy of a Completion Function
+--------------------------------
+
+Nearly all completion functions will start out the same way. For these cases,
+the following can be used as a template for creating new completion functions:
+
+.. CODESAMPLE completion-2.ebuild
+
+1. The convention for completion function names is usually _NAME, where NAME
+ is the name of the application/function you are writing the completion
+ function for. If NAME contains a '-', it should be replaced with a '_'.
+ Hence bash-completion-config would be _bash_completion_config(). Failing
+ to do so can cause weird bugs if bash is invoked in POSIX-mode while a
+ function name containing a '-' is in the environment (POSIX sh does not
+ allow a '-' in function names).
+
+3. Resets the ``${COMPREPLY}`` array, as it may be set from a previous
+ invocation.
+
+4. Sets the local variable, ``${cur}`` to the current word of the command line.
+ If the current command line, ``${COMP_LINE}`` is say 'foo --fil', ``${cur}``
+ would be equal to '--fil'. If ``${COMP_LINE}`` is equal to 'foo --file '
+ (note the space at the end), ``${cur}`` is null.
+
+5. Sets the local variable, ``${prev}`` to the previous word of the command
+ line. ``${prev}`` is the word before ``${cur}``.
+
+6. Sets the local variable, ``${opts}``. In a real completion function, this
+ variable would be set to all the options that ``foo`` recognizes.
+
+8. Tests whether or not the current word is equivalent to -* (an option) or if
+ we're completing on the first word (ie. ``${COMP_CWORD}`` == 1).
+
+9. If the test returns true, show the available options, ``${opts}``. The -W
+ option to ``compgen`` tells bash to complete on the word list (string or
+ something that evaluates to a string). In the majority of cases, you'll
+ pass ``'-- ${cur}'`` to ``compgen`` telling it to only return those
+ completions that match ``${cur}``.
+
+13. Most of the time, you'll want to perform a certain action if ``${prev}`` is
+ equal to a certain option. For example, if ``foo`` has a --file option
+ (and -f for short) that takes any kind file, you could do:
+
+ .. CODESAMPLE completion-3.ebuild
+
+.. case "${prev}" in
+ -f|--file)
+ COMPREPLY=( $(compgen -f -- ${cur}) )
+ ;;
+ esac ..
+
+17. Tells bash to use the ``_foo`` function to generate any completions for
+ the ``foo`` application/function.
+
+
+Real-World Example
+------------------
+
+For this document, I will take you through a real-world example and write a
+real completion function for ``revdep-rebuild`` (might even be available in
+``gentoo-bashcomp`` by the time you read this :]).
+
+.. CODESAMPLE completion-4.ebuild
+
+Lines 1-12 are pretty much the same as in the previous section.
+
+15. If ``${prev}`` is equal to -X|--package-names, call _pkgname (a function
+ defined by ``gentoo-bashcomp`` that completes on package names - it sets
+ ``${COMPREPLY}``, so we don't worry about that here).
+
+18. If ``${prev}`` is equal to --soname, generate a list of all shared libs
+ in /lib and /usr/lib*. Pass that list to ``compgen`` to generate a list
+ of possible completions that match ``${cur}``.
+
+24. Obviously we cannot complete on any regexp's so if ``${prev}`` is equal
+ to --soname-regexp, do nothing.
+
+27. For anything else (any options not specified in the case statement above
+ OR any argument to one of the options specified in the case statement)
+ perform the tests. Since --package-names can take multiple package
+ names, we want to continue to complete on package names until another
+ recognized option is encountered (ie. is ``${prev}``).
+
+30. Since _pkgname sets ``${COMPREPLY}`` and we want to add to that list,
+ we have to use the COMPREPLY=(${COMPREPLY[@] ... ) construct.
+
+37. Tell bash to use _revdep_rebuild to generate all possible completions
+ for revdep-rebuild.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/tasks-reference/environment/text.rst b/tasks-reference/environment/text.rst
new file mode 100644
index 0000000..6aeb72c
--- /dev/null
+++ b/tasks-reference/environment/text.rst
@@ -0,0 +1,18 @@
+Environment Files
+=================
+
+Some packages need to globally set an environment variable for all users. The
+canonical way of doing this is via ``/etc/env.d``. All files in this directory
+are sourced when generating user environment settings.
+
+This directory should **only** be used for setting environment variables.
+
+To install a file into this directory, use ``doenvd`` or ``newenvd`` (see
+`Install Functions Reference`_). The format of the file should be a series of
+lines in the form ``VARIABLE="the value"``.
+
+There is further discussion in the `main handbook Environment Variables section
+<http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=2&chap=5>`__.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/tasks-reference/init-scripts/text.rst b/tasks-reference/init-scripts/text.rst
new file mode 100644
index 0000000..0c2199d
--- /dev/null
+++ b/tasks-reference/init-scripts/text.rst
@@ -0,0 +1,15 @@
+Init Scripts
+============
+
+Init scripts should be installed into ``/etc/init.d`` using the ``doinitd`` or
+``newinitd`` functions (see `Install Functions Reference`_). Any configuration
+(commandline parameters or environment variables) for these scripts should be
+handled via entries in ``/etc/conf.d`` with the same filename -- ``doconfd`` or
+``newconfd`` can be used to install these.
+
+An overview of the Gentoo init system and how to write init scripts is available
+in the `main handbook Writing Init Scripts section
+<http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=2&chap=4#doc_chap4>`__.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/tasks-reference/pam/text.rst b/tasks-reference/pam/text.rst
new file mode 100644
index 0000000..1f444dd
--- /dev/null
+++ b/tasks-reference/pam/text.rst
@@ -0,0 +1,170 @@
+Working with PAM
+================
+
+PAM (Pluggable Authentication Modules) is a mechanism which allows different
+applications to authenticate using various specified parameters, using for
+example a passwd/shadow file, a Kerberos server, an LDAP server or an a NT
+Domain server (using Samba).
+
+With PAM, a program just needs to require authentication for a given login class
+(defined in a ``pam.d`` file), and PAM framework will take care of calling the
+modules which will provide authentication.
+
+There are different PAM implementations. Gentoo Linux, by default, uses the
+Linux-PAM implementation which is installed via ``sys-libs/pam``; FreeBSD and
+NetBSD (and hence Gentoo/FreeBSD) use OpenPAM, which is a minimal version. The
+different implementations can provide different authentication modules, and can
+differ in some details of the configuration.
+
+Structure of a ``pamd`` File
+----------------------------
+
+But let's see the structure of a ``pamd`` file. First of all, the ``pamd ``files
+are placed in ``/etc/pam.d``, and they are structured as one statement per line.
+The statement is composed of 3 or 4 tokens:
+
+* The first token specifies the type of service for which the statement is done.
+ There are four types:
+
+ + *account*, which checks for validity of the user account.
+ + *auth*, which verifies that the user is who is claim to be, using passwords
+ or other ways such as biometric and smart-card devices.
+ + *password*, which takes care of changing users' password.
+ + *session*, which covers tasks such as checks for the user validity or
+ mount/umount of home directories, executed both before starting and after
+ closing the user session.
+
+* The second token is the control that tells PAM how to behave with failures and success of the authentication for the module specified:
+
+ + *requisite*, a failure results in the termination of the process.
+ + *required*, a failure will lead in a failure for the service, but before
+ this, all the other modules are being executed.
+ + *sufficient*, a success in this module leads to a success in authentication
+ if no *required* module failed before of it.
+ + *optional*, in which case the failure or the success are ignored if this is
+ not the only module present, in which case a success or a failure of it
+ makes the authentication succeed or fail.
+
+* The third token is the module to execute for that type of service; PAM modules
+ are extensible and, as the name says, pluggable. The result is that there are
+ a small number of default modules and some external optional modules which can
+ be built against PAM implementation to define additional authentication
+ methods. Some documentation states that we need to specify the full path of
+ the module, but this creates problems because not all the systems install the
+ modules in the same place: Linux-PAM on Gentoo is generally set up to load
+ them from ``/lib/security``, but for example on AMD64 this become
+ ``/lib64/security``, and on OpenPAM they are just in ``/usr/lib(64)``. The
+ result is that providing the full path will lead to non-working ``pamd``
+ files, and the right way to handle this is just states the module name -- the
+ PAM implementation will take care of finding the module.
+
+* The last token, which can consist of multiple items, describe the parameters
+ passed to the module. These are module-dependent.
+
+As the number and the type of modules shipped with the implementation depends on
+the implementations themselves (Linux-PAM provides a full working set of
+modules, OpenPAM doesn't provide modules at all, and it's the operating system
+which provides them, as FreeBSD or NetBSD do), there are just a few modules
+which can be used directly in ``pamd`` files without the risk of providing a
+non-working configuration file:
+
+* ``pam_deny.so``, ``pam_permit.so`` -- they just report a failure or a success
+* ``pam_rootok.so`` reports success if the user is root, else a failure
+* ``pam_nologin.so`` checks for presence of /etc/nologin file with a reason for
+ blocking user logins -- it's used for example when it's better to avoid users
+ logging in on a compromised system
+* ``pam_securetty.so`` checks that the login is done in a tty which is
+ considered secure by a configuration file (depends on the implementation)
+* ``pam_unix.so`` is the base module for Unix systems, it just checks the
+ user/password pair with ``/etc/passwd`` and ``/etc/shadow``.
+
+There are also other modules which can be used for more complex authentication
+against a database (mysql or postgresql), against an LDAP directory or against
+an NT domain (using samba). This is useful on thin or fat clients where the
+users have an unique login for all the machines. Another place where this is
+useful is a cluster of servers which needs to authenticate against a single
+source for some services, such as mail and ftp servers.
+
+But for desktop systems, all the different services, such as mail servers, ftp
+servers, ssh and so on, just need to authenticate in the same way the users logs
+in to the system.
+
+To achieve this, RedHat developed for Linux-PAM (which hadn't had a way to rely
+on another authentication scheme) a ``pam_stack.so`` module which accepted as
+parameter ``"login=<login service to use>"``, telling PAM to execute the auth
+stack for the service stated.
+
+Unfortunately that module relied upon internal data structures of Linux-PAM and
+assumptions which aren't valid for other PAM implementations, so it is
+completely non-portable. It is not used in all the implementations of Linux-PAM
+(see for example MacOS X, which uses Linux-PAM but doesn't provide
+``pam_stack.so``), and so it's not present on all Linux distributions.
+
+A solution came when AltLinux developers added a new instruction for the control
+token: *include*. That control token can be used on Linux-PAM 0.78 and on
+OpenPAM to do the same as a ``required pam_stack.so``, replacing the module name
+with the name of the login class to mimic.
+
+In this way, instead of loading a module which in turn reloads pam, the option
+is parsed directly by the PAM implementation which loads the other login class
+and takes care of executing it, and the same syntax is valid on both Linux-PAM
+and OpenPAM systems.
+
+New packages (and new versions of old packages) should then use the ``include``
+directive instead of ``pam_stack.so`` module, but to do that they need to depend
+on a later version of ``sys-libs/pam`` or on ``sys-libs/openpam`` (note: openpam
+is for now just on G/FreeBSD's project overlay) -- to resolve this,
+``virtual/pam`` is set up to add the right dependency for the use of the include
+directive.
+
+Installing ``pamd`` Files
+-------------------------
+
+The right place for ``pamd`` files is ``/etc/pam.d``, but installing them by
+hand checking for ``pam`` USE flag is tricky and doesn't follow the same path as
+initd and confd files, so the solution is to use the ``pam`` eclass.
+
+In the ``pam`` eclass there are functions which provide installation facilities
+for ``pamd`` files (``dopamd`` and ``newpamd``, whose usage is the same as
+similar ``do*`` and ``new*`` functions) and the ``/etc/security`` files
+(``dopamsecurity`` and ``newpamsecurity``, which need the first argument to be
+the subdirectory of ``/etc/security`` in which the files are to be installed).
+Those groups of functions already takes care of verifying whether the ``pam``
+USE flag is made optional for the package -- if this is the case, and the flag
+is disabled, the ``pamd`` files are just skipped.
+
+Many ``pamd`` files just uses one or more auth types from ``system-auth`` login class,
+which is the base one which provides login facilities for most services on
+common desktop systems. Instead of adding a ``pamd`` file in ``${FILESDIR}``
+for this, one can use the ``pamd_mimic_system`` function. This function takes a series
+of parameters -- the first one is the name of the login class (the name of the
+``pamd`` file in /etc/pam.d); the others are the auth types for which system-auth
+needs to be used.
+
+For example, a call like: ::
+
+ pamd_mimic_system foo auth password
+
+installs an ``/etc/pam.d/foo`` file which contains: ::
+
+ auth include system-auth
+ password include system-auth
+
+which just uses ``system-auth`` login class.
+
+Installing PAM Modules
+----------------------
+
+As PAM modules are looked for in different directories on different
+implementations, which also depends on the libdir's name for ARCHs with more
+than one ABI, usually is not possible to trust the default directory stated by
+the module (always if the module state a default directory). The solution for
+this is also in ``pam`` eclass. The function ``getpam_mod_dir`` returns the
+correct directory to use for the current implementation/arch.
+
+When the PAM mdoule doesn't provide a way to install the package by itself, such
+as a ``Makefile`` or an installation script, there are also the ``dopammod`` and
+``newpammod`` functions which takes care of install the module in the right
+directory.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/tasks-reference/perl-modules/text.rst b/tasks-reference/perl-modules/text.rst
new file mode 100644
index 0000000..d30bf9a
--- /dev/null
+++ b/tasks-reference/perl-modules/text.rst
@@ -0,0 +1,11 @@
+Perl Modules
+============
+
+This section covers where and how Perl modules should be installed. This is for
+Perl applications which use their own ``.pm`` files, **not** for CPAN things.
+
+.. Todo:: write me. see thread on -dev.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
+
diff --git a/tasks-reference/text.rst b/tasks-reference/text.rst
new file mode 100644
index 0000000..4d623e4
--- /dev/null
+++ b/tasks-reference/text.rst
@@ -0,0 +1,10 @@
+Tasks Reference
+===============
+
+This section covers various common tasks which may are used by many different
+ebuilds.
+
+.. CHILDLIST
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/text.rst b/text.rst
new file mode 100644
index 0000000..990353e
--- /dev/null
+++ b/text.rst
@@ -0,0 +1,69 @@
+Introduction
+============
+
+.. epigraph::
+ A policy is a restrictive document to prevent a recurrence of a single
+ incident, in which that incident is never mentioned.
+
+ -- Kaufman's Law
+
+This document is an ongoing work in progress. It contains gaps,
+inaccuracies, omissions, typos and the occasional outright lie. The
+intent is to make an handbook giving developers and users correct,
+detailed, up to date technical content.
+
+Contributions are encouraged. See the `Contributing to This Document`_ section
+for how to get started. Thanks for Ciaran for permitting me to continue this
+and sending me the RST source and needed scripts.
+
+Authors
+-------
+
+Ciaran McCreesh <ciaranm@gentoo.org>
+ Main content
+
+Tim Yamin <plasmaroo@gentoo.org>
+ Editing
+
+Grant Goodyear <g2boojum@gentoo.org>
+ `Here Documents`_, `Distutils`_
+
+Aaron Walker <ka0ttic@gentoo.org>
+ `Completion Files`_, `subversion.eclass Reference`_
+
+Robert Coie <rac@gentoo.org>
+ `Configuring xemacs for UTF-8`_
+
+Tom Martin <slarti@gentoo.org>
+ `Configuring emacs for UTF-8`_, `Subversion Sources`_, `Conflicting USE
+ Flags`_
+
+Paul Varner <fuzzyray@gentoo.org>
+ `RPM Sources`_
+
+Ilya Volynets-Evenbakh <iluxa@gentoo.org>
+ `MIPS ABIs`_
+
+Diego Pettenò <flameeyes@gentoo.org>
+ `Working with PAM`_, `aclocal and m4 Files`_
+
+Fernando J. Pereda <ferdy@gentoo.org>
+ `Arch Specific Notes -- Alpha`_
+
+Simon Stelling <blubb@gentoo.org>
+ `Arch Specific Notes -- AMD64/EM64T`_
+
+Alin Dobre <alin@gentoo.org>
+ `echo -- Print strings`_
+
+Contents
+--------
+
+.. CHILDLIST
+
+Full Contents
+-------------
+
+.. FULLCHILDLIST
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/todolist/text.rst b/todolist/text.rst
new file mode 100644
index 0000000..69fc905
--- /dev/null
+++ b/todolist/text.rst
@@ -0,0 +1,10 @@
+Todo List
+=========
+
+This todo list is automatically generated from the ``.. Todo::`` directives in
+other documents.
+
+.. TODOLIST
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/tools-reference/bash/bash-1.ebuild b/tools-reference/bash/bash-1.ebuild
new file mode 100644
index 0000000..a52202d
--- /dev/null
+++ b/tools-reference/bash/bash-1.ebuild
@@ -0,0 +1,5 @@
+# Header.
+
+if something ; then
+ do_stuff
+fi
diff --git a/tools-reference/bash/bash-10.ebuild b/tools-reference/bash/bash-10.ebuild
new file mode 100644
index 0000000..39b7db4
--- /dev/null
+++ b/tools-reference/bash/bash-10.ebuild
@@ -0,0 +1,5 @@
+# Header.
+
+while read myline ; do
+ einfo "It says ${myline}"
+done < some_file
diff --git a/tools-reference/bash/bash-11.ebuild b/tools-reference/bash/bash-11.ebuild
new file mode 100644
index 0000000..7c3e977
--- /dev/null
+++ b/tools-reference/bash/bash-11.ebuild
@@ -0,0 +1,5 @@
+# Header.
+
+somevar="Hello World"
+echo "${somevar} is ${#somevar} characters long"
+
diff --git a/tools-reference/bash/bash-12.ebuild b/tools-reference/bash/bash-12.ebuild
new file mode 100644
index 0000000..5e65daf
--- /dev/null
+++ b/tools-reference/bash/bash-12.ebuild
@@ -0,0 +1,3 @@
+# Header.
+
+myconf="$(use_enable acl ) $(use_enable nls ) --with-tlib=ncurses"
diff --git a/tools-reference/bash/bash-2.ebuild b/tools-reference/bash/bash-2.ebuild
new file mode 100644
index 0000000..85876e4
--- /dev/null
+++ b/tools-reference/bash/bash-2.ebuild
@@ -0,0 +1,11 @@
+# Header.
+
+if something ; then
+ do_stuff
+elif something_else ; then
+ do_other_stuff
+elif full_moon ; then
+ howl
+else
+ turn_into_a_newt
+fi
diff --git a/tools-reference/bash/bash-3.ebuild b/tools-reference/bash/bash-3.ebuild
new file mode 100644
index 0000000..5056e55
--- /dev/null
+++ b/tools-reference/bash/bash-3.ebuild
@@ -0,0 +1,8 @@
+# Header.
+
+if some_stuff ; then
+ # A statement is required here. a blank or a comment
+ # isn't enough!
+else
+ einfo "Not some stuff"
+fi
diff --git a/tools-reference/bash/bash-4.ebuild b/tools-reference/bash/bash-4.ebuild
new file mode 100644
index 0000000..13edf37
--- /dev/null
+++ b/tools-reference/bash/bash-4.ebuild
@@ -0,0 +1,8 @@
+# Header.
+
+if some_stuff ; then
+ # Do nothing
+ :
+else
+ einfo "Not some stuff"
+fi
diff --git a/tools-reference/bash/bash-5.ebuild b/tools-reference/bash/bash-5.ebuild
new file mode 100644
index 0000000..c18fa4f
--- /dev/null
+++ b/tools-reference/bash/bash-5.ebuild
@@ -0,0 +1,14 @@
+# is $foo zero length?
+if [[ -z "${foo}" ]] ; then
+ die "Please set foo"
+fi
+
+# is $foo equal to "moo"?
+if [[ "${foo}" == "moo" ]] ; then
+ einfo "Hello Larry"
+fi
+
+# does "${ROOT}/etc/deleteme" exist?
+if [[ -f "${ROOT}/etc/deleteme" ]] ; then
+ einfo "Please delete ${ROOT}/etc/readme manually!"
+fi
diff --git a/tools-reference/bash/bash-6.ebuild b/tools-reference/bash/bash-6.ebuild
new file mode 100644
index 0000000..a4a10cf
--- /dev/null
+++ b/tools-reference/bash/bash-6.ebuild
@@ -0,0 +1,6 @@
+# Header.
+
+bash$ [ -n $foo ] && [ -z $foo ] && echo "huh?"
+huh?
+bash$ [[ -n $foo ]] && [[ -z $foo ]] && echo "huh"?
+bash$
diff --git a/tools-reference/bash/bash-7.ebuild b/tools-reference/bash/bash-7.ebuild
new file mode 100644
index 0000000..5f1f568
--- /dev/null
+++ b/tools-reference/bash/bash-7.ebuild
@@ -0,0 +1,5 @@
+# Header.
+
+for myvar in "the first" "the second" "and the third" ; do
+ einfo "This is ${myvar}"
+done
diff --git a/tools-reference/bash/bash-8.ebuild b/tools-reference/bash/bash-8.ebuild
new file mode 100644
index 0000000..3639a28
--- /dev/null
+++ b/tools-reference/bash/bash-8.ebuild
@@ -0,0 +1,6 @@
+# Header.
+
+for (( i = 1 ; i <= 10 ; i++ )) ; do
+ einfo "i is ${i}"
+done
+
diff --git a/tools-reference/bash/bash-9.ebuild b/tools-reference/bash/bash-9.ebuild
new file mode 100644
index 0000000..a800a5a
--- /dev/null
+++ b/tools-reference/bash/bash-9.ebuild
@@ -0,0 +1,5 @@
+# Header.
+
+while hungry ; do
+ eat_cookies
+done
diff --git a/tools-reference/bash/text.rst b/tools-reference/bash/text.rst
new file mode 100644
index 0000000..f449af1
--- /dev/null
+++ b/tools-reference/bash/text.rst
@@ -0,0 +1,372 @@
+bash -- Standard Shell
+======================
+
+A thorough understanding of ``bash`` programming is vital when working with
+ebuilds.
+
+Bash Conditionals
+-----------------
+
+Basic Selection
+'''''''''''''''
+
+The basic conditional operator is the ``if`` statement:
+
+.. CODESAMPLE bash-1.ebuild
+
+Multiple Selection
+''''''''''''''''''
+
+Multiple pronged selection can be done using ``else`` and ``elif``:
+
+.. CODESAMPLE bash-2.ebuild
+
+.. Warning:: You **must** specify at least one statement inside each block. The
+ following will **not** work:
+
+.. CODESAMPLE bash-3.ebuild
+
+If you really don't want to restructure the block, you can use a single colon
+(``:``) on its own as a null statement.
+
+.. CODESAMPLE bash-4.ebuild
+
+Selection Tests
+'''''''''''''''
+
+To do comparisons or file attribute tests, ``[ ]`` or ``[[ ]]`` blocks are
+needed.
+
+.. CODESAMPLE bash-5.ebuild
+
+Single versus Double Brackets in ``bash``
+'''''''''''''''''''''''''''''''''''''''''
+
+.. Important:: The ``[[ ]]`` form is generally safer than ``[ ]`` and should
+ be used in all new code.
+
+This is because ``[[ ]]`` is a bash syntax construct, whereas ``[ ]`` is a
+program which happens to be implemented as an internal -- as such, cleaner
+syntax is possible with the former. For a simple illustration, consider:
+
+.. CODESAMPLE bash-6.ebuild
+
+String Comparison in ``bash``
+''''''''''''''''''''''''''''''
+
+The general form of a string comparison is ``string1 operator string2``. The
+following are available:
+
+==================== =======================================================
+Operator Purpose
+==================== =======================================================
+``==`` (also ``=``) String equality
+``!=`` String inequality
+``<`` String lexiographic comparison (before)
+``>`` String lexiographic comparison (after)
+``=~`` String regular expression match (**bash 3 only**, not
+ currently allowed in ebuilds)
+==================== =======================================================
+
+String Tests in ``bash``
+''''''''''''''''''''''''
+
+The general form of string tests is ``-operator "string"``. The following are
+available:
+
+==================== =========================================
+Operator Purpose
+==================== =========================================
+``-z "string"`` String has zero length
+``-n "string"`` String has non-zero length
+==================== =========================================
+
+.. Note:: To check whether a variable is set and not blank, use ``-n "${BLAH}"``
+ rather than ``-n $BLAH``. The latter will cause problems in some situations if
+ the variable is unset.
+
+Integer Comparison in ``bash``
+''''''''''''''''''''''''''''''
+
+The general form of integer comparisons is ``int1 -operator int2``. The
+following are available:
+
+==================== =========================================
+Operator Purpose
+==================== =========================================
+``-eq`` Integer equality
+``-ne`` Integer inequality
+``-lt`` Integer less than
+``-le`` Integer less than or equal to
+``-gt`` Integer greater than
+``-ge`` Integer greater than or equal to
+==================== =========================================
+
+File Tests in ``bash``
+''''''''''''''''''''''
+
+The general form of a file test is ``-operator "filename"``. The following are
+available (lifted from `bash-1`_):
+
+==================== =========================================
+Operator Purpose
+==================== =========================================
+``-a file`` Exists (use ``-e`` instead)
+``-b file`` Exists and is a block special file
+``-c file`` Exists and is a character special file
+``-d file`` Exists and is a directory
+``-e file`` Exists
+``-f file`` Exists and is a regular file
+``-g file`` Exists and is set-group-id
+``-h file`` Exists and is a symbolic link
+``-k file`` Exists and its sticky bit is set
+``-p file`` Exists and is a named pipe (FIFO)
+``-r file`` Exists and is readable
+``-s file`` Exists and has a size greater than zero
+``-t fd`` Descriptor fd is open and refers to a terminal
+``-u file`` Exists and its set-user-id bit is set
+``-w file`` Exists and is writable
+``-x file`` Exists and is executable
+``-O file`` Exists and is owned by the effective user id
+``-G file`` Exists and is owned by the effective group id
+``-L file`` Exists and is a symbolic link
+``-S file`` Exists and is a socket
+``-N file`` Exists and has been modified since it was last read
+==================== =========================================
+
+File Comparison in ``bash``
+'''''''''''''''''''''''''''
+
+The general form of a file comparison is ``"file1" -operator "file2"``. The
+following are available (lifted from `bash-1`_):
+
+==================== =====================================================
+Operator Purpose
+==================== =====================================================
+``file1 -nt file2`` file1 is newer (according to modification date) than
+ file2, or if file1 exists and file2 does not.
+``file1 -ot file2`` file1 is older than file2, or if file2 exists and
+ file1 does not.
+``file1 -ef file2`` file1 and file2 refer to the same device and inode
+ numbers.
+==================== =====================================================
+
+Boolean Algebra in ``bash``
+'''''''''''''''''''''''''''
+
+There are constructs available for boolean algebra ('and', 'or' and 'not').
+These are used *outside* of the ``[[ ]]`` blocks. For operator precedence, use
+``( )``.
+
+============================= ==================================
+Construct Effect
+============================= ==================================
+``first || second`` first *or* second (short circuit)
+``first && second`` first *and* second (short circuit)
+``! condition`` *not* condition
+============================= ==================================
+
+
+.. Note:: These will also sometimes work *inside* ``[[ ]]`` constructs, and using
+ ``!`` before a test is fairly common. ``[[ ! -foo ]] && bar`` is fine. However,
+ there are catches -- ``[[ -f foo && bar ]]`` will **not** work properly, since
+ commands cannot be run inside ``[[ ]]`` blocks.
+
+Inside ``[ ]`` blocks, several ``-test`` style boolean operators are available.
+These should be avoided in favour of ``[[ ]]`` and the above operators.
+
+Bash Iterative Structures
+-------------------------
+
+There are a few simple iterative structures available from within ``bash``. The
+most useful of these is a ``for`` loop. This can be used to perform the same
+task upon multiple items.
+
+.. CODESAMPLE bash-7.ebuild
+
+There is a second form of the ``for`` loop which can be used for repeating an
+event a given number of times.
+
+.. CODESAMPLE bash-8.ebuild
+
+There is also a ``while`` loop, although this is usually not useful within
+ebuilds.
+
+.. CODESAMPLE bash-9.ebuild
+
+This is most commonly used to iterate over lines in a file:
+
+.. CODESAMPLE bash-10.ebuild
+
+See `die and Subshells`_ for an explanation of why ``while read < file`` should
+be used over ``cat file | while read``.
+
+Bash Variable Manipulation
+--------------------------
+
+There are a number of special ``${}`` constructs in ``bash`` which either
+manipulate or return information based upon variables. These can be used instead
+of expensive (or illegal, if we're in global scope) external calls to ``sed``
+and friends.
+
+``bash`` String Length
+''''''''''''''''''''''
+
+The ``${#somevar}`` construct can be used to obtain the length of a string
+variable.
+
+.. CODESAMPLE bash-11.ebuild
+
+``bash`` Variable Default Values
+''''''''''''''''''''''''''''''''
+
+There are a number of ways of using a default value if a variable is unset or
+zero length. The ``${var:-value}`` construct expands to the value of ``${var}``
+if it is set and not null, or ``value`` otherwise. The ``${var:value}``
+construct is similar, but checks only that the variable is set.
+
+The ``${var:=value}`` and ``${var=value}`` forms will also assign ``value`` to
+``var`` if ``var`` is unset (and not null for the ``:=`` form).
+
+The ``${var:?message}`` form will display ``message`` to stderr and then exit if
+``var`` is unset or null. This should generally not be used within ebuilds as it
+does not use the ``die`` mechanism. There is a ``${var?message}`` form too.
+
+The ``${var:+value}`` form expands to ``value`` if ``var`` is set and not null,
+or a blank string otherwise. There is a ``${var+value}`` form.
+
+``bash`` Substring Extraction
+'''''''''''''''''''''''''''''
+
+The ``${var:offset}`` and ``${var:offset:length}`` constructs can be used to
+obtain a substring. Strings are zero-indexed. Both ``offset`` and ``length`` are
+arithmetic expressions.
+
+The first form with a positive offset returns a substring starting with the
+character at ``offset`` and continuing to the end of a string. If the offset is
+negative, the offset is taken relative to the *end* of the string.
+
+.. Note:: For reasons which will not be discussed here, any negative value must be
+ an *expression* which results in a negative value, rather than simply a negative
+ value. The best way to handle this is to use ``${var:0-1}``. ``${var:-1}`` will
+ **not** work.
+
+The second form returns the first ``length`` characters of the value of
+``${var}`` starting at ``offset``. If ``offset`` is negative, the offset is
+taken from the *end* of the string. The ``length`` parameter *must not* be less
+than zero. Again, negative ``offset`` values must be given as an expression.
+
+``bash`` Command Substitution
+'''''''''''''''''''''''''''''
+
+The ``$(command )`` construct can be used to run a command and capture the
+output (``stdout``) as a string.
+
+.. Note:: The ```command``` construct also does this, but should be avoided in
+ favour of ``$(command )`` for clarity, ease of reading and nesting purposes.
+
+.. CODESAMPLE bash-12.ebuild
+
+
+``bash`` String Replacements
+''''''''''''''''''''''''''''
+
+There are three basic string replacement forms available: ``${var#pattern}``,
+``${var%pattern}`` and ``${var/pattern/replacement}``. The first two are used
+for deleting content from the start and end of a string respectively. The third
+is used to replace a match with different content.
+
+The ``${var#pattern}`` form will return ``var`` with the shortest match of
+``pattern`` at the start of the value of ``var`` deleted. If no match can be
+made, the value of ``var`` is given. To delete the *longest* match at the start,
+use ``${var##pattern}`` instead.
+
+The ``${var%pattern}`` and ``${var%%pattern}`` forms are similar, but delete the
+shortest and longest matches at the *end* of ``var`` respectively.
+
+.. Note:: The terms *greedy* and *non-greedy* are sometimes used here (``%`` and
+ ``#`` being the non-greedy forms). This is arguably incorrect, but the terms
+ are fairly close.
+
+The ``${var/pattern/replacement}`` construct expands to the value of ``var``
+with the first match of ``pattern`` replaced with ``replacement``. To replace
+*all* matches, ``${var//pattern/replacement}`` can be used.
+
+.. Note:: `bash-1`_ incorrectly describes what will be matched. Of all the possible
+ leftmost matches, the longest will be taken. Yes, really, the longest, even if
+ it involves favouring later groups or later branches. This is **not** like
+ ``perl`` or ``sed``. See `IEEE1003.1-2004-9.1`_ for details.
+
+To match only if ``pattern`` occurs at the start of the value of ``var``, the
+pattern should begin with a ``#`` character. To match only at the end, the
+pattern should begin with a ``%``.
+
+If ``replacement`` is null, matches are deleted and the ``/`` following
+``pattern`` may be omitted.
+
+The ``pattern`` may contain a number of special metacharacters for pattern
+matching.
+
+.. Todo:: tables of bash metachars
+
+If the ``extglob`` shell option is enabled, a number of additional constructs
+are available. These can be *extremely* useful sometimes.
+
+.. Todo:: table of extra bash goodies
+
+``bash`` Arithmetic Expansion
+'''''''''''''''''''''''''''''
+
+The ``$(( expression ))`` construct can be used for integer arithmetic
+evaluation. ``expression`` is a C-like arithmetic expression. The following
+operators are supported (the table is in order of precedence, highest first):
+
++-----------------------+-------------------------------------------------------+
+| Operators | Effect |
++=======================+=======================================================+
+| ``var++``, ``var--`` | Variable post-increment, post-decrement |
++-----------------------+-------------------------------------------------------+
+| ``++var``, ``--var`` | Variable pre-increment, pre-decrement |
++-----------------------+-------------------------------------------------------+
+| ``-``, ``+`` | Unary minus and plus |
++-----------------------+-------------------------------------------------------+
+| ``!``, ``~`` | Logical negation, bitwise negation |
++-----------------------+-------------------------------------------------------+
+| ``**`` | Exponentiation |
++-----------------------+-------------------------------------------------------+
+| ``*``, ``/``, ``%`` | Multiplication, division, remainder |
++-----------------------+-------------------------------------------------------+
+| ``+``, ``-`` | Addition, subtraction |
++-----------------------+-------------------------------------------------------+
+| ``<<``, ``>>`` | Left, right bitwise shifts |
++-----------------------+-------------------------------------------------------+
+| ``<=``, ``>=``, | Comparison: less than or equal to, greater than or |
+| ``<``, ``>`` | equal to, strictly less than, strictly greater than |
++-----------------------+-------------------------------------------------------+
+| ``==``, ``!=`` | Equality, inequality |
++-----------------------+-------------------------------------------------------+
+| ``&`` | Bitwise AND |
++-----------------------+-------------------------------------------------------+
+| ``^`` | Bitwise exclusive OR |
++-----------------------+-------------------------------------------------------+
+| ``|`` | Bitwise OR |
++-----------------------+-------------------------------------------------------+
+| ``&&`` | Logical AND |
++-----------------------+-------------------------------------------------------+
+| ``||`` | Logical OR |
++-----------------------+-------------------------------------------------------+
+| ``expr ? expr : expr``| Conditional operator |
++-----------------------+-------------------------------------------------------+
+| ``=``, ``*=``, ``/=``,| Assignment |
+| ``%=``, ``+=``, | |
+| ``-=``, ``<<=``, | |
+| ``>>=``, ``&=``, | |
+| ``^=``, ``|=`` | |
++-----------------------+-------------------------------------------------------+
+| ``expr1 , expr2`` | Multiple statements |
++-----------------------+-------------------------------------------------------+
+
+
+.. Note:: There is no ``**=`` assignment operator.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/tools-reference/cat/code-sample-1.ebuild b/tools-reference/cat/code-sample-1.ebuild
new file mode 100644
index 0000000..cd9980b
--- /dev/null
+++ b/tools-reference/cat/code-sample-1.ebuild
@@ -0,0 +1,10 @@
+# Header.
+
+src_install() {
+ # ...
+ cat <<- EOF > ${D}/etc/mail/trusted-users
+ # trusted-users - users that can send mail as others without a warning
+ # apache, mailman, majordomo, uucp are good candidates
+ EOF
+ # ...
+}
diff --git a/tools-reference/cat/text.rst b/tools-reference/cat/text.rst
new file mode 100644
index 0000000..4ea2979
--- /dev/null
+++ b/tools-reference/cat/text.rst
@@ -0,0 +1,48 @@
+cat -- File Concatenation
+=========================
+
+The ``cat`` command can be used to concatenate the contents of two or more
+files. The usage is ``cat firstfile secondfile ...``.
+
+Abuse of ``cat``
+----------------
+
+If you find yourself about to use ``cat`` in an ebuild, stop and reconsider. It
+is almost always unnecessary.
+
+All usages in the form ``cat somefile | somecommand`` are silly and should be
+eschewed. The form ``somecommand < somefile`` does the same thing, and doesn't
+involve an extra fork and a pipe. With many standard utilities the ``somecommand
+somefile`` form will work as well.
+
+Using ``foo=$(cat somefile)`` to place the contents of a file into the
+variable ``foo`` is also unnecessary. The command ``foo=$(<somefile)`` works
+just as well and doesn't require a fork. Similarly, ``cat file | xargs cmd`` and
+``xargs cmd < file`` can be replaced by ``cmd $(<file)``.
+
+Finally, ``cat foo > bar``, where ``foo`` is a single file, can usually be
+replaced by ``cp -f foo bar``.
+
+Here Documents
+--------------
+
+On the other hand, ``cat`` is exceptionally useful for so-called "here"
+documents, such as the following example from ``sendmail-8.13.3 ebuild``
+
+.. CODESAMPLE code-sample-1.ebuild
+
+In this example ``cat`` is used inside ``src_install`` to create the
+``${D}/etc/mail/trusted-users`` file. Specifically, the new file will comprise
+the lines between the ``cat`` line and the line with ``EOF`` in the ebuild.
+
+The funny hyphen in ``<<-`` is a >=bash-2.05 syntax that tells
+``cat`` to strip leading tabs (please note that when you want to copy
+the example, you have to replace the leading spaces with tabs), so
+that, as Azarah puts it, "we won't have the ebuilds looking from space
+effect". For such small files as the example above, a set of here
+documents is more elegant, and easier to maintain, than the equivalent
+bunch of files floating about in ``${FILESDIR}`` would be. If for some
+reason you need to preserve leading whitespace, then simply use ``<<``
+instead of ``<<-`` to get the desired effect.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/tools-reference/cut/cut-1.ebuild b/tools-reference/cut/cut-1.ebuild
new file mode 100644
index 0000000..0124dde
--- /dev/null
+++ b/tools-reference/cut/cut-1.ebuild
@@ -0,0 +1,3 @@
+# Header.
+
+cut -s -d',' -f2,4-5 input.txt > output.txt
diff --git a/tools-reference/cut/cut-2.ebuild b/tools-reference/cut/cut-2.ebuild
new file mode 100644
index 0000000..1bc4e1f
--- /dev/null
+++ b/tools-reference/cut/cut-2.ebuild
@@ -0,0 +1,3 @@
+# Header.
+
+do_stuff | cut -c2-
diff --git a/tools-reference/cut/text.rst b/tools-reference/cut/text.rst
new file mode 100644
index 0000000..0d006db
--- /dev/null
+++ b/tools-reference/cut/text.rst
@@ -0,0 +1,37 @@
+cut -- Column Extraction
+========================
+
+The ``cut`` tool can be used to extract specific columns from files which are
+delimited by a particular character or by column numbers. It can be passed
+filenames on the commandline; if none are specified, it reads from stdin.
+
+The ``cut`` tool considers the first character in a line to have index ``1``.
+The ``-c``, ``-f`` and ``-b`` switches take a parameter listing the desired
+columns. This can be a single value, or a more complex list of values separated
+by commas. Each value can be a single number, or two numbers separated by
+hyphens representing ``low-high``. If ``low`` is unspecified, it is treated as
+the first column. If ``high`` is unspecified, it is treated as being "up to the
+last character (inclusive)".
+
+To select particular characters from each line, use the ``-c`` switch. For
+particular bytes (not the same as characters when using multibyte text), use
+``-b``. To specify particular fields, use ``-f``.
+
+When using ``-f``, the field delimiter can be specified using the ``-d`` switch.
+The default value is the tab character. The ``-s`` switch instructs ``cut`` to
+suppress lines which do not contain any instances of the delimiter -- by default
+they are echoed intact.
+
+For example, to extract the second, fourth and fifth columns in a
+comma-delimited file, ignoring lines which contain no commas, one could use:
+
+.. CODESAMPLE cut-1.ebuild
+
+To chop the first character off stdin, one could use:
+
+.. CODESAMPLE cut-2.ebuild
+
+See `cut-1`_ and `IEEE1003.1-2004-cut`_ for full documentation.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/tools-reference/diff-and-patch/text.rst b/tools-reference/diff-and-patch/text.rst
new file mode 100644
index 0000000..05d2a5a
--- /dev/null
+++ b/tools-reference/diff-and-patch/text.rst
@@ -0,0 +1,31 @@
+diff and patch -- File Differences
+==================================
+
+The ``diff`` tool is used to create patches (sometimes called diffs). A patch is
+a program (computer science definition) which modifies text across one or more
+files. Typically these are used for making changes to source code before it is
+compiled.
+
+The simplest invocation is ``diff -u oldfile newfile``, which will create a list
+of differences in unified format between ``oldfile`` and ``newfile``. To operate
+over directories instead, use ``diff -urN olddir newdir``.
+
+.. Note:: ``cvs`` and ``svn`` provide ``cvs diff`` and ``svn diff`` respectively
+ which may be more helpful.
+
+For patches which go in the main tree, use unified (``-u``) format. This is
+generally the best format to use when sending patches upstream too -- however,
+occasionally you may be asked to provide context diffs, which are more portable
+than unifieds (but don't handle conflicts as cleanly). In this case, use ``-c``
+rather than ``-u``.
+
+To apply a patch, use ``patch -pX < whatever.patch``, where ``X`` is a number
+representing the number of path components which must be removed (typically this
+is ``0`` or ``1``). Within ebuilds, use the ``epatch`` function instead -- see
+`Patching with epatch`_.
+
+The `diff-1`_ and `patch-1`_ manual pages provide more information.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
+
diff --git a/tools-reference/echangelog/text.rst b/tools-reference/echangelog/text.rst
new file mode 100644
index 0000000..5203625
--- /dev/null
+++ b/tools-reference/echangelog/text.rst
@@ -0,0 +1,15 @@
+echangelog -- ChangeLog Generation
+==================================
+
+The ``echangelog`` tool should be used to generate ``ChangeLog`` entries. This
+tool uses the ``ECHANGELOG_USER`` environment variable, which should be set in
+the format ``"Your Name <luser@gentoo.org>"``. The changelog message should be
+passed to ``echangelog`` on the commandline.
+
+``echangelog`` should be called *after* any adds, removes or updates have been
+made.
+
+See `echangelog-1`_ for details.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/tools-reference/echo/text.rst b/tools-reference/echo/text.rst
new file mode 100644
index 0000000..55005bd
--- /dev/null
+++ b/tools-reference/echo/text.rst
@@ -0,0 +1,60 @@
+echo -- Print strings
+=====================
+
+The ``echo`` command can be used to print strings. The standard usage is ``echo
+firstString secondString ...``. Also, it provides additional parameters for
+formatting of the output.
+
+Abuse of ``echo``
+-----------------
+
+If you find yourself about to use ``echo`` in an ebuild, eclass or initscript,
+stop and reconsider. It is almost always unnecessary.
+
+First of all, for printing messages in standard portage scripts, you can use
+the ``einfo``, and ``eerror`` functions along with their corresponding
+functions, ``einfon``, ``eerrorn``, etc, which are the same as the former,
+but they won't print the trailing newline (``\n``).
+
+All usage of the form ``echo ${somevar} | grep substring`` just to check if the
+contents of the ``${somevar}`` variable contains ``substring``, or more
+often, ``echo ${somevar} | command``, are deprecated and should be (and in most
+cases, can be) used as less as possible: doing so involves for no reason an
+additional shell session and a pipe. The "here strings" section describes
+the preferred way of dealing with such cases.
+
+Here Strings
+------------
+
+As of >=bash-2.05b, the so-called "here strings" have been
+introduced. Using "here strings", you can pass contents of an
+environment variable to the standard input of an application, using
+``<<<word`` redirection: what actually happens is that bash
+expands ``word`` and passes the result to the standard input.
+
+A common example would be verifying if a variable ``${foo}`` contains
+the ``bar`` substring with the following construct: ``grep bar <<<
+${foo}``. This replaces the deprecated and more wasteful behaviour of
+using ``echo ${foo} | grep bar``.
+
+Standard usage of ``echo``
+--------------------------
+
+In standard calls, the ``echo`` command with no additional options, outputs the
+arguments passed to the standard output, separated by whitespace and with a
+trailing newline character (``\n``).
+
+If one wants to exclude the trailing newline character, the ``-n`` option can be
+passed, as in: ``echo -n "no trailing newline"``.
+
+Special characters, like tabs (``\t``), newline characters (``\n``), carriage
+return characters (``\r``) (i.e. for translating newlines from DOS format to
+Unix format), and any other ASCII character given by its code value) can be
+passed to the ``echo`` command with the ``-e`` option. For example, to output
+three strings, each on different lines, in a single ``echo`` command, use:
+``echo -e "first line\nsecond line\nthird line"``.
+
+Other escape sequences and additional parameters for the ``echo`` command are
+available in the man page.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/tools-reference/ekeyword/text.rst b/tools-reference/ekeyword/text.rst
new file mode 100644
index 0000000..0ac64ff
--- /dev/null
+++ b/tools-reference/ekeyword/text.rst
@@ -0,0 +1,14 @@
+ekeyword -- Keywording
+======================
+
+The ``ekeyword`` tool should be used to manipulate the ``KEYWORDS`` variable.
+Using this tool will guarantee that you get the correct keyword ordering --
+manual editing may screw this up. The usage is ``ekeyword changes ebuilds``.
+Valid changes are in the form ``sparc`` (to mark stable), ``~sparc`` (to mark
+unstable), ``-sparc`` (to mark unavailable) and ``^sparc`` (to remove the
+``sparc`` keyword). The special ``all`` keyword is useful when doing version
+bumps -- ``ekeyword ~all foo-1.23.ebuild`` will drop all currently present
+keywords to unstable. See `ekeyword-1`_ for details.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/tools-reference/epkgmove/text.rst b/tools-reference/epkgmove/text.rst
new file mode 100644
index 0000000..e4a20fd
--- /dev/null
+++ b/tools-reference/epkgmove/text.rst
@@ -0,0 +1,8 @@
+epkgmove -- Package Moves
+=========================
+
+``epkgmove`` is currently broken. Do not use it.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
+
diff --git a/tools-reference/false-and-true/text.rst b/tools-reference/false-and-true/text.rst
new file mode 100644
index 0000000..519aee7
--- /dev/null
+++ b/tools-reference/false-and-true/text.rst
@@ -0,0 +1,8 @@
+false and true -- Generating Return Codes
+=========================================
+
+The ``false`` utility can be used to obtain a non-zero exit code. The ``true``
+utility always produces a zero exit code.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/tools-reference/find/find-1.ebuild b/tools-reference/find/find-1.ebuild
new file mode 100644
index 0000000..69149db
--- /dev/null
+++ b/tools-reference/find/find-1.ebuild
@@ -0,0 +1,5 @@
+# Header.
+
+find ${S} -type f | while read f ; do
+ einfo "Doing unholy things to ${f}"
+done
diff --git a/tools-reference/find/find-2.ebuild b/tools-reference/find/find-2.ebuild
new file mode 100644
index 0000000..479d7e4
--- /dev/null
+++ b/tools-reference/find/find-2.ebuild
@@ -0,0 +1,5 @@
+# Header.
+
+for f in $(find ${S} -type f) ; do
+ einfo "Calling down holy vengance upon ${f}"
+done
diff --git a/tools-reference/find/find-3.ebuild b/tools-reference/find/find-3.ebuild
new file mode 100644
index 0000000..9c62e4e
--- /dev/null
+++ b/tools-reference/find/find-3.ebuild
@@ -0,0 +1,3 @@
+# Header.
+
+find ${S} -name '*.backup' -exec rm '{}' \;
diff --git a/tools-reference/find/text.rst b/tools-reference/find/text.rst
new file mode 100644
index 0000000..5266021
--- /dev/null
+++ b/tools-reference/find/text.rst
@@ -0,0 +1,55 @@
+find -- Finding Files
+=====================
+
+The ``find`` utility can be used to search for and perform commands upon groups
+of files matching a given set of criteria. The basic usage is ``find path rules``.
+
+For portability purposes, **always** specify a path. Do not rely upon
+``find`` defaulting to the current working directory if no path is provided.
+
+Useful rules include:
+
+================== ===========================================================
+Rule Effect
+================== ===========================================================
+``-name "blah"`` Only find files named ``blah``. The ``*`` and ``?`` wildcards
+ may be used.
+``-type f`` Find only regular files, not directories.
+``-type d`` Find only directories.
+``-type l`` Find only symbolic links.
+``-user foo`` Find only files belonging to user ``foo``. It is best to use
+ named users rather than numeric UIDs. In particular, ``root``
+ may not be UID 0 on some systems.
+``-group foo`` Find only files belonging to group ``foo``. It is best to use
+ named groups rather than numeric GIDs.
+================== ===========================================================
+
+The ``-mindepth`` and ``-maxdepth`` are GNU extensions that should be avoided if
+possible.
+
+By default, ``find`` will echo a list of matching files to the standard output.
+This can be used in a ``while`` loop:
+
+.. CODESAMPLE find-1.ebuild
+
+.. Warning:: The ``die`` construct will **not work** during the above loop. See
+ `die and Subshells`_.
+
+Or a ``for`` loop (for small numbers of files):
+
+.. CODESAMPLE find-2.ebuild
+
+.. Warning:: In both cases, files with weird characters or spaces in their names
+ may cause serious problems.
+
+As an alternative, ``find`` supports a ``-exec`` argument. It accepts a command
+to run, terminated by a semicolon. Inside the command, the string ``{}`` is
+replaced by the name of the current matched file. Be careful with escaping to
+ensure that ``bash`` doesn't gobble up the special characters:
+
+.. CODESAMPLE find-3.ebuild
+
+See `find-1`_ and `IEEE1003.1-2004-find`_ for further details and examples.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/tools-reference/gentoo-syntax/text.rst b/tools-reference/gentoo-syntax/text.rst
new file mode 100644
index 0000000..48acfcc
--- /dev/null
+++ b/tools-reference/gentoo-syntax/text.rst
@@ -0,0 +1,13 @@
+gentoo-syntax -- Enhanced Vim Behaviour
+=======================================
+
+The ``app-vim/gentoo-syntax`` package provides syntax highlighting, indent
+rules, filetype settings and so on for all kinds of Gentoo things within Vim.
+
+Full documentation is provided with the package, and can be viewed `online
+<http://svn.berlios.de/viewcvs/*checkout*/gentoo-syntax/trunk/doc/gentoo-syntax.txt>`_
+or by using ``vim``'s internal help browser (``:help gentoo-syntax``).
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
+
diff --git a/tools-reference/glep31check/text.rst b/tools-reference/glep31check/text.rst
new file mode 100644
index 0000000..66c2cfe
--- /dev/null
+++ b/tools-reference/glep31check/text.rst
@@ -0,0 +1,12 @@
+glep31check -- UTF-8 Validation
+===============================
+
+.. _glep31check:
+
+The ``glep31check`` tool can be used to validate files for `GLEP 31`_ (UTF-8)
+compliance. There is no ebuild in the tree currently -- one can be obtained from
+`here <http://dev.gentoo.org/~ciaranm/overlay/app-portage/glep31check/>`__.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
+
diff --git a/tools-reference/grep/text.rst b/tools-reference/grep/text.rst
new file mode 100644
index 0000000..3f99689
--- /dev/null
+++ b/tools-reference/grep/text.rst
@@ -0,0 +1,36 @@
+grep -- Text Filtering
+======================
+
+The ``grep`` tool can be used to extract lines matching a given regular
+expression from a file, or to check whether a given regular expression matches
+any line in a file.
+
+The usage is ``grep "pattern" files``. If no files are specified, text is read
+from the standard input. The "pattern" is a standard basic regular expression,
+as described in `IEEE1003.1-2004-9.3`_.
+
+If the ``-E`` argument is supplied, ``pattern`` is treated as being an extended
+regular expression as described in `IEEE1003.1-2004-9.4`_.
+
+If the ``-F`` argument is supplied, ``pattern`` is treated as being a fixed
+string rather than a regular expression.
+
+By default, ``grep`` prints out matching lines from the input. If ``-q`` is
+specified, no output is displayed. If ``-l`` (lowercase letter ell) is
+specified, only the filenames of files which contain matching lines are
+displayed.
+
+The ``-v`` option can be used to select lines which do *not* match the pattern.
+
+The ``-s`` option can be used to suppress messages about nonexistent or
+unreadable files.
+
+The return code can be used to test whether or not a match occurred. A return
+code of ``0`` indicates that one or more matches occurred; a code of ``1``
+indicates no matches.
+
+See `IEEE1003.1-2004-grep`_ for details. The `grep-1`_ manual page on GNU systems
+documents many non-portable additional features.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/tools-reference/head-and-tail/head-and-tail-1.ebuild b/tools-reference/head-and-tail/head-and-tail-1.ebuild
new file mode 100644
index 0000000..70a51dc
--- /dev/null
+++ b/tools-reference/head-and-tail/head-and-tail-1.ebuild
@@ -0,0 +1,25 @@
+# Header.
+
+# bad: get the first five lines of input.txt with all 'foo'
+# replaced with 'bar'
+head -n 5 input.txt | sed -e 's/foo/bar/g' > output.txt
+
+# good: use sed's address ranges and command groups to do
+# the same thing with only one fork
+sed -n -e '1,5{ s/foo/bar/g ; p }' input.txt > output.txt
+
+# good: another way is with an extra command which exits
+# on line 5
+sed -n -e 's/foo/bar/gp ; 5q' input.txt > output.txt
+
+# bad: set foo to the first line containing somestring
+foo=$(sed -n -e '/somestring/p' input.txt | head -n 1 )
+
+# good: use early exit to do the same thing in pure sed
+foo=$(sed -n -e '/somestring/{ p ; q }' input.txt )
+
+# bad: output the last line matching 'somestring'
+sed -n -e '/somestring/p' input.txt | tail -n 1
+
+# good: do this in pure sed using the hold space
+sed -n -e '/somestring/h ; ${ x ; p }'
diff --git a/tools-reference/head-and-tail/head-and-tail-2.ebuild b/tools-reference/head-and-tail/head-and-tail-2.ebuild
new file mode 100644
index 0000000..68d3dd4
--- /dev/null
+++ b/tools-reference/head-and-tail/head-and-tail-2.ebuild
@@ -0,0 +1,4 @@
+# Header.
+
+sed -n -e '123p'
+
diff --git a/tools-reference/head-and-tail/text.rst b/tools-reference/head-and-tail/text.rst
new file mode 100644
index 0000000..28ac0cb
--- /dev/null
+++ b/tools-reference/head-and-tail/text.rst
@@ -0,0 +1,40 @@
+head and tail -- Line Extraction
+================================
+
+The ``head`` and ``tail`` utilities can be used to obtain only the first or last
+parts of a file respectively. Both will read from the files named on the
+commandline, or stdin if no files are provided.
+
+The ``head`` utility takes a single argument, ``-n``, which must be followed by
+an integer indicating the desired number of lines to be displayed.
+
+.. Warning:: Use of the GNU ``-c`` option is unportable and should be avoided.
+
+For full details, see `IEEE1003.1-2004-head`_. Note that `head-1`_ on GNU
+systems describes many non-portable options.
+
+The ``tail`` utility is similar, but takes lines from the *end* of the file. The
+``-n`` argument specifies how many lines to display.
+
+To specify "the last five lines", use ``tail -n5``. To specify "all but the
+first five lines", use ``tail -n+5``.
+
+For full details, see `IEEE1003.1-2004-tail`_. Note that `tail-1`_ on GNU
+systems describes many non-portable options.
+
+Chaining ``head`` or ``tail`` with ``sed``
+------------------------------------------
+
+Chaining ``head`` or ``tail`` with ``sed`` is usually unnecessary. Use of
+addresses and early exit can do the same thing with a single ``sed`` call:
+
+.. CODESAMPLE head-and-tail-1.ebuild
+
+``tail -n X`` where X is larger than one is possible to do in pure
+``sed`` but tricky. Using chained commands here is probably simplest.
+
+Finally, to extract a single specific line, use ``sed`` instead:
+
+.. CODESAMPLE head-and-tail-2.ebuild
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/tools-reference/sed/sed-1.ebuild b/tools-reference/sed/sed-1.ebuild
new file mode 100644
index 0000000..039633f
--- /dev/null
+++ b/tools-reference/sed/sed-1.ebuild
@@ -0,0 +1,6 @@
+# Header.
+
+# This plugin is mapped to the 'h' key by default, which conflicts with some
+# other mappings. Change it to use 'H' instead.
+sed -i 's/\(noremap <buffer> \)h/\1H/' info.vim \
+ || die 'sed failed'
diff --git a/tools-reference/sed/sed-10.ebuild b/tools-reference/sed/sed-10.ebuild
new file mode 100644
index 0000000..3f08563
--- /dev/null
+++ b/tools-reference/sed/sed-10.ebuild
@@ -0,0 +1,4 @@
+# Header.
+
+# Replace any "emacs" instances (ignoring case) with "Vim"
+sed -i -e 's/emacs/Vim/gi' editors.txt || die "Ouch"
diff --git a/tools-reference/sed/sed-11.ebuild b/tools-reference/sed/sed-11.ebuild
new file mode 100644
index 0000000..a9f7e20
--- /dev/null
+++ b/tools-reference/sed/sed-11.ebuild
@@ -0,0 +1,12 @@
+# Header.
+
+# Add 'Bob' after the 'To:' line:
+sed -i -e '/^To: $/a Bob' data.in || die "Oops"
+
+# Add 'From: Alice' before the 'To:' line:
+sed -i -e '/^To: $/i From: Alice'
+
+# Note that the spacing between the 'i' or 'a' and 'Bob' or 'From: Alice' is simply ignored'
+
+# Add 'From: Alice' indented by two spaces: (You only need to escape the first space)
+sed -i -e '/^To: $/i\ From: Alice'
diff --git a/tools-reference/sed/sed-2.ebuild b/tools-reference/sed/sed-2.ebuild
new file mode 100644
index 0000000..74ad731
--- /dev/null
+++ b/tools-reference/sed/sed-2.ebuild
@@ -0,0 +1,13 @@
+# Header.
+
+# Add in the Gentoo -r number to fluxbox -version output. We need to look
+# for the line in version.h.in which contains "__fluxbox_version" and append
+# our content to it.
+if [[ "${PR}" == "r0" ]] ; then
+ suffix="gentoo"
+else
+ suffix="gentoo-${PR}"
+fi
+sed -i \
+ -e "s~\(__fluxbox_version .@VERSION@\)~\1-${suffix}~" \
+ version.h.in || die "version sed failed"
diff --git a/tools-reference/sed/sed-3.ebuild b/tools-reference/sed/sed-3.ebuild
new file mode 100644
index 0000000..043a1c4
--- /dev/null
+++ b/tools-reference/sed/sed-3.ebuild
@@ -0,0 +1,11 @@
+# Header.
+
+# This plugin uses an 'automatic HelpExtractor' variant. This causes
+# problems for us during the unmerge. Fortunately, sed can fix this
+# for us. First, we extract the documentation:
+sed -e '1,/^" HelpExtractorDoc:$/d' \
+ ${S}/plugin/ZoomWin.vim > ${S}/doc/ZoomWin.txt \
+ || die "help extraction failed"
+# Then we remove the help extraction code from the plugin file:
+sed -i -e '/^" HelpExtractor:$/,$d' ${S}/plugin/ZoomWin.vim \
+ || die "help extract remove failed"
diff --git a/tools-reference/sed/sed-4.ebuild b/tools-reference/sed/sed-4.ebuild
new file mode 100644
index 0000000..05b1d3f
--- /dev/null
+++ b/tools-reference/sed/sed-4.ebuild
@@ -0,0 +1,8 @@
+# Header.
+
+sed [ option flags ] \
+ -e 'first command' \
+ -e 'second command' \
+ -e 'and so on' \
+ input-file > output-file \
+ || die "Oops, sed didn't work!"
diff --git a/tools-reference/sed/sed-5.ebuild b/tools-reference/sed/sed-5.ebuild
new file mode 100644
index 0000000..1e4d9fa
--- /dev/null
+++ b/tools-reference/sed/sed-5.ebuild
@@ -0,0 +1,6 @@
+# Header.
+
+# replace all instances of "some text" with "different content" in
+# somefile.txt
+sed -i -e 's/some text/different content/g' somefile.txt || \
+ die "Sed broke!"
diff --git a/tools-reference/sed/sed-6.ebuild b/tools-reference/sed/sed-6.ebuild
new file mode 100644
index 0000000..66b75c8
--- /dev/null
+++ b/tools-reference/sed/sed-6.ebuild
@@ -0,0 +1,5 @@
+# Header.
+
+# replace all instances of "/usr/local" with "/usr"
+sed -i -e 's~/usr/local~/usr~g' somefile.txt || \
+ die "sed broke"
diff --git a/tools-reference/sed/sed-7.ebuild b/tools-reference/sed/sed-7.ebuild
new file mode 100644
index 0000000..c7d9aa8
--- /dev/null
+++ b/tools-reference/sed/sed-7.ebuild
@@ -0,0 +1,4 @@
+# Header.
+
+# Replace any "hello"s which occur at the start of a line with "howdy".
+sed -i -e 's!^hello!howdy!' data.in || die "sed failed"
diff --git a/tools-reference/sed/sed-8.ebuild b/tools-reference/sed/sed-8.ebuild
new file mode 100644
index 0000000..7ee3808
--- /dev/null
+++ b/tools-reference/sed/sed-8.ebuild
@@ -0,0 +1,4 @@
+# Header.
+
+# Replace any "bye"s which occur at the end of a line with "cheerio!".
+sed -i -e 's,bye$,cheerio!,' data.in || die "sed failed"
diff --git a/tools-reference/sed/sed-9.ebuild b/tools-reference/sed/sed-9.ebuild
new file mode 100644
index 0000000..c0dce41
--- /dev/null
+++ b/tools-reference/sed/sed-9.ebuild
@@ -0,0 +1,5 @@
+# Header.
+
+# Replace any lines which are exactly "change this line" with "have a
+# cookie".
+sed -i -e 's-^change this line$-have a cookie-' data.in || die "Oops"
diff --git a/tools-reference/sed/text.rst b/tools-reference/sed/text.rst
new file mode 100644
index 0000000..5ab0158
--- /dev/null
+++ b/tools-reference/sed/text.rst
@@ -0,0 +1,338 @@
+sed -- Stream Editor
+====================
+
+Sometimes it is better to use regular expressions to manipulate content rather
+than patching sources. This can be used for small changes, especially those
+which are likely to create patch conflicts across versions. The canonical way of
+doing this is via ``sed``:
+
+.. CODESAMPLE sed-1.ebuild
+
+Another common example is appending a ``-gentoo-blah`` version string (some
+upstreams like us to do this so that they can tell exactly which package they're
+dealing with). Again, we can use ``sed``. Note that the ``${PR}`` variable will
+be set to ``r0`` if we don't have a ``-r`` component in our version.
+
+.. CODESAMPLE sed-2.ebuild
+
+It is also possible to extract content from existing files to create new files
+this way. Many ``app-vim`` ebuilds use this technique to extract documentation
+from the plugin files and convert it to Vim help format.
+
+.. CODESAMPLE sed-3.ebuild
+
+A summary of the more common ways of using ``sed`` and a description of
+commonly used address and token patterns follows. Note that some of these
+constructs are specific to ``GNU sed 4`` -- on non-GNU userland archs, the
+``sed`` command must be aliased to GNU sed. Also note that ``GNU sed 4`` is
+guaranteed to be installed as part of ``system``. This was not always the case,
+which is why some packages, particularly those which use ``sed -i``, have
+``DEPEND`` s upon ``>=sys-apps/sed-4``.
+
+Basic ``sed`` Invocation
+------------------------
+
+The basic form of a call is:
+
+.. CODESAMPLE sed-4.ebuild
+
+For cases where the input and output files are the same, the inplace option
+should be used. This is done by passing ``-i`` as one of the option flags.
+
+Usually ``sed`` prints out every line of the created content. To obtain only
+explicitly printed lines, the ``-n`` flag should be used.
+
+.. Note:: The term *pattern* refers to the description of text being matched.
+
+Simple Text Substitution using ``sed``
+---------------------------------------
+
+The commonest form of ``sed`` is to replace all instances of ``"some text"``
+with ``"different content"``. This is done as follows:
+
+.. CODESAMPLE sed-5.ebuild
+
+.. Note:: The ``/g`` flag is required to replace *all* occurrences. Without this
+ flag, only the first match on each line is replaced.
+
+.. Warning:: The above will replace ``"irksome texting"`` with
+ ``"irkdifferent contenting"``, which may not be desired.
+
+If the pattern or the replacement string contains the forward slash character,
+it is usually easiest to use a different delimiter. Most punctuation characters
+are allowed, although backslash and any form of brackets should be avoided.
+
+.. CODESAMPLE sed-6.ebuild
+
+Patterns can be made to match only at the start or end of a line by using the
+``^`` and ``$`` metacharacters. A ``^`` means "match at the start of a line
+only", and ``$`` means "match at the end of a line only". By using both in a
+single statement, it is possible to match exact lines.
+
+.. CODESAMPLE sed-7.ebuild
+
+.. Note:: There is no need for a ``!g`` suffix here.
+
+.. CODESAMPLE sed-8.ebuild
+
+.. CODESAMPLE sed-9.ebuild
+
+To ignore case in the pattern, add the ``/i`` flag.
+
+.. CODESAMPLE sed-10.ebuild
+
+.. Warning:: Case insensitive matching doesn't work correctly when backreferences
+ are used.
+
+Regular Expression Substitution using ``sed``
+---------------------------------------------
+
+It is also possible to do more complex matches with ``sed``. Some examples could
+be:
+
+* Match any three digits
+* Match either "foo" or "bar"
+* Match any of the letters "a", "e", "i", "o" or "u"
+
+These types of pattern can be chained together, leading to things like "match
+any vowel followed by two digits followed by either foo or bar".
+
+To match any of a set of characters, a *character class* can be used. These come
+in three forms.
+
+* A backslash followed by a letter. ``\d``, for example, matches a single digit
+ (any of 0, 1, 2, ... 9). ``\s`` matches a single whitespace character. A table
+ of the more useful classes is provided later in this document.
+* A group of characters inside square brackets. ``[aeiou]``, for example,
+ matches any one of 'a', 'e', 'i', 'o' or 'u'. Ranges are allowed, such as
+ ``[0-9A-Fa-fxX]``, which could be used to match any hexadecimal digit or the
+ characters 'x' and 'X'. Inverted character classes, such as ``[^aeiou]``,
+ match any single character *except* those listed.
+* A POSIX character class is a special named group of characters that are
+ locale-aware. For example, ``[[:alpha:]]`` matches any 'alphabet' character in
+ the current locale. A table of the more useful classes is provided later in
+ this document.
+
+.. Note:: The regex ``a[^b]`` does **not** mean "match a, so long as it does not
+ have a 'b' after it". It means "match a followed by exactly one character which
+ is not a 'b'". This is important when one considers a line ending in the
+ character 'a'.
+
+.. Note:: At the time of writing, the ``sed`` documentation (`sed-1`_ and
+ ``sed.info``) does not mention that POSIX character classes are supported.
+ Consult `IEEE1003.1-2004-9.3`_ for full details of how these *should* work, and
+ the ``sed`` source code for full details of how these *actually* work.
+
+To match any one of multiple options, *alternation* can be used. The basic form
+is ``first\|second\|third``.
+
+To group items to avoid ambiguity, the ``\(parentheses\)`` construct may be
+used. To match "iniquity" or "infinity", one could use ``in\(iqui\|fini\)ty``.
+
+To optionally match an item, add a ``\?`` after it. For example, ``colou\?r``
+matches both "colour" and "color". This can also be applied to character classes
+and groups in parentheses, for example ``\(in\)\?finite\(ly\)\?``. Further atoms
+are available for matching "one or more", "zero or more", "at least n", "between
+n and m" and so on -- these are summarised later in this document.
+
+There are also some special constructs which can be used in the replacement part
+of a substitution command. To insert the contents of the pattern's first matched
+bracket group, use ``\1``, for the second use ``\2`` and so on up to ``\9``. An
+unescaped ampersand ``&`` character can be used to insert the entire contents of
+the match. These and other replace atoms are summarised later in this document.
+
+Addresses in ``sed``
+--------------------
+
+Many ``sed`` commands can be applied only to a certain line or range of lines.
+This could be useful if one wishes to operate only on the first ten lines of a
+document, for example.
+
+The simplest form of address is a single positive integer. This will cause the
+following command to be applied only to the line in question. Line numbering
+starts from 1, but the address 0 can be useful when one wishes to insert text
+*before* the first line. If the address 100 is used on a 50 line document, the
+associated command will never be executed.
+
+To match the last line in a document, the ``$`` address may be used.
+
+To match any lines that match a given regular expression, the form
+``/pattern/`` is allowed. This can be useful for finding a particular line and
+then making certain changes to it -- sometimes it is simpler to handle this in
+two stages rather than using one big scary ``s///`` command. When used in
+ranges, it can be useful for finding all text between two given markers or
+between a given marker and the end of the document.
+
+To match a range of addresses, ``addr1,addr2`` can be used. Most address
+constructs are allowed for both the start and the end addresses.
+
+Addresses may be inverted with an exclamation mark. To match all lines *except*
+the last, ``$!`` may be used.
+
+Finally, if no address is given for a command, the command is applied to every
+line in the input.
+
+.. Note:: GNU ``sed`` does **not** support the ``%`` address forms found in some
+ other implementations. It also doesn't support ``/addr/+offset``, that's an
+ ``ex`` thing...
+
+Other more complex options involving chaining addresses are available. These are
+not discussed in this document.
+
+Content Deletion using ``sed``
+------------------------------
+
+Lines may be deleted from a file using ``address d`` command. To delete the
+third line of a file, one could use ``3d``, and to filter out all lines
+containing "fred", ``/fred/d``.
+
+.. Note:: sed -e ``/fred/d`` is *not* the same as ``s/.*fred.*//`` -- the former
+ will delete the lines including the newline, whereas the latter will delete the
+ lines' contents but not the newline.
+
+Content Extraction using ``sed``
+--------------------------------
+
+When the ``-n`` option is passed to ``sed``, no output is printed by default.
+The ``p`` command can be used to display content. For example, to print lines
+containing "infra monkey", the command ``sed -n -e '/infra monkey/p'`` could be
+used. Ranges may also be printed -- ``sed -n -e '/^START$/,/^END$/p'`` is
+sometimes useful.
+
+Inserting Content using ``sed``
+-------------------------------
+
+To insert text with sed use a ``address a`` or ``i`` command. The
+``a`` command inserts on the line following the match while the ``i``
+command inserts on the line before the match.
+
+As usual, an address can be either a line number or a regular
+expression: a line number command will only be executed once and a
+regular expression insert/append will be executed for each match.
+
+.. CODESAMPLE sed-11.ebuild
+
+Note that you should use a match instead of a line number wherever
+possible. This reduces problems if a line is added at the beginning of
+the file, for example, causing your sed script to break.
+
+Regular Expression Atoms in ``sed``
+-----------------------------------
+
+Basic Atoms
+'''''''''''
+
+================================== ==========================
+Atom Purpose
+================================== ==========================
+``text`` Literal text
+``\( \)`` Grouping
+``\|`` Alternation, a *or* b
+``*`` ``\?`` ``\+`` ``\{\}`` Repeats, see below
+``.`` Any single character
+``^`` Start of line
+``$`` End of line
+``[abc0-9]`` Any one of
+``[^abc0-9]`` Any one character except
+``[[:alpha:]]`` POSIX character class, see below
+``\1`` .. ``\9`` Backreference
+``\x`` (any special character) Match character literally
+``\x`` (normal characters) Shortcut, see below
+================================== ==========================
+
+Character Class Shortcuts
+'''''''''''''''''''''''''
+
+========= ==========================
+Atom Description
+========= ==========================
+``\a`` "BEL" character
+``\f`` "Form Feed" character
+``\t`` "Tab" character
+``\w`` "Word" (a letter, digit or underscore) character
+``\W`` "Non-word" character
+========= ==========================
+
+
+POSIX Character Classes
+'''''''''''''''''''''''
+
+Read the source, it's the only place these're documented properly...
+
+================= ==========================
+Class Description
+================= ==========================
+``[[:alpha:]]`` Alphabetic characters
+``[[:upper:]]`` Uppercase alphabetics
+``[[:lower:]]`` Lowercase alphabetics
+``[[:digit:]]`` Digits
+``[[:alnum:]]`` Alphabetic and numeric characters
+``[[:xdigit:]]`` Digits allowed in a hexadecimal number
+``[[:space:]]`` Whitespace characters
+``[[:print:]]`` Printable characters
+``[[:punct:]]`` Punctuation characters
+``[[:graph:]]`` Non-blank characters
+``[[:cntrl:]]`` Control characters
+================= ==========================
+
+Count Specifiers
+''''''''''''''''
+
+============= ==========================
+Atom Description
+============= ==========================
+``*`` Zero or more (greedy)
+``\+`` One or more (greedy)
+``\?`` Zero or one (greedy)
+``\{N\}`` Exactly N
+``\{N,M\}`` At least N and no more than M (greedy)
+``\{N,\}`` At least N (greedy)
+============= ==========================
+
+Replacement Atoms in ``sed``
+----------------------------
+
+================== =============================
+Atom Description
+================== =============================
+``\1`` .. ``\9`` Captured ``\( \)`` contents
+``&`` The entire matched text
+``\L`` All subsequent characters are converted to lowercase
+``\l`` The following character is converted to lowercase
+``\U`` All subsequent characters are converted to uppercase
+``\u`` The following character is converted to uppercase
+``\E`` Cancel the most recent ``\L`` or ``\U``
+================== =============================
+
+
+Details of ``sed`` Match Mechanics
+----------------------------------
+
+GNU ``sed`` uses a traditional (non-POSIX) nondeterministic finite automaton with
+extensions to support capturing to do its matching. This means that in all
+cases, the match with the leftmost starting position will be favoured. Of all
+the leftmost possible matches, favour will be given to leftmost alternation
+options. Finally, all other things being equal favour will be given to the
+longest of the leftmost counting options.
+
+Most of this is in violation of one of the sillier POSIX rules, so it's best not
+to rely upon it. It *is* safe to assume that ``sed`` will always pick the leftmost
+match, and that it will match greedily with priority given to items earlier in
+the pattern.
+
+Notes on Performance with ``sed``
+---------------------------------
+
+.. Todo:: write this
+
+Recommended Further Reading for Regular Expressions
+---------------------------------------------------
+
+The author recommends *Mastering Regular Expressions* by Jeffrey E. F. Friedl
+for those who wish to learn more about regexes. This text is remarkably devoid
+of phrases like "let ``t`` be a finite contiguous sequence such that ``t[n] ∈ ∑
+∀ n``", and was *not* written by someone whose pay cheque depended upon them being
+able to express simple concepts with pages upon pages of mathematical and Greek
+symbols.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
diff --git a/tools-reference/sort/text.rst b/tools-reference/sort/text.rst
new file mode 100644
index 0000000..0c90a93
--- /dev/null
+++ b/tools-reference/sort/text.rst
@@ -0,0 +1,15 @@
+sort -- Sorting Text
+====================
+
+The ``sort`` tool can be used to sort text. It sorts the contents of the files
+named on the commandline, or the text provided on standard input if no files are
+given. Output is to standard output by default, unless a ``-o filename`` option
+is provided.
+
+To ignore case, the ``-f`` switch may be used.
+
+Many other options are available. See `sort-1`_ and `IEEE1003.1-2004-sort`_ for
+details.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/tools-reference/text.rst b/tools-reference/text.rst
new file mode 100644
index 0000000..56cc0c2
--- /dev/null
+++ b/tools-reference/text.rst
@@ -0,0 +1,11 @@
+Tools
+=====
+
+This section provides an overview of various useful standard Unix and Gentoo
+tools and utilities that may be used within ebuilds or when working with
+ebuilds.
+
+.. CHILDLIST
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
diff --git a/tools-reference/tr/text.rst b/tools-reference/tr/text.rst
new file mode 100644
index 0000000..63dff78
--- /dev/null
+++ b/tools-reference/tr/text.rst
@@ -0,0 +1,30 @@
+tr -- Character Translation
+===========================
+
+The ``tr`` command can be used to translate, squeeze and delete character
+sequences. See `tr-1`_ and `IEEE1003.1-2004-tr`_ for the full specification.
+
+.. Note:: ``tr``, unlike most other utilities, only reads from standard input
+ and only writes to standard output. Therefore, you will have to use
+ ``tr [options] < input > output``.
+
+``tr`` operates in a number of modes, depending upon the invocation:
+
+Deleting characters
+ To delete all occurrences of certain characters, use ``tr -d asdf``.
+
+Deleting repeated characters
+ To replace repeated characters with a single character ('squeeze'), use
+ ``tr -s asdf``.
+
+Transliterating characters
+ To replace all 'a' characters with '1', all 'b' with '2' and all 'c' with
+ '3', use ``tr abc 123``.
+
+Certain special forms are allowed for the arguments. ``a-z`` expands to all
+characters from 'a' to 'z', ``\t`` represents a tab and so on. See the
+documentation for a full list.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+
+
diff --git a/tools-reference/uniq/text.rst b/tools-reference/uniq/text.rst
new file mode 100644
index 0000000..e2bc402
--- /dev/null
+++ b/tools-reference/uniq/text.rst
@@ -0,0 +1,12 @@
+uniq -- Filtering Duplicates
+============================
+
+The ``uniq`` utility can be used to filter **adjacent** duplicate lines in files
+or in the text provided through standard input.
+
+.. Note:: Instead of using ``sort | uniq``, one should use ``sort -u``.
+
+See `uniq-1`_ and `IEEE1003.1-2004-uniq`_ for details.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..
+