patch for portage documentation

portage-2.0.47-r12-doc.diff (text/plain), 39.10 KB, created by Gregorio Guidi (RETIRED) on 2003-03-30 19:23:18 UTC

diff -uNr portage-2.0.47-r12.orig/bin/ebuild.sh portage-2.0.47-r12/bin/ebuild.sh
--- portage-2.0.47-r12.orig/bin/ebuild.sh	2003-03-28 06:15:16.000000000 +0100
+++ portage-2.0.47-r12/bin/ebuild.sh	2003-03-30 18:08:35.000000000 +0200
@@ -835,13 +835,16 @@
 	echo
 	echo "  setup       : execute package specific setup actions"
 	echo "  fetch       : download source archive(s) and patches"
+	echo "  digest      : creates a digest file for the package"
 	echo "  unpack      : unpack/patch sources (auto-fetch if needed)"
 	echo "  compile     : compile sources (auto-fetch/unpack if needed)"
-	echo "  merge       : merge image into live filesystem, recording files in db"
-	echo "                (auto-fetch/unpack/compile if needed)"
-	echo "  unmerge     : remove package from live filesystem"
+	echo "  install     : installs the package to the temporary install directory"
+	echo "  qmerge      : merge image into live filesystem, recording files in db"
+	echo "  merge       : does fetch, unpack, compile, install and qmerge"
+	echo "  config      : execute package specific configuration actions"
 	echo "  package     : create tarball package of type ${PACKAGE}"
 	echo "                (will be stored in ${PKGDIR}/All)"
+	echo "  rpm         : builds a RedHat RPM package"
 	echo "  clean       : clean up all source and temporary files"
 	echo
 	echo "The following settings will be used for the ebuild process:"
diff -uNr portage-2.0.47-r12.orig/bin/emergehelp.py portage-2.0.47-r12/bin/emergehelp.py
--- portage-2.0.47-r12.orig/bin/emergehelp.py	2003-03-30 16:51:55.000000000 +0200
+++ portage-2.0.47-r12/bin/emergehelp.py	2003-03-30 18:16:18.000000000 +0200
@@ -12,11 +12,10 @@
 	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")+" >"
-	print "   "+turquoise("emerge")+" < "+turquoise("sync")+" | "+turquoise("info")+" >"
+	print "   "+turquoise("emerge")+" < "+turquoise("--sync")+" | "+turquoise("--info")+" | "+turquoise("--version")+" >"
 	print "   "+turquoise("emerge")+" "+turquoise("--resume")+" ["+green("--pretend")+"]"
-	print "   "+turquoise("emerge")+" "+turquoise("help")+" [ "+green("system")+" | "+green("config")+" | "+green("sync")+" ] "
-	print bold("Options:")+" "+green("-")+"["+green("bcCdDefhikKlnoOpPsSuUvV")+"] ["+green("--oneshot")+"] ["+green("--noconfmem")+"]"
-	print bold("Actions:")+" [ "+green("clean")+" | "+green("depclean")+" | "+green("inject")+" | "+green("prune")+" | "+green("regen")+" | "+green("search")+" | "+green("unmerge")+" ]"
+	print "   "+turquoise("emerge")+" "+turquoise("--help")+" [ "+green("system")+" | "+green("config")+" | "+green("sync")+" ] "
+	print bold("Actions:")+" [ "+green("--clean")+" | "+green("--depclean")+" | "+green("--inject")+" | "+green("--prune")+" | "+green("--regen")+" | "+green("--search")+" | "+green("--unmerge")+" ]"
 	print
 
 def help(myaction,myopts,havecolor=1):
@@ -36,7 +35,7 @@
 		print "              emerge to display detailed help."
 		print
 		print turquoise("Actions:")
-		print "       "+green("clean")+" ("+green("-c")+" short option)"
+		print "       "+green("--clean")+" ("+green("-c")+" short option)"
 		print "              Cleans the system by removing outdated packages which will not"
 		print "              remove functionalities or prevent your system from working."
 		print "              The arguments can be in several different formats :"
@@ -62,7 +61,7 @@
 		print "              "+bold("<=sys-devel/binutils-2.11.92.0.12.3-r1")+" matches"
 		print "                  binutils-2.11.90.0.7 and binutils-2.11.92.0.12.3-r1"
 		print
-		print "       "+green("depclean")
+		print "       "+green("--depclean")
 		print "              Cleans the system by removing packages that are not associated"
 		print "              with explicitly merged packages. Depclean works by creating the"
 		print "              full dependency tree from the system list and the world file,"
@@ -73,92 +72,103 @@
 		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 "       "+green("--info")
 		print "              Displays important portage variables that will be exported to"
 		print "              ebuild.sh when performing merges. This information is useful"
 		print "              for bug reports and verification of settings. All settings in"
 		print "              make.{conf,globals,defaults} and the environment show up if"
 		print "              run with the '--verbose' flag."
 		print
