docs/149480: [PATCH] grammar/english suggestions for RUN_DEPENDS section of Porter's Handbook

[Sahil Tandon]

>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:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Mon Aug 09 23:20:03 UTC 2010
>Closed-Date:
>Last-Modified:
>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:
>Unformatted: