- Add more info to the DESCRIPTION section.

- Add a BUGS section to explain issues related to limitations in the cache
  format and its validation mechanism.

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

1 files changed, 31 insertions, 2 deletions

diff --git a/man/egencache.1 b/man/egencache.1
index c641f036..4891a34a 100644
--- a/man/egencache.1
+++ b/man/egencache.1
@@ -5,7 +5,9 @@ egencache \- generate metadata cache for ebuild repositories
 .B egencache
 .I [options] --update [ATOM]\fR...
 .SH "DESCRIPTION"
-The egencache program generates metadata cache for ebuild repositories.
+The egencache program generates metadata cache for ebuild repositories and
+stores it in the \fImetadata/cache/\fR directory within the repository itself,
+for distribution.
 .SH ACTIONS
 .TP
 .BR "\-\-update [ATOM] ... "
@@ -15,7 +17,9 @@ for the details on package atom syntax.
 .SH OPTIONS
 .TP
 .BR "\-\-cache\-dir=CACHE_DIR"
-Location of the metadata cache.
+Location of the intermediate metadata cache which is stored in a different
+format that includes eclass state. See the \fBBUGS\fR section for
+information about why this is necessary.
 .br
 Defaults to /var/cache/edb/dep.
 .TP
@@ -51,6 +55,31 @@ If this variable is set in \fBmake.conf\fR(5) then any options that it
 contains will be added to the beginning of the command line on every
 invocation. These options will not be added if the
 \fB\-\-ignore-default\-opts\fR option is specified.
+.SH "BUGS"
+There are significant limitations associated with the metadata
+cache format that is distributed in the \fImetadata/cache/\fR directory
+of the repository. These limitations are related to the cache validation
+mechanism. Currently, the validation mechanism involves comparison of
+a cache entry mtime to the mtime of the corresponding \fBebuild(5)\fR. This
+mechanism is unreliable in cases when eclass changes result in metadata
+changes, since no information about eclass state is available in the cache.
+Also, since the mtime of the cache entry must correspond to that of the
+ebuild, the cache format is only suitable for distribution via protocols
+that preserve timestamps (such as \fBrsync(1))\fR. For cache that is
+distributed via \fBgit(1)\fR repositories, there is currently a workaround
+implemented in \fBemerge\fR(1) \fB\-\-sync\fR which updates ebuild mtimes
+to match their corresponding cache entries (except for ebuilds that are
+modified relative to HEAD).
+
+In order to solve the above problems, a future extension
+to the cache format will include additional
+validation data in the form of digests for both the ebuild
+and its inherited eclasses. Until the
+cache format has been extended in this way, it is necessary to enable
+\fBmetadata-transfer\fR in \fBFEATURES\fR (see \fBmake.conf(5)\fR).
+This causes intermediate cache (in a different format that includes
+eclass state) to be generated inside the directory which is configurable
+via the \fB\-\-cache\-dir\fR option.
 .SH "REPORTING BUGS"
 Please report bugs via http://bugs.gentoo.org/
 .SH "AUTHORS"