-		print "       "+green("inject")+" ("+green("-i")+" short option)"
+		print "       "+green("--inject")+" ("+green("-i")+" short option)"
 		print "              Add a stub entry for a package so that Portage thinks that it's"
-		print "              installed when it really isn't.  Handy if you roll your own"
-		print "              packages.  Example: "
+		print "              installed when it really isn't. Handy if you roll your own"
+		print "              packages. You must specify a category and particular version of"
+		print "              a package, for example: "
 		#NOTE: this next line *needs* the "sys-kernel/"; *please* don't remove it!
-		print "              "+bold("emerge inject sys-kernel/gentoo-sources-2.4.19")
+		print "              "+bold("emerge --inject sys-kernel/gentoo-sources-2.4.19")
 		print
-		print "       "+green("prune")+" ("+green("-P")+" short option)"
+		print "       "+green("--prune")+" ("+green("-P")+" short option)"
 		print "              "+turquoise("WARNING: This action can remove important packages!")
-		print "              Removes all older versions of a package from your system."
+		print "              Removes all but the latest versions of matching packages. If there are"
+		print "              multiple SLOTs for a package, it leaves the latest version in each SLOT."
 		print "              This action doesn't always verify the possible binary"
 		print "              incompatibility between versions and can thus remove essential"
 		print "              dependencies from your system."
-		print "              The argument format is the same as for the "+bold("clean")+" action."
+		print "              The argument format is the same as for the "+bold("--clean")+" action."
 		print
-		print "       "+green("regen")
+		print "       "+green("--regen")
 		print "              Causes portage to check and update the dependency cache of all"
 		print "              ebuilds in the portage tree. This is not recommended for rsync"
 		print "              users as rsync updates the cache using server-side caches."
-		print "              Rsync users should simply 'emerge sync' to regenerate."
+		print "              Rsync users should simply 'emerge --sync' to regenerate."
 		print
-		print "       "+green("search")+" ("+green("-s")+" short option)"
+		print "       "+green("--search")+" ("+green("-s")+" short option)"
 		print "              searches for matches of the supplied string in the current local"
 		print "              portage tree. The search string is a regular expression."
 		print "              A few examples: "
-		print "              "+bold("emerge search '^kde'")
+		print "              "+bold("emerge --search '^kde'")
 		print "                  list all packages starting with kde"
-		print "              "+bold("emerge search 'gcc$'")
+		print "              "+bold("emerge --search 'gcc$'")
 		print "                  list all packages ending with gcc"
-		print "              "+bold("emerge search ''")+" or"
-		print "              "+bold("emerge search '.*'")
+		print "              "+bold("emerge --search ''")+" or"
+		print "              "+bold("emerge --search '.*'")
 		print "                  list all available packages "
 		print
-		print "       "+green("unmerge")+" ("+green("-C")+" short option)"
+		print "       "+green("--unmerge")+" ("+green("-C")+" short option)"
 		print "              "+turquoise("WARNING: This action can remove important packages!")
 		print "              Removes all matching packages without checking for outdated"
 		print "              versions, effectively removing a package "+bold("completely")+" from"
 		print "              your system. Specify arguments using the dependency specification"
-		print "              format described in the "+bold("clean")+" action above."
+		print "              format described in the "+bold("--clean")+" action above."
 		print
 		print turquoise("Options:")
 		print "       "+green("--buildpkg")+" ("+green("-b")+" short option)"
-		print "              tell emerge to build binary packages for all ebuilds processed"
-		print "              (in addition to actually merging the packages.  Useful for"
+		print "              Tells emerge to build binary packages for all ebuilds processed"
+		print "              (in addition to actually merging the packages). Useful for"
 		print "              maintainers or if you administrate multiple Gentoo Linux"
-		print "              systems (build once, emerge tbz2s everywhere)."
+		print "              systems (build once, emerge tbz2s everywhere). The package will"
+		print "              be created in the "+bold("${PKGDIR}/All")+" directory."
 		print
 		print "       "+green("--buildpkgonly")+" ("+green("-B")+" short option)"
-		print "              Creates binary a binary package, but does not merge it to the"
-		print "              system. This has the restriction that unsatisfied dependancies"
-		print "              must not exist for the desired package as they cannot be used if"
-		print "              they do not exist on the system."
+		print "              Creates a binary package, but does not merge it to the"
+		print "              system. This has the restriction that dependencies for the"
+		print "              desired package will not be automatically merged, so they"
+		print "              must exist on the system."
 		print
 		print "       "+green("--changelog")+" ("+green("-l")+" short option)"
 		print "              When pretending, also display the ChangeLog entries for packages"
 		print "              that will be upgraded."
 		print
