[patch] patch for man/emerge.1

portage-2.0.48-emerge.1.diff (text/plain), 16.41 KB, created by Gregorio Guidi (RETIRED) on 2003-05-25 12:05:17 UTC

--- man/emerge.1~	2003-05-25 17:30:08.000000000 +0200
+++ man/emerge.1	2003-05-25 17:54:10.000000000 +0200
@@ -1,4 +1,4 @@
-.TH "EMERGE" "1" "Feb 2003" "Portage 2.0.47" "Portage"
+.TH "EMERGE" "1" "Feb 2003" "Portage 2.0.48" "Portage"
 .SH "NAME"
 emerge \- Command\-line interface to the Portage system
 .SH "SYNOPSIS"
@@ -7,10 +7,10 @@
 [\fIoptions\fR] [\fIaction\fR] [\fIebuild\fR | \fItbz2file\fR | \fIclass\fR | \fIdependency\fR] ...
 .TP
 \fBemerge\fR
-[\fIoptions\fR] [\fIaction\fR] \fBebuildfile\fR
+\fBsync\fR | \fBinfo\fR
 .TP
 \fBemerge\fR
-\fBsync\fR | \fBrsync\fR
+\fI\-\-resume\fR [\-\-\fBpretend\fR | \-\-\fBskipfirst\fR]
 .TP
 \fBemerge\fR
 \fI\-\-help \-h\fR [\fBsystem\fR | \fBconfig\fR | \fBsync\fR]
@@ -78,29 +78,27 @@
 later updating.  
 .TP
 \fBclean\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.
+Cleans the system by removing outdated packages which will not
+remove functionalities or prevent your system from working.
+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
 .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
+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
@@ -108,40 +106,43 @@
 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.
+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
+make.{conf,globals,defaults} and the environment show up if
+run with the '\-\-verbose' flag.
 .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.
+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.  Example:
+\fBemerge inject sys-kernel/gentoo-sources-2.4.19\fR
 .TP
 \fBprune\fR (\fB\-P\fR)
-\fBWARNING: This action can remove important packages!\fR Removes
-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.
+\fBWARNING: This action can remove important packages!\fR
+Removes all older versions of a package from your system.
+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 \fBclean\fR action.
+.TP
+\fBregen\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)
-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
-contains the word "office".  If you want to search the package
-descriptions as well, use the \fB\-\-searchdesc\fR,\fB-S\fR option.
+Searches for matches of the supplied string in the current local
+portage tree. The search string is a regular expression.
+A few examples:
+  \fBemerge search '^kde'\fR
+    list all packages starting with kde
+  \fBemerge search 'gcc$'\fR
+    list all packages ending with gcc
+  \fBemerge search ''\fR or
+  \fBemerge search '.*'\fR
+    list all available packages
 .TP
 \fBsync\fR
 Initiates a portage tree update with one of the rsync.gentoo.org
@@ -151,14 +152,11 @@
 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.
+\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. Specify arguments using the dependency specification
+format described in the \fBclean\fR action above.
 .SH "OPTIONS "
 .TP
 \fB\-\-buildpkg\fR (\fB\-b\fR)
@@ -170,17 +168,27 @@
 packages is to use \fBquickpkg\fR which creates a tbz2 from the
 live filesystem.
 .TP
+\fB\-\-buildpkgonly\fR (\fB\-B\fR)
+Creates a binary package, but does not merge it to the
+system. This has the restriction that dependencies for the
+desired package will not be automatically merged, so they
+must 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.
+Display the pretend output in a tabular form. Versions are
+aligned vertically.
 .TP
 \fB\-\-debug\fR (\fB\-d\fR)
-Tells emerge to run the emerge command in \-\-debug mode.  In this
+Tells emerge to run the emerge command in \fB\-\-debug\fR mode.  In this
 mode the bash build environment will run with the \-x option,
 causing it to output verbose debug information to stdout.
 \-\-debug is great for finding bash syntax errors.
 .TP
