From 5f252c72350e1671ad01630e90d5acb2226629e3 Mon Sep 17 00:00:00 2001
From: Zac Medico <zmedico@gentoo.org>
Date: Fri, 22 Jun 2012 17:29:39 -0700
Subject: Document /etc/portage/sets and world_sets more.

---
 man/emerge.1  | 18 ++++++++++++++----
 man/portage.5 | 19 +++++++++++++++++--
 2 files changed, 31 insertions(+), 6 deletions(-)

diff --git a/man/emerge.1 b/man/emerge.1
index 0d9f6def1..5d0c05d9b 100644
--- a/man/emerge.1
+++ b/man/emerge.1
@@ -1,4 +1,4 @@
-.TH "EMERGE" "1" "Dec 2011" "Portage VERSION" "Portage"
+.TH "EMERGE" "1" "Jun 2012" "Portage VERSION" "Portage"
 .SH "NAME"
 emerge \- Command\-line interface to the Portage system
 .SH "SYNOPSIS"
@@ -69,7 +69,9 @@ packages deemed necessary for your system to run properly. \fBworld\fR
 encompasses both the \fBselected\fR and \fBsystem\fR sets. [See
 \fBFILES\fR below for more information.] Other sets can exist depending
 on the current configuration. The default set configuration is located
-in the \fB/usr/share/portage/config/sets\fR directory. Note that a \fIset\fR
+in the \fB/usr/share/portage/config/sets\fR directory.
+User sets may be created by placing files in the \fB/etc/portage/sets/\fR
+directory (see \fBportage\fR(5)). Note that a \fIset\fR
 is generally used in conjunction with \fB\-\-update\fR. When used as 
 arguments to \fBemerge\fR sets have to be prefixed with \fB@\fR to be
 recognized. Use the \fB\-\-list\-sets\fR action to display a list of
@@ -543,7 +545,7 @@ the build may fail if the dependencies aren't satisfied.
 .TP
 .BR "\-\-noreplace " (\fB\-n\fR)
 Skips the packages specified on the command\-line that have already
-been installed.  Without this option, any packages, ebuilds, or deps
+been installed.  Without this option, any package atoms or package sets
 you specify on the command\-line \fBwill\fR cause Portage to remerge
 the package, even if it is already installed.  Note that Portage will
 not remerge dependencies by default.
@@ -915,7 +917,7 @@ those USE settings (on Bourne-compatible shells you may omit the \fBenv\fR
 part).  If you want those USE settings to be more 
 permanent, you can put them in /etc/portage/package.use instead.
 .LP
-If \fBemerge \-\-update system\fR or \fBemerge \-\-update world\fR
+If \fBemerge \-\-update @system\fR or \fBemerge \-\-update @world\fR
 fails with an error message, it may be that an ebuild uses some
 newer feature not present in this version of \fBemerge\fR.  You
 can use \fBemerge \-\-update portage\fR to upgrade to the lastest
@@ -1054,6 +1056,11 @@ Contains a list of all user\-specified packages.  You can safely edit
 this file, adding packages that you want to be considered in \fBworld\fR
 set updates and removing those that you do not want to be considered.
 .TP
+.B /var/lib/portage/world_sets
+This is like the world file but instead of package atoms it contains
+packages sets which always begin with the \fB@\fR character. Use
+\fB/etc/portage/sets/\fR to define user package sets.
+.TP
 .B /etc/make.conf
 Contains variables for the build process, overriding those in
 \fBmake.globals\fR.
@@ -1061,6 +1068,9 @@ Contains variables for the build process, overriding those in
 .B /etc/portage/color.map
 Contains variables customizing colors.
 .TP
+.B /etc/portage/sets/
+Contains user package set definitions (see \fBportage\fR(5)).
+.TP
 .B /etc/dispatch\-conf.conf
 Contains settings to handle automatic updates/backups of configuration 
 files.
diff --git a/man/portage.5 b/man/portage.5
index 099d6011d..7341a0352 100644
--- a/man/portage.5
+++ b/man/portage.5
@@ -1,4 +1,4 @@
-.TH "PORTAGE" "5" "Oct 2011" "Portage VERSION" "Portage"
+.TH "PORTAGE" "5" "Jun 2012" "Portage VERSION" "Portage"
 .SH NAME
 portage \- the heart of Gentoo
 .SH "DESCRIPTION"
@@ -69,6 +69,9 @@ package-specific bashrc files
 .BR /etc/portage/profile/
 site-specific overrides of \fB/etc/make.profile/\fR
 .TP
+.BR /etc/portage/sets/
+user\-defined package sets
+.TP
 .BR /usr/portage/metadata/
 .nf
 layout.conf
@@ -761,6 +764,17 @@ in the following order:
 /etc/portage/env/${CATEGORY}/${PF}
 .RE
 .TP
+.BR /etc/portage/sets/
+.RS
+For each file in this directory, a package set is created with its name
+corresponding to the name of the file. Each file should contain a list
+of package atoms, one per line. When referencing package sets in
+\fBemerge\fR(1) arguments, the set name is prefixed with \fB@\fR.
+
+Also see \fB/var/lib/portage/world_sets\fR and the \fBemerge\fR(1)
+\fB\-\-list\-sets\fR option.
+.RE
+.TP
 .BR /usr/portage/metadata/
 .RS
 .TP
@@ -1077,7 +1091,8 @@ app\-cdr/cdemu
 .TP
 .BR world_sets
 This is like the world file but instead of package atoms it contains
-packages sets which always begin with the @ character.
+packages sets which always begin with the \fB@\fR character. Use
+\fB/etc/portage/sets/\fR to define user package sets.
 
 .I Example:
 .nf
-- 
cgit v1.2.3-1-g7c22