For bug #131030, update the warning about potential for emerge --sync overwrite or delete files in ${PORTDIR}. Add references to the PKGDIR and DISTDIR docs.

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

2 files changed, 26 insertions, 11 deletions

diff --git a/cnf/make.conf b/cnf/make.conf
index e411b153f..8a3b180ca 100644
--- a/cnf/make.conf
+++ b/cnf/make.conf
@@ -78,18 +78,28 @@
 # PORTDIR is the location of the portage tree. This is the repository
 #     for all profile information as well as all ebuilds. If you change
 #     this, you must update your /etc/make.profile symlink accordingly.
+#     ***Warning***
+#     Data stored inside PORTDIR is in peril of being overwritten or deleted by
+#     the emerge --sync command. The default value of PORTAGE_EXTRA_RSYNC_OPTS
+#     will protect the default locations of DISTDIR and PKGDIR, but users are
+#     warned that any other locations inside PORTDIR are not necessarily safe
+#     for data storage.
 #PORTDIR=/usr/portage
 #
 # DISTDIR is where all of the source code tarballs will be placed for
 #     emerges. The source code is maintained here unless you delete
 #     it. The entire repository of tarballs for Gentoo is 9G. This is
 #     considerably more than any user will ever download. 2-3G is
-#     a large DISTDIR.
+#     a large DISTDIR. Note that locations under /usr/portage are not
+#     necessarily safe for data storage. See the PORTDIR documentation
+#     for more information.
 #DISTDIR=/usr/portage/distfiles
 #
 # PKGDIR is the location of binary packages that you can have created
 #     with '--buildpkg' or '-b' while emerging a package. This can get
-#     up to several hundred megs, or even a few gigs.
+#     up to several hundred megs, or even a few gigs. Note that
+#     locations under /usr/portage are not necessarily safe for data
+#     storage. See the PORTDIR documentation for more information.
 #PKGDIR=/usr/portage/packages
 #
 # PORT_LOGDIR is the location where portage will store all the logs it
diff --git a/man/make.conf.5 b/man/make.conf.5
index d0de72fd7..e0c0bbbf5 100644
--- a/man/make.conf.5
+++ b/man/make.conf.5
@@ -96,7 +96,9 @@ This variable is passed by the \fIebuild scripts\fR to the \fIconfigure\fR
 as \fI\-\-target=${CTARGET}\fR only if it is defined.
 .TP
 \fBDISTDIR\fR = \fI[path]\fR
-Defines the location of your local source file repository.
+Defines the location of your local source file repository.  Note
+that locations under /usr/portage are not necessarily safe for data storage.
+See the \fBPORTDIR\fR documentation for more information.
 .br
 Defaults to /usr/portage/distfiles.
 .TP
@@ -325,7 +327,9 @@ Defines if color should be disabled by default.
 Defaults to false.
 .TP
 \fBPKGDIR\fR = \fI[path]\fR
-Defines the location where created .tbz2 binary packages will be stored.
+Defines the location where created .tbz2 binary packages will be stored.  Note
+that locations under /usr/portage are not necessarily safe for data storage.
+See the \fBPORTDIR\fR documentation for more information.
 .br
 Defaults to /usr/portage/packages.
 .TP
@@ -420,18 +424,19 @@ Defaults to /var/tmp.
 This variable controls permissions for \fIWORKDIR\fR (see \fBebuild\fR(5)).
 .TP
 \fBPORTDIR\fR = \fI[path]\fR
-Defines the location of your Portage tree.
+Defines the location of the Portage tree. This is the repository for all
+profile information as well as all ebuilds. If you change this, you must update
+your /etc/make.profile symlink accordingly.
 .br
 Defaults to /usr/portage. 
 .br
 \fB***Warning***\fR
 .br
-Storing data such as distfiles and binary packages in PORTDIR can
-be potentially dangerous. The default emerge configuration defaults to this 
-behavior (which will work fine), however if you deviate from the default
-configuration by changing PKGDIR or DISTDIR, emerge \-\-sync may inadvertedly
-delete all your distfiles/binary packages. Please make sure to set
-\fBPORTAGE_EXTRA_RSYNC_OPTS\fR properly to insure the safety of files in PORTDIR.
+Data stored inside \fBPORTDIR\fR is in peril of being overwritten or deleted by
+the emerge \-\-sync command. The default value of
+\fBPORTAGE_EXTRA_RSYNC_OPTS\fR will protect the default locations of
+\fBDISTDIR\fR and \fBPKGDIR\fR, but users are warned that any other locations
+inside \fBPORTDIR\fR are not necessarily safe for data storage.
 .TP
 \fBPORTDIR_OVERLAY\fR = \fI"[path] [different\-path] [etc...]"\fR
 Defines the directories in which user made ebuilds may be stored and not