A number of documentation fixes and preparation of the project website.

1 files changed, 660 insertions, 364 deletions

diff --git a/doc/layman.8.xml b/doc/layman.8.xml
index ecd2ec7..c11ad9c 100644
--- a/doc/layman.8.xml
+++ b/doc/layman.8.xml
@@ -1,6 +1,6 @@
 <?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">
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 <article>
 
   <articleinfo>
@@ -8,8 +8,8 @@
     
     <authorgroup>
       <author>
-        <firstname>Gunnar</firstname>
-        <surname>Wrobel</surname>
+	<firstname>Gunnar</firstname>
+	<surname>Wrobel</surname>
 	<affiliation>
 	  <address>
 	    <email>wrobel@gentoo.org</email>
@@ -22,33 +22,154 @@
     </authorgroup>
 
     <copyright>
-      <year>2006</year>
+      <year>2006-2007</year>
       <holder>Gunnar Wrobel</holder>
     </copyright>
   </articleinfo>
 
   <section>
+    <title>Overview</title>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  <link linkend="layman-synopsis">Synopsis</link>
+	</para>
+      </listitem>
+    </itemizedlist>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  <link linkend="layman-description">Description</link>
+	</para>
+      </listitem>
+    </itemizedlist>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  <link linkend="layman-actions">Action flags</link>
+	</para>
+      </listitem>
+    </itemizedlist>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  <link linkend="layman-other-options">Other options</link>
+	</para>
+      </listitem>
+    </itemizedlist>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  <link linkend="layman-configuration">Configuration</link>
+	</para>
+      </listitem>
+    </itemizedlist>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  <link linkend="layman-remote">Overlay lists</link>
+	</para>
+      </listitem>
+    </itemizedlist>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  <link linkend="layman-local">Layman cache</link>
+	</para>
+      </listitem>
+    </itemizedlist>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  <link linkend="layman-make-conf">Handling make.conf</link>
+	</para>
+      </listitem>
+    </itemizedlist>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  <link linkend="layman-update">Handle overlays</link>
+	</para>
+      </listitem>
+    </itemizedlist>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  <link linkend="layman-list">List overlays</link>
+	</para>
+      </listitem>
+    </itemizedlist>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  <link linkend="layman-types">Overlay types</link>
+	</para>
+      </listitem>
+    </itemizedlist>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  <link linkend="layman-global">Get your overlay published to the world</link>
+	</para>
+      </listitem>
+    </itemizedlist>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  <link linkend="layman-examples">Examples</link>
+	</para>
+      </listitem>
+    </itemizedlist>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  <link linkend="layman-files">Layman files</link>
+	</para>
+      </listitem>
+    </itemizedlist>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  <link linkend="layman-bugs">Reporting bugs</link>
+	</para>
+      </listitem>
+    </itemizedlist>
+  </section>
+
+  <section id="layman-reference">
     <title>Reference</title>
 
-    <refentry>
+    <refentry id="layman-manpage">
       <refentryinfo>
