For bug #156536, update --resume docs to show that the resume history is capable of storing two merge lists. (branches/2.1.2 r6762)

svn path=/main/branches/2.1.2.9/; revision=7450

2 files changed, 81 insertions, 103 deletions

diff --git a/man/emerge.1 b/man/emerge.1
index 203fa1eb6..1a4aea020 100644
--- a/man/emerge.1
+++ b/man/emerge.1
@@ -1,4 +1,4 @@
-.TH "EMERGE" "1" "Jun 2007" "Portage 2.1.3" "Portage"
+.TH "EMERGE" "1" "Dec 2006" "Portage 2.1" "Portage"
 .SH "NAME"
 emerge \- Command\-line interface to the Portage system
 .SH "SYNOPSIS"
@@ -90,23 +90,18 @@ has completed.  This usually entails configuration file setup or other similar
 setups that the user may wish to run.
 .TP
 .BR \-\-depclean
-Cleans the system by removing packages that are not associated
-with explicitly merged packages. Depclean works by creating the
-full dependency tree from the system list and the world file,
-then comparing it to installed packages. Packages installed, but
-not associated with an explicit merge are listed as candidates
-for unmerging. Inexperienced users are advised to use \fB\-\-pretend\fR
-with this option in order to see a preview of which packages
-will be uninstalled. \fBWARNING: Removing some
+Determines all packages installed on the system that have no 
+explicit reason for being there.  \fBemerge\fR generates a list 
+of packages which it expects to be installed by checking the 
+\fBsystem\fR package list and the \fBworld\fR file.  It then 
+compares that list to the list of packages which are actually 
+installed; the differences are listed as unnecessary packages 
+and then unmerged after a short timeout.  \fBWARNING: Removing some 
 packages may cause packages which link to the removed package 
-to stop working and complain about missing libraries.\fR
-Rebuild the complaining package to fix this issue.  Also see
+to stop working and complain about missing libraries.\fR 
+Re\-emerge the complaining package to fix this issue.  Also see
 \fB\-\-with\-bdeps\fR for behavior with respect to build time dependencies that
-are not strictly required. Depclean serves as a dependency aware
-version of \fB\-\-unmerge\fR. When given one or more atoms, it will
-unmerge matched packages that have no reverse dependencies. Use
-\fB\-\-depclean\fR together with \fB\-\-verbose\fR to show reverse
-dependencies.
+are not strictly required.
 .TP
 .BR "\-\-help " (\fB\-h\fR)
 Displays help information for emerge.  Adding one of the additional
@@ -130,12 +125,12 @@ package data.  It does not populate cache for the overlays listed in
 PORTDIR_OVERLAY.  In order to generate cache for overlays, use \fB\-\-regen\fR.
 .TP
 .BR "\-\-prune " (\fB\-P\fR)
-\fBWARNING: This action can remove important packages!\fR  Removes all but the
-highest installed version of a package from your system. This action doesn't
-verify the possible binary compatibility between versions and can thus remove
-essential dependencies from your system. Use \fB\-\-prune\fR together with
-\fB\-\-verbose\fR to show reverse dependencies or with \fB\-\-nodeps\fR to
-ignore all dependencies.
+\fBWARNING: This action can remove important packages!\fR  Prune looks at each
+installed package and attempts to \fBremove\fR all but the \fBmost recently 
+installed version.  \fRPrune ignores \fBslots\fR, if you require a slot\-aware
+Prune use \fB emerge \-\-clean\fR.  Prune may inadvertently remove important 
+packages from your system.  Use \fB\-\-clean\fR instead unless you really 
+know what you're doing.
 .TP
 .BR \-\-regen
 Causes portage to check and update the dependency cache of all ebuilds in the 
@@ -185,9 +180,8 @@ description of PORTDIR_OVERLAY for a method to avoid deletions.
 \fBWARNING: This action can remove important packages!\fR Removes
 all matching packages.  This does no checking of dependencies, so
 it may remove packages necessary for the proper operation of your
-system.  Its arguments can be \fIatoms\fR or
-\fIebuilds\fR. For a dependency aware version of \fB\-\-unmerge\fR,
-use \fB\-\-depclean\fR or \fB\-\-prune\fR.
+system.  Its arguments can be \fIebuilds\fR, \fIsets\fR, or
+\fIatoms\fR.
 .TP
 .BR "\-\-update " (\fB\-u\fR)
 Updates packages to the best version available, which may not always be the 
