From 60671162fcf663b1d5718cbd628034bbf6957b83 Mon Sep 17 00:00:00 2001
From: Zac Medico <zmedico@gentoo.org>
Date: Fri, 20 Jun 2008 03:46:40 +0000
Subject: [PATCH] Document the new emerge <file> feature.

svn path=/main/trunk/; revision=10732
---
 RELEASE-NOTES       | 5 +++++
 man/emerge.1        | 8 +++++++-
 pym/_emerge/help.py | 2 +-
 3 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/RELEASE-NOTES b/RELEASE-NOTES
index 6b15a2f72..ba4bf9409 100644
--- a/RELEASE-NOTES
+++ b/RELEASE-NOTES
@@ -35,6 +35,11 @@ portage-2.2
 portage-2.1.5
 ==================================
 
+* It is now possible to use `emerge <file>` to reinstall the package that
+  installed a particular file. Package contents entries are indexed to
+  improve performance. A command such as `emerge /lib/modules` can serve
+  as a decent substitute for module-rebuild.
+
 * The pkg_postinst phase is now called after the previous version of a
   package has been removed. As a consequence, it is no longer possible
   to call has_version in pkg_postinst to detect whether the current
diff --git a/man/emerge.1 b/man/emerge.1
index 43253bc93..44a5975f1 100644
--- a/man/emerge.1
+++ b/man/emerge.1
@@ -4,7 +4,7 @@ emerge \- Command\-line interface to the Portage system
 .SH "SYNOPSIS"
 .TP
 .BR emerge
-[\fIoptions\fR] [\fIaction\fR] [\fIebuild\fR | \fItbz2file\fR | \fI@set\fR | \fIatom\fR] ...
+[\fIoptions\fR] [\fIaction\fR] [\fIebuild\fR | \fItbz2file\fR | \fIfile\fR | \fI@set\fR | \fIatom\fR] ...
 .TP
 .BR emerge
 \fB\-\-sync\fR | \fB\-\-version\fR
@@ -50,6 +50,12 @@ A \fItbz2file\fR must be a valid .tbz2 created with \fBebuild
 <package>\-<version>.ebuild package\fR or \fBemerge \-\-buildpkg 
 [category/]<package>\fR or \fBquickpkg /var/db/pkg/<category>/<package>\fR.
 .TP
+.BR file
+A \fIfile\fR must be a file or directory that has been installed by one or
+more packages. For directories that are owned by multiple packages, all
+owning packages to be selected. See the portageq(1) owners command if you
+would like to query the owners of one or more files or directories.
+.TP
 .BR set
 A \fIset\fR is a convenient shorthand for a large group of
 packages.  Two sets are currently always available: \fBsystem\fR
diff --git a/pym/_emerge/help.py b/pym/_emerge/help.py
index 1996a61ab..1ec7e96bc 100644
--- a/pym/_emerge/help.py
+++ b/pym/_emerge/help.py
@@ -9,7 +9,7 @@ from portage.output import bold, turquoise, green
 def shorthelp():
 	print bold("emerge:")+" the other white meat (command-line interface to the Portage system)"
 	print bold("Usage:")
-	print "   "+turquoise("emerge")+" [ "+green("options")+" ] [ "+green("action")+" ] [ "+turquoise("ebuildfile")+" | "+turquoise("tbz2file")+" | "+turquoise("dependency")+" ] [ ... ]"
+	print "   "+turquoise("emerge")+" [ "+green("options")+" ] [ "+green("action")+" ] [ "+turquoise("ebuild")+" | "+turquoise("tbz2")+" | "+turquoise("file")+" | "+turquoise("@set")+" | "+turquoise("atom")+" ] [ ... ]"
 	print "   "+turquoise("emerge")+" [ "+green("options")+" ] [ "+green("action")+" ] < "+turquoise("system")+" | "+turquoise("world")+" >"
 	print "   "+turquoise("emerge")+" < "+turquoise("--sync")+" | "+turquoise("--metadata")+" | "+turquoise("--info")+" >"
 	print "   "+turquoise("emerge")+" "+turquoise("--resume")+" [ "+green("--pretend")+" | "+green("--ask")+" | "+green("--skipfirst")+" ]"
-- 
2.26.2