From sahil@spartan.hamla.org  Mon Aug  9 23:17:28 2010
Return-Path: <sahil@spartan.hamla.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 48740106566B;
	Mon,  9 Aug 2010 23:17:28 +0000 (UTC)
	(envelope-from sahil@spartan.hamla.org)
Received: from spartan.hamla.org (spartan.hamla.org [206.251.255.30])
	by mx1.freebsd.org (Postfix) with ESMTP id 2A59E8FC15;
	Mon,  9 Aug 2010 23:17:27 +0000 (UTC)
Received: by spartan.hamla.org (Postfix, from userid 1001)
	id BC8FA17153; Mon,  9 Aug 2010 19:17:27 -0400 (EDT)
Message-Id: <20100809231727.BC8FA17153@spartan.hamla.org>
Date: Mon,  9 Aug 2010 19:17:27 -0400 (EDT)
From: Sahil Tandon <sahil@FreeBSD.org>
Reply-To: Sahil Tandon <sahil@FreeBSD.org>
To: FreeBSD-gnats-submit@freebsd.org
Cc: doc@FreeBSD.org, danfe@FreeBSD.org 
Subject: [PATCH] grammar/english suggestions for RUN_DEPENDS section of Porter's Handbook 
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         149480
>Category:       docs
>Synopsis:       [PATCH] grammar/english suggestions for RUN_DEPENDS section of Porter's Handbook
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    pgj
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Mon Aug 09 23:20:03 UTC 2010
>Closed-Date:    Wed Aug 11 19:54:08 UTC 2010
>Last-Modified:  Sat Aug 14 21:30:01 UTC 2010
>Originator:     Sahil Tandon
>Release:        FreeBSD 9.0-CURRENT i386
>Organization:
>Environment:

	
>Description:
In the patch below, I suggest some grammar/english adjustments to the section on RUN_DEPENDS.
I have copied danfe@ on this report because he introduced this (very important!) information 
into the Porter's Handbook, and I do not want to step on any toes or imply that my english is 
superior.  I simply want to increase clarity, and hope that you will review my patch + merge 
the parts that you consider useful.
>How-To-Repeat:
	
>Fix:

	



--- porters-handbook.diff begins here ---
? porters-handbook.diff
Index: 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.1070
diff -u -r1.1070 book.sgml
--- en_US.ISO8859-1/books/porters-handbook/book.sgml	8 Aug 2010 13:54:36 -0000	1.1070
+++ en_US.ISO8859-1/books/porters-handbook/book.sgml	9 Aug 2010 23:07:34 -0000
@@ -3283,33 +3283,28 @@
 	    part can be omitted if it is the same as
 	    <makevar>DEPENDS_TARGET</makevar>.</para>
 
-	  <para>Quite common situation is when
+	  <para>A quite common situation is when
 	    <makevar>RUN_DEPENDS</makevar> is literally the same as
 	    <makevar>BUILD_DEPENDS</makevar>, especially if ported
 	    software is written in a scripted language or if it requires
-	    the same run-time environment used to build it.  In this
-	    case, it is very tempting, and indeed natural to directly
-	    assign one to another:</para>
+	    the same build and run-time environment.  In this
+	    case, it is both tempting and intuitive to directly
+	    assign one to the other:</para>
 
 	  <programlisting>RUN_DEPENDS= ${BUILD_DEPENDS}</programlisting>
 