@@ -361,12 +355,6 @@ the printout:
 Results may vary, but the general outcome is a reduced or condensed
 output from portage's displays.
 .TP
-.BR "\-\-reinstall changed\-use"
-Tells emerge to include installed packages where USE flags have
-changed since installation.  Unlike \fB\-\-newuse\fR, this option does
-not trigger reinstallation when flags that the user has not
-enabled are added or removed.
-.TP
 .BR "\-\-skipfirst"
 This option is only valid when used with \fB\-\-resume\fR.  It removes the 
 first package in the resume list so that a merge may continue in the presence 
@@ -553,43 +541,6 @@ variable to allow or disallow the emerging of a package masked by
 versions of packages, you should update your 
 \fI/etc/portage/package.keywords\fR file to list the packages you want the 
 \'testing\' version.  See \fBportage\fR(5) for more information.
-.SH "CONFIGURATION FILES"
-Portage has a special feature called "config file protection". The purpose of
-this feature is to prevent new package installs from clobbering existing
-configuration files. By default, config file protection is turned on for /etc
-and the KDE configuration dirs; more may be added in the future.
-.LP
-When Portage installs a file into a protected directory tree like /etc, any
-existing files will not be overwritten. If a file of the same name already
-exists, Portage will change the name of the to\-be\-installed file from 'foo' to
-\'._cfg0000_foo\'. If \'._cfg0000_foo\' already exists, this name becomes
-\'._cfg0001_foo\', etc. In this way, existing files are not overwritten,
-allowing the administrator to manually merge the new config files and avoid any
-unexpected changes.
-.LP
-In addition to protecting overwritten files, Portage will not delete any files
-from a protected directory when a package is unmerged. While this may be a
-little bit untidy, it does prevent potentially valuable config files from being
-deleted, which is of paramount importance.
-.LP
-Protected directories are set using the \fICONFIG_PROTECT\fR variable, normally
-defined in /etc/make.globals. Directory exceptions to the CONFIG_PROTECTed
-directories can be specified using the \fICONFIG_PROTECT_MASK\fR variable. To find
-files that need to be updated in /etc, type \fBfind /etc \-iname \'._cfg????_*\'\fR.
-.LP
-You can disable this feature by setting \fICONFIG_PROTECT="\-*"\fR in /etc/make.conf.
-Then, Portage will mercilessly auto\-update your config files. Alternatively,
-you can leave Config File Protection on but tell Portage that it can overwrite
-files in certain specific /etc subdirectories. For example, if you wanted
-Portage to automatically update your rc scripts and your wget configuration,
-but didn't want any other changes made without your explicit approval, you'd
-add this to /etc/make.conf:
-.LP
-.I CONFIG_PROTECT_MASK="/etc/wget /etc/rc.d"
-.LP
-Tools such as dispatch\-conf, cfg\-update, and etc\-update are also available to
-aid in the merging of these files. They provide interactive merging and can
-auto\-merge trivial changes.
 .SH "REPORTING BUGS"
 Please report any bugs you encounter through our website:
 .LP
@@ -621,9 +572,6 @@ Contains variables for the build process, overriding those in
 \fBmake.globals\fR.  \fBYou should edit this file instead of the ones
 listed below\fR.
 .TP
-.B /etc/portage/color.map
-Contains variables customizing colors.
-.TP
 .B /etc/dispatch\-conf.conf
 Contains settings to handle automatic updates/backups of configuration 
 files.
@@ -656,7 +604,6 @@ this file\fR.
 .BR ebuild (1),
 .BR ebuild (5),
 .BR make.conf (5),
-.BR color.map (5),
 .BR portage (5)
 .LP
 A number of helper applications reside in \fI/usr/lib/portage/bin\fR.
diff --git a/pym/emergehelp.py b/pym/emergehelp.py
index a9acac607..cc2dc0bbb 100644
--- a/pym/emergehelp.py
+++ b/pym/emergehelp.py
@@ -1,4 +1,4 @@
-# Copyright 1999-2007 Gentoo Foundation
+# Copyright 1999-2006 Gentoo Foundation
 # Distributed under the terms of the GNU General Public License v2
 # $Id$
 
