docs/66775: Clarification that port names should not contain version numbers

[Peter Pentchev]

The following reply was made to PR docs/66775; it has been noted by GNATS.

From: Peter Pentchev <roam at ringlet.net>
To: Aasmund Eikli <inter at o12a.com>
Cc: bug-followup at FreeBSD.org
Subject: Re: docs/66775: Clarification that port names should not contain version numbers
Date: Mon, 9 Aug 2004 15:31:08 +0300

 On Sat, Jul 31, 2004 at 09:00:45PM +0000, Aasmund Eikli wrote:
 > The following reply was made to PR docs/66775; it has been noted by GNATS.
 > 
 > From: Aasmund Eikli <inter at o12a.com>
 > To: freebsd-gnats-submit at FreeBSD.org
 > Cc:  
 > Subject: Re: docs/66775: Clarification that port names should not contain
 >  version numbers
 > Date: Sat, 31 Jul 2004 22:52:16 +0200
 > 
 >  Doc diffs to reflect suggestions:
 >  
 >  --- article.sgml        Tue Jul 27 16:34:49 2004
 >  +++ article.sgml        Sat Jul 31 15:35:56 2004
 >  @@ -2418,7 +2418,9 @@
 >                     <step>
 >                       <para>Upgrade the copied port to the new version 
 >  (remember
 >                         to change the <makevar>PORTNAME</makevar> so there
 >  -                     are not duplicate ports with the same name).</para>
 >  +                     are not duplicate ports with the same name).
 >  +                     Alternatively, change <makevar>LATEST_LINK</makevar>
 >  +                     depending on the purpose.</para>
 >                     </step>
 
 I think that 'remmeber to change the PORTNAME' and 'change LATEST_LINK'
 clauses should be at the same level of "nesting" (parenthesized or not)
 to avoid confusion - this way, it might seem that changing LATEST_LINK
 is an alternative to upgrading the port :)  How about something like
 this instead?
 
 Index: doc/en_US.ISO8859-1/articles/committers-guide/article.sgml
 ===================================================================
 RCS file: /home/ncvs/doc/en_US.ISO8859-1/articles/committers-guide/article.sgml,v
 retrieving revision 1.207
 diff -u -r1.207 article.sgml
 --- doc/en_US.ISO8859-1/articles/committers-guide/article.sgml	8 Aug 2004 13:43:53 -0000	1.207
 +++ doc/en_US.ISO8859-1/articles/committers-guide/article.sgml	9 Aug 2004 12:21:10 -0000
 @@ -2431,9 +2431,10 @@
  
  		<procedure>
  		  <step>
 -		    <para>Upgrade the copied port to the new version (remember
 -		      to change the <makevar>PORTNAME</makevar> so there
 -		      are not duplicate ports with the same name).</para>
 +		    <para>Upgrade the copied port to the new version.  Remember
 +		      to change either the <makevar>PORTNAME</makevar> or
 +		      the <makevar>LATEST_LINK</makevar> variable so there
 +		      are not duplicate ports with the same name.</para>
  		  </step>
  
  		  <step>
 
 >  --- book.sgml   Sat Jul 31 15:40:21 2004
 >  +++ book.sgml   Sat Jul 31 15:52:11 2004
 >  @@ -1064,7 +1064,10 @@
 >               <literal>Data::Dumper</literal> module becomes
 >               <literal>p5-Data-Dumper</literal>.  If the software in question
 >               has numbers, hyphens, or underscores in its name, you may 
 >  include
 >  -           them as well (like <literal>kinput2</literal>).</para>
 >  +           them as well (like <literal>kinput2</literal>).
 >  +           Make sure that the <makevar>PORTNAME</makevar> variable and the
 >  +           <makevar>PORTVERSION</makevar> variable contains the name 
 
 ITYM 'contain' here, since both variables form the sentence subject :)
 
 >  and the
 >  +           version number of the port respectively. You should not mix 
 >  the two.</para>
 
 A minor point, but I've gathered the impression that two spaces are
 preferred before the start of a new sentence.  How about this?
 
 Index: doc/en_US.ISO8859-1/books/porters-handbook/book.sgml
 ===================================================================
 RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
 retrieving revision 1.476
 diff -u -r1.476 book.sgml
 --- doc/en_US.ISO8859-1/books/porters-handbook/book.sgml	9 Aug 2004 11:51:37 -0000	1.476
 +++ doc/en_US.ISO8859-1/books/porters-handbook/book.sgml	9 Aug 2004 12:29:31 -0000
 @@ -1071,7 +1071,11 @@
  	    <literal>Data::Dumper</literal> module becomes
  	    <literal>p5-Data-Dumper</literal>.  If the software in question
  	    has numbers, hyphens, or underscores in its name, you may include
 -	    them as well (like <literal>kinput2</literal>).</para>
 +	    them as well (like <literal>kinput2</literal>).  Make sure that
 +	    the <makevar>PORTNAME</makevar> and
 +	    <makevar>PORTVERSION</makevar> variables contain the name and
 +	    the version of the port respectively.  You should not mix the
 +	    two.</para>
  	</listitem>
  
  	<listitem>
 
 Thanks for your work on this :)
 
 G'luck,
 Peter
 
 -- 
 Peter Pentchev	roam at ringlet.net    roam at cnsys.bg    roam at FreeBSD.org
 PGP key:	http://people.FreeBSD.org/~roam/roam.key.asc
 Key fingerprint	FDBA FD79 C26F 3C51 C95E  DF9E ED18 B68D 1619 4553
 This sentence would be seven words long if it were six words shorter.