+		print "       "+green("--columns")
+		print "              With this option, the output produced with --pretend will be"
+		print "              aligned to be easy to parse."
+		print
 		print "       "+green("--debug")+" ("+green("-d")+" short option)"
 		print "              Tell emerge to run the ebuild command in --debug mode. In this"
 		print "              mode, the bash build environment will run with the -x option,"
-		print "              causing it to output verbose debug information print to stdout."
+		print "              causing it to output verbose debug information to stdout."
 		print "              --debug is great for finding bash syntax errors."
 		print
 		print "       "+green("--deep")+" ("+green("-D")+" short option)"
 		print "              When used in conjunction with --update, this flag forces emerge"
 		print "              to consider the entire dependency tree of packages, instead of"
-		print "              checking only the immediate dependencies of the packages.  As an"
+		print "              checking only the immediate dependencies of the packages. As an"
 		print "              example, this catches updates in libraries that are not directly"
 		print "              listed in the dependencies of a package."
-		print 
+		print
+		print "       "+green("--digest")
+		print "              Forces creation of digest file when digest is missing for a package."
+		print
 		print "       "+green("--emptytree")+" ("+green("-e")+" short option)"
 		print "              Virtually tweaks the tree of installed packages to only contain"
 		print "              glibc, this is great to use together with --pretend. This makes"
 		print "              it possible for developers to get a complete overview of the"
-		print "              complete dependency tree of a certain package."
+		print "              dependency tree of a package, and it enables complete trees to"
+		print "              be rebuilt using the latest libraries."
 		print
 		print "       "+green("--fetchonly")+" ("+green("-f")+" short option)"
 		print "              Instead of doing any package building, just perform fetches for"
-		print "              all packages (main package as well as all dependencies.) When"
+		print "              all packages (main package as well as all dependencies). When"
 		print "              used in combination with --pretend all the SRC_URIs will be"
 		print "              displayed multiple mirrors per line, one line per file."
 		print
@@ -175,12 +185,18 @@
 		print "              Note that the build may fail if deps aren't satisfied."
 		print 
 		print "       "+green("--noreplace")+" ("+green("-n")+" short option)"
-		print "              Skip the packages specified on the command-line that have"
-		print "              already been installed.  Without this option, any packages,"
-		print "              ebuilds, or deps you specify on on the command-line *will* cause"
-		print "              Portage to remerge the package, even if it is already installed."
+		print "              Skip the packages specified on the command-line for which"
+		print "              the same version has already been installed."
+		print "              Without this option, any packages, ebuilds, or deps you specify"
+		print "              on the command-line *will* cause Portage to remerge the"
+		print "              package, even if it is already installed."
 		print "              Note that Portage won't remerge dependencies by default."
 		print
+		print "       "+green("--nospinner")
+		print "              Disables the spinner for the session. The spinner is active when"
+		print "              the terminal device is determined to be a TTY. This flag disables"
+		print "              it regardless."
+		print
 		print "       "+green("--oneshot")
 		print "              Emerge as normal, but don't add packages to the world profile for"
 		print "              later updating. This prevents consideration of this package"
@@ -196,10 +212,13 @@
 		print "              weren't used.  Using --pretend is strongly recommended before"
 		print "              installing an unfamiliar package.  In the printout, N = new,"
 		print "              U = updating, R = replacing, B = blocked by an already installed"
-		print "              package, D = possible downgrading. --verbose causes affecting"
+		print "              package, D = downgrading. --verbose causes affecting"
 		print "              use flags to be printed out accompanied by a '+' for enabled"
 		print "              and a '-' for disabled flags."
 		print
+		print "       "+green("--quiet")+" ("+green("-q")+" short option)"
+		print "              Tells portage to be less verbose when doing search or regen."
+		print
 		print "       "+green("--resume")
 		print "              Resumes the last merge operation. Can be treated just like a"
 		print "              regular merge as --pretend and other options work along side."
@@ -215,9 +234,9 @@
 		print "                emerge -S 'perl.*module'"
 		print
 		print "       "+green("--update")+" ("+green("-u")+" short option)"
-		print "              Updates packages to the best version available, which may not"
-		print "              always be the highest version number due to masking for testing"
-		print "              and development."
+		print "              Updates packages, along with their dependencies, to the best"
+		print "              version available, which may not always be the highest version"
+		print "              number due to masking for testing and development."
 		print
 		print "       "+green("--upgradeonly")+" ("+green("-U")+" short option)"
 		print "              Updates packages, but excludes updates that would result in a"
@@ -225,7 +244,7 @@
 		print "              considered at a basic level."
 		print
 		print "       "+green("--usepkg")+" ("+green("-k")+" short option)"
-		print "              Tell emerge to use binary packages (from $PKGDIR) if they are"
+		print "              Tells emerge to use binary packages (from $PKGDIR) if they are"
 		print "              available, thus possibly avoiding some time-consuming compiles."
 		print "              This option is useful for CD installs; you can export"
 		print "              PKGDIR=/mnt/cdrom/packages and then use this option to have"