@@ -7,7 +7,8 @@ import os,sys
 from output import bold, turquoise, green
 
 def shorthelp():
-	print bold("emerge:")+" the other white meat (command-line interface to the Portage system)"
+	print
+	print
 	print bold("Usage:")
 	print "   "+turquoise("emerge")+" [ "+green("options")+" ] [ "+green("action")+" ] [ "+turquoise("ebuildfile")+" | "+turquoise("tbz2file")+" | "+turquoise("dependency")+" ] [ ... ]"
 	print "   "+turquoise("emerge")+" [ "+green("options")+" ] [ "+green("action")+" ] < "+turquoise("system")+" | "+turquoise("world")+" >"
@@ -16,15 +17,17 @@ def shorthelp():
 	print "   "+turquoise("emerge")+" "+turquoise("--help")+" [ "+green("system")+" | "+green("world")+" | "+green("config")+" | "+green("--sync")+" ] "
 	print bold("Options:")+" "+green("-")+"["+green("abBcCdDefgGhikKlnNoOpqPsStuvV")+"] ["+green("--oneshot")+"] ["+green("--newuse")+"] ["+green("--noconfmem")+"]"
 	print      "                                          [ " + green("--color")+" < " + turquoise("y") + " | "+ turquoise("n")+" >  ] [ "+green("--columns")+" ]"
-	print      "                                     [ "+green("--reinstall ")+turquoise("changed-use")+" ] ["+green("--nospinner")+"]"
+	print      "                                                                 ["+green("--nospinner")+"]"
 	print "                                          [ "+green("--deep")+"  ] [" + green("--with-bdeps")+" < " + turquoise("y") + " | "+ turquoise("n")+" > ]"
 	print bold("Actions:")+" [ "+green("--clean")+" | "+green("--depclean")+" | "+green("--prune")+" | "+green("--regen")+" | "+green("--search")+" | "+green("--unmerge")+" ]"
+	print
 
 def help(myaction,myopts,havecolor=1):
-	if not myaction and ("--verbose" not in myopts):
+	if not myaction and ("--help" not in myopts):
 		shorthelp()
 		print
-		print "   For more help try 'emerge --help --verbose' or consult the man page."
+		print "   For more help try 'emerge --help' or consult the man page."
+		print
 	elif not myaction:
 		shorthelp()
 		print
@@ -64,17 +67,10 @@ def help(myaction,myopts,havecolor=1):
 		print "              full dependency tree from the system list and the world file,"
 		print "              then comparing it to installed packages. Packages installed, but"
 		print "              not associated with an explicit merge are listed as candidates"
-		print "              for unmerging. Inexperienced users are advised to use --pretend"
-		print "              with this option in order to see a preview of which packages will"
-		print "              be uninstalled. "+turquoise(" WARNING: Removing some packages may cause")
-		print "              "+turquoise("packages which link to the removed package to stop working and")
-		print "              "+turquoise("complain about missing libraries. Rebuild the complaining package")
-		print "              "+turquoise("to fix this issue.")+" Also see --with-bdeps for behavior with"
-		print "              respect to build time dependencies that are not strictly"
-		print "              required. Depclean serves as a dependency aware version of"
-		print "              --unmerge. When given one or more atoms, it will unmerge matched"
-		print "              packages that have no reverse dependencies. Use --depclean"
-		print "              together with --verbose to show reverse dependencies."
+		print "              for unmerging."+turquoise(" WARNING: This can seriously affect your system by")
+		print "              "+turquoise("removing packages that may have been linked against, but due to")
+		print "              "+turquoise("changes in USE flags may no longer be part of the dep tree. Use")
+		print "              "+turquoise("caution when employing this feature.")
 		print
 		print "       "+green("--info")
 		print "              Displays important portage variables that will be exported to"
@@ -94,12 +90,11 @@ def help(myaction,myopts,havecolor=1):
 		print
 		print "       "+green("--prune")+" ("+green("-P")+" short option)"
 		print "              "+turquoise("WARNING: This action can remove important packages!")
-		print "              Removes all but the highest installed version of a package"
+		print "              Removes all but the most recently installed version of a package"
 		print "              from your system. This action doesn't verify the possible binary"
 		print "              compatibility between versions and can thus remove essential"
