Added current version

svn path=/trunk/webapp-config/; revision=2

6 files changed, 1847 insertions, 0 deletions

diff --git a/doc/.svn.ignore b/doc/.svn.ignore
new file mode 100644
index 0000000..004ede6
--- /dev/null
+++ b/doc/.svn.ignore
@@ -0,0 +1,4 @@
+*.5
+*.8
+*.5.html
+*.8.html
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..aaace8a
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,43 @@
+#
+# webapp-config/doc/Makefile
+#		Simple Makefile to rebuild the documentation from the
+#		docbook XML sources
+#
+#		Part of the webapp-config package
+#
+# Copyright (c) 1999-2005 Gentoo Foundation
+#       Released under v2 of the GNU GPL
+#
+# Author(s)     Stuart Herbert <stuart@gentoo.org>
+#               Renat Lumpau   <rl03@gentoo.org>
+#               Gunnar Wrobel  <php@gunnarwrobel.de>
+#
+# ========================================================================
+
+MAN_PAGES = webapp-config.8 webapp-config.5 webapp.eclass.5
+HTML_PAGES = webapp-config.8.html webapp-config.5.html webapp.eclass.5.html
+
+TMPFILE=./webapp-config.man
+
+all: man html
+
+html: $(HTML_PAGES)
+
+man: $(MAN_PAGES)
+
+clean:
+	rm -f $(MAN_PAGES)
+	rm -f $(HTML_PAGES)
+
+%.html: %.xml
+	@echo HTML $@
+	@xmlto html-nochunks $<
+
+%: %.xml
+	@echo MAN $@
+	@xmlto man $<
+#
+# fix up the blank lines that docbook leaves behind
+#
+	@cat $@ | sed -e 's/$$/.fred/g;' | tr -d '\n' | sed -e 's/.fred.fred\./.fred./g;' | sed -e 's/.fred/\n/g;' > $(TMPFILE)
+	@mv $(TMPFILE) $@
diff --git a/doc/webapp-config.5.xml b/doc/webapp-config.5.xml
new file mode 100644
index 0000000..49de978
--- /dev/null
+++ b/doc/webapp-config.5.xml
@@ -0,0 +1,216 @@
+<?xml version='1.0'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<article>
+  <articleinfo>
+    <title>webapp-config</title>
+
+    <authorgroup>
+      <author>
+        <firstname>Stuart</firstname>
+        <surname>Herbert</surname>
+        <affiliation>
+          <address><email>stuart@gentoo.org</email></address>
+          <address><email>stuart@gnqs.org</email></address>
+        </affiliation>
+      </author>
+      <author>
+        <firstname>Renat</firstname>
+        <surname>Lumpau</surname>
+        <affiliation>
+          <address><email>rl03@gentoo.org</email></address>
+        </affiliation>
+      </author>
+      <author>
+        <firstname>Gunnar</firstname>
+        <surname>Wrobel</surname>
+        <affiliation>
+          <address><email>php@gunnarwrobel.de</email></address>
+        </affiliation>
+      </author>
+    </authorgroup>
+
+    <copyright>
+      <year>2003-2005</year>
+      <holder>Stuart Herbert</holder>
+      <holder>Renat Lumpau</holder>
+      <holder>Gunnar Wrobel</holder>
+    </copyright>
+
+  </articleinfo>
+
+  <section>
+    <title>Reference</title>
+
+    <refentry>
+      <refentryinfo>
+        <title>webapp-config</title>
+	<date>November 2005</date>
+	<productname>Gentoo Linux</productname>
+      </refentryinfo>
+      <refmeta>
+        <refentrytitle>webapp-config</refentrytitle>
+	<manvolnum>5</manvolnum>
+      </refmeta>
+      <refnamediv>
+        <refname>webapp-config</refname>
+	<refpurpose>Configuration file for the <citerefentry><refentrytitle>webapp-config</refentrytitle><manvolnum>8</manvolnum></citerefentry> tool</refpurpose>
+      </refnamediv>
+      <refsynopsisdiv>
+        <cmdsynopsis><command>/etc/vhosts/webapp-config</command></cmdsynopsis>
+      </refsynopsisdiv>
+
+      <refsect1>
+        <title>Description</title>
+	<para><filename>/etc/vhosts/webapp-config</filename> contains the default settings for the <citerefentry><refentrytitle>webapp-config</refentrytitle><manvolnum>8</manvolnum></citerefentry> installer tool.</para>
+      </refsect1>
+
+      <refsect1>
+        <title>Settings</title>
+	<variablelist>
+	  <varlistentry>
+	    <term>vhost_root</term>
+	    <listitem>
+	      <para>Directory which holds the <filename>htdocs</filename> directory for your website.</para>
+	      <para>By default, all websites are <filename>/var/www/<replaceable>fqdn</replaceable></filename>, where <replaceable>fqdn</replaceable> is the full hostname of the website (e.g. www.gentoo.org).  If you are putting your websites somewhere else, you must update vhost_root to suit.</para>
+	      <para>You can use the value of  <userinput>vhost_hostname</userinput> in your definition of <userinput>vhost_root</userinput>.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>vhost_hostname</term>
+	    <listitem>
+	      <para>Default value when <command>webapp-config</command>'s <option>-h</option> switch hasn't been used.</para>
+	      <para>By default, this is set to the full hostname of your computer.  If this hasn't been set correctly, then this is set to <userinput>localhost</userinput> instead.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>vhost_subdomain_{1,2,3...}</term>
+	    <listitem>
+	      <para>The value of <userinput>vhost_hostname</userinput>
+	      is splitted at each dot and the resulting domain name
+	      parts are stored in sequentially
+	      numbered <userinput>vhost_subdomain_N</userinput>
+	      variables (e.g. <userinput>www.test.org</userinput>
+	      results
+	      in <userinput>vhost_subdomain_1</userinput>=org, <userinput>vhost_subdomain_2</userinput>=test,
+	      etc.). 
+	      </para>
+	      <para>
+		You may not set these variables yourself since they
+		are generated internally
+		by <command>webapp-config</command>. But you can use
+		them within the configuration file. So if you want to
+		have fine grained control over the location the web
+		applications get installed, you can
+		set <userinput>vhost_root</userinput>="/var/www/${vhost_subdomain_1}/${vhost_subdomain_2}/${vhost_subdomain_3}"
+	      </para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>vhost_server</term>
+	    <listitem>
+	      <para>Default value when <command>webapp-config</command>'s <option>-s</option> switch hasn't been used.</para>
+	      <para>By default, this is set to <userinput>apache</userinput>, which is the webserver that most people use.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>vhost_config_uid</term>
+	    <listitem>
+	      <para>Default value when <command>webapp-config</command>'s <option>-u</option> switch hasn't been used.</para>
+	      <para>By default, this is set to the username of the user who is running <command>webapp-config</command>.  At the time of writing, <command>webapp-config</command> only works for the <userinput>root</userinput> user, because only the <userinput>root</userinput> user is allowed to change the ownership of files and directories on disk.</para>
+	      <para>This can be <emphasis>either</emphasis> the name of a user or their numerical user id.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>vhost_config_gid</term>
+	    <listitem>
+	      <para>Default value when <command>webapp-config</command>'s <option>-g</option> switch hasn't been used.</para>
+	      <para>By default, this is set to the primary group of the user who is running <command>webapp-config</command>.</para>
+	      <para>This can be <emphasis>either</emphasis> the name of a group or their numerical group id.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>vhost_config_virtual_files</term>
+	    <listitem>
+	      <para>Default value when <command>webapp-config</command>'s <option>--virtual-files</option> switch hasn't been used.</para>
+	      <para>By default, files which can be shared are hardlinked in.  The <glossterm>virtual install</glossterm> does not get a local copy of the file, which normally prevents the web server or non-root users from editing the file.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>vhost_default_uid</term>
+	    <listitem>
+	      <para>Default user to own all files and directories that aren't server-owned or config-owned.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>vhost_default_gid</term>
+	    <listitem>
+	      <para>Default group to own all files and directories that aren't server-owned or config-owned.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>vhost_htdocs_insecure</term>
+	    <term>vhost_htdocs_secure</term>
+	    <listitem>
+	      <para>Default values for the basename of the DocumentRoot.</para>
+	      <para><command>webapp-config</command> installs into <filename>vhost_root/vhost_htdocs_insecure</filename> by default.  If you use the <option>--secure</option> switch, <command>webapp-config</command> installs into <filename>vhost_root/vhost_htdocs_secure</filename> instead.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>vhost_perms_serverowned_dir</term>
+	    <term>vhost_perms_serverowned_file</term>
+	    <listitem>
+	      <para>Default filesystem permissions for directories and files that are installed as 'server-owned'.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>vhost_perms_configowned_dir</term>
+	    <term>vhost_perms_configowned_file</term>
+	    <listitem>
+	      <para>Default filesystem permissions for directories and files that are installed as 'config-owned'.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>vhost_perms_defaultowned_dir</term>
+	    <listitem>
+	      <para>Default filesystem permissions for directories that are installed as 'default-owned'.  Note that it is not possible to install files that are 'default-owned'.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>vhost_perms_virtual_dir</term>
+	    <term>vhost_perms_virtual_file</term>
+	    <listitem>
+	      <para>Default filesystem permissions for directories and files that are installed as 'virtual'.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>vhost_perms_installdir</term>
+	    <listitem>
+	      <para>Default filesystem permissions for the directory that <command>webapp-config</command> installs the package into.</para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+      </refsect1>
+
+      <refsect1>
+        <title>See Also</title>
+	<para><citerefentry><refentrytitle>webapp.eclass</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>webapp-config</refentrytitle><manvolnum>8</manvolnum></citerefentry></para>
+	<para><command>webapp-config</command> is based on the design for an installer for web-based applications first defined in <ulink url="http://www.gentoo.org/proj/en/glep/glep-0011.html">GLEP #11</ulink> for the Gentoo Linux project.</para>
+      </refsect1>
+    </refentry>
+  </section>
+</article>
diff --git a/doc/webapp-config.8.xml b/doc/webapp-config.8.xml
new file mode 100644
index 0000000..e51e172
--- /dev/null
+++ b/doc/webapp-config.8.xml
@@ -0,0 +1,573 @@
+<?xml version='1.0'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<article>
+  <articleinfo>
+    <title>webapp-config</title>
+    
+    <authorgroup>
+      <author>
+        <firstname>Stuart</firstname>
+        <surname>Herbert</surname>
+        <affiliation>
+          <address><email>stuart@gentoo.org</email></address>
+          <address><email>stuart@gnqs.org</email></address>
+        </affiliation>
+      </author>
+      <author>
+        <firstname>Renat</firstname>
+        <surname>Lumpau</surname>
+        <affiliation>
+          <address><email>rl03@gentoo.org</email></address>
+        </affiliation>
+      </author>
+      <author>
+        <firstname>Gunnar</firstname>
+        <surname>Wrobel</surname>
+        <affiliation>
+          <address><email>php@gunnarwrobel.de</email></address>
+        </affiliation>
+      </author>
+    </authorgroup>
+
+    <copyright>
+      <year>2003-2005</year>
+      <holder>Stuart Herbert</holder>
+      <holder>Renat Lumpau</holder>
+      <holder>Gunnar Wrobel</holder>
+    </copyright>
+  </articleinfo>
+
+  <section>
+    <title>Reference</title>
+
+    <refentry>
+      <refentryinfo>
+        <title>webapp-config</title>
+	<date>November 2005</date>
+	<productname>Gentoo Linux</productname>
+      </refentryinfo>
+      <refmeta>
+        <refentrytitle>webapp-config</refentrytitle>
+	<manvolnum>8</manvolnum>
+      </refmeta>
+      <refnamediv>
+        <refname>webapp-config</refname>
+	<refpurpose>manage installs of web-based applications for virtual hosting</refpurpose>
+      </refnamediv>
+
+      <refsynopsisdiv>
+        <cmdsynopsis>
+	  <command>webapp-config</command>
+	  <arg choice="opt">
+	    <option>--bug-report</option>
+	  </arg>
+	  <arg choice="plain">
+	    <option>-I</option>
+	  </arg>
+	  <arg choice="opt">
+	    <option>-dghusDE</option>
+	    <option>--soft</option>
+	    <option>--secure</option>
+	  </arg>
+	  <arg choice="req">
+	    <replaceable>app-name</replaceable>
+	  </arg>
+	  <arg choice="req">
+	    <replaceable>app-version</replaceable>
+	  </arg>
+	</cmdsynopsis>
+
+	<cmdsynopsis>
+	  <command>webapp-config</command>
+	  <arg choice="opt">
+	    <option>--bug-report</option>
+	  </arg>
+	  <arg choice="plain">
+	    <option>-U</option>
+	  </arg>
+	  <arg choice="opt">
+	    <option>-dghusDE</option>
+	  </arg>
+	  <arg choice="req">
+	    <replaceable>app-name</replaceable>
+	  </arg>
+	  <arg choice="req">
+	    <replaceable>app-version</replaceable>
+	  </arg>
+	</cmdsynopsis>
+
+	<cmdsynopsis>
+	  <command>webapp-config</command>
+	  <arg choice="opt">
+	    <option>--bug-report</option>
+	  </arg>
+	  <arg choice="plain">
+	    <option>-C</option>
+	  </arg>
+	  <arg choice="req">
+	    <option>-d</option>
+	    <replaceable>directory</replaceable>
+	  </arg>
+	</cmdsynopsis>
+
+	<cmdsynopsis>
+	  <command>webapp-config</command>
+	  <arg choice="plain">
+	    <option>--list-installs</option>
+	  </arg>
+	  <group choice="opt">
+	    <arg>
+	      <replaceable>app-name</replaceable>
+	    </arg>
+	  </group>
+	  <group choice="opt">
+	    <arg>
+	      <replaceable>app-version</replaceable>
+	    </arg>
+	  </group>
+	</cmdsynopsis>
+
+	<cmdsynopsis>
+	  <command>webapp-config</command>
+	  <arg choice="plain">
+	    <option>--list-unused-installs</option>
+	  </arg>
+	  <group choice="opt">
+	    <arg>
+	      <replaceable>app-name</replaceable>
+	    </arg>
+	  </group>
+	  <group choice="opt">
+	    <arg>
+	      <replaceable>app-version</replaceable>
+	    </arg>
+	  </group>
+	</cmdsynopsis>
+
+	<cmdsynopsis>
+	  <command>webapp-config</command>
+	  <arg choice="plain">
+	    <option>--show-installed</option>
+	  </arg>
+	  <group choice="opt">
+	    <arg>
+	      <option>-d</option>
+	      <replaceable>directory</replaceable>
+	    </arg>
+	  </group>
+	</cmdsynopsis>
+
+	<cmdsynopsis>
+	  <command>webapp-config</command>
+	  <arg choice="plain">
+	    <option>--show-postinst</option>
+	  </arg>
+	  <arg choice="plain">
+	    <replaceable>app-name</replaceable>
+	  </arg>
+	  <arg choice="plain">
+	    <replaceable>app-version</replaceable>
+	  </arg>
+	</cmdsynopsis>
+
+	<cmdsynopsis>
+	  <command>webapp-config</command>
+	  <group choice="plain">
+	    <arg>--list-servers</arg>
+	    <arg>-v</arg>
+	    <arg>--version</arg>
+	    <arg>-h</arg>
+	    <arg>--help</arg>
+	  </group>
+	</cmdsynopsis>
+
+      </refsynopsisdiv>
+
+      <refsect1>
+        <title>Description</title>
+	<para><command>webapp-config</command> is a powerful tool that allows you to install, upgrade, and remove web-based applications in a virtual-hosting environment.</para>
+      </refsect1>
+
+      <refsect1>
+        <title>Web-Based Applications And Virtual Hosts</title>
+	<para><command>webapp-config</command> is aimed at providing the package management functionality that you need if you are running multiple web sites off of the same computer (<glossterm>virtual hosting</glossterm>).</para>
+	<refsect2>
+	  <title>Two-Stage Install</title>
+	  <para>Package managers such as <command>rpm</command> and <command>emerge</command> are designed to install one copy of a package, and to install it onto one fixed location.  This conflicts with the needs of a virtual hosting environment, where you need to be able to install a package in multiple places, so that it can be part of more than just the one website.  But package managers are essential for maintaining a computer over time - so how can we have both?</para>
+	  <para>The answer is a two-stage install.  The traditional package manager installs a <glossterm>master copy</glossterm> into <filename>/usr/share/webapps/</filename>.  This <glossterm>master copy</glossterm> isn't fit to run - but it is ready to then be used by <command>webapp-config</command> to install the package multiple times in multiple places.</para>
+	</refsect2>
+
+	<refsect2>
+	  <title>Multiple Installations Of The Same Package</title>
+	  <para><command>webapp-config</command> allows you to install multiple copies of the same package on the same computer at the same time.  You choose which directory to install each separate copy into.</para>
+	  <para>We call these multiple installations "<glossterm>virtual copies</glossterm>".</para>
+	  <para>You can also have different versions of the same package installed at the same time.  This allows you to gradually roll out a new version of a package across your sites; you are not forced to upgrade every single website at once.</para>
+	  <para><command>webapp-config</command> minimises the number of duplicated files to the absolute minimum possible, to keep disk space usage low.  The majority of files are hard linked to the master copy; only configuration files, and any files that the package needs to write to, are copied into the virtual copy.</para>
+	</refsect2>
+
+  	<refsect2>
+	  <title>File Ownership And Permissions</title>
+	  <para>If you are used to installing web-based applications by hand, you'll appreciate that it can be a pain to get every file owned by the correct user, and with the correct permissions.  Some files need to be owned by the user that the webserver runs as.  Others need to be owned by specific shell accounts, so that those users can login and edit the configuration files.  If your Linux distribution offers you a choice of web servers - each running under a different user - even the installers can struggle to get it right.</para>
+	  <para>With <command>webapp-config</command>, you tell the installer which web server you are going to be using, and which shell account needs to be able to edit the configuration files. <command>webapp-config</command> then installs your files with the correct ownership and permissions.</para>
+	</refsect2>
+
+	<refsect2>
+	  <title>Protected Configuration Files</title>
+	  <para><command>webapp-config</command> automatically ensures that your configuration files are never overwritten during an upgrade - even if you have not edited the files at all.  Additionally, <command>webapp-config</command> will never overwrite any file that it did not install, or that has been changed since it was installed by <command>webapp-config</command>.  <command>webapp-config</command> uses md5 checksums to determine whether a file has been changed or not.  In the case of symbolic links, <command>webapp-config</command> will not replace a symlink that points to a different file.</para>
+	  <para>When an upgrade does attempt to overwrite a protected file, <command>webapp-config</command> creates a ._cfg file with the new file inside.  You can use <command>etc-update</command> to complete the install, just as you would with the regular <command>emerge</command>.</para>
+	</refsect2>
+
+	<refsect2>
+	  <title>Hard Linking vs Soft Linking</title>
+	  <para>A <glossterm>virtual copy</glossterm> is built mostly by creating hard links to files under <filename>/usr/share/webapps</filename>.  If a hard link cannot be created, the file is copied from <filename>/usr/share/webapps</filename> instead.</para>
+	  <para>Hard links can only be created to files on the same filesystem.  If you keep <filename>/usr/share/webapps</filename> and <filename>/var/www</filename> on different filesystems, <command>webapp-config</command> cannot use hard links, and will be forced to copy the files instead.</para>
+	  <para>There are two ways to get around the hard link problem.</para>
+	  <para>The easiest way is to make <filename>/usr/share/webapps</filename> a symlink to a directory under <filename>/var/www</filename>.  For most people, this will ensure that everything is on the same filesystem.</para>
+	  <para>However, if you keep the websites you host on separate filesystems (like I do), then <command>webapp-config</command> is never going to be able to hard-link files for you.</para>
+	  <para>You can choose to use the <option>--soft</option> command-line switch instead.  This switch tells <command>webapp-config</command> to create symbolic links instead of hard links.  Symbolic links work across filesystems.</para>
+	  <para>The problem with using symbolic links is that some packages do not work when the virtual copy is made from symbolic links.  Many users - and system administrators alas - have also complained that they find directories full of symbolic links confusing.  For these reasons, symbolic links are not used by default in <command>webapp-config</command> any more.</para>
+	</refsect2>
+
+        <refsect2>
+          <title>Virtual File Voodoo</title>
+	  <para>By default, the <glossterm>master copy</glossterm> contains the metadata that decides which files get linked into a <glossterm>virtual copy</glossterm> and which files do not.  Files are either owned by the web server (server-owned), are configuration files (config-owned), or are linked in (virtual).  Directories can be server-ownedor config-owned, but most of the time they need to be just plain directories (default-owned) created inside the installation directory (set with the <option>-d</option> switch).  <command>webapp-config</command> provides a number of switches which allows you to override the <glossterm>master copy</glossterm>'s metadata - if you ever find that you need to.</para>
+	  <para>The <option>--default-dirs</option> and <option>--virtual-files</option> switches allow you to decide what <command>webapp-config</command> will do if (respectively) a directory or a file is marked as being default or virtual.  You can tell <command>webapp-config</command> to make the directory or file any of the other choices - server-owned or config-owned - instead.</para>
+        </refsect2>
+  	<refsect2>
+      <title>${ROOT}</title>
+      <para>This version of webapp-config is intended to fully support ${ROOT}. If you are unsure what that means, consult <citerefentry><refentrytitle>emerge</refentrytitle><manvolnum>1</manvolnum></citerefentry></para>
+	</refsect2>
+      </refsect1>
+
+      <refsect1>
+        <title>Actions</title>
+	<variablelist>
+	  <varlistentry>
+	    <term><option>-I</option></term>
+	    <term><option>--install</option></term>
+	    <listitem>
+	      <para>Activate <emphasis>install mode</emphasis>.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>-U</option></term>
+	    <term><option>--upgrade</option></term>
+	    <listitem>
+	      <para>Activate <emphasis>upgrade mode</emphasis>.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>-C</option></term>
+	    <term><option>--clean</option></term>
+	    <listitem>
+	      <para>Activate <emphasis>remove mode</emphasis>.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>--list-installs</option> <replaceable>app-name</replaceable> <replaceable>app-version</replaceable></term>
+	    <term><option>--li</option> <replaceable>app-name</replaceable> <replaceable>app-version</replaceable></term>
+	    <listitem>
+	      <para>Outputs a list of all the virtual copies of the <replaceable>app-name</replaceable>-<replaceable>app-version</replaceable> package.</para>
+	      <para>If you omit <replaceable>app-name</replaceable> or <replaceable>app-version</replaceable> webapp-config will display all available packages/versions.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>--list-unused-installs</option> <replaceable>app-name</replaceable> <replaceable>app-version</replaceable></term>
+	    <term><option>--lui</option> <replaceable>app-name</replaceable> <replaceable>app-version</replaceable></term>
+	    <listitem>
+	      <para>Outputs a list of all the master copies of the <replaceable>app-name</replaceable>-<replaceable>app-version</replaceable> package that have not been installed using <command>webapp-config</command> <option>-I</option>.</para>
+	      <para>Both <replaceable>app-name</replaceable> or <replaceable>app-version</replaceable> can be <emphasis>*</emphasis> to search for multiple packages or versions.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>--show-installed</option></term>
+	    <term><option>--si</option></term>
+	    <listitem>
+	      <para>Outputs the app-name and app-version of the application installed in <replaceable>directory</replaceable>.</para>
+	      <para>Use the <option>-d</option> switch to tell <command>webapp-config</command> which <replaceable>directory</replaceable> to look in.  <replaceable>directory</replaceable> is a directory under the htdocs dir.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>--show-postinst</option> <replaceable>app-name</replaceable> <replaceable>app-version</replaceable></term>
+	    <term><option>--spi</option> <replaceable>app-name</replaceable> <replaceable>app-version</replaceable></term>
+	    <listitem>
+	      <para>Displays the post-installation instructions of the <replaceable>app-name</replaceable>-<replaceable>app-version</replaceable> package.  Very handy if you didn't see them displayed when the package was installed.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>--show-postupgrade</option> <replaceable>app-name</replaceable> <replaceable>app-version</replaceable></term>
+	    <term><option>--spu</option> <replaceable>app-name</replaceable> <replaceable>app-version</replaceable></term>
+	    <listitem>
+	      <para>Displays the post-upgrade instructions of the <replaceable>app-name</replaceable>-<replaceable>app-version</replaceable> package.  Very handy if you didn't see them displayed when the package was upgraded.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>--list-servers</option></term>
+	    <term><option>--ls</option></term>
+	    <listitem>
+	      <para>Outputs a list of the web servers that <command>webapp-config</command> currently supports.</para>
+	      <para>Use the <option>-s</option> <replaceable>server</replaceable> switch to change which web-server an install or upgrade should use.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>-?</option></term>
+	    <term><option>--help</option></term>
+	    <listitem>
+	      <para>Provide a list of supported switches.  Also lists all the default values for each switch.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>-v</option></term>
+	    <term><option>--version</option></term>
+	    <listitem>
+	      <para>Displays the current version number of <command>webapp-config</command></para>
+	    </listitem>
+	  </varlistentry>
+
+	</variablelist>
+      </refsect1>
+
+      <refsect1>
+        <title>Options</title>
+	<para>List of the remaining switches that <command>webapp-config</command> accepts.  To see the default values that <command>webapp-config</command> will use when a switch is omitted, use <userinput>webapp-config --help</userinput>.</para>
+	<variablelist>
+	  <varlistentry>
+	    <term><replaceable>app-name</replaceable> <replaceable>app-version</replaceable></term>
+	    <listitem>
+	      <para>Together, these two parameters tell <command>webapp-config</command> which package to install (<option>-I</option> mode), upgrade to (<option>-U</option> mode), or to search for (<option>--list-installs</option> mode).</para>
+	      <para>They must be the last two parameters passed to <command>webapp-config</command>.</para>
+	      <para>These parameters are not optional.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>--bug-report</option></term>
+	    <term><option>--pretend</option></term>
+	    <term><option>-p</option></term>
+	    <listitem>
+	      <para>Provide output to include inside a bug-report.</para>
+	      <para>Use this switch if you're having problems with the install (<option>-I</option> mode), upgrade (<option>-U</option> mode), or clean (<option>-C</option> mode) operations.  Add this switch to the command-line that's not working, and make sure you paste the output into your bug report.</para>
+	      <para>If you need to use this switch, make sure it's the first switch you use to call <command>webapp-config</command>.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>-s</option> <replaceable>server</replaceable></term>
+	    <term><option>--server</option> <replaceable>server</replaceable></term>
+	    <listitem>
+	      <para>Set which web-server to install (<option>-I</option> mode) or upgrade (<option>-U</option> mode) for.</para>
+	      <para><command>webapp-config</command> needs to know which web server you are going to use to access your virtual copy.  If you don't provide the correct switch, your virtual copy may not work correctly.</para>
+	      <para>Use <userinput>webapp-config --list-servers</userinput> to see a list of valid <replaceable>server</replaceable> settings.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>-u</option> <replaceable>user</replaceable></term>
+	    <term><option>--user</option> <replaceable>user</replaceable></term>
+	    <listitem>
+	      <para>Set which user will own any installed configuration files.</para>
+	      <para>When <command>webapp-apache</command> creates a <glossterm>virtual copy</glossterm> (<option>-I</option> mode), the <glossterm>virtual copy</glossterm> creates <emphasis>local</emphasis> copies of any configuration files that the package needs to use.  By using the <option>-u</option> switch, you can specify which <replaceable>user</replaceable> owns these configuration files.</para>
+	      <para>If you give shell accounts out to the users who host websites on your computer, the <option>-u</option> allows you to give ownership of the configuration file (and therefore write permission) to the shell account associated with the website.</para>
+	      <para><replaceable>user</replaceable> can be a username or a numerical user id.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>-g</option> <replaceable>group</replaceable></term>
+	    <term><option>--group</option> <replaceable>group</replaceable></term>
+	    <listitem>
+	      <para>Set which group will own any installed configuration files.</para>
+	      <para>When <command>webapp-apache</command> creates a <glossterm>virtual copy</glossterm> (<option>-I</option> mode), the <glossterm>virtual copy</glossterm> creates <emphasis>local</emphasis> copies of any configuration files that the package needs to use.  By using the <option>-g</option> switch, you can specify which <replaceable>group</replaceable> owns these configuration files.</para>
+	      <para>If you give shell accounts out to groups of users who host websites on your computer, the <option>-g</option> allows you to give ownership of the configuration file (and therefore write permission) to the group associated with the website.</para>
+	      <para><replaceable>group</replaceable> can be a group name or a numerical group id.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>-d</option> <replaceable>directory</replaceable></term>
+	    <term><option>--dir</option> <replaceable>directory</replaceable></term>
+	    <listitem>
+	      <para>Specify where to create the virtual copy.</para>
+	      <para>The <command>webapp-config</command> tool allows you to create a virtual copy anywhere you want.  You are no longer limited to installing a web-based app in /home/httpd/htdocs/&lt;package-name&gt;/!  Simply use the <option>-d</option> switch to tell <command>webapp-config</command> where you want to create your virtual copy.</para>
+	      <para><replaceable>directory</replaceable> is a directory under your htdocs dir.  If you do not set the <replaceable>hostname</replaceable> correctly (by using the <option>-h</option> switch), <command>webapp-config</command> will look under the wrong htdocs directory!</para>
+	      <para>This option is required by the <option>-C</option> switch.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>-h</option> <replaceable>host</replaceable></term>
+	    <term><option>--host</option> <replaceable>host</replaceable></term>
+	    <listitem>
+	      <para>Specify the <glossterm>fully-qualified domain name</glossterm> of the virtual host.</para>
+	      <para>Some web-based applications - whether through genuine need or bad design - need to know the hostname of the website that they are part of.</para>
+	      <para>Some web-based applications need to install files (such as cgi scripts) that do not belong under the htdocs directory.  To make sure that these files go in the right place, you need to use the <option>-h</option> switch to tell <command>webapp-config</command> the hostname of the website.</para>
+	      <para><replaceable>host</replaceable> must be a <glossterm>fully-qualified domain name</glossterm>.</para>
+	      <para>If you do not use the <option>-h</option> switch, your virtual copy may not work correctly.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>-D</option> <replaceable>KEY=VALUE</replaceable></term>
+	    <term><option>--define</option> <replaceable>KEY=VALUE</replaceable></term>
+	    <listitem>
+	      <para>Define a configuration variable for <command>webapp-config</command>.</para>
+	      <para>
+		Allows to name a <replaceable>KEY=VALUE</replaceable>
+                pair that will be imported into the configuration
+                variables of webapp-config. This allows you to provide
+                customized variables which can be used in the
+                configuration file. This can also be used to
+                temporarily overwrite variables from the configuration
+                file.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>-E</option> <replaceable>variable name</replaceable></term>
+	    <term><option>--envvar</option> <replaceable>variable name</replaceable></term>
+	    <listitem>
+	      <para>Define an environment variable that will be picked up by <command>webapp-config</command>.</para>
+	      <para>
+		Allows to name single environment variable that will
+                be imported by webapp-config. This allows you to
+                provide customized variables which can be used in the
+                configuration file. This can also be used to
+                temporarily overwrite variables from the configuration
+                file.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>--envall</option></term>
+	    <listitem>
+	      <para>Imports all environment variables into the configuration process of <command>webapp-config</command>.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>-V</option></term>
+	    <term><option>--verbose</option></term>
+	    <listitem>
+	      <para>Use this option to increase the amount of output from the <option>--list-installs</option> switch.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>--soft</option></term>
+	    <listitem>
+	      <para>Use this option to create the virtual copy using symbolic links instead of hard links.</para>
+	      <para>You may find this option useful if <filename>/usr/share/webapps</filename> is on a different filesystem to your htdocs directories.  However, it has been discovered that some packages do not work with this option, which is why it is no longer the default behaviour.  You are always better off making <filename>/usr/share/webapps</filename> a symlink to a directory on the same filesystem as your htdocs directories.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>--secure</option></term>
+	    <listitem>
+	      <para>Use this option to install into the <filename>htdocs-secure</filename> directory rather than into the <filename>htdocs</filename> directory.</para>
+	      <para>This option is useful if you keep separate directories for your http: and https: sites.</para>
+	      <para>You can change 'htdocs-secure' by editing the config file <filename>/etc/vhosts/webapp-config</filename>.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>--default-dirs</option> <replaceable>type</replaceable></term>
+	    <term><option>--vd</option> <replaceable>type</replaceable></term>
+	    <term><option>--virtual-files</option> <replaceable>type</replaceable></term>
+	    <term><option>--vf</option> <replaceable>type</replaceable></term>
+	    <listitem>
+	      <para><replaceable>type</replaceable> must be one of:</para>
+	      <variablelist>
+	        <varlistentry>
+		  <term>server-owned</term>
+		  <listitem>
+		    <para>Directories or files are owned by the user that the web server runs as.  Use the <option>-s</option> switch to specify which web server to use.</para>
+		  </listitem>
+		</varlistentry>
+		<varlistentry>
+		  <term>config-owned</term>
+		  <listitem>
+		    <para>Directories or files are owned by the user and group specified with the <option>-u</option> and <option>-g</option> switches.</para>
+		  </listitem>
+		</varlistentry>
+		<varlistentry>
+		  <term>virtual</term>
+		  <listitem>
+		    <para>Directories or files are shared; no local copy is created.</para>
+		  </listitem>
+		</varlistentry>
+	      </variablelist>
+	    </listitem>
+	  </varlistentry>
+
+	</variablelist>
+      </refsect1>
+
+      <refsect1>
+        <title>Examples</title>
+	<para>All of these examples are aimed at Gentoo Linux.  If you are using <command>webapp-config</command> on a different Linux distribution, they may not work out of the box for you.</para>
+	<refsect2>
+	  <title>Installing applications</title>
+	  <para>To install a copy of phpmyadmin-2.5.6, so that it is available from http://www.example.com/databases/admin/, you would do this:</para>
+	  <para><userinput>webapp-config -I -h www.example.com -d /databases/admin/ phpmyadmin 2.5.6</userinput></para>
+	  <para>To make sure that the shell account 'dbadmin' could edit the configuration files of phpmyadmin, you'd add the <option>-u</option> switch like this:</para>
+	  <para><userinput>webapp-config -I -h www.example.com -d /databases/admin -u dbadmin phpmyadmin 2.5.6</userinput></para>
+	</refsect2>
+	<refsect2>
+	  <title>Upgrading applications</title>
+	  <para>To upgrade the copy of phpmyadmin-2.5.6 to version 2.5.7, you would do this:</para>
+	  <para><userinput>webapp-config -U -d /databases/admin/ phpmyadmin 2.5.7</userinput></para>
+	  <para>To upgrade <emphasis>all</emphasis> the virtual copies of phpmyadmin-2.5.6, you would do this:</para>
+	  <para>
+	    <userinput>for x in `webapp-config --li phpmyadmin 2.5.6`;do . ${x}/.webapp &amp;&amp; webapp-config -U -h ${WEB_HOSTNAME} -d ${WEB_INSTALLDIR} phpmyadmin 2.5.7; done</userinput>
+	  </para>
+	</refsect2>
+	<refsect2>
+	  <title>Removing applications</title>
+	  <para>To remove the copy of phpmyadmin-2.5.7, you would do this:</para>
+	  <para><userinput>webapp-config -C -h www.example.com -d /databases/admin/</userinput></para>
+	  <para>To remove <emphasis>all</emphasis> the virtual copies of phpmyadmin-2.5.7, you would do this:</para>
+	  <para>
+	    <userinput>for x in `webapp-config --li phpmyadmin 2.5.7`;do . ${x}/.webapp &amp;&amp; webapp-config -C -h ${WEB_HOSTNAME} -d ${WEB_INSTALLDIR}; done</userinput>
+	  </para>
+	</refsect2>
+      </refsect1>
+
+      <refsect1>
+        <title>Files</title>
+	<variablelist>
+	  <varlistentry>
+	    <term><filename>/etc/vhosts/webapp-config</filename></term>
+	    <listitem>
+	      <para>Configuration file, holding the defaults for <command>webapp-config</command></para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><filename>/var/db/webapps</filename></term>
+	    <listitem>
+	      <para>This directory tree holds information about the location of each virtual copy on the computer.</para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+      </refsect1>
+
+      <refsect1>
+        <title>See Also</title>
+	<para><citerefentry><refentrytitle>webapp.eclass</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>webapp-config</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>emerge</refentrytitle><manvolnum>1</manvolnum></citerefentry></para>
+	<para><command>webapp-config</command> is based on the design for an installer for web-based application installers first defined in <ulink url="http://www.gentoo.org/proj/en/glep/glep-0011.html">GLEP #11</ulink> for the Gentoo Linux project.</para>
+      </refsect1>
+    </refentry>
+  </section>
+</article>
diff --git a/doc/webapp-eclass.xml b/doc/webapp-eclass.xml
new file mode 100644
index 0000000..569b353
--- /dev/null
+++ b/doc/webapp-eclass.xml
@@ -0,0 +1,567 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/webapps/webapp-eclass.xml,v 1.3 2006/01/19 16:43:24 rl03 Exp $ -->
+
+<guide link="/proj/en/webapps/webapp-eclass.xml" lang="en">
+<title>webapp.eclass Documentation</title>
+
+<author title="Author">
+  <mail link="rl03@gentoo.org">Renat Lumpau</mail>
+</author>
+
+<abstract>
+The goal of this guide is to teach the reader how to create and maintain ebuilds
+for web applications. It presents an overview of the webapp.eclass and then
+discusses three ebuilds of increasing complexity and functionality.
+</abstract>
+
+<!-- The content of this document is licensed under the CC-BY-SA license -->
+<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
+<license/>
+
+<version>1.0</version>
+<date>2006-01-17</date>
+
+<chapter>
+<title>Introduction</title>
+<section>
+<title>Background</title>
+<body>
+
+<p>
+<c>webapp.eclass</c> and <c>webapp-config</c> provide a standardized way to
+maintain web applications on Gentoo. Server administrators can use the
+<c>webapp-config</c> utility to install, upgrade, and remove software.
+<c>webapp-config</c> relies on a package manager such as Portage to prepare
+the application for installation into multiple virtual hosts. On Gentoo, this
+is done by an ebuild that uses <c>webapp.eclass</c>.
+</p>
+
+<p>
+The goal of this guide is to teach the reader how to create and maintain
+ebuilds for web applications. It presents an overview of the
+<c>webapp.eclass</c> and then discusses three ebuilds of increasing complexity
+and functionality. Using the <c>webapp-config</c> utility is beyond the scope
+of this guide and is documented in <c>man 8 webapp-config</c>.
+</p>
+
+</body>
+</section>
+<section>
+<title>Prerequisites</title>
+<body>
+
+<p>
+This guide assumes a basic familiarity with Portage and the ebuild format. Both
+are well-documented; the reader is encouraged to consult the <uri
+link="/proj/en/devrel/handbook/handbook.xml">official ebuild HOWTO</uri> and
+the unofficial <uri
+link="http://dev.gentoo.org/~plasmaroo/devmanual/">devmanual</uri>.
+</p>
+
+<p>
+<c>webapp-config</c> is under active development. Be sure to install the latest
+version; as of the time of this writing, it is 1.50.7. You can follow the
+development process on our <uri
+link="http://www.vhost-tools.org/">website</uri>.
+</p>
+
+</body>
+</section>
+<section>
+<title>A standardized approach to installing web applications</title>
+<body>
+
+<p>
+Gentoo has developed a standardized way of handling web applications. It is
+outlined in <uri link="/proj/en/glep/glep-0011.html">GLEP 11</uri> and
+discussed in detail in <c>man 5 webapp.eclass</c>. The reader is urged to
+familiarize himself with these documents before proceeding. The manpage also
+outlines the filesystem locations into which the eclass and
+<c>webapp-config</c> install files; advanced users and developers should take
+note.
+</p>
+
+<p>
+The <c>webapp.eclass</c> is located in the usual place in the Portage tree. By
+default, it will be found in <path>/usr/portage/eclass/webapp.eclass</path>. By
+definition, the source code is the ultimate documentation and should be
+consulted whenever something does not perform as expected or further
+clarification is required.
+</p>
+</body>
+</section>
+</chapter>
+
+<chapter>
+<title>Writing Ebuilds</title>
+<section>
+<title>Beginner: www-apps/gallery-2.0.2</title>
+<body>
+
+<p>
+Many web applications require no compilation and are installed by copying their
+files to a directory to be served by a httpd server such as Apache. The
+<c>webapp.eclass</c> simplifies this task by preparing the necessary set of
+directories.
+</p>
+
+<p>
+Let's take a look at a simple ebuild for <uri
+link="http://sources.gentoo.org/viewcvs.py/gentoo-x86/www-apps/gallery">www-apps/gallery-2.0.2</uri>.
+To use any of the functions in the eclass, the ebuild must first inherit it:
+</p>
+
+<pre caption="Inheriting the eclass">
+inherit webapp.eclass
+</pre>
+
+<p>
+The ebuild then sets several standard variables, such as <c>DESCRIPTION</c>,
+<c>IUSE</c>, <c>RDEPEND</c>, and <c>S</c>. The first important note is that
+ebuilds that use the <c>webapp.eclass</c> do not typically set the <c>SLOT</c>
+variable (the rationale for this is described in the manpage). <uri
+link="#doc_chap2_sect3">Section 2.3</uri> will explain how <c>SLOT</c> can be
+set when it is truly needed, but for now we will let the eclass handle it.
+</p>
+
+<note>
+Unless explicitly overridden, the eclass sets <c>SLOT="${PVR}"</c>. One
+important downside of this behavior is that security revision bumps are no
+longer possible. This is unfortunate and will be changed soon.
+</note>
+
+<p>
+<path>www-apps/gallery-2.0.2</path> does not require patching or compiling, so
+the ebuild does not call <c>src_unpack</c> or <c>src_compile</c>; installation
+is handled in <c>src_install</c>. The first thing <c>src_install</c> does is
+call a special helper function that sets up the required directory structure:
+</p>
+
+<pre caption="Setting up src_install">
+src_install() {
+  webapp_src_preinst
+</pre>
+
+<p>
+This function is required of all ebuilds that use the <c>webapp.eclass</c> and
+override the default <c>src_install</c>.
+</p>
+
+<p>
+Having set up the environment, the ebuild installs the web application:
+</p>
+
+<pre caption="Installing">
+cp -R * ${D}/${MY_HTDOCSDIR}
+</pre>
+
+<p>
+<c>${MY_HTDOCSDIR}</c> is one of the variables exported by
+<c>webapp_src_preinst</c>. Files placed there will be copied into the right
+directory under the webserver's document root by <c>webapp-config</c>. For a
+full list of variables exported by the eclass, please see the manpage.
+</p>
+
+<p>
+Next, the ebuild marks a file in <c>${FILESDIR}</c> as a file containing
+instructions to be displayed by <c>webapp-config</c> after the application has
+been installed:
+</p>
+
+<pre caption="Post-install instructions">
+webapp_postinst_txt en ${FILESDIR}/postinstall-en2.txt
+</pre>
+
+<note>
+A careful reader will observe that it is customary for other ebuilds to display
+instructions to the user in <c>pkg_postinst</c>. Ebuilds that inherit
+<c>webapp.eclass</c> may still do so, but the ebuild author should understand
+the important difference in usage. More often than not, post-install
+instructions include information specific to a virtual host, such as locations
+of a particular configuration file or a URL to access the web application
+remotely. This information is not available to Portage and cannot be included
+in <c>pkg_postinst</c>. Instead, it should be included in a post-install file
+and installed using <c>webapp_postinstall_txt</c>.
+</note>
+
+<p>
+Let's examine a typical post-install file:
+</p>
+
+<pre caption="Post-install file">
+  0. Create a new MySQL database:
+  mysqladmin create geeklog
+
+  1. Edit ${VHOST_ROOT}/${PN}-${PVR}/config.php and set database settings.
+
+  2. Login on
+  http://${VHOST_HOSTNAME}/${VHOST_APPDIR}/admin/install/install.php
+  and follow the directions.
+
+  3. Don't forget to delete the admin/install directory when you're done!
+</pre>
+
+<p>
+Post-install instruction files are plain text files. They can contain
+bash-style variables (e.g., <c>${PN}</c>) that will be expanded at display
+time. The <c>webapp-config</c> utility responsible for displaying the file
+exports a number of variables that allow for the customization of instructions.
+Consult the manpage for a list of available variables.
+</p>
+
+<p>
+Finally, the ebuild calls another mandatory helper function:
+</p>
+
+<pre caption="webapp_src_install">
+webapp_src_install
+</pre>
+
+<p>
+<c>webapp_src_install</c> is responsible for setting the right permissions on
+installed files.
+</p>
+
+<p>
+There are several best practices for writing simple ebuilds:
+</p>
+
+<ul>
+  <li>
+    Don't copy unneeded files. Some packages include <path>.svn</path> or
+    <path>CVS</path> directories or <path>Makefiles</path>; those should be
+    removed prior to installation. Note that the <path>LICENSE</path> file is
+    sometimes needed by the application and should not be removed.
+  </li>
+  <li>
+    Ensure that consecutive calls to all ebuild functions succeed. For
+    instance, don't remove files outside of <c>src_unpack</c>. If you must,
+    remove files from <c>${D}</c> rather than <c>${S}</c>.
+  </li>
+  <li>
+    For portability purposes, don't use GNU-only extensions such as <c>cp
+    -a</c>. They will break on non-GNU userlands such as Gentoo/FreeBSD.
+  </li>
+</ul>
+
+</body>
+</section>
+<section>
+<title>Intermediate: www-apps/tikiwiki-1.9.2</title>
+<body>
+
+<p>
+Many web applications have a more complicated installation procedure. Let's
+look at how <uri
+link="http://sources.gentoo.org/viewcvs.py/gentoo-x86/www-apps/tikiwiki">www-apps/tikiwiki-1.9.2</uri>
+handles one such package. After inheriting the eclass, the ebuild specifies a
+number of required and optional dependencies.
+</p>
+
+<pre caption="Specifying Dependencies">
+RDEPEND="virtual/php
+  mysql? ( >=dev-db/mysql-4 )
+  postgres? ( dev-db/postgresql )
+  graphviz? ( media-gfx/graphviz )
+"
+</pre>
+
+<p>
+Many web-applications written in PHP require that the PHP binary have certain
+capabilities built-in; common requirements include support for sessions and a
+specific database engine. This is typically accomplished by using the
+<c>depend.php</c> eclass; unfortunately, the author is not aware of any existing
+documentation for that eclass. The reader is referred to the eclass itself for
+further information and encouraged to consult relevant ebuilds in Portage.
+</p>
+
+<warn>
+If the package requires specific Perl modules, all dependencies must have
+ebuilds available. Relying on CPAN is not acceptable.
+</warn>
+
+<p>
+A common mistake with specifying dependencies for web applications is to
+unconditionally <c>RDEPEND</c> on a database engine such as MySQL or
+PostgreSQL.  Many, if not all, web applications are able to connect to a remote
+database server. Thus, a local database should not be a requirement; the right
+syntax for dealing with this is:
+</p>
+
+<pre caption="Database Dependencies">
+mysql? ( >=dev-db/mysql-4 )
+</pre>
+
+<note>
+It is currently not possible to depend on a generic webserver. Instead, you
+must explicitly specify the webserver (e.g., <path>net-www/apache</path>). This
+is inconvenient and has been reported in <uri
+link="http://bugs.gentoo.org/show_bug.cgi?id=11007">bug #11007</uri>; we hope
+that this issue will be resolved soon.
+</note>
+
+<p>
+<path>www-apps/tikiwiki</path> does not use <c>depend.php</c> and instead uses
+<c>pkg_setup</c> to print a warning:
+</p>
+
+<pre caption="pkg_setup()">
+pkg_setup () {
+  webapp_pkg_setup
+  einfo "Make sure your PHP is compiled with mysql or postgres support"
+  einfo "If you need PDF generation, make sure your PHP is emerged with xml2"
+}
+</pre>
+
+<p>
+Note the use of a mandatory helper function <c>webapp_pkg_setup</c>.
+</p>
+
+<p>
+Many web applications require write access to certain files. The eclass
+provides a helper function that marks a file as server-owned; at install time,
+<c>webapp-config</c> will ensure that it has the right owner and permissions:
+</p>
+
+<pre caption="webapp_serverowned">
+webapp_serverowned ${MY_HTDOCSDIR}/tiki-install.php
+</pre>
+
+<p>
+<c>webapp_serverowned</c> takes an optional <c>-R</c> flag to recurse into
+subdirectories. This flag has been added recently and not many ebuilds take
+advantage of it. Please consult the manpage for more information.
+</p>
+
+<p>
+Practically all web applications use configuration files to store settings.
+Such files should not be placed into <path>/etc</path> (figuring out the
+rationale is left as an exercise for the reader). To avoid losing important
+configuration information, the eclass provides another helper function that
+will instruct <c>webapp-config</c> not to overwrite an existing file. The
+administrator can use familiar tools such as <c>etc-update</c> or
+<c>dispatch-conf</c> to manage such files.
+</p>
+
+<pre caption="webapp_configfile">
+webapp_configfile ${MY_HTDOCSDIR}/config.php
+</pre>
+
+<p>
+Note that it is currently not possible to mark a file as both server-owned and
+config-protected. This has been fixed in an upcoming version of
+<c>webapp-config</c>. For now, there is a workaround described in <uri
+link="#doc_chap2_sect3">Section 2.3</uri>.
+</p>
+
+<p>
+To ease upgrades of web applications, the eclass provides a helper function
+that displays instructions when an existing installation is being upgraded:
+</p>
+
+<pre caption="Post-upgrade file">
+webapp_postupgrade_txt en ${FILESDIR}/postupgrade-en.txt
+</pre>
+
+<p>
+Even though no ebuilds in Portage currently take advantage this functionality,
+the reader is encouraged to use it in his ebuilds.
+</p>
+
+<p>
+The ebuild calls the familiar helper function to complete the installation.
+Note an important consequence of using <c>webapp_src_install</c> to set the
+correct file permissions: any manual adjustments to file permissions and
+ownership via <c>fowners</c> and <c>fperms</c> must occur <e>after</e>
+<c>webapp_src_install</c> is called.
+</p>
+
+<pre caption="Adjusting permissions">
+webapp_src_install
+fperms 0644 /etc/zm.conf
+</pre>
+
+<p>
+The tikiwiki ebuild displays some brief notes using <c>pkg_postinst</c>. Note
+the use of another helper function:
+</p>
+
+<pre caption="pkg_postinst">
+pkg_postinst() {
+  einfo "To setup a MySQL database, run:"
+  einfo "\"emerge --config =${PF}\""
+  einfo "If you are using PostgreSQL, consult your documentation"
+  webapp_pkg_postinst
+}
+</pre>
+
+<p>
+Strictly speaking, <c>webapp_pkg_postinst</c> is not mandatory. It is
+responsible for automatically calling <c>webapp-config</c> when the
+<c>vhosts</c> USE flag is unset. In rare instances it may be desirable to
+override this behavior; please consult <path>www-apps/otrs</path> for an
+example.
+</p>
+
+</body>
+</section>
+<section>
+<title>Advanced: www-apps/moinmoin-1.5.0</title>
+<body>
+
+<p>
+This section presents an overview of more advanced installation tasks provided
+by the <c>webapp.eclass</c>. An example of this functionality is <uri
+link="http://sources.gentoo.org/viewcvs.py/gentoo-x86/www-apps/moinmoin">www-apps/moinmoin-1.5.0</uri>.
+</p>
+
+<p>
+<c>moinmoin</c> is a wiki engine written in Python that uses <c>distutils</c>
+to install itself. Thus, it requires <c>SLOT="0"</c> to avoid collisions.
+Ebuilds that inherit <c>webapp.eclass</c> must set
+<c>WEBAPP_MANUAL_SLOT="yes"</c> to override the default <c>SLOT</c>ting
+behavior:
+</p>
+
+<pre caption="Setting SLOT">
+SLOT="0"
+WEBAPP_MANUAL_SLOT="yes"
+</pre>
+
+<note>
+The <c>yes</c> in <c>WEBAPP_MANUAL_SLOT="yes"</c> is case-sensitive.
+</note>
+
+<p>
+<c>moinmoin</c> installs files that should not be served by the webserver. The
+ebuild places such files in <c>${MY_HOSTROOTDIR}/${PF}</c>.
+</p>
+
+<pre caption="Installing into dodir ${MY_HOSTROOTDIR}/${PF}">
+dodir ${MY_HOSTROOTDIR}/${PF}
+cp -r data underlay config/wikiconfig.py ${D}/${MY_HOSTROOTDIR}/${PF}
+</pre>
+
+<p>
+A best practice for installing any application via Portage is to ensure it
+operates out of the proverbial box with sensible defaults. The eclass
+implements a helper function to aid with configuring the application after it
+has been installed by <c>webapp-config</c>.
+</p>
+
+<pre caption="webapp_hook_script">
+webapp_hook_script ${FILESDIR}/reconfig-2
+</pre>
+
+<p>
+The reconfig hook is a script, typically written in bash, that is invoked by
+<c>webapp-config</c> after installation and before removal.
+</p>
+
+<pre caption="Reconfig hook">
+#!/bin/bash
+
+die() {
+  echo "#####"
+  echo $1
+  echo "#####"
+  exit 1
+}
+
+if [ $1 = "install" ]; then
+  sed -e "s|/path/to/wikiconfig|${VHOST_ROOT}/${PN}-${PVR}|g" \
+    -i ${MY_INSTALLDIR}/moin.cgi || die "sed failed"
+  sed -e "s|\./data/|${VHOST_ROOT}/${PN}-${PVR}/data|
+    s|\./underlay/|${VHOST_ROOT}/${PN}-${PVR}/underlay|" \
+    -i ${VHOST_ROOT}/${PN}-${PVR}/wikiconfig.py || die "sed failed"
+
+elif [ $1 = "clean" ]; then
+  echo $1
+fi
+</pre>
+
+<p>
+The reconfig hook can use the same variables as the postinstall file. It is
+typically used to edit configuration files to set file locations that may
+differ from the default values. As of <c>webapp-config-1.50</c>, reconfig hooks
+are run in a sandbox to minimize risk; please consult the manpage for more
+details.
+</p>
+
+<p>
+There are several best practices for using reconfig hooks:
+</p>
+
+<ul>
+  <li>Die with an error message if the script failed</li>
+  <li>
+    Be careful about removing files when called with <c>clean</c>. Don't remove
+    configuration files or any other files that may have been locally
+    modified.
+  </li>
+  <li>
+    To mark a file as both config-protected and server-owned, use
+    <c>webapp_configfile</c> from the ebuild and use the reconfig hook to mark
+    it as server-owned:
+  </li>
+</ul>
+
+<pre caption="Using the reconfig hook to mark files as server-owned">
+chown ${VHOST_SERVER_UID}:${VHOST_SERVER_GID} ${MY_INSTALLDIR}/Settings.php
+</pre>
+
+<p>
+The eclass provides several other functions that are rarely used. The most
+notable is <c>webapp_sqlscript</c>, which marks a file as an SQL create script.
+In its current state, this function is only moderately useful.
+</p>
+
+</body>
+</section>
+</chapter>
+
+<chapter>
+<title>Additional Best Practices</title>
+<section>
+<title>Apache</title>
+<body>
+
+<ul>
+  <li>
+    Be careful when installing apache configuration files. If you place a
+    misconfigured Apache configuration file into
+    <path>/etc/apache{2}/vhosts.d</path>, the server will fail on next restart.
+    Is is better to either install the file elsewhere and let the administrator
+    customize it, or comment out the contents to avoid failure.
+  </li>
+</ul>
+
+</body>
+</section>
+</chapter>
+
+<chapter>
+<title>Next Steps</title>
+<section>
+<title>Obtaining More Information</title>
+<body>
+
+<p>
+Additional examples can be found in the <path>www-apps</path> category of the
+Portage tree. Developers and users should also consult the <uri
+link="http://svn.gnqs.org/projects/gentoo-webapps-overlay">web-apps
+overlay</uri> for even more examples and software packages.
+</p>
+
+<p>
+If you have a question that is not answered in this document, please feel free
+to contact the <uri
+link="http://svn.gnqs.org/projects/gentoo-webapps-overlay/wiki/Contributors">web-apps
+herd</uri> or ask on <uri link="irc://freenode/gentoo-web">IRC</uri>.
+</p>
+
+</body>
+</section>
+</chapter>
+</guide>
diff --git a/doc/webapp.eclass.5.xml b/doc/webapp.eclass.5.xml
new file mode 100644
index 0000000..e9bd4ff
--- /dev/null
+++ b/doc/webapp.eclass.5.xml
@@ -0,0 +1,444 @@
+<?xml version='1.0'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<article>
+  <articleinfo>
+    <title>webapp.eclass</title>
+
+    <authorgroup>
+      <author>
+        <firstname>Stuart</firstname>
+        <surname>Herbert</surname>
+        <affiliation>
+          <address><email>stuart@gentoo.org</email></address>
+          <address><email>stuart@gnqs.org</email></address>
+        </affiliation>
+      </author>
+      <author>
+        <firstname>Renat</firstname>
+        <surname>Lumpau</surname>
+        <affiliation>
+          <address><email>rl03@gentoo.org</email></address>
+        </affiliation>
+      </author>
+      <author>
+        <firstname>Gunnar</firstname>
+        <surname>Wrobel</surname>
+        <affiliation>
+          <address><email>wrobel@gentoo.org</email></address>
+        </affiliation>
+      </author>
+    </authorgroup>
+
+    <copyright>
+      <year>2003-2006</year>
+      <holder>Stuart Herbert</holder>
+      <holder>Renat Lumpau</holder>
+      <holder>Gunnar Wrobel</holder>
+    </copyright>
+  </articleinfo>
+
+  <section>
+    <title>Reference</title>
+
+    <refentry>
+      <refentryinfo>
+        <title>webapp.eclass</title>
+	<date>January 2006</date>
+	<productname>Gentoo Linux</productname>
+      </refentryinfo>
+      <refmeta>
+        <refentrytitle>webapp.eclass</refentrytitle>
+	<manvolnum>5</manvolnum>
+      </refmeta>
+      <refnamediv>
+        <refname>webapp.eclass</refname>
+	<refpurpose>standardised approach to writing ebuilds for web-based applications</refpurpose>
+      </refnamediv>
+
+      <refsynopsisdiv>
+        <cmdsynopsis>
+	  <command>inherit webapp</command>
+	</cmdsynopsis>
+      </refsynopsisdiv>
+
+      <refsect1>
+        <title>Description</title>
+	<para>If you are writing an ebuild for a web-based application, your ebuild should use the functions, variables, and techniques documented in this man page.</para>
+	<para>The main reason to use the webapp eclass is that it provides a solution to a number of problems that plagued older approaches:</para>
+	<refsect2>
+	  <title>Support For Virtual Hosts</title>
+	  <para>Many web servers today have to be able to host more than one website at a time.  This is normally done through <glossterm>name-based virtual hosting</glossterm>.  See the Apache documentation for more details about how this works.</para>
+	  <para>Traditional package installers only install a single copy of a package.  Many webservers need to make the same package available as part of different virtual hosts.  The administrator normally ends up installing and upgrading each of these packages by hand.  This makes for more work for the administrator.</para>
+	  <para><userinput>webapp.eclass</userinput> overcomes this problem by installing packages, and associated metadata, in a format and location understood by <citerefentry><refentrytitle>webapp-config</refentrytitle><manvolnum>8</manvolnum></citerefentry>.  The administrator then uses <command>webapp-config</command> to install and upgrade however many copies of the package as he needs.</para>
+	</refsect2>
+	<refsect2>
+	  <title>Installing Into The Correct Directory</title>
+	  <para>Virtual hosts are normally stored on disk in their own directories.  The location of these directories can vary from computer to computer.  It is not unusual for each administrator to have his own preferred location for putting virtual hosts.</para>
+	  <para>Traditional packagers always install a single copy of the package, normally into <filename>/home/httpd/htdocs/&lt;package-name&gt;/</filename>.   If the administrator changes the DocumentRoot of their preferred web server to point to a different directory, traditional packagers are unable to detect this and adjust accordingly.  They also are unable to detect any attempt to install a package into a virtual host.</para>
+	  <para><userinput>webapp.eclass</userinput> overcomes this problem because it makes no attempt to install packages into the webserver's DocumentRoot. Instead, it installs the files of the package into the <filename>/usr/share/webapps</filename> hierarchy - which is never directly used by any webserver.  The administrator then uses <command>webapp-config</command> to complete the installation to the directory of his choice.</para>
+	</refsect2>
+	<refsect2>
+	  <title>Installing With The Correct File Ownerships</title>
+	  <para>Web-based applications are made up of files and directories that need to be owned by more than one user.  Any files or directories that the web server needs to write to - these need to be owned by whatever user the web server runs as.  Configuration files need to be owned by the non-root user who owns the website.  The rest of the files and directories need to be owned by root, to ensure that they cannot be tampered with by other users.</para>
+	  <para>Traditional packagers have no way to understand which user the web server runs as, or which user needs to own the configuration files.  Some packages assume that the user is running the Apache web server, and hard-code the information into their installation scripts.  Unfortunately, any packages that do this will not work if the user chooses to use an alternative web server.</para>
+	  <para><userinput>webapp.eclass</userinput> overcomes this problem because it provides a number of functions which the ebuild can use to indicate who needs to own what.  When the administrator completes the install using <command>webapp-config</command>, he can tell <command>webapp-config</command> which web server the package will be running under, and which user needs to own the configuration files.</para>
+	</refsect2>
+	<refsect2>
+	  <title>Apache Modules vs CGI Scripts</title>
+	  <para>Most web-based applications are written in scripting languages such as PHP, Python, or Perl.  Most scripting languages are available either as Apache modules and as stand-alone CGI scripting engines.  Sometimes, it makes more sense to install scripting languages as CGI scripting engines.  Although CGI engines run much slower than Apache modules, the advantage is that it allows a single computer to run multiple versions of the same language - something that sometimes is necessary.</para>
+	  <para>It's also worth pointing out that the administrator has a choice of web servers - and not all scripting languages run as compiled-in modules in all web servers.</para>
+	  <para>It is difficult-to-impossible for a traditional package manager to provide a single package that can cope with all of the possible permutations.</para>
+	  <para><userinput>webapp.eclass</userinput> provides a function for ebuilds to indicate which script files need to be run by which scripting engine.  <command>webapp-config</command> can, if necessary, modify these script files to use the correct CGI engine when installing into a virtual host.</para>
+	</refsect2>
+	<refsect2>
+	  <title>Overwriting Configuration Files</title>
+	  <para>When packages are upgraded, new configuration files are installed.  Different package managers handle this in different ways.  Portage can prevent files being overwritten on a per-directory basis.  Web-based applications normally have configuration files installed in the same directories as the scripts themselves.  Packages for Portage, therefore, normally end up overwriting the configuration file because the alternative is having to wade through pages of <command>etc-update</command> output.</para>
+	  <para><userinput>webapp.eclass</userinput> avoids this problem by allowing ebuilds to indicate which files are configuration files.  <command>webapp-config</command> uses this information to ensure that configuration files are not overwritten.  The administrator can then use <command>etc-update</command> as normal to complete the upgrade.</para>
+	</refsect2>
+	<refsect2>
+	  <title>Handling Web Server Configuration Files</title>
+	  <para>There are some web-based applications that will not work without installing configuration files for the webserver.  Deciding which webserver to install configuration files for, and where to install these configuration files, is problematic at best.</para>
+	  <para><userinput>webapp.eclass</userinput> addresses this in two ways.  Firstly, ebuilds are encouraged to supply configuration files for <emphasis>all</emphasis> supported webservers.  <command>webapp-config</command> will then install the correct configuration files for the selected webserver when the virtual copy of the application is installed.</para>
+	</refsect2>
+	<refsect2>
+	  <title>Handling SQL Databases</title>
+	  <para>Many web-based applications store their data in sql-based databases.  Installing these databases is enough of a pain; upgrading them is something that's often left to the administrator to struggle through.</para>
+	  <para><userinput>webapp.eclass</userinput> does not provide a full solution today to this problem.  Ebuilds can indicate which files are SQL scripts, and which database engine the scripts are for.  A future version of <userinput>webapp.eclass</userinput> will (hopefully) provide a tool to automatically generate an upgrade script to help the administrator.</para>
+	</refsect2>
+      </refsect1>
+
+      <refsect1>
+        <title>Installation Directories</title>
+	<para><glossterm>webapp.eclass</glossterm> creates an intermediate install of a package, so that the computer's administrator can then perform multiple installations using <citerefentry><refentrytitle>webapp-config</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
+	<para>The intermediate install (known as the <glossterm>master copy</glossterm>) is never used by, or accessed via, the web server.</para>
+	<para>The intermediate install goes into the <filename>/usr/share/webapps</filename> directory structure:</para>
+	<screen>
+/usr/share/webapps
+|- &lt;package name&gt;
+   |- &lt;package version&gt;
+      |- hostroot                     ${MY_HOSTROOTDIR}
+      |- htdocs                       ${MY_HTDOCSDIR}
+      |- cgi-bin                      ${MY_CGIBINDIR}
+      |- conf                         ${MY_SERVERCONFIGDIR}
+      |- errors                       ${MY_ERRORSDIR}
+      |- icons                        ${MY_ICONSDIR}
+        </screen>
+        <variablelist>
+          <varlistentry>
+	    <term>MY_HOSTROOTDIR</term>
+	    <listitem>
+	      <para>Any files or directories that would normally go into <filename>/var/www/localhost</filename> should be installed into this directory.</para>
+	      <para>This directory is for files that you do <emphasis>not</emphasis> want served up under the DocumentRoot.  An example of suitable files would be password databases.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>MY_HTDOCSDIR</term>
+	    <listitem>
+	      <para>Any files or directories that would normally go into <filename>/var/www/localhost/htdocs/&lt;package-name&gt;/</filename> should be installed into this directory.</para>
+	      <para>This directory is for the main files of the package.  Don't put all the files in a subdirectory called &lt;package-name&gt;.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>MY_CGIBINDIR</term>
+	    <listitem>
+	      <para>Any files or directories that would normally go into <filename>/var/www/localhost/cgi-bin/</filename> should be installed into this directory.</para>
+	      <para>At runtime (when the package is running), this directory will be read-only.  You should keep this in mind when deciding which files, scripts, and executables belong in here.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>MY_SERVERCONFIGDIR</term>
+	    <listitem>
+	      <para>This directory contains the per-vhost config files that the web server will use.</para>
+	      <para>You may have to manually configure your webserver to actually use any configuration files installed in this directory.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>MY_ERRORSDIR</term>
+	    <listitem>
+	      <para>Any files or directories that would normally go into <filename>/var/www/localhost/errors/</filename> should be installed into this directory.</para>
+	      <para>When the webserver encounters an error, such as 403: Forbidden or 404: File not found, the default behaviour of the webserver is to look for a page in the MY_ERRORSDIR directory.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>MY_ICONSDIR</term>
+	    <listitem>
+	      <para>Any files or directories that would normally to into <filename>/var/www/localhost/icons/</filename> should be installed into this directory.</para>
+	    </listitem>
+	  </varlistentry>
+        </variablelist>
+      </refsect1>
+
+      <refsect1>
+        <title>Functions</title>
+	<refsect2>
+          <title>Functions for pkg_setup()</title>
+	  <variablelist>
+	    <varlistentry>
+	      <term><command>webapp_pkg_setup</command></term>
+	      <listitem>
+	        <para>If your ebuild has a <userinput>pkg_setup</userinput>, make sure that the first thing it does is to call the <userinput>webapp_pkg_setup</userinput> function.</para>
+		<para>This function performs a lot of sanity checks.</para>
+	      </listitem>
+	    </varlistentry>
+	  </variablelist>
+        </refsect2>
+        <refsect2>
+          <title>Functions for src_install()</title>
+	  <para>The first line of your <userinput>src_install()</userinput> function must be</para>
+	  <screen>
+	  	webapp_src_preinst
+	  </screen>
+	  <para><userinput>webapp_src_preinst()</userinput> prepares ${D}, so that you can install your files into directories as normal.  Then, use these functions <emphasis>after</emphasis> you have installed your files, to add metadata that <command>webapp-config</command> will use later.</para>
+	  <para>Unless explicitly stated in the description of the function, you should assume that these functions do <emphasis>not</emphasis> copy any files into ${D} for you.</para>
+	  <variablelist>
+	    <varlistentry>
+          <term><command>webapp_configfile</command> <replaceable>file</replaceable> <replaceable>[file ...]</replaceable></term>
+	      <listitem>
+	        <para>Use this function to indicate that a particular file is an editable configuration file.  <command>webapp-config</command> will install configuration files so that they can be edited by non-root users.</para>
+		<para><replaceable>file</replaceable> is a config-file.  The file should be in ${D}.  <replaceable>file</replaceable> is normally under ${MY_HTDOCSDIR}.</para>
+	      </listitem>
+	    </varlistentry>
+	    <varlistentry>
+	      <term><command>webapp_hook_script</command> <replaceable>file</replaceable></term>
+	      <listitem>
+	        <para>Use this function to install a script that <command>webapp-config</command> will run immediately after the creation of a <glossterm>virtual copy</glossterm> and immediately before the removal of a <glossterm>virtual copy</glossterm>.</para>
+		<para><replaceable>file</replaceable> is an executable script.  The script must accept one parameter; either <userinput>file install</userinput>, or <userinput>file clean</userinput>.  When called as <userinput>file install</userinput>, the script is running after the creation of a <glossterm>virtual copy</glossterm>.  And when called as <userinput>file clean</userinput>, the script is running immediately before the removal of a <glossterm>virtual copy</glossterm>.</para>
+		<para>Think of hook scripts as a way to perform custom actions that <command>webapp-config</command> itself doesn't give you a way to do.  Because any files created by hook scripts aren't added to the contents list, it is essential that hook scripts also clean up after themselves - because <command>webapp-config</command> cannot do it for you.</para>
+        <para>Hook scripts are now run inside a sandbox. Write access is limited to <userinput>VHOST_HTDOCSDIR</userinput>, <userinput>MY_INSTALLDIR</userinput>, <userinput>VHOST_ROOT</userinput> and <userinput>VHOST_CGIBINDIR</userinput>.</para>
+		<para>Hook scripts can rely on a number of environment variables being set.  They are listed in the HOOK SCRIPT VARS section below.</para>
+        <para>Please note that hook scripts <emphasis>must</emphasis> work correctly with <userinput>${ROOT}</userinput> set!</para>
+	      </listitem>
+	    </varlistentry>
+	    <varlistentry>
+	      <term><command>webapp_postinst_txt</command> <replaceable>language</replaceable> <replaceable>file</replaceable></term>
+	      <listitem>
+	        <para>Use this function to install a plain text file that contains any post-installation instructions that the administrator needs to read about.  <command>webapp-config</command> will show these instructions to the administrator after he has run <command>webapp-config</command> <option>-I</option>.</para>
+		<para>The instructions can contain shell variables.  They will be expanded by <command>webapp-config</command> before being shown to the administrator.</para>
+		<para>The instructions can make use of the environment variables that are listed in the HOOK SCRIPT VARS section below.</para>
+		<para><replaceable>language</replaceable> is for future compatibility.  For now, always use <userinput>en</userinput>.</para>
+		<para><replaceable>file</replaceable> is a text file in ${S}.  This function will install this file for you into ${D}.</para>
+	      </listitem>
+	    </varlistentry>
+	    <varlistentry>
+	      <term><command>webapp_postupgrade_txt</command> <replaceable>language</replaceable> <replaceable>file</replaceable></term>
+	      <listitem>
+	        <para>Use this function to install a plain text file that contains any post-uprade instructions that the administrator needs to read about.  <command>webapp-config</command> will show these instructions to the administrator after he has run <command>webapp-config</command> <option>-U</option>.</para>
+		<para>The instructions can contain shell variables.  They will be expanded by <command>webapp-config</command> before being shown to the administrator.</para>
+		<para>The instructions can make use of the environment variables that are listed in the HOOK SCRIPT VARS section below.</para>
+		<para><replaceable>language</replaceable> is for future compatibility.  For now, always use <userinput>en</userinput>.</para>
+		<para><replaceable>file</replaceable> is a text file in ${S}.  This function will install this file for you into ${D}.</para>
+	      </listitem>
+	    </varlistentry>
+	    <varlistentry>
+          <term><command>webapp_serverowned</command> <replaceable>[-R]</replaceable> <replaceable>file</replaceable> <replaceable>[file ...]</replaceable></term>
+	      <listitem>
+	        <para>Use this function to mark a file that needs to be owned by whichever user the web server runs as.  <command>webapp-config</command> will ensure that the file is owned by the correct user when the time comes.</para>
+		<para><replaceable>file</replaceable> is a file under ${D}.</para>
+        <para>Use the optional <replaceable>-R</replaceable> flag to recurse into subdirectories.</para>
+	      </listitem>
+	    </varlistentry>
+	    <varlistentry>
+	      <term><command>webapp_server_configfile</command> <replaceable>server</replaceable> <replaceable>file</replaceable> <replaceable>newfile</replaceable></term>
+	      <listitem>
+	        <para>Use this function to install a webserver configuration file.  The configuration file is installed into ${MY_SERVERCONFIGDIR}, and <command>webapp-config</command> will install this file during install (-I mode).</para>
+	        <para><replaceable>server</replaceable> is one of: apache, lighttpd, aolserver.</para>
+	        <para><replaceable>file</replaceable> is a webserver configuration file in ${S}.  This should be a configuration file tested with <replaceable>server</replaceable>.</para>
+	        <para><replaceable>newfile</replaceable> is the new name for <replaceable>file</replaceable>.  This parameter is optional; if not supplied, <replaceable>newfile</replaceable> is set to <userinput>`basename <replaceable>file</replaceable>`</userinput>.</para>
+	      </listitem>
+	    </varlistentry>
+	    <varlistentry>
+	      <term><command>webapp_sqlscript</command> <replaceable>sql-engine</replaceable> <replaceable>file</replaceable></term>
+	      <listitem>
+	        <para>Use this function to install an SQL script.  The script is installed into ${MY_SQLSCRIPTSDIR}, but is <emphasis>not</emphasis> installed into any database server at this time.</para>
+		<para><replaceable>sql-engine</replaceable> is one of: mysql, postgresql.</para>
+		<para><replaceable>file</replaceable> is an SQL script in ${S}.  This should be a script to create the tables from scratch.  <replaceable>file</replaceable> will be installed into ${D} for you by this function.</para>
+	      </listitem>
+	    </varlistentry>
+	    <varlistentry>
+	      <term><command>webapp_src_install</command></term>
+	      <listitem>
+	        <para>Call this function at the end of your <userinput>src_install</userinput> function.</para>
+		<para>To see what this function does, read the source code.</para>
+	      </listitem>
+	    </varlistentry>
+	  </variablelist>
+        </refsect2>
+        <refsect2>
+          <title>Functions for pkg_postinst()</title>
+	  <variablelist>
+	    <varlistentry>
+	      <term><command>webapp_pkg_postinst</command></term>
+	      <listitem>
+	        <para>If your ebuild has a <userinput>pkg_postinst</userinput> function, make sure the last thing it does is to call <userinput>webapp_pkg_postinst</userinput>.</para>
+		<para>This function automatically calls <command>webapp-config</command> if the <emphasis>vhosts</emphasis> flag is NOT present.</para>
+	      </listitem>
+	    </varlistentry>
+	  </variablelist>
+	</refsect2>
+      </refsect1>
+
+      <refsect1>
+        <title>Hook Script Vars</title>
+	<para>These environment variables will always be present whenever <command>webapp-config</command> runs a hook script, or whenever post-installation instructions are shown.</para>
+	<variablelist>
+	  <varlistentry>
+	    <term>MY_HOSTROOTDIR</term>
+	    <term>MY_HTDOCSDIR</term>
+	    <term>MY_CGIBINDIR</term>
+	    <term>MY_ERRORSDIR</term>
+	    <term>MY_ICONSDIR</term>
+	    <term>MY_SERVERCONFIGDIR</term>
+	    <term>MY_SQLSCRIPTSDIR</term>
+	    <listitem>
+	      <para>See the Install Directories section above.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>ROOT</term>
+	    <listitem>
+	      <para>The ${ROOT} variable as set by Portage. Please note that you do not need to explicitly add the ${ROOT} prefix - webapp-config will do that automatically.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>MY_INSTALLDIR</term>
+	    <listitem>
+	      <para>The full path to the directory that the virtual copy has been installed into.</para>
+	      <para>If you are not using virtual hosts, this defaults to <filename>/var/www/localhost/htdocs/${PN}/</filename>.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>VHOST_SERVER</term>
+	    <listitem>
+	      <para>The name of the webserver that we are installing for.  Set with the <option>-s</option> option to <command>webapp-config</command>.</para>
+	      <para>At the moment, <command>webapp-config</command> only supports the <command>apache-basic</command> web server, so this isn't a lot of use.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>VHOST_ROOT</term>
+	    <listitem>
+	      <para>The full path to the Document Root's parent directory.</para>
+	      <para>If you are not using virtual hosts, this defaults to <filename>/var/www/localhost/</filename>.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>VHOST_HOSTNAME</term>
+	    <listitem>
+	      <para>The hostname that this application will be accessed via.</para>
+	      <para>If you are not using virtual hosts, this defaults to <filename>localhost</filename>.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>VHOST_HTDOCSDIR</term>
+	    <listitem>
+	      <para>The full path to the Document Root of the website that the virtual copy is being installed into.</para>
+	      <para>If you are not using virtual hosts, this defaults to <filename>/var/www/localhost/htdocs/</filename>.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>VHOST_APPDIR</term>
+	    <listitem>
+	      <para>The directory under VHOST_HTDOCSDIR where the virtual copy is being installed into.  If you want the full path, use $MY_INSTALLDIR.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>VHOST_CGIBINDIR</term>
+	    <listitem>
+	      <para>The directory under VHOST_HTDOCSDIR which cgi-bin files installed into.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>VHOST_CONFDIR</term>
+	    <listitem>
+	      <para>The directory under VHOST_HTDOCSDIR which server configuration files are installed into.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>VHOST_ERRORSDIR</term>
+	    <listitem>
+	      <para>The directory under VHOST_HTDOCSDIR which custom error files are installed into.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>VHOST_ICONSDIR</term>
+	    <listitem>
+	      <para>The directory under VHOST_HTDOCSDIR which custom server icons are installed into.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>VHOST_CONFIG_UID</term>
+	    <listitem>
+	      <para>The name of the user who owns all configuration files.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>VHOST_CONFIG_GID</term>
+	    <listitem>
+	      <para>The name of the user who owns all configuration files.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>VHOST_SERVER_UID</term>
+	    <listitem>
+	      <para>The name of the user who will own all server-owned files and directories.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>VHOST_SERVER_GID</term>
+	    <listitem>
+	      <para>The name of the group who owns all server-owned files and directories.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>VHOST_DEFAULT_UID</term>
+	    <listitem>
+	      <para>The name of the user who owns all the remaining files and directories.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>VHOST_DEFAULT_GID</term>
+	    <listitem>
+	      <para>The name of the group who owns all the remaining files and directories.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>VHOST_PERMS_SERVEROWNED_DIR</term>
+	    <term>VHOST_PERMS_SERVEROWNED_FILE</term>
+	    <term>VHOST_PERMS_CONFIGOWNED_DIR</term>
+	    <term>VHOST_PERMS_CONFIGOWNED_FILE</term>
+	    <term>VHOST_PERMS_DEFAULTOWNED_DIR</term>
+	    <term>VHOST_PERMS_VIRTUALOWNED_DIR</term>
+	    <term>VHOST_PERMS_VIRTUALOWNED_FILE</term>
+	    <term>VHOST_PERMS_INSTALLDIR</term>
+	    <listitem>
+	      <para>See <citerefentry><refentrytitle>webapp-config</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.</para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+      </refsect1>
+
+      <refsect1>
+        <title>Examples</title>
+	<para>See <filename>/usr/share/doc/webapp-config*/</filename> for example ebuilds.</para>
+      </refsect1>
+
+      <refsect1>
+        <title>Files</title>
+	<variablelist>
+	  <varlistentry>
+	    <term><filename>/etc/vhosts/webapp-config</filename></term>
+	    <listitem>
+	      <para>Configuration file, holding the defaults for <command>webapp-config</command> and the <userinput>webapp.eclass</userinput> eclass.</para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+      </refsect1>
+
+      <refsect1>
+        <title>See Also</title>
+	<para><citerefentry><refentrytitle>webapp-config</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>webapp-config</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>emerge</refentrytitle><manvolnum>1</manvolnum></citerefentry></para>
+	<para>The <userinput>webapp.eclass</userinput> is part of the <command>webapp-config</command> package.  <command>webapp-config</command> is based on the design for an installer for web-based applications first discussed in <ulink url="http://www.gentoo.org/proj/en/glep/glep-0011.html">GLEP #11</ulink> for the Gentoo Linux project.</para>
+      </refsect1>
+    </refentry>
+  </section>
+</article>