@@ -238,7 +257,15 @@
 		print "              available at the time of dependency calculation."
 		print
 		print "       "+green("--verbose")+" ("+green("-v")+" short option)"
-		print "              Tell emerge to run in verbose mode."
+		print "              Tells emerge to run in verbose mode. If used in conjunction"
+		print "              with --pretend, it displays the USE variables enabled for the"
+		print "              build process."
+		print
+		print "       "+green("--version")+" ("+green("-V")+" short option)"
+		print "              Displays the version number of "+bold("emerge")+"."
+		print "              It cannot be used in conjunction with other options; the name"
+		print "              and format of the action is a convention."
+		print
 	elif myaction in ["rsync","sync"]:
 		print
 		print bold("Usage: ")+turquoise("emerge")+" "+turquoise("sync")
Files portage-2.0.47-r12.orig/bin/portage-2.0.47-r12.tar.bz2 and portage-2.0.47-r12/bin/portage-2.0.47-r12.tar.bz2 differ
diff -uNr portage-2.0.47-r12.orig/man/ebuild.1 portage-2.0.47-r12/man/ebuild.1
--- portage-2.0.47-r12.orig/man/ebuild.1	2003-03-07 08:44:40.000000000 +0100
+++ portage-2.0.47-r12/man/ebuild.1	2003-03-30 18:24:14.000000000 +0200
@@ -1,7 +1,7 @@
-.TH "EBUILD" "1" "Nov 2002" "Portage 2.0.44" "Portage"
+.TH "EBUILD" "1" "Feb 2003" "Portage 2.0.47" "Portage"
 .SH "NAME"
 ebuild \- manual page for the ebuild program, a low level interface to
-the Portage system. 
+the Portage system.
 .SH "SYNOPSIS"
 .B ebuild
 .I file command [command]\fR...
@@ -120,14 +120,16 @@
 will perform all these steps for you, stopping along the way if a
 particular step doesn't complete successfully.
 .TP
-.BR unmerge
-This function first executes the \fIpkg_prerm\fR function (if specified).
-Then it removes all files from the live filesystem that have a valid md5
-checksum and mtime in the package contents file.  Any empty directories
-are recursively removed.  Finally, it runs \fIpkg_postrm\fR function (if
-specified).  It is safe to merge a new version of a package first and
-then unmerge the old one.  In fact, this is the recommended package
-upgrade method.
+.BR config
+Run specific actions needed to donfigure package after install
+.TP
+.BR prerm
+Run package specific actions that need to be done before the package
+is removed from filesystem.
+.TP
+.BR postrm
+Run package specific actions that need to be done after the package
+is removed from filesystem.
 .TP
 .BR package
 This command is a lot like the \fImerge\fR command, except that after
diff -uNr portage-2.0.47-r12.orig/man/ebuild.5 portage-2.0.47-r12/man/ebuild.5
--- portage-2.0.47-r12.orig/man/ebuild.5	2003-03-30 16:52:34.000000000 +0200
+++ portage-2.0.47-r12/man/ebuild.5	2003-03-30 16:41:45.000000000 +0200
@@ -111,7 +111,7 @@
 \fBWORKDIR\fR = \fI"${PORTAGE_TMPDIR}/portage/${PF}/work"\fR
 Contains the path to the package build root.  Do not modify this variable.
 .TP
-\fBFILESDIR\fR = \fI"${PORTDIR}/${CATEGORY}/${PF}/files"\fR
+\fBFILESDIR\fR = \fI"${PORTDIR}/${CATEGORY}/${PN}/files"\fR
 Contains the path to the 'files' sub folder in the package specific
 location in the portage tree.  Do not modify this variable.
 .TP
@@ -256,6 +256,12 @@
 .br
 You may use the same syntax to vary dependencies as seen above in \fBDEPEND\fR.
 .TP
+\fBPDEPEND\fR
+This should contain a list of all packages that will have to be installed after
+the program has been merged.
+.br
+You may use the same syntax to vary dependencies as seen above in \fBDEPEND\fR.
+.TP
 \fBRESTRICT\fR = \fI[nostrip,nomirror,fetch]\fR
 This should be a space delimited list of portage features to restrict.
 .PD 0
@@ -501,7 +507,7 @@
 .TP
 .B prepallstrip
 .PD 1
-Useful for when a package installs into \fB${D}\fR via scripts
+Useful when a package installs into \fB${D}\fR via scripts
 (i.e. makefiles).  If you want to be sure that libraries are executable,
 aclocal files are installed into the right place, doc/info/man files are
 all compressed, and that executables are all stripped of debugging symbols,
diff -uNr portage-2.0.47-r12.orig/man/emerge.1 portage-2.0.47-r12/man/emerge.1
--- portage-2.0.47-r12.orig/man/emerge.1	2003-03-30 16:52:20.000000000 +0200
+++ portage-2.0.47-r12/man/emerge.1	2003-03-30 18:39:19.000000000 +0200
@@ -7,16 +7,13 @@
 [\fIoptions\fR] [\fIaction\fR] [\fIebuild\fR | \fItbz2file\fR | \fIclass\fR | \fIdependency\fR] ...
 .TP
 \fBemerge\fR
-[\fIoptions\fR] [\fIaction\fR] \fBebuildfile\fR
+\fB\-\-sync\fR | \fB\-\-info\fR | \fB\-\-version\fR
 .TP
 \fBemerge\fR
-\fBsync\fR | \fBrsync\fR
+\fB\-\-resume\fR | [\fB\-\-pretend\fR]
 .TP
 \fBemerge\fR
-\fI\-\-help \-h\fR [\fBsystem\fR | \fBconfig\fR | \fBsync\fR]
-.TP
-\fBemerge\fR
-\fI\-\-version\fR
+\fB\-\-help\fR [\fBsystem\fR | \fBconfig\fR | \fBsync\fR]
 .SH "DESCRIPTION"
 \fBemerge\fR is the definitive command\-line interface to the Portage
 system.  It is primarily used for installing packages, and \fBemerge\fR
@@ -77,100 +74,105 @@
 to the \fBworld\fR file at the end, so that they are considered for
 later updating.  
 .TP
-\fBclean\fR (\fB\-c\fR)
+\fB\-\-clean\fR (\fB\-c\fR)
 Cleans the system by removing packages that will not effect the
 functionality of the system.  The arguments can be \fIebuilds\fR,
 \fIclasses\fR, or \fIdependencies\fR.  For example, \fBemerge
 clean binutils\fR cleans out old versions of binutils;
 \fBemerge clean net\-www/mozilla\-0.9.9\-r2\fR cleans out that
 specific version of Mozilla.  This is generally safe to use.
-\fBNote that\fR clean \fBdoes not remove unslotted packages.\fR
+\fBNote that\fR clean \fBdoes not remove slotted packages.\fR
 .TP
-\fBdepclean\fR
-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 are suggested for unmerging. \fBWARNING: Removing some
-packages may cause packages which link to the removed package
-to stop working and complain about missing libraries.\fR
-Re\-emerge the complaining package to fix this issue.
-\fBNote that changes in USE flags can drastically affect the
-output of depclean.\fR
+\fB\-\-depclean\fR
+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. \fBWARNING: This can seriously affect your system by
+removing packages that may have been linked against, but due to
+changes in USE flags may no longer be part of the dep tree. Use
+caution when employing this feature\fR.
 .TP
-\fBhelp\fR (\fB\-h\fR)
+\fB\-\-help\fR (\fB\-h\fR)
 Displays help information for emerge.  Adding one of the additional
 arguments listed above will give you more specific help information
 on that subject.  The internal \fBemerge\fR help documentation is
 updated more frequently than this man page; check it out if you
 are having problems that this man page does not help resolve.
 .TP
-\fBinfo\fR
-This is a list of information to include in bug reports which aids
-the developers with fixing any problems you may report. \fBPlease
-include this information when submitting a bug report.\fR Expanded
-output can be obtained with the \fI--verbose\fR option.
-.TP
-\fBinject\fR (\fB\-i\fR)
-Injecting a package inserts a 'stub' for that package so that Portage
-thinks that it is installed. It is handy if you need, say, a binary
-version of XFree86 for esoteric hardware, or you just like to roll
-your own packages.  You \fBmust\fR specify a category and particular
-version of a package for injecting.  For example,
-\fBemerge inject sys\-kernel/gentoo\-sources\-2.4.19\fR.
+\fB\-\-info\fR
+Displays important portage variables that will be exported to
+ebuild.sh when performing merges. This information is useful
+for bug reports and verification of settings. All settings in
+\fBmake.{conf,globals,defaults}\fR and the environment show up if
+run with the \fB--verbose\fR flag.
+.TP
+\fB\-\-inject\fR (\fB\-i\fR)
+Add a stub entry for a package so that Portage thinks that it's
+installed when it really isn't. Handy if you roll your own
+packages. You must specify a category and particular version of
+a package, for example: \fBemerge --inject sys-kernel/gentoo-sources-2.4.19\fR.
 .TP
-\fBprune\fR (\fB\-P\fR)
+\fB\-\-prune\fR (\fB\-P\fR)
 \fBWARNING: This action can remove important packages!\fR Removes
-all but the latest versions of matching packages.  If there are
+all but the latest versions of matching packages. If there are
 multiple SLOTs for a package, it leaves the latest version in each
-SLOT. This does no checking of dependencies, so it may remove
-packages necessary for the proper operation of your system. \fBUse\fR
-clean \fBinstead unless you really know what you're doing\fR.  Its
-arguments can be \fIebuilds\fR, \fIclasses\fR, or \fIdependencies\fR
-\-\- see \fBclean\fR above for examples.
-.TP
-\fBrsync\fR
-See \fBsync\fR below.
+SLOT. This action doesn't always verify the possible binary
+incompatibility between versions and can thus remove essential
+dependencies from your system. The argument format is the same as
+for the \fB\-\-clean\fR action.
+.TP
+\fB\-\-regen\fR
+Causes portage to check and update the dependency cache of all ebuilds
+in the portage tree. This is not recommended for rsync users as rsync
+updates the cache using server-side caches. Rsync users should simply
+\fBemerge \-\-sync\fR to regenerate.
 .TP
-\fBsearch\fR (\fB\-s\fR)
+\fB\-\-search\fR (\fB\-s\fR)
 Searches for matches of the supplied string in the portage tree.
 The search string is a regular expression.  For example, \fBemerge
-search "^kde"\fR searches for any package that starts with "kde";
-\fBemerge search "gcc$"\fR searches for any package that ends with
-"gcc"; \fBemerge search "office"\fR searches for any package that
+\-\-search "^kde"\fR searches for any package that starts with "kde";
+\fBemerge \-\-search "gcc$"\fR searches for any package that ends with
+"gcc"; \fBemerge \-\-search "office"\fR searches for any package that
 contains the word "office".  If you want to search the package
 descriptions as well, use the \fB\-\-searchdesc\fR,\fB-S\fR option.
 .TP
-\fBsync\fR
+\fB\-\-sync\fR
 Initiates a portage tree update with one of the rsync.gentoo.org
 mirrors.  \fBNote that any changes you have made to the portage
-tree will be erased\fR.  Except for in special circumstances,
+tree will be erased\fR.  Except for special circumstances,
 this uses \fBrsync\fR to do the update. See make.conf's description
 of PORTDIR_OVERLAY for a method to avoid deletions.
 .TP
-\fBunmerge\fR (\fB\-C\fR)
-\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 \fIebuilds\fR, \fIclasses\fR, or
-\fIdependencies\fR \-\- see \fBclean\fR above for examples.
-.TP
-\fB\-\-version\fR
-Displays the version number of \fBemerge\fR.
+\fB\-\-unmerge\fR (\fB\-C\fR)
+\fBWARNING: This action can remove important packages!\fR
+Removes all matching packages without checking for outdated
+versions, effectively removing a package \fBcompletely\fR from
+your system. The argument format is the same as for the
+\fB\-\-clean\fR action.
 .SH "OPTIONS "
 .TP
 \fB\-\-buildpkg\fR (\fB\-b\fR)
 Tells emerge to build binary packages for all ebuilds processed in
 addition to actually merging the packages.  Useful for maintainers
 or if you administrate multiple Gentoo Linux systems (build once,
-emerge tbz2s everywhere).  The package will be created in the
+emerge tbz2s everywhere). The package will be created in the
 \fI${PKGDIR}\fR/All directory.
 .TP
+\fB\-\-buildpkgonly\fR (\fB\-B\fR)
+Creates binary a binary package, but does not merge it to the
+system. This has the restriction that unsatisfied dependancies
+must not exist for the desired package as they cannot be used if
+they do not exist on the system.
+.TP
+\fB\-\-changelog\fR (\fB\-l\fR)
+When pretending, also display the ChangeLog entries for packages
+that will be upgraded.
+.TP
 \fB\-\-columns\fR
-Used along side \fI--pretend\fR to causes the package, new version,
-and old version to be displayed in an aligned format for easy cut\-n\-paste.
+With this option, the output produced with --pretend will be
+aligned to be easy to parse.
 .TP
 \fB\-\-debug\fR (\fB\-d\fR)
 Tells emerge to run the emerge command in \-\-debug mode.  In this
@@ -185,33 +187,39 @@
 As an example, this catches updates in libraries that are not directly
 listed in the dependencies of a package.
 .TP
+\fB\-\-digest\fR
+Forces creation of digest file when digest is missing for a package.
+.TP
 \fB\-\-emptytree\fR (\fB\-e\fR)
 Virtually tweaks the tree of installed packages to only contain glibc;
 this is great to use together with \-\-pretend. This allows developers
-to get a complete overview of the complete dependency tree of a package,
+to get an overview of the complete dependency tree of a package,
 and it enables complete trees to be rebuilt using the latest libraries.
 .TP
 \fB\-\-fetchonly\fR (\fB\-f\fR)
 Instead of doing any package building, just perform fetches for all
-packages (the main package as well as all dependencies.)
+packages (the main package as well as all dependencies). When
+used in combination with --pretend all the SRC_URIs will be
+displayed multiple mirrors per line, one line per file.
 .TP
 \fB\-\-noconfmem\fR