-	  <para>However, doing so can and often will result in
-	    run-time dependencies be polluted by superfluous entries, not
-	    present in original port's <makevar>BUILD_DEPENDS</makevar>.
-	    It happens due to the fact that &man.make.1 is being lazy
-	    when it evaluates assignments like these.  Most probably
-	    additional dependencies will be pulled by
-	    <filename>ports/Mk/bsd.*.mk</filename> when processing
-	    <makevar>USE_<replaceable>*</replaceable></makevar>
-	    variables, which most ports contain.  For example, such
-	    direct assignment along with
-	    <literal>USE_GMAKE=yes</literal> will bring
-	    <application>gmake</application> into
-	    <makevar>RUN_DEPENDS</makevar>, despite that it was not
-	    included explicitly in <makevar>BUILD_DEPENDS</makevar>.  To
-	    prevent this from happening, immediate expansion assignment
-	    should be used, i.e. expand the value before assigning it
-	    to the variable:</para>
+	  <para>However, such assignment can pollute run-time dependencies
+	  with entries not defined in the port's original <makevar>BUILD_DEPENDS</makevar>.
+	  This happens because of &man.make.1;'s lazy evaluation of variable
+	  assignment.  Consider a <filename>Makefile</filename> with 
+	  <makevar>USE_<replaceable>*</replaceable></makevar> variables, which
+	  are processed by <filename>ports/Mk/bsd.*.mk</filename> to augment
+	  initial build dependencies.  For example, <literal>USE_GMAKE=yes</literal>
+	  adds <filename role="package">devel/gmake</filename> to
+	  <makevar>BUILD_DEPENDS</makevar>. To prevent such additional dependencies
+	  from polluting <makevar>RUN_DEPENDS</makevar>, take care to assign
+	  with expansion, i.e. expand the value before assigning it to the 
+	  variable:</para>
 
 	    <programlisting>RUN_DEPENDS:=  ${BUILD_DEPENDS}</programlisting>
 	</sect2>
--- porters-handbook.diff ends here ---

>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->pgj 
Responsible-Changed-By: pgj 
Responsible-Changed-When: Wed Aug 11 19:20:23 UTC 2010 
Responsible-Changed-Why:  
It is my stuff. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=149480 

From: Gabor PALI <pgj@FreeBSD.org>
To: bug-followup@FreeBSD.org, sahil@FreeBSD.org, 
	Alexey Dokuchaev <danfe@freebsd.org>
Cc:  
Subject: Re: docs/149480: [PATCH] grammar/english suggestions for RUN_DEPENDS 
	section of Porter's Handbook
Date: Wed, 11 Aug 2010 21:26:07 +0200

 Hi Sahil,
 
 I was the one who received and refined Alexey's patch a bit, so many
 of your fixes touch my changes to the original one.  Well, sorry for
 my poor English, it seems it could not learn that language in almost
 20 years... :P
 
 
 :g

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/149480: commit references a PR
Date: Wed, 11 Aug 2010 19:42:40 +0000 (UTC)

 pgj         2010-08-11 19:37:15 UTC
 
   FreeBSD doc repository
 
   Modified files:
     en_US.ISO8859-1/books/porters-handbook book.sgml 
   Log:
   - Improve text on RUN_DEPENDS
   
   PR:             docs/149480
   Submitted by:   sahil
   
   Revision  Changes    Path
   1.1071    +16 -21    doc/en_US.ISO8859-1/books/porters-handbook/book.sgml
 _______________________________________________
 cvs-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/cvs-all
 To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
 
State-Changed-From-To: open->closed 
State-Changed-By: pgj 
State-Changed-When: Wed Aug 11 19:53:49 UTC 2010 
State-Changed-Why:  
Committed.  Thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=149480 

From: Alexey Dokuchaev <danfe@FreeBSD.org>
To: Gabor PALI <pgj@FreeBSD.org>
Cc: bug-followup@FreeBSD.org, sahil@FreeBSD.org
Subject: Re: docs/149480: [PATCH] grammar/english suggestions for RUN_DEPENDS section of Porter's Handbook
Date: Sat, 14 Aug 2010 21:20:37 +0000

 On Wed, Aug 11, 2010 at 09:26:07PM +0200, Gabor PALI wrote:
 > Hi Sahil,
 > 
 > I was the one who received and refined Alexey's patch a bit, so many
 > of your fixes touch my changes to the original one.  Well, sorry for
 > my poor English, it seems it could not learn that language in almost
 > 20 years... :P
 
 I also do not have strong opinion on proposed changes; I'm also not a
 native speaker and I understand that my text is probably overly
 complicated; but due to its technical nature it's hard to explain it "in
 plain words".  So I leave it to others' judgment.  After all, my sole
 concern is that people should really stop making that mistake, that's
 all.  If my wording can be improved to be more clear to porters, I do
 not object.
 
 ./danfe
>Unformatted:
