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

1 files changed, 19 insertions, 72 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.