-Causes portage to disregard merge records indicating that a config file
-inside of a CONFIG_PROTECT directory has been merged already. Portage
-will normally merge those files only once to prevent the user from
-dealing with the same config multiple times. This flag will cause the
-file to always be merged.
+Portage keeps track of files that have been placed into
+\fBCONFIG_PROTECT\fR directories, and normally it will not merge the
+same file more than once, as that would become annoying. This
+can lead to problems when the user wants the file in the case
+of accidental deletion. With this option, files will always be
+merged to the live fs instead of silently dropped.
 .TP
 \fB\-\-nodeps\fR
-Merges specified packages without merging any dependencies.  Note that
+Merges specified packages without merging any dependencies. Note that
 the build may fail if the dependencies aren't satisfied.
 .TP
 \fB\-\-noreplace\fR (\fB\-n\fR)
-Skips the packages specified on the command\-line that have already
-been installed.  Without this option, any packages, ebuilds, or deps
-you specify on on the command\-line *will* cause Portage to remerge
-the package, even if it is already installed. Note that Portage will
-not remerge dependencies by default.
+Skips the packages specified on the command\-line for which the same
+version is already installed. Without this option, any packages,
+ebuilds, or deps you specify on on the command\-line *will* cause
+Portage to remerge the package, even if it is already installed.
+Note that Portage will not remerge dependencies by default.
 .TP
 \fB\-\-nospinner\fR
 Disables the spinner for the session. The spinner is active when the
@@ -219,18 +227,30 @@
 .TP
 \fB\-\-oneshot\fR
 Emerge as normal, but do not add the packages to the world profile
-for later updating.
+for later updating. This prevents consideration of this package
+unless this package is depended upon by another package.
 .TP
 \fB\-\-onlydeps\fR (\fB\-o\fR)
-Only merge (or pretend to merge) the dependencies of the packages
-specified, not the packages themselves.
+Only merge (or pretend to merge) the dependencies of the specified
+packages, not the packages themselves.
 .TP
 \fB\-\-pretend\fR (\fB\-p\fR)
 Instead of actually performing the merge, simply display what *would*
 have been installed if \-\-pretend weren't used.  Using \-\-pretend
 is strongly recommended before installing an unfamiliar package. In
 the printout, N = new, U = upgrading, R = replacing, B = blocked by
-an already installed package.
+an already installed package, D = downgrading. --verbose causes affecting
+use flags to be printed out accompanied by a '+' for enabled
+and a '-' for disabled flags.
+.TP
+\fB\-\-quiet\fR (\fB\-q\fR)
+Tells portage to be less verbose when doing \fBsearch\fR or \fBregen\fR.
+.TP
+\fB\-\-resume\fR
+Resumes the last merge operation. Can be treated just like a
+regular merge as --pretend and other options work along side.
+\fBemerge --resume\fR only returns an error on failure. Nothing to
+do exits with a message and a success condition.
 .TP
 \fB\-\-searchdesc\fR (\fB\-S\fR)
 Matches the search string against the description field as well as
@@ -238,21 +258,29 @@
 matched as regular expressions.
 .TP
 \fB\-\-update\fR (\fB\-u\fR)
-Updates packages to the most recent version available.  \fBNote that\fR \-\-update \fBdoes not have full functionality yet\fR.  It will not automatically update dependencies of packages in the \fBworld\fR file, unless they too are in the \fBworld\fR file.
+Updates packages, along with their dependencies, to the most recent
+version available, which may not always be the highest version number
+due to masking for testing and development.
+.TP
+\fB\-\-upgradeonly\fR (\fB\-U\fR)
+Updates packages, but excludes updates that would result in a
+lower version of the package being installed. SLOTs are
+considered at a basic level.
 .TP
-\fB\-\-usepkg\fR (\fB\-k\fR) 
+\fB\-\-usepkg\fR (\fB\-k\fR)
 Tells emerge to use binary packages (from $PKGDIR) if they are available, thus possibly avoiding some time\-consuming compiles. This option is useful for CD installs; you can export PKGDIR=/mnt/cdrom/packages and then use this option to have emerge "pull" binary packages from the CD in order to satisfy dependencies.
 .TP
 \fB\-\-verbose\fR (\fB\-v\fR)
-Tell emerge to run in verbose mode.  Currently this flag causes emerge to print out GNU info errors, if any.
+Tells emerge to run in verbose mode. If used in conjunction with \-\-pretend,
+it displays the USE variables enabled for the build process.
 .TP
-\fB\-\-version\fR
-Displays the version number of \fBemerge\fR.  It cannot be used in
+\fB\-\-version\fR (\fB\-V\fR)
+Displays the version number of \fBemerge\fR. It cannot be used in
 conjunction with other options; the name and format of the action
 is a convention.
 .SH "OUTPUT"
 While utilizing emerge and the pretend/verbose flags, the output
