Describe and recommend the use of the LATEST_LINK variable in

the Committer's Guide ports repo-copy section and in the package naming
section of the Porter's Handbook.  In the end, I wrote something that
turned out quite a bit different and somewhat more long-winded than
the suggestions in the PR, but LATEST_LINK was not documented anywhere
until now, so there :)

PR:		66775
Submitted by:	eik

en_US.ISO8859-1/articles/committers-guide/article.sgml

@@ -731,11 +731,11 @@ alias scvs cvs -d <replaceable>user</replaceable>@ncvs.FreeBSD.org:/home/ncvs</p
 	</itemizedlist>
 
 	<para>You will almost certainly get a conflict because
-	  of the <literal>$Id: article.sgml,v 1.260 2007-04-08 17:45:24 blackend Exp $</literal> (or in FreeBSD's case,
+	  of the <literal>$Id: article.sgml,v 1.261 2007-04-25 13:13:22 roam Exp $</literal> (or in FreeBSD's case,
 	  <literal>$<!-- stop expansion -->FreeBSD<!-- stop expansion -->$</literal>)
 	  lines, so you will have to edit the file to resolve the conflict
-	  (remove the marker lines and the second <literal>$Id: article.sgml,v 1.260 2007-04-08 17:45:24 blackend Exp $</literal> line,
+	  (remove the marker lines and the second <literal>$Id: article.sgml,v 1.261 2007-04-25 13:13:22 roam Exp $</literal> line,
-	  leaving the original <literal>$Id: article.sgml,v 1.260 2007-04-08 17:45:24 blackend Exp $</literal> line intact).</para>
+	  leaving the original <literal>$Id: article.sgml,v 1.261 2007-04-25 13:13:22 roam Exp $</literal> line intact).</para>
       </listitem>
 
       <listitem>
@@ -2547,9 +2547,21 @@ docs:Documentation Bug:freebsd-doc:</programlisting>
 
 		<procedure>
 		  <step>
-		    <para>Upgrade the copied port to the new version (remember
+		    <para>Upgrade the copied port to the new version.
-		      to change the <makevar>PORTNAME</makevar> so there
+		      Remember to change the <makevar>LATEST_LINK</makevar>
-		      are not duplicate ports with the same name).</para>
+		      so there are no duplicate ports with the same name.
+		      In some rare cases it may be necessary to change the
+		      <makevar>PORTNAME</makevar> instead of
+		      <makevar>LATEST_LINK</makevar>, but this should only
+		      be done when it is really needed &mdash; e.g. using
+		      an existing port as the base for a very similar
+		      program with a different name, or upgrading a port to
+		      a new upstream version which actually changes the
+		      distribution name, like the transition from
+		      <filename>textproc/libxml</filename> to
+		      <filename>textproc/libxml2</filename>.  In most cases,
+		      changing <makevar>LATEST_LINK</makevar> should
+		      suffice.</para>
 		  </step>
 
 		  <step>

en_US.ISO8859-1/books/porters-handbook/book.sgml

@@ -1043,6 +1043,28 @@ PORTEPOCH=      1</programlisting>
 	  them part of <makevar>PORTNAME</makevar>.</para>
       </sect2>
 
+      <sect2>
+	<title><makevar>LATEST_LINK</makevar></title>
+
+	<para>In some cases, several versions of a program may be present in
+	  the ports collection at the same time.  Both the index build and
+	  the package build system need to be able to see them as different,
+	  independent ports, although they may all have the same
+	  <makevar>PORTNAME</makevar>, <makevar>PKGNAMEPREFIX</makevar>, and
+	  even <makevar>PKGNAMESUFFIX</makevar>.  In those cases, the
+	  optional <makevar>LATEST_LINK</makevar> variable should be set to
+	  a different value for all ports except the <quote>main</quote>
+	  one &mdash; see the <filename>editors/vim5</filename> and
+	  <filename>editors/vim</filename> ports, and the
+	  <filename>www/apache*</filename> family for examples of its use.
+	  Note that how to choose a <quote>main</quote> version &mdash;
+	  <quote>most popular</quote>, <quote>best supported</quote>,
+	  <quote>least patched</quote>, and so on &mdash; is outside the
+	  scope of this handbook's recommendations; we only tell you how to
+	  specify the other ports' versions after you have picked a
+	  <quote>main</quote> one.</para>
+      </sect2>
+
     <sect2 id="porting-pkgname">
       <title>Package Naming Conventions</title>
 
@@ -1079,17 +1101,33 @@ PORTEPOCH=      1</programlisting>
 	</listitem>
 
 	<listitem>
-	  <para>The first letter of <filename>name</filename> part
+	  <para>The first letter of the <filename>name</filename> part
-	    should be lowercase.  (The rest of the name can contain
+	    should be lowercase.  (The rest of the name may contain
 	    capital letters, so use your own discretion when you are
 	    converting a software name that has some capital letters in it.)
-	    There is a tradition of naming <literal>perl 5</literal> modules by
+	    There is a tradition of naming <literal>Perl 5</literal> modules by
 	    prepending <literal>p5-</literal> and converting the double-colon
 	    separator to a hyphen; for example, the
 	    <literal>Data::Dumper</literal> module becomes
-	    <literal>p5-Data-Dumper</literal>.  If the software in question
+	    <literal>p5-Data-Dumper</literal>.</para>
-	    has numbers, hyphens, or underscores in its name, you may include
+	</listitem>
-	    them as well (like <literal>kinput2</literal>).</para>
+	
+	<listitem>
+	  <para>Make sure that the port's name and version are clearly
+	    separated and placed into the <makevar>PORTNAME</makevar> and
+	    <makevar>PORTVERSION</makevar> variables.  The only reason for
+	    <makevar>PORTNAME</makevar> to contain a version part is if
+	    the upstream distribution is really named that way, as in
+	    the <filename>textproc/libxml2</filename> or
+	    <filename>japanese/kinput2-freewnn</filename> ports.  Otherwise,
+	    the <makevar>PORTNAME</makevar> should not contain any
+	    version-specific information.  It is quite normal for several
+	    ports to have the same <makevar>PORTNAME</makevar>, as the
+	    <filename>www/apache*</filename> ports do; in that case,
+	    different versions (and different index entries) are
+	    distinguished by the <makevar>PKGNAMEPREFIX</makevar>,
+	    <makevar>PKGNAMESUFFIX</makevar>, and
+	    <makevar>LATEST_LINK</makevar> values.</para>
 	</listitem>
 
 	<listitem>