From 9ad42362509c25583e3e3f70fb161910c905a069 Mon Sep 17 00:00:00 2001
From: Peter Pentchev <roam@FreeBSD.org>
Date: Wed, 19 Feb 2003 07:25:18 +0000
Subject: [PATCH] Add a warning about always updating the ports-base
 subcollection whenever any part of the Ports Collection is updated to the
 CVSup chapter of the Handbook.

Add a similar Q&A to the 'User Applications' section of the FAQ,
with the answer referencing the warning in the Handbook.

Reviewed by:	keramida
Approved by:	ceri (mentor), keramida, Stijn Hoop <stijn@win.tue.nl>
---
 en_US.ISO8859-1/books/faq/book.sgml           | 20 +++++++++++
 .../books/handbook/mirrors/chapter.sgml       | 36 +++++++++++++++++--
 2 files changed, 54 insertions(+), 2 deletions(-)

diff --git a/en_US.ISO8859-1/books/faq/book.sgml b/en_US.ISO8859-1/books/faq/book.sgml
index dd2046fba4..95fa20e5ae 100644
--- a/en_US.ISO8859-1/books/faq/book.sgml
+++ b/en_US.ISO8859-1/books/faq/book.sgml
@@ -5178,6 +5178,26 @@ crw-rw-rw-  1 root  wheel   41,   1 Oct 15 22:14 spx</screen>
             connection.</para>
         </answer>
       </qandaentry>
+
+      <qandaentry>
+	<question id="ports-base-update">
+	  <para>I updated parts of the Ports Collection using CVSup, and
+	    now many ports fail to build with mysterious error messages!
+	    What happened?  Is the Ports Collection broken in some major
+	    way?</para>
+	</question>
+
+	<answer>
+	  <para>If you only update parts of the Ports Collection, using
+	    one of its CVSup subcollections and not the
+	    <literal>ports-all</literal> CVSup collection, you should
+	    <emphasis>always</emphasis> update the
+	    <literal>ports-base</literal> subcollection too!  The reasons
+	    are described <ulink
+	    url="../handbook/cvsup.html#CVSUP-COLLEC-PBASE-WARN">in the
+	    Handbook</ulink>.</para>
+	</answer>
+      </qandaentry>
     </qandaset>
   </chapter>
 
diff --git a/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml b/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml
index 7ada2df199..1974a58da9 100644
--- a/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml
@@ -2526,6 +2526,26 @@ doc/zh_TW.Big5</screen>
 		<listitem>
 		  <para>The FreeBSD Ports Collection.</para>
 
+		  <important id="cvsup-collec-pbase-warn">
+		    <para>If you do not want to update the whole of
+		      <literal>ports-all</literal> (the whole ports tree),
+		      but use one of the subcollections listed below,
+		      make sure that you <emphasis>always</emphasis> update
+		      the <literal>ports-base</literal> subcollection!
+		      Whenever something changes in the ports build
+		      infrastructure represented by
+		      <literal>ports-base</literal>, it is virtually certain
+		      that those changes will be used by <quote>real</quote>
+		      ports real soon.  Thus, if you only update the
+		      <quote>real</quote> ports and they use some of the new
+		      features, there is a very high chance that their build
+		      will fail with some mysterious error message.  The
+		      <emphasis>very first</emphasis> thing to do in this
+		      case is to make sure that your
+		      <literal>ports-base</literal> subcollection is up to
+		      date.</para>
+		  </important>
+
 		  <variablelist>
 		    <varlistentry>
 		      <term><literal>ports-archivers
@@ -2559,8 +2579,20 @@ doc/zh_TW.Big5</screen>
 			  release=cvs</literal></term>
 		      
 		      <listitem>
-			<para>Miscellaneous files at the top of
-			  /usr/ports.</para>
+			<para>The Ports Collection build infrastructure -
+			  various files located in the
+			  <filename>Mk/</filename> and
+			  <filename>Tools/</filename> subdirectories of
+			  <filename>/usr/ports</filename>.</para>
+
+			<note>
+			  <para>Please see the <link
+			    linkend="cvsup-collec-pbase-warn">important
+			    warning above</link>: you should
+			    <emphasis>always</emphasis> update this
+			    subcollection, whenever you update any part of
+			    the FreeBSD Ports Collection!</para>
+			</note>
 		      </listitem>
 		    </varlistentry>