-may be a little hard to understand for the first time.  This section
+may be a little hard to understand the first time.  This section
 exists to explain what the shorthanded information means.
 .TP
 .B [blocks B     ] app-text/dos2unix (from pkg app-text/hd2u-0.8.0)
@@ -296,6 +324,12 @@
 we see that nmap can use the \fBUSE\fR variables gtk and gnome, but that your current
 settings have gtk and gnome disabled.  So optional support for gtk and gnome will
 not be enabled in nmap when you emerge it.
+.TP
+.B [ebuild    U ] media-video/nvidia-kernel-1.0.3123-r2 [1.0.4191-r2]
+If you run the command, the selected package will be installed.
+A newer version is already present, but the D flag is not displayed,
+this means that the package will be installed in a different SLOT
+and will peacefully coexist with the installed one.
 .SH "NOTES"
 You should almost always precede any package install or update
 attempt with a \fB\-\-pretend\fR install or update.  This lets
@@ -305,10 +339,6 @@
 update a large number of packages if the portage tree has
 been particularly active.
 .LP 
-You also want to typically use \fB\-\-update\fR, which ignores
-packages that are already fully updated but upgrades those that
-are not.
-.LP 
 When you install a package with uninstalled dependencies and do
 not explicitly state those dependencies in the list of parameters,
 they will not be added to the world file.  If you want them to be
@@ -321,12 +351,6 @@
 flags specified on the command line are NOT remembered\fR.  For
 example, \fBUSE="\-x \-gnome" emerge mc\fR will emerge mc with
 those USE settings.
-.LP 
-If \fBemerge \-\-update system\fR or \fB emerge \-\-update world\fR
-fail 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
-version, which should support any necessary new features.
 .SH "MASKED PACKAGES"
 \fINOTE: Please use caution when using development packages. Problems
 and bugs resulting from misusing masked packages drains Gentoo
@@ -396,8 +420,8 @@
 edit this file\fR.
 .TP
 \fB/etc/make.profile/use.defaults\fR
-Contains the USE flags that are enabled by default. \fBDo not edit this
-file\fR.
+Contains packages that, if installed, cause respective USE flag to be enabled by default.
+\fBDo not edit this file\fR.
 .TP
 \fB/usr/portage/profiles/use.desc\fR 
 Contains the master list of USE flags with descriptions of their
diff -uNr portage-2.0.47-r12.orig/man/make.conf.5 portage-2.0.47-r12/man/make.conf.5
--- portage-2.0.47-r12.orig/man/make.conf.5	2003-03-30 16:52:54.000000000 +0200
+++ portage-2.0.47-r12/man/make.conf.5	2003-03-30 18:34:15.000000000 +0200
@@ -91,12 +91,12 @@
 .br
 Defaults to ${PORTDIR}/distfiles.
 .TP
-\fBFEATURES\fR = \fI"buildpkg ccache cvs digest mirror noauto noclean sandbox"\fR
+\fBFEATURES\fR = \fI"buildpkg ccache cvs digest distcc keeptemp mirror noauto noclean notitles sandbox userpriv usersandbox"\fR
 Defines actions portage takes by default.  These options should
 not be changed by anyone but developers and/or maintainers.  'sandbox' is an important
 part of \fBFEATURES\fR and should not be disabled by default.
 .br
- 
+
 .br
 \fIbuildpkg\fR: binary packages will always be generated.
 .br
@@ -119,6 +119,8 @@
 \fInoclean\fR: do not clean out the build directory after finishing
 merging the package.
 .br
+\fInotitles\fR: disables xterm titlebar updates.
+.br
 \fIsandbox\fR: enable sandbox-ing when running \fBemerge\fR(1) and
 \fBebuild(1)\fR.
 .br
@@ -139,7 +141,7 @@
 .TP
 \fBMAKEOPTS\fR
 Use this variable if you want to use parallel make.  For example, if you
-have a dual\-processor system, set this variable to "\-j2" or "\-j3" for 
+have a dual\-processor system, set this variable to "\-j2" or "\-j3" for
 enhanced build performance with many packages. Suggested settings are
 between \fICPUs+1\fR and \fI2*CPUs+1\fR.
 For more information, see \fBmake\fR(1).
@@ -166,11 +168,11 @@
 Defines the location where created .tbz2 binary packages will be stored.
 .br
 Defaults to ${PORTDIR}/packages.
-.TP 
+.TP
 \fBPORTDIR\fR = \fI[path]\fR
 Defines the location of your Portage tree.
 .br
-Defaults to /usr/portage. 
+Defaults to /usr/portage.
 .TP
 \fBPORTDIR_OVERLAY\fR = \fI[path]\fR
 Defines a directory in which user made ebuilds may be stored and not