diff options
author | 2007-09-11 14:07:14 +0000 | |
---|---|---|
committer | 2007-09-11 14:07:14 +0000 | |
commit | 6be664ac1eff99ce74112583e6a0be2cd98a21b2 (patch) | |
tree | 79ed7a8a05b291db0a6154d5f4ca0387d6166590 /doc | |
parent | Moved layman to trunk again. (diff) | |
download | overlord-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.xml | 1024 |
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> + <?xml version="1.0" ?> + <layman> + <overlays> + <overlay + type = "svn" + src = "https://mydomain.net/svn/myoverlay/" + contact = "me@mydomain.net" + name = "myoverlay"> + + <link> + http://mydomain.net/myoverlay + </link> + + <description> + Contains some of my ebuilds. + </description> + </overlay> + </overlays> + </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> |