aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorGunnar Wrobel <p@rdus.de>2007-09-11 14:07:14 +0000
committerGunnar Wrobel <p@rdus.de>2007-09-11 14:07:14 +0000
commit6be664ac1eff99ce74112583e6a0be2cd98a21b2 (patch)
tree79ed7a8a05b291db0a6154d5f4ca0387d6166590 /doc
parentMoved layman to trunk again. (diff)
downloadoverlord-6be664ac1eff99ce74112583e6a0be2cd98a21b2.tar.gz
overlord-6be664ac1eff99ce74112583e6a0be2cd98a21b2.tar.bz2
overlord-6be664ac1eff99ce74112583e6a0be2cd98a21b2.zip
A number of documentation fixes and preparation of the project website.
Diffstat (limited to 'doc')
-rw-r--r--doc/layman.8.xml1024
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>