-\fB\-\-deep\fR
+\fB\-\-deep\fR (\fB\-D\fR)
 When used in conjunction with \fB\-\-update\fR, this flag forces
 \fBemerge\fR to consider the entire dependency tree of packages,
 instead of checking only the immediate dependencies of the packages.
@@ -188,25 +196,28 @@
 listed in the dependencies of 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,
+Virtually tweaks the tree of installed packages to only contain glibc,
+this is great to use together with \fB\-\-pretend\fR. This makes it possible for
+developers to get a complete 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 \fB\-\-pretend\fR 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.
-.TP
-\fB\-\-nodeps\fR
-Merges specified packages without merging any dependencies.  Note that
-the build may fail if the dependencies aren't satisfied.
+Portage keeps track of files that have been placed into
+CONFIG_PROTECT 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 (\fB\-O\fR)
+Merges specified packages, but don't merge any dependencies.  Note that
+the build may fail if deps aren't satisfied.
 .TP
 \fB\-\-noreplace\fR (\fB\-n\fR)
 Skips the packages specified on the command\-line that have already
@@ -221,37 +232,78 @@
 .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.
 .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.
+Instead of actually performing the merge, simply display what
+ebuilds and tbz2s *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 = updating, R = replacing, B = blocked by an already installed
+package, D = possible 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)
+Effects vary, but the general outcome is a reduced or condensed
+output from portage's displays.
+.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.
+'emerge \-\-resume' 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
-the package name.  \fBTake caution\fR as the descriptions are also
+the package's name. \fBTake caution\fR as the descriptions are also
 matched as regular expressions.
+  emerge -S html
+  emerge -S applet
+  emerge -S 'perl.*module'
+.TP
+\fB\-\-skipfirst\fR
+This option is only valid in a resume situation. 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.
 .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.
-.TP
-\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.
+Updates packages, along with their dependencies, to the best
+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 ofthe package being installed. SLOTs are
+considered at a basic level.
+.TP
+\fB\-\-usepkg\fR (\fB\-k\fR)
+Tell 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\-\-usepkgonly\fR (\fB\-K\fR)
+Like \-\-usepkg above, except this only allows the use of binary
+packages, and it will abort the emerge if the package is not
+available at the time of dependency calculation.
 .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.
 .TP
-\fB\-\-version\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.
+\fB\-\-version\fR (\fB\-V\fR)
+Displays the currently installed version of portage along with
+other information useful for quick reference on a system. See
+\fBemerge\fR info for more advanced information.
 .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
@@ -372,10 +424,10 @@
 Please include the output of \fBemerge info\fR when you submit your
 bug report.
 .SH "SEE ALSO"
-.BR emerge --help,
-.BR ebuild (1),
-.BR ebuild (5),
-.BR make.conf (5)
+\fBemerge \-\-help\fR,
+\fBebuild\fR(1),
+\fBebuild\fR(5),
+\fBmake.conf\fR(5)
 .LP 
 A number of helper applications reside in \fI/usr/lib/portage/bin\fR.
 .LP 
@@ -398,14 +450,14 @@
 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 
+\fB/usr/portage/profiles/use.desc\fR
 Contains the master list of USE flags with descriptions of their
 functions. \fBDo not edit this file\fR.
 .TP
-\fB/etc/make.profile/virtuals\fR 
+\fB/etc/make.profile/virtuals\fR
 Contains a list of default packages used to resolve virtual dependencies.
 \fBDo not edit this file\fR.
 .TP
@@ -415,7 +467,7 @@
 corresponding virtual here. The first package listed after the virtual is
 the entry used for matching the virtual.
 .TP
-\fB/etc/make.profile/package\fR
+\fB/etc/make.profile/packages\fR
 Contains a list of packages used for the base system. The \fBsystem\fR
 and \fBworld\fR classes consult this file. \fBDo not edit this file\fR.
 .TP