-        <title>layman</title>
-	<date>February 2006</date>
-	<productname>Gentoo Linux</productname>
+	<title>layman</title>
+	<date>September 2007</date>
+	<productname>layman</productname>
+	<productnumber>1.1</productnumber>
+	<copyright>
+	  <year>2006-2007</year>
+	  <holder>Gunnar Wrobel</holder>
+	</copyright>
+	<legalnotice>
+	  <para>
+	    This is free software.  You may redistribute copies of it
+	    under the terms of the GNU General Public License v2
+	    (http://www.gnu.org/licenses/old-licenses/gpl-2.0.html).
+	  </para>
+	</legalnotice>
       </refentryinfo>
       <refmeta>
-        <refentrytitle>layman</refentrytitle>
+	<refentrytitle>layman</refentrytitle>
 	<manvolnum>8</manvolnum>
       </refmeta>
       <refnamediv>
-        <refname>layman</refname>
+	<refname>layman</refname>
 	<refpurpose>
-	  manage your local repository of gentoo overlays
+	  manage your local repository of Gentoo overlays
 	</refpurpose>
       </refnamediv>
 
-      <refsynopsisdiv>
-        <cmdsynopsis>
+      <refsynopsisdiv id="layman-synopsis">
+	<cmdsynopsis>
 	  <command>layman</command>
 	  <group choice="plain">
 	    <arg>-a</arg>
@@ -60,7 +181,7 @@
 	  </group>
 	</cmdsynopsis>
 
-        <cmdsynopsis>
+	<cmdsynopsis>
 	  <command>layman</command>
 	  <group choice="plain">
 	    <arg>-d</arg>
@@ -72,7 +193,7 @@
 	  </group>
 	</cmdsynopsis>
 
-        <cmdsynopsis>
+	<cmdsynopsis>
 	  <command>layman</command>
 	  <group choice="plain">
 	    <arg>-s</arg>
@@ -84,7 +205,19 @@
 	  </group>
 	</cmdsynopsis>
 
-        <cmdsynopsis>
+	<cmdsynopsis>
+	  <command>layman</command>
+	  <group choice="plain">
+	    <arg>-i</arg>
+	    <arg>--info</arg>
+	  </group>
+	  <group choice="plain">
+	    <arg>ALL</arg>
+	    <arg><replaceable>overlay</replaceable></arg>
+	  </group>
+	</cmdsynopsis>
+
+	<cmdsynopsis>
 	  <command>layman</command>
 	  <group choice="plain">
 	    <arg>-S</arg>
@@ -92,7 +225,7 @@
 	  </group>
 	</cmdsynopsis>
 
-        <cmdsynopsis>
+	<cmdsynopsis>
 	  <command>layman</command>
 	  <group choice="plain">
 	    <arg>-L</arg>
@@ -100,7 +233,7 @@
 	  </group>
 	</cmdsynopsis>
 
-        <cmdsynopsis>
+	<cmdsynopsis>
 	  <command>layman</command>
 	  <group choice="plain">
 	    <arg>-l</arg>
@@ -108,7 +241,7 @@
 	  </group>
 	</cmdsynopsis>
 
-        <cmdsynopsis>
+	<cmdsynopsis>
 	  <command>layman</command>
 	  <group choice="plain">
 	    <arg>-f</arg>
@@ -116,106 +249,381 @@
 	  </group>
 	</cmdsynopsis>
 
-        <cmdsynopsis>
-	  <command>layman</command>
-	  <group choice="plain">
-	    <arg>-n</arg>
-	    <arg>--nofetch</arg>
-	  </group>
-	</cmdsynopsis>
-
-        <cmdsynopsis>
-	  <command>layman</command>
-	  <group choice="plain">
-	    <arg>-k</arg>
-	    <arg>--nocheck</arg>
-	  </group>
-	</cmdsynopsis>
-
-        <cmdsynopsis>
-	  <command>layman</command>
-	  <group choice="plain">
-	    <arg>-q</arg>
-	    <arg>--quiet</arg>
-	  </group>
-	</cmdsynopsis>
-
-        <cmdsynopsis>
-	  <command>layman</command>
-	  <group choice="plain">
-	    <arg>-Q</arg>
-	    <arg>--quietness</arg>
-	    <group choice="plain">
-	      <arg><replaceable>0-4</replaceable></arg>
-	    </group>
-	  </group>
-	</cmdsynopsis>
-
       </refsynopsisdiv>
 
-      <refsect1>
-        <title>Description</title>
+      <refsection id="layman-description">
+	<title>Description</title>
 
 	<para><command>layman</command> is a script that allows you to
-	add, remove and update gentoo overlays from a variety of
+	add, remove and update Gentoo overlays from a variety of
 	sources.</para>
 
-      </refsect1>
+	<refsection>
+	  <title>WARNING</title>
 
-      <refsect1>
-        <title>WARNING</title>
-
-	<para><command>layman</command> makes it easy to retrieve and
-	  update overlays for gentoo. In addition it makes it TRIVIAL
+	  <para><command>layman</command> makes it easy to retrieve and
+	  update overlays for Gentoo. In addition it makes it TRIVIAL
 	  to break your system. 
-	</para>
+	  </para>
 
-	<para>The main portage tree provides you with high quality ebuilds
-	  that are all maintained by gentoo developers. This will not
+	  <para>The main portage tree provides you with high quality ebuilds
+	  that are all maintained by Gentoo developers. This will not
 	  be the case for most of the overlays you can get by using
 	  <command>layman</command>. Thus you are removing the
 	  security shield that the standard tree provides for
 	  you. You should keep that in mind when installing ebuilds
 	  from an overlay.
-	</para>
+	  </para>
 
-	<para>To ensure the security of your system you MUST read the
+	  <para>To ensure the security of your system you MUST read the
 	  source of the ebuild you are about to install. 
-	</para>
+	  </para>
+
+	</refsection>
+
+      </refsection>
+
+      <refsection id="layman-options">
+	<title>Options</title>
+
+	<refsection id="layman-actions">
+	  <title>Actions</title>
+
+	  <para>List of possible <command>layman</command> actions.</para>
+
+	  <variablelist>
+	    <varlistentry>
+	      <term><option>-f</option></term>
+	      <term><option>--fetch</option></term>
+	      <listitem>
+		<para>Fetches the remote list of overlays. You will
+		usually NOT need to explicitely specify this option. The
+		fetch operation will be performed automatically once you
+		run the sync, sync-all, or list action. You can prevent
+		this automatic fetching using the --nofetch option.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><option>-a</option> <replaceable>overlay</replaceable></term>
+	      <term><option>--add</option> <replaceable>overlay</replaceable></term>
+	      <listitem>
+		<para>Add the given overlay from the cached remote list to
+		your locally installed overlays. Specify "ALL" to add
+		all overlays from the remote list.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><option>-d</option> <replaceable>overlay</replaceable></term>
+	      <term><option>--delete</option> <replaceable>overlay</replaceable></term>
+	      <listitem>
+		<para>Remove the given overlay from your locally installed
+		overlays. Specify "ALL" to remove all overlays</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><option>-s</option> <replaceable>overlay</replaceable></term>
+	      <term><option>--sync</option> <replaceable>overlay</replaceable></term>
+	      <listitem>
+		<para>Update the specified overlay. Use "ALL" as
+		parameter to synchronize all overlays</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><option>-i</option> <replaceable>overlay</replaceable></term>
+	      <term><option>--info</option> <replaceable>overlay</replaceable></term>
+	      <listitem>
+		<para>Display all available information about the specified overlay.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><option>-S</option></term>
+	      <term><option>--sync-all</option></term>
+	      <listitem>
+		<para>Update all overlays. Shortcut for -s ALL.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><option>-L</option></term>
+	      <term><option>--list</option></term>
+	      <listitem>
+		<para>List the contents of the remote list.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><option>-l</option></term>
+	      <term><option>--list-local</option></term>
+	      <listitem>
+		<para>List the locally installed overlays.</para>
+	      </listitem>
+	    </varlistentry>
+
+	  </variablelist>
+	</refsection>
+
+	<refsection id="layman-other-options">
+
+	  <title>Other options</title>
+
+	  <para>List of other available <command>layman</command> options.</para>
+
+	  <variablelist>
+
+	    <varlistentry>
+	      <term><option>-c</option> <replaceable>path</replaceable></term>
+	      <term><option>--config</option> <replaceable>path</replaceable></term>
+	      <listitem>
+		<para>Path to an alternative configuration file.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><option>-o</option> <replaceable>url</replaceable></term>
+	      <term><option>--overlays</option> <replaceable>url</replaceable></term>
+	      <listitem>
+		<para>Specifies the location of additional overlay
+		lists. You can use this flag several times and the
+		specified urls will get temporarily appended to the list
+		of urls you specified in your config file. You may also
+		specify local file URLs by prepending the path with
+		<userinput>file://</userinput>. This option
+		will only append the URL for this specific layman run -
+		edit your config file to add a URL permanently. So this
+		is useful for testing purposes.
+		</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><option>-n</option></term>
+	      <term><option>--nofetch</option></term>
+	      <listitem>
+		<para>Prevents <command>layman</command> from
+		automatically fetching the remote lists of overlays. The
+		default behaviour for <command>layman</command> is to
+		update all remote lists if you run the sync, list or
+		fetch operation.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><option>-k</option></term>
+	      <term><option>--nocheck</option></term>
+	      <listitem>
+		<para>Prevents <command>layman</command> from checking
+		the remote lists of overlays for complete overlay
+		definitions. The default behaviour for layman is to
+		reject overlays that do not provide a description or a
+		contact attribute.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><option>-q</option></term>
+	      <term><option>--quiet</option></term>
+	      <listitem>
+		<para>Makes <command>layman</command> completely quiet.
+		This option is dangerous: If the processes spawned by
+		layman when adding or synchronizing overlays require
+		any input layman will hang without telling you
+		why. This might happen for example if your overlay
+		resides in subversion and the SSL certificate of
+		the server needs acceptance.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><option>-v</option></term>
+	      <term><option>--verbose</option></term>
+	      <listitem>
+		<para>Makes <command>layman</command> more verbose and
+		you will receive a description of the overlays you can
+		download.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><option>-N</option></term>
+	      <term><option>--nocolor</option></term>
+	      <listitem>
+		<para>Remove color codes from the <command>layman</command>
+		output.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><option>-Q</option><replaceable>LEVEL</replaceable></term>
+	      <term><option>--quietness</option><replaceable>LEVEL</replaceable></term>
+	      <listitem>
+		<para>Makes <command>layman</command> less verbose.
+		Choose a value between 0 and 4 with 0 being completely
+		quiet. Once you set this below 3, the same warning as
+		given for --quiet applies.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><option>-p</option><replaceable>LEVEL</replaceable></term>
+	      <term><option>--priority</option><replaceable>LEVEL</replaceable></term>
+	      <listitem>
+		<para>Use this option in combination with
+		the <command>--add</command>. It will modify the
+		priority of the added overlay and thus influence the
+		order of entries in the make.conf file. The lower the
+		priority, the earlier in the list the entry will be
+		mentioned. Use a value between 0 and 100. The default
+		value is 50.</para>
+	      </listitem>
+	    </varlistentry>
+
+	  </variablelist>
+
+	</refsection>
+
+      </refsection>
+
+      <refsection id="layman-configuration">
+
+	<title>Configuration</title>
+
+	<para><command>layman</command> reads configuration parameters
+	from the file
+	<filename>/etc/layman/layman.cfg</filename> by
+	default. This file provides seven possible settings.</para>
+
+	<variablelist>
+
+	  <varlistentry>
+	    <term><option>storage</option></term>
+	    <listitem>
+	      <para>Directory that will be used to store the overlays
+	      and all additional data <command>layman</command>
+	      needs. The default is
+	      <filename>/usr/portage/local/layman</filename>. layman
+	      uses a location within the /usr/portage hierarchy instead
+	      of <filename>/var</filename> in order to
+	      store its data. This decision has been made to support
+	      network filesystems. If you have your portage tree on nfs
+	      or a similar filesystem and several machines access the
+	      same ebuild repository over the net it will be necessary
+	      to also provide all necessary <command>layman</command>
+	      data within the hierarchy of the tree. This way the
+	      overlays will also have to be synced at one location
+	      only.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>cache</option></term>
+	    <listitem>
+	      <para><command>layman</command> will store the downloaded
+	      global list of overlays here. The default is
+	      <filename>%(storage)s/cache.xml</filename>.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>overlays</option></term>
+	    <listitem>
+	      <para><command>layman</command> will store the list of
+	      installed overlays here. The default is
+	      <filename>%(storage)s/overlays.xml</filename>.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>make.conf</option></term>
+	    <listitem>
+	      <para>This is the portage configuration file that
+	      <command>layman</command> will modify in order to make
+	      the new overlays available within portage. The default
+	      is <filename>%(storage)s/make.conf</filename>. You could
+	      also specify <filename>/etc/make.conf
+	      directly</filename>. But that would mean that you have
+	      an external program trying to automatically set
+	      variables within this very central configuration
+	      file. Since I consider that dangerous I prefer having a
+	      very small external file that only contains the setting
+	      for PORTAGE_OVERLAYS. This file is then sourced at the
+	      end of <filename>/etc/make.conf</filename>. This is the
+	      reason why <command>layman</command> suggests running
+	      "echo "source
+	      <filename>/usr/portage/local/layman/make.conf</filename>" >>
+	      <filename>/etc/make.conf</filename>" after it has been
+	      installed.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>overlays</option></term>
+	    <listitem>
+	      <para>Specifies the url for the remote list of all
+	      available overlays. The default is
+	      <filename>http://www.gentoo.org/proj/en/overlays/layman-global.txt</filename>. You
+	      can specify several URLs here (one per line). The
+	      contents will get merged to a single list of
+	      overlays. This allows to add a personal collection of
+	      overlays that are not present in the global list.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>proxy</option></term>
+	    <listitem>
+	      <para>Specify your proxy in case you have to use
+	      one.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><option>nocheck</option></term>
+	    <listitem>
+	      <para>Set to "yes" if <command>layman</command> should stop
+	      worrying about overlays with missing a contact address or
+	      the description.</para>
+	    </listitem>
+	  </varlistentry>
 
-      </refsect1>
+	</variablelist>
 
-      <refsect1>
+      </refsection>
 
-        <title>Handling overlays</title>
+      <refsection id="layman-handling">
+	<title>Handling overlays</title>
 
 	<para><command>layman</command> intends to provide easy
-	  maintenance of gentoo overlays while not requiring any
-	  configuration.
+	maintenance of Gentoo overlays while not requiring any
+	configuration.
 	</para>
 
-	<refsect2>
+	<refsection id="layman-remote">
 
-	  <title>Remote overlay lists</title>
+	  <title>Overlay lists</title>
 
-	  <para><command>layman</command> allows you to fetch an overlay
-	    without the need to modify any configuration files. In
-	    order for this to be possible the script needs an external
-	    list of possible overlay sources. There will be a
-	    centralized list available <ulink
-	    url="http://www.gentoo.org/proj/en/overlays/layman-global.txt">here</ulink>,
-	    but nothing will prevent you from using or publishing your
-	    own list of overlays. The location of the remote lists can
-	    also be modified using the <option>--overlays</option> option
-	    when running <command>layman</command>.
+	  <para><command>layman</command> allows you to fetch an
+	  overlay without the need to modify any configuration
+	  files. In order for this to be possible the script needs an
+	  external list of possible overlay sources. There is a
+	  centralized list available at <ulink
+	  url="http://www.gentoo.org/proj/en/overlays/layman-global.txt"/>
+	  but nothing will prevent you from using or publishing your
+	  own list of overlays. The location of the remote lists can
+	  also be modified using the <option>--overlays</option>
+	  option when running <command>layman</command>.
 	  </para>
 
 	  <para>To get a new overlay added to the central list provided
-	    for layman, send a mail to
-	    <email>overlays@gentoo.org</email>. Gentoo developers may
-	    add their overlay entries directly into the list which can
-	    be accessed over the CVS repository for the Gentoo
-	    website.
+	  for layman, send a mail to
+	  <email>overlays@gentoo.org</email>. Gentoo developers may
+	  add their overlay entries directly into the list which can
+	  be accessed over the CVS repository for the Gentoo
+	  website.
 	  </para>
 
 	  <para>You can also use several lists at the same time. Just
@@ -225,9 +633,9 @@
 	  </para>
 
 	  <para><command>layman</command> also allows you to define
-	    local files in this list. Just make sure you prepend these
-	    pathnames in standard URL notation
-	    with <filename>file://</filename>.
+	  local files in this list. Just make sure you prepend these
+	  pathnames in standard URL notation
+	  with <filename>file://</filename>.
 	  </para>
 
 	  <para>If you need to use a proxy for access to the internet,
@@ -237,59 +645,59 @@
 	  environment variable in case you set it.
 	  </para>
 
-	</refsect2>
+	</refsection>
 
-	<refsect2>
+	<refsection id="layman-local">
 
 	  <title>Local cache</title>
 
 	  <para><command>layman</command> stores a local copy of the
-	    fetched remote list. It will be stored in
-	    <filename>/usr/portage/local/layman/cache.xml</filename>
-	    by default. There exists only one such cache file and it
-	    will be overwritten every time you
-	    run <command>layman</command>.
+	  fetched remote list. It will be stored in
+	  <filename>/usr/portage/local/layman/cache.xml</filename>
+	  by default. There exists only one such cache file and it
+	  will be overwritten every time you
+	  run <command>layman</command>.
 	  </para>
 
-	</refsect2>
+	</refsection>
 
-	<refsect2>
+	<refsection id="layman-make-conf">
 
 	  <title>Handling <filename>/etc/make.conf</filename></title>
 
 	  <para>Since <command>layman</command> is designed to
-	    automatically handle the inclusion of overlays into your
-	    system it needs to be able to modify
-	    the <command>PORTDIR_OVERLAY</command> variable in your
-	    <filename>/etc/make.conf</filename> file. But
-	    <filename>/etc/make.conf</filename> is a very central and
-	    essential configuration file for a gentoo
-	    system. Automatically modifying this file would be
-	    somewhat dangerous. You can
-	    allow <command>layman</command> to do this by setting
-	    the <command>make_conf</command> variable in the
-	    configuration file to <filename>/etc/make.conf</filename>.
+	  automatically handle the inclusion of overlays into your
+	  system it needs to be able to modify
+	  the <command>PORTDIR_OVERLAY</command> variable in your
+	  <filename>/etc/make.conf</filename> file. But
+	  <filename>/etc/make.conf</filename> is a very central and
+	  essential configuration file for a Gentoo
+	  system. Automatically modifying this file would be
+	  somewhat dangerous. You can
+	  allow <command>layman</command> to do this by setting
+	  the <command>make_conf</command> variable in the
+	  configuration file to <filename>/etc/make.conf</filename>.
 	  </para>
 
 	  <para>A much safer and in fact recommended solution to the
-	    problem is to let <command>layman</command> handle an
-	    external file that only contains
-	    the <command>PORTDIR_OVERLAY</command> variable and is
-	    sourced within the
-	    standard <filename>/etc/make.conf</filename> file. Just add the following line to the end of your 
-	    <filename>/etc/make.conf</filename> file:
+	  problem is to let <command>layman</command> handle an
+	  external file that only contains
+	  the <command>PORTDIR_OVERLAY</command> variable and is
+	  sourced within the
+	  standard <filename>/etc/make.conf</filename> file. Just add the following line to the end of your 
+	  <filename>/etc/make.conf</filename> file:
 	  </para>
 
 	  <para>source /usr/portage/local/layman/make.conf</para>
 
 	  <para><filename>/usr/portage/local/layman/make.conf</filename>
-	    is the default provided in the layman
-	    configuration. Change this filename in case you decide to
-	    store it somewhere else.
+	  is the default provided in the layman
+	  configuration. Change this filename in case you decide to
+	  store it somewhere else.
 	  </para>
 
 	  <para>The file does not necessarily need to exist at the
-	    beginning. If it is missing, layman will create it for you.
+	  beginning. If it is missing, layman will create it for you.
 	  </para>
 
 	  <para>There is also no need to remove the
@@ -298,285 +706,163 @@
 	  this variable and all your old entries will remain in there.
 	  </para>
 
-	</refsect2>
+	</refsection>
 
-	<refsect2>
+	<refsection id="layman-update">
 
 	  <title>Adding, removing and updating overlays</title>
 
 	  <para>Once a remote list of overlays has been fetched,
-	    <command>layman</command> allows to add overlays from the
-	    remote list to your system. The script will try to fetch
-	    the overlay. If this is successful the overlay information
-	    will be copied from the cache to the list of locally
-	    installed overlays. In addition
-	    <command>layman</command> will modify the
-	    <command>PORTDIR_OVERLAY</command> variable to include the
-	    new overlay path.
+	  <command>layman</command> allows to add overlays from the
+	  remote list to your system. The script will try to fetch
+	  the overlay. If this is successful the overlay information
+	  will be copied from the cache to the list of locally
+	  installed overlays. In addition
+	  <command>layman</command> will modify the
+	  <command>PORTDIR_OVERLAY</command> variable to include the
+	  new overlay path.
 	  </para>
 
 	  <para>Removing the overlay with <command>layman</command>  will
-	    delete the overlay without leaving any traces behind.
+	  delete the overlay without leaving any traces behind.
 	  </para>
 
 	  <para>In order to update all overlays managed by
-	    <command>layman</command> you can run the script with the 
-	    <option>--sync ALL</option> option or
-	    the <option>--sync-all</option> flag.
+	  <command>layman</command> you can run the script with the 
+	  <option>--sync ALL</option> option or
+	  the <option>--sync-all</option> flag.
 	  </para>
 
-	</refsect2>
+	</refsection>
 
-	<refsect2>
+	<refsection id="layman-list">
 
 	  <title>List overlays</title>
 
 	  <para><command>layman</command> provides the
-	    <option>--list</option> and <option>--list-local</option>
-	    options to print a list of available respectively
-	    installed overlays.
+	  <option>--list</option> and <option>--list-local</option>
+	  options to print a list of available respectively
+	  installed overlays.
 	  </para>
 
 	  <para> Listing will prepend all fully supported overlays
-	    with a green asterisk, all non-official overlays with a
-	    yellow asterisk and all overlays that you will not be able
-	    to use since you do not have the necessary tools installed
-	    with a red asterisk.
+	  with a green asterisk, all non-official overlays with a
+	  yellow asterisk and all overlays that you will not be able
+	  to use since you do not have the necessary tools installed
+	  with a red asterisk.
 	  </para>
 
 	  <para> In the default mode layman will be strict about
-	    listing overlays and only present you with overlays that
-	    are fully supported. In addition it will complain about
-	    overlays that are missing a description field or a contact
-	    attribute. This type of behaviour has been added with
-	    layman-1.0.7 and if you'd like to return to the old
-	    behaviour you may use the k option flag or set the nocheck
-	    option in the configuration file.
+	  listing overlays and only present you with overlays that
+	  are fully supported. In addition it will complain about
+	  overlays that are missing a description field or a contact
+	  attribute. This type of behaviour has been added with
+	  layman-1.0.7 and if you'd like to return to the old
+	  behaviour you may use the k option flag or set the nocheck
+	  option in the configuration file.
 	  </para>
 
-	</refsect2>
+	</refsection>
 
-	<refsect2>
+	<refsection id="layman-types">
 
 	  <title>Overlay types</title>
 
 	  <para>Currently <command>layman</command> supports overlays that
-	    are exported via <command>rsync</command>,
-	    <command>subversion</command>, <command>bzr</command>, 
-	    <command>darcs</command>, <command>git</command>, 
-	    <command>mercurial</command> or provided
-	    as <command>tar</command> packages.
+	  are exported via <command>rsync</command>,
+	  <command>subversion</command>, <command>bzr</command>, 
+	  <command>darcs</command>, <command>git</command>, 
+	  <command>mercurial</command> or provided
+	  as <command>tar</command> packages.
 	  </para>
 
-	</refsect2>
-
-      </refsect1>
-
-      <refsect1>
-
-        <title>Actions</title>
-
-	<para>List of possible <command>layman</command> actions.</para>
-
-	<variablelist>
-	  <varlistentry>
-	    <term><option>-f</option></term>
-	    <term><option>--fetch</option></term>
-	    <listitem>
-	      <para>Fetches the remote list of overlays. You will
-	      usually NOT need to explicitely specify this option. The
-	      fetch operation will be performed automatically once you
-	      run the sync, sync-all, or list action. You can prevent
-	      this automatic fetching using the --nofetch option.</para>
-	    </listitem>
-	  </varlistentry>
-
-	  <varlistentry>
-	    <term><option>-a</option> <replaceable>overlay</replaceable></term>
-	    <term><option>--add</option> <replaceable>overlay</replaceable></term>
-	    <listitem>
-	      <para>Add the given overlay from the cached remote list to
-	      your locally installed overlays. Specify "ALL" to add
-	      all overlays from the remote list.</para>
-	    </listitem>
-	  </varlistentry>
-
-	  <varlistentry>
-	    <term><option>-d</option> <replaceable>overlay</replaceable></term>
-	    <term><option>--delete</option> <replaceable>overlay</replaceable></term>
-	    <listitem>
-	      <para>Remove the given overlay from your locally installed
-	      overlays. Specify "ALL" to remove all overlays</para>
-	    </listitem>
-	  </varlistentry>
-
-	  <varlistentry>
-	    <term><option>-s</option> <replaceable>overlay</replaceable></term>
-	    <term><option>--sync</option> <replaceable>overlay</replaceable></term>
-	    <listitem>
-	      <para>Update the specified overlay. Use "ALL" as
-	      parameter to synchronize all overlays</para>
-	    </listitem>
-	  </varlistentry>
-
-	  <varlistentry>
-	    <term><option>-i</option> <replaceable>overlay</replaceable></term>
-	    <term><option>--info</option> <replaceable>overlay</replaceable></term>
-	    <listitem>
-	      <para>Display all available information about the specified overlay.</para>
-	    </listitem>
-	  </varlistentry>
-
-	  <varlistentry>
-	    <term><option>-S</option></term>
-	    <term><option>--sync-all</option></term>
-	    <listitem>
-	      <para>Update all overlays. Shortcut for -s ALL.</para>
-	    </listitem>
-	  </varlistentry>
-
-	  <varlistentry>
-	    <term><option>-L</option></term>
-	    <term><option>--list</option></term>
-	    <listitem>
-	      <para>List the contents of the remote list.</para>
-	    </listitem>
-	  </varlistentry>
-
-	  <varlistentry>
-	    <term><option>-l</option></term>
-	    <term><option>--list-local</option></term>
-	    <listitem>
-	      <para>List the locally installed overlays.</para>
-	    </listitem>
-	  </varlistentry>
-
-	</variablelist>
-      </refsect1>
-
-      <refsect1>
-
-        <title>Options</title>
+	</refsection>
+
+      </refsection>
+
+      <refsection id="layman-global">
+
+	<title>Overlay lists</title>
+
+	<refsection>
+
+	  <title>Overlay list format</title>
+
+	  <para>
+	    Layman uses a central list of overlays in xml format. The file looks like this:
+	    <example>
+	      <title>An example overlay.xml file</title>
+	      <programlisting>
+	      &lt;?xml version="1.0" ?&gt;
+	      &lt;layman&gt;
+	      &lt;overlays&gt;
+	      &lt;overlay
+	      type = "svn"
+	      src  = "https://mydomain.net/svn/myoverlay/"
+	      contact = "me@mydomain.net"
+	      name = "myoverlay"&gt;
+	      
+	      &lt;link&gt;
+	      http://mydomain.net/myoverlay
+	      &lt;/link&gt;
+	      
+	      &lt;description&gt;
+	      Contains some of my ebuilds.
+	      &lt;/description&gt;
+	      &lt;/overlay&gt;
+	      &lt;/overlays&gt;
+	      </programlisting>
+	    </example>
+	  </para>
 
-	<para>List of available <command>layman</command> options.</para>
+	</refsection>
 
-	<variablelist>
+	<refsection>
 
-	  <varlistentry>
-	    <term><option>-c</option> <replaceable>path</replaceable></term>
-	    <term><option>--config</option> <replaceable>path</replaceable></term>
-	    <listitem>
-	      <para>Path to an alternative configuration file.</para>
-	    </listitem>
-	  </varlistentry>
+	  <title>Adding an overlay locally</title>
 
-	  <varlistentry>
-	    <term><option>-o</option> <replaceable>url</replaceable></term>
-	    <term><option>--overlays</option> <replaceable>url</replaceable></term>
-	    <listitem>
-	      <para>Specifies the location of additional overlay
-	      lists. You can use this flag several times and the
-	      specified urls will get temporarily appended to the list
-	      of urls you specified in your config file. You may also
-	      specify local file urls by prepending the path with
-	      file://. This option will only append the URL for this
-	      specific layman run - edit your config file to add a URL
-	      permanently. So this is useful for testing purposes.
-	      </para>
-	    </listitem>
-	  </varlistentry>
-
-	  <varlistentry>
-	    <term><option>-n</option></term>
-	    <term><option>--nofetch</option></term>
-	    <listitem>
-	      <para>Prevents <command>layman</command> from
-	      automatically fetching the remote lists of overlays. The
-	      default behaviour for <command>layman</command> is to
-	      update all remote lists if you run the sync, list or
-	      fetch operation.</para>
-	    </listitem>
-	  </varlistentry>
+	  <para>
+	    Simply create an overlay list in the format described
+	    above and run <command>layman</command> with the
+	    <option>-o</option> switch. You need to
+	    prepend local file URLs with
+	    <userinput>file://</userinput>.
+	  </para>
 
-	  <varlistentry>
-	    <term><option>-k</option></term>
-	    <term><option>--nocheck</option></term>
-	    <listitem>
-	      <para>Prevents <command>layman</command> from checking
-	      the remote lists of overlays for complete overlay
-	      definitions. The default behaviour for layman is to
-	      reject overlays that do not provide a description or a
-	      contact attribute.</para>
-	    </listitem>
-	  </varlistentry>
+	</refsection>
 
-	  <varlistentry>
-	    <term><option>-q</option></term>
-	    <term><option>--quiet</option></term>
-	    <listitem>
-	      <para>Makes <command>layman</command> completely quiet.
-		This option is dangerous: If the processes spawned by
-		layman when adding or synchronizing overlays require
-		any input layman will hang without telling you
-		why. This might happen for example if your overlay
-		resides in subversion and the SSL certificate of
-		the server needs acceptance.</para>
-	    </listitem>
-	  </varlistentry>
+	<refsection>
 
-	  <varlistentry>
-	    <term><option>-v</option></term>
-	    <term><option>--verbose</option></term>
-	    <listitem>
-	      <para>Makes <command>layman</command> more verbose and
-	        you will receive a description of the overlays you can
-	        download.</para>
-	    </listitem>
-	  </varlistentry>
+	  <title>Adding an overlay globally</title>
 
-	  <varlistentry>
-	    <term><option>-N</option></term>
-	    <term><option>--nocolor</option></term>
-	    <listitem>
-	      <para>Remove color codes from the <command>layman</command>
-	      output.</para>
-	    </listitem>
-	  </varlistentry>
+	  <para>
+	    The global list of overlays used by
+	    <command>layman</command> lies at
+	    <filename>http://www.gentoo.org/proj/en/overlays/layman-global.txt</filename>.
+	  </para>
 
-	  <varlistentry>
-	    <term><option>-Q</option><replaceable>LEVEL</replaceable></term>
-	    <term><option>--quietness</option><replaceable>LEVEL</replaceable></term>
-	    <listitem>
-	      <para>Makes <command>layman</command> less verbose.
-		Choose a value between 0 and 4 with 0 being completely
-		quiet. Once you set this below 3, the same warning as
-		given for --quiet applies.</para>
-	    </listitem>
-	  </varlistentry>
+	  <para>
+	    All Gentoo developers have access to this location via CVS
+	    and can modify the list of overlays.
+	  </para>
 
-	  <varlistentry>
-	    <term><option>-p</option><replaceable>LEVEL</replaceable></term>
-	    <term><option>--priority</option><replaceable>LEVEL</replaceable></term>
-	    <listitem>
-	      <para>Use this option in combination with
-		the <command>--add</command>. It will modify the
-		priority of the added overlay and thus influence the
-		order of entries in the make.conf file. The lower the
-		priority, the earlier in the list the entry will be
-		mentioned. Use a value between 0 and 100. The default
-		value is 50.</para>
-	    </listitem>
-	  </varlistentry>
+	  <para>
+	    If you are not a Gentoo developer but whish to get your
+	    overlay listed you should contact the Gentoo Overlays team
+	    at <email>overlays@gentoo.org</email>. You can also join
+	    <userinput>#gentoo-overlays</userinput> on
+	    <filename>irc.freenode.net</filename>.
+	  </para>
 
-	</variablelist>
+	</refsection>
 
-      </refsect1>
+      </refsection>
 
-      <refsect1>
+      <refsection id="layman-examples">
 
-        <title>Examples</title>
+	<title>Examples</title>
 
-	<refsect2>
+	<refsection>
 
 	  <title>Installing an overlay</title>
 
@@ -585,18 +871,18 @@
 	  <command>wrobel</command> to your list of installed
 	  overlays.</para>
 
-	</refsect2>
+	</refsection>
 
-	<refsect2>
+	<refsection>
 
 	  <title>Syncing your overlays</title>
 
 	  <para><userinput>layman -s ALL</userinput></para>
 	  <para>This updates all overlays</para>
 
-	</refsect2>
+	</refsection>
 
-	<refsect2>
+	<refsection>
 
 	  <title>Performing several actions at the same time</title>
 
@@ -604,13 +890,13 @@
 	  <para>This fetches the remote list and immediately adds two
 	  overlays</para>
 
-	</refsect2>
+	</refsection>
 
-      </refsect1>
+      </refsection>
 
-      <refsect1>
+      <refsection id="layman-files">
 
-        <title>Files</title>
+	<title>Files</title>
 
 	<variablelist>
 
@@ -624,7 +910,17 @@
 
 	</variablelist>
 
-      </refsect1>
+      </refsection>
+
+      <refsection id="layman-bugs">
+
+	<title>Reporting bugs</title>
+	
+	<para>
+	  Please report bugs you might find at <ulink url="http://bugs.gentoo.org"/>
+	</para>
+
+      </refsection>
 
     </refentry>
   </section>