Add a warning regarding mixing ports(7) and pkg(8) to install software

I think it's something that has been missing from the handbook for a long
time.

Unfortunately, this patch does not explain all the subtleties of the ports
framework (like, e.g., that ports create packages during the build process
which are then installed via pkg). We should probably hint the reader about
it somewhere, but that's something for another patch. What's important here
is to warn new users about problems they might encounter.

Also, add some examples of working with quarterly with Subversion.

PR:		251195
Submitted by:	Fred <fjs.usa01 gmail.com>

1 files changed, 33 insertions, 1 deletions

diff --git a/en_US.ISO8859-1/books/handbook/ports/chapter.xml b/en_US.ISO8859-1/books/handbook/ports/chapter.xml
index 110d47f3b6..90a753b439 100644
--- a/en_US.ISO8859-1/books/handbook/ports/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/ports/chapter.xml
@@ -837,6 +837,24 @@ security/sudo</screen>
     <para>By default, the Ports Collection itself is stored as a
       subdirectory of <filename>/usr/ports</filename>.</para>
 
+    <warning>
+      <para>Before installing and using the Ports Collection, please
+	be aware that it is generally ill-advised to use the
+	Ports Collection in conjunction with the binary packages
+	provided via <application>pkg</application> to install
+	software.  <application>pkg</application>, by default,
+	tracks quarterly branch-releases of the ports
+	tree and not HEAD. Dependencies could be different for a port
+	in HEAD compared to its counterpart in a quarterly branch
+	release and this could result in conflicts between
+	dependencies installed by <application>pkg</application>
+	and those from the Ports Collection.
+	If the Ports Collection and <application>pkg</application>
+	must be used in conjunction, then be sure that your
+	Ports Collection and <application>pkg</application> are
+	on the same branch release of the ports tree.</para>
+    </warning>
+
     <para>Before an application can be compiled using a port, the
       Ports Collection must first be installed.  If it was not
       installed during the installation of &os;, use one of the
@@ -917,18 +935,32 @@ security/sudo</screen>
       </step>
 
       <step>
-	<para>Check out a copy of the ports tree:</para>
+	<para>Check out a copy of the HEAD branch of the ports
+	  tree:</para>
 
 	<screen>&prompt.root; <userinput>svn checkout https://svn.FreeBSD.org/ports/head /usr/ports</userinput></screen>
       </step>
 
       <step>
+	<para>Or, check out a copy of a quarterly branch:</para>
+
+	<screen>&prompt.root; <userinput>svn checkout https://svn.FreeBSD.org/ports/branches/2020Q3 /usr/ports</userinput></screen>
+      </step>
+
+      <step>
 	<para>As needed, update <filename>/usr/ports</filename> after
 	  the initial <application>Subversion</application>
 	  checkout:</para>
 
 	<screen>&prompt.root; <userinput>svn update /usr/ports</userinput></screen>
       </step>
+
+      <step>
+	<para>As needed, switch <filename>/usr/ports</filename> to a
+	  different quarterly branch:</para>
+
+	<screen>&prompt.root; <userinput>svn switch http://svn.freebsd.org/ports/branches/2020Q4/ /usr/ports</userinput></screen>
+      </step>
     </procedure>
 
     <para>The Ports Collection contains directories