Add documentation for the new --keep-going option.

svn path=/main/trunk/; revision=10818

3 files changed, 39 insertions, 10 deletions

diff --git a/NEWS b/NEWS
index 5a65595a..acd4c6cd 100644
--- a/NEWS
+++ b/NEWS
@@ -3,6 +3,11 @@ News (mainly features/major bug fixes)
 portage-2.2
 -------------
 
+* Add emerge --keep-going option to continue as much as possible after
+  an error. When an error occurs, dependencies are recalculated for
+  remaining packages and any with unsatisfied dependencies are
+  automatically dropped. The --skipfirst option automatically drops
+  packages in the same way, and also drops and masked packages.
 * Add subversion support for repoman.
 * It is now possible to use `emerge <file>` to reinstall the package that
   installed a particular file. Package contents entries are indexed to
diff --git a/man/emerge.1 b/man/emerge.1
index 44a5975f..0dc6884e 100644
--- a/man/emerge.1
+++ b/man/emerge.1
@@ -321,6 +321,12 @@ directory.
 .BR "\-\-ignore-default-opts"
 Causes \fIEMERGE_DEFAULT_OPTS\fR (see \fBmake.conf\fR(5)) to be ignored.
 .TP
+.BR "\-\-keep\-going"
+Continue as much as possible after an error. When an error occurs,
+dependencies are recalculated for remaining packages and any with
+unsatisfied dependencies are automatically dropped. Also see
+the related \fB\-\-skipfirst\fR option.
+.TP
 .BR "\-\-newuse " (\fB\-N\fR)
 Tells emerge to include installed packages where USE flags have changed since 
 compilation.  USE flag changes include:
@@ -399,9 +405,10 @@ 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 
-of an uncorrectable or inconsequential error.  This should only be used in 
-cases where skipping the package will not result in failed dependencies.
+first package in the resume list. Dependencies are recalculated for
+remaining packages and any that have unsatisfied dependencies or are
+masked will be automatically dropped. Also see the related
+\fB\-\-keep\-going\fR option.
 .TP
 .BR "\-\-tree " (\fB\-t\fR)
 Shows the dependency tree for the given target by indenting dependencies.
diff --git a/pym/_emerge/help.py b/pym/_emerge/help.py
index 1ec7e96b..27e150d8 100644
--- a/pym/_emerge/help.py
+++ b/pym/_emerge/help.py
@@ -15,8 +15,8 @@ def shorthelp():
 	print "   "+turquoise("emerge")+" "+turquoise("--resume")+" [ "+green("--pretend")+" | "+green("--ask")+" | "+green("--skipfirst")+" ]"
 	print "   "+turquoise("emerge")+" "+turquoise("--help")+" [ "+green("system")+" | "+green("world")+" | "+green("--sync")+" ] "
 	print bold("Options:")+" "+green("-")+"["+green("abBcCdDefgGhkKlnNoOpqPsStuvV")+"]"
-	print "          [ "+green("--columns")+"   ] [ "+green("--deep")+"      ] [ "+green("--newuse")+"    ]"
-	print "          [ "+green("--noconfmem")+" ] [ "+green("--nospinner")+" ] [ "+green("--oneshot")+"   ]"
+	print "          [ "+green("--columns")+"   ] [ "+green("--deep")+"      ] [ "+green("--keep-going")+" ] [ "+green("--newuse")+"   ]"
+	print "          [ "+green("--noconfmem")+" ] [ "+green("--nospinner")+" ] [ "+green("--oneshot")+"    ]"
 	print "          [ " + green("--color")+" < " + turquoise("y") + " | "+ turquoise("n")+" >           ] [ "+green("--complete-graph")+"            ]"
 	print "          [ "+green("--reinstall ")+turquoise("changed-use")+"     ] [ " + green("--with-bdeps")+" < " + turquoise("y") + " | "+ turquoise("n")+" >      ]"
 	print bold("Actions:")+"  [ "+green("--clean")+" | "+green("--depclean")+" | "+green("--prune")+" | "+green("--regen")+" | "+green("--search")+" | "+green("--unmerge")+" ]"
@@ -292,6 +292,17 @@ def help(myaction,myopts,havecolor=1):
 		print "              downloaded from the remote server without consulting packages"
 		print "              existing in the packages directory."
 		print
+		print "       "+green("--keep-going")
+		desc = "Continue as much as possible after " + \
+			"an error. When an error occurs, " + \
+			"dependencies are recalculated for " + \
+			"remaining packages and any with " + \
+			"unsatisfied dependencies are " + \
+			"automatically dropped. Also see " + \
+			"the related --skipfirst option."
+		for line in wrap(desc, desc_width):
+			print desc_indent + line
+		print
 		print "       "+green("--newuse")+" ("+green("-N")+" short option)"
 		print "              Tells emerge to include installed packages where USE flags have "
 		print "              changed since installation."
@@ -349,11 +360,17 @@ def help(myaction,myopts,havecolor=1):
 		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"
-		print "              the presence of an uncorrectable or inconsequential error. This"
-		print "              should only be used in cases where skipping the package will not"
-		print "              result in failed dependencies."
+		desc = "This option is only valid when " + \
+			"used with --resume.  It removes the " + \
+			"first package in the resume list. " + \
+			"Dependencies are recalculated for " + \
+			"remaining packages and any that " + \
+			"have unsatisfied dependencies or are " + \
+			"masked will be automatically dropped. " + \
+			"Also see the related " + \
+			"--keep-going option."
+		for line in wrap(desc, desc_width):
+			print desc_indent + line
 		print
 		print "       "+green("--tree")+" ("+green("-t")+" short option)"
 		print "              Shows the dependency tree using indentation for dependencies."