Migrate documentation from DocBook to Asciidoc

3 files changed, 428 insertions, 1003 deletions

diff --git a/doc/Makefile b/doc/Makefile
index 64b28af..93d8180 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -27,15 +27,10 @@ clean:
 	rm -f $(MAN_PAGES)
 	rm -f $(HTML_PAGES)
 
-%.html: %.xml
+%.html: %.txt
 	@echo HTML $@
-	@xmlto html-nochunks $<
+	a2x --conf-file=asciidoc.conf  --attribute="laymanversion=1.4.1" --format=xhtml "$<"
 
-%: %.xml
+%: %.txt
 	@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) $@
+	a2x --conf-file=asciidoc.conf  --attribute="laymanversion=1.4.1" --format=manpage "$<"
diff --git a/doc/layman.8.txt b/doc/layman.8.txt
new file mode 100644
index 0000000..15cea11
--- /dev/null
+++ b/doc/layman.8.txt
@@ -0,0 +1,424 @@
+LAYMAN(8)
+=========
+:man source:   layman {laymanversion}
+:man manual:   layman {laymanversion}
+Gunnar Wrobel <wrobel@gentoo.org>
+
+
+NAME
+----
+layman - manage your local repository of Gentoo overlays
+
+
+SYNOPSIS
+--------
+*layman* [-a] | [*--add*] [*ALL*] | [overlay]
+
+*layman* [-d] | [*--delete*] [*ALL*] | [overlay]
+
+*layman* [-s] | [*--sync*] [*ALL*] | [overlay]
+
+*layman* [-i] | [*--info*] [*ALL*] | [overlay]
+
+*layman* [-S] | [*--sync-all*]
+
+*layman* [-L] | [*--list*]
+
+*layman* [-l] | [*--list-local*]
+
+*layman* [-f] | [*--fetch*]
+
+
+DESCRIPTION
+-----------
+*layman* is a script that allows you to add, remove and update
+Gentoo overlays from a variety of sources.
+
+WARNING
+~~~~~~~
+*layman* makes it easy to retrieve and update overlays for Gentoo.
+In addition it makes it TRIVIAL to break your system.
+
+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 *layman*. 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.
+
+To ensure the security of your system you MUST read the source of
+the ebuild you are about to install.
+
+
+OPTIONS
+-------
+
+ACTIONS
+~~~~~~~
+List of possible *layman* actions.
+
+*-f*, *--fetch*::
+    Fetches the remote list of overlays. You will usually NOT need
+to explicitly 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.
+
+*-a* 'overlay', *--add* 'overlay'::
+    Add the given overlay from the cached remote list to your
+    locally installed overlays. Specify "ALL" to add all overlays
+    from the remote list.
+
+*-d* 'overlay', *--delete* 'overlay'::
+    Remove the given overlay from your locally installed overlays.
+    Specify "ALL" to remove all overlays
+
+*-s* 'overlay', *--sync* 'overlay'::
+    Update the specified overlay. Use "ALL" as parameter to
+    synchronize all overlays
+
+*-i* 'overlay', *--info* 'overlay'::
+    Display all available information about the specified overlay.
+
+*-S*, *--sync-all*::
+    Update all overlays. Shortcut for *-s ALL*.
+
+*-L*, *--list*::
+    List the contents of the remote list.
+
+*-l*, *--list-local*::
+    List the locally installed overlays.
+
+
+OTHER OPTIONS
+~~~~~~~~~~~~~
+List of other available *layman* options.
+
+*-c* 'path', *--config* 'path'::
+    Path to an alternative configuration file.
+
+*-o* 'url', *--overlays* 'url'::
+    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.
+
+*-n*, *--nofetch*::
+    Prevents *layman* from automatically fetching the remote lists
+    of overlays. The default behavior for *layman* is to update all
+    remote lists if you run the sync, list or fetch operation.
+
+*-k*, *--nocheck*::
+    Prevents *layman* from checking the remote lists of overlays for
+    complete overlay definitions. The default behavior for *layman* is
+    to reject overlays that do not provide a description or a contact
+    attribute.
+
+*-q*, *--quiet*::
+    Makes *layman* completely quiet. In quiet mode child processes
+    will be run with stdin closed to avoid running into infinite and
+    blindly interactive sessions. Thus a child process may abort once
+    it runs into an situation with need for human interaction.
+    For example this might happen if your overlay resides in Subversion
+    and the SSL certificate of the server needs manual acceptance.
+
+*-v*, *--verbose*::
+    Makes *layman* more verbose and you will receive a description of
+    the overlays you can download.
+
+*-N*, *--nocolor*::
+    Remove color codes from the *layman* output.
+
+*-Q*'LEVEL', *--quietness* 'LEVEL'::
+    Makes *layman* 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.
+
+*-p*'LEVEL', *--priority* 'LEVEL'::
+    Use this option in combination with the *--add*. 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.
+
+
+CONFIGURATION
+-------------
+*layman* reads configuration parameters from the file
+'/etc/layman/layman.cfg' by default. This file provides seven possible
+settings.
+
+storage::
+    Directory that will be used to store the overlays and all
+    additional data *layman* needs. The default is '/var/lib/layman'.
+    *layman* uses a location within the '/usr/portage' hierarchy
+    instead of '/var' in order to store its data. This decision has
+    been made to support network file systems. If you have your
+    portage tree on nfs or a similar file system and several
+    machines access the same ebuild repository over the net it
+    will be necessary to also provide all necessary *layman* data
+    within the hierarchy of the tree. This way the overlays will
+    also have to be synced at one location only.
+
+cache::
+    *layman* will store the downloaded global list of overlays here.
+    The default is '%(storage)s/cache.xml'.
+
+overlays::
+    *layman* will store the list of installed overlays here.
+    The default is '%(storage)s/overlays.xml'.
+
+make.conf::
+    This is the *portage* configuration file that *layman* will
+    modify in order to make the new overlays available within
+    *portage*. The default is '%(storage)s/make.conf'. You could
+    also specify '/etc/make.conf' directly. 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
+    '/etc/make.conf'. This is the reason why *layman* suggests running
+    `echo 'source /var/lib/layman/make.conf' >> /etc/make.conf`
+    after it has been installed.
+
+overlays::
+    Specifies the URL for the remote list of all available overlays.
+    The default is 'http://www.gentoo.org/proj/en/overlays/repositories.xml'.
+    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.
+
+proxy::
+    Specify your proxy in case you have to use one.
+
+nocheck::
+    Set to "yes" if *layman* should stop worrying about overlays
+    with missing a contact address or the description.
+
+
+HANDLING OVERLAYS
+-----------------
+*layman* intends to provide easy maintenance of Gentoo overlays
+while not requiring any configuration.
+
+
+OVERLAY LISTS
+~~~~~~~~~~~~~
+*layman* 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
+'http://www.gentoo.org/proj/en/overlays/repositories.xml'
+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 *--overlays* option when running *layman*.
+
+To get a new overlay added to the central list provided for *layman*,
+send a mail to <overlays@gentoo.org>. Gentoo developers may add their
+overlay entries directly into the list which can be accessed over the
+CVS repository for the Gentoo website.
+
+You can also use several lists at the same time. Just add one URL per
+line to the overlays variable in your configuration file. *layman*
+will merge the contents of all lists.
+
+*layman* also allows you to define local files in this list.
+Just make sure you prepend these path names in standard URL notation with 'file://'.
+
+If you need to use a proxy for access to the Internet, you can use
+the corresponding variable in the *layman* configuration file.
+*layman* will also respect the *http_proxy* environment variable in case you set it.
+
+
+LOCAL CACHE
+~~~~~~~~~~~
+*layman* stores a local copy of the fetched remote list.
+It will be stored in '/var/lib/layman/cache.xml' by default.
+There exists only one such cache file and it will be overwritten
+every time you run *layman*.
+
+
+HANDLING /ETC/MAKE.CONF
+~~~~~~~~~~~~~~~~~~~~~~~
+Since *layman* is designed to automatically handle the inclusion of
+overlays into your system it needs to be able to modify the
+*PORTDIR_OVERLAY* variable in your '/etc/make.conf' file.
+But '/etc/make.conf' is a very central and essential configuration
+file for a Gentoo system. Automatically modifying this file would
+be somewhat dangerous. You can allow *layman* to do this by
+setting the make_conf variable in the configuration file to
+'/etc/make.conf'.
+
+A much safer and in fact recommended solution to the problem is
+to let *layman* handle an external file that only contains the
+*PORTDIR_OVERLAY* variable and is sourced within the standard
+'/etc/make.conf' file. Just add the following line to the end of
+your '/etc/make.conf' file:
+
+-------------------------------------------
+source /var/lib/layman/make.conf
+-------------------------------------------
+
+'/var/lib/layman/make.conf' is the default provided in the *layman*
+configuration. Change this file name in case you decide to store
+it somewhere else.
+
+The file does not necessarily need to exist at the beginning.
+If it is missing, *layman* will create it for you.
+
+There is also no need to remove the original *PORTDIR_OVERLAY*
+variable from the make.conf file. Layman will simply add new overlays
+to this variable and all your old entries will remain in there.
+
+
+ADDING, REMOVING AND UPDATING OVERLAYS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Once a remote list of overlays has been fetched, *layman* 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 *layman* will modify the
+*PORTDIR_OVERLAY* variable to include the new overlay path.
+
+Removing the overlay with *layman* will delete the overlay without
+leaving any traces behind.
+
+In order to update all overlays managed by *layman* you can run
+the script with the *--sync ALL* option or the *--sync-all* flag.
+
+
+LIST OVERLAYS
+~~~~~~~~~~~~~
+*layman* provides the *--list* and *--list-local* options to print
+a list of available respectively installed overlays.
+
+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.
+
+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 behavior
+has been added with *layman* 1.0.7 and if you'd like to return to
+the old behavior you may use the k option flag or set the nocheck
+option in the configuration file.
+
+
+SEARCHING EBUILDS IN OVERLAYS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You can search through the ebuilds available in the overlays on
+'http://overlays.gentoo.org/' by using *eix*. Emerge the package and
+run `update-eix-remote update`.
+
+
+OVERLAY TYPES
+~~~~~~~~~~~~~
+Currently *layman* supports overlays that are exported via *rsync*,
+*subversion*, *bzr*, *darcs*, *git*, *mercurial* or provided as tar
+packages.
+
+
+OVERLAY LISTS
+-------------
+
+OVERLAY LIST FORMAT
+~~~~~~~~~~~~~~~~~~~
+Layman uses a central list of overlays in XML format. The file looks
+like this:
+
+Example 1. An example overlays.xml file
+
+-------------------------------------------
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE repositories SYSTEM "/dtd/repositories.dtd">
+<repositories xmlns="" version="1.0">
+<repo quality="experimental" status="official">
+	<name>gnome</name>
+	<description>experimental gnome ebuilds</description>
+	<homepage>http://git.overlays.gentoo.org/gitweb/?p=proj/gnome.git;a=summary</homepage>
+	<owner type="project">
+		<email>gnome@gentoo.org</email>
+		<name>GNOME herd</name>
+	</owner>
+	<source type="git">git://git.overlays.gentoo.org/proj/gnome.git</source>
+	<source type="git">http://git.overlays.gentoo.org/gitroot/proj/gnome.git</source>
+	<source type="git">git+ssh://git@git.overlays.gentoo.org/proj/gnome.git</source>
+	<feed>http://git.overlays.gentoo.org/gitweb/?p=proj/gnome.git;a=atom</feed>
+	<feed>http://git.overlays.gentoo.org/gitweb/?p=proj/gnome.git;a=rss</feed>
+</repo>
+</repositories>
+-------------------------------------------
+
+
+ADDING AN OVERLAY LOCALLY
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Simply create an overlay list in the format described above and run
+*layman* with the -o switch. You need to prepend local file URLs
+with 'file://'.
+
+
+ADDING AN OVERLAY GLOBALLY
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+The global list of overlays used by *layman* lies at
+'http://www.gentoo.org/proj/en/overlays/repositories.xml'.
+
+All Gentoo developers have access to this location via CVS and
+can modify the list of overlays.
+
+If you are not a Gentoo developer but wish to get your overlay
+listed you should contact the Gentoo Overlays team at
+<overlays@gentoo.org>. You can also join *#gentoo-overlays* on
+irc.freenode.net.
+
+
+EXAMPLES
+--------
+
+INSTALLING AN OVERLAY
+~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------
+layman -f -a wrobel
+-------------------------------------------
+
+This would add the overlay with the id wrobel to your list of
+installed overlays.
+
+
+SYNCING YOUR OVERLAYS
+~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------
+layman -s ALL
+-------------------------------------------
+
+This updates all overlays
+
+
+PERFORMING SEVERAL ACTIONS AT THE SAME TIME
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------
+layman -f -a wrobel -a webapps-experimental
+-------------------------------------------
+
+This fetches the remote list and immediately adds two overlays
+
+
+FILES
+-----
+'/etc/layman/layman.cfg'::
+    Configuration file, holding the defaults for *layman*
+
+
+AUTHORS
+-------
+- Gunnar Wrobel <wrobel@gentoo.org>
+- Sebastian Pipping <sping@gentoo.org>
+
+
+REPORTING BUGS
+--------------
+Please report bugs you might find at 'http://bugs.gentoo.org/'
diff --git a/doc/layman.8.xml b/doc/layman.8.xml
deleted file mode 100644
index dda55e9..0000000
--- a/doc/layman.8.xml
+++ /dev/null
@@ -1,994 +0,0 @@
-<?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>layman</title>
-    
-    <authorgroup>
-      <author>
-	<firstname>Gunnar</firstname>
-	<surname>Wrobel</surname>
-	<affiliation>
-	  <address>
-	    <email>wrobel@gentoo.org</email>
-	    <otheraddr>
-	      <ulink url="http://gunnarwrobel.de" />
-	    </otheraddr>
-	  </address>
-	</affiliation>
-      </author>
-    </authorgroup>
-
-    <copyright>
-      <year>2005-2009</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-search">Searching ebuilds in 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>
-    <title>External links</title>
-    <itemizedlist>
-      <listitem>
-	<para>
-	  <ulink url="http://sourceforge.net/projects/layman/">Layman project page on SourceForge</ulink>
-	</para>
-      </listitem>
-      <listitem>
-	<para>
-	  <ulink url="http://overlays.gentoo.org">Gentoo Overlays project</ulink>
-	</para>
-      </listitem>
-      <listitem>
-	<para>
-	  <ulink url="http://ohloh.net/projects/layman/">Layman project page on Ohloh</ulink>
-	</para>
-      </listitem>
-      <listitem>
-	<para>
-	  <ulink url="http://freshmeat.net/projects/layman/">Layman project page on Freshmeat</ulink>
-	</para>
-      </listitem>
-      <listitem>
-	<para>
-	  <ulink url="http://bugs.gentoo.org/">Bug tracker</ulink>
-	</para>
-      </listitem>
-      <listitem>
-	<para>
-	  <ulink url="http://gentoo-wiki.com/Portage_Overlay_Listing#Layman">Wiki</ulink>
-	</para>
-      </listitem>
-      <listitem>
-	<para>
-	  <ulink url="http://log.onthebrink.de/feeds/posts/default/-/layman">Blog</ulink>
-	</para>
-      </listitem>
-      <listitem>
-	<para>
-	  <ulink url="http://www.google.com/reader/public/atom/user/02645926629531261525/label/%5Bproject%5D%20layman">Combined RSS feed</ulink>
-	</para>
-      </listitem>
-    </itemizedlist>
-  </section>
-
-  <section id="layman-reference">
-    <title>Reference</title>
-
-    <refentry id="layman-manpage">
-      <refentryinfo>
-	<title>layman</title>
-	<date>July 2010</date>
-	<productname>layman</productname>
-	<productnumber>1.4.1</productnumber>
-	<copyright>
-	  <year>2005-2009</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>
-	<manvolnum>8</manvolnum>
-      </refmeta>
-      <refnamediv>
-	<refname>layman</refname>
-	<refpurpose>
-	  manage your local repository of Gentoo overlays
-	</refpurpose>
-      </refnamediv>
-
-      <refsynopsisdiv id="layman-synopsis">
-	<cmdsynopsis>
-	  <command>layman</command>
-	  <group choice="plain">
-	    <arg>-a</arg>
-	    <arg>--add</arg>
-	  </group>
-	  <group choice="plain">
-	    <arg>ALL</arg>
-	    <arg><replaceable>overlay</replaceable></arg>
-	  </group>
-	</cmdsynopsis>
-
-	<cmdsynopsis>
-	  <command>layman</command>
-	  <group choice="plain">
-	    <arg>-d</arg>
-	    <arg>--delete</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>
-	    <arg>--sync</arg>
-	  </group>
-	  <group choice="plain">
-	    <arg>ALL</arg>
-	    <arg><replaceable>overlay</replaceable></arg>
-	  </group>
-	</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>
-	    <arg>--sync-all</arg>
-	  </group>
-	</cmdsynopsis>
-
-	<cmdsynopsis>
-	  <command>layman</command>
-	  <group choice="plain">
-	    <arg>-L</arg>
-	    <arg>--list</arg>
-	  </group>
-	</cmdsynopsis>
-
-	<cmdsynopsis>
-	  <command>layman</command>
-	  <group choice="plain">
-	    <arg>-l</arg>
-	    <arg>--list-local</arg>
-	  </group>
-	</cmdsynopsis>
-
-	<cmdsynopsis>
-	  <command>layman</command>
-	  <group choice="plain">
-	    <arg>-f</arg>
-	    <arg>--fetch</arg>
-	  </group>
-	</cmdsynopsis>
-
-      </refsynopsisdiv>
-
-      <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
-	sources.</para>
-
-	<refsection>
-	  <title>WARNING</title>
-
-	  <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>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>To ensure the security of your system you MUST read the
-	  source of the ebuild you are about to install. 
-	  </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 explicitly 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 behavior 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 behavior 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.
-		In quiet mode child processes will be run with stdin closed
-		to avoid running into infinite and blindly interactive sessions.
-		Thus a child process may abort once it runs into an
-		situation with need for human interaction.
-		For example this might happen if your overlay
-		resides in Subversion and the SSL certificate of
-		the server needs manual 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>/var/lib/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 file systems. If you have your portage tree on nfs
-	      or a similar file system 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>/var/lib/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/repositories.xml</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>
-
-	</variablelist>
-
-      </refsection>
-
-      <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.
-	</para>
-
-	<refsection id="layman-remote">
-
-	  <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 is a
-	  centralized list available at <ulink
-	  url="http://www.gentoo.org/proj/en/overlays/repositories.xml"/>
-	  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.
-	  </para>
-
-	  <para>You can also use several lists at the same time. Just
-	  add one URL per line to the overlays variable in your
-	  configuration file. <command>layman</command> will merge the
-	  contents of all lists. 
-	  </para>
-
-	  <para><command>layman</command> also allows you to define
-	  local files in this list. Just make sure you prepend these
-	  path names in standard URL notation
-	  with <filename>file://</filename>.
-	  </para>
-
-	  <para>If you need to use a proxy for access to the Internet,
-	  you can use the corresponding variable in
-	  the <command>layman</command> configuration file. Layman
-	  will also respect the <command>http_proxy</command>
-	  environment variable in case you set it.
-	  </para>
-
-	</refsection>
-
-	<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>/var/lib/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>
-
-	</refsection>
-
-	<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>.
-	  </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:
-	  </para>
-
-	  <para>source /var/lib/layman/make.conf</para>
-
-	  <para><filename>/var/lib/layman/make.conf</filename>
-	  is the default provided in the layman
-	  configuration. Change this file name 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.
-	  </para>
-
-	  <para>There is also no need to remove the
-	  original <command>PORTDIR_OVERLAY</command> variable from
-	  the make.conf file. Layman will simply add new overlays to
-	  this variable and all your old entries will remain in there.
-	  </para>
-
-	</refsection>
-
-	<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.
-	  </para>
-
-	  <para>Removing the overlay with <command>layman</command>  will
-	  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.
-	  </para>
-
-	</refsection>
-
-	<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.
-	  </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.
-	  </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 behavior has been added with
-	  layman-1.0.7 and if you'd like to return to the old
-	  behavior you may use the k option flag or set the nocheck
-	  option in the configuration file.
-	  </para>
-
-	</refsection>
-
-	<refsection id="layman-search">
-
-	  <title>Searching ebuilds in overlays</title>
-
-	  <para>
-	    You can search through the ebuilds available in the
-	    overlays on <ulink url="http://overlays.gentoo.org"/> by
-	    using "eix". Emerge the package and run
-	    <command>update-eix-remote update</command>.
-	  </para>
-
-	</refsection>
-
-	<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.
-	  </para>
-
-	</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 overlays.xml file</title>
-	      <programlisting>
-	      &lt;?xml version="1.0" encoding="UTF-8"?&gt;
-	      &lt;!DOCTYPE repositories SYSTEM "/dtd/repositories.dtd"&gt;
-	      &lt;repositories xmlns="" version="1.0"&gt;
-	        &lt;repo quality="experimental" status="official"&gt;
-	          &lt;name&gt;gnome&lt;/name&gt;
-	          &lt;description&gt;experimental gnome ebuilds&lt;/description&gt;
-	          &lt;homepage&gt;http://git.overlays.gentoo.org/gitweb/?p=proj/gnome.git;a=summary&lt;/homepage&gt;
-	          &lt;owner type="project"&gt;
-	            &lt;email&gt;gnome@gentoo.org&lt;/email&gt;
-	            &lt;name&gt;GNOME herd&lt;/name&gt;
-	          &lt;/owner&gt;
-	          &lt;source type="git"&gt;git://git.overlays.gentoo.org/proj/gnome.git&lt;/source&gt;
-	          &lt;source type="git"&gt;http://git.overlays.gentoo.org/gitroot/proj/gnome.git&lt;/source&gt;
-	          &lt;source type="git"&gt;git+ssh://git@git.overlays.gentoo.org/proj/gnome.git&lt;/source&gt;
-	          &lt;feed&gt;http://git.overlays.gentoo.org/gitweb/?p=proj/gnome.git;a=atom&lt;/feed&gt;
-	          &lt;feed&gt;http://git.overlays.gentoo.org/gitweb/?p=proj/gnome.git;a=rss&lt;/feed&gt;
-	        &lt;/repo&gt;
-	      &lt;/repositories&gt;
-	      </programlisting>
-	    </example>
-	  </para>
-
-	</refsection>
-
-	<refsection>
-
-	  <title>Adding an overlay locally</title>
-
-	  <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>
-
-	</refsection>
-
-	<refsection>
-
-	  <title>Adding an overlay globally</title>
-
-	  <para>
-	    The global list of overlays used by
-	    <command>layman</command> lies at
-	    <filename>http://www.gentoo.org/proj/en/overlays/repositories.xml</filename>.
-	  </para>
-
-	  <para>
-	    All Gentoo developers have access to this location via CVS
-	    and can modify the list of overlays.
-	  </para>
-
-	  <para>
-	    If you are not a Gentoo developer but wish 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>
-
-	</refsection>
-
-      </refsection>
-
-      <refsection id="layman-examples">
-
-	<title>Examples</title>
-
-	<refsection>
-
-	  <title>Installing an overlay</title>
-
-	  <para><userinput>layman -f -a wrobel</userinput></para>
-	  <para>This would add the overlay with the id
-	  <command>wrobel</command> to your list of installed
-	  overlays.</para>
-
-	</refsection>
-
-	<refsection>
-
-	  <title>Syncing your overlays</title>
-
-	  <para><userinput>layman -s ALL</userinput></para>
-	  <para>This updates all overlays</para>
-
-	</refsection>
-
-	<refsection>
-
-	  <title>Performing several actions at the same time</title>
-
-	  <para><userinput>layman -f -a wrobel -a webapps-experimental</userinput></para>
-	  <para>This fetches the remote list and immediately adds two
-	  overlays</para>
-
-	</refsection>
-
-      </refsection>
-
-      <refsection id="layman-files">
-
-	<title>Files</title>
-
-	<variablelist>
-
-	  <varlistentry>
-	    <term><filename>/etc/layman/layman.cfg</filename></term>
-	    <listitem>
-	      <para>Configuration file, holding the defaults for
-	      <command>layman</command></para>
-	    </listitem>
-	  </varlistentry>
-
-	</variablelist>
-
-      </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>
-</article>