From 387b74f15929efbdce79a6fbf12448f90bb83766 Mon Sep 17 00:00:00 2001
From: Gunnar Wrobel
Date: Tue, 11 Sep 2007 05:53:25 +0000
Subject: Import layman.
---
doc/.svn.ignore | 3 +
doc/Makefile | 41 ++++
doc/layman.8.xml | 601 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 645 insertions(+)
create mode 100644 doc/.svn.ignore
create mode 100644 doc/Makefile
create mode 100644 doc/layman.8.xml
(limited to 'doc')
diff --git a/doc/.svn.ignore b/doc/.svn.ignore
new file mode 100644
index 0000000..ff0e9f9
--- /dev/null
+++ b/doc/.svn.ignore
@@ -0,0 +1,3 @@
+*.html
+*.8
+semantic.cache
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..64b28af
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,41 @@
+#
+# layman/doc/Makefile
+# Simple Makefile to rebuild the documentation from the
+# docbook XML sources
+#
+# Copyright (c) 1999-2005 Gentoo Foundation
+# Released under v2 of the GNU GPL
+#
+# Author(s) Stuart Herbert
+# Renat Lumpau
+# Gunnar Wrobel
+#
+# ========================================================================
+
+MAN_PAGES = layman.8
+HTML_PAGES = layman.8.html
+
+TMPFILE=./layman.man
+
+all: man html
+
+html: $(HTML_PAGES)
+
+man: $(MAN_PAGES)
+
+clean:
+ rm -f $(MAN_PAGES)
+ rm -f $(HTML_PAGES)
+
+%.html: %.xml
+ @echo HTML $@
+ @xmlto html-nochunks $<
+
+%: %.xml
+ @echo MAN $@
+ @xmlto man $<
+#
+# fix up the blank lines that docbook leaves behind
+#
+ @cat $@ | sed -e 's/$$/.fred/g;' | tr -d '\n' | sed -e 's/.fred.fred\./.fred./g;' | sed -e 's/.fred/\n/g;' > $(TMPFILE)
+ @mv $(TMPFILE) $@
diff --git a/doc/layman.8.xml b/doc/layman.8.xml
new file mode 100644
index 0000000..c966786
--- /dev/null
+++ b/doc/layman.8.xml
@@ -0,0 +1,601 @@
+
+
+
+
+
+ layman
+
+
+
+ Gunnar
+ Wrobel
+
+
+ wrobel@gentoo.org
+
+
+
+
+
+
+
+
+
+ 2006
+ Gunnar Wrobel
+
+
+
+
+ Reference
+
+
+
+ layman
+ February 2006
+ Gentoo Linux
+
+
+ layman
+ 8
+
+
+ layman
+
+ manage your local repository of gentoo overlays
+
+
+
+
+
+ layman
+
+ -a
+ --add
+
+
+ ALL
+ overlay
+
+
+
+
+ layman
+
+ -d
+ --delete
+
+
+ ALL
+ overlay
+
+
+
+
+ layman
+
+ -s
+ --sync
+
+
+ ALL
+ overlay
+
+
+
+
+ layman
+
+ -S
+ --sync-all
+
+
+
+
+ layman
+
+ -L
+ --list
+
+
+
+
+ layman
+
+ -l
+ --list-local
+
+
+
+
+ layman
+
+ -f
+ --fetch
+
+
+
+
+ layman
+
+ -n
+ --nofetch
+
+
+
+
+ layman
+
+ -k
+ --nocheck
+
+
+
+
+ layman
+
+ -q
+ --quiet
+
+
+
+
+ layman
+
+ -Q
+ --quietness
+
+ 0-4
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+ Handling overlays
+
+ layman intends to provide easy
+ maintenance of gentoo overlays while not requiring any
+ configuration.
+
+
+
+
+ Remote 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 will be a
+ centralized list available here,
+ 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
+ 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
+ pathnames 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
+ /usr/portage/local/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 /usr/portage/local/layman/make.conf
+
+ /usr/portage/local/layman/make.conf
+ is the default provided in the layman
+ configuration. Change this filename 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
+ option or
+ the flag.
+
+
+
+
+
+
+ List overlays
+
+ layman provides the
+ and
+ 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 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.
+
+
+
+
+
+
+ Overlay types
+
+ Currently layman supports overlays that
+ are exported via rsync,
+ subversion, bzr,
+ darcs, git,
+ mercurial or provided
+ as tar packages.
+
+
+
+
+
+
+
+
+ Actions
+
+ List of possible layman actions.
+
+
+
+
+
+
+ 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.
+
+
+
+
+ overlay
+ 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.
+
+
+
+
+ overlay
+ overlay
+
+ Remove the given overlay from your locally installed
+ overlays. Specify "ALL" to remove all overlays
+
+
+
+
+ overlay
+ overlay
+
+ Update the specified overlay. Use "ALL" as
+ parameter to synchronize all overlays
+
+
+
+
+
+
+
+ Update all overlays. Shortcut for -s ALL.
+
+
+
+
+
+
+
+ List the contents of the remote list.
+
+
+
+
+
+
+
+ List the locally installed overlays.
+
+
+
+
+
+
+
+
+ Options
+
+ List of available layman options.
+
+
+
+
+ path
+ path
+
+ Path to an alternative configuration file.
+
+
+
+
+ url
+ url
+
+ Specifies the location of additional overlay
+ lists. You can use this flag several times and the
+ specified urls will get 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://
+
+
+
+
+
+
+
+ Prevents layman from
+ automatically fetching the remote lists of overlays. The
+ default behaviour for layman is to
+ update all remote lists if you run the sync, list or
+ fetch operation.
+
+
+
+
+
+
+
+ Prevents layman 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.
+
+
+
+
+
+
+
+ Makes layman 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.
+
+
+
+
+ LEVEL
+ 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.
+
+
+
+
+ LEVEL
+ 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.
+
+
+
+
+
+
+
+
+
+ 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
+
+
+
+
+
+
+
+
+
+
--
cgit v1.2.3-1-g7c22