-		print "              dependencies from your system. Use --prune together with"
-		print "              --verbose to show reverse dependencies or with --nodeps to"
-		print "              ignore all dependencies."
+		print "              dependencies from your system."
+		print "              The argument format is the same as for the "+bold("--clean")+" action."
 		print
 		print "       "+green("--regen")
 		print "              Causes portage to check and update the dependency cache of all"
@@ -145,11 +140,9 @@ def help(myaction,myopts,havecolor=1):
 		print
 		print "       "+green("--unmerge")+" ("+green("-C")+" short option)"
 		print "              "+turquoise("WARNING: This action can remove important packages!")
-		print "              Removes all matching packages. This does no checking of"
-		print "              dependencies, so it may remove packages necessary for the proper"
-		print "              operation of your system. Its arguments can be atoms or"
-		print "              ebuilds. For a dependency aware version of --unmerge, use"
-		print "              --depclean or --prune."
+		print "              Removes all matching packages "+bold("completely")+" from"
+		print "              your system. Specify arguments using the dependency specification"
+		print "              format described in the "+bold("--clean")+" action above."
 		print
 		print "       "+green("--update")+" ("+green("-u")+" short option)"
 		print "              Updates packages to the best version available, which may not"
@@ -303,12 +296,6 @@ def help(myaction,myopts,havecolor=1):
 		print "              Effects vary, but the general outcome is a reduced or condensed"
 		print "              output from portage's displays."
 		print
-		print "       "+green("--reinstall ") + turquoise("changed-use")
-		print "              Tells emerge to include installed packages where USE flags have"
-		print "              changed since installation.  Unlike --newuse, this option does"
-		print "              not trigger reinstallation when flags that the user has not"
-		print "              enabled are added or removed."
-		print
 		print "       "+green("--skipfirst")
 		print "              This option is only valid in a resume situation. It removes the"
 		print "              first package in the resume list so that a merge may continue in"
@@ -391,4 +378,48 @@ def help(myaction,myopts,havecolor=1):
 		print "       versions or newer ebuilds have become available since you last did a"
 		print "       sync and update."
 		print
+	elif myaction=="config":
+		outstuff=green("Config file management support (preliminary)")+"""
+
+Portage has a special feature called "config file protection".  The purpose of
+this feature is to prevent new package installs from clobbering existing
+configuration files.  By default, config file protection is turned on for /etc
+and the KDE configuration dirs; more may be added in the future.
+
+When Portage installs a file into a protected directory tree like /etc, any
+existing files will not be overwritten.  If a file of the same name already
+exists, Portage will change the name of the to-be-installed file from 'foo' to
+'._cfg0000_foo'.  If '._cfg0000_foo' already exists, this name becomes
+'._cfg0001_foo', etc.  In this way, existing files are not overwritten,
+allowing the administrator to manually merge the new config files and avoid any
+unexpected changes.
+
+In addition to protecting overwritten files, Portage will not delete any files
+from a protected directory when a package is unmerged.  While this may be a
+little bit untidy, it does prevent potentially valuable config files from being
+deleted, which is of paramount importance.
+
+Protected directories are set using the CONFIG_PROTECT variable, normally
+defined in /etc/make.globals.  Directory exceptions to the CONFIG_PROTECTed
+directories can be specified using the CONFIG_PROTECT_MASK variable.  To find
+files that need to be updated in /etc, type:
+
+# find /etc -iname '._cfg????_*'
+
+You can disable this feature by setting CONFIG_PROTECT="-*" in /etc/make.conf.
+Then, Portage will mercilessly auto-update your config files.  Alternatively,
+you can leave Config File Protection on but tell Portage that it can overwrite
+files in certain specific /etc subdirectories.  For example, if you wanted
+Portage to automatically update your rc scripts and your wget configuration,
+but didn't want any other changes made without your explicit approval, you'd
+add this to /etc/make.conf:
+
+CONFIG_PROTECT_MASK="/etc/wget /etc/rc.d"
+
+Tools such as dispatch-conf, cfg-update, and etc-update are also available to
+aid in the merging of these files. They provide interactive merging and can
+auto-merge trivial changes.
+
+"""